<chapter id="X-087-2-uucp"><title>Managing<?lb>Taylor UUCP</title>
<indexterm id="idx-configuringUUCP-1" class="startofrange"><primary>configuring</primary><secondary>Taylor UUCP</secondary></indexterm>
<indexterm id="idx-UUCP-2" class="startofrange"><primary>Taylor UUCP</primary></indexterm>

<para>
UUCP was designed in the late seventies by Mike Lesk at AT&amp;T Bell
Laboratories to provide a simple dialup network over public telephone
lines. Despite the popularity of dialup PPP and SLIP connections to the
Internet, many people who want to have email and Usenet News on their home
machine still use UUCP because it is often cheaper, especially in countries
where Internet users have to pay by the minute for local telephone calls, or 
where they do not have a local ISP and must pay long distance toll rates to 
connect. Although there are many implementations of UUCP running on a wide 
variety of hardware platforms and operating systems, overall, they are highly 
compatible.
</para>

<para>
However, as with most software that has somehow become &ldquo;standard&rdquo;
over the years, there is no UUCP that one would call <emphasis>the</emphasis>
UUCP. It has undergone a steady evolution since the first version was
implemented in 1976.  Currently, there are two major species that differ
mainly in their hardware support and configuration. Of these two,
various implementations exist, each varying slightly from its siblings.
</para>

<para>
One species is known as Version 2 UUCP, which dates back to a 1977
implementation by Mike Lesk, David A. Novitz, and Greg Chesson. Although it
is fairly old, it is still frequently used. Recent implementations of
Version 2 provide much of the comfort that the newer UUCP species do.
</para>

<para>
The second species was developed in 1983 and is commonly referred to
as BNU (Basic Networking Utilities) or HoneyDanBer UUCP. The latter
name is derived from the authors' names (P. Honeyman, D. A. Novitz,
and B. E. Redman) and is often shortened further to HDB, which is the
term we'll use in this chapter. HDB was conceived to eliminate some of
Version 2 UUCP's deficiencies.  For example, new transfer protocols
were added, and the spool directory was split so that now there is one
directory for each site with which you have UUCP traffic.
</para>

<para>
<indexterm><primary>Taylor, Ian</primary></indexterm>
The implementation of UUCP currently distributed with Linux is Taylor
UUCP 1.06, which is the version this
chapter is based upon.<footnote id="X-087-2-FNUU01"><para>
Written and copyrighted by Ian Taylor, 1995.
</para>
</footnote>  Taylor UUCP Version 1.06 was released in August 1995.
Apart from traditional configuration files, Taylor UUCP can also be compiled
to understand the newstyle&mdash;a.k.a. Taylor&mdash;configuration files.
</para>

<para>
Taylor UUCP is usually compiled for HDB compatibility, the Taylor 
configuration scheme, or both.  Because the Taylor scheme is much more 
flexible and probably easier to understand than the often obscure HDB 
configuration files, we will describe the Taylor scheme below.
</para>

<para>
This chapter is not designed to exhaustively describe the command-line
options for the UUCP commands and what they do, but to give you an
introduction to how to set up a working UUCP node. The first section gives
a gentle introduction about how UUCP implements remote execution and file
transfers. If you are not entirely new to UUCP, you might want to skip to
the section <xref linkend="X-087-2-uucp.config.files">&rdquo; later in this 
chapter, which explains the various files used to set up UUCP.
</para>

<para>
We will, however, assume that you are familiar with the user programs of
the UUCP suite, <command>uucp</command> and <command>uux</command>.
For a description, refer to the online manual pages.
</para>

<para>
<INDEXTERM><PRIMARY>uucico command</PRIMARY></INDEXTERM>
Besides the publicly accessible programs <command>uucp</command> and
<command>uux</command>, the UUCP suite contains a number of commands used
for administrative purposes only. They are used to monitor UUCP traffic
across your node, remove old log files, or compile statistics. None of these
will be described here because they are peripheral to the main tasks of UUCP.
Besides, they're well documented and fairly easy to understand; refer to 
the manual pages for more information. However, there
is a third category, which comprise the actual UUCP
&ldquo;work horses.&rdquo;  They are called <command>uucico</command>
(where <emphasis>cico</emphasis> stands for copy-in copy-out), and
<command>uuxqt</command>, which executes jobs sent from remote systems.
We concentrate on these two important programs in this chapter.
</para>

<para>
If you're not satisfied with our coverage of these topics, you should read
the documentation that comes with the UUCP package.  This is a set of
Texinfo files that describe the setup using the Taylor configuration
scheme. You can convert the Texinfo files into a <command>dvi</command> file 
using the <command>texi2dvi</command> (found in the Texinfo package in your 
distribution) and view the <command>dvi</command> file using the 
<command>xdvi</command> command.
</para>

<para>
<indexterm><primary>HOWTOs</primary><secondary>UUCP</secondary></indexterm>
Guylhem Aznar's UUCP-HOWTO is another good source for information about UUCP 
in a Linux environment. It is available at any Linux Documentation
Project mirror and is posted regularly to
<systemitem role="newsgroup">comp.os.linux.answers</systemitem>.
</para>

<para>
<indexterm><primary>newsgroups</primary><secondary>comp.mail.uucp</secondary></indexterm> 
<INDEXTERM><PRIMARY>comp.mail.uucp</PRIMARY></INDEXTERM>
There's also a newsgroup for the discussion of UUCP called <systemitem
role="newsgroup">comp.mail.uucp</systemitem>. If you have questions
specific to Taylor UUCP, you may be better off asking them there,
rather than on the <systemitem
role="newsgroup">comp.os.linux.*</systemitem> groups.
</para>

<sect1 id="X-087-2-uucp.intro.grades"><title>UUCP Transfers and Remote Execution</title>

<para>
<indexterm><primary>jobs (UUCP)</primary></indexterm> 
<INDEXTERM><PRIMARY>UUCP</PRIMARY><SECONDARY>jobs</SECONDARY></INDEXTERM>
<indexterm><primary>Taylor UUCP</primary><secondary>job</secondary></indexterm>
The concept of jobs is vital to understanding UUCP.
Every transfer that a user initiates with <command>uucp</command> or
<command>uux</command> is called a <command>job</command>. It is made up of 
a command to be executed on a remote system, a collection of files to 
be transferred between sites, or both.
</para>

<para>
As an example, the following command makes UUCP copy the file
<filename>netguide.ps</filename> to a remote host named
<systemitem role="sitename">pablo</systemitem> and execute the
<command>lpr</command> command on
<systemitem role="sitename">pablo</systemitem>
to print the file:
</para>

<para>
<screen>
$ <userinput>uux -r pablo!lpr !netguide.ps</userinput>
</screen>
</para>

<para>
<indexterm><primary>spool directory</primary></indexterm> 
<indexterm><primary>spooling</primary></indexterm> 
<indexterm><primary>Taylor UUCP</primary><secondary>spool directory</secondary></indexterm>
UUCP does not generally call the remote system immediately to execute a job
(or else you could make do with <command>kermit</command>). Instead, it
temporarily stores the job description away. This is called
<emphasis>spooling</emphasis>. The directory tree under which jobs are stored
is therefore called the <emphasis>spool directory</emphasis> and is generally
located in <filename>/var/spool/uucp</filename>. In our example, the job
description would contain information about the remote command to be executed
(<command>lpr</command>), the user who requested the execution, and a couple
of other items. In addition to the job description, UUCP has to store the
input file <filename>netguide.ps</filename>.
</para>

<para>
The exact location and naming of spool files may vary, depending on
some compile-time options. HDB-compatible UUCPs generally store spool
files in a <filename>/var/spool/uucp</filename> subdirectory with the name
of the remote site. When compiled for Taylor configuration, UUCP creates
subdirectories below the site-specific spool directory for different types
of spool files.
</para>

<para>
At regular intervals, UUCP dials up the remote system.  When a connection to
the remote machine is established, UUCP transfers the files describing the
job, plus any input files.  The incoming jobs will not be executed
immediately, but only after the connection terminates. Execution is handled 
by <command>uuxqt</command>, which also takes care of forwarding any jobs that
are designated for another site.
</para>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>priorities</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>spool grade</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>job</secondary></indexterm>
To distinguish between more and less important jobs, UUCP associates a
<emphasis>grade</emphasis> with each job. This is a single digit ranging
from 0 through 9, A through Z, and a through z, in decreasing precedence. Mail
is customarily spooled with grade B or C, while news is spooled with grade
N. Jobs with higher grades are transferred earlier. Grades may be assigned
using the <option>&ndash;g</option> flag when invoking <command>uucp</command>
or <command>uux</command>.
</para>

<para>
You can also prohibit the transfer of jobs below a given grade at certain
times. To do this we set the <emphasis>maximum spool grade</emphasis>
that will be prohibited during a conversation. The maximum spool grade 
defaults to z, meaning all grades will be transferred every time. Note the 
semantic ambiguity here: a file is transferred only if it has a grade 
<emphasis>equal to</emphasis> or <emphasis>above</emphasis> the maximum spool grade threshold.
</para>

<sect2 id="X-087-2-uucico.connect"><title>The Inner Workings of uucico</title>
<para>
<indexterm><primary>Taylor UUCP</primary><secondary>uucico</secondary></indexterm>
<indexterm><primary>uucico command</primary></indexterm> 
To understand why <command>uucico</command> needs to know particular 
information, a quick description of how it actually connects to a remote 
system is helpful.
</para>

