Setting Things Up

Build term

Hopefully, this should just involve a make, if this doesn't work, you may have to do some hacking. Make sure that you've got the same version on all machines you want to run term on - different versions of term are incompatible. Seek out and destroy any old binaries on your system - or know how to avoid them.

Test term

Do a make test to build term's test daemon. Test works by running two copies of term on your system, a ``local'' and a ``remote'' copy. Both of these will read your termrc, so you can adjust their behaviour. Run test as ./test so as to avoid your system's test. You should now be able to do a trsh and a tupload (try tupload ./term /usr/tmp - you should get a copy of the term binary in /usr/tmp ). The local term's output should show up in local.log, the remote's in remote.log. You can start term up with a -d255 flag to enable debugging output to be written to these files, or enable debugging in your termrc.

Make a Transparent Link

Presumably, you can establish a modem connection between your local and remote hosts. Typically, your dialing into some kind of terminal server and connecting to your remote host from there. You are also using some kind of terminal software, such as kermit or seyon to talk to your modem (the examples in this document will use kermit, since that is what its author uses). If you're having trouble with your modem, or your terminal software, take a look at the Serial HOWTO, that should help you out.

Having established your link, you want to make it as transparent as possible. Check the commands on the terminal server (help or ? will usually get you started). Go for the 8 bit options whenever possible. This may mean changing the way you log in to a system, e.g. if the server uses rlogin, you may have to use it and give it the -8 flag to make it transparent. Especially watch out for xon/xoff flow control, you don't want that, try to enable rts/cts (hardware) flow control. You may need to check your modem docs to learn how to configure it to do 8-bit rts/cts communications.

Run linecheck

linecheck is program that is supplied that with term that checks the transparency of a link, providing configuration information that term needs to run correctly. linecheck will send each of the 255 possible eight bit characters over the link and verify that each was transmitted successfully. term needs to be configured to deal with characters that cannot be transmitted over the link, and linecheck determines what characters these are. You use linecheck after you've established as transparent a modem link as possible. To run linecheck, do the following

  1. On the remote system, run linecheck linecheck.log.
  2. Suspend your comm program (ˆZ under kermit) (otherwise it will steal characters from linecheck).
  3. On the local system run linecheck linecheck.log > /dev/modem < /dev/modem.

When linecheck is done, you'll find a set of numbers at the bottom of the linecheck.log files. These should be escaped in the termrc at the other end of the link. For example, on my system, my local linecheck.log said nothing and my remote linecheck.log said to escape 29 and 157. Therefore, my local termrc escapes these characters and my remote termrc escapes nothing. If I escape a character on one end, I have to also ignore it on the other, so, in this example, I'll have to ignore 29 and 157 on my remote system.

If linecheck hangs, try using

linecheck linecheck.log 17 19 > /dev/modem < /dev/modem 

this will escape your xon/xoff (flow control) characters, which will hang your line if you've got software flow control. If this solves the hanging problems, you'll want to escape /ignore 17/19 in both termrc's. If your terminal server has other demonic characters that will shut it down, try running linecheck with those characters escaped, as above. You can spot these characters if linecheck hangs. If this is the case, kill it, then look in the logfiles. The last characters transmitted are likely to be the culprits. Try it again with these characters escaped.

In summary, my local termrc has the lines

 
escape 29
escape 157
and my remote termrc has the lines
 
ignore 29
ignore 157
since my remote linecheck.log said to escape 29 and 157.

Try Running term

Log into the remote system, making the link as transparent as possible (if you haven't already). Fire up term on the remote end. I use the following:

exec term -l $HOME/tlog -s 38400 -c off -w 10 -t 150.

Let's run down each option one by one (note that I could just as easily have put these options in my termrc. I did it this way because it saves editing a file while getting term set up).

exec means to destroy your current shell, running the given program in its place. I exec things because I don't intend to use my login shell again, so it's just wasting memory. If you're debugging the link and can reliably kill the remote term, you might not want to do an exec.

-l $HOME/tlog. This logs errors to the file tlog in my home directory. Very useful for debugging. No reason not to do this.

-s 38400 : I've got a 14400 baud modem, with compression. For optimal compression ratios, I want to be able to push bits down the pipe as fast as possible. For a slower modem, you should use something lower. Note that if you have a slower machine with 16450 uart on your serial port, high baudrates can cause data loss by overloading the chip on your serial port. term will recover from this, but if you see a lot of error messages in your log file, (or get overrun warnings from linux kernel versions 0.99pl15 and up) you again might want to lower this number.

-c off : This turns data compression off. I've got a compressing modem, and I don't want to compress things twice.

-w 10 -t 150 : Again, these are options to optimize my fast modem link. I have set my window to 10 and my timeout to 150. This is per the recommendation in the term_setup man page.

Suspend your comm program (ˆZ under kermit). You don't want it running while term is running, because it will fight with term over the serial port. If you can convince your modem to not hang up when you exit your comm program (when it toggles DTR), you could just exit the program at this point.

Now run term locally. I use:

term -r -c off -l $HOME/tlog -s 38400 -w 10 -t 150 \ < /dev/modem > /dev/modem &

The only option here that is different from the other end is the -r option. You need this on one end, otherwise term clients will spontaneously die on you. I need to tell term where the modem is, so I point both standard input and output at /dev/modem (that's what the < and > do). I also run it in the background, so I can use this screen for something else if I want to.

term should work now :-). Try a trsh, and see what happens. If you hang, or your link seems slow, take a look at your tlog on each end. Are you getting timeouts or error messages? If so, then you've configured something incorrectly. Try again (after you've finished reading this :-). Note that the connection won't seem blazingly fast, especially if you're using compression - it will be a little jumpy. The real speed comes in during file transfer and the like.

Gotchas to Watch Out For

Are you running the right binary? term has been updated quite a lot, and many systems have different versions of the programs floating around. Make sure you're using the right version. Note that this applies to linecheck too. You can use bash's type -a or the whereis command to find which program is being run. term versions after 1.11 should print out their version number when they start up. (Although version 1.14 claims to be 1.12. Sigh.)

Do you have the right termrc? Is it called $HOME/.term/termrc? Some systems have pre-installed termrc's, make sure they're gone before you set things up. If you're running things as root, lookout for /.term. term creates files (sockets actually) while it's running, so it has its own directory, $HOME/.term, where the file termrc goes (note, there is no leading dot in termrc!).

Once you've got term running, you might want to try to get things optimized. A good way to measure the speed of your link is to run tmon in one window while up/downloading a file in another. Try both (big) text files and compressed files, the plain text should go a factor of two-ish faster than the compressed files. The parameters you want to fiddle with are compression (-c), windows (-w) and timeout (-t).

Compression you want this on if you don't have a compressing modem. If you do have such a modem, turn compression off, otherwise you'll be compressing things twice, which typically increasesthe amount of data transmitted. Compressing modems are ones that use the MNP-5 or V42.bis protocols. Check your modem documentation and the message when your modem connects.

Windows this is the number of chunks of data, or packets, that term will let go over the line before it gets an acknowledgment (or ack) from the remote term. For fast modems, increasing this can be a win, for slower links this can overwhelm the remote end.

Timeout the time term will wait for an ack. If you've increased windows, and you're getting timeouts in your logfile, try increasing this.

For 14400/V42.bis, I use -c off -w 10 -t 150. I typically get around 1700 cps on compressed files and 3500 cps on ascii files using tupload.