Unlike many other networking environments, UUCP requires no special hardware. It is the basis for communication on USENET (See "Joining USENET," by Sydney Weinstein, Sys Admin July/August 1992) and between systems. While various UUCP protocols can be run on Local Area Networks, UUCP is most commonly used to create a dial-up network (that is, call the remote machine when I have something for it; otherwise, stay quiet).

UUCP History

UUCP was first written by Mike Lesk of AT&T as a research project. During and after the project, UUCP became such a success that Mike Lesk joined with David Nowitz and Greg Chesson to build a version which was shipped with Version 7 UNIX and subsequently became known as Version 2 UUCP. Some vendors still ship this version, and many older UNIX systems use it.

AT&T's System V Release 3 included a new UUCP version: the "Basic Networking Utilities," or HoneyDanBer (HDB), UUCP. Written in 1983 by Peter Honeyman, David A. Nowitz, and Brian E. Redman, HDB UUCP was named after the login names the three used on the system, hence "Honey," "Dan," "Ber." The HDB release added functionality and corrected some of the design deficiencies which existed. Some of the the new functionality provided support for newer modems and networks.

For the most part, communication between the different UUCP versions is transparent once they have been configured. While most of the features remain the same, the names and layouts of many of the configuration files have changed. As a result, it is very easy to tell which version you have. If your /usr/lib/uucp directory contains a file named L.sys, then you have Version 2; if there's a file named Systems, your version is HoneyDanBer UUCP. If you don't have a /usr/lib/uucp directory, means that you don't have UUCP installed. Figure 1 lists the file names for each version, and tells what they are used for.

The UUCP Network

The UUCP network consists of a group of machines that are connected by some communications mechanism and that use UUCP to transfer files and information. Figure 2 shows a sample network consisting of an Internet gateway, uunet.ca, which provides UUCP services via dialup 19.2 Kbaud over a Telebit Trailblazer Plus at choreo's end, and a Telebit T3000 at uunet.ca's end. unilabs connects to choreo at 19.2 Kbaud using a Telebit Trailblazer. The three other machines which are connected to unilabs use 9600 direct wire baud over.

The connection mechanism may consist of a modem and phone line, a serial cable between machines which are in close proximity, or some form of a leased line in the case of distant systems.

A UUCP network typically includes diverse machines and operating system versions. The network shown in Figure 2, for example, connects SCO UNIX, Motorola UNIX, AT&T UNIX, Spectrix XENIX, and SCO XENIX. This diversity puts a premium on cooperation, for even though all of these machines run UNIX or a derivative, the different versions of UUCP involved make each one unique.

How It Works

Before explaining the UUCP commands, I want to provide a brief overview of how things work. A more thorough discussion comes later.

A user submits a job to UUCP for processing by using one of three commands: uucp, uux, or uuto. These commands create a job file in the /usr/spool/uucp/sysname directory. The program uucico calls the remote system, logs in, and transfers the files, then uuxqt completes the processing on the remote system. UUCP is a batch processing service: it may take a while for the job to be processed, as the system administrator may have restricted the times when the uucico daemon executes (in order to control long-distance phone charges, for example).

UUCP, like most networking tools, has a specific form of machine addressing. The UUCP form is commonly called "bang" addressing, because machines in the UUCP command are separated by the ! (bang) character, with the filename as the final component, as in

thumper!unilabs!choreo!/tmp/transfer

In this address, a file will travel from the machine thumper, to unilabs, to choreo, where it will end up as the file /tmp/transfer. UUCP commands do not understand Internet (or Domain) addressing, which is typically used in TCP/IP and many mail applications. Internet addressing uses the "@" symbol to separate machine and user as in

chare@unilabs.org

The "!" has special meaning to the C shell, so if you work with that shell, remember to escape the "!" with a backslash to prevent the C shell from interpreting the "!", as follows

thumper\!unilabs\!choreo\!/tmp/transfer

