Connecting to other computers with UUCP

How UUCP works

The UNIX system uses the HoneyDanBer implementation of UUCP. UUCP uses a batch method to manage communications traffic, storing (or ``spooling'') requests for later execution when actual contact is made between systems. When UUCP commands are executed, work files and any data files needed are created in /usr/spool/uucp and its subdirectories; these work and data files are described in ``The UUCP spool directory contents''. The program uucico scans these directories for the instructions contained in any work files and executes them. Although it is possible to execute commands immediately, most systems call other systems according to a daily schedule (usually during the evenings to reduce connection costs). There are three directories associated with UUCP:

/usr/spool/uucp: This is the working directory for UUCP. Work files, lock files, log files, and all UUCP communications traffic are stored here and in subdirectories.
/usr/spool/uucppublic: This is the publicly readable or writable target directory used for most file transfers. A tilde (~) can be used as an abbreviation for this directory in uucp commands (in csh it must be escaped: \~).
/usr/lib/uucp: Most of the UUCP programs are stored here, as well as the supporting database or control files. The main user programs, including uux and uucp, are found in /usr/bin.

The /usr/lib/uucp directory also contains configuration files for UUCP (distinguished by their capitalized names). The most important to understand are:

Configuration: contains information that establishes and configures the protocol used when transferring data to and from a remote computer. (This file is optional.)
Systems: contains information needed to establish a link to a remote computer, including the name of the connecting device associated with the remote computer, when the computer can be reached, telephone number, login sequence, and password.
Permissions: defines the access level granted to computers when they attempt to transfer files or remotely execute commands on your computer.
Devices: contains information concerning the port name, speed, and type of the Automatic Call Units (modems), direct links, and network devices.

The uucp traffic is managed by three daemons (supervisory programs) which run in the background, handling file transfers and command executions. (The daemons can also be executed manually as commands.)

uucico: selects the device used for the link, establishes the link to the remote computer, performs the required login sequence and permission checks, transfers data and executes files, logs results, and (if requested) notifies the user by mail of transfer completions. When the local uucico daemon calls a remote computer, it ``talks'' to the uucico daemon on the remote computer during the session.
uuxqt: performs remote program execution. uuxqt runs after the conversation between the uucico programs is completed. It searches the spool directory for execute files (X.files) that were sent from a remote computer. When an X.file file is found, uuxqt opens it to get the list of data files that are required for the execution. It then checks to see if the required data files are available and accessible. uuxqt also verifies that it has permission to execute the requested command.
uusched: schedules the queued work in the spool directory. Before starting the uucico daemon, uusched randomizes the order in which remote computers are called.

When you enter a UUCP command, the program creates a work file and (usually) a data file for the requested transfer. The work file contains information required for transferring the file. The data file is a copy of the specified source file. After these files are created in the spool directory, the uucico daemon is started.

The uucico daemon attempts to establish a connection to the remote computer. See ``A sample UUCP transaction'' for an example of a session.

When uucico logs in on the remote computer, the remote computer starts a uucico daemon. The two uucico daemons then negotiate the line protocol to be used in the file transfer. The local uucico daemon then transfers the file that you are sending to the remote computer. The remote uucico places the file in the specified pathname on the remote computer. After your local computer finishes sending files, the remote computer may take over and send queued files to your local computer.

If the remote computer or the device selected to make the connection to the remote computer is unavailable, the request remains queued in the spool directory. If set up to run by cron each hour, uudemon.hour starts the uusched daemon. When the uusched daemon starts, it searches the spool directory for the remaining work files, generates the random order in which these requests are to be processed, and then starts the transfer process (uucico) described in the previous paragraphs.

A sample UUCP transaction

The following steps trace the execution of a uucp command:

A user on a system called Kilgore wishes to send a copy of the file minutes.01.10 to a remote system called obie. To accomplish this, the user enters the following command:

uucp minutes.01.10 obie\!/usr/spool/uucppublic
Note that obie\!\~ would also work for the destination and the exclamation point need only be escaped (preceded by a ``\'') if the csh is used; the Bourne shell (sh) and Korn shell (ksh) do not require this.
A work file named C.obieNxxxx is created in the /usr/spool/uucp/obie directory, where xxxx is the job number.
The uusched daemon schedules the request for execution by uucico.
When the execution time is reached, uucico first checks the Systems file and confirms that obie is a recognized system and that a call is permitted at this time.
Using the information in the Systems file, uucico next locates the modem device and tty port associated with it as stored in the Devices file.
Using the phone number in the Systems file and the modem type from the Devices file, uucico uses the appropriate modem commands from the Dialers file (or runs a dialer program from the /usr/lib/uucp directory) to connect to the remote system.
uucico creates a lock file (LCK..tty1a) to lock the serial line, and a lock file (LCK..obie) to lock the called system in the directory /usr/spool/uucp.
uucico uses the login sequence and password defined in the Systems file to log in to obie, whose own uucico confirms that kilgore is recognized before beginning the actual transaction.
The calling system, kilgore, is said to be the ``guest''; the called system, obie, is said be the ``host''. The host uucico checks the local Permissions file to confirm that the guest is authorized to transfer the file.
The guest (kilgore) transmits the file in packets that are checked for errors and retransmitted if garbled. During reception, the file is stored in a temporary file (TM.xxxx) in the /usr/spool/uucp/kilgore directory on the host (obie). When the transfer is complete, the file is moved to the proper destination, in this case /usr/spool/uucppublic/minutes.01.10.
Each machine records its side of the transaction in log files. For example, obie would have recorded the exchange in /usr/spool/uucp/.Log/uucp/kilgore.
Unless the host system (obie) has requests of its own, a hangup request is sent, the connection is terminated, and the lock files are removed.

For remote command execution (using uux), an execute X.file is created in the /usr/spool/uucp directory. The uuxqt daemon scans this directory for work, checks the Permissions file to confirm permission to execute the command, then executes it. This takes place after the modems hang up and uucico exits.

How a UUCP transmission proceeds

A UUCP session consists of four parts: connection, an initial handshake that establishes the protocol to use, a series of file transfers, and a final handshake. All four parts produce different characteristic debugging output, and it is possible to deduce which element of the session is failing by scrutinizing the output.

When the connection stage begins, uucico scans the Systems file for the system to connect to. Using the device field for the specified system, it opens the Devices file and connects to the named device.

A single example session is documented in the following sections.

Stage 1: Connection

The command to invoke this session is uutry -x9 scolon, which sets the debugging level to 9 and makes uutry attempt to connect to system scolon. The beginning of the output shows uucico reading the Systems and Devices files in an attempt to set up a connection:

   01: mchFind called (scolon)
   02: list (rmail) num = 1
   03: name (scolon) not found; return FAIL
   04: list (rmail) num = 1
   05: name (OTHER) not found; return FAIL
   06: _Request (FALSE), _Switch (TRUE), _CallBack (FALSE), _MyName (), _Commands rmail
   07: chdir(/usr/spool/uucp/scolon)
   08: conn(scolon)
   09: Device Type ACU wanted
   10: mlock tty1A succeeded
   11: fixline(6, 2400)
   12: processdev: calling setdevcfg(uucico, ACU)
   13: gdial(hayes2400) called

Line 01 indicates that uucico is looking for scolon in Systems. The next six lines are internal debugging information from uucico: on line 08 it finds scolon and attempts to connect to it. From the Systems file uucico determines that it needs a device of type ACU. Checking the Devices file, uucico determines that tty1A is such a device (line 10) and takes it over (line 11), setting it to the speed stated in Devices.