<para>
<indexterm><primary>gethostbyname(&thinsp;)</primary><secondary>uucico and</secondary></indexterm> 
When you execute <command>uucico -s <replaceable>system</replaceable></command>
from the command line, <command>uucico</command> first has to connect
physically. The actions taken depend on the type of connection to
open. Thus, when using a telephone line, it has to find a modem and dial
out. Over TCP, it has to call <function>gethostbyname</function> to convert
the name to a network address, find out which port to open, and bind the
address to the corresponding socket.
</para>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>master</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>slave</secondary></indexterm>
A successful connection is followed by authorization. This procedure 
generally consists of the remote system
asking for a login name and possibly a password. This exchange is commonly
called the <emphasis>login chat</emphasis>. The authorization procedure is
performed either by the usual
<command>getty/login</command> suite,
or on TCP sockets by <command>uucico</command> itself.  If authorization
succeeds, the remote end fires up <command>uucico</command>. The local copy of
<command>uucico</command> that initiated the connection is referred to as
<emphasis>master</emphasis>, and the remote copy as <emphasis>slave</emphasis>.
</para>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>call sequence check</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>handshake</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>protocols</secondary></indexterm>
<indexterm><primary>call sequence checks</primary></indexterm> 
Next follows the <emphasis>handshake phase</emphasis>&thinsp;: the master sends
its hostname plus several flags.  The slave checks this hostname for
permission to log in, send, and receive files, etc.  The flags describe
(among other things) the maximum grade of spool files to transfer. If
enabled, a conversation count or <emphasis>call sequence number</emphasis>
check takes place here. With this feature, both sites maintain a count of
successful connections, which are compared. If they do not match, the
handshake fails. This is useful to protect yourself against impostors.
</para>

<para>
Finally, the two <command>uucico</command>s try to agree on a common
<emphasis>transfer protocol</emphasis>. This protocol governs the way data is
transferred, checked for consistency, and retransmitted in case of an error.
There is a need for different protocols because of the differing types of
connections supported. For example, telephone lines require a
&ldquo;safe&rdquo; protocol, which is pessimistic about errors, while TCP
transmission is inherently reliable and can use a more efficient protocol that
foregoes most extra error checking.
</para>

<para>
After the handshake is complete, the actual transmission phase begins.
Both ends turn on the selected protocol driver. At this point, the drivers
possibly perform a protocol-specific initialization sequence.
</para>

<para>
The master then sends all files queued for the remote system whose
spool grade is high enough. When it has finished, it informs the slave
that it is done and that the slave may now hang up. The slave now can
either agree to hang up or take over the conversation.  This is a
change of roles: now the remote system becomes master, and the local one
becomes slave. The new master now sends its files.  When done, both
<command>uucico</command>&thinsp;s exchange termination messages and close the
connection.
</para>

<para>
If you need additional information on UUCP, please refer to the
source code. There is also a really antique article floating around the Net, 
written by David A. Novitz, which gives a detailed description of the UUCP
protocol.<footnote id="X-087-2-FNUU02"><para>
It's also included in the 4.4BSD <emphasis>System Manager's Manual</emphasis>.
</para>
</footnote> The Taylor UUCP FAQ also
discusses some details UUCP's implementation. It is posted to
<systemitem role="newsgroup">comp.mail.uucp</systemitem> regularly.


</para>

</sect2>

<sect2><title>uucico Command-line Options</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>calling out</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>logging and debugging</secondary></indexterm>
<indexterm><primary>debugging</primary><secondary>UUCP setup</secondary></indexterm>
<indexterm><primary>uucico command</primary><secondary>command-line options</secondary></indexterm> 
In this section, we describe the most important command-line options for
<command>uucico</command>&thinsp;:
</para>

<para>
<variablelist>

<varlistentry><term><option>&ndash; &ndash; system, &ndash;s <replaceable>system</replaceable></option></term>
<listitem><para>
Calls the named <replaceable>system</replaceable> unless prohibited by call-time
restrictions.
</para>
</listitem>
</varlistentry>

<varlistentry><term><option>&ndash;S <replaceable>system</replaceable></option></term>
<listitem><para>
Calls the named <replaceable>system</replaceable> unconditionally.
</para>
</listitem>
</varlistentry>

<varlistentry><term><option>&ndash; &ndash;master, &ndash;r1</option></term>
<listitem><para>
Starts <command>uucico</command> in master mode. This is the default when
<option>&ndash;s</option> or <option>&ndash;S</option> is given. All by itself,
the <option>&ndash;r1</option> option causes <command>uucico</command> to try
to call all systems in the <filename>sys</filename> file described in the 
next section of this chapter, unless prohibited by call or retry time 
restrictions.
</para>
</listitem>
</varlistentry>

<varlistentry><term><option>&ndash; &ndash;slave, &ndash;r0</option></term>
<listitem><para>
Starts <command>uucico</command> in slave mode. This is the default
when no <option>&ndash;s</option> or <option>&ndash;S</option> is
given.  In slave mode, either standard input/output are assumed to be
connected to a serial port, or the TCP port specified by the
<option>&ndash;p</option> option is used.
</para>
</listitem>
</varlistentry>

<varlistentry><term><option>&ndash; &ndash;ifwork, &ndash;C</option></term>
<listitem><para>
This option supplements <option>&ndash;s</option> or
<option>&ndash;S</option> and tells <command>uucico</command> to call the
named system only if there are jobs spooled for it.
</para>
</listitem>
</varlistentry>

<varlistentry><term><option>&ndash; &ndash;debug <replaceable>type</replaceable>, &ndash;x <replaceable>type</replaceable></option>, <option>&ndash;X <replaceable>type</replaceable></option></term>
<listitem><para>
Turns on debugging of the specified type. Several types can be given as a
comma-separated list. The following types are valid:
<systemitem role="keyword">abnormal</systemitem>,
<systemitem role="keyword">chat</systemitem>,
<systemitem role="keyword">handshake</systemitem>,
<systemitem role="keyword">uucp-proto</systemitem>,
<systemitem role="keyword">proto</systemitem>,
<systemitem role="keyword">port</systemitem>,
<systemitem role="keyword">config</systemitem>,
<systemitem role="keyword">spooldir</systemitem>,
<systemitem role="keyword">execute</systemitem>,
<systemitem role="keyword">incoming</systemitem>, and
<systemitem role="keyword">outgoing</systemitem>.
Using <systemitem role="keyword">all</systemitem> turns on all options.  For
compatibility with other UUCP implementations, a number may be specified
instead, which turns on debugging for the first <replaceable>n</replaceable>
items from the above list.
</para>

<para>
Debugging messages will be logged to the <filename>Debug</filename>
file below <filename>/var/spool/uucp</filename>.
</para>

</listitem>
</varlistentry>

</variablelist>
</para>

</sect2>

</sect1>

<sect1 id="X-087-2-uucp.config.files"><title>UUCP Configuration Files</title>

<para>
<indexterm id="chuu.config.files.uucp" class="startofrange"><primary>configuration files</primary><secondary>UUCP</secondary></indexterm>
<indexterm id="idx-UUCPconfigurationfiles-1" class="startofrange"><primary>Taylor UUCP</primary><secondary>configuration files</secondary></indexterm>
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
<filename>/usr/lib/uucp</filename> directory. Most of these files are
used only when dialing out.
</para>

<sect2><title>A Gentle Introduction to Taylor UUCP</title>

<para>
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).
</para>

<para>
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.
</para>

<para>
All files described in this section are kept in
<filename>/etc/uucp</filename> 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 <filename>README</filename> file in
<filename>/usr/lib/uucp</filename>.
</para>

<para>
For UUCP to work properly, these files must be owned by the
<systemitem role="userid">uucp</systemitem> 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
<systemitem role="userid">uucp</systemitem>, you must make sure the
<command>uuchk</command> program is
<emphasis>not</emphasis>. Otherwise, users will be able to display
system passwords even though the files have mode 600.
</para>

<para>
The central UUCP configuration file is
<filename>/etc/uucp/config</filename>, 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 <systemitem
role="sitename">vstout</systemitem> as their UUCP gateway:
</para>

<para>
<screen>
# /etc/uucp/config - UUCP main configuration file
nodename         vstout
</screen>
</para>

<para>
<?troff .hw specific>
The <filename>sys</filename> 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 <systemitem role="sitename">pablo</systemitem> 
would look like this:
</para>

<para>
<screen>
# /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
</screen>
</para>
<?troff .Nd 10>

<para>
<systemitem role="keyword">time</systemitem> specifies the times at
which the remote system may be called.  <systemitem
role="keyword">chat</systemitem> describes the login chat
scripts&mdash;the sequence of strings that must be exchanged to allow
<command>uucico</command> to log into <systemitem
role="sitename">pablo</systemitem>. We will get back to chat scripts
later. The <systemitem role="keyword">port</systemitem> keyword simply
names an entry in the <filename>port</filename> file.  (Refer to <xref
linkend="X-087-2-uucp.fig.files">.) You can assign whatever name you
like as long as it refers to a valid entry in
<filename>port</filename>.
</para>

