.TH TERM_CLIENTS 1
.SH NAME
trsh, tupload, tdownload, tredir, tudpredir, txconn, tmon, tshutdown, trdate, 
trdated \- clients to term
.SH SYNOPSIS
.IR trsh 
[\-S\ on|off] [\-p\ <number>] [\-t\ <server>] [\-c] [\-r] [\-v]
[\-s] [<command>]
.PP
.IR tupload 
[\-S\ on|off] [\-p\ <number>] [\-t\ <server>] [\-c] [\-r] [\-v]
[\-f] [\-u] [\-q] <local\ file> [\-\-as\ <remote\ file>]
[<local\ file> [\-\-as\ <remote\ file>] ...] [<remote\ directory>]
.PP
.IR tdownload 
[\-S\ on|off] [\-p\ <number>] [\-t\ <server>] [\-c] [\-r] [\-v]
[\-f] [\-u] [\-q] <local\ file> [\-\-as\ <local\ file>]
[<local\ file> [\-\-as\ <local\ file>] ...] [<local directory>]
.PP
.IR tredir 
[\-S\ on|off] [\-p\ <number>] [\-t\ <server>] [\-c] [\-r] [\-v]
<local\ port> [<remote\ host>:]<remote\ port> 
[<local\ port> [<remote\ host>:]<remote\ port> ...]
.PP
.IR tudpredir 
[\-S\ on|off] [\-p\ <number>] [\-t\ <server>] [\-c] [\-r] [\-v]
<local\ port> [<remote\ host>:]<remote\ port> 
[<local\ port> [<remote\ host>:]<remote\ port> ...]
.PP
.IR txconn 
[\-S\ on|off] [\-p\ <number>] [\-t\ <server>] [\-c] [\-r] [\-v]
[<local display>]
.PP
.IR tmon
[\-S\ on|off] [\-p\ <number>] [\-t\ <server>] [\-c] [\-r] [\-v]
.PP
.IR tshutdown
[\-S\ on|off] [\-p\ <number>] [\-t\ <server>] [\-c] [\-r] [\-v]
[\-h] [\-n]
.PP
.IR trdate
[\-S\ on|off] [\-p\ <number>] [\-t\ <server>] [\-c] [\-r] [\-v]
.PP
.IR trdated
[\-S\ on|off] [\-p\ <number>] [\-t\ <server>] [\-c] [\-r] [\-v]
[\-d\ <delay>]
.SH DESCRIPTION
These clients connect to a local 
.IR term (1)
daemon and initiate a communication
link with the remote daemon and remote processes.
.IR Trsh
runs an interactive shell or commands on the remote system, 
.IR tupload
transfers files from the local system to the remote, and
.IR tdownload
does the reverse.
.IR tredir
and
.IR tupdredir
redirect connections from ports on the local system to ports on a
remote system (TCP or UDP respectively),
.IR txconn 
redirects X server connections from the local system to the remote,
and
.IR tmon
prints summary information about a 
.IR term 
link.
.PP
As far as the clients are concerned,
the link established by
.IR term (1)
is completely symmetric; the clients don't know
which system is your physically local system (the system you're typing at) and
which is physically remote.
From a client's point of view, the local system is the one on which
the client is executing.
The remote system is the other system, the one on which the client is
not executing.
.SH USAGE
.TP
.IR "trsh \ \ \ "
With no arguments,
.IR trsh 
is similar to 
.IR rlogin (1).
An interactive shell is started on the remote system.  
Terminal features such as character echoing, line editing, and window
resizing are handled by a tty on the remote system.
If a \fIcommand\fR is given, it executes on the remote system instead of
the default shell.
Specifying \fIcommand\fR without the \-s option is primarily useful
for starting a non-default shell remotely.
.TP
.IR 
There is a single
.IR trsh
specific option:
.IR 
.RS
.TP
.BR \-s
Use a simple connection.
This makes 
.IR trsh
behave more like
.IR rsh (1).
The specified \fIcommand\fR is executed by a shell on the remote
system.
Like
.IR rsh (1),
quoted shell metacharacters are interpreted remotely, so filename
redirection, multiple commands, or pipes can be used remotely.
If no \fIcommand\fR is given, the \-s option is ignored.
.PP
The \-s option should almost always be used 
when a \fIcommand\fR is provided.
In particular, it should be used if 
.IR trsh
is part of a pipeline.
The only exception to this rule is when
remote terminal features are needed.
.RE
.TP
.IR 
.IR Trsh
differs from 
.IR rlogin (1)
and
.IR rsh (1)
in a couple of significant ways.  First, the stdout and stderr of the
remote shell or command are both directed to the local stdout.
Second, the connection is broken as soon as a local end-of-file occurs.
This means that any output generated by the remote system after EOF is
lost.
For example,
.TP
.IR 
.IR 
\ \ \ trsh -s wc < /etc/passwd
.TP
.IR 
runs the remote 
.IR wc (1)
command on the contents of the local /etc/passwd, but will not produce any output.
.TP
.IR tredir
.IR Tredir
accept pairs of port numbers, the first of each being the local port
number to redirect, and the second the remote port to redirect into.  
They will also accept
a hostname with each of the second port numbers.  For example, 
.TP
.IR 
\ \ \ tredir\ 119\ my.nntp.host:119
.TP
.IR 
can be run on the non-internet side of the link.
Then, any local program  
that connects to port 119 (like an NNTP newsreader), will be connected to
port 119 on my.nntp.host.
.IR Tredir
becomes a background daemon once it has successfully established the
local port. More than one port can be redirected at once with a single
.IR tredir.
For example,
.TP
.IR 
\ \ \ tredir\ 119\ my.nntp.host:119\ 4000\ remote.home:23
.TP
.IR 
would redirect ports 119 and 4000, 119 to the nntp port on
my.nntp.host, and port 4000 to the login port on remote.host.
.IR Tredir
handles redirecting TCP ports.
.TP
.IR tudpredir
.IR Tudpredir
works similarly to 
.IR tredir
except a UDP port is redirected instead of a TCP port.  One important
difference is
.IR tudpredir
commands must be placed in the background manually.  I've yet to actually
find a case where this is usefull.
.TP 
.IR tupload
.IR Tupload
takes a list of local file names to upload. If there is more than one name, 
then the last name is checked to see if it matches a remote directory.
If it does match a remote directory, the files are uploaded
to this directory.  If a previous upload was aborted without modifying
either the local or remote file, then the upload will be resumed.
.IR 
Tupload specific options are:
.RS
.TP
.BR \-f
Tells 
.IR upload 
to force the upload by overwriting the file if it can't resume.
.TP
.BR \-u
Unlink the local file after a successful upload.
.TP
.BR \-v
Verbose mode. Will write out the number of bytes transferred, the name
of the remote file, and the CPS rate. Two 'v's will produce more
output; note, however, that the "current CPS" values shown will be less 
accurate at the beginning and end of the upload, since tupload has no 
direct knowledge about how fast term is sending data.
.TP
.BR \-q
Quiet mode. Tupload will not write out any messages.
.TP
.BR \-\-as\ <remote\ file>
Any of the local \fIfile\fR names may be followed by the \-\-as
<remote\ file> option to specify a new name for the remote copy of the
file. 
By default the remote file will have the same name as the local file.
.RE
.TP
.IR tdownload
.IR Tdownload
takes the same arguments as 
.IR tupload,
but uses them to transfer the file(s) in the opposite direction.
If the last name is a local directory, it is used to put all the
files in.  One or more local files may be specified "-\-as -" and the 
file's data will be sent to stdout.
.TP
.IR txconn
.IR Txconn
establishes an X screen port on the system it is run on.
Connections to that screen will be redirected to the X server on the
other system.
If your DISPLAY environment variable is set,
.IR txconn
will try to use the screen number given by DISPLAY.
.IR Txconn
prints the number of the screen it actually establishes in a format
suitable for re-setting your DISPLAY variable.
The recommended method of starting
.IR txconn
and setting your DISPLAY variable at the same time is to run
.TP
.IR 
.TP
.IR 
\ \ \ setenv \ DISPLAY \ `hostname`:0
.TP
.IR 
\ \ \ setenv \ DISPLAY \ `txconn`
.TP
.IR 
from csh and related shells, or
.TP
.IR 
.IR 
\ \ \ export \ DISPLAY \ `hostname`:0
.TP
.IR 
\ \ \ export \ DISPLAY=`txconn`
.TP
.IR 
from sh and related shells.  Later trsh calls will have this preset.
.IR Txconn
becomes a background daemon
once it has successfully established the port.
.TP
.IR tmon
.IR Tmon
periodically queries the 
.IR term
daemon for information about the number of clients and the
data flow-rate of the channels.
It updates its output on the terminal it is running in.
.TP
.IR tshutdown
.IR Tshutdown
closes all
.IR term
clients and stops both the local and remote
.IR term
servers.  Sometimes a crashed client will keep this from working.
In that case you can blast the
.IR term
servers by typing Control-C to kill the local server, then
echoing 00000 to your modem device multiple times to kill the remote server.

.IR Tshutdown 
will take a '-h' argument to request the local term perform a hangup
on exit, or a '-n' argument to request no hangup.  The default is set
by the "hangup_on_exit" option in the termrc file.  Tshutdown will only
work if the modem accepts +++AT commands.
.TP
.IR trdate/trdated
.IR Trdate
is a time setting utility. It will read the time on the remote
system and set the local clock to the remote time. It attempts to take into
account the delay in getting the data across the link by adding half the
time taken to get the info onto the time it receives. 
.TP
.IR 
When run with a 'd' as the last character of the name, trdated will set the
time every 5 minutes. It can thus be started in
.IR rc.local
and run as a daemon. If it does not find a term connection it will ignore the error silently
so it can run when there is no term connection.
.TP
.IR 
.IR trdate/trdated
may only be used by root.
.RS
.TP
.BR \-v
Verbose mode. Tmon will output details as it goes.
.TP
.BR \-d\ delay
Change delay. Only valid in daemon mode. Sets the delay between time
queries to
.IR delay
seconds. Default is 300 seconds (5 minutes).
.RE


.SH GLOBAL OPTIONS
The following options are accepted by all 
.IR term 
clients
.TP
.BR \-S \ on
Specifies to connection is to a shared server.  (Default if set user or
group id.)
.TP
.BR \-S \ off
Specifies to connection is to a private server.
.TP
.BR \-c
Specifies a compressing link.  All clients 
use compression by default.
.TP
.BR \-p \ <number>
Specifies priority for this link.  A client with higher priority will be able
to send its data faster than lower priority clients.  This may be changed in 
future releases.  
The priority of
.IR trsh
defaults to 10 and
.IR tupload/tdownload
default to -5.  All other clients default to zero.  Valid numbers are between
-20 and 20.
.BR \-r
Specifies a raw link (no compression).
.TP
.BR \-t \ <server>
Specifies which term daemon socket to connect to (~/.term/socket<server>).
This is useful if you have specific socket names for connections to
specific remote hosts, or if
you have multiple terms using different serial connections.
.TP
.BR \-v
Verbose.  See each client's listing for what information this will print.
.TP
.BR \-vv
Very verbose.  See each client's listing for what information this will print.
.TP
.PP
.SH EXAMPLES
Some simple, contrived examples:
.PP
.IR 
\ \ \ trsh
.PP
This establishes an interactive shell on the remote machine.  The
connection is maintained until you exit the remote shell.
.PP
.IR 
\ \ \ trsh -s who
.PP
prints out a list of current users of the remote machine.
.PP
.IR 
\ \ \ ls -li | awk '{print $1, $5}' | trsh -s plot
.PP
will generate a scatter plot of file size vs inode.
Most likely this would be run on the physically remote system to
produce local graphical output about the files on the remote system.
.PP
.IR 
\ \ \ tupload -vv -r lin-0.99.3.tar.Z --as lin993.tar.Z /new
.PP
This will upload the local file 'lin-0.99.3.tar.Z' to the remote system
with the name '/new/lin993.tar.Z'. It will resume an upload if
there is an existing /new/lin993.tar.Z, and will write out the CPS
and bytes transferred every so often. It will not do compression on the way. 
.PP
.IR 
\ \ \ tredir 6667 munagin.ee.mu.oz.au:6500 9017 17
.PP
This will map any connections to port 6667 on your local host to port
6500 on munagin.ee.mu.oz.au and any connections on your local host to port
9017 to port 17 on the remote machine.
So if you do 'telnet 0 6667' locally, you will be
connected to port 6500 on munagin, and if you do 'telnet 0 9017', you will
be connected to port 17 on the remote machine.
.PP 
Let's say the physically remote machine, earlobe.mit.edu, is on
the internet.
You can establish a port on earlobe which will allow anyone on the
internet to telnet to your physically local, non-internet machine.
On the local machine you could type
.PP
.IR 
\ \ \ trsh -s tredir 4000 23
.PP
Alternatively, if you already have an interactive shell on the remote
machine you could just run the tredir command from that shell.
In either case, once the tredir daemon is running, users typing
.PP
.IR 
\ \ \ telnet earlobe.mit.edu 4000
.PP
from any internet host will get a login prompt from your physically
local machine.
.SH ENVIRONMENT VARIABLES
.TP
.BR SHELL
Default shell for 
.IR trsh.
.TP 
.BR DISPLAY
Used by 
.IR txconn 
to determine which X server port to use.
.TP
.BR TERMDIR
Where to find the .term directory in private mode.  This directory will
contain the socket used by all term clients.  The default is HOME.
.TP
.BR TERMSHARE
Where term runs from in shared mode.  The default is /usr/local/lib/term.
.TP
.PD 0

.BR TERMMODE
What mode term will attempt to use.
.IP "" 16
0 == private
.IP "" 16
1 == system shared
.IP "" 16
2 == user shared
.PD
.TP
.BR TERMSERVER
This should specify the <server> name, if you used one.
.SH BUGS
If the remote command for 'trsh -s <command>' doesn't consume its
input fast enough, the channel can lose data.
.IR Trsh 
breaks the channel as soon as the local EOF is received, thus losing
any final output from the remote process.
.IR Tmon
gives bogus output on some machines (e.g. NeXT).
.SH SEE ALSO
.IR term (1),
.IR termrc (1),
.IR term_clients (1),
.IR term_setup (1),
.IR termtest (1),
.IR linecheck (1).
.SH AUTHOR
Michael O'Reilly, michael@iinet.com.au, original author
.br
Bill C. Riemers, bcr@physics.purdue.edu, current developer