Having obtained a suitable device, uucico invokes the dialer hayes2400 to place the call (line 13), and enters the connection script:

   14: expect: ("")
   15: got it
   16: sendthem (ATQ0E0T&D2&C1S0=0X4S2=043^M)
   17: expect: (OK^M)
   18: ^M^JOK^Mgot it
   19: sendthem (ATDT9222681^M)
   20: expect: (Speed)
   21: ^J^M^JCONNECT 2400got it
   22: getto ret 6
   23: expect: ("")
   24: got it
   25: sendthem (^M^M)
   26: expect: (ogin:)
   27: le /usr/spool/uucppublic/info contains a roadmap of ^J^Mthe bulletin board
   areas.^J^M^J^MWARNING: Unauthorized access will be prosecuted.^J^M^J^M^M^Jscolo
   n!login:got it
   28: sendthem (uusls^M)
   29: expect: (ssword:)
   30: ic/info contains a roadmap of ^J^Mthe bulletin board areas.^J^M^J^MWARNING:
   Unauthorized access will be prosecuted.^J^M^J^M^M^Jscolon!login: uusls^M^JPass
   word:got it
   31: sendthem (bbsuucp^M)
   32: ISTRIP cleared

First the dialer talks to the modem. The standard Hayes modem response to a successful command is to echo OK; line 16 shows the dialer sending an initialization string (specified in /usr/lib/uucp/Dialcodes, or programmed into the dialer binary) to the modem. (A Hayes ATDT command causes the modem to tone-dial the following number.) When the modem establishes a connection, the dialer waits for the modem to return the connection speed: in this case the standard message CONNECT 2400 indicating a 2400-baud link. (Faster modems may return CONNECT 9600 or CONNECT 14400.)

At this point, the dialer follows the login script given in Systems:

   scolon Any  ACU 2400-9600 0923 222681 "" \r ogin:-@-ogin:-@-ogin: uusls ssword:
   bbsuucp

First, a return is sent. Then, uucico waits for the string "ogin". This is received, and uucico sends "uusls", the appropriate login. (The remote host prints the text of /etc/issue, a message file used for remote logins. uucico ignores the message.) Finally, uucico sees the password prompt, sends a password, and clears the login sequence.

If you run a sample uutry session and encounter problems during this phase, then it is probably due to one of the following conditions:

Incorrect Systems configuration file. The host you are trying to contact is not in the Systems file, or its device type corresponds to no known device in the Devices file, or the login sequence is wrong.
Incorrect Devices configuration file. uucico cannot initialize a device suitable for connecting to the designated host.
Incorrect Dialers configuration file. (This is not normally needed for simple UUCP installations.)
Dialer timeout before connection. If you are using a high-speed modem (particularly one that supports multiple speeds and modes) it generates a series of tones to negotiate a connection at the highest possible protocol and baud rate. This may take so long that the dialer is not allowing sufficient time for the connection. The solution is to add dashes ``--'' to the end of the telephone number in Systems. A dash is interpreted as a pause of approximately two seconds; if your modem is taking four seconds to negotiate a connection, add two dashes to the end of the telephone number to prevent the dialer from timing out.
Incorrect hardware configuration or noisy line. A noisy line or badly configured modem can result in junk being received by uucico. In this case, uucico normally hangs up and uutry may attempt to repeat the connection later.
Incorrect serial line configuration. If uucico begins displaying garbage after obtaining a connection (for example, after receiving the login message from the remote host), then the serial line from the local host to the local modem is probably running at the wrong speed. A solution is to check the login script in System; if it contains -BREAK-, replace each instance of -BREAK- with -@-, this prevents the UUCP programs from cycling the serial port speed.

Stage 2: Initial handshake

Now that the dialer has established a connection, the uucico daemon on the local host starts to negotiate a protocol with the remote uucico.

