4. Using Taylor UUCP

4.1 Calling Other Systems
4.2 Accepting Calls
4.3 Using UUCP for Mail and News.
4.4 The Spool Directory Layout
4.5 Cleaning the Spool Directory		Cleaning the UUCP Spool Directory

4.1 Calling Other Systems

By default uucp and uux will automatically start up uucico to call another system whenever work is queued up. However, the call may fail, or you may have put in time restrictions which prevent the call at that time (perhaps because telephone rates are high) (see section 5.7.3.1 When to Call). Also, a remote system may have work queued up for your system, but may not be calling you for some reason (perhaps you have agreed that your system should always place the call). To make sure that work gets transferred between the systems withing a reasonable time period, you should arrange to periodically invoke uucico.

These periodic invocations are normally triggered by entries in the `crontab' file. The exact format of `crontab' files, and how new entries are added, varies from system to system; check your local documentation (try `man cron').

To attempt to call all systems with outstanding work, use the command `uucico -r1'. To attempt to call a particular system, use the command `uucico -s system'. To attempt to call a particular system, but only if there is work for it, use the command `uucico -C -s system'. (see section 2.10 Invoking uucico).

A common case is to want to try to call a system at a certain time, with periodic retries if the call fails. A simple way to do this is to create an empty UUCP command file, known as a poll file. If a poll file exists for a system, then `uucico -r1' will place a call to it. If the call succeeds, the poll file will be deleted.

A poll file can be easily created using the `uux' command, by requesting the execution of an empty command. To create a poll file for system, just do something like this:

uux -r system!

The `-r' tells `uux' to not start up `uucico' immediately. Of course, if you do want `uucico' to start up right away, omit the `-r'; if the call fails, the poll file will be left around to cause a later call.

For example, I use the following crontab entries locally:

45 * * * * /bin/echo /usr/lib/uucp/uucico -r1 | /bin/su uucpa 40 4,10,15 * * * /usr/bin/uux -r uunet!

Every hour, at 45 minutes past, this will check if there is any work to be done, and, if there is, will call the appropriate system. Also, at 4:40am, 10:40am, and 3:40pm, this will create a poll file file for `uunet', forcing the next run of uucico to call `uunet'.

4.2 Accepting Calls

To accept calls from another system, you must arrange matters such that when that system calls in, it automatically invokes uucico on your system.

The most common arrangement is to create a special user name and password for incoming UUCP calls. This user name typically uses the same user ID as the regular uucp user (Unix permits several user names to share the same user ID). The shell for this user name should be set to uucico.

Here is a sample `/etc/passwd' line to accept calls from a remote system named airs:

Uairs:password:4:8:airs UUCP:/usr/spool/uucp:/usr/lib/uucp/uucico

The details may vary on your system. You must use reasonable user and group ID's. You must use the correct file name for uucico. The password must appear in the UUCP configuration files on the remote system, but will otherwise never be seen or typed by a human.

Note that uucico appears as the login shell, and that it will be run with no arguments. This means that it will start in slave mode and accept an incoming connection. See section 2.10 Invoking uucico.

On some systems, creating an empty file named `.hushlogin' in the home directory will skip the printing of various bits of information when the remote uucico logs in, speeding up the UUCP connection process.

For the greatest security, each system which calls in should use a different user name, each with a different password, and the called-login command should be used in the `sys' file to ensure that the correct login name is used. See section 5.7.4 Accepting a Call, and see 5.11 Security.

If you never need to dial out from your system, but only accept incoming calls, you can arrange for uucico to handle logins itself, completely controlling the port, by using the `--endless' option. See section 2.10 Invoking uucico.

4.3 Using UUCP for Mail and News.

Taylor UUCP does not include a mail package. All Unix systems come with some sort of mail delivery agent, typically sendmail or MMDF. Source code is available for some alternative mail delivery agents, such as IDA sendmail and smail.

Taylor UUCP also does not include a news package. The two major Unix news packages are C-news and INN. Both are available in source code form.

Configuring and using mail delivery agents is a notoriously complex topic, and I will not be discussing it here. Configuring news systems is usually simpler, but I will not be discussing that either. I will merely describe the interactions between the mail and news systems and UUCP.

A mail or news system interacts with UUCP in two ways: sending and receiving.

4.3.1 Sending mail or news via UUCP
4.3.2 Receiving mail or news via UUCP

4.3.1 Sending mail or news via UUCP

When mail is to be sent from your machine to another machine via UUCP, the mail delivery agent will invoke uux. It will generally run a command such as `uux - system!rmail address', where system is the remote system to which the mail is being sent. It may pass other options to uux, such as `-r' or `-g' (see section 2.3 Invoking uux).

The news system also invokes uux in order to transfer articles to another system. The only difference is that news will use uux to invoke rnews on the remote system, rather than rmail.

You should arrange for your mail and news systems to invoke the Taylor UUCP version of uux. If you only have Taylor UUCP, or if you simply replace any existing version of uux with the Taylor UUCP version, this will probably happen automatically. However, if you have two UUCP packages installed on your system, you will probably have to modify the mail and news configuration files in some way.

