UUCP "G" PROTOCOL Session UN047 Fall 1990 DECUS Symposium Las Vegas, Nevada Tuesday, 4pm-5pm Pavilion 2, Las Vegas Hilton Jamie E. Hanrahan Chair, VMSnet (DECUS uucp) and Internals Working Groups DECUS VAX Systems SIG Simpact Associates 9210 Sky Park Court San Diego, CA 92123 +1 619-565-1865 x1116 jeh@dcs.simpact.com jeh@crash.cts.com {decwrl,scubed,crash,nosc}!simpact!jeh UUCP "G" PROTOCOL Page 2 UN047, Tuesday, 4-5 pm 1 INITIAL HANDSHAKE ("SHERE EXCHANGE") o Occurs after call placement and login o Initiated by answering system o All messages begin with \020 (ctrl-P, also known as DLE) and end with \000 (NUL) o Sent and received in "raw mode" (no carriage returns, line feeds, etc.) ______________________________________________________________ Caller Answerer ------> <-------- (places call, gets carrier, gets login prompt, logs in) (uucico program starts) ________ \020Shere=hostname\000 ________ \020Shostname\000 \020ROK\000 ______________________________________________________________ ________ o hostname's are the respective systems' uucp host names. ________ o Caller's Shostname message may include any or all of the following optional elements: ________ ___ ___ _____ _____ Shostname -Qseq -xdbg -pgrade -vgrade=grade ___ - seq = call sequence number (or 0) ___ - dbg is a digit, answerer sets its debug level accordingly _____ - grade indicates what class of files are being transferred (e.g. mail, news, arbitrary files). Taken from systems file entry; not sent or supported by all systems. Some implementations support -p, some support -v, some both, some neither. (See discussion of "C." files later on) ________ o Old answerers may send just Shere instead of Shere=hostname . The "ROK" message says that the answerer has accepted the call. Instead, the answerer may reject the call with any of the following messages: o RLCK - answerer thinks it's already talking to that caller o RCB - answerer wants to call the caller back (to avoid imposter callers) UUCP "G" PROTOCOL Page 3 UN047, Tuesday, 4-5 pm o RBADSEQ - call sequence number is wrong (caller is an imposter, or more likely, sequence numbers weren't updated properly at one end or the other) o RLOGIN - caller's login name (username) isn't known to answerer's uucp (USERFILE or Permissions file) o RYou are unknown to me - (yes, it really does send all of that) caller's hostname isn't known to answerer (as determined by L.sys or Systems file) If caller receives any of these, it simply hangs up. (The answerer hangs up after sending the reject message, possibly waiting a few seconds so that the modem disconnect won't prevent the message from reaching the caller.) If answerer "accepts the call": ______________________________________________________________ Caller Answerer ------> <-------- ________ Pprotlist ____ Uprot ______________________________________________________________ where ________ o protlist is a list of the protocols (each identified by a single letter, e.g. "g") supported by the answerer ____ ________ o prot is a single protocol from protlist selected by the answerer o Caller can send UN (and then hang up) if it supports no protocols in common with answerer At this point the two machines have agreed on a protocol. We'll assume that it's the "g" protocol, so that the last two messages may have been something like ______________________________________________________________ Caller Answerer ------> <-------- Pfgt Ug ______________________________________________________________ At this point both systems call the gturnon() function, which causes the g data link protocol to start up. UUCP "G" PROTOCOL Page 4 UN047, Tuesday, 4-5 pm 2 G PROTOCOL PACKET FORMATS All subsequent communication (until after the G protocol shutdown) is in "packet mode". o Each packet has a six-byte header ____ o Control packets have only a header o Data packets have a header and a data segment 2.1 Packet Header Format +-------+-------+-------+-------+-------+-------+ | DLE | K | cklo | ckhi | ctl | XOR | +-------+-------+-------+-------+-------+-------+ ______ The first byte is always DLE (octal 020, hex 10). The second byte is the "K-byte". For a control packet it is always 9 (ie a tab character). For data packets it indicates the transmitted (physical) length of the following data segment, as follows: K-byte value data seg. len. (bytes) ------------ ---------------------- 1 32 2 64 3 128 4 256 5 512 6 1024 7 2048 8 4096 9 control packet The third and fourth bytes are the low and high bytes, respectively, of a checksum computed on the data segment (if any) plus the control byte. (The checksum computation is described later.) The fifth byte is a bitmapped command byte, described in the next section. The last byte is a simple XOR of the middle four bytes. The first and last bytes perform a framing and validation function for headers. 2.2 The Control Byte The "control" byte is bit-mapped as follows: 7 6 5 4 3 2 1 0 +-------+-----------+-----------+ | T T | X X X | Y Y Y | +-------+-----------+-----------+ UUCP "G" PROTOCOL Page 5 UN047, Tuesday, 4-5 pm The T field denotes the type of packet: T value packet type ------- ------------------------------------------ 0 control packet 1 alternate channel data packet (unused in uucp) 2 long data block 3 short data block (to be described later) The interpretations of the X and Y fields vary with the packet type (control vs. data). For control packets the X field is the type of control packet and the Y field is a parameter, as follows: X value name Y field interpretation ------- ------ --------------------------------------- 1 CLOSE no significance 2 NAK last correctly received packet number 3 SRJ packet number to retransmit 4 ACK last correctly received packet number 5 INITC max window size to use 6 INITB max data segment size to use 7 INITA max window size to use o The "data segment size" on the INITB packet is encoded like the KBYTE but with numbers one lower; e.g. an INITB packet with a Y field of 1 indicates a data segment size of 64 bytes. o Most descriptions of uucp refer to types 2 and 4 as "RJ" (reject) and "RR" (receiver ready), respectively. o SRJ ("selective reject") is not used in known implementations. 2.3 Data Packets For data packets, the X field is the sequence number of the packet, and the Y field is the "ACK number" -- the sequence number of the last packet correctly received by the system sending the data packet. (See the section on data transfer and acknowledgement.) A data packet header is always followed by a data segment of size indicated by the Kbyte. 2.3.1 Long Data Packets If the packet type is "long data", all 'n' bytes of the data segment (where 'n' is denoted by the Kbyte) contain data. UUCP "G" PROTOCOL Page 6 UN047, Tuesday, 4-5 pm 2.3.2 Short Data Packets If the packet type is "short data", the data segment is still sent in __________ its entirety, but the first one or two bytes indicate the difference between its physical (transmitted) length and the number of bytes to be passed to the presentation level (its "logical length"): 7 6 5 4 3 2 1 0 +---+---------------------------+ | 0 | length difference (1-127) | +---+---------------------------+ or, if the difference is too large to fit in seven bits, 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 +---+---------------------------+-------------------------------+ | 1 | length difference(lo bits)| length difference (high bits) | +---+---------------------------+-------------------------------+ first byte of data segment second byte of data segment For example, a data packet with a physical segment size of 64 (Kbyte=2), but an effective (logical) length of zero, would be sent by sending a "short data" packet where the data segment consisted of a byte with the numeric value 64, e.g. 7 6 5 4 3 2 1 0 +---+---------------------------+ | 0 | 1 0 0 0 0 0 0 | +---+---------------------------+ followed by 63 additional bytes (whose contents would be ignored by the receiver). 3 G PROTOCOL ("DATA LINK LAYER") INITIALIZATION G protocol is initialized via an exchange of the INITA, INITB, and INITC packets. A simple approach: o Each system starts sending INITA's to the other o Upon receiving an INITA, send an INITB o Upon receiving an INITB, send an INITC o When both have sent and received an INITC, initialization is complete When the INITx packets are received each system sets its uucp parameters _______ (data segment size and maximum transmit window size) to the smaller of what it can handle and what it gets from the packet. UUCP "G" PROTOCOL Page 7 UN047, Tuesday, 4-5 pm 4 G PROTOCOL DATA TRANSFER AND ACKNOWLEDGEMENT After initialization, data packets are exchanged. Thus, all subsequent traffic consists of Shortdata, Longdata, ACK, and NAK packets (until the end of the session, when CLOSE packets are exchanged). ____________ o Each data packet must be acknowledged by the receiver. o Data packets can only be acknowledged in sequence. o If a data packet arrives corrupted (as determined via checksum), the receiver sends a NAK (requesting retransmission) or simply does not send an ACK, allowing the sender to time out awaiting an ACK (which has the same effect). o The first packet sent by each transmitter has sequence number one. Packet sequence numbers are modulo 8 (ie 0, 1, ..., 7, 0, ...) o Uucp (in most implementations) uses a transmit window size of more than 1 (typically 3, maximum 7 due to the three-bit packet sequence numbers) - After sending one data packet the sender need not wait for ______ an ACK before sending the next data packet, until window ____ size unACK'd packets have been sent - Colloquially this is known as a "windowed" protocol. (As opposed to stop-and-wait, e.g. most Kermit implementations) ______ ____ - After the transmit window is full (ie window size unACK'd packets have been sent), transmitter must wait for an ACK of (at least) the first packet in the transmit window before sending another packet _______ ______ ____ o g protocol's receive window size is 1 -- at any given time there is only one packet which is valid to be received. o An ACK provides the number of the last correctly-received packet, and implies that all earlier packet numbers have also been correctly received. Thus a single ACK may acknowledge multiple packets. o The "ACK number" -- the number of the most recent correctly- received message -- also appears in the Y field of the headers of data packets. If a system is about to acknowledge a packet, but happens to have a data packet to send, it need not send an explicit ACK; putting the number of the packet to be ACK'd in the Y field of the data packet is sufficient. This doesn't happen often, because uucp's "upper layers" don't use the link in both directions at once. ___ ____ ______ o A NAK provides the same number as an ACK but requests retransmission of all outstanding packets with higher (modulo 8) numbers. UUCP "G" PROTOCOL Page 8 UN047, Tuesday, 4-5 pm o Both ACKs and NAKs provide acknowledgement for not only the indicated packet but also all previous packets in the transmit window ("stacked ACKs"). This is known as a "go back n" protocol. It is relatively easy to implement but performance suffers when errors occur. More complex protocols allow a receive window size of greater than one with "selective reject", and this was in fact the intent of the SRJ control packet. An SRJ says "retransmit this one packet, I didn't get it right". This avoids having to resend an entire transmit window to correct an error in just one packet. UUCP "G" PROTOCOL Page 9 UN047, Tuesday, 4-5 pm 4.1 A Simple Data Exchange ______________________________________________________________ Sender Receiver ------> <-------- Data 1 (receives Data 1 ok) Ack 1 Data 2 (receives Data 2 ok) Ack 2 (receives Ack 1) Data 3 (receives Data 3 ok) Ack 3 (receives Ack 2) Data 4 (receives Data 4 in error) NAK 3 (receives Ack 3) Data 5 (receives Data 5 ok but out of seq.) (receives NAK 3) (resends everything in window) Data 4 Data 5 (receives Data 4 ok) Ack 4 Data 6 (receives Data 5 ok) Ack 5 (receives Ack 4) Data 7 etc... ______________________________________________________________ 4.2 Data Link Layer: Interesting Cases, Implementation Notes, And War Stories 4.2.1 Corrupted Packet Headers When looking for a packet, the receiver should scan for a DLE, then read the next five bytes following and check the XOR. o If the XOR check fails, the "packet header" cannot be trusted. Scanning for the next DLE begins at the next byte following the ___ current DLE (not six bytes after it). o If the XOR check succeeds, but something's wrong with the header (illegal Kbyte value, for example), the receiver should treat this the same as an XOR failure. (XOR checks aren't all that robust) UUCP "G" PROTOCOL Page 10 UN047, Tuesday, 4-5 pm 4.2.2 Corrupted Data Segments If the header on a data packet is good (XOR is okay), but the checksum indicates that the data segment is corrupt: o Send a NAK to indicate receipt of a corrupted data packet (but see below) o Rescan the input looking for the next control packet, starting with the first byte of the data segment This seems counterintuitive; if we can trust the header it seems that we ought to be able to trust it to tell us how long the data segment is, and just skip it. Suppose the file being received is a copy of just one direction of a uucp data transfer. If we pay no attention to what's inside the data segments we see this (assuming 32-byte data segments, K = 1): HHHHHH DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD HHHHHH DDDD... but since the data contains a uucp packet stream, the data fields contain HHHHHH ddddhhhhhhdddddddddddddddddddddd HHHHHH ddddddddddhhhhhh 1 2 3 4 5 Now, suppose that the header at 1 gets corrupted in transmission, so the XOR check fails. We junk it and start looking for another DLE, and we find the "imbedded header" at 2. It passes xor, so we interpret it as a data header, and read the next 32 characters. If it happens to be the right packet number it'll fail on checksum, but more likely it's the wrong packet number; whatever, we send a NAK to tell the sender what we want, and resume scanning. Since we rescan all of (what we thought was) the data segment, we'll find the DLE at 3...and we're back in sync. If instead we had said "bad data segment, skip 32 characters" we'd be looking for the next header starting at 4. We'd then find the next imbedded header at 5.... we'd eventually get back in sync, but it might take a LONG time! 4.2.3 Missing Packets (out-of-sequence Packets) Uucp "g" protocol employs a receive window size of one; that is, there is only one packet that may be received at any time (the next one that follows the previous correctly-received packet). If an out-of-sequence packet is received the correct response is to send a NAK (with the Y field, as always, being the number of the last good packet). UUCP "G" PROTOCOL Page 11 UN047, Tuesday, 4-5 pm 4.2.4 Too Many NAKs It is not good to send a NAK for every error condition. Let's revisit the simple data exchange diagrammed previously: ______________________________________________________________ Sender Receiver ------> <-------- Data 3 (receives Data 3 ok) Ack 3 (receives Ack 2) Data 4 (data 4 is corrupted on the link) (receives Data 4 w/error) NAK 3 (#1) (receives Ack 3) Data 5 (receives Data 5 out of seq.) NAK 3 (#2) Data 6 (receives Data 6 out of seq.) NAK 3 (#3) (receives NAK 3 #1) Data 4 Data 5 Data 6 (receives Data 4 ok) Ack 4 (receives NAK 3 #2) Data 4 Data 5 Data 6 (receives Ack 4) (receives Data 4 out of seq.) NAK 4 etc... ______________________________________________________________ o Unix uucps address this by being very "shy" about sending NAKs, mostly just letting the sender time out. This works but hurts throughput. o DECUS uucp keeps track of the number of received error packets and sends the NAK only if the number modulo the window size = 1. Thus we send the first NAK right away, but no more until at least a window-size worth of packets have been received. UUCP "G" PROTOCOL Page 12 UN047, Tuesday, 4-5 pm 4.2.5 Duplicate Packets If a packet is received with a number that's already been received and ACKd it's either o a duplicate of one we got earlier; our ACKs got lost, so the sender timed out and is resending its window o a future packet, and the intervening seven packets were bad (but this can't happen, since max window size is seven, not eight) Since packets must always be acked in sequence, the only correct thing is to send a NAK indicating the last good (in sequence) received packet. 4.2.6 Miscellaneous 4.2.6.1 Control Packet Priority The control packet types denote the priority of the packets. That is, if several control packets are to be sent, the lower-numbered ones are sent first. (CLOSE before anything else, for example.) Control packets in turn have priority over data packets. 4.2.6.2 Varying Physical Packet Lengths Although the protocol allows for data packets with different K values (physical lengths) to be sent in a session, in practice, both ends always use the value negotiated at the start of the session. 4.2.6.3 Interpacket Noise The DLE that begins a packet should follow right on the heels of the previous packet. Berkeley 4.3 uucp has a bug that causes it to send two ___ null bytes between packets. A robust implementation will not report errors when it encounters two null bytes while looking for a DLE. 4.2.6.4 Common Parameters Almost all implementations seem to use a window size of 3 and a data packet physical length of 64 bytes (Kbyte = 2). Some implementations will agree to use a larger window size or packet length, but do not do so correctly. UUCP "G" PROTOCOL Page 13 UN047, Tuesday, 4-5 pm 4.2.6.5 Checksum Details The checksum that is placed in the packet header for data packets has the value MAGIC - (chksum(buf,len) ^ (0xFF & cbyte)) For control packets, the checksum value is simply MAGIC - (0xFF & cbyte) where buf is the data segment len is its (physical) length chksum() is shown below cbyte is the value of the control byte MAGIC is 0125252 (octal) (i.e. alternating bits set) If a data packet is resent, the checksum must be recalculated, as the checksum includes the control byte and the Y field (last good received packet number) of the control byte might change between transmissions of the same data packet. /* * the checksum routine, copied from G. L. Chesson's article, * modified by John Gilmore to reflect actual behavior * (see References) */ int chksum(s,n) register unsigned char *s; register n; { register short sum; register unsigned short t; register short x; sum = -1; x = 0; do { if (sum < 0) { sum <<= 1; sum++; } else sum <<= 1; t = sum; sum += *s++ & 0377; x += sum ^ n; if ((unsigned short)sum <= t) sum ^= x; } while (--n > 0); return(sum); } UUCP "G" PROTOCOL Page 14 UN047, Tuesday, 4-5 pm 5 FILE TRANSFER "MESSAGES" ("APPLICATION LAYER") ________ ____ ____ The data packets and acknowledgements form a reliable data link which ________ _____ the two uucico programs use to exchange messages and files. ______ ____ At the start of a uucp session the caller is in master mode and the _____ answerer is in slave. The caller searches its uucp spool directory for work (queued requests to send or receive files). Each such "work request" results in an "S" (request to send), "R" (request to receive), or "X" (remote request for uucp) message being sent to the slave: _________________ ___________________ S srcfile_on_master targetfile_on_slave ... ________________ ____________________ R srcfile_on_slave targetfile_on_master ... _______ ___________________ X srcfile uucphost!targetfile ... (not covered here) The slave will respond with one of: (for send requests) SY ok SN2 not permitted SN4 can't create temporary file (for receive requests) RY ok (gives protection mode of file) RN2 not permitted If the master receives any of the reject messages it simply looks for its next queued work request. If the master receives an "ok", the master (for file send requests) or the slave (for file receive requests) sends the file to the other side. The receiver of the file then sends one of the following messages: CN5 couldn't move temp file into place CY file received ok to the sender. UUCP "G" PROTOCOL Page 15 UN047, Tuesday, 4-5 pm 6 ROLE EXCHANGE When the master has no more queued work requests it asks the slave if it wants to hang up. The slave then looks for work and, if any is found, the two systems exchange master and slave roles. Example: Slave has no work, hangup is agreed upon: ______________________________________________________________ Master Slave ------> <----- H HY HY (at this point both systems invoke the G protocol shutdown routine) ______________________________________________________________ Example: Slave has work, roles are exchanged: ______________________________________________________________ Master Slave ------> <----- H HN (at this point roles are exchanged) Slave Master -----> <------ S file1 file2 ... ______________________________________________________________ When the new master runs out of work it will again ask the former master if it wants to hang up (as more work may have been queued on that side during its tenure as slave). The process repeats until neither system finds any work for the other. UUCP "G" PROTOCOL Page 16 UN047, Tuesday, 4-5 pm 7 SENDING AND RECEIVING MESSAGES AND FILES ("PRESENTATION LAYER") 7.1 Sending Messages o Messages (S, SY, SNn, R, RY, RNn, CY, CNn, H, HY, HN) are sent in longdata packets. o Some uucps send the last (or only) part of a message in a shortdata packet. o As many packets as necessary for the message are used. o The message is terminated by a null byte. o Only one message is sent at a time. o Some uucps seem to expect the rest of the packet to be padded with nulls. 7.2 Sending Files o Since Unix, and therefore uucp, has no concept of "file attributes", the file is simply copied, byte for byte, into packets and transmitted. (The file protection mode is sent either as a parameter on the S message or with the RY message.) o Transmission of a shortdata packet with logical length of zero indicates end of file (that is, the previous packet contains the last bytes in the file). These details are specific to the "g" protocol -- thus "g" includes both the data link and presentation layers. 8 G PROTOCOL SHUTDOWN When both systems have agreed (via H, HY, HY message exchange) to hang up, they each call the gturnoff() function, causing CLOSE control messages to be exchanged: ______________________________________________________________ (either) (either) --------> <-------- CLOSE CLOSE ______________________________________________________________ UUCP "G" PROTOCOL Page 17 UN047, Tuesday, 4-5 pm 9 "OVER AND OUT" After the data link layer has exchanged "CLOSE" messages, one more set of "over and out" messages is exchanged: ______________________________________________________________ Caller Answerer ------> <-------- OOOOOO (six "O"'s) (seven "O"'s) OOOOOOO ______________________________________________________________ Note that since the "g" protocol has already been turned off, these ___ message are not preceded by six-byte headers. They are, however, ________ preceded by DLE and terminated by NUL, as were the Shere, Shostname, _____ Pprots, etc., messages at the beginning of the session. UUCP "G" PROTOCOL Page 18 UN047, Tuesday, 4-5 pm 10 A COMPLETE SESSION Here the caller sends one file and receives one, after which the answerer sends one file. (ACKs, NAKs, and retransmits for the g protocol are not shown.) ______________________________________________________________ Caller Answerer ------> <-------- (places call, logs in, etc.) (uucico program starts) (subsequent transmissions are framed by DLE .... NUL) ________ Shere=hostname ________ Shostname ROK Pfgt Ug (subsequent packets have "g" protocol headers) Control(INITA) Control(INITA) Control(INITB) Control(INITB) Control(INITC) Control(INITC) Longdata(S fromfile1 tofile1 ...) Longdata(SY) Longdata(file contents) Longdata(file contents) ... Shortdata(last few bytes of file) Shortdata(logical length 0) Longdata(CY) Longdata(R fromfile1 tofile1 ...) Longdata(RY) Longdata(file contents) Longdata(file contents) ... Shortdata(last few bytes of file) Shortdata(logical length 0) Longdata(CY) Longdata(H) Longdata(HN) Longdata(S fromfile1 tofile1 ...) Longdata(SY) Longdata(file contents) Longdata(file contents) ... Shortdata(last few bytes of file) Shortdata(logical length 0) Longdata(CY) Longdata(H) Longdata(HY) Longdata(HY) UUCP "G" PROTOCOL Page 19 UN047, Tuesday, 4-5 pm Control(CLOSE) Control(CLOSE) (subsequent transmissions are framed only by DLE .... NUL) OOOOOO OOOOOOO ______________________________________________________________ 11 UUCP WORK FILES: ORIGINS OF "S" AND "R" COMMANDS ____ _____ The uucico programs at each system are driven by work files in the uucp spool directory. o To decide whether to call a uucp neighbor, uucico looks for work files associated with the neighbor's uucp host name. o When answering a call from a uucp neighbor, after the neighbor asks "do you want to hang up?", the answering uucico looks for work files associated with the calling system's uucp host name. 11.1 Work File Names An older work file naming convention is: ______________ _____ ____ C.remotehostname grade uniq For example, C.crashA8128 o "C." is a constant ______________ o remotehostname is the uucp host name of the remote system (7 chars max, even if the actual host name is longer) _____ o grade is a single letter denoting the priority of the work request e.g. "A" is the most important, "Z" is very unimportant, and "N" is somewhere in between. Since the files are found by searching the spool directory, and since files are kept in lexical order by file name, the most important files are found first. Some uucps can be configured to only place outbound calls for certain grades of work at certain times of day; for example, mail is typically assigned a very high grade, and one might want to transfer mail almost as soon as it is queued, with file transfers somewhat less important, and news being relegated to evenings and nights. UUCP "G" PROTOCOL Page 20 UN047, Tuesday, 4-5 pm o uniq is four characters (four digits in older implementations) which make this work file name unique, even though other work files for the same uucp host, with the same grade, may exist. o Newer systems use four or six alphanumeric characters, and case __ is significant, e.g. C.noscMabcdef is a different file from C.noscMabcdeF. o Some Unix implementations use different conventions. - HoneyDanBer uses a different subdirectory for each neighbor system (the subdirectory name is the neighbor system's uucp host name). (see references) - One implementation uses one subdirectory for "C." files, and another for all data files. o Other systems with restrictive file names (e.g. MS-DOS) can use different conventions, as long as the same functions can be performed. For example, uucp/spool/C.simpactA1234 might become C:UUCP\SPOOL\C\SIMPACT\A1234 After starting up in master mode, the uucico program processes each work file associated with the remote system. When no work files remain, the master mode uucico offers to switch roles (i.e. it sends an "H" message to the slave). The slave searches for work files containing the master's host name. If any are found, roles are switched, otherwise the systems agree to hang up. 11.2 Work File Contents Each work file contains one or more "S", "R", or "X" (not covered here) commands. These are processed (i.e. sent to the neighbor, and the indicated file transferred) in turn. 11.2.1 "S" (send File From Master To Slave) Commands Format: _______ ________ ____ ____ ________ ____ ______ S srcfile trgtfile user opts datafile mode notify _______ o srcfile is the fully-qualified pathname of the source file ________ o trgtfile is the fully-qualified pathname to which the file is to be copied on the target system UUCP "G" PROTOCOL Page 21 UN047, Tuesday, 4-5 pm ____ o user is the sending user's login name ____ o opts options, preceded by "-" _______ - c send directly from srcfile. If absent, send from copy ________ of file in spool directory, name given by datafile, and _______ delete copy after transferring; in this case srcfile is informational, providing the file's original name. - m notify sender by mail when copy is completed ______ - n notify user notify on target system when file arrives If no options are present, a hyphen appears here as a placeholder. ________ o datafile if "c" option present, "D.0"; if "c" absent, gives the name of the data file in the spool directory for uucico to send. ____ o mode is the Unix-style file protection mode (in octal) to be given to the new file ______ o notify is the name of a user on the target system; present only if "n" option present 11.2.2 "R" (Receive File From Slave To Master) Commands ________ ____ ______ Same as "S" commands, except datafile, mode, and notify fields are not present. 11.3 Origins Of Work Files Work files are created when: o Users issue "uucp" commands (these are explicit requests to copy files to or from uucp neighbors) o Users send mail which goes out via uucp (the "mailer" places the mail in a file in a spool directory, and creates the necessary work file to cause it to be sent to the first hop in the uucp path) o "Route-through" uucp mail arrives (this is really just the same as the preceding case -- the "mailer" is seen as just another user) o News is queued for transmission to another system (as with mail, the news transfer programs place the news batch in a file in the spool directory, and create the necessary work file) UUCP "G" PROTOCOL Page 22 UN047, Tuesday, 4-5 pm 12 EXECUTION FILES ("X." FILES) ______ _______ _________ The X-file mechanism is used for remote command execution. o Receipt of a file named X.anything in the spool directory triggers the "uuxqt" program o uuxqt interprets the X-file o Typical uses are for mail and news o The uux command allows users to request remote execution of arbitrary commands (permissions permitting) 12.1 X-File Contents The X-File contains one or more lines. The first character on each line specifies a command type. It is followed by a blank and one or more parameters which are interpreted according to the command type, as follows: (From a Usenet article by Dr. Peter Honeyman) C command to be executed I file name for command input O file name for command output F file required to be present before running command; optional second argument gives name for the file at execution time R name of user who issued request (relative to the host named on the U line) U second arg is name of host that passed this X. file to me; first arg is a user name on that host (overridden by R line) Z send status notification (and error output) if command failed N send no status notification if command failed n send status notification if command succeeded B return command input on error e requests command be processed with sh(1) E requests command be processed with exec(2) M return status info to the named file on the requesting host # comment line Unrecognized lines are ignored, i.e. treated as comments. 12.2 Example: Sending Mail. User jeh on system simpact sends mail to user bblue on uucp neighbor crash. 1. simpact's mailer creates mail text file in spool directory (file name D.simpactA3214) UUCP "G" PROTOCOL Page 23 UN047, Tuesday, 4-5 pm 2. simpact's mailer creates what will become an X-file in simpact's spool directory (file name B.simpactA3214) U jeh simpact F D.simpactA3214 I D.simpactA3214 C rmail bblue 3. simpact's mailer creates work file in simpact's spool directory (file name C.crashA0001) S D.simpactA3214 D.simpactA3214 jeh - D.simpactA3214 0666 S B.simpactA3214 X.simpactA3214 jeh - B.simpactA3214 0666 4. simpact calls system "crash" and interprets the work file, transferring the "D." and "B." files (in that order). Note that when the "B." file arrives at crash, its name is X.simpactA3214 (see the second "S" command in the C file above). 5. The uuxqt program at crash interprets the X file, using the file D.simpactA3214 as input to the command "rmail bblue". Notes: ____ o Some systems use a different uniq value in the file name for each locally-created file (instead of relying on the first letter to keep them separate). o Some systems use the "D." prefix for both the mail message text and for the file that will become the "X." file on the target ____ system. (In this case, the uniq value must be different for these two files) o This mechanism is designed so that, even with a single spool ____ directory and uncoordinated uniq values, all file names will be unique: - Only the local system creates "B." and "C." files. - Only the remote system creates "X." files. - Only the local system creates files called _____________ "D.localhostname*". - Only the remote system creates files called ______________ "D.remotehostname*". 13 FILE NAME TRANSLATION Systems with different file name syntax need not be barred from participating in uucp transfers, and particularly not from mail and news. UUCP "G" PROTOCOL Page 24 UN047, Tuesday, 4-5 pm 13.1 Receiving Mail And News o Only received "D." and "X." files are of concern. o Local uucico maps file names specified by Unix system to local requirements when processing received "S" commands (in slave mode). ____ o Local uuxqt performs the same translation when handling file names in the "X." file. 13.2 Sending Mail And News o Names of locally-created "B.", "C.", and "D." files can adhere to local conventions. o When constructing the local work file ("C." file), build ________ Unix-format trgtfile names in the "S" commands. 14 REFERENCES AND ACKNOWLEDGEMENTS 14.1 Uucp Protocols (The following two papers were instrumental both in preparing this article and in implement uucp "g" for VMS. I believe that all of the material in these two papers is incorporated in this article. I could be wrong.) Chuck Wegrzyn posted a Usenet article (date unknown) that described the Shere exchange, over-and-out exchange, and the application layer. "Packet Driver Protocol" by G. L. Chesson of Bell Laboratories (October 5, 1988), distributed via Usenet and Internet, is the standard reference on the the "g" protocol data link layer. 14.2 The Uucp System ________ ____ ___ ______ Managing uucp and Usenet by Tim O'Reilly and Grace Todino, (O'Reilly And Associates, Newton, MA 02164), has a good description of the Shere exchange and of work file and execution file contents. "Uucp Implementation Description" by D. A. Nowitz, part of most complete _____________ _________ Unix documentation sets (check the Supplementary Documents volumes, if present) provides a general description of each program in the uucp suite. "HoneyDanBer UUCP -- Bringing UNIX Systems into the Information Age" by _______ Bill Rieken and Jim Webb, ;login: (journal of the Usenix Association), Volume 11, Numbers 3 and 4 (May/June and July/August, 1986). Describes "external" features of one of the newest Unix uucp implementations, including new file name conventions, logging, and error handling. UUCP "G" PROTOCOL Page 25 UN047, Tuesday, 4-5 pm 14.3 General A widely-recognized work on the subject of data communications protocols ________ ________ is Computer Networks by Andrew S. Tanenbaum (Prentice-Hall). Algorithms are included for several different types of windowed data link protocols. _______ _ ____ ________ ________ Kermit, A File Transfer Protocol by Frank da Cruz (Digital Press), provides a very lucid description of the sliding-window extension to Kermit. Although windowed Kermit differs in several important ways from uucp "g", this material was of great assistance in designing the windowed "g" implementation for DECUS uucp and in understanding the subtle nuances of windowed protocols. 14.4 Critiques And Proofreading The following people graciously reviewed and send comments on early versions of this paper: o Christopher J. Ambler, chris@fubarsys.slo.ca.us, cambler@polyslo.calpoly.edu o Jordan Brown, jbrown@jato.jpl.nasa.gov o Nick Pemberton, Lsuc, uunet!mnetor!aimed!nick o Mark Pizzolato, decwrl!infopiz!mark