I should note that while as a user I can execute the command, whether or not the remote system carries out my request depends upon the level of security implemented on the remote system.

The Directory Hierarchy

The UUCP utilities use three distinct directory hierarchies, as illustrated in Figure 3a for HoneyDanBer and Figure 3b for Version 2.

Both versions use the /usr/lib/uucp directory for the base UUCP programs and the configuration files. /usr/bin contains the programs typically used by users. The separation is partly owing to the nature of UNIX, but is also intended to deny regular users access to many of the configuration files in /usr/lib/uucp for security reasons.

The /usr/bin directory contains the user-level commands which allow access to the UUCP subsystem. /usr/lib/uucp contains the configuration and operating system level commands, and /usr/spool/uucp holds the log and working files. /usr/spool/uucppublic is typically the only directory which is readable and writable by UUCP.

Among the file differences between the two versions is the cu command. Version 2 places it in /bin; HDB, in /usr/bin.

So, what are the commands included in these directories? The heart of the set is uucico (UNIX to UNIX Copy In Copy Out). This program starts the transfer by calling the remote system (or acting as a shell when the remote system calls in), then negotiates the login, identifies the protocol to use for this transfer (UUCP supports several different protocols), and transfers the files. Normally, only the system administrator will invoke this command in interactive mode. Typically, it is run by system utilities such as cron, in order to help control access. uucico will be discussed more thoroughly later in this series. In this installment, I concentrate on user commands.

The uuname Command

What you'll need to know in order to use UUCP effectively is the name of your own system, and the names of the systems your system knows how to connect to. The files that contain the information on how to connect to whom, when, etc., are all protected files so the information can only be accessed indirectly, through the uuname command.

uuname with no arguments returns the list of systems known to the uucp command; uuname -c returns the list of systems known to the cu command. The -c option is typically only supported by HoneyDanBer UUCP systems, but these lists will usually be the same, unless cu and uucp use different files. Figure 4 shows the use of the uuname command.

The uucp Command

uucp is the command most typically used in this toolset. Its function is to transfer files from one machine to another using "bang" syntax. You can specify as many machines as you want in the transfer path, but many machines do not allow the remote execution of UUCP. Reasons for denying remote execution might include limited storage facilities (since everything destined for a particular system is stored at the intermediate site for as long as it takes to contact the remote); cost (if a long-distance call from the intermediate system to the remote is required); or security. To promote the latter, most system administrators prefer to limit the number of commands available (note, however, that use of UUCP violates the requirements of C2 security as described in the U.S. Department of Defense, Trusted Computing Base Evaluation Criteria).

All of these issues are pertinent if you are on the USENET, as you will likely be relying upon the graciousness of someone else to complete your request.

Using uucp can be as "simple" as

uucp choreo!/usr/spool/uucppublic/transfer ~/transfer

This example is a request to copy the file transfer from the /usr/spool/uucppublic directory on choreo, to the ~ directory on the local machine. But what is ~? The ~ tells uucp to substitute the directory PUBDIR, which is usually /usr/spool/uucppublic. PUBDIR is defined at the time the UUCP binaries are compiled, and so may be different from vendor to vendor. (See Figure 5 for other examples of uses of the uucp command.)

A slight modification to this seemingly simple transfer request may result in error. For example,

cp /tmp/newcmd /bin/newcmd

will result in an error because the user executing the command doesn't have write access for the directory. The same is true for UUCP. If the command is

uucp choreo! \ /usr/spool/uucppublic/ \
transfer /bin/transfer

then the transfer will fail, because of restrictive access permissions.

This security feature allows the system administrator to control which directories will be writable by UUCP, and which directories others can read files from.

uucp has a number of useful options. If you want to send a file via e-mail or copy it to another system using uucp, but you want to make further changes to the file without forwarding those changes, you can use the -C option. The -C tells uucp to make a physical copy of the source file before transferring it to the remote system. If this option is not used, then uucp saves a pointer to where the file is so that it can be later retrieved for transmission.