<para>
The <filename>port</filename> 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
<filename>/dev/ttyS1</filename> (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 <filename>sys</filename> file:
</para>

<para>
<screen>
# /etc/uucp/port - UUCP ports
# /dev/ttyS1 (COM2)
port            serial1
type            modem
device          /dev/ttyS1
speed           38400
dialer          nakwell
</screen>
</para>

<para>
The information pertaining to the dialers is kept in yet another file
called&mdash;you guessed it&mdash;<filename>dial</filename>. 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:
</para>

<para>
<screen>
# /etc/uucp/dial - per-dialer information
# NakWell modems
dialer          nakwell
chat            "" AT&amp;F OK ATDT\T CONNECT
</screen>
</para>

<para>
The line starting with <systemitem role="keyword">chat</systemitem>
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 <systemitem role="keyword">\T</systemitem>
sequence will be replaced with the phone number by
<command>uucico</command>.
</para>

<para>
To give you a rough idea how <command>uucico</command> deals with these
configuration files, assume you issue the following command:

<screen>
$ <userinput>uucico -s pablo</userinput>
</screen>
</para>

<para>
The first thing <command>uucico</command> does is look up <systemitem
role="sitename">pablo</systemitem> in the <filename>sys</filename>
file. From the <filename>sys</filename> file entry for <systemitem
role="sitename">pablo</systemitem>, it sees that it should use the
<systemitem role="keyword">serial1</systemitem> port to establish the
connection.  The <filename>port</filename> file tells
<command>uucico</command> that this is a modem port, and that it has a
NakWell modem attached.
</para>

<para>
<command>uucico</command> now searches <filename>dial</filename> for
the entry describing the NakWell modem, and having found one, opens
the serial port <filename>/dev/cua1</filename> and executes the dialer
chat. That is, it sends <command>AT&amp;F</command>, waits for the
<command>OK</command> response, etc. When encountering the string
<systemitem role="keyword">\T</systemitem>, it substitutes the phone
number (555-22112) extracted from the <filename>sys</filename> file.
</para>

<para>
After the modem returns <command>CONNECT</command>, the connection has been
established, and the modem chat is complete. <command>uucico</command> now
returns to the <filename>sys</filename> file and executes the login chat. In
our example, it would wait for the <command>login:</command> prompt, then send
its username (<emphasis role=bold>vstout</emphasis>), wait for the
<command>password:</command> prompt, and send its password
(<command>lorca</command>).
</para>

<para>
<?troff .hw section>
After completing authorization, the remote end is assumed to fire up its own
<command>uucico</command>. The two then enter the handshake phase
described in the previous section.
</para>

<para>
<xref linkend="X-087-2-uucp.fig.files"> illustrates the dependencies among 
configuration files.
</para>

<figure id="X-087-2-uucp.fig.files">
<title>Interaction of Taylor UUCP configuration files</title>
<!-- <graphic fileref="lag2_1601.jpg"></graphic> -->
<!-- 2016-01-28; MAB, TLDP -->
<mediaobject> 
  <imageobject>
    <imagedata fileref="images/lag2_1601.jpg" format="jpg">
  </imageobject>
  <imageobject>
    <imagedata fileref="images/lag2_1601.eps" format="eps">
  </imageobject>
</mediaobject>
</figure>

</sect2>

<sect2 id="X-087-2-uucp.starting.parameters"><title>What UUCP Needs to Know</title>

<para>
Before you start writing the UUCP configuration files, you have to gather some
information that UUCP requires.
</para>

<para>
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 <filename>/dev/ttyS0</filename> through
<filename>/dev/ttyS3</filename>.  Some distributions, such as
Slackware, create a link called <filename>/dev/modem</filename> to the
appropriate <filename>ttyS*</filename> device file, and configure
<command>kermit</command>, <command>seyon</command>, and any other
communication programs to use this generic file. In this case, you
should use <filename>/dev/modem</filename> in your UUCP configuration,
too.
</para>

<para>
The reason for using a symbolic link is that all dial-out programs use
so-called <emphasis>lock files</emphasis> to signal when a serial port is
in use. The names of these lock files are a concatenation of the string
<filename>LCK..</filename> and the device filename, for instance
<filename>LCK..ttyS1</filename>. 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 <filename>crontab</filename> entry.
For details on serial port setup, please refer to
<xref linkend="X-087-2-serial">.
</para>

<para>
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.
</para>

<para>
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.<footnote id="X-087-2-FNUU04"><para>
If you're just going to try out UUCP, get the number of an archive site near
you. Write down the login and password&mdash;they're public to make anonymous
downloads possible. In most cases, they're something like
<systemitem role="userid">uucp/uucp</systemitem> or
<systemitem role="userid">nuucp/uucp</systemitem>.
</para>
</footnote>

</para>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>logging in</secondary></indexterm>
You also have to know <emphasis>exactly</emphasis> how to log into the
system. Do you have to press the Enter key before the login prompt appears?
Does it display <literal>login:</literal> or <literal>user:</literal>? This
is necessary for composing the <emphasis>chat script</emphasis>. If you don't
know, or if the usual chat script fails, try to call the system with a terminal
program like <command>kermit</command> or <command>minicom</command> and 
record exactly what you have to do.
</para>
</sect2>

<sect2 id="X-087-2-uucp.starting.sitename"><title>Site Naming</title>

<para>
<indexterm><primary>addresses</primary><secondary>UUCP hostname</secondary></indexterm>
<indexterm><primary>choosing</primary><secondary>UUCP hostname</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>hostname</secondary></indexterm>
<indexterm><primary>hostname</primary><secondary>UUCP</secondary></indexterm>
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.<footnote id="X-087-2-FNUU05"><para>
The only limitation is that it shouldn't be longer than seven characters, so
as to not confuse UUCP implementations that run on an operating system that
imposes a narrow limit on filenames. Names that are longer than seven
characters are often truncated by UUCP. Some versions even limit the name to
six characters.
</para>
</footnote>

</para>

<para>
However, if you use UUCP for a mail or news link, you should think
about having the name registered with the UUCP Mapping Project.<footnote id="X-087-2-FNUU06"><para> The UUCP Mapping Project
registers all UUCP hostnames worldwide and makes sure they are
unique.  </para></footnote> The UUCP Mapping Project is described in
<xref linkend="X-087-2-mail">. Even if you participate in a domain,
you might consider having an official UUCP name for your site.
</para>

<para>
Frequently, people choose their UUCP name to match the first component of
their fully qualified domain name. Suppose your site's domain address is
<systemitem role="sitename">swim.twobirds.com</systemitem>; then your UUCP
hostname would be <systemitem role="sitename">swim</systemitem>. 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.
</para>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>Mapping Project</secondary></indexterm>
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.
</para>

<para>
By default, the UUCP suite uses the name set by <command>hostname</command> as
the site's UUCP name. This name is commonly set by a command on the boot
time <filename>rc</filename> scripts, and is usually stored in the
<filename>/etc/hostname</filename>. If your UUCP name is different from what
you set your hostname to, you have to use the
<command>hostname</command> option in the
<filename>config</filename> file to tell <command>uucico</command> about your
UUCP name. This is described next.
</para>
</sect2>

<sect2><title>Taylor Configuration Files</title>
<para>
<indexterm><primary>configuration files</primary><secondary>Taylor UUCP</secondary></indexterm> 
We now return to the configuration files. Taylor UUCP gets its information
from the following files:

<variablelist>
<varlistentry><term><filename>config</filename></term>
<listitem><para>
This is the main configuration file. You can define your site's UUCP name here.
</para>
</listitem>
</varlistentry>

<varlistentry><term><filename>sys</filename></term>
<listitem><para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry><term><filename>port</filename></term>
<listitem><para>
This file contains entries describing each available port, together with the line speed
supported and the dialer to be used.
</para>
</listitem>
</varlistentry>

<varlistentry><term><filename>dial</filename></term>
<listitem><para>
This file describes dialers used to establish a telephone connection.
</para>
</listitem>
</varlistentry>

<varlistentry><term><filename>dialcode</filename></term>
<listitem><para>
This file contains expansions for symbolic dial codes.
</para>
</listitem>
</varlistentry>

<varlistentry><term><filename>call</filename></term>
<listitem><para>
This file contains the login name and password to be used when calling a system.
Rarely used.
</para>
</listitem>
</varlistentry>

<varlistentry><term><filename>passwd</filename></term>
<listitem><para>
This file contains login names and passwords that systems may use when logging in. It is used only when <command>uucico</command> does its own password
checking.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>
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: <literal>\#</literal>.
</para>

<para>
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.
</para>

<para>
<indexterm><primary>displaying</primary><secondary>UUCP configuration</secondary></indexterm>
<indexterm><primary>checking</primary><secondary>UUCP</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>checking</secondary></indexterm>
When you think you have configured your UUCP system completely, you can check
your configuration using the <command>uuchk</command> tool (located in
<filename>/usr/lib/uucp</filename>). <command>uuchk</command> reads your
configuration files and prints out a detailed report of the configuration
values used for each system.
</para>

</sect2>

<sect2><title>General Configuration Options Using the config File</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>configuration files</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>hostname</secondary></indexterm>
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 <command>hostname</command>
command, but it is generally a good idea to set the UUCP name explicitly. Here's a sample <filename>config</filename> file:

<screen>
# /usr/lib/uucp/config - UUCP main configuration file
hostname        vstout
</screen>
</para>

<para>
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 &ldquo;Anonymous UUCP.&rdquo;
</para>

</sect2>

<sect2 id="X-087-2-uucp.systems.file"><title>How to Tell UUCP About Other Systems Using the <?lb>sys File</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>sys file</secondary></indexterm>
<indexterm id="idx-UUCPremotesystem-1" class="startofrange"><primary>Taylor UUCP</primary><secondary>remote system</secondary></indexterm>
The <filename>sys</filename> file describes the systems that your
machine knows about. An entry is introduced by the <systemitem
role="keyword">system</systemitem> keyword; the subsequent lines up to
the next <systemitem role="keyword">system</systemitem> directive
detail the parameters specific to that site. Commonly, a system entry
defines parameters such as the telephone number and login chat.
</para>

<para>
Parameters before the very first <systemitem
role="keyword">system</systemitem> line set default values used for
all systems. Usually, you set protocol parameters and the like in
the defaults section.
</para>
<para>

The most prominent fields are discussed in detail in the following sections.
</para>
<?troff .Nd 10>

<sect3><title>System name</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>remote system</secondary></indexterm>
The <emphasis>system</emphasis> command names the remote
system. You must specify the correct name of the remote system, not an alias
you invented, because <command>uucico</command> will check it against what
the remote system says it is called when you log
on.<footnote id="X-087-2-FNUU07"><para>
Older Version 2 UUCPs don't broadcast their name when being called; however,
newer implementations often do, and so does Taylor UUCP.
</para>
</footnote>

</para>

<para>
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
<command>uucico</command> should try in turn), you can specify
<emphasis>alternates</emphasis>, which we'll describe after the basic 
configuration options.
</para>

</sect3>

<sect3><title>Telephone number</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>phone number</secondary></indexterm>
If the remote system is to be reached over a telephone line, the
<systemitem role="keyword">phone</systemitem> field specifies the number the
modem should dial. It may contain several tokens interpreted by
<command>uucico</command>'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.<footnote id="X-087-2-FNUU08"><para>
For instance, most companies' private installations require you to dial a 0 or
9 to get a line to the outside.
</para>
</footnote>

</para>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>dialcode file</secondary></indexterm>
It is often convenient to use names instead of numbers to describe
area dialing codes. The <filename>dialcode</filename> 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
<filename>dialcode</filename> file:
</para>

<para>
<screen>
# /usr/lib/uucp/dialcode - dialcode translation
Bogoham         024881
Coxton          035119
</screen>
</para>

<para>
With these translations, you can use a phone number such as
<systemitem role="keyword">Bogoham7732</systemitem> in the
<filename>sys</filename> 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.
</para>

</sect3>

