TERM(1)

NAME
term - server for multiple communication channels on a serial link

SYNOPSIS
term [-s speed] [-n on|off] [-c on|off] [-S on|off] [-r] [-f arg] [-w arg] [-t arg] [-o] [-a] [-d lev] [-l file] [-v file] [-1] [-q] <server>

DESCRIPTION
Term and its clients support multiple, compressed, and error-corrected communication channels over a regular serial link, typically a modem connection. The clients can set up channels to run an interactive shell on the other system similar to rlogin(1), to execute commands on the other system similar to rsh(1), to transfer files in either direction, to redirect X server connections from one system to the other, or to redirect any network port connection from one system to a port on the other. Any of these can occur simultaneously, and in either direction.

To support these multiple clients, a term daemon on each system takes control of the device connected to the modem. So you must compile term and the clients on both systems. Source is available by anonymous ftp temporarily from physics.purdue.edu:/pub/bcr/term/term???.tar.gz. Normally source is available by anonymous ftp from tartarus.uwa.edu.au:/pub/oreillym/term/term???.tar.z and nic.funet.fi:/pub/OS/Linux/BETA/term???.tar.z but not at the time of this patch.

DEFINITION
Due to the fact that anything term and its clients can initiate from one end of the link they will just as happily initiate from the other, the following frame of reference will be used throughout this documentation. The remote system refers to the system at the other end of the modem link, and the local host refers to the machine you are typing on, typically the user's home system.

USAGE
Term is run as a daemon which accepts connections from its clients and establishes channels for each client's data. Term must be run on both ends. On the remote system, execute something like

term -r -n off

Then, on the local system, you can exit your comm program and type

term -v /dev/tty?? [-n off] &

where tty?? is the device name for your modem or serial port. You may be able to start the local term from within your comm program, e.g. for xcomm type

control-A x "$ term"

Once the term daemons are running at both ends they handle the transmission of data over the link. These clients connect to a local term daemon which establishes a communication channel with the remote daemon and/or remote processes. The clients are discussed in detail in term_clients(1). Briefly, trsh runs an interactive shell or commands on the remote system, tupload transfers files from the local system to the remote, tredir redirects connections from a port on the local system to a port on the remote system, txconn redirects X server connections from the local system to the remote, and tmon monitors client statistics.

OPTIONS
Term accepts a number of command-line options which override settings established by the termrc file (see below):

-S off|on
    Turns off|on share mode. This option is on by default if the program is set user or group id.

-c off|on
    Turns off compression. Still does error correction. Consider this option if you have hardware compression (ie. v.32.bis) or are transferring compressed files. The default is to have compression on (except for clients which disable it by default for themselves, such as tupload ).

-n on|off
    Turns on line noise echoing. Talk requests, writes, and biffs to the login which is running term will then appear. This is a useful option to use on the local end (the end you are sitting at). Without this, you will never see any talk requests directed to your remote login. Default is off.

-f off|<number>
    Makes term send XON at specified interval. Zero is no flow control emulation, 10 is a single XON every 10 characters. The default is zero. 100 is a reasonable value.

-s off|<number>
    Specifies a maximum number of bits per second (baudrate) term will try to send over the serial link. Term will avoid sending characters at a higher data rate than this. This overrides the BAUDRATE environment variable. The default is to use the speed of your computer's serial port, but be warned that this may be too high if your modem runs at a lower rate over the phone line. The baudrate option is intended for systems that buffer output to the modem. During setup and tuning it is better to have <number> be too small rather than too large. For high speed links (> 38400), making it unlimited is probably advantageous. This is achieved by using the value of off. term will then rely solely on your kernel to do flow control.

-w <number>
    Sets the transmission window size; that is, the number of unacknowledged packets that term may send. Lower numbers may lead to better interactive response times. Higher numbers may lead to better throughput, particularly if the serial link latencies are large and the timeout length is set large. Higher numbers can also improve efficiency on noisy lines. The default is determined as a function of your baudrate.