The ^J^M character pairs appearing in the uutry output are carriage return and line feed pairs. In DOS, both characters are needed to indicate the end of a line: in the Macintosh system a ``^M'' indicates the end of a line: and in the UNIX system a ``^J'' indicates the end of a line. Many online services transmit both characters at the end of every line, in case a different type of system tries to connect and cannot recognize the local newline format. When reading the uutry output, a ^M^J character pair should therefore be taken as indicating a new line.

omsg in the uucico debugging output means that the local uucico outputs a message: imsg means that the local uucico reads a message.

uucico ignores the incoming text until it sees a ``^P'' (byte with octal value \020). All messages in the initial handshake begin with a ``^P'' and end with a null byte (represented in this listing as ``^@'').

The first packet is ^PShere=scolon^@. The Shere= message indicates the remote uucico is running on scolon.

Here is the protocol negotiation phase:

   CB + "protocol"
   33 : imsg >^M^JLast   successful login for uusls: Wed Aug 11 14:28:58 BST 1993
   on tty8C^M^JLast unsuccessful login for uusls: Tue Aug 10 19:41:17 BST 199ik3
   on tty8D^M^JSCO UNIX System V/386 Release 3.2^M^JCopyright (C) 1976-1989 UNIX
   System Laboratories, Inc.^M^JCopyright (C) 1980-1989 Microsoft Corporation^M^J
   Copyright (C) 1983-1996 The Santa Cruz Operation, Inc.^M^J All Rights Reserved
   ^M^Jscolon^M^J^PShere=scolon^@Login Successful: System=scolon
   34 : omsg "Sjocksco -Q0 -x9"
   35 : imsg >^PROK^@msg-ROK
   36 :  Rmtname scolon, Role MASTER,  Ifn - 6, Loginuser - root
   37 : rmesg - 'P' imsg >^PPgetxf^@got Pgetxf
   38 : wmesg 'U'g
   39 : omsg "Ug"
   40 : 	Protocol: g
   41 : 		g window size set to 7
   42 : 		g variable packets set to true
   43 : 		g packet size set to 64
   44 : 	Protocol: G
   45 : 		G window size set to 7
   46 : 		G packet size set to 512

After receiving the first packet, ^PShere=scolon^@, the originating host replies with an outgoing message:

   34 : omsg "Sjocksco -Q0 -x9"

The second message packet in any transaction is:

   ^PShostname -Qseqnum -xdebug^@

where hostname is the local hosts name, seqnum is the sequence number for this conversation, and debug is the debugging level in use.

The sequence number is stored at both sites, and is incremented each time a conversation takes place via UUCP. If they do not match up, it is likely that security has been broken (or a disk backup restored following a crash). This feature is not used by all UUCP implementations.

The third packet is an acknowledgement from the remote uucico (which sends ROK -- see below.) A number of different responses are possible at this stage; these may indicate various error conditions:

ROK: The calling UUCP is accepted; proceed to protocol negotiation.
RLCK: The called UUCP already has a lock file for the calling UUCP; the two machines are already communicating (or a lock file has not been removed).
RCB: The called UUCP will call back. (Used to avoid imposters.)
RBADSEQ: The call sequence number is wrong.
RLOGIN: The calling UUCP is using the wrong login.
Ryou are unknown to me: The calling UUCP is not listed in the recipient's Systems file, and the receiving system is not set up to accept anonymous UUCP connections.

If the connection is accepted, the remote system then sends a packet like ^PPgetxf^@. The ``P'' prefix indicates that the subsequent letters are the protocols supported by the remote system. In this case, the ``g'', ``e'', ``t'', ``x'', and ``f'' protocols are supported, in decreasing order of preference.

The local uucico reads /usr/lib/uucp/Configuration to obtain its own protocol setup, and sends a packet in response:

   38 : wmesg 'U'g