Actually, if both the system UUCP and Taylor UUCP are using the same spool directory format, the system uux will probably work fine with the Taylor uucico (the reverse is not the case: the Taylor uux requires the Taylor uucico). However, data transfer will be somewhat more efficient if the Taylor uux is used.

4.3.2 Receiving mail or news via UUCP

To receive mail, all that is necessary is for UUCP to invoke rmail. Any mail delivery agent will provide an appropriate version of rmail; you must simply make sure that it is in the command path used by UUCP (it almost certainly already is). The default command path is set in `policy.h', and it may be overridden for a particular system by the command-path command (see section 5.7.7 Miscellaneous sys File Commands).

Similarly, for news UUCP must be able to invoke rnews. Any news system will provide a version of rnews, and you must ensure that is in a directory on the path that UUCP will search.

4.4 The Spool Directory Layout

In general, the layout of the spool directory may be safely ignored. However, it is documented here for the curious. This description only covers the SPOOLDIR_TAYLOR layout. The ways in which the other spool directory layouts differ are described in the source file `unix/spool.c'.

Directories and files are only created when they are needed, so a typical system will not have all of the entries described here.

4.4.1 System Spool Directories
4.4.2 Status Directory		Status Spool Directory
4.4.3 Execution Subdirectories		Execution Spool Subdirectories
4.4.4 Other Spool Subdirectories
4.4.5 Lock Files in the Spool Directory		Spool Directory Lock Files

4.4.1 System Spool Directories

`system'

There is a subdirectory of the main spool directory for each remote system.

`system/C.'

This directory stores files describing file transfer commands to be sent to the system. Each file name starts with `C.g', where g is the job grade. Each file contains one or more commands. For details of the commands, see 6.5.2 UUCP Protocol Commands.

`system/D.'

This directory stores data files. Files with names like `D.gssss', where g is the grade and ssss is a sequence number, are waiting to be transferred to the system, as directed by the files in the `system/C.' directory. Files with other names, typically `D.systemgssss', have been received from system and are waiting to be processed by an execution file in the `system/X.' directory.

`system/D.X'

This directory stores data files which will become execution files on the remote system. In current practice, this directory rarely exists, because most simple executions, including typical uses of rmail and rnews, send an `E' command rather than an execution file (see section 6.5.2.4 The E Command).

`system/X.'

This directory stores execution files which have been received from system. This directory normally exists, even though the corresponding `D.X' directory does not, because uucico will create an execution file on the fly when it receives an `E' command.

`system/SEQF'

This file holds the sequence number of the last job sent to system. The sequence number is used to ensure that file names are unique in the remote system spool directory. The file is four bytes long. Sequence numbers are composed of digits and the upper case letters.

4.4.2 Status Directory

`.Status'

This directory holds status files for each remote system. The name of the status file is the name of the system which it describes. Each status file describes the last conversation with the system. Running `uustat --status' basically just formats and prints the contents of the status files (see section 2.4.3 uustat Examples).

Each status file has a single text line with six fields.

code

A code indicating the status of the last conversation. The following values are defined, though not all are actually used.

`0'

Conversation completed normally.

`1'

uucico was unable to open the port.

`2'

The last call to the system failed while dailing.

`3'

The last call to the system failed while logging in.

`4'

The last call to the system failed during the initial UUCP protocol handshake (see section 6.5.1 The Initial Handshake).

`5'

The last call to the system failed after the initial handshake.

`6'

uucico is currently talking to the system.

`7'

The last call to the system failed because it was the wrong time to call (this is not used if calling the system is never permitted).

retries

The number of retries since the last successful call.

time of last call

The time of the last call, in seconds since the epoch (as returned by the time system call).

wait

If the last call failed, this is the number of seconds since the last call before uucico may attempt another call. This is set based on the retry time; see 5.7.3.1 When to Call. The `-f' or `-S' options to uucico direct it to ignore this wait time; see 2.10 Invoking uucico.

description

A text description of the status, corresponding to the code in the first field. This may contain spaces.

system name

The name of the remote system.

4.4.3 Execution Subdirectories

`.Xqtdir'

When uuxqt executes a job requested by uux, it first changes the working directory to the `.Xqtdir' subdirectory. This permits the job to create any sort of temporary file without worrying about overwriting other files in the spool directory. Any files left in the `.Xqtdir' subdirectory are removed after each execution is complete.

`.Xqtdirnnnn'

When several instances of uuxqt are executing simultaneously, each one executes jobs in a separate directory. The first uses `.Xqtdir', the second uses `.Xqtdir0001', the third uses `.Xqtdir0002', and so forth.

`.Corrupt'

If uuxqt encounters an execution file which it is unable to parse, it saves it in the `.Corrupt' directory, and sends mail about it to the UUCP administrator.

`.Failed'