uucp jobs, like lp jobs or at jobs, all have associated request or job IDs. You can use the -j option to have uucp report on the job number of the uucp request. Knowing the job number makes it easier to track the job, or to cancel it using the uustat command.

The next example uses the -j option to get the job ID, which specifies the job which copies this file to the remote system choreo:

$ uucp -j cmd.fig.1 choreo!~ \
choreoN8e71

choreoN8e71 is the job number from uucp.

The -m option instructs uucp to send mail to the sender when his/her uucp job is complete. This is handy when you need a file from a remote system to complete some work or when you're sending a file out and you want to call the recipient after the transfer is complete. The -n option followed by a user name performs the same type of operation, except that the mail message is sent to the specific user on the remote system.

If your uucp command returns an error immediately after you press RETURN, the problem is likely to be incorrect syntax. In the following sequence, for example,

$ uucp
usage uucp from ... to
uucp failed completely (2)

I didn't specify any command-line arguments, so uucp gave me a usage message and told me that it had failed. When you enter the command, uucp tries to verify that it knows how to contact the remote machine. If uucp doesn't complain, and the system prompt returns, then your request has been accepted, and now all you can do is wait and see what happens.

The uux Command

uux allows for remote command execution. uux will gather input from different systems as specified, run the command on the specified system, and, finally, send the standard output to a file. Like many system administrators, I use uux for remote printing. I have a dot matrix printer at home; when I need to print a file on my employer's laser printer, I format it and then submit it to my printer system. My printer system executes the appropriate printer interface, which collects the data to be printed, and runs uux (as in the next example) to print the file on the remote printer.

uux - choreo!lp -dnec

This example instructs uux to read its standard input for the data stream, and to send this data stream to the command lp -dnec on the remote system choreo. The Santa Cruz Operation used this method to implement remote printing over UUCP, XENIX-NET, and TCP/IP prior to their support for the LPD protocol.

A second example

uux "!diff \
usg!/usr/dan/file1 \
pwba!/a4/dan/file2 > \
!~/dan/file.diff"

retrieves file1 from the system usg and file2 from the system pwba, runs a diff from the local system on the two files, and saves the output under PUBDIR in a file named file.diff. uux will try to complete all of the file transfers and then run the command.

Systems that use UUCP for their USENET news feed use uux to invoke the rnews command on the remote system, for the purpose of transferring news articles.

The uuto and uupick Commands

The uuto command works with uupick to send files to a remote destination, invoking a uucp command to perform the transfer. Files transferred via uuto are saved in the directory structure shown in Figure 7.

For each user who uses uuto, uucp creates a directory in the /usr/spool/uucppublic/receive directory, under the user name. Then there is a directory for each system. Given this type of structure, it is possible to download files with the same name from different systems, without having to consider overwriting the previous file when the next is transferred.

The command syntax for uuto is straightforward

uuto files remote!user

as in