-t <number>
    Timeout length in 20ths of a second. This specifies how long term will wait for an acknowledgement before retransmitting a packet. Default is 70 (i.e. 3.5 seconds), maximum 1000. Decreasing both window size and timeouts can lead to less latencies for interactive work, and faster noise recovery at the expense of total throughput speed.

-r  Use this on the remote term so that client numbers won't clash.

-a  Turns on seven bit line mode. Use only if you have a seven bit line, as determined by linecheck.

-l <filename>
    Output all log/noise/debugging to the file <filename>

-v <filename>
    Set the modem device to be <filename>. Appropriate usage is something like "-v/dev/ttys1"

-1  Use stdout instead of stdin as the modem port. This is ignored if a -v is also present.

-d off|<number>
    This sets the debugging level. This is useful for monitoring packet timeout conditions and other things. Level 64 is suggested, 478 is verbose. Read debug.h and the other source files to find out what the levels do. If you are not familiar with packet protocols and pouring through source code, then this option is unlikely to help you.

-o  Turns on packet send forcing. Re-transmits oldest packet if nothing to send. Default off. Of dubious utility. Not properly debugged. Very bad idea if speed is unlimited.

-q  Make term quieter. Multiple `-q' options make term more quiet.

<server>
    Use this to tell term to use a unique socket name. Then for term clients to work, you will need setenv TERMSERVER <server> or exportTERMSERVER=<server>. This option is normally used only if your machine has multiple modems so that term users can specify which term server they wish to use.

INITIALIZATION FILE
The file termrc in the .term directory in your home directory may be used to specify default settings for a user. These settings are overruled by values set in the command line, but several options can only be set in this file. Blank lines and lines beginning with '#' are comments; other lines must begin with one of the options. Legal options are:

escape <number>
    This is one of the most important options for term. Usage is either 'escape <some decimal number>' or 'escape <start of range>-<end of range>'. This tells term to never transmit the character or characters in the range. This is essential for serial lines that aren't fully transparent. For example, lines that use software flow control will want to do 'escape 17' and 'escape 19'. If you only have a seven-bit link, DO NOT use 'escape 128-255', see the termrc 'sevenbit' option below. See also the linecheck program, and term_setup(1).

ignore <number>
    This tells term to silently strip this character if it is received over the serial link. Its use should correspond to 'escape' options used by the term on the other system. E.g. if you use 'escape 126' on one end, you should use 'ignore 126' on the other.

compress on|off
    Turns the default compression mode on or off. The default is 'compress on'. With this on, all data will be compressed by term before sending over the serial line, and then un-compressed at the other end. If you are sending already compressed data, it is recommended that you turn compression off. Similarly, if your modem already does compression you may consider leaving it off. You can turn compression on and off on a client-by-client basis with the '-c' option for clients. See term_clients(1).

baudrate off|<number>
    This is used to limit the rate at which term sends data. Set this to the minimum of your modem speed, and the computer-to-modem baud rate. Values that are too high will cause packet retransmissions if data is lost; values that are too low will cause loss of throughput. off will make your rate unlimited.

timeout <number>
    Set the number of 1/20ths of a second to wait before re-sending packets that haven't been acknowledged. Low values will provide faster recovery from line noise, but higher values are required if the latencies in your link are large. Values between 50 and 120 are typical. The default value is 70.

noise on|off
    If this is set, then term will send anything it doesn't understand to the standard error or the -l file. This is where talk requests, mail biffs, writes, and corrupted packets will end up. This is recommended for the local end.

remote
    This should be set on the remote side. It should always be specified on one and only one end of the link. This prevents client number clashes, and determines which server says hello first.

window <number>
    This set the maximum number of packets that can be outstanding the large the value, the better your maximum possible transmission speed, but if it is too large, it will take a long to recover from timeout errors! Allowed values are 1-16. The default is based on your baudrate.

shift <number>
    This sets a 'shift' value. This number is XOR'ed with all bytes before they are sent and dramatically reduces the # of escape characters sent. Typically numbers between 224 and 255 give the best results.

sevenbit on|off
    Use this if you are running on a 7 bit line. By default this is off.

seven_in on|off
    Use this if your incoming line is seven bit or you need to escape most of the characters between 128 and 255. If seven_in is on at one machine, seven_out must be on at on the other machine.

seven_out on|off
    Use your outgoing line is seven bit. See seven_in.

stopbits <number>
    This is used in the transmission speed calculations. The default value is 1.

denyrsh on|off
    This allows you to block incoming execution requests. The default is off.

chroot <pathname>
    This performs a chroot() to the specified path, just before entering main loop. This option is ignored if term is started by anybody except root.

share on|off
    This controls whether other users my access the term socket by setting the TERMMODE and TERMSHARE environmental variables, and using SUID -or- SGID programs.

chdir <pathname>
    This makes the default directory the specified path.

login on|off
    Use this to specify you don't want "trsh" to default with a login shell. The default is off.

noise on|off
    Use this to turn on printing of line noise and warnings, and talk requests. This is off by default.

quiet <number>
    This sets the "quietness level", zero by default. This is equivalent to [-q], but only takes effect after reading the termrc, so it has no effect on the initial messages printed before reading termrc.

terminate <string>
    This sets a string that will cause term to exit, and is '00000' by default. To help prevent accidently terminations this must be at least 5 characters long.

shell <command>
    This specifies some command you want to be given as soon as you execute your first term command. Normally this should be a script name.

blocksize <number>
    Use this to set the maximum size block that can be written to your modem at once. Typical values are 256, 512, or 1024. The default is 512 and you probably don't need to change this.

collisions on|off
    Use this if you get lots of timeout errors only when transmitting and receiving at the same time.

flowcontrol off|<number>
    Use this to tell term to generate control-Q's every now and then in case your terminal server understands flow control and things accidently turn it off, i.e. line noise. This is off by default, but may be set to any non-negative value.

increment <number>
    This controls how many times a second term tries to send data. Normally the default of 20 should be fine, but if you are using term to get by a firewall, you might improve your transmission speeds by raising this.

packetsize <number>
    This is the maximum size packet term will use. The default is 256 and you probably won't need to change this. Valid values are anything between 1 and 256.

ENVIRONMENT VARIABLES

BAUDRATE
    Used to set the speed. Overridden by termrc or command line setting.

SHELL
    Default shell for trsh.

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.

TERMSHARE
    Where term runs from in shared mode. The default is /usr/local/lib/term.

TERMMODE
    What mode term will attempt to use. 0 == private, 1 == system shared, 2 == user shared.

TERMSERVER
    This should specify the <server> name, if you used one.

DIAGNOSTICS
The -d option provides debugging output. See term_setup(1) or linecheck(1) for further diagnostic information.

SEE ALSO

term_clients(1)
    The man page for the term clients.

term_setup(1)
    The man page for the linecheck program and the test program for debugging your serial link and exercising term and clients.

term/INSTALL
    Documents how to install term on your machine.

term/README
    The original documents for term from which these man pages were written.

term/README.security
    Describes in more detail how term's shared mode works.

term/README.porting
    How to compile and link network-using programs to take advantage of term's transparent network emulation.

term/Term.HOWTO
    A detailed description of how to make term work. It may be somewhat out of date with the current version of term.

term/FAQ
    Answers to some frequently asked questions.

term/TERMRC
    Another description of the syntax and options the user may set in ~/.term/termrc.

term/CREDITS
    Credits for many of the people who have contributed to term.

term/CHANGES
    A list of changes to the program since these manuals were edited (version 1.19).

BUGS
If a remote client stops consuming its input but leaves the channel open, the local term daemon will continue to resend unacked packets. Term by default requires a line which passes through all ascii values from 0 to 255. Xyplex-type terminal servers may require the use of set session passall to work correctly.

AUTHOR
Michael O'Reilly, oreillym@tartarus.uwa.edu.au.
Bill C Riemers, bcr@physics.purdue.edu, is temporarily maintaining term.