Setting Things Up

# 3 Setting Things Up

Contents of this section

## 3.1 Build `term`

When you are lucky, this should just involve a `make`. Most probably however, you need to do more. Due to new features in newer versions of `term` (`sharing`, `configure`) it is now a bit more complicated to create obtain your `term` binary. A couple of ways can now be followed to obtain your binary.

To cover all these ways `term` can be build I will split this section into three parts:

1. Build `term` upto version 1.15
2. Build `term`, versions 1.16 upto 1.19
3. Build `term`, versions 2.0.0 and higher

### Build `term` upto version 1.15

For these versions of `term` building should invoke no more than the commands

    make DO=install OS-type
    make installman

You will find `term`, its clients and the manual pages nicely built and installed and ready for use after this.

The only thing you may want to do is changing some of the pathes in the `Makefile` or changing some of the compiler flags.

### Build `term`, versions 1.16 upto 1.19

Starting with version 1.16 the concept of `sharing` the `term` connection with other users has entered `term`. With this concept built in also the ways of building `term` are extended.

To build `term` you can now choose one of the following ways:

1. You are an ordinary user (no root acces) and you do not want to share the `term` connection with other users. As user who does not want to share the `term` connection with other users you should do the following to build `term`:

       make DO=install OS-type
       make installman

   After this `term`, its clients and the manual pages are built and installed.
2. You are an ordinary user (no root acces) and you want to share the `term` connection with other users. As user who wants to share the `term` connection you should do the following:

       make DO=installshare USERSHARE=$HOME/term OS-type
       make installman

   After this `term`, its clients and the manual pages are built and installed. Furthermore, you will have a directory `$HOME/term` with permissions `drwxrwxr-x`
3. You are `root` and you do not want to share the `term` connection with other users. As root who does not want the `term` connection be shareable you should do the following to build `term`:

       make DO=install OS-type
       make installman

   After this `term`, its clients and the manual pages are built and installed.
4. You are `root` and want to make the `term` connection shareable. Create a `term` group with no member by adding the following line in /etc/group:

       term::16:root

   or any other unused `GID` than 16 when 16 is already in use. Now do

       make DO=installshare OS-type
       make installman

   After this `term`, its clients and the manual pages are built and installed. Furthermore, you now have a directory called `/usr/local/lib/term` (default) owned by group `term` and with permissions `drwxrwxr-x`

### Build `term`, versions 2.0.0 and higher

For `term` versions 2.0.0 and higher there are many ways to build the `term` binary and the clients. All of these can be done both by root and by ordinary user:

1. Build `term` in private mode without full `term` networking
2. Build `term` in private mode with full `term` networking
3. Build `term` in shared mode without full `term` networking
4. Build `term` in shared mode with full `term` networking

In these versions of `term` also the `configure` concept is used. When `configure` is run it checks on what operating system you are trying to install `term`, whether the source directory is available or not and if any runtime options are set. According to the things found `configure` then creates a `Makefile` using Makefile.in which is provided in the `term` package.

Two of the more important options to configure are `--root` and `--user` which state whether `term` will be installed by root or an ordinary user.

### Build term in private mode without full `term` networking

To build `term` this way you need to execute the following commands (both for root and ordinary user):

    ./configure --root  OR --user
    make install installman

This builds the binaries and installs these binaries and the manual pages.

### Build term in private mode with full `term` networking.

To build `term` this way you need to execute the following commands (both for root and ordinary user):

    ./configure --root  OR --user
    make installnet installman

This builds the binaries and installs these binaries and the manual pages.

### Build term in shared mode without full `term` networking

To build `term` this way you need to execute the following commands (both for root and ordinary user):

    ./configure --root  OR --user
    make share installman

This builds the binaries and installs these binaries and the manual pages.

### Build term in shared mode with full `term` networking

To build `term` this way you need to execute the following commands (both for root and ordinary user):

    ./configure --root  OR --user
    make share installnet installman

This builds the binaries and installs these binaries and the manual pages.

## 3.2 Setting environment variables

`term` knows a couple of environment variables which can be set by users. The first three of these I will explain are

- TERMDIR
- TERMSHARE
- TERMMODE

By setting these variables you can control the way `term` is run.

For `term` versions upto 1.15 only the variable `TERMDIR` is important (these versions do not know the shared mode). For these versions TERMDIR should be set as follows:

    setenv TERMDIR $HOME     (csh or tcsh)
    export TERMDIR=$HOME     (bash)

Starting with version 1.16 `term` also lnows the variables `TERMSHARE` and `TERMMODE`. With these variables `term` can be told to run in `private` mode or in `shared` mode. I will explain how to set the variables for private mode and shared mode.