If uuxqt executes a job, and the job fails, and there is enough disk space to hold the command file and all the data files, then uuxqt saves the files in the `.Failed' directory, and sends mail about it to the UUCP administrator.

4.4.4 Other Spool Subdirectories

`.Sequence'

This directory holds conversation sequence number files. These are used if the sequence command is used for a system (see section 5.7.7 Miscellaneous sys File Commands). The sequence number for the system system is stored in the file `.Sequence/system'. It is simply stored as a printable number.

`.Temp'

This directory holds data files as they are being received from a remote system, before they are moved to their final destination. For file send requests which use a valid temporary file name in the temp field of the `S' or `E' command (see section 6.5.2.1 The S Command), uucico receives the file into `.Temp/system/temp', where system is the name of the remote system, and temp is the temporary file name. If a conversation fails during a file transfer, these files are used to automatically restart the file transfer from the point of failure.

If the `S' or `E' command does not include a temporary file name, automatic restart is not possible. In this case, the files are received into a randomly named file in the `.Temp' directory itself.

`.Preserve'

This directory holds data files which could not be transferred to a remote system for some reason (for example, the data file might be large, and exceed size restrictions imposed by the remote system). When a locally requested file transfer fails, uucico will store the data file in the `.Preserve' directory, and send mail to the requestor describing the failure and naming the saved file.

`.Received'

This directory records which files have been received. If a conversation fails just after uucico acknowledges receipt of a file, it is possible for the acknowledgement to be lost. If this happens, the remote system will resend the file. If the file were an execution request, and uucico did not keep track of which files it had already received, this could lead to the execution being performed twice.

To avoid this problem, when a conversation fails, uucico records each file that has been received, but for which the remote system may not have received the acknowledgement. It records this information by creating an empty file with the name `.Received/system/temp', where system is the name of the remote system, and temp is the temp field of the `S' or `E' command from the remote system (see section 6.5.2.1 The S Command). Then, if the remote system offers the file again in the next conversation, uucico refuses the send request and deletes the record in the `.Received' directory. This approach only works for file sends which use a temporary file name, but this is true of all execution requests.

4.4.5 Lock Files in the Spool Directory

Lock files for devices and systems are stored in the lock directory, which may or may not be the same as the spool directory. The lock directory is set at compilation time by LOCKDIR in `policy.h', which may be overridden by the lockdir command in the `config' file (see section 5.6.1 Miscellaneous config File Commands).

For a description of the names used for device lock files, and the format of the contents of a lock file, see 6.3 UUCP Lock Files.

`LCK..sys'

A lock file for a system, where sys is the system name. As noted above, these lock files are kept in the lock directory, which may not be the spool directory. These lock files are created by uucico while talking to a remote system, and are used to prevent multiple simultaneous conversations with a system.

On systems which limit file names to 14 characters, only the first eight characters of the system name are used in the lock file name. This requires that the names of each directly connected remote system be unique in the first eight characters.

`LCK.XQT.NN'

When uuxqt starts up, it uses lock files to determine how many other uuxqt daemons are currently running. It first tries to lock `LCK.XQT.0', then `LCK.XQT.1', and so forth. This is used to implement the max-uuxqts command (see section 5.6.1 Miscellaneous config File Commands). It is also used to parcel out the `.Xqtdir' subdirectories (see section 4.4.3 Execution Subdirectories).

`LXQ.cmd'

When uuxqt is invoked with the `-c' or `--command' option (see section 2.11 Invoking uuxqt), it creates a lock file named after the command it is executing. For example, `uuxqt -c rmail' will create the lock file `LXQ.rmail'. This prevents other uuxqt daemons from executing jobs of the specified type.

`system/X./L.xxx'

While uuxqt is executing a particular job, it creates a lock file with the same name as the `X.' file describing the job, but replacing the initial `X' with `L'. This ensures that if multiple uuxqt daemons are running, they do not simultaneously execute the same job.

`LCK..SEQ'

This lock file is used to control access to the sequence files for each system (see section 4.4.1 System Spool Directories). It is only used on systems which do not support POSIX file locking using the fcntl system call.

4.5 Cleaning the Spool Directory

The spool directory may need to be cleaned up periodically. Under some circumstances, files may accumulate in various subdirectories, such as `.Preserve' (see section 4.4.4 Other Spool Subdirectories) or `.Corrupt' (see section 4.4.3 Execution Subdirectories).

Also, if a remote system stops calling in, you may want to arrange for any queued up mail to be returned to the sender. This can be done using the uustat command (see section 2.4 Invoking uustat).

The `contrib' directory includes a simple `uuclean' script which may be used as an example of a clean up script. It can be run daily out of `crontab'.

You should periodically trim the UUCP log files, as they will otherwise grow without limit. The names of the log files are set in `policy.h', and may be overridden in the configuration file (see section 5.6 The Main Configuration File). By default they are are `/usr/spool/uucp/Log' and `/usr/spool/uucp/Stats'. You may find the savelog program in the `contrib' directory to be of use. There is a manual page for it in `contrib' as well.