<sect3><title>port and speed</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>device</secondary></indexterm>
The <systemitem role="keyword">port</systemitem> and <systemitem
role="keyword">speed</systemitem> options are used to select the
device used for calling the remote system and the maximum speed to
which the device should be set.<footnote id="X-087-2-FNUU09"><para>
The bit rate of the <emphasis>tty</emphasis> must be at least as high as the maximum
transfer speed.
</para>
</footnote>
A <systemitem role="keyword">system</systemitem> entry may
use either option alone or both options in conjunction. When looking
up a suitable device in the <filename>port</filename> file, only ports that have a matching port name and/or speed range are selected.
</para>

<para>
Generally, using the <systemitem role="keyword">speed</systemitem>
option only should suffice. If you have only one serial device defined
in <filename>port</filename>, <command>uucico</command> 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
<command>uucico</command> finds that there are several matches, it
tries each device in turn until it finds an unused one.
</para>

</sect3>

<sect3><title>The login chat</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>logging in</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>login chat</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>chat scripts</secondary></indexterm>
<indexterm><primary>chat script</primary><secondary>UUCP</secondary></indexterm>
We already encountered the login chat script, which tells
<command>uucico</command> how to log in to the remote system. It
consists of a list of tokens specifying strings expected and sent by
the local <command>uucico</command> process. <command>uucico</command>
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.  <command>uucico</command> automatically appends a
carriage return character (<systemitem role="keyword">\r</systemitem>)
to any send string. Thus, a simple chat script would look like:

<screen>
 ogin: vstout ssword: catch22
</screen>
</para>

<para>
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 <command>Login:</command> instead of
<command>login:</command>. If the string you are expecting or sending
contains spaces or other white-space characters, you must use quotes
to surround the text.
</para>

<para>
<command>uucico</command> also allows for some sort of conditional execution. 
Let's say the remote machine's <command>getty</command>
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,
<literal>""</literal>, tells UUCP to not wait for anything, but to continue 
with the next send string:

<screen>
 "" \n\r\d\r\n\c ogin:-BREAK-ogin: vstout ssword: catch22
</screen>
</para>

<para>
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:

<variablelist>
<varlistentry><term><literal>""</literal></term>
<listitem><para>
The empty string. It tells <command>uucico</command> to not wait for anything,
but to proceed with the next send string immediately.
</para>
</listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">\t</systemitem></term>
<listitem><para>
Tab character.
</para>
</listitem>
</varlistentry>
<?troff .wcon_off>
<varlistentry><term><systemitem role="keyword">\r</systemitem></term>
<listitem><para>
Carriage return character.
</para>
</listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">\s</systemitem></term>
<listitem><para>
Space character. You need this to embed spaces in a chat string.
</para>
</listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">\n</systemitem></term>
<listitem><para>
Newline character.
</para>
</listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">\\</systemitem></term>
<listitem><para>
Backslash character.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>
On send strings, the following escape characters and strings are legal in
addition to the above:

<variablelist>
<varlistentry><term><systemitem role="keyword">EOT</systemitem></term>
<listitem><para>
End of transmission character (<command>^D</command>).
</para>
</listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">BREAK</systemitem></term>
<listitem><para>
Break character.
</para>
</listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">\c</systemitem></term>
<listitem><para>
Suppress sending of carriage return at end of string.
</para>
</listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">\d</systemitem></term>
<listitem><para>
Delay sending for 1 second.
</para>
</listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">\E</systemitem></term>
<listitem><para>
Enable echo checking. This requires <command>uucico</command> 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.
</para></listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">\e</systemitem></term>
<listitem><para>
Disable echo checking.
</para></listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">\K</systemitem></term>
<listitem><para>
Same as <systemitem role="keyword">BREAK</systemitem>.
</para></listitem>
</varlistentry>

<varlistentry><term><systemitem role="keyword">\p</systemitem></term>
<listitem><para>
Pause for fraction of a second.
</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect3>

<sect3><title>Alternates</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>alternates</secondary></indexterm>
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 <emphasis>alternate</emphasis>.
</para>

<para>
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 <systemitem role="keyword">alternate</systemitem>.
</para>

<para>
To use two phone numbers for <systemitem role="sitename">pablo</systemitem>,
you would modify its <filename>sys</filename> entry in the following way:

<screen>
system       pablo
phone        123-456
.. entries as above ...
alternate
phone        123-455
</screen>
</para>

<para>
When calling <systemitem role="sitename">pablo</systemitem>,
<command>uucico</command> 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.
</para>
</sect3>

<sect3><title>Restricting call times</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>restrict</secondary><tertiary>call time</tertiary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>call time</secondary></indexterm>
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 <command>uucico</command> the
<option>&ndash;S</option> or <option>&ndash;f</option> option.
</para>

<para>
By default, Taylor UUCP disallows connections at any time, so you
<emphasis>have</emphasis> to use some sort of time specification in the
<filename>sys</filename> file. If you don't care about call time restrictions,
you can specify the <command>time</command> option with a
value of <systemitem role="keyword">Any</systemitem> in your
<filename>sys</filename> file.
</para>

<para>
The simplest way to restrict call time is to include a
<systemitem role="keyword">time</systemitem> entry, followed by a string made
up of a day and a time subfield. Day may be any combination of
<systemitem role="keyword">Mo, Tu, We, Th, Fr, Sa,</systemitem> and <systemitem role="keyword">Su</systemitem>. You can 
also specify <systemitem role="keyword">Any</systemitem>,
<systemitem role="keyword">Never</systemitem>, or
<systemitem role="keyword">Wk</systemitem> 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:

<screen>
time            MoWe0300-0730,Fr1805-2200
</screen>
</para>

<para>
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 <systemitem role="keyword">Mo1830-0600</systemitem>, it actually
means Monday, between midnight and 6:00 a.m. and between 6:30 p.m. and midnight.
</para>

<para>
The special time strings <systemitem role="keyword">Any</systemitem> and
<systemitem role="keyword">Never</systemitem> mean what they say: calls may be
placed at any or no time, respectively.
</para>

<para>
Taylor UUCP also has a number of special tokens you may use in time strings,
such as <systemitem role="keyword">NonPeak</systemitem> and
<systemitem role="keyword">Night</systemitem>.  These special tokens are shorthand for
<systemitem role="keyword">Any2300-0800,SaSu0800-1700</systemitem> and
<systemitem role="keyword">Any1800-0700,SaSu</systemitem>, respectively.
</para>  

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>retry interval</secondary></indexterm>
The <emphasis>time</emphasis> command takes an optional
second argument that describes a retry time in minutes. When an attempt to
establish a connection fails, <command>uucico</command> 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, <command>uucico</command> will
refuse to call the remote system within 5 minutes after the last failure. By
default, <command>uucico</command> uses an exponential backoff scheme, where
the retry interval increases with each repeated failure.
</para>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>priorities</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>spool grade</secondary></indexterm>
The <command>timegrade</command> command allows you to
attach a maximum spool grade to a schedule. For instance, assume you have the
following <command>timegrade</command> commands in a
<systemitem role="keyword">system</systemitem> entry:

<screen>
timegrade           N Wk1900-0700,SaSu 
timegrade           C Any
</screen>
</para>
<?troff .Nd 10>

<para>
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.
</para>

<para>
Just like <command>time</command>, the <command>timegrade</command> command takes a retry interval in minutes as an optional third argument.
</para>

<para>
However, a caveat about spool grades is in order here. First, the
<command>timegrade</command> option applies only to what
<emphasis>your</emphasis> systems sends; the remote system may still transfer
anything it likes.  You can use the
<command>call-timegrade</command> option to explicitly
request it to send only jobs above some given spool grade; but there's no
guarantee it will obey this request.<footnote id="X-087-2-FNUU10"><para>
If the remote system runs Taylor UUCP, it will obey.
</para></footnote>
</para>

<para>
Similarly, the <replaceable>timegrade</replaceable> 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
<command>uucico</command> to restrict itself to a certain spool grade.
<indexterm class="endofrange" startref="idx-UUCPremotesystem-1">
</para>

</sect3>

</sect2>

<sect2><title>Identifying Available Devices Through the port File</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>port file</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>device</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>modem</secondary></indexterm>
The <filename>port</filename> file tells <command>uucico</command> about the
available ports. These are usually modem ports, but other types, such as direct
serial lines and TCP sockets, are supported as well.
</para>

<para>
Like the <filename>sys</filename> file, <filename>port</filename>
consists of separate entries starting with the keyword
<systemitem role="keyword">port</systemitem> followed by the port name. This
name may be used in the <filename>sys</filename> file's
<systemitem role="keyword">port</systemitem> statement. The name need not
be unique; if there are several ports with the same name,
<command>uucico</command> will try each in turn until it finds one that
is not currently being used.
</para>

<para>
The <command>port</command> command should be followed
immediately by the <systemitem role="keyword">type</systemitem> statement,
which indicates what type of port is described. Valid types are
<systemitem role="keyword">modem</systemitem>,
<systemitem role="keyword">direct</systemitem> for direct connections, and
<systemitem role="keyword">tcp</systemitem> for TCP sockets. If the
<command>port</command> command is missing, the port
type defaults to modem.
</para>

<para>
In this section, we cover only modem ports; TCP ports and direct lines are
discussed in a later section.
</para>
<?troff .wcon_off>
<para>
For modem and direct ports, you have to specify the device for calling out
using the <systemitem role="keyword">device</systemitem> directive. Usually,
this is the name of a device special file in the <filename>/dev</filename>
directory, like <filename>/dev/ttyS1</filename>.
</para>

<para>
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
<command>uucico</command> how to initialize the modem and make it dial
the desired number. Taylor UUCP keeps the descriptions of all dialers in a
<?troff .ne 10>
file named <filename>dial</filename>.  To use any of these, you have to specify
the dialer's name using the <command>dialer</command>
command.
</para>

<para>
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
<systemitem role="sitename">drop</systemitem> 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 <filename>port</filename> file that specifies a
different dialer. Now you can give the new port a different name, such as
<systemitem role="keyword">serial1-slow</systemitem>, and use the
<systemitem role="keyword">port</systemitem> directive in the
<systemitem role="sitename">drop</systemitem> system entry in
<filename>sys</filename>.
</para>

<para>
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:

<screen>
# 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
</screen>
</para>