uuto $HOME/sysadmin/uucp/* choreo!chare

This command will queue each of the files for transmission to the machine choreo, under the user name chare.

When the file arrives on the remote system, a mail message informs the user specified on the command line of its arrival (see Figure 8 for a sample message).

To notify the sender when the file transfer is complete, use the option -m on the uuto command line, as in:

uuto -m $HOME/sysadmin/ \
uucp/* wabbit!chare

In order to retrieve files sent via the uuto command, the remote user uses the command uupick. uupick may be invoked with or without the name of the system you want to check for files from. Consider the example:

chare@unilabs> uupick -s wabbit
from system wabbit: file answer
?
m
65 blocks
from system wabbit: file arepdaemon
?
d
from system wabbit: file autoreply
?
<RETURN>
chare@unilabs> 

In this example of uupick, you must give the command the name of the system you want to look at. uupick displays each file or directory found in your subdirectory and asks what you want to do with it. The action taken by uupick is dependent upon your answer.

The "m" response followed by a directory name, as in

m down_here

tells uupick to copy the file to the directory. If the specified directory name is not an absolute pathname, uupick will put the file into a destination relative to the user's current working directory. If no destination is named, then the file will be put into the user's current working directory.

The message "65 blocks" in the example is from cpio, which is used on this system to complete the copy.

The "d" response indicates that you want this entry to be deleted. If you do not want to do anything with the specifed entry, you can simply press RETURN.

The "a" response is similar to the "m," expect that it instructs uupick to copy all of the files to the specified directory. The same rules for the destination as when using the "m" response apply here.

The "p" response prints the content of the file. Be warned, however, that since this command is a shell script, it doesn't check the validity of the file before sending it to the terminal display using the cat command.

In order to quit from uupick, use the command "q", or Control-D.

Figure 9 and Figure 10, respectively, document the uuto and uupick commands.

Using Electronic Mail

A wealth of electronic mail programs is available to the UNIX community. Some are public domain, some commercial, and a couple -- mail and mailx -- are part of UNIX. Mail consists of a Mail User Agent (MUA) and a Mail Transport Agent (MTA). UUCP interacts with the MTA, while the user interacts with the MUA (electronic mail is a whole series of articles to its own, not to be tackled here).

To send mail to a user on a remote system, I need to know the name of the remote system, and the user's userID. Once I have entered my mail message, the mail transport determines that this is a remote system user, and the message is routed through UUCP to contact the remote system.

Mailing Binary Files

Binary files create problems for many mailers. The commands uuencode and uudecode encode and decode the file into something sendable through mail. For those systems which do not have these commands, there are public domain version available in the USENET archives. Take note, however, that sending a file through mail may be frowned upon. This is because you must rely on the availability of disk space on the intermediate machine -- a resource which may not be available when you need it.

To send a binary file, you uuencode it: that is, you "encode" the contents of the file into an ASCII file using a hexadecimal notation. The information on the file name is saved in a header at the top of the encoded data. The actual encoded file is 35 percent larger than the original: three bytes become four, plus some control information.

The syntax for uuencode is a little tricky, and not all systems support it (to make it really frustrating). To uuencode a file to be sent later, use the command line

uuencode sourcefile remotefile > file

It is necessary to redirect the output of uuencode to a file as it writes the encoded text to standard output by default. This is because uuencode is meant to be used in the command line

uuencode sourcefile remotefile | \
mail remote!user

If the sourcefile is not specified, then uuencode reads from standard input:

cat file | uuencode \
remotefile | mail \
remote!user

On receiving the encoded file by mail, the remote user can uudecode it to build the orginal file. Once saved from mail, the file must be edited to remove all of the lines before the word "begin" and all after the word "end."

begin 644 commands
M555#4" \
M(%1H92!U<V5R)W,@4&5R<W!E8W1I\
=F4*"D-H<FES($AA<F4*"E1H
...
7=VET:"!T:&4@=V]R9"!B96=I;BP*
"@IF
end

"Begin" and "end" indicate the start and finish of the actual file to be assembled. (There's some variation here -- I have sometimes run my file through uudecode without editing and had a useful file in the end and other times been burned.)

The begin line in the example identifies the name of the file (commands) and the permissions associated with the file (644).

uudecode is easier to get along with than uuencode. It reads from standard input if no files are specified on the command line or works with the named files:

uudecode file
cat file | uudecode

Since uudecode can read from standard input, a mail alias can be set up to automatically do the decode once it arrives to the system. Adding an alias is mail-transport-dependent, so I won't discuss it here.

Keeping Track of Things

Two commands fit into this category: uustat and uulog. uulog, which is typically not used by general users, allows the system administrator to view the log files kept by UUCP for either uucico or uuxqt, which is the companion to uux. The differences between HoneyDanBer UUCP and Version 2 are quite significant, so I'll note them here.

HDB uulog looks at the uucico and uuxqt files under /usr/spool/uucp/.Log//uucico/<system>, and /usr/spool/uucp/.Log/uuxqt/<system>. The options to HDB uulog are

-s system -- prints file transfer information regarding the named system.

-f system -- performs a tail -f on the transfer log for the named system. You must send an INTERRUPT signal to terminate this.)

-x -- looks in the uuxqt log instead of the uucico log.

-n number -- performs a tail command using the specified number of lines as the amount of text to show.

The output from the command can be useful to the system administrator who has a UUCP problem.

The Version 2 uulog command is similar in nature to the HoneyDanBer version. Version 2 uulog requires either the -u option, which, with a user name, prints the log entries for the specified user, or the -s option, which prints the log details for the specified system.

The second management command is uustat. The HDB uustat command allows the user to inquire about job status, and to perform some rudimentary job control operations. I will discuss the HDB command first, and then the Version 2 command.

HDB uustat has a number of options, most of them fairly self-explanatory. The "-a" option lists the current jobs in "all" of the UUCP queues. The information listed includes the job number, who submitted the job, when it was submitted, and what work is to be done.

The "-m" option shows the availability of each of the machines the system knows about.

uustat -p requests that a ps command be executed for each process ID in a valid lock file. The options given to the ps command are flp, which generates output like that shown below. Notice that the command being executed is a cu command to a system named choreo.

chare@unilabs> uustat -p
LCK..tty01: 2221

F S   UID  PID PPID C PRI NI   ADDR   SZ
WCHAN  STIME TTY   TIME COMD

10 S  chare 2221  115 0 28 20  531e6   26
ff78130e 23:16:47 m332x01 0:02 cu choreo

After "-a," the uustat option most often used is "-k," which kills the named UUCP job. You must be the owner of the UUCP request or the super-user in order to kill the job. The syntax requires the UUCP job ID, which you can retrieve with the uustat -a command.

There is currently no easy way to kill more than one UUCP job at a time. I will discuss several methods to accomplish this later in this series.

Listing 1 is uuq, a shell script based on a program called uuqstat, which was written by Frank Bicknell and published in Rebecca Thomas's "Wizard's Grabbag" in UNIXWorld (March 1990). This shell script prints a nicely formatted report using the output of uustat; it is for HoneyDanBer UUCP only.

The following is a somewhat spruced-up example of uustat -a output:

chare@unilabs> uuq
Remote                          Local Job
System  Direction  Date - Time  User  ID
------, ---------, -----------, ------, ------------
choreo, Sending, 09/29-23:33, chare, choreoN8ed4
diehard, Sending, 09/29-21:22, root, diehardN5960

The output includes where the job is being sent to or received from, the date and time of submission, who submitted it, and the job ID.

The Version 2 uustat command is similar to the HDB uustat.

Interactive Sessions Using UUCP

The majority of the UUCP components are for use in batch mode. However, it sometimes becomes necessary to communicate interactively with a remote system. While this is often achieved with third party public-domain or commercial terminal emulation communications software, the cu command is also an alternative.

cu is the interactive component of UUCP. Despite the availablity of third-party software, many people still use cu to conduct their remote login sessions. It is the tool commonly used to debug UUCP connections and to test for the proper operation of connections and modems before starting the UUCP process. cu is provided in both Version 2 and HDB implementations of UUCP. Berkeley UNIX versions provide a command similar to cu, called tip.

To use cu to contact a remote system, you must have a valid user name and password on the remote system. cu uses the serial port and/or modem normally be used for UUCP. During the cu connection, the local system behaves rather transparently, simply transmitting the characters to the remote system, and receiving the characters from the remote system.

There are several different ways to start cu, depending upon the options you want to use and the version which you are using. The most common method used under HDB is simply to specify the system name (this assumes that the system administrator has already taken the time to set up the appropriate files).

The command

cu wabbit

on a HDB system which has been properly configured will perform the connection. Otherwise, cu will report that the system is unknown.

This command format is not recognized under Version 2 cu. Rather, you use the format

cu -l /dev/tty000 dir

This command line means that cu should use the serial line specified with the -l option, (/dev/tty000); the dir signifies that this is a direct connection to the remote system.

Because there are many different configuration paths for UUCP and cu in general, the cu command is a complex and powerful tool, supporting file transfer and local and remote system manipulation. A common complaint is that cu doesn't provide any form of terminal emulation: it simply passes the characters through to the user's terminal, thus increasing the potential for locked terminals due to escape sequences.

Given a configured system, the following sequence shows what a session with cu will look like:

cu unilabs
Connected
UniLabs Research
Please Login: chare
Password:

SYSTEM V/68 Release R3V4.8
Version 920715 M68020
unilabs
...

Once you have logged into the remote system, it is as if you were at a dumb terminal connected directly to the system -- the remote system does not know that you have logged in via cu. You request work to be done by submitting commands as you would on your local system.

When your work is done, you exit by logging off of the remote machine and using one of the cu tilde commands to close the connection, specifically "~." (tilde period). In many cases, logging off the remote system will be enough to tell cu that the connection has been closed and that it should terminate. However, in as many other cases, cu will not be able to determine this, probably because of incorrect or deficient cabling.

cu has a built-in set of commands: the tilde command set. These commands, which range from changing directories to performing basic file transfer, are shown in Figure 13. The cu command-line options are presented in Figure 14.

Transferring Files

cu can transfer files to and from the remote system, but this file transfer capability has no form of error-checking and cannot handle binary files. The command ~%take transfers a file from the remote system to the local system, while ~%put transfers from the local system to the remote.

A sample file transfer looks like this:

chare@unilabs> cd /tmp
chare@unilabs> lc
doc.Z      mbox.chare*   uucp
mail.log    sa.adrfl    uucp.mail.log
chare@unilabs> ~%take mail.log
stty -echo;mesg n;echo '~>':mail.log;cat
mail.log;echo '~>';mesg y;stty echo
~>:mail.log
chare@unilabs> ~%put cmd.fig.1
stty -echo; cat - > cmd.fig.1; stty echo
chare@unilabs> exit
UniLabs Research
Please Login: ~.
Disconnected
$

I issued the ~%take command and said that I wanted the file mail.log. This file will be created in my current directory unless I specify another directory. cu turns off local echo using stty, denies message using mesg, and, with the ~> feature of the cu receiver process, which saves the incoming data to the named file, does a cat of the file on the remote system. Once complete, the echo and messages are re-established.

The process is the same for put, except in reverse. Normally, the number of characters transferred is printed.

Conclusion

UUCP is a large and complex animal: it takes some time to tame, but if you're patient, it becomes a valuable aid in communicating information, mail, and files with other systems and other users. If you consider UUCP to be a dead networking protocol, you might note how many users and systems exist on USENET because of it.

Bibliography

For more reading on UUCP, I suggest the following books, some of which were used as references for this series.

Todino, Grace. Using UUCP and USENET. Sebastopol, CA: O'Reilly and Associates, 1989.

Todino, Grace, and Tim O'Reilly. Managing UUCP and USENET. Sebastopol, CA: O'Reilly and Associates, 1989.

Anderson, Costales, Henderson. UNIX Communications. Corte Madera, CA: The Waite Group, 1988.

Thomas, Rebecca, and Rik Farrow. UNIX Administration Guide for System V. Englewood Cliffs, NJ: Prentice-Hall, 1989.

Farrow, Rik. UNIX System Security. Reading, MA: Addison-Wesley, 1991.

About the Author

Chris Hare is Ottawa Technical Services Manager for Choreo Systems, Inc. He has worked in the UNIX environment since 1986 and in 1988 became one of the first SCO authorized instructors in Canada. He teaches UNIX introductory, system administration, and programming classes. His current focus is on networking, Perl, and X. Chris can be reached at chare@choreo.ca, or chare@unilabs.org, which is his home.