to indicate the protocol (in this case, ``g'') to be used. (uucico uses the first protocol it finds listed against the appropriate system or device in Configuration that it has in common with the protocols listed in the remote uucico's protocol string.)

The protocol is then established, and the rest of the UUCP debugging session consists of transfers.

Stage 3: File transfers

The debugging output from the file transfer stage is heavily dependent on the protocol being used to control the transfers. See ``Defining a communications protocol'' for a brief introduction to the protocols.

At all times during a session, one uucico daemon acts as a master, issuing commands, while the other is a slave, obeying orders. Initially, the calling UUCP is master, although the roles may change during the session. If a protocol error occurs while commands are being exchanged, both uucico's switch immediately to the final handshake.

The following commands can be sent by a master:

H

A request to hang up the connection. The slave responds with one of:

HY: The slave agrees to hang up.
HN: The slave disagrees. Master and slave exchange roles, and the new master may begin to issue commands.

R

A request by the master to receive a file from the slave. (Additional arguments are possible.)

S

A request by the master to send a file to the slave. (Additional arguments are possible.)

X

A request by the master to execute uucp on the slave. This command requires additional arguments. It is used when forwarding a file through intermediate hosts.

In the listing below, line 59 indicates that the ``g'' protocol is started (lines 47 to 58 are the internal ``g'' protocol startup sequence). No files are queued for transfer on either host, so after a brief exchange the master issues an HY command on line 76 (which is seen being sent on line 79), and the UUCP session moves to the closing handshake.

   47 :	send 77
   48 :	pkgetpack: Connodata=1
   49 :	rec h->cntl 73
   50 :	send 61
   51 :	state - [INIT code a] (1)
   52 :	pkgetpack: Connodata=2
   53 :	rec h->cntl 61
   54 :	send 57
   55 :	state - [INIT code a]&[INIT code b] (3)
   56 :	pkgetpack: Connodata=3
   57 :	rec h->cntl 53
   58 :	state - [O.K.] (10)
   59 :	Proto started g
   60 :	*** TOP ***  -  role=1, setline - X
   61 :	gtwvec: dir /usr/spool/uucp/scolon
   62 :	wmesg 'H'
   63 :	pkwrite: icount = 64
   64 :	send 37777777610
   65 :	send 64 byte packet.
   66 :	rmesg - 'H' pkgetpack: Connodata=4
   67 :	rec h->cntl 41
   68 :	pkcntl: RR/RJ: Connodata=0
   69 :	state - [O.K.] (10)
   70 :	pkgetpack: Connodata=1
   71 :	rec h->cntl 37777777611
   72 :	send 41
   73 :	got HY
   74 :	 PROCESS: msg - HY
   75 :	HUP:
   76 :	wmesg 'H'Y
   77 :	pkwrite: icount = 64
   78 :	send 37777777621
   79 :	send 64 byte packet.
   80 :	send 10
   81 :	send 10

Stage 4: Closing handshake

The closing handshake is used to confirm that the UUCP session has completed successfully. The calling uucico sends a packet of six zeros, and the remote host responds with a packet of seven zeros. (Line 86 is just a series of trailing nulls appended to the final response packet.)

   82 :	cntrl - 0
   83 :	omsg "OOOOOO"
   84 :	send OO 0,omsg "OOOOOO"
   85 :	imsg >^P^I^H*"^I^P^B!l^R]HY^@omsg "OOOOOO"
   86 :	imsg
   >^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@
   ^@^@^@^@^@^@^@^@^@^@exit code 0
   87 :	Conversation Complete: Status SUCCEEDED
   88 :	
   89 :	TM_cnt: 0

Different protocol debugging outputs

Different protocols produce different debugging output during the file transfer phase. The output in the preceding example uses the ``g'' protocol. The ``G'' protocol produces largely similar output, while the non-error correcting protocols (``e'', ``f'', ``x'') produce different output.

In general, the debugging output from uucico once a protocol has been negotiated consists of a list of packets sent, and any errors or resend attempts made. The ``g'' and ``G'' protocols are particularly verbose: the other protocols tend to be less informative.