<para>
The system entry for site <systemitem role="sitename">drop</systemitem> would
now give <systemitem role="keyword">serial1</systemitem> as the port name, but
request to use it at only 9,600 bps.  <command>uucico</command> 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.
</para>

</sect2>

<sect2><title>How to Dial a Number Using the dial File</title>

<para>

<indexterm><primary>Taylor UUCP</primary><secondary>dial file</secondary></indexterm>
<indexterm id="idx-UUCPmodem-1" class="startofrange"><primary>Taylor UUCP</primary><secondary>modem</secondary></indexterm>
The <filename>dial</filename> 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.
</para>
<?troff .wcon_off>

<para>
Nevertheless, different dialers or modems may require a different
configuration. You can describe each of them in the
<filename>dial</filename> file. Entries in <filename>dial</filename>
start with the <command>dialer</command> command
that gives the dialer's name.
</para>

<para>
The most important entry besides <command>dialer</command> is the modem chat, specified by the <command>chat</command> command. Similar to the
login chat, it consists of a sequence of strings
<command>uucico</command> 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 <systemitem
role="keyword">dialer</systemitem> entry shows a typical modem chat
for a Hayes-compatible modem:
</para>

<screen>
# NakWell modem; connect at high speed
dialer          nakwell         # dialer name
chat            "" AT&amp;F OK\r ATH1E0Q0 OK\r ATDT\T CONNECT
chat-fail       BUSY
chat-fail       ERROR
chat-fail       NO\sCARRIER
dtr-toggle      true
</screen>

<para>
The modem chat begins with <literal>""</literal>, the empty expect
string.  <command>uucico</command> therefore sends the first
command <command>AT&amp;F</command> right
away. <command>AT&amp;F</command> is the Hayes command to reset the
modem to factory default configuration.  <command>uucico</command>
then waits until the modem has sent <literal>OK</literal> and sends
the next command, which turns off local echo and the like. After the
modem returns <literal>OK</literal> again, <command>uucico</command>
sends the dialing command <command>ATDT</command>.  The escape
sequence <literal>\T</literal> in this string is replaced with the
phone number taken from the system entry <filename>sys</filename>
file. <command>uucico</command> then waits for the modem to return the
string <literal>CONNECT</literal>, which signals that a connection
with the remote modem has been established successfully.
</para>

<para>
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; <command>uucico</command> 
continues to wait for the expected string until it times out. The UUCP
log file therefore only shows a bland &ldquo;timed out in chat
script&rdquo; instead of the specific reason.
</para>

<para>
However, Taylor UUCP allows you to tell <command>uucico</command> about these
error messages using the <command>chat-fail</command>
command as shown above. When <command>uucico</command> detects a chat-fail
string while executing the modem chat, it aborts the call and logs the error
message in the UUCP log file.
</para>

<para>
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 
<systemitem role="keyword">dtr-toggle</systemitem> 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.<footnote id="X-087-2-FNUU11"><para>
Some modems don't seem to like this and occasionally hang.
</para>
</footnote>

</para>

<indexterm class="endofrange" startref="idx-UUCPmodem-1">

</sect2>

<sect2><title>UUCP Over TCP</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>over TCP/IP</secondary></indexterm>
<indexterm><primary>TCP (Transmission Control Protocol)</primary><secondary>UUCP</secondary></indexterm>
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.
</para>

<para>
In <filename>sys</filename>, you would specify a system to be called via TCP 
like this:

<screen>
system          gmu
address         news.groucho.edu
time            Any
port            tcp-conn
chat            ogin: vstout word: clouseau
</screen>
</para>

<para>
The <command>address</command> command gives the
IP address of the host or its fully qualified domain name.  The
corresponding <filename>port</filename> entry would read:

<screen>
port            tcp-conn
type            tcp
service         540
</screen>
</para>

<para>
The entry states that a TCP connection should be used when a
<filename>sys</filename> entry references
<systemitem role="keyword">tcp-conn</systemitem>, and that
<command>uucico</command> 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
<command>service</command> command. The port number
corresponding to this name will be looked up in
<filename>/etc/services</filename>. The common name for the UUCP service is
<systemitem role="keyword">uucpd</systemitem>.
</para>

</sect2>

<sect2><title>Using a Direct Connection</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>direct lines</secondary></indexterm>
Assume you use a direct line to connect your system
<systemitem role="sitename">vstout</systemitem> to
<systemitem role="sitename">tiny</systemitem>. Much like in the modem case,
you have to write a system entry in the <filename>sys</filename> file. The
<command>port</command> command identifies the serial port
<systemitem role="keyword">tiny</systemitem> is hooked up to:

<screen>
system          tiny
time            Any
port            direct1
speed           38400
chat            ogin: cathcart word: catch22
</screen>
</para>

<para>
In the <filename>port</filename> file, you have to describe the serial port
for the direct connection. A <systemitem role="keyword">dialer</systemitem>
entry is not needed because there's no need for dialing:

<screen>
port            direct1
type            direct
speed           38400
device		    /dev/ttyS1
</screen>
</para>

<indexterm class="endofrange" startref="idx-UUCPconfigurationfiles-1">
<indexterm class="endofrange" startref="chuu.config.files.uucp"> 
</sect2>
</sect1>

<sect1 id="X-087-2-uucp.permissions"><title>Controlling Access to UUCP Features</title>

<para>
<indexterm id="idx-securityUUCP-1" class="startofrange"><primary>security</primary><secondary>UUCP</secondary></indexterm>
<indexterm id="idx-accessUUCP-1" class="startofrange"><primary>access</primary><secondary>UUCP</secondary></indexterm>
UUCP is quite a flexible system. With that flexibility comes a need to
carefully control access to its features to prevent abuse, whether it be 
intentional or accidental. The primary features of concern to the UUCP 
administrator are remote command execution, file transfer, and forwarding. 
Taylor UUCP provides a means of limiting the freedom that remote UUCP hosts 
have in exercising each of these features. With careful selection of 
permissions, the UUCP administrator can ensure that the host's security is 
preserved.
</para>

<sect2><title>Command Execution</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>restrict</secondary><tertiary>command execution</tertiary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>command execution</secondary></indexterm>
UUCP's task is to copy files from one system to another and to request
execution of certain commands on remote hosts. Of course, you as an
administrator would want to control what rights you grant other
systems&mdash;allowing them to execute any command they choose on your system 
is definitely not a good idea.
</para>

<para>
<indexterm><primary>SMTP (Simple Mail Transfer Protocol)</primary><secondary>batched</secondary></indexterm>
<indexterm><primary>rmail command</primary></indexterm>
<indexterm><primary>rnews command</primary></indexterm>
<indexterm><primary>rsmtp</primary><secondary>command</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>mail</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>news</secondary></indexterm>
By default, the only commands Taylor UUCP allows other systems to execute on
your machine are <command>rmail</command> and <command>rnews</command>, which
are commonly used to exchange email and Usenet News over UUCP. To change the
set of commands for a particular system, you can use the
<systemitem role="keyword">commands</systemitem> keyword in the
<filename>sys</filename> file. Similarly, you may want to limit the search
path to just those directories containing the allowed commands. You can
change the search path allowed for a remote host with the
<systemitem role="keyword">command-path</systemitem> statement. For instance,
you may want to allow system
<systemitem role="sitename">pablo</systemitem> to execute the
<command>bsmtp</command> command in addition to <command>rmail</command>
and <command>rnews</command>:<footnote id="X-087-2-FNUU12"><para>
<command>bsmtp</command> is used to deliver mail with batched SMTP.
</para>
</footnote>

<screen>
system          pablo
...
commands        rmail rnews bsmtp
</screen>
</para>

</sect2>

<sect2><title>File Transfers</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>restrict</secondary><tertiary>file transfer</tertiary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>file transfer</secondary></indexterm>
Taylor UUCP also allows you to fine-tune file transfers in great
detail. At one extreme, you can disable transfers to and from a
particular system. Just set <systemitem
role="keyword">request</systemitem> to <systemitem
role="keyword">no</systemitem>, and the remote system will not be able
to either retrieve files from your system or send it any
files. Similarly, you can prohibit your users from transferring files
to or from a system by setting <systemitem
role="keyword">transfer</systemitem> to <systemitem
role="keyword">no</systemitem>.  By default, users on both the local
and the remote system are allowed to upload and download files.
</para>

<para>
In addition, you can configure the directories that files may be
copied to and from. Usually you will want to restrict access from
remote systems to a single directory hierarchy, but still allow your
users to send files from their home directory. Commonly, remote users are 
allowed to receive files only from the public UUCP directory
<filename>/var/spool/uucppublic</filename>.  This is the traditional
place to make files publicly available, very much like FTP servers on
the Internet.<footnote id="X-087-2-uucp-FNUU13"><para> You may use a
tilde (<literal>~</literal>) character to refer to the UUCP public
directory, but only in UUCP configuration files; outside it usually
translates to the user's home directory.
</para>
</footnote>
</para>

<para>
Taylor UUCP provides four different commands to configure the
directories for sending and receiving files. They are: 
<command>local-send</command>, which specifies the list of
directories a user may ask UUCP to send files from; 
<command>local-receive</command>, which gives the list of
directories a user may ask to receive files to; and 
<command>remote-send</command> and <command>remote-receive</command>, 
which do the analogous for
requests from a foreign system. Consider the following example:

<screen>
system          pablo
...
local-send      /home ~
local-receive   /home ~/receive
remote-send     ~ !~/incoming !~/receive
remote-receive  ~/incoming
</screen>
</para>

<para>
The <command>local-send</command> command allows
users on your host to send any files below <filename>/home</filename>
and from the public UUCP directory to <systemitem
role="sitename">pablo</systemitem>. The <command>local-receive</command> 
command allows them to
receive files either to the world-writable
<filename>receive</filename> directory in the
<filename>uucppublic</filename>, or any world-writable directory below
<filename>/home</filename>. The <command>remote-send</command> 
directive allows <systemitem
role="sitename">pablo</systemitem> to request files from
<filename>/var/spool/uucppublic</filename>, except for files from the
<filename>incoming</filename> and <filename>receive</filename>
directories.  This is signaled to <command>uucico</command> by
preceding the directory names with exclamation marks. Finally, the
last line allows <systemitem role="sitename">pablo</systemitem> to
upload files to <systemitem role="sitename">incoming</systemitem>.
</para>

