16.2. UUCP Configuration Files
In contrast to simpler file transfer programs, UUCP was designed to be able to handle all transfers automatically. Once it is set up properly, interference by the administrator should not be necessary on a day-to-day basis. The information required for automated transfer is kept in a couple of configuration files that reside in the /usr/lib/uucp directory. Most of these files are used only when dialing out.
16.2.1. A Gentle Introduction to Taylor UUCP
To say that UUCP configuration is difficult would be an understatement. It is really a hairy subject, and the sometimes terse format of the configuration files doesn't make things easier (although the Taylor format is almost easy reading compared to the older formats in HDB or Version 2).
To give you a feel for how all the configuration files interact, we will introduce you to the most important ones and have a look at sample entries from these files. We won't explain everything in detail now; a more accurate account is given in separate sections that follow. If you want to set up your machine for UUCP, you had best start with some sample files and adapt them gradually. You can pick either those shown below or those included in your favorite Linux distribution.
All files described in this section are kept in /etc/uucp or a subdirectory thereof. Some Linux distributions contain UUCP binaries that have support for both HDB and Taylor configuration enabled, and use different subdirectories for each configuration file set. There will usually be a README file in /usr/lib/uucp.
For UUCP to work properly, these files must be owned by the uucp user. Some of them contain passwords and telephone numbers, and therefore should have permissions of 600. Note that although most UUCP commands must be setuid to uucp, you must make sure the uuchk program is not. Otherwise, users will be able to display system passwords even though the files have mode 600.
The central UUCP configuration file is /etc/uucp/config, which is used to set general parameters. The most important of them (and for now, the only one) is your host's UUCP name. At the Virtual Brewery, they use vstout as their UUCP gateway:
# /etc/uucp/config - UUCP main configuration file nodename vstout |
The sys file is the next important configuration file. It contains all the system-specific information of sites to which you are linked. This includes the site's name and information on the link itself, such as the telephone number when using a modem link. A typical entry for a modem-connected site called pablo would look like this:
# /usr/lib/uucp/sys - name UUCP neighbors # system: pablo system pablo time Any phone 555-22112 port serial1 speed 38400 chat ogin: vstout ssword: lorca |
time specifies the times at which the remote system may be called. chat describes the login chat scripts—the sequence of strings that must be exchanged to allow uucico to log into pablo. We will get back to chat scripts later. The port keyword simply names an entry in the port file. (Refer to Figure 16-1.) You can assign whatever name you like as long as it refers to a valid entry in port.
The port file holds information specific to the link itself. For modem links, it describes the device special file to be used, the range of speeds supported, and the type of dialing equipment connected to the port. The following entry describes /dev/ttyS1 (a.k.a. COM 2), to which the administrator has connected a NakWell modem capable of running at speeds up to 38,400 bps. The port's name is chosen to match the port name given in the sys file:
# /etc/uucp/port - UUCP ports # /dev/ttyS1 (COM2) port serial1 type modem device /dev/ttyS1 speed 38400 dialer nakwell |
The information pertaining to the dialers is kept in yet another file called—you guessed it—dial. For each dialer type, it basically contains the sequence of commands that are issued to dial up a remote site, given the telephone number. Again, this is specified as a chat script. For example, the entry for NakWell might look like this:
# /etc/uucp/dial - per-dialer information # NakWell modems dialer nakwell chat "" AT&F OK ATDT\T CONNECT |
The line starting with chat specifies the modem chat, which is the sequence of commands sent to and received from the modem to initialize it and make it dial the desired number. The \T sequence will be replaced with the phone number by uucico.
To give you a rough idea how uucico deals with these configuration files, assume you issue the following command:
$ uucico -s pablo |
The first thing uucico does is look up pablo in the sys file. From the sys file entry for pablo, it sees that it should use the serial1 port to establish the connection. The port file tells uucico that this is a modem port, and that it has a NakWell modem attached.
uucico now searches dial for the entry describing the NakWell modem, and having found one, opens the serial port /dev/cua1 and executes the dialer chat. That is, it sends AT&F, waits for the OK response, etc. When encountering the string \T, it substitutes the phone number (555-22112) extracted from the sys file.
After the modem returns CONNECT, the connection has been established, and the modem chat is complete. uucico now returns to the sys file and executes the login chat. In our example, it would wait for the login: prompt, then send its username (vstout), wait for the password: prompt, and send its password (lorca).
After completing authorization, the remote end is assumed to fire up its own uucico. The two then enter the handshake phase described in the previous section.
Figure 16-1 illustrates the dependencies among configuration files.
16.2.2. What UUCP Needs to Know
Before you start writing the UUCP configuration files, you have to gather some information that UUCP requires.
First, you have to figure out what serial device your modem is attached to. Usually, the (DOS) ports COM1: through COM4: map to the device special files /dev/ttyS0 through /dev/ttyS3. Some distributions, such as Slackware, create a link called /dev/modem to the appropriate ttyS* device file, and configure kermit, seyon, and any other communication programs to use this generic file. In this case, you should use /dev/modem in your UUCP configuration, too.
The reason for using a symbolic link is that all dial-out programs use so-called lock files to signal when a serial port is in use. The names of these lock files are a concatenation of the string LCK.. and the device filename, for instance LCK..ttyS1. If programs use different names for the same device, they will fail to recognize each other's lock files. As a consequence, they will disrupt each other's session when started at the same time. This is quite possible when you schedule your UUCP calls using a crontab entry. For details on serial port setup, please refer to Chapter 4.
Next, you must find out at what speed your modem and Linux will communicate. You have to set this speed to the maximum effective transfer rate you expect to get. The effective transfer rate may be much higher than the raw physical transfer rate your modem is capable of. For instance, many modems send and receive data at 56 kbps. Using compression protocols such as V.42bis, the actual transfer rate may climb over 100 kbps.
Of course, if UUCP is to do anything at all, you need the phone number of a system to call. Also, you need a valid login ID and possibly a password for the remote machine.[1]
You also have to know exactly how to log into the system. Do you have to press the Enter key before the login prompt appears? Does it display login: or user:? This is necessary for composing the chat script. If you don't know, or if the usual chat script fails, try to call the system with a terminal program like kermit or minicom and record exactly what you have to do.
16.2.3. Site Naming
As with TCP/IP-based networking, your host has to have a name for UUCP networking. As long as you simply want to use UUCP for file transfers to or from sites you dial up directly, or on a local network, this name does not have to meet any standards.[2]
However, if you use UUCP for a mail or news link, you should think about having the name registered with the UUCP Mapping Project.[3] The UUCP Mapping Project is described in Chapter 17. Even if you participate in a domain, you might consider having an official UUCP name for your site.
Frequently, people choose their UUCP name to match the first component of their fully qualified domain name. Suppose your site's domain address is swim.twobirds.com; then your UUCP hostname would be swim. Think of UUCP sites as knowing each other on a first-name basis. Of course, you can also use a UUCP name completely unrelated to your fully qualified domain name.
However, make sure not to use the unqualified site name in mail addresses unless you have registered it as your official UUCP name. At the very best, mail to an unregistered UUCP host will vanish in some big black bit bucket. If you use a name already held by some other site, this mail will be routed to that site and cause its postmaster a lot of headaches.
By default, the UUCP suite uses the name set by hostname as the site's UUCP name. This name is commonly set by a command on the boot time rc scripts, and is usually stored in the /etc/hostname. If your UUCP name is different from what you set your hostname to, you have to use the hostname option in the config file to tell uucico about your UUCP name. This is described next.
16.2.4. Taylor Configuration Files
We now return to the configuration files. Taylor UUCP gets its information from the following files:
- config
This is the main configuration file. You can define your site's UUCP name here.
- sys
This file describes all known sites. For each site, it specifies its name, what times to call it, which number to dial (if any), what type of device to use, and how to log on.
- port
This file contains entries describing each available port, together with the line speed supported and the dialer to be used.
- dial
This file describes dialers used to establish a telephone connection.
- dialcode
This file contains expansions for symbolic dial codes.
- call
This file contains the login name and password to be used when calling a system. Rarely used.
- passwd
This file contains login names and passwords that systems may use when logging in. It is used only when uucico does its own password checking.
Taylor configuration files are generally made up of lines containing keyword-value pairs. A hash sign introduces a comment that extends to the end of the line. To use a hash sign to mean itself, escape it with a backslash like this: \#.
There are quite a number of options you can tune with these configuration files. We can't go into all the parameters, but we will cover the most important ones here. Then you should be able to configure a modem-based UUCP link. Additional sections describe the modifications necessary if you want to use UUCP over TCP/IP or over a direct serial line. A complete reference is given in the Texinfo documents that accompany the Taylor UUCP sources.
When you think you have configured your UUCP system completely, you can check your configuration using the uuchk tool (located in /usr/lib/uucp). uuchk reads your configuration files and prints out a detailed report of the configuration values used for each system.
16.2.5. General Configuration Options Using the config File
You won't generally use this file to describe much beside your UUCP hostname. By default, UUCP will use the name you set with the hostname command, but it is generally a good idea to set the UUCP name explicitly. Here's a sample config file:
# /usr/lib/uucp/config - UUCP main configuration file hostname vstout |
A number of miscellaneous parameters can be set here too, such as the name of the spool directory or access rights for anonymous UUCP. The latter will be described later in this chapter in the section “Anonymous UUCP.”
16.2.6. How to Tell UUCP About Other Systems Using the sys File
The sys file describes the systems that your machine knows about. An entry is introduced by the system keyword; the subsequent lines up to the next system directive detail the parameters specific to that site. Commonly, a system entry defines parameters such as the telephone number and login chat.
Parameters before the very first system line set default values used for all systems. Usually, you set protocol parameters and the like in the defaults section.
The most prominent fields are discussed in detail in the following sections.
16.2.6.1. System name
The system command names the remote system. You must specify the correct name of the remote system, not an alias you invented, because uucico will check it against what the remote system says it is called when you log on.[4]
Each system name can appear only once. If you want to use several sets of configurations for the same system (such as different telephone numbers uucico should try in turn), you can specify alternates, which we'll describe after the basic configuration options.
16.2.6.2. Telephone number
If the remote system is to be reached over a telephone line, the phone field specifies the number the modem should dial. It may contain several tokens interpreted by uucico's dialing procedure. An equal sign (=) means wait for a secondary dial tone, and a dash (-) generates a one-second pause. Some telephone installations choke when you don't pause between dialing a special access code and the telephone number.[5]
It is often convenient to use names instead of numbers to describe area dialing codes. The dialcode file allows you to associate a name with a code that you may subsequently use when specifying telephone numbers for remote hosts. Suppose you have the following dialcode file:
# /usr/lib/uucp/dialcode - dialcode translation Bogoham 024881 Coxton 035119 |
With these translations, you can use a phone number such as Bogoham7732 in the sys file, which will probably make things a little more legible and a whole lot easier to update should the dialing code for Bogoham ever change.
16.2.6.3. port and speed
The port and speed options are used to select the device used for calling the remote system and the maximum speed to which the device should be set.[6] A system entry may use either option alone or both options in conjunction. When looking up a suitable device in the port file, only ports that have a matching port name and/or speed range are selected.
Generally, using the speed option only should suffice. If you have only one serial device defined in port, uucico always picks the right one anyway, so you only have to give it the desired speed. If you have several modems attached to your systems, you still often don't want to name a particular port, because if uucico finds that there are several matches, it tries each device in turn until it finds an unused one.
16.2.6.4. The login chat
We already encountered the login chat script, which tells uucico how to log in to the remote system. It consists of a list of tokens specifying strings expected and sent by the local uucico process. uucico waits until the remote machine sends a login prompt, then returns the login name, waits for the remote system to send the password prompt, and sends the password. Expect and send strings appear in alternation in the script. uucico automatically appends a carriage return character (\r) to any send string. Thus, a simple chat script would look like:
ogin: vstout ssword: catch22 |
You will probably notice that the expect fields don't contain the whole prompts. This ensures that the login succeeds, even if the remote system transmits Login: instead of login:. If the string you are expecting or sending contains spaces or other white-space characters, you must use quotes to surround the text.
uucico also allows for some sort of conditional execution. Let's say the remote machine's getty needs to be reset before sending a prompt. For this, you can attach a subchat to an expect string, set off by a dash. The subchat is executed only if the main expect fails, i.e., a timeout occurs. One way to use this feature is to send a BREAK if the remote site doesn't display a login prompt. The following example gives a general-purpose chat script that should also work in case you have to press Enter before the login appears. The empty first argument, "", tells UUCP to not wait for anything, but to continue with the next send string:
"" \n\r\d\r\n\c ogin:-BREAK-ogin: vstout ssword: catch22 |
A couple of special strings and escape characters can occur in the chat script. The following is a partial list of characters legal in expect strings:
- ""
The empty string. It tells uucico to not wait for anything, but to proceed with the next send string immediately.
- \t
Tab character.
- \r
Carriage return character.
- \s
Space character. You need this to embed spaces in a chat string.
- \n
Newline character.
- \\
Backslash character.
On send strings, the following escape characters and strings are legal in addition to the above:
- EOT
End of transmission character (^D).
- BREAK
Break character.
- \c
Suppress sending of carriage return at end of string.
- \d
Delay sending for 1 second.
- \E
Enable echo checking. This requires uucico to wait for the echo of everything it writes to be read back from the device before it can continue with the chat. It is primarily useful when used in modem chats (which we will encounter later). Echo checking is off by default.
- \e
Disable echo checking.
- \K
Same as BREAK.
- \p
Pause for fraction of a second.
16.2.6.5. Alternates
Sometimes you want to have multiple entries for a single system, for instance if the system can be reached on different modem lines. With Taylor UUCP, you can do this by defining a so-called alternate.
An alternate entry retains all settings from the main system entry and specifies only those values that should be overridden in the default system entry or added to it. An alternate is offset from the system entry by a line containing the keyword alternate.
To use two phone numbers for pablo, you would modify its sys entry in the following way:
system pablo phone 123-456 .. entries as above ... alternate phone 123-455 |
When calling pablo, uucico will first dial 123-456, and if this fails, it will try the alternate. The alternate entry retains all settings from the main system entry and overrides the telephone number only.
16.2.6.6. Restricting call times
Taylor UUCP provides a number of ways you may restrict the times when calls can be placed to a remote system. You might do this either because of limitations the remote host places on its services during business hours, or simply to avoid times with high call rates. Note that it is always possible to override call-time restrictions by giving uucico the –S or –f option.
By default, Taylor UUCP disallows connections at any time, so you have to use some sort of time specification in the sys file. If you don't care about call time restrictions, you can specify the time option with a value of Any in your sys file.
The simplest way to restrict call time is to include a time entry, followed by a string made up of a day and a time subfield. Day may be any combination of Mo, Tu, We, Th, Fr, Sa, and Su. You can also specify Any, Never, or Wk for weekdays. The time consists of two 24-hour clock values, separated by a dash. They specify the range during which calls may be placed. The combination of these tokens is written without white space in between. Any number of day and time specifications may be grouped together with commas, as this line shows:
time MoWe0300-0730,Fr1805-2200 |
This example allows calls on Mondays and Wednesdays from 3:00 a.m. to 7:30 a.m., and on Fridays between 6:05 p.m. and 10:00 p.m. When a time field spans midnight, say Mo1830-0600, it actually means Monday, between midnight and 6:00 a.m. and between 6:30 p.m. and midnight.
The special time strings Any and Never mean what they say: calls may be placed at any or no time, respectively.
Taylor UUCP also has a number of special tokens you may use in time strings, such as NonPeak and Night. These special tokens are shorthand for Any2300-0800,SaSu0800-1700 and Any1800-0700,SaSu, respectively.
The time command takes an optional second argument that describes a retry time in minutes. When an attempt to establish a connection fails, uucico will not allow another attempt to dial up the remote host within a certain interval. For instance, when you specify a retry time of 5 minutes, uucico will refuse to call the remote system within 5 minutes after the last failure. By default, uucico uses an exponential backoff scheme, where the retry interval increases with each repeated failure.
The timegrade command allows you to attach a maximum spool grade to a schedule. For instance, assume you have the following timegrade commands in a system entry:
timegrade N Wk1900-0700,SaSu timegrade C Any |
This allows jobs with a spool grade of C or higher (usually mail is queued with grade B or C) to be transferred whenever a call is established, while news (usually queued with grade N) are transferred only during the night and at weekends.
Just like time, the timegrade command takes a retry interval in minutes as an optional third argument.
However, a caveat about spool grades is in order here. First, the timegrade option applies only to what your systems sends; the remote system may still transfer anything it likes. You can use the call-timegrade option to explicitly request it to send only jobs above some given spool grade; but there's no guarantee it will obey this request.[7]
Similarly, the timegrade field is not checked when a remote system calls in, so any jobs queued for the calling system will be sent. However, the remote system can explicitly request your uucico to restrict itself to a certain spool grade.
16.2.7. Identifying Available Devices Through the port File
The port file tells uucico about the available ports. These are usually modem ports, but other types, such as direct serial lines and TCP sockets, are supported as well.
Like the sys file, port consists of separate entries starting with the keyword port followed by the port name. This name may be used in the sys file's port statement. The name need not be unique; if there are several ports with the same name, uucico will try each in turn until it finds one that is not currently being used.
The port command should be followed immediately by the type statement, which indicates what type of port is described. Valid types are modem, direct for direct connections, and tcp for TCP sockets. If the port command is missing, the port type defaults to modem.
In this section, we cover only modem ports; TCP ports and direct lines are discussed in a later section.
For modem and direct ports, you have to specify the device for calling out using the device directive. Usually, this is the name of a device special file in the /dev directory, like /dev/ttyS1.
In the case of a modem device, the port entry also determines what type of modem is connected to the port. Different types of modems have to be configured differently. Even modems that claim to be Hayes-compatible aren't always really compatible with one another. Therefore, you have to tell uucico how to initialize the modem and make it dial the desired number. Taylor UUCP keeps the descriptions of all dialers in a file named dial. To use any of these, you have to specify the dialer's name using the dialer command.
Sometimes, you will want to use a modem in different ways, depending on which system you call. For instance, some older modems don't understand when a high-speed modem attempts to connect at 56 kbps; they simply drop the line instead of negotiating a connect at 9,600 bps, for instance. When you know site drop uses such a dumb modem, you have to set up your modem differently when calling them. For this, you need an additional port entry in the port file that specifies a different dialer. Now you can give the new port a different name, such as serial1-slow, and use the port directive in the drop system entry in sys.
A better to distinguish the ports is by the speeds they support. For instance, the two port entries for the above situation may look like this:
# NakWell modem; connect at high speed port serial1 # port name type modem # modem port device /dev/ttyS1 # this is COM2 speed 115200 # supported speed dialer nakwell # normal dialer # NakWell modem; connect at low speed port serial1 # port name type modem # modem port device /dev/ttyS1 # this is COM2 speed 9600 # supported speed dialer nakwell-slow # don't attempt fast connect |
The system entry for site drop would now give serial1 as the port name, but request to use it at only 9,600 bps. uucico then automatically uses the second port entry. All remaining sites that have a speed of 115,200 bps in the system entry will be called using the first port entry. By default, the first entry with a matching speed will be used.
16.2.8. How to Dial a Number Using the dial File
The dial file describes the way various dialers are used. Traditionally, UUCP talks of dialers rather than modems, because in earlier times, it was usual practice to have one (expensive) automatic dialing device serve a whole bank of modems. Today, most modems have dialing support built in, so this distinction gets a little blurred.
Nevertheless, different dialers or modems may require a different configuration. You can describe each of them in the dial file. Entries in dial start with the dialer command that gives the dialer's name.
The most important entry besides dialer is the modem chat, specified by the chat command. Similar to the login chat, it consists of a sequence of strings uucico sends to the dialer and the responses it expects in return. It is commonly used to reset the modem to some known state and dial the number. The following sample dialer entry shows a typical modem chat for a Hayes-compatible modem:
# NakWell modem; connect at high speed dialer nakwell # dialer name chat "" AT&F OK\r ATH1E0Q0 OK\r ATDT\T CONNECT chat-fail BUSY chat-fail ERROR chat-fail NO\sCARRIER dtr-toggle true |
The modem chat begins with "", the empty expect string. uucico therefore sends the first command AT&F right away. AT&F is the Hayes command to reset the modem to factory default configuration. uucico then waits until the modem has sent OK and sends the next command, which turns off local echo and the like. After the modem returns OK again, uucico sends the dialing command ATDT. The escape sequence \T in this string is replaced with the phone number taken from the system entry sys file. uucico then waits for the modem to return the string CONNECT, which signals that a connection with the remote modem has been established successfully.
Sometimes the modem fails to connect to the remote system; for instance, if the other system is talking to someone else and the line is busy. In this case, the modem returns an error message indicating the reason. Modem chats are not capable of detecting such messages; uucico continues to wait for the expected string until it times out. The UUCP log file therefore only shows a bland “timed out in chat script” instead of the specific reason.
However, Taylor UUCP allows you to tell uucico about these error messages using the chat-fail command as shown above. When uucico detects a chat-fail string while executing the modem chat, it aborts the call and logs the error message in the UUCP log file.
The last command in the example shown above tells UUCP to toggle the Data Terminal Ready (DTR) control line before starting the modem chat. Normally, the serial driver raises DTR when a process opens the device to tell the attached modem that someone wants to talk to it. The dtr-toggle feature then drops DTR, waits a moment, and raises it again. Many modems can be configured to react to a drop of DTR by going off-hook, entering command state, or resetting themselves.[8]
16.2.9. UUCP Over TCP
Absurd as it may sound, using UUCP to transfer data over TCP is not that bad an idea, especially when transferring large amounts of data such as Usenet news. On TCP-based links, news is generally exchanged using the NNTP protocol, through which articles are requested and sent individually without compression or any other optimization. Although adequate for large sites with several concurrent newsfeeds, this technique is very unfavorable for small sites that receive their news over a relatively slow connection such as ISDN. These sites will usually want to combine the qualities of TCP with the advantages of sending news in large batches, which can be compressed and thus transferred with very low overhead. A common way to transfer these batches is to use UUCP over TCP.
In sys, you would specify a system to be called via TCP like this:
system gmu address news.groucho.edu time Any port tcp-conn chat ogin: vstout word: clouseau |
The address command gives the IP address of the host or its fully qualified domain name. The corresponding port entry would read:
port tcp-conn type tcp service 540 |
The entry states that a TCP connection should be used when a sys entry references tcp-conn, and that uucico should attempt to connect to the TCP network port 540 on the remote host. This is the default port number of the UUCP service. Instead of the port number, you may also give a symbolic port name to the service command. The port number corresponding to this name will be looked up in /etc/services. The common name for the UUCP service is uucpd.
16.2.10. Using a Direct Connection
Assume you use a direct line to connect your system vstout to tiny. Much like in the modem case, you have to write a system entry in the sys file. The port command identifies the serial port tiny is hooked up to:
system tiny time Any port direct1 speed 38400 chat ogin: cathcart word: catch22 |
In the port file, you have to describe the serial port for the direct connection. A dialer entry is not needed because there's no need for dialing:
port direct1 type direct speed 38400 device /dev/ttyS1 |