Copyright (c) 1986, 1993
The Regents of the University of California. All rights reserved.

%sccs.include.proprietary.roff%

@(#)implement.ms 8.2 (Berkeley) 06/01/94

Installation and Operation of \*(UU

4.4BSD Edition .AU D. A. Nowitz .AI AT&T Bell Laboratories Murray Hill, New Jersey 07974 .AU Carl S. Gutekunst .AI Communications Software Research and Development Pyramid Technology Corporation Mountain View, California 94039 .AB \*(Uu is a series of programs designed to permit communication between X systems using a variety of communications links. \*(Uu provides batched, error free file transfers and remote command execution. It is well suited for tasks such as electronic mail, public news networks, and software distribution, particularly when only slow, low-cost communication links are available (e.g., 1200 baud dial-up).

This document describes the 4.3BSD version of \*(Uu. This is a distant but direct descendent of the ``second implementation'' of \*(Uu developed by D. A. Nowitz at AT&T Bell Laboratories. A number of other \*(Uu versions are in common usage; these are discussed only to the extent that they affect administration of 4.3BSD systems.

Revised August 24, 1986 .AE

.OH 'Installation and Operation of UUCP''SMM:14-%' .EH 'SMM:14-%''Installation and Operation of UUCP'

\*(UU OVERVIEW

\*(Uu is a batch-type operation. Users issue commands that are queued in a spool directory for processing by background daemons.

Uucp (UNIX-to-UNIX Copy) and uux (UNIX-to-UNIX Execution) provide the user interface to \*(Uu. Uucp has syntax and semantics similar to the standard X utility cp(1), with the added ability to prefix filenames with system names. Similarly, uux mimics the conventions of sh(1), and allows commands to be prefixed with system names.

Uucico (Copy-In, Copy-Out) is the primary \*(Uu daemon. It processes the requests queued by uucp and uux, initiates calls to remote systems, transfers files, and forks other daemons to execute uux-requested commands. Uucico also acts as the \*(Uu ``shell'' when remote systems call in to requests transfers.

Three types of files are used in \*(Uu operation. Control files describe the \*(Uu environment, including known remote hosts, available devices, and remote file access permissions. Control files are relatively static; they are generally changed only by the system administrator. Spool files (also called Queue files) contain transfer requests and data; they are created and deleted as necessary by uucp, uux, and uucico. Log files accumulate a history of \*(Uu activity; these tend to grow forever if not periodically cleaned up.

Spool files are further divided into three types: Work files contain directions for file transfers between systems. Every invocation of uucp or uux creates one or more work files. Data files contain data for transfer to or from remote systems. Execution files contain directions for X command executions which involve the resources of one or more systems. Execution files are created only by uux. ===========================================================================
SECTION 2: USER UTILITIES
===========================================================================

USER UTILITIES

\*(Uu includes a total of ten ``primary'' utilities, that is, ten utilities for general users. All reside in the /usr/bin directory, where they are easily accessible. This section provides detailed implementation descriptions for the more important commands; see the corresponding man pages for additional information.

The following two commands queue transfer requests:

The following four commands provide \*(Uu status information:

The following four commands provide miscellaneous support services:

===========================================================================
Uucp - UNIX to UNIX File Copy

The uucp command is the user's primary interface with the system. The uucp command was designed to look like cp to the user. The syntax is

uucp [ option ] ... source ... destination

where the source and destination may contain the prefix system-name! which indicates the system on which the file or files reside or where they will be copied.

The options interpreted by uucp are:

The destination may be a directory name, in which case the file name is taken from the last part of the source's name. The source name may contain special shell characters such as ``?*[]''; these and other shell characters such as ``!<>'' will need to be quoted or escaped. If a source argument has a system-name! prefix for a remote system, the file name expansion will be done on the remote system.

The command

uucp *.c usg!/usr/dan

will set up the transfer of all files whose names end with ``.c'' to the ``/usr/dan'' directory on the ``usg'' machine.

The source and/or destination names may also contain a ~user prefix. This translates to the login directory on the specified system. A lone ~ prefix is expanded to the name of the specified system's public access directory, usually /usr/spool/uucppublic. For names with partial path-names, the current directory is prepended to the file name. File names with ../ are not permitted.

The command

uucp usg!~dan/*.h ~dan

will set up the transfer of files whose names end with ``.h'' in dan's login directory on system ``usg'' to dan's local login directory.

For each source file, the program will check the source and destination file-names and the system-part of each to classify the work into one of five types:

After the work has been set up in the spool directories, the \*(Uu daemon uucico is started to try to contact the other machine to execute the work (unless the -r option was specified).

Type 1

Uucp makes a copy of the file. The -m option is not honored in this case.

Type 2

A one line "work file" is created for each file requested and put in the C. spool directory with the following fields, each separated by a blank. (All "work files" and "execute files" use a blank as the field separator.)

.KS Type 3

For each source file, a "work file" is created. A -C option on the uucp command will cause the "data file" to be copied into the spool directory and the file to be transmitted from the copy; the copy is deleted when the transfer completes. The fields of each entry are given below.

.KE Type 4 and Type 5

Uucp generates a uucp command and sends it to the remote machine; the remote uucico executes the uucp command. ===========================================================================
Uux - UNIX To UNIX Execution

The uux command is used to set up the execution of a X command where the execution machine and/or some of the files are remote. The syntax of the uux command is

uux [ - "] [" option ] ... command-string

where the command-string is made up of one or more arguments. All special shell characters such as ``<>|*?!'' must be quoted either by quoting the entire command-string or quoting the character as a separate argument. Within the command-string, the command and file names may contain a system-name! prefix. All arguments which do not contain a ``!'' will not be treated as files. (They will not be copied to the execution machine.) The `-' is used to indicate that the standard input for command-string should be inherited from the standard input of the uux command.

The options, used mostly for debugging and by other programs, are:

The command

pr abc | uux - usg!lpr

will set up the output of ``pr abc'' as standard input to an lpr command to be executed on system ``usg''.

Uux generates an "execute file" which contains the names of the files required for execution (including standard input), the user's login name, the destination of the standard output, and the command to be executed. This file is either put in the X. spool directory for local execution, or in the D.hostnameX directory for transfer to the remote system.

For required files which are not on the execution machine, uux will generate receive command files (type 2 above). These command-files will be put on the execution machine and executed by uucico. (This will work only if the local system has permission to put files in the remote spool directory as controlled by the remote USERFILE.)

The "execute file" will be processed by the uuxqt(8C) program on the execution machine. It is made up of several lines, each of which contains an identification character and one or more arguments. The order of the lines in the file is not relevant and some of the lines may not be present. Each line is described below.

===========================================================================
SECTION 3: SYSTEM UTILITIES
===========================================================================
SYSTEM AND ADMINISTRATIVE UTILITIES

\*(Uu includes four system utilities; these are not normally referenced by users. All except uucpd reside in the \*(Uu administrative directory, /usr/lib/uucp. These include:

===========================================================================
Uucico - Copy In, Copy Out (\*(Uu Daemon)

Uucico is the ``heart'' of the \*(Uu system. The program performs the following major functions:

Uucico may be started in several ways;

When started by method a, b or c, the program is considered to be in MASTER mode. In this mode, a connection will be made to a remote system. If started by a remote system (method d), the program is considered to be in SLAVE mode.

The MASTER mode will operate in one of two ways. If no system name is specified (-s option not specified) the program will scan the spool directory for systems to call. If a system name is specified, that system will be called, and work will only be done for that system.

The uucico program is generally started by another program. There are several options used for execution:

The next part of this section will describe the major steps within the uucico program.

Scan For Work

The names of the work related files in a spool subdirectory have format

type . system-name grade number

where:

Type is an upper case letter, ( C - work (copy command) file, D - data file, X - execute file); System-name is the remote system; Grade is a character in the range [0-9][A-Z][a-z]; Number is a four digit, padded sequence number.

The file

C.res45n0031

would be a "work file" for a file transfer between the local machine and the ``res45'' machine.

The scan for work is done by looking through the appropriate spool directory for work files (files with prefix C.). A list is made of all systems to be called. Uucico will then call each system and process all "work files" .

Call Remote System

The call is made using information from the control files that reside in the /usr/lib/uucp directory. At the start of the call process, a lock is set to forbid multiple conversations between the same two systems.

The system name is found in the L.sys control file. The information contained for each system is;

The time field is checked against the present time to see if the call should be made.

The phone number .R may contain abbreviations (e.g. mh, py, boston) which get translated into dial sequences using the L-dialcodes file.

The L-devices file is scanned using fields [3] and [4] from the L.sys file to find an available device for the call. The program will try all devices which satisfy [3] and [4] until the call is made or no more devices can be tried. If a device is successfully opened, a lock file is created so that another copy of uucico will not try to use it. If the call is complete, the login information .R (field [6] of L.sys) is used to login.

The conversation between the two uucico programs begins with a handshake started by the called, SLAVE , system. The SLAVE sends a message to let the MASTER know it is ready to receive the system identification and conversation sequence number. The response from the MASTER is verified by the SLAVE and if acceptable, protocol selection begins. The SLAVE can also reply with a ``call-back required'' message in which case, the current conversation is terminated.

Line Protocol Selection

The remote system sends a message

Pproto-list

where proto-list is a string of characters, each representing a line protocol.

The calling program checks the proto-list for a letter corresponding to an available line protocol and returns a use-protocol message. The use-protocol message is

Ucode

where code is either a one character protocol letter or N which means there is no common protocol.

The following protocols are implemented in 4.3BSD \*(Uu:

Note: AT&T System VR2 \*(UU supports the x (X.25) and e (Error Free) protocols, which provide functionality similar to the 4.3BSD f and t protocols, respectively. They are incompatible, however. Thus when attempting to connect two systems via X.25 or an local area network, it is not adequate for both systems to simply ``support X.25'' or ``support error free transfers.'' Both must support the same \*(Uu protocols.

Work Processing

The initial roles ( MASTER or SLAVE ) for the work processing are the mode in which each program starts. (The MASTER has been specified by the -r1 uucico option.) The MASTER program does a work search similar to the one used in the ``Scan For Work'' section.

There are five messages used during the work processing, each specified by the first character of the message. They are;

The MASTER will send R , S or X messages until all work from the spool directory is complete, at which point an H message will be sent. The SLAVE will reply with SY, SN, RY, RN, HY, HN, XY, XN, corresponding to yes or no for each request.

The send and receive replies are based on permission to access the requested file/directory using USERFILE and read/write permissions of the file/directory. After each file is copied into the spool directory of the receiving system, a copy-complete message is sent by the receiver of the file. The message CY will be sent if the file has successfully been moved from the temporary spool file to the actual destination. Otherwise, a CN message is sent. (In the case of CN , the transferred file will be in the TM. spool subdirectory.) The requests and results are logged on both systems.

The hangup response is determined by the SLAVE program by a work scan of its spool directory. If work for the MASTER\|'s system exists in the SLAVE\|'s spool directory, an HN message is sent and the programs switch roles. If no work exists, an HY response is sent.

Conversation Termination

When a HY message is received by the MASTER it is echoed back to the SLAVE and the protocols are turned off. Each program sends a final ``OO'' message to the other. The original SLAVE program will clean up and terminate. The MASTER will proceed to call other systems and process work as long as possible or terminate if a -s option was specified.

===========================================================================
Uuxqt - Uucp Command Execution

The uuxqt program is used to execute execute files .R generated by uux. The uuxqt program may be started by either the uucico or uux programs. The program scans the X. spool directory for execute files. Each one is checked to see if all the required files are available and if so, the command line or send line is executed.

The execute file .R is described in the uux section above.

Command Execution

The execution is accomplished by executing a sh -c .R of the command line after appropriate standard input and standard output have been opened. If a standard output is specified, the program will create a send command or copy the output file as appropriate. ===========================================================================
Uuclean - Uucp Spool Directory Cleanup

This program is typically started by the cron(8) daemon, once a day. Its function is to remove files from the spool directories which are more than 3 days old. These are usually files for work which can not be completed.

The options available are:

===========================================================================
SECTION 4: CONTROL FILES
===========================================================================
SYSTEM CONTROL FILES

Seven Control Files are referenced by the \*(Uu utilities. All live in the \*(Uu administrative directory, /usr/lib/uucp. These are ASCII files, and can be modified using standard text editors such as vi and ex. Lines beginning with a `#' character are comments; lines ending with a `\e' are continued on the next input line.

A general description of each file follows; see the man pages for complete information. Examples of the six standard files are included in the distribution in the /usr/lib/uucp/UUAIDS directory. L-devices - \*(UU Devices File

This file declares all devices that are available to uucico for calling out. The special device files are assumed to be in the /dev directory. The format for each entry is

caller line call-unit class dialer [chat....]

where;

The line

ACU tty47 unused 1200 hayes

would be set up for a system which had device tty47 wired to a Hayes ``Smartmodem 1200'' for use at 1200 baud. L-dialcodes - Phone Number Prefix File

This file contains entries with location abbreviations used in the L.sys file (e.g. py, mh, boston). The entry format is

abb dial-seq

where;

The line

py 165-

would be set up so that entry py7777 would send 165-7777 to the dial-unit. L.aliases - Hostname Aliases File

This file defines mapping (aliasing) of remote host names. This is intended for compensating for systems that have changed names, or do not provide their entire machine name (like most USG systems). It is also useful when a machine's name is not obvious or commonly misspelled.

Each line is of the form

real-name alias-name

where real-name is the full, correct name for the host, and alias-name is the old or truncated name. L.sys - \*(Uu Systems File

Each entry in this file represents one system which can be called by the local uucp programs. The format for each entry is

system times caller class device/phone-number [login]

where;

A typical entry in the L.sys file would be

sys Any ACU 1200 mh7654 login:--login: uucp ssword: word

The expect algorithm looks at the last part of the string as illustrated in the password field. L.cmds - Commands Permissions File

This file contains a list of commands, one per line, that are permitted for remote execution via uux. This list should be chosen with great care, since commands that take filenames as arguments will allow users to easily circumvent \*(Uu's security. For most sites, L.cmds should only include the lines: rmail ruusend SQFILE - Sequence Check File (Optional)

This file contains an entry for each remote system with which this site agrees to perform conversation sequence checks. The initial entry is just the system name of the remote system. The first conversation will add two items to the line, the conversation count, and the date/time of the most resent conversation. These items will be updated with each conversation. If a sequence check fails, which could indicate that an unauthorized connection has been attempted, the entry will have to be adjusted.

This facility is technically no longer supported in 4.3BSD \*(Uu, since it was hardly ever used and consumed precious memory space on PDP-11 systems. The compile-time #define GNXSEQ can be set to enable sequence checking should it be needed. USERFILE - Pathnames Permissions File

This file contains user accessibility information. It specifies four types of constraint;

Each line in the file has the following format

login,sys [ c ] path-name [ path-name ] ...

where;

The constraints are implemented as follows.

The line

u,m /usr/xyz

allows machine m to login with name u and request the transfer of files whose names start with ``/usr/xyz''.

The line

dan, /usr/dan

allows the ordinary user dan to issue commands for files whose name starts with ``/usr/dan''.

The lines

u,m /usr/xyz /usr/spool

u, /usr/spool

allows any remote machine to login with name u , but if its system name is not m , it can only ask to transfer files whose names start with ``/usr/spool''.

The lines

root, /

, /usr

allows any user to transfer files beginning with ``/usr'' but the user with login root can transfer any file.

===========================================================================
SECTION 5: SPOOL FILES
===========================================================================

SPOOL FILES

Spool Files contain \*(Uu transfer requests and data. Most have been described in detail earlier in this document.

All spool files live in the /usr/spool/uucp directory tree. To keep the spool directory from becoming hopelessly cluttered, each type of spool file is kept in its own subdirectory. The name of the directory is the same as the common prefix of the filename. For example, work files (files beginning with C.) are kept in the C. directory; execute files (which begin with X.) are kept in the X. directory, and so on.

A total of ten spool subdirectories are used, one of which is optional:

The following sections describe only those spool files that were not discussed earlier. LCK - lock files

Lock files are created for each device in use (except for TCP/IP sockets) and each system conversing. This prevents duplicate conversations and multiple attempts to use the same devices. The form of the lock file name is

LCK..str

where str is either a device or system name. The files may be left in the spool directory if uucico aborts. They will be ignored (reused) after 90 minutes. When runs abort and calls are desired before the time limit expires, the lock files should be removed. If the LCK. subdirectory is used, it's access mode can be set to 777, thus allowing normal users to remove dead lock files when necessary. STST - system status files

These files are created in the STST subdirectory by uucico. They contain information of failures such as login, dialup, or sequence check, and will contain a TALKING, RECEIVING, or SENDING status when two machines are conversing. The file name is STST/system, where system is the host name of the remote machine.

For ordinary failures (dialup, login), the file indicates the time of the last failure; this allows uucico to avoid retrying the failed call too soon. For sequence check failures, the file must be removed before any future attempts to converse with that remote system.

If the file is left due to an aborted run, it may contain a TALKING status. In this case, the file must be removed before a conversation is attempted. The easiest way to do this is to use the uupoll command to force uucico to start up. TM - temporary data files

These files are created in the /usr/spool/uucp/TM. directory while files are being copied from a remote machine. Their names have the form

TM.pid.ddd

where pid is a process-id and ddd is a sequential three digit number starting at zero for each invocation of uucico and incremented for each file received. After the entire remote file is received, the TM file is moved to the requested destination, often the X. or D. directory. If processing is abnormally terminated or the move fails, the file will remain in the TM. directory.

The stranded files should be periodically removed; the uuclean program is useful in this regard. The command

uuclean -d/usr/spool/uucp/TM. -pTM.

will remove all TM files older than three days. ===========================================================================
SECTION 6: LOG FILES
===========================================================================

LOG FILES

The following files provide a history of \*(Uu activities. All live in the spool directory, /usr/spool/uucp. They grow forever, and must be periodically trimmed or deleted; this is usually done weekly (or daily) via cron.

Optionally, one LOGFILE per site may be maintained in the LOG subdirectory. This option can be selected at \*(Uu compile time via the LOGBYSITE #define in uucp.h. ===========================================================================
SECTION 7: ADMINSTRATION AND SYSTEM SECURITY
===========================================================================

ADMINISTRATION AND SYSTEM SECURITY X System Files /etc/passwd

\*(Uu requires a login in /etc/passwd; at its simplest the entry would be uucp::66:1:UNIX-to-UNIX Copy:/usr/spool/uucppublic:/usr/lib/uucp/uucico

This user should own all the \*(Uu files and utilities. Remote sites wishing to call in for \*(Uu transfers would login to uucp (with the correct password, if any), and get uucico as their ``shell.'' Since uucico would be called without any options, it would run in SLAVE mode, thus responding correctly to the remote system, which would be in MASTER mode.

The directory /usr/spool/uucppublic should be created with 777 access modes, owned by uucp. In addition to serving as the home directory for \*(Uu remote logins, uucppublic provides a ``public-access'' directory where any user can read, write, or transfer files.

There are a number of security problems with using a single login, not the least of which is that superuser permission would be necessary to edit the control files. A better arrangement would be: uucp::66:1:UUCP Administrator:/usr/lib/uucp: nuucp::67:1:UNIX-to-UNIX Copy:/usr/spool/uucppublic:/usr/lib/uucp/uucico This provides one login for the \*(Uu administrator (which must be kept secure!) and a second for remote machines to use for login. A still more elaborate setup would use a separate login for each remote site, and possibly provide the administrator with a choice of shells: uucp::66:1:UUCP Administrator:/usr/lib/uucp: UUCP::66:1:UUCP Administrator:/usr/lib/uucp:/bin/csh Uhosta::6001:1:UNIX-to-UNIX Copy:/usr/spool/uucppublic:/usr/lib/uucp/uucico Uhostb::6002:1:UNIX-to-UNIX Copy:/usr/spool/uucppublic:/usr/lib/uucp/uucico Uhostc::6003:1:UNIX-to-UNIX Copy:/usr/spool/uucppublic:/usr/lib/uucp/uucico

It is assumed that the login name used by a remote computer to dial in is not the same as the login name of a normal user of the machine. However, several remote computers may employ the same login name.

Note that uucppublic is not used as the home directory for uucp when it logs into a regular shell. This would be an extreme security hazard, since anyone could slip a ``Trojan horse'' into a .profile or .cshrc file, which would be automatically executed when the \*(Uu administrator logged in.

/etc/rc

The system startup file, /etc/rc, should clean up any stray lock files with the line

rm -f /usr/spool/uucp/LCK.*

or, if the LCK subdirectory is being used,

rm -f /usr/spool/uucp/LCK/LCK.* /etc/services

If \*(Uu is to be used over TCP/IP links, then an entry for \*(Uu's port number should be added to /etc/services:

uucp 540/tcp uucpd # UUCP TCP/IP ===========================================================================
Shell Scripts For Periodic Cleanup

The \*(Uu system has a fairly large number of activities that must occur periodically. These include starting uucico to process queued requests, running uuclean to remove old spool files, and shuffling the boundlessly-growing log files. Some sites will also want to poll other sites periodically.

While it's possible to put all the necessary commands into cron's control file /usr/lib/crontab, this would be extremely awkward. The usual technique is to use three separate shells scripts, one each for hourly, daily, and weekly operations. Examples are provided in the UUAIDS directory; the following sections provide some specific recommendations.

Hourly

Activities that should occur hourly include:

Daily

The daily script should be started by cron in the wee hours, around 4 a.m. Activities that should occur daily include:

Weekly

Small sites with very little traffic may chose to shuffle the log files once per week, instead of once per day. The weekly script should, like the daily script, be run early in the morning. ===========================================================================
Connecting new systems

When first connecting a new machine to a \*(Uu network, it is useful to try and establish a connection with tip or cu first. The \*(Uu administrator will quickly become aware of any special facilities that are going to be required, for example: What lines and modems are to be used? Is the connection through different hardware and carriers? Does the remote system care about parity? What speed lines are being used and do they cycle through several speeds? Is there a line switch front end that will require special login dialogue in L.sys?

Once a successful login is achieved ``by hand,'' the administrator should have enough information to allow the correct setup of the control files in /usr/lib/uucp.

The \*(Uu administrator should then negotiate with the remote site's \*(Uu administrator as to who (if anyone) will do polling and when. Both administrators must set up the relevant accounts and passwords. The local administrator should decide on what permissions and security precautions are to be observed. Testing time and facilities will need to be arranged to complete initial connection testing between the systems. ============================================================================
Miscellaneous Security Issues

The \*(Uu system, left unrestricted, will let any outside user execute any commands and copy any files that are accessible to the uucp login user. It is up to the individual sites to be aware of this and apply the protections that they feel are necessary.

There are several security features available aside from the normal file mode protections. These must be set up by the installer of the \*(Uu system.

The login for uucp does not get a standard shell. Instead, uucico is started. Therefore, the only work that can be done is through uucico . A path check is done on file names that are to be sent or received. USERFILE supplies the information for these checks. USERFILE can also be set up to require call-back for certain login-ids. (See the description of USERFILE above.) A conversation sequence count can be set up so that the called system can be more confident that the caller is who he says he is. Uuxqt is restricted via the L.cmds file to a small list of commands that it will execute. A ``PATH'' shell statement is prepended to the command line as specified in the L.cmds file. The administrator may modify the list or remove the restrictions as desired. All the \*(Uu utilities except uudecode, uuencode, and uusend should be owned by the uucp login with the ``setuid'' bit set and only execute permissions (e.g. mode 04111). This will prevent outsiders from modifying the programs to get at a standard shell with a uucp login. Optionally, the utilities may belong to group daemon and be given ``setgid'' permissions (mode 06111). Uuxqt should only permit other \*(Uu programs to execute it; its mode should be 04100 or 06110. The control files L.sys, USERFILE, and SQFILE contain highly sensitive information. They should be owned by the uucp login, with read and write permission granted only to the owner (mode 0600). ===========================================================================
SECTION 7: UUCP SOURCE INSTALLATION
===========================================================================
INSTALLING THE \*(UU SYSTEM

The source for the \*(UU system resides in the /usr/src/usr.bin/uucp directory. The README file includes complete instructions on how to rebuild the \*(Uu system from source.

For most environments, only two files will need to be modified: uucp.h includes a large number of tunable system-dependent parameters, including operating system type, devices to be supported, and a variety of optional features. The Makefile may also have to be modified, particularly if you chose to keep certain files in different directories from usual. ===========================================================================
SECTION 8: ACKNOWLEDGMENTS
===========================================================================

ACKNOWLEDGEMENTS

4.3BSD UUCP was a group development effort, involving the contributed work of over one hundred members of the USENET community. We're extremely grateful to them all.

Special thanks go to the following individuals, whose contributions were especially valuable:

Thanks again to everyone who contributed. Berkeley UUCP continues to be a product of its own users, and would not exist as it does today without them.