<para>
A major problem with file transfers using UUCP is that it receives files
only to directories that are world-writable. This may tempt some users to set
up traps for other users. However, there's no way to escape this problem
outside of disabling UUCP file transfers altogether.
</para>

</sect2>

<sect2><title>Forwarding</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>restrict</secondary><tertiary>forwarding</tertiary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>forwarding</secondary></indexterm>
UUCP provides a mechanism to have other systems execute file transfers on your
behalf. For instance, suppose your system has <command>uucp</command> access 
to a system called <systemitem role="sitename">seci</systemitem>, but not to 
another system called <systemitem role="sitename">uchile</systemitem>. This 
allows you to make <systemitem role="sitename">seci</systemitem> retrieve a 
file from <systemitem role="sitename">uchile</systemitem> for you and send it 
to your system. The following command would achieve this:

<screen>
$ <userinput>uucp -r seci!uchile!~/find-ls.gz ~/uchile.files.gz</userinput>
</screen>
</para>

<para>
This technique of passing a job through several systems is called
<emphasis>forwarding</emphasis>. On your own UUCP system, you would want to 
limit the forwarding service to a few hosts you trust not to run up a 
horrendous phone bill by making you download the latest X11R6 source release 
for them.
</para>

<para>
By default, Taylor UUCP prohibits forwarding altogether. To enable
forwarding for a particular system, you can use the 
<command>forward</command> command. This command specifies a
list of sites the system may request you to forward jobs to and
from. For instance, the UUCP administrator of <systemitem
role="sitename">seci</systemitem> would have to add the following
lines to the <filename>sys</filename> file to allow <systemitem
role="sitename">pablo</systemitem> to request files from <systemitem
role="sitename">uchile</systemitem>:

<screen>
####################
# pablo
system          pablo
...
forward         uchile
####################
# uchile
system          uchile
...
forward-to      pablo
</screen>
</para>

<para>
The <systemitem role="keyword">forward-to</systemitem> entry for
<systemitem role="sitename">uchile</systemitem> is necessary so that any files
returned by it are actually passed on to
<systemitem role="sitename">pablo</systemitem>. Otherwise UUCP would drop them.
This entry uses a variation of the
<command>forward</command> command that permits
<systemitem role="sitename">uchile</systemitem> to send files only to
<systemitem role="sitename">pablo</systemitem> through
<systemitem role="sitename">seci</systemitem>, not the other way round.
</para>

<para>
To permit forwarding to any system, use the special keyword
<systemitem role="keyword">ANY</systemitem> (capital letters required).
</para>

</sect2>

</sect1>

<sect1 id="X-087-2-uucp.dialin"><title>Setting Up Your System for Dialing In</title>

<para>
<indexterm id="idx-UUCPconfigureasserver-1" class="startofrange"><primary>Taylor UUCP</primary><secondary>configure as server</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>calling in</secondary></indexterm>
<indexterm id="idx-serverUUCP-1" class="startofrange"><primary>servers</primary><secondary>UUCP</secondary></indexterm>
If you want to set up your site for dialing in, you have to permit logins on
your serial port and customize some system files to provide UUCP accounts, 
which we will cover in this section. 
</para>

<sect2 id="X-087-2-uucp.dialin.accounts"><title>Providing UUCP Accounts</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>accounts</secondary></indexterm>
<indexterm><primary>Taylor UUCP</primary><secondary>set up logins</secondary></indexterm>
To begin with, you have to set up user accounts that let remote sites log into
your system and establish a UUCP connection. Generally, you will provide
a separate login name to each system that polls you. When setting up an
account for system <systemitem role="sitename">pablo</systemitem>, you might
give it the username <systemitem role="userid">Upablo</systemitem>. There is
no enforced policy on login names; they can be just about anything, but it
will be convenient for you if the login name is easily related to the remote
host name.
</para>

<para>
For systems that dial in through the serial port, you usually have to add
these accounts to the system password file <filename>/etc/passwd</filename>.
It is good practice to put all UUCP logins in a special group, such as
<systemitem role="userid">uuguest</systemitem>. The account's home directory
should be set to the public spool directory
<filename>/var/spool/uucppublic</filename>&thinsp;; its login shell must be
<command>uucico</command>.
</para>

<para>
<indexterm><primary SORTAS="etc/inetd.conf file">/etc/inetd.conf file</primary></indexterm> 
To serve UUCP systems that connect to your site over TCP, you have to
set up <command>inetd</command> to handle incoming connections on the
<systemitem role="keyword">uucp</systemitem> port by adding the
following line to
<filename>/etc/inetd.conf</filename>&thinsp;:<footnote
id="X-087-2-FNUU14"><para> Note that <command>tcpd</command> usually
has mode 700, so that you must invoke it as user <systemitem
role="userid">root</systemitem>, not <systemitem
role="userid">uucp</systemitem>. <command>tcpd</command> is discussed
in more detail in <xref linkend="X-087-2-appl">.
</para>
</footnote>

<screen>
uucp   stream  tcp   nowait  root  /usr/sbin/tcpd  /usr/lib/uucp/uucico -l
</screen>
</para>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>passwd file</secondary></indexterm>
<indexterm><primary sortas="usr/lib/uucp/passwd file">/usr/lib/uucp/passwd file</primary></indexterm> 
<?troff .ffn>
The <option>&ndash;l</option> option makes <command>uucico</command> perform
its own login authorization. It prompts for a login name and a password
just like the standard <command>login</command> program, but relies on its
private password database instead of <filename>/etc/passwd</filename>. This
private password file is named <filename>/etc/uucp/passwd</filename> and
contains pairs of login names and passwords:

<screen>
Upablo  IslaNegra
Ulorca  co'rdoba
</screen>
</para>

<para>
This file must be owned by
<systemitem role="userid">uucp</systemitem> and have permissions of 600.
</para>

<para>
<indexterm><primary>mgetty program</primary></indexterm>
Does this database sound like such a good idea that you would like to use
it on normal serial logins, too? Well, in some cases you can. What you
need is a <command>getty</command> program that you can tell to invoke
<command>uucico</command> instead of <command>/bin/login</command> for
your UUCP users.<footnote id="X-087-2-FNUU15"><para>
Gert Doering's <command>mgetty</command> is such a beast. It runs on a
variety of platforms, including SCO Unix, AIX, SunOS, HP-UX, and Linux.
</para>
</footnote> The invocation of
<command>uucico</command> would look like this:

<screen>
/usr/lib/uucp/uucico -l -u <replaceable>user</replaceable>
</screen>

The <option>&ndash;u</option> option tells it to use the specified user
name rather than prompting for it.<footnote id="X-087-2-FNUU16"><para>
This option is not present in Version 1.04.
</para>
</footnote>

</para>

<para>
To protect your UUCP users from callers who might give a false system name and
snarf all their mail, you should add
<command>called-login</command> commands to each system
entry in the <filename>sys</filename> file. This is described in the next
section.
</para>

</sect2>

<sect2 id="X-087-2-uucp.security.called-login"><title>Protecting Yourself Against Swindlers</title>

<para>
<indexterm id="idx-UUCPloginsecurity-1" class="startofrange"><primary>Taylor UUCP</primary><secondary>login security</secondary></indexterm>
<indexterm id="chuu.uucp.security" class="startofrange"><primary>UUCP</primary><secondary>security</secondary></indexterm> 
A major problem with UUCP is that the calling system can lie about its name;
it announces its name to the called system after logging in, but the server
doesn't have any way to check it. Thus, an attacker could log into his or her
own UUCP account, pretend to be someone else, and pick up that other site's
mail. This is particularly troublesome if you offer login via anonymous UUCP,
where the password is made public.
</para>
<?troff .Nd 10>

<para>
You <emphasis>must</emphasis> guard against this sort of impostor. The cure
for this disease is to require each system to use a particular login name
by specifying a <systemitem role="keyword">called-login</systemitem> in
<filename>sys</filename>. A sample system entry may look like this:

<screen>
system          pablo
... usual options ...
called-login    Upablo
</screen>
</para>

<para>
The upshot is that whenever a system logs in and pretends it is
<systemitem role="sitename">pablo</systemitem>,
<command>uucico</command> checks whether it has logged in as
<systemitem role="userid">Upablo</systemitem>. If it hasn't, the
calling system is turned down, and the connection is dropped. You
should make it a habit to add the <command>called-login</command> command to every system entry
you add to your <filename>sys</filename> file. It is important that
you do this for <emphasis>all</emphasis> systems in your
<command>sys</command> file, regardless of whether they will ever call
your site or not. For those sites that never call you, you should
probably set <systemitem role="keyword">called-login</systemitem> to
some totally bogus user name, such as <systemitem
role="userid">neverlogsin</systemitem>.
</para>

</sect2>

<sect2><title>Be Paranoid: Call Sequence Checks</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>call sequence check</secondary></indexterm>
Another way to fend off and detect impostors is to use <command>call sequence 
checks</command>. These help you protect against intruders who somehow manage to find out the password with which you log into your UUCP system.
</para>

<para>
When using call sequence checks, both machines keep track of the number of
connections established so far. The counter is incremented with each 
connection. After logging in, the caller sends its call sequence number, and 
the receiver checks it against its own number. If they don't match, the 
connection attempt is rejected. If the initial number is chosen at 
random, attackers will have a hard time guessing the correct call sequence 
number.
</para>

<para>
But call sequence checks do more for you. Even if some very clever
person should detect your call sequence number as well as your password, you
will find out. When the attacker calls your UUCP feed and steals your
mail, this will increase the feeds call sequence number by one. The next time
<emphasis>you</emphasis> call your feed and try to log in, the remote
<command>uucico</command> will refuse you, because the numbers don't match
anymore!
</para>

<para>
If you have enabled call sequence checks, you should check your log files
regularly for error messages that hint at possible attacks. If your system
rejects the call sequence number the calling system offers,
<command>uucico</command> will put a message into the log file saying
something like, &ldquo;Out of sequence call rejected.&rdquo; If your system
is rejected by its feed because the sequence numbers are out of sync, it
will put a message in the log file saying, &ldquo;Handshake failed
(RBADSEQ).&rdquo;
</para>

<para>
To enable call sequence checks, add the following command to the
system entry:

<screen>
# enable call sequence checks
sequence        true
</screen>
</para>

<para>
<indexterm><primary SORTAS="Sequence file">.Sequence file</primary></indexterm>
In addition, you have to create the file containing the sequence
number itself.  Taylor UUCP keeps the sequence number in a file called
<filename>.Sequence</filename> in the remote site's spool
directory. It <emphasis>must</emphasis> be owned by <systemitem
role="userid">uucp</systemitem> and must be mode 600 (i.e., readable
and writeable only by <systemitem role="userid">uucp</systemitem>). It
is best to initialize this file with an arbitrary, previously
agreed-upon start value. A simple way to create this file is:

<screen>
# <userinput>cd /var/spool/uucp/pablo</userinput>
# <userinput>echo 94316 > .Sequence</userinput>
# <userinput>chmod 600 .Sequence</userinput>
# <userinput>chown uucp.uucp .Sequence</userinput>
</screen>
</para>

<para>
Of course, the remote site has to enable call sequence checks as well and
start by using exactly the same sequence number as you.
</para>

<indexterm class="endofrange" startref="idx-UUCPloginsecurity-1">
<indexterm class="endofrange" startref="chuu.uucp.security"> 

<indexterm class="endofrange" startref="idx-serverUUCP-1">
<indexterm class="endofrange" startref="idx-securityUUCP-1">
<indexterm class="endofrange" startref="idx-accessUUCP-1">

</sect2>

<sect2><title>Anonymous UUCP</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>anonymous</secondary></indexterm>
<indexterm><primary>anonymous UUCP</primary></indexterm>
<indexterm><primary>UUCP</primary><secondary>anonymous</secondary></indexterm> 
If you want to provide anonymous UUCP access to your system, you first have to
set up a special account for it as previously described.  A common practice 
is to give the anonymous account a login name and a password of
<systemitem role="userid">uucp</systemitem>.
</para>

<para>
In addition, you have to set a few of the security options for unknown systems.
For instance, you may want to prohibit them from executing any commands on
your system. However, you cannot set these parameters in a
<filename>sys</filename> file entry because the
<command>system</command> command requires the system's
name, which you don't have. Taylor UUCP solves this dilemma through the
<command>unknown</command> command.
<command>unknown</command> can be used in the
<filename>config</filename> file to specify any command that can usually
appear in a system entry:

<screen>
unknown         remote-receive ~/incoming
unknown         remote-send ~/pub
unknown         max-remote-debug none
unknown         command-path /usr/lib/uucp/anon-bin
unknown         commands rmail
</screen>
</para>

<para>
This will restrict unknown systems to downloading files from below the
<filename>pub</filename> directory and uploading files to the
<filename>incoming</filename> directory below
<filename>/var/spool/uucppublic</filename>. The next line will make
<command>uucico</command> ignore any requests from the remote system to
turn on debugging locally. The last two lines permit unknown systems to
execute <command>rmail</command>&thinsp;; but the command path specified makes
<command>uucico</command> look for the <command>rmail</command> command in
a private directory named <filename>anon-bin</filename> only. This restriction
allows you to provide some special <command>rmail</command> that, for instance,
forwards all mail to the superuser for examination. This allows anonymous
users to reach the maintainer of the system, but at the same time prevents 
them from injecting any mail to other sites.
</para>

<para>
To enable anonymous UUCP, you must specify at least one
<systemitem role="keyword">unknown</systemitem> statement in
<filename>config</filename>. Otherwise <command>uucico</command> will
reject all unknown systems.
</para>

<indexterm class="endofrange" startref="idx-UUCPconfigureasserver-1">

</sect2>
</sect1>

<sect1 id="X-087-2-uucp.protocols"><title>UUCP Low-Level Protocols</title>

<para>
<indexterm id="idx-UUCPprotocol-1" class="startofrange"><primary>UUCP</primary><secondary>protocols</secondary></indexterm>
To negotiate session control and file transfers with the remote end,
<command>uucico</command> uses a set of standardized messages. This is often
referred to as the <command>high-level protocol</command>. During the 
initialization phase and the hangup phase these are simply sent across as 
strings. However, during the real transfer phase, an additional low-level 
protocol that is mostly transparent to the higher levels is employed. This 
protocol offers some added benefits, such as allowing error checks on data 
sent over unreliable links.
</para>

<sect2><title>Protocol Overview</title>

<para>
<indexterm><primary>protocols</primary><secondary>UUCP</secondary></indexterm>
UUCP is used over different types of connections, such as serial lines, TCP, 
or sometimes even X.25; it is advantageous to transport UUCP within
protocols designed specifically for the underlying network protocol. In
addition, several implementations of UUCP have introduced different
protocols that do roughly the same thing.
</para>

<para>
Protocols can be divided into two categories: <command>streaming</command> 
and <command>packet</command> protocols. Protocols of the streaming variety 
transfer a file as a whole, possibly computing a checksum over it. This is 
nearly free of overhead, but requires a reliable connection because any 
error will cause the whole file to be retransmitted. These protocols are 
commonly used over TCP connections but are not suitable for use over 
telephone lines. Although modern modems do quite a good job at error 
correction, they are not perfect, nor is there any error detection between 
your computer and the modem.
</para>

<para>
On the other hand, packet-oriented protocols split up the file into
several chunks of equal size. Each packet is sent and received
separately, a checksum is computed, and an acknowledgment is returned
to the sender. To make this more efficient, sliding-window protocols
have been invented, which allow for a limited number (a window) of
outstanding acknowledgments at any time. This greatly reduces the
amount of time <command>uucico</command> has to wait during a
transmission. Still, the relatively large overhead compared to a
streaming protocol makes packet protocols inefficient for TCP use, but
ideal for telephone lines.
</para>

<para>
The width of the data path also makes a difference. Sometimes sending 8-bit
characters over a serial connection is impossible; for instance, the
connection could go through a stupid terminal server that strips off the eighth
bit. When you transmit 8-bit characters over a 7-bit connection, they have to
be quoted on transmission. In the worst-case scenerio, quoting doubles the 
amount of data to be transmitted, although compression done by the hardware may
compensate. Lines that can transmit arbitrary 8-bit characters
are usually called <emphasis>8-bit clean</emphasis>. This is the case for all
TCP connections, as well as for most modem connections.
</para>

<para>
Taylor UUCP 1.06 supports a wide variety of UUCP protocols. The most common
of these are:

<variablelist>
<varlistentry><term><emphasis>g</emphasis></term>
<listitem><para>
This is the most common protocol and should be understood by virtually all
<command>uucico</command>s. It does thorough error checking and is therefore
well suited for noisy telephone links. <emphasis>g</emphasis> requires an
8-bit clean connection. It is a packet-oriented protocol that uses a
sliding-window technique.
</para></listitem>
</varlistentry>

<varlistentry><term><emphasis>i</emphasis></term>
<listitem><para>
This is a bidirectional packet protocol, which can send and receive files at
the same time. It requires a full-duplex connection and an 8-bit clean data
path. It is currently understood by Taylor UUCP only.
</para></listitem>
</varlistentry>

<varlistentry><term><emphasis>t</emphasis></term>
<listitem><para>
This protocol is intended for use over a TCP connection or other truly
error-free networks.  It uses packets of 1,024 bytes and requires an 8-bit
clean connection.
</para></listitem>
</varlistentry>

<varlistentry><term><emphasis>e</emphasis></term>
<listitem><para>
<?troff .hw connections>
This should basically do the same as <emphasis>t</emphasis>. The main
difference is that <emphasis>e</emphasis> is a streaming protocol and is
thus suited only to reliable network connections.
</para></listitem>
</varlistentry>

<varlistentry><term><emphasis>f</emphasis></term>
<listitem><para>
This is intended for use with reliable X.25 connections. It is a streaming
protocol and expects a 7-bit data path. 8-bit characters are quoted, which
can make it very inefficient.
</para></listitem>
</varlistentry>

<varlistentry><term><emphasis>G</emphasis></term>
<listitem><para>
This is the System V Release 4 version of the <emphasis>g</emphasis> protocol.
It is also understood by some other versions of UUCP.
</para></listitem>
</varlistentry>

<varlistentry><term><emphasis>a</emphasis></term>
<listitem><para>
This protocol is similiar to ZMODEM. It requires an 8-bit connection, but
quotes certain control characters like XON and XOFF.
</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

<sect2><title>Tuning the Transmission Protocol</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>protocols</secondary><tertiary>tuning</tertiary></indexterm>
All protocols allow for some variation in packet sizes, timeouts, etc. 
Usually, the defaults work well under standard circumstances, but may
not be optimal for your situation.  The <emphasis>g</emphasis> protocol, for
instance, uses window sizes from 1 to 7, and packet sizes in powers of 2
ranging from 64 through 4096. If your telephone line is usually so noisy that
it drops more than 5 percent of all packets, you should probably lower the
packet size and shrink the window. On the other hand, on very good telephone
lines the protocol overhead of sending acknowledgments for every 128 bytes may
prove wasteful, so you might increase the packet size to 512 or even 1,024.
Most binaries included in Linux distributions default to a window size of 7
and 128-byte packets.
</para>

<para>
Taylor UUCP lets you tune parameters with the 
<command>protocol-parameter</command> command in the
<filename>sys</filename> file.  For instance, to set the
<emphasis>g</emphasis> protocol's packet size to 512 when talking to
<systemitem role="sitename">pablo</systemitem>, you have to add:

<screen>
system          pablo
...
protocol-parameter g  packet-size  512
</screen>
</para>

<para>
The tunable parameters and their names vary from protocol to protocol. For a
complete list of them, refer to the documentation enclosed in the Taylor UUCP
source.
</para>

</sect2>

<sect2><title>Selecting Specific Protocols</title>

<para>
<indexterm><primary>UUCP</primary><secondary>protocols</secondary><tertiary>selection</tertiary></indexterm>
Not every implementation of <command>uucico</command> speaks and understands
each protocol, so during the initial handshake phase, both processes have to
agree on a common one.  The master <command>uucico</command> offers the
slave a list of supported protocols by sending
<literal>P</literal><replaceable>protlist</replaceable>, from which the slave
may pick one.
</para>

<para>
Based on the type of port used (modem, TCP, or direct),
<command>uucico</command> will compose a default list of
protocols. For modem and direct connections, this list usually
comprises <emphasis>i</emphasis>, <emphasis>a</emphasis>,
<emphasis>g</emphasis>, <emphasis>G</emphasis>, and
<emphasis>j</emphasis>.  For TCP connections, the list is
<emphasis>t</emphasis>, <emphasis>e</emphasis>,
<emphasis>i</emphasis>, <emphasis>a</emphasis>,
<emphasis>g</emphasis>, <emphasis>G</emphasis>,
<emphasis>j</emphasis>, and <emphasis>f</emphasis>. You can override
this default list with the <command>protocols</command> command, which may be specified
in a system entry as well as a port entry. For instance, you might
edit the <filename>port</filename> file entry for your modem port like
this:

<screen>
port            serial1
...
protocols       igG
</screen>
</para>

<para>
This will require any incoming or outgoing connection through this port to use
<emphasis>i</emphasis>, <emphasis>g</emphasis>, or <emphasis>G</emphasis>. If
the remote system does not support any of these, the conversation will fail.
</para>

<indexterm class="endofrange" startref="idx-UUCPprotocol-1">
</sect2>
</sect1>

<sect1 id="X-087-2-uucp.misc.faq"><title>Troubleshooting</title>

<para>
<indexterm><primary>UUCP</primary><secondary>troubleshooting</secondary></indexterm>
This section describes what may go wrong with your UUCP connection and makes
location suggestions to fix the error. Although these problems are 
encountered on a regular basis, there is much more that can go wrong
than what we have listed.
</para>

<para>
<indexterm><primary>UUCP</primary><secondary>checking</secondary></indexterm>
If you have a problem, enable debugging with <option>&ndash;xall</option>,
and take a look at the output in <filename>Debug</filename> in the spool
directory. The file should help you to quickly recognize the problem. It is 
often helpful to turn on the modem's speaker when it doesn't 
connect. With Hayes-compatible modems, you can turn on the speaker by adding
<literal>ATL1M1 OK</literal> to the modem chat in the
<filename>dial</filename> file.
</para>

<para>
The first check should always be whether all file permissions are set
correctly. <command>uucico</command> should be setuid <systemitem
role="userid">uucp</systemitem>, and all files in
<filename>/usr/lib/uucp</filename>,
<filename>/var/spool/uucp</filename>, and
<filename>/var/spool/uucppublic</filename> should be owned by
<systemitem role="userid">uucp</systemitem>. There are also some
hidden files in the spool directory which must be owned by <systemitem
role="userid">uucp</systemitem> as well.<footnote
id="X-087-2-FNUU17"><para> That is, files with names beginning with a
dot. Such files aren't normally displayed by the <command>ls</command>
command.
</para>
</footnote>
</para>

<para>
When you're sure you have the permissions of all files set correctly, and
you're still experiencing problems, you can then begin to take error
messages more literally. We'll now look at some of the more common errors
and problems.
</para>

<sect2><title>uucico Keeps Saying &ldquo;Wrong Time to Call&rdquo;</title>
<para>
This probably means that in the system entry in <filename>sys</filename>, you
didn't specify a <command>time</command> command that
details when the remote system may be called, or you gave one that actually
forbids calling at the current time. If no call schedule is given,
<command>uucico</command> assumes the system can never be called.
</para>

</sect2>

<sect2><title>uucico Complains That the Site Is Already Locked</title>

<para>
This means that <command>uucico</command> detects a lock file for the remote
system in <filename>/var/spool/uucp</filename>. The lock file may be from an
earlier call to the system that crashed or was killed. Another possible
explanation is that there's another <command>uucico</command> process
sitting around that is trying to dial the remote system and has gotten stuck
in a chat script, or stalled for some other reason.
</para>

<para>
To correct this error, kill all <command>uucico</command> processes
open for the site with a hangup signal, and remove all lock files that
they have left lying around.
</para>

</sect2>

<sect2><title>You Can Connect to the Remote Site, but the Chat Script Fails</title>
<para>
Look at the text you receive from the remote site. If it's garbled, you might
have a speed-related problem. Otherwise, confirm that it really agrees with what
your chat script expects.  Remember, the chat script starts with an expect
string. If you receive the login prompt and send your name, but never get the
password prompt, insert some delays before sending it, or even in between the
letters. You might be too fast for your modem.
</para>

</sect2>

<sect2><title>Your Modem Does Not Dial</title>
<para>
If your modem doesn't indicate that the DTR line has been raised when
<command>uucico</command> calls out, you might not have given the
right device to <command>uucico</command>. If your modem recognizes
DTR, check with a terminal program that you can write to the modem. If
this works, turn on echoing with <systemitem
role="keyword">\E</systemitem> at the start of the modem chat. If the
modem doesn't echo your commands during the modem chat, check if your
line speed is too high or low. If you see the echo, check if you have
disabled modem responses or set them to number codes.  Verify that the
chat script itself is correct. Remember that you have to write two
backslashes to send one to the modem.
</para>

</sect2>

<sect2><title>Your Modem Tries to Dial but Doesn't Get Out</title>
<para>
Insert a delay into the phone number, especially if you have to dial a
special sequence to gain an outside line from a corporate telephone network.
Make sure you are using the correct dial type, as some telephone networks
support only one type of dialing. Additionally, double check the telephone
number to make sure it's correct.
</para>

</sect2>

<sect2><title>Login Succeeds, but the Handshake Fails</title>
<para>
Well, there can be a number of problems in this situation. The output in the 
log file should tell you a lot. Look at what protocols the remote site 
offers (it sends a string <literal>P</literal>
<replaceable>protlist</replaceable> during the handshake). For the handshake 
to succeed, both ends must support at least one common protocol, so check 
that they do.
</para>

<para>
If the remote system sends <command>RLCK</command>, there is a stale lockfile
for you on the remote system already connected to the remote system on a 
different line.  Otherwise, ask the remote system administrator to remove the 
file.
</para>

<para>
If the remote system sends <command>RBADSEQ</command>, it has conversation 
count checks enabled for you, but the numbers didn't match. If it sends
<command>RLOGIN</command>, you were not permitted to log in under this ID.
</para>

</sect2>

</sect1>

<sect1><title>Log Files and Debugging</title>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>logging and debugging</secondary></indexterm>
<INDEXTERM><PRIMARY>Log file (UUCP)</PRIMARY></INDEXTERM>
<INDEXTERM><PRIMARY>log files, debugging</PRIMARY></INDEXTERM>
When compiling the UUCP suite to use Taylor-style logging, you have only three
global log files, all of which reside in the spool directory. The main log
file is named <filename>Log</filename> and contains all the information about
established connections and transferred files. A typical excerpt looks like
this (after a little reformatting to make it fit the page):

<screen>
uucico pablo - (1994-05-28 17:15:01.66 539) Calling system pablo (port cua3)
uucico pablo - (1994-05-28 17:15:39.25 539) Login successful
uucico pablo - (1994-05-28 17:15:39.90 539) Handshake successful
               (protocol 'g' packet size 1024 window 7)
uucico pablo postmaster (1994-05-28 17:15:43.65 539) Receiving D.pabloB04aj
uucico pablo postmaster (1994-05-28 17:15:46.51 539) Receiving X.pabloX04ai
uucico pablo postmaster (1994-05-28 17:15:48.91 539) Receiving D.pabloB04at
uucico pablo postmaster (1994-05-28 17:15:51.52 539) Receiving X.pabloX04as
uucico pablo postmaster (1994-05-28 17:15:54.01 539) Receiving D.pabloB04c2
uucico pablo postmaster (1994-05-28 17:15:57.17 539) Receiving X.pabloX04c1
uucico pablo - (1994-05-28 17:15:59.05 539) Protocol 'g' packets: sent 15,
                resent 0, received 32
uucico pablo - (1994-05-28 17:16:02.50 539) Call complete (26 seconds)
uuxqt pablo postmaster (1994-05-28 17:16:11.41 546) Executing X.pabloX04ai
               (rmail okir)
uuxqt pablo postmaster (1994-05-28 17:16:13.30 546) Executing X.pabloX04as
               (rmail okir)
uuxqt pablo postmaster (1994-05-28 17:16:13.51 546) Executing X.pabloX04c1
               (rmail okir)
</screen>
</para>
<?troff .Nd 10>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>statistics</secondary></indexterm>
The next important log file is <filename>Stats</filename>, which lists file
transfer statistics. The section of <filename>Stats</filename> corresponding
to the above transfer looks like this (again, the lines have been split to fit
the page):

<screen>
postmaster pablo (1994-05-28 17:15:44.78)
                  received 1714 bytes in 1.802 seconds (951 bytes/sec)
postmaster pablo (1994-05-28 17:15:46.66)
                  received 57 bytes in 0.634 seconds (89 bytes/sec)
postmaster pablo (1994-05-28 17:15:49.91)
                  received 1898 bytes in 1.599 seconds (1186 bytes/sec)
postmaster pablo (1994-05-28 17:15:51.67)
                  received 65 bytes in 0.555 seconds (117 bytes/sec)
postmaster pablo (1994-05-28 17:15:55.71)
                  received 3217 bytes in 2.254 seconds (1427 bytes/sec)
postmaster pablo (1994-05-28 17:15:57.31)
                  received 65 bytes in 0.590 seconds (110 bytes/sec)
</screen>
</para>

<para>
The third file is <filename>Debug</filename>. Debugging information is 
written here. If you use debugging, make sure this file
has protection mode 600. Depending on the debug mode you select, it may
contain the login and password you use to connect to the remote system.
</para>

<para>
<indexterm><primary>Taylor UUCP</primary><secondary>HDB</secondary></indexterm>
If you have some tools around that expect your log files to be in the 
traditional format used by HDB-compatible UUCP implementations, you can also
compile Taylor UUCP to produce HDB-style logs. This is simply a matter of 
enabling a compile-time option in <filename>config.h</filename>.
</para>

<indexterm class="endofrange" startref="idx-UUCP-2">
<indexterm class="endofrange" startref="idx-configuringUUCP-1">
</sect1>
</chapter>