1. Running `term` in private mode can be done setting the variables TERMDIR and TERMMODE in the following way: For csh or tcsh

       setenv TERMDIR $HOME
       setenv TERMMODE 0

   For bash

       export TERMDIR=$HOME
       export TERMMODE=0

2. When you want to use `term` in shared mode there are two ways of setting the variables:
   1. When term is installed as a SUID program only TERMMODE has to be set (?? README in the term package).

          setenv TERMMODE 'number'    (csh or tcsh)
          export TERMMODE='number'    (bash)

      For `'number'` you have to enter 1 when you are using one of the `term` versions 1.16 upto 1.19 and 2 when you are using `term` version 2.0.0 or higher.
   2. When `term` is installed as a SGID program the variables have to be set in the following way: For csh or tcsh

          setenv TERMMODE 1
          setenv TERMDIR /usr/local/lib/term
          setenv TERMSHARE $TERMDIR

      For bash

          export TERMMODE=1
          export TERMDIR=/usr/local/lib/term
          export TERMSHARE=$TERMDIR

      Setting the variables this way makes it possible to start old clients (clients linked to an older version of `client.a`) in shared mode.

Starting with version 2.0.0 `term` also knows the variable `TERMSERVER`. You need to set this variable when you have multiple modems and you have more than one conection at a time. To specify which connection to use, you must start `term` with a server name:

    nohup term -v /dev/modem1 Connection1 &
    nohup term -v /dev/modem2 Connection2 &

Users should then set the variable TERMSERVER to the connection name they want to use:

    setenv TERMSERVER Connection1   (csh or tcsh)
    export TERMSERVER=Connection2   (bash)

## 3.3 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.`

## 3.4 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 are 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 do not 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.

## 3.5 Run linecheck

`linecheck` is program that is supplied with `term`. It checks the transparency of a link, providing configuration information that `term` needs to run correctly. `linecheck` will send each of the 256 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. Escape back to your local system and 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 will 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 shall 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 have got software flow control. If this solves the hanging problems, you will 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.

## 3.6 Try Running `term`

Log into the remote system, making the link as transparent as possible (if you have not 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 do not intend to use my login shell again, so it is just wasting memory. If you are 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 have 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 have got a compressing modem, and I do not 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.

Escape back to your local machine and suspend your comm program (`^Z` under kermit). You do not 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 is 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 have configured something incorrectly. Try again (after you have finished reading this :-). Note that the connection won't seem blazingly fast, especially if you are using compression - it will be a little jumpy. The real speed comes in during file transfer and the like.

## 3.7 Terminate your `term` connection

Most certain, after you have done a lot of work using `term`, you want to finish your work and bring your `term` connection down. For this to be realized there are three ways:

1. Kill the `term` programs on both sides of the connection. This is the least recommended way of terminating your connection
2. A better way is to execute the following command locally:

       echo '00000' > /dev/modem

   This wil nicely terminate your `term` connection. It will work for all version of `term`. Make sure that the sequence of zeros contains at least `five` zeros.
3. Starting with version 1.14 there is the program `tshutdown` (actually for version 1.14 it is available as a patch, for newer versions it is in the package). Executing tshutdown nicely terminates your `term` connection.

## 3.8 Gotchas to Watch Out For

If your .term or term directory is mounted with NFS you need to set the flag -DTERM_NFS_DIR in the CFLAGS line of the Makefile. Alas, for the author this flag causes a compile error when term 1.19 is compiled on a machine running sunOS 4.*.

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 are 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`? Depending of the version of term you are running and the way you installed term (being root or user) this file has to be in one of the following directories: `/usr/local/lib/term`, `$HOME/.term` or `$HOME`. Some systems have pre-installed termrc's, make sure they are gone before you set things up. If you are running things as root, lookout for `/.term.` `term` creates files (sockets actually) while it is running, so it has its own directory, `$HOME/.term,` where the file `termrc` goes (note, there is no leading dot in `termrc`!).

With newer versions of `term` the structure of the directory tree under `/usr/local/lib/term` has changed a couple of times. If you are not aware of this, it can cause all kinds of error messages. The best thing to do is to delete the directory tree under /usr/local/lib/term (save your `termrc`) and then install your new `term` version. This way, you avoid the struggle with a messed up directory tree.

Once you have 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`), timeout (`-t`) and retrain (`-A`. Watch out with the retrain parameter. I got a performance decrease of 80% to 90% compared to running term without the retrain parameter. It is not clear if this is a bug in term version 1.19, the version I am running and if this problem exists only with term version 1.19.

`Compression`: you want this on if you do not have a compressing modem. If you do have such a modem, turn compression off, otherwise you will be compressing things twice, which typically increases the 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 have increased windows, and you are 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.

Next Chapter, Previous Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter