%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%                       Legal Notice                            %
%                                                               %
% This document is copyright (C) Olaf Kirch, okir@monad.swb.de  %
%                                                               %
% For copying conditions, please refer to the file COPYING.	%
%                                                               %
% The author is not liable for any damages, direct or indirect, %
% resulting from the use of information provided in this        %
% document.                                                     %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% When viewing this document with vi on an 80-columns screen,   %
% do a ':se nonumber' first.                                    %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%               S T A R T   O F   C H A P T E R                 %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Warning - these are not _all_ occurences of UUCPLIBDIR. There
% are more references to it in verbatim environments.
\def\uucplib{\file{/usr/lib/uucp}}
\def\uucpspool{\file{/var/spool/uucp}}
\def\publicspool{\file{/var/spool/uucppublic}}
\def\pubdir{\file{uucppublic}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Managing Taylor UUCP}
\label{uucp}
\index{configuring!UUCP|(}
\index{UUCP|(}


\section{History}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% UUCP Versions, and \linux{}  comes with BNU.                  %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

UUCP was designed in the late seventies by Mike Lesk at AT\&T Bell
Laboratories to provide a simple dial-up network over public telephone
lines. Since most people that want to have email and Usenet News on
their home machine still communicate through modems, UUCP has remained
very popular.  Although there are many implementations running on a
wide variety of hardware platforms and operating systems, they are
compatible to a high degree.


However, as with most software that has somehow become ``standard'' over
the years, there is no UUCP which one would call \emph{the} UUCP.  It
has undergone a steady process of evolution since the first version
which was implemented in 1976.  Currently, there are two major species
which differ mainly in their support of hardware and their
configuration.  Of these, various implementations exist, each varying
slightly from its siblings.


\index{UUCP!Version 2}
One species is the so-called ``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 in frequent use. Recent
implementations of Version 2 provide much of the comfort of the newer
UUCP species.


\index{UUCP!HDB}
\index{UUCP!BNU}
\index{Basic Networking Utilities|see {UUCP, HDB}}
\index{HoneyDanBer|see {UUCP, HDB}}
\index{HDB|see {UUCP, HDB}}
\index{BNU|see {UUCP, HDB}}
The second species was developed in 1983, and is commonly referred
to as BNU (Basic Networking Utilities), HoneyDanBer UUCP, or HDB for
short.  The name is derived from the authors' names, P.~Honeyman,
D.~A.~Novitz, and B.~E.~Redman.  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 you have UUCP traffic with.


\index{UUCP!Taylor}
\index{Taylor, Ian}
The implementation of UUCP currently distributed with \linux{} is Taylor
UUCP~1.04,\footnote{
  Written and copyrighted by Ian Taylor, 1993.
  % Ian Taylor can be reached at \email{ian@airs.com}.
} which is the version this chapter is based upon.  Taylor UUCP Version
1.04 was released in February 1993.  Apart from traditional
configuration files, Taylor UUCP may also be compiled to understand the
new-style~-- a.k.a. ``Taylor''~-- configuration files.


Version 1.05 has been released recently, and will soon make its way into
most distributions. The differences between these versions mostly affect
features you will never use, so you should be able to configure Taylor
UUCP~1.05 using the information form this book.


As included in most \linux{} distributions, Taylor UUCP is usually
compiled for BNU compatibility, or the Taylor configuiration scheme, or
both.  As the latter is much more flexible, and probably easier to
understand than the often rather obscure BNU configuration files, I
will describe the Taylor scheme below.


The purpose of this chapter is not to give you an exhaustive description
of what the command line options for the UUCP commands are and what they
do, but to give you an introduction on how to set up a working UUCP
node.  The first section gives a hopefully gentle introduction about how
UUCP implements remote execution and file transfers. If you are not
entirely new to UUCP, you might want to skip this and move on to
section~\ref{uucp.config.files}, which explains the various files used
to set up UUCP.


We will however assume that you are familiar with the user programs of
the UUCP suite. These are \prog{uucp} and \prog{uux}. For a description,
please refer to the on-line manual pages.


Besides the publicly accessible programs, \prog{uux} and \prog{uucp},
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're peripheral to the main tasks of UUCP.
Besides, they're well documented and fairly easy to understand.
However, there is a third category, which comprises the actual UUCP
``work horses''.  They are called \prog{uucico} (where cico stands for
copy-in copy-out), and \prog{uuxqt}, which executes jobs sent from
remote systems.

% Taylor UUCP 1.04 supports serial connections (either direct or via
% modem) and TCP/IP connections, and has drivers for the traditional
% protocols g, e, f, and t, as well as for a couple of new protocols. All
% of those will be discussed later in this chapter.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{More Information on UUCP}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Those who don't find everything they need in this chapter should read
the documentation that comes along with the package.  This is a set of
texinfo files that describe the setup using the Taylor configuration
scheme.  Texinfo can be converted to DVI and to GNU info files using
\prog{tex} and \prog{makeinfo}, respectively.


\index{HOWTO!UUCP}
If you want to use BNU or even (shudder!) Version~2 configuration files, 
there is a very good book, ``Managing UUCP and Usenet''
(\cite{reilly-uucp}).  I find it very useful. Another good source for
information about UUCP on Linux is Vince Skahan's UUCP-HOWTO, which is
posted regularly to \ngrp{comp.os.linux.announce}.


There's also a newsgroup for the discussion of UUCP, called
\ngrp{comp.mail.uucp}.  If you have questions specific to Taylor UUCP,
you may be better off asking them there, rather than on the
\ngrp{comp.os.linux} groups.


% There is a mailing list for users of Taylor UUCP. To subscribe (or
% leave), send mail to  \email{taylor-uucp-request@gnu.ai.mit.edu}. Please
% note that this mail is handled by a human being.  To write a message to
% the list, simply send it to \email{taylor-uucp@gnu.ai.mit.edu}. Bug
% reports should also be directed to this list.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Layout of UUCP Transfers and Remote Execution}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Gives a short introduction to jobs, spool files, and          %
% grading.                                                      %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{uucp.intro.grades}

\index{UUCP!job}
Vital to the understanding of UUCP is the concept of \emph{jobs}.
Every transfer a user initiates with \prog{uucp} or \prog{uux} is
called a job. It is made up of a \emph{command} to be executed on
a remote system, and a collection of \emph{files} to be transferred
between sites. One of these parts may be missing.


As an example, assume you issued the following command on your host, which
makes UUCP copy the file \file{netguide.ps} to host \host{pablo}, and
makes it execute the \prog{lpr} command to print the file.


\begin{tscreen}
\begin{verbatim}
$ uux -r pablo!lpr !netguide.ps
\end{verbatim}
\end{tscreen}


\index{UUCP!spool directory}
UUCP does not generally call the remote system immediately to execute
a job (else you could make do with \prog{kermit}). Instead, it
temporarily stores the job description away. This is called
\emph{spooling}.  The directory tree under which jobs are stored is
therefore called the \emph{spool directory} and is generally located
in \uucpspool.  In our example, the job description would contain
information about the remote command to be executed (\prog{lpr}), 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,
\file{netguide.ps}.


The exact location and naming of spool files may vary, depending on
some compile-time options. HDB-compatible UUCP's generally store spool
files in a directory named \uucpspool\file{/\var{site}}, where
\var{site} is the name of the remote site. When compiled for Taylor
configuration, UUCP will create subdirectories below the site-specific
spool directory for different types of spool files.


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. This is done by \prog{uuxqt}, which also takes care of
forwarding any jobs if they are designated for another site.



\index{UUCP!priorities}
\index{UUCP!spool grade}
\index{UUCP!job}
To distinguish between important and less important jobs, UUCP
associates a \emph{grade} with each job. This is a single letter,
ranging from 0 through 9, A though 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 grade are transferred
earlier. Grades may be assigned using the \option{-g} flag when
invoking \prog{uucp} or \prog{uux}.


You can also disallow the transfer of jobs below a given grade at
certain times.  This is also called the \emph{maximum spool grade}
allowed during a conversation and defaults to~z. Note the
terminological ambiguity here: a file is transferred only if it is
\emph{equal or above} the maximum spool grade.


\subsection{The Inner Workings of \prog{uucico}}
\label{uucico.connect}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This section introduces you to the way uucico connects to a   %
% system and does file transfer. Not intended to be accurate.   %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!uucico@\prog{uucico}|(}

\blackdiamond
To understand why \prog{uucico} needs to know certain things, a quick
description of how it actually connects to a remote system might be in
order here.

When you execute \prog{uucico -s \var{system}} from the command line, it
first has to connect physically. The actions taken depend on the type of
connection to open~-- e.g. when using telephone line, it has to find a
modem, and dial out. Over TCP, it has to call \func{gethostbyname(3)} to
convert the name to a network address, find out which port to open, and
bind the address to the corresponding socket.


\index{UUCP!master}
\index{UUCP!slave}
After this connection has been established, an authorization procedure
has to be passed. It generally consists of the remote system asking for
a login name, and possibly a password. This is commonly called the
\emph{login chat}. The authorization procedure is performed either by the
usual \prog{getty}/\prog{login} suite, or~-- on TCP sockets~-- by
\prog{uucico} itself.  If authorization succeeds, the remote end fires
up \prog{uucico}. The local copy of \prog{uucico} which initiated the
connection is referred to as \emph{master}, the remote copy as \emph{slave}.


\index{UUCP!call sequence check}
\index{UUCP!handshake}
\index{UUCP!protocol}
Next follows the \emph{handshake phase}: the master now 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 \emph{call sequence number} 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.


Finally, the two \prog{uucico}'s try to agree on a common \emph{transfer
protocol}. 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 ``safe'' 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.


After the handshake is complete, the actual transmission phase begins.
Both ends turn on the selected protocol driver. The drivers possibly
perform a protocol-specific initialization sequence.


First, the master 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
\prog{uucico}'s exchange termination messages, and close the connection.


We will not go into this in greater detail: please refer to either the
sources or any good book on UUCP for this. 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.  The Taylor
UUCP FAQ also disucsses some details of the way UUCP is implemented.
It is posted to \ngrp{comp.mail.uucp} regularly.



\subsection{\prog{uucico} Command Line Options}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Introduces uucico and friends                                 #
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!uucico@\prog{uucico}}
\index{uucico@\prog{uucico}}
\index{UUCP!calling out}
\index{UUCP!logging and debugging}
\index{debugging!UUCP setup}

This section describes the most important command line options for
\prog{uucico}.  For a complete list, please refer to the
\file{uucico(1)} manual page.


\begin{dispitems}
\ditem[\option{-s \var{system}}]
        Call the named \var{system} unless prohibited by call time
        restrictions.

\ditem[\option{-S \var{system}}]
        Call the named \var{system} unconditionally.

\ditem[\option{-r1}]
        Start \prog{uucico} in master mode. This is the default when
        \option{-s} or \option{-S} is given. All by itself, the
        \option{-r1} option causes \prog{uucico} to try to call all
        systems in \file{sys}, unless prohibited by call or retry time
        restrictions.

\ditem[\option{-r0}]
        Start \prog{uucico} in slave mode. This is the default when no
        \option{-s} or \option{-S} 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{-p} option is
        used.

\ditem[\option{-x \var{type}}, \option{-X \var{type}}]
        Turn on debugging of the specified type. Several types may be
        given as a comma-separated list. The following types are valid:
        \keyword{abnormal}, \keyword{chat}, \keyword{handshake},
        \keyword{uucp-proto}, \keyword{proto}, \keyword{port},
        \keyword{config}, \keyword{spooldir}, \keyword{execute},
        \keyword{incoming}, \keyword{outgoing}. Using \keyword{all}
        turns on all options.  For compatibility with other UUCP
        implementations, a number may be specified instead, which turns
        on debugging for the first \var{n} items from the above list.


        Debugging messages will be logged to the file \file{Debug} below
        \uucpspool.

\end{dispitems}


\index{UUCP!uucico@\prog{uucico}|)}

\section{UUCP Configuration Files}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
% A Description of all HoneyDanBer Config Files.                %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\namedlabel{uucp.config.files}{UUCP Configuration Files}

In contrast to simpler file transfer programs, UUCP was designed to be
able to handle all transfers automatically. Once it is set up
properly, interference by the administrator should not be necessary
on a day-to-day basis. The information required for this is is kept in
a couple of \emph{configuration files} that reside in the directory
\uucplib. Most of these files are used only when dialing out.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{A Gentle Introduction to Taylor UUCP}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!configuration files|(}

To say that UUCP configuration is hard 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 Talyor
format is almost easy reading compared to the older formats in HDB or
Version~2).


To give you a feel how all these files interact, we will introduce you
to the most important ones, and have a look at sample entries of these
files. We won't explain everything in detail now; a more accurate
account is given in separate sections below. If you want to set up your
machine for UUCP, you had best start with some sample files, and adapt
them gradually.  You can pick either those shown below, or those
included in your favorite \linux{} distribution.


All files described in this section are kept in \uucplib{} 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 \file{README} file in \uucplib.


For UUCP to work properly, these files must be owned by the
\user{uucp} user.  Some of them contain passwords and telephone
numbers, and therefore should have permissions of 600.\footnote{
  Note that although most UUCP commands must be setuid to \user{uucp},
  you must make sure the \prog{uuchk} program is \emph{not}.  Otherwise,
  users will be able to display passwords even though they have mode
  600.
}


The central UUCP configuration file is \uucplib\file{/config}, and 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 \host{vstout} as their UUCP gateway:


\begin{tscreen}
\begin{verbatim}
# /usr/lib/uucp/config - UUCP main configuration file
hostname         vstout
\end{verbatim}
\end{tscreen}


The next important configuration file is the \file{sys} file. It
contains all system-specific information of sites you are linked to.
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 \host{pablo} would be


\begin{tscreen}
\begin{verbatim}
# /usr/lib/uucp/sys - name UUCP neighbors
# system: pablo
system          pablo
time            Any
phone           123-456
port            serial1
speed           38400
chat            ogin: vstout ssword: lorca
\end{verbatim}
\end{tscreen}


The \keyword{port} names a port to be used, and \keyword{time}
 specifies the times at which it may be called.  \keyword{chat}
describes the login chat scripts~-- the sequence of strings that must
be exchanged between to allow \prog{uucico} to log into \host{pablo}.
We will get back to chat scripts later.  The \keyword{port} command
does not name a device special file such as \file{/dev/cua1}, but
rather names an entry in the \file{port} file.  You can assign these
names as you like as long as they refer to a valid entry in
\file{port}.


The \file{port} file holds information specific to the link itself.  For
modem links, it describes the device special file to be used, the range
of speeds supported, and the type of dialing equipment connected to the
port. The entry below describes \file{/dev/cua1} (a.k.a. COM 2), to
which a NakWell modem is connected that is capable of running at
speeds up to 38400bps.  The entry's name way chosen to match the port
name given in the \file{sys} file.


\begin{tscreen}
\begin{verbatim}
# /usr/lib/uucp/port - UUCP ports
# /dev/cua1 (COM2)
port            serial1
type            modem
device          /dev/cua1
speed           38400
dialer          nakwell
\end{verbatim}
\end{tscreen}


The information pertaining to the dialers itself is kept in yet another
file, called~-- you guessed it: \file{dial}. For each dialer type, it
basically contains the sequence of commands to be issued to dial up a
remote site, given the telephone number. Again, this is specified as a
chat script. For example, the entry for the above NakWell might look
like this:


\begin{tscreen}
\begin{verbatim}
# /usr/lib/uucp/dial - per-dialer information
# NakWell modems
dialer          nakwell
chat            "" ATZ OK ATDT\T CONNECT
\end{verbatim}
\end{tscreen}


The line starting with \keyword{chat} specifies the modem chat, which is
the sequence of commands sent to and received from the modem to
initialize it and make it dial the desired number. The ``\keyword{\bs T}''
sequence will be replaced with the phone number by \prog{uucico}.


\begin{figure}[tbp]
\iftex
 \ifps
  \begin{center}
   \mbox{\epsffile{figures/uucp.epsf}}
  \end{center}
 \else
  \begin{center}
   \input{uucp.eepic}
  \end{center}
 \fi
\else
\fi
\caption{
 \label{uucp.fig.files}
 Interaction of Taylor UUCP Configuration Files.
}
\end{figure}

To give you a rough idea how \prog{uucico} deals with these
configuration files, assume you issued the command


\begin{tscreen}
\${} uucico -s pablo
\end{tscreen}

\noindent
on the command line. The first thing \prog{uucico} does is look up
\host{pablo} in the \file{sys} file. From the \file{sys} file entry
for \host{pablo} it sees that it should use the \keyword{serial1} port
to establish the connection.  The \file{port} file tells it that this is
a modem port, and that it has a NakWell modem attached.


\prog{uucico} now searches \file{dial} for the entry describing
the NakWell modem, and having found one, opens the serial port 
\file{/dev/cua1} and executes the dialer chat. That is, it sends
``\term{ATZ}'', waits for the ``\term{OK}'' response, etc. When
encountering the string ``\keyword{\bs T}'', it substitutes the phone
number (123--456) extracted from the \file{sys} file.


After the modem returns \term{CONNECT}, the connection has been
established, and the modem chat is complete. \prog{uucico} now returns
to the \file{sys} file and executes the login chat. In our example, it
would wait for the ``\term{login:}'' prompt, then send its user name
(\term{neruda}), wait for the ``\term{password:}'' prompt, and send its
password, ``\term{lorca}''.


After completing authorization, the remote end is assumed to fire up
its own \prog{uucico}. The two will then enter the handshake phase
described in the previous section.


The way the configuration files depend on each other is also shown in
figure~\ref{uucp.fig.files}.

\index{UUCP!configuration files|)}

\subsection{What UUCP Needs to Know}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Helps you setting up your modem and finding out the           %
% information needed to connect to another site.                %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{uucp.starting.parameters}

Before you start writing the UUCP configuration files, you have to
gather some information it needs to know.


First, you will 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 \file{/dev/cua0} through \file{/dev/cua3}.  Most
distributions, such as Slackware, create a link \file{/dev/modem} as a
link to the appropriate \file{cua*} device file, and configure
\prog{kermit}, \prog{seyon}, etc, to use this generic file.  In this
case, you should either use \file{/dev/modem} in your UUCP
configuration, too.


The reason for this is that all dial-out programs use so-called
\emph{lock files} to signal when a serial port is in use. The names of
these lock files are a concatenation of the string \file{LCK..} and
the device file name, for instance \file{LCK..cua1}. 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 not an unlikely event
when you schedule your UUCP calls using a \file{crontab} entry.


For details of setting up your serial ports, please refer to
chapter~\ref{serial}.


Next, you must find out at what speed your modem and \linux{} will
communicate.  You will have to set this 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 2400bps (bits
per second).  Using compression protocols such as V.42bis, the actual
transfer rate may climb up to 9600bps.


Of course, if UUCP is to do anything, you will need the phone number of
a system to call.  Also, you will need a valid login id and possibly a
password for the remote machine.\footnote{
  If you're just going to try out UUCP, get the number of an archive
  site near you. Write down the login and password~-- they're public to
  make anonymous downloads possible. In most cases, they're something
  like \user{uucp/uucp} or \user{nuucp/uucp}.
}


\index{UUCP!logging in}
You will also have to know \emph{exactly} how to log into the system.
E.g., do you have to press the BREAK key before the login prompt
appears? Does it display \term{login:} or \term{user:}? This is
necessary for composing the \emph{chat script}, which is a recipe telling
\prog{uucico} how to log in. If you don't know, or if the usual chat
script fails, try to call the system with a terminal program like
\prog{kermit} or \prog{minicom}, and write down exactly what you have
to do.



\subsection{Site Naming}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This subsection shortly deals with site naming and how to set %
% your nodename.                                                %
%                                                               %
% A word about domain naming should go into the mail section.   %
% It hasn't very much to do with uucp.                          %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{uucp.starting.sitename}
\index{address!UUCP hostname}
\index{choosing!UUCP hostname}
\index{UUCP!hostname}
\index{hostname!UUCP}

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{
  The only limitation is that it shouldn't be longer than 7~characters,
  so as to not confuse hosts with filesystems that impose a narrow limit
  on file names.
}


However, if you use UUCP for a mail or news link, you should think about
having the name registered with the UUCP Mapping project. The UUCP
Mapping Project is described in chapter~\ref{mail}. Even if you
participate in a domain, you might consider having an official UUCP name
for your site.


Frequently, people choose their UUCP name to match the first component
of their fully qualified domain name. Suppose your site's domain
address is \host{swim.twobirds.com}, then your UUCP host name would be
\host{swim}.  Think of UUCP sites as knowing each other on a
first-name basis.  Of course, you can also use a UUCP name completely
unrelated to your fully qualified domain name.


\index{UUCP!Mapping Project}
However, make sure not to use the unqualified site name in mail
addresses unless you have registered it as your official UUCP
name.\footnote{
  The UUCP Mapping Project registers all UUCP hostnames world-wide and
  makes sure they are unique. To register your UUCP name, ask the
  maintainers of the site that handles your mail; they will be able to
  help you with it.
} 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
no end of headaches.


By default, the UUCP suite uses the name set by \prog{hostname} as the
site's UUCP name. This name is commonly set in the \file{/etc/rc.local}
script.  If your UUCP name is different from what you set your host name
to, you have to use the \keyword{hostname} option in the \file{config}
file to tell \prog{uucico} about your UUCP name. This is described
below.


\subsection{Taylor Configuration Files}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

We now return to the configuration files.  Taylor UUCP gets its
information from the following files:

\begin{dispitems}
\ditem[\file{config}]
	This is the main configuration file. You can define your site's
	UUCP name here.

\ditem[\file{sys}]
	This file describes all sites known to you.  For each site, it
        specifies its name, at what times to call it, which number to
        dial (if any), what type of device to use, and how to log on.

\ditem[\file{port}]
	Contains entries describing each port available, together with
        the line speed supported and the dialer to be used.

\ditem[\file{dial}] 
	Describes dialers used to establish a telephone
        connection.

\ditem[\file{dialcode}] 
	Contains expansions for symbolic dialcodes.

\ditem[\file{call}] 
	Contains the login name and password to be used when calling
	a system.  Rarely used.

\ditem[\file{passwd}] 
	Contains login names and passwords systems may use when logging
	in. This file is used only when \prog{uucico} does its own
	password checking.

\end{dispitems}


Taylor configuration files are generally made up of lines containing
keyword-value pairs. A hash sign introduces a comment that entends
to the end of the line. To use a hash sign by itself, you may escape it
with a backslash.


There are quite a number of options you can tune with these
configuration files.  We can't go into all parameters here, but will
only cover the most important ones. They you should be able to
configure a modem-based UUCP link.  Additional sections will 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.


\index{display!UUCP configuration}
\index{checking!UUCP}
\index{UUCP!checking}
When you think you have configured your UUCP system completely, you
can check your configuration using the \prog{uuchk} tool (located in
\uucplib). \prog{uuchk} reads your configuration files, and prints
out a detailed report of the configuration values used for each
system.


\subsection{General Configuration Options~-- the \file{config} File}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!config file@\file{config} file}
\index{UUCP!hostname}

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
\prog{hostname} command, but it is generally a good idea to set the UUCP
name explicitly. A sample file is shown below:


\begin{tscreen}
\begin{verbatim}
# /usr/lib/uucp/config - UUCP main configuration file
hostname        vstout
\end{verbatim}
\end{tscreen}
 

Of course, there are a number of miscellaneous parameters that may be
set here, too, such as the name of the spool directory, or access rights
for anonymous UUCP.  The latter will be described in a later section.


\subsection{How to Tell UUCP about other Systems~-- the \file{sys} File}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% A Description of the Systems file                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{uucp.systems.file}
\index{UUCP!sys file@\file{sys} file}
\index{UUCP!remote system|(}

The \file{sys} file describes the systems your machine knows about.  An
entry is introduced by the \keyword{system} keyword; the subsequent
lines up to the next \keyword{system} directive detail the parameters
specific to that site.  Commonly, a system entry will define parameters
such as the telephone number and the login chat.


Parameters before the very first \keyword{system} line set default
values used for all systems.  Usually, you will set protocol paramters
and the like in the defaults section.


Below, the most prominent fields are discussed in some detail.


\subsubsection{System Name}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% system                                                       %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!remote system}
\index{UUCP!hostname}

The \keyword{system} command names the remote system. You must specify
the correct name of the remote system, not an alias you invented,
because \prog{uucico} will check it against what the remote system says
it is called when you log on.\footnote{
    Older Version 2 UUCP's don't broadcast their name when being called;
    however, newer implementations often do, and so does Taylor UUCP.
}


Each system name may appear more only once.  If you want to use
several sets of configurations for the same system (such as different
telephone numbers \prog{uucico} should try in turn), you can specify
\emph{alternates}.  Alternates are described below.


\subsubsection{Telephone Number}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% phone number                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!phone number}

If the remote system is to be reached over a telephone line, the
\keyword{phone} field specifies the number the modem should dial.  It
may contain several tokens interpreted by \prog{uucico}'s dialing
procedure.  An equal sign means to wait for a secondary dial tone, and
a dash generates a one-second pause. For instance, some telephone
installations will choke when you don't pause between dialing the
prefix code and telephone number.

{\bf [Don't know the proper English term for this~-- you know,
something like a company's private internal installation where you
have to dial a 0 or 9 to get a line to the outside.]}


\index{UUCP!dialcode file@\file{dialcode} file}
Any embedded alphabetic string may be used to hide site-dependent
information like area codes. Any such string is translated to a
dialcode using the \file{dialcode} file. Suppose you have the
following \file{dialcode} file:


\begin{tscreen}
\begin{verbatim}
# /usr/lib/uucp/dialcode - dialcode translation
Bogoham         024881
Coxton          035119
\end{verbatim}
\end{tscreen}
 

With these translations, you can use a phone number such as
\keyword{Bogoham7732} in the \file{sys} file, which makes things probably
a little more legible.



\subsubsection{Port and Speed}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% speed                                                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!device}

The \keyword{port} and \keyword{speed} options are used to select
the device used for calling the remote system, and the maximum
speed to which the device should be set.\footnote{
  The Baud rate of the tty must be at least as high as the maximum
  transfer speed.
} A \keyword{system} entry may use either option alone, or both options
in conjunction.  When looking up a suitable device in the \file{port}
file, only those ports are selected that have a matching port name
and/or speed range.


Generally, using the \keyword{speed} option should suffice. If you have
only one serial device defined in \file{port}, \prog{uucico} will always
pick 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 \prog{uucico}
finds that there are several matches, it tries each device in turn until
it finds an unused one.




\subsubsection{The Login Chat}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% chat script                                                  %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!logging in}
\index{UUCP!login chat}
\index{UUCP!chat scripts|(}
\index{chat script!UUCP}

Above, we already encountered the login chat script, which tells
\prog{uucico} how to log into the remote system.  It consists of a list
of tokens, specifying strings expected and sent by the local
\prog{uucico} process. The intention is to make \prog{uucico} wait until
the remote machine sends a login prompt, then return the login name,
wait for the remote system to send the password prompt, and send the
password. Expect and send strings are given in alternation.
\prog{uucico} automatically appends a carriage return character
(\keyword{\bs r}) to any send string. Thus, a simple chat script would
look like

\begin{tscreen}
 ogin: vstout ssword: catch22
\end{tscreen}

You will notice that the expect fields don't contain the whole prompts.
This is to make sure that the login succeeds even if the remote system
broadcasts \term{Login:} instead of \term{login:}.


\prog{uucico} also allows for some sort of conditional execution, for
example in the case that the remote machine's \prog{getty} needs to be
reset before sending a prompt. For this, you can attach a sub-chat to an
expect string, offset by a dash.  The sub-chat 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 an allround chat script that should also
work in case you have to hit return before the login appears.
\term{\dqt\dqt} tells UUCP to not wait for anything and continue with
the next send string immediately.


\begin{tscreen}
\begin{verbatim}
 "" \n\r\d\r\n\c ogin:-BREAK-ogin: vstout ssword: catch22
\end{verbatim}
\end{tscreen}
 
 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Special strings and escape characters in the chat script as %
% supported by Taylor UUCP 1.03. These are taken from the     %
% texinfo files.                                              %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
There are a couple of special strings and escape characters which may
occur in the chat script. The following is an incomplete list of
characters legal in expect strings:


\begin{dispitems}
\ditem[\keyword{\dqt\dqt}]
	The empty string. It tells \prog{uucico} not to wait for
	anything, but proceed with the next send string immediately.

\ditem[\keyword{\bs t}]
	Tab character.

\ditem[\keyword{\bs r}]
	Carriage return character.

\ditem[\keyword{\bs s}]
	Space character. You need this to embed spaces in a chat string.

\ditem[\keyword{\bs n}]
	Newline character.

\ditem[\keyword{\bs\bs}]
	Backslash character.

\end{dispitems}
 
\medskip\noindent
On send strings, the following escape characters and strings are legal
in addition to the above:


\begin{dispitems}
\ditem[\keyword{EOT}]
	End of transmission character (\term{\car D}).

\ditem[\keyword{BREAK}]
	Break character.

\ditem[\keyword{\bs c}]
	Suppress sending of carriage return at end of string.

\ditem[\keyword{\bs d}]
	Delay sending for 1 second.

\ditem[\keyword{\bs E}]
	Enable echo checking. This requires \prog{uucico} to wait for
	the echo of everything it writes to be read back from the device
	before it can continue with the chat. It is primarily useful
	when used in modem chats (which we will encounter below). Echo
	checking is off by default.

\ditem[\keyword{\bs e}]
	Disable echo checking.

\ditem[\keyword{\bs K}]
	Same as \keyword{BREAK}.

\ditem[\keyword{\bs p}]
	Pause for fraction of a second.
\end{dispitems}

\index{UUCP!chat scripts|)}



\subsubsection{Alternates}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!alternates}

Sometimes it is desirable 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 \emph{alternate}.


An alternate entry retains all settings from the main system entry, and
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 \keyword{alternate}.


To use two phone numbers for \host{pablo}, you would modify its
\file{sys} entry in the following way:


\begin{tscreen}
\begin{verbatim}
system       pablo
phone        123-456
... entries as above ...
alternate
phone        123-455
\end{verbatim}
\end{tscreen}


When calling \host{pablo}, \prog{uucico} will now first dial 123-456,
and if this fails, try the alternate.  The alternate entry retains all
settings from the main system entry, and overrides only the telephone
number.


\subsubsection{Restricting Call Times}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% schedule                                                     %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!restrict!call time}
\index{UUCP!call time}

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 \prog{uucico} the \option{-S} or \option{-f} option.


By default, Taylor UUCP will disallow connections at any time, so you
\emph{have} to use some sort of time specification in the \file{sys}
file.  If you don't care about call time restrictions, you can specify
the \keyword{time} option with a value of \keyword{Any} in your
\file{sys} file.


The simplest way to restrict call time is the \keyword{time} entry,
which is followed by a string made up of a day and a time subfield.
Day may be any of \keyword{Mo, Tu, We, Th, Fr, Sa, Su} combined, or
\keyword{Any}, \keyword{Never}, or \keyword{Wk} for weekdays. The time
consists of two 24-hour clock values, separated by a dash. They
specify the range during which calls may be placed. The combination of
these tokens is written without white space in between.  Any number of
day and time specifications may be grouped together with commas.  For
example,


\begin{tscreen}
\begin{verbatim}
time            MoWe0300-0730,Fr1805-2000
\end{verbatim}
\end{tscreen}


\noindent
allows calls on Monday and Wednesdays from 3~a.m. to 7.30, and on
Fridays between 18.05 and 20.00.  When a time field spans midnight, say
\keyword{Mo1830-0600}, it actually means Monday, between midnight and
6~a.m., and between 6.30~p.m. and midnight.


The special time strings \keyword{Any} and \keyword{Never} mean what
they say: Calls may be placed at any or no time, respectively.


% Taylor UUCP also has a number of special tokens you may use in time
% strings, such as \keyword{NonPeak} and \keyword{Night}.  They are
% shorthand for \keyword{Any2300-0800,SaSu0800-1700} and
% \keyword{Any1800-0700,SaSu}, respectively.


\index{UUCP!retry interval}
The \keyword{time} command takes an optional second argument that
describes a retry time in minutes. When an attempt to establish a
connection fails, \prog{uucico} will not allow another attempt to dial
up the remote host within a certain interval. By default,
\prog{uucico} uses an exponential backoff scheme, where the retry
interval increases with each repeated failure.  For instance, when you
specify a retry time of 5 minutes, \prog{uucico} will refuse to call
the remote system within 5 minutes after the last failure.


\index{UUCP!priorities|(}
\index{UUCP!spool grade|(}
The \keyword{timegrade} command allows you to attach a maximum spool
grade to a schedule. For instance, assume you have the following
\keyword{timegrade} commands in a \keyword{system} entry:


\begin{tscreen}
\begin{verbatim}
timegrade           N Wk1900-0700,SaSu 
timegrade           C Any
\end{verbatim}
\end{tscreen}


This allows jobs with a spoolgrade 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) will be
transferred only during the night and at weekends.


Just like \keyword{time}, the \keyword{timegrade} command takes
a retry interval in minutes as an optional third argument.


However, a caveat about spool grades is in order here: First, the
\keyword{timegrade} option applies only to what \emph{your} systems
sends; the remote system may still transfer anything it likes.  You can
use the \keyword{call-timegrade} option to explicitly request it to send
only jobs above some given spool grade; but there's no guarantee it will
obey this request.\footnote{
  If the remote system runs Talyor UUCP, it will obey.
}


Similarly, the \keyword{timegrade} field is not checked when a remote
system calls in, so any jobs queued for the calling system will be sent.
However, the remote system can explicitly request your \prog{uucico} to
restrict itself to a certain spool grade.


\index{UUCP!priorities|)}
\index{UUCP!spool grade|)}
\index{UUCP!remote system|)}



\subsection{What Devices there are~-- the \file{port} File}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This section introduces the Devices file.                     %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!port file@\file{port} file}
\index{UUCP!device|(}
\index{UUCP!modem}

The \file{port} file tells \prog{uucico} about the available ports.
These may be modem ports, but other types such as direct serial lines
and TCP sockets are supported as well.


Like the \file{sys} file, \file{port} consists of separate entries
starting with the keyword \keyword{port}, followed by the port name.
This name may be used by in the \file{sys} file's \keyword{port}
statement.  The name need not be unique; if there are several ports
with the same name, \prog{uucico} will try each in turn until it finds
one that is not currently being used.


The \keyword{port} command should be immediately followed by the
\keyword{type} statement that describes what type of port is described.
Valid types are \keyword{modem}, \keyword{direct} for direct
connections, and \keyword{tcp} for TCP sockets. If the \keyword{port}
command is missing, the port type defaults to modem.


In this section, we will cover only modem ports; TCP ports and direct
lines are discussed in a later section.


For modem and direct ports, you have to specify the device for calling
out using the \keyword{device} directive.  Usually, this is the name of
a device special file in the \file{/dev} directory, like
\file{/dev/cua1}.\footnote{
  Some people use the \file{ttyS*} devices instead, which are intended
  for dial-in only.
}


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
needn't be really compatible with each other.  Therefore, you have to
tell \prog{uucico} how to initialize the modem and how to make it dial
the desired number.  Taylor UUCP keeps the descriptions of all dialers
in a file named \file{dial}.  To use any of these, you have to specify
the dialer's name using the \keyword{dialer} command.


Sometimes, you will want to use a modem in different ways, depending
on which system you call.  For instance, some older modems don't
understand when a high-speed modem attempts to connect at 14400bps;
they simply drop the line instead of negotiating a connect at, say,
9600bps. When you know site \host{drop} uses such a dumb modem, you
have to set up your modem differently when calling them. For this, you
need an additional port entry in the \file{port} file that specifies a
different dialer.  Now you can give the new port a different name,
such as \keyword{serial1-slow}, and use the \keyword{port} directive
in \host{drop} system entry in \file{sys}.


A better way is to distinguish the ports by the speeds they support.
For instance, the two port entries for the above situation may look
like this:


\begin{tscreen}
\begin{verbatim}
# NakWell modem; connect at high speed
port            serial1         # port name
type            modem           # modem port
device          /dev/cua1       # this is COM2
speed           38400           # supported speed
dialer          nakwell         # normal dialer

# NakWell modem; connect at low speed
port            serial1         # port name
type            modem           # modem port
device          /dev/cua1       # this is COM2
speed           9600            # supported speed
dialer          nakwell-slow    # don't attempt fast connect
\end{verbatim}
\end{tscreen}


The system entry for site \host{drop} would now give \keyword{serial1}
as port name, but request to use it at 9600bps only.  \prog{uucico}
will then automatically use the second port entry. All remaining
sites that have a speed of 38400bps in the system entry will be called
using the first port entry.



\index{UUCP!device|)}



\subsection{How to Dial a Number~-- the \file{dial} File}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This section describes the Dialers file                       %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!dial file@\file{dial} file}
\index{UUCP!modem|(}

The \file{dial} file describes the way various dialers are used.
Traditionally, UUCP talks of dialers rather than modems, because in
earlier times, it was usual practice to have one (expensive) automatic
dialing device serve a whole bank of modems. Today, most modems have
dialing support builtin, so this distinction gets a little blurred.


Nevertheless, different dialers or modems may require a different
configuration.  You can describe each of them in the \file{dial} file.
Entries in \file{dial} start with the \keyword{dialer} command that
gives the dialer's name.


The most important entry beside this is the modem chat, specified by
the \keyword{chat} command. Similar to the login chat, it consists of
a sequence of strings \prog{uucico} sends to the dialer and the
responses it expects in return. It is commonly used to reset the modem
to some known state, and dial the number. The following sample dialer
entry shows a typical modem chat for a Hayes-compatible modem:


\begin{tscreen}
\begin{verbatim}
# NakWell modem; connect at high speed
dialer          nakwell         # dialer name
chat            "" ATZ OK\r ATH1E0Q0 OK\r ATDT\T CONNECT
chat-fail       BUSY
chat-fail       ERROR
chat-fail       NO\sCARRIER
dtr-toggle      true
\end{verbatim}
\end{tscreen}


The modem chat begins with \term{\dqt\dqt}, the empty expect string.
\prog{uucico} will therefore send the first command (\term{ATZ}) right
away.  \term{ATZ} is the Hayes command to reset the modem. It then waits
until the modem has sent \term{OK}, and sends the next command which
turns off local echo, and the like. After the modem returns \term{OK}
again, \prog{uucico} sends the dialing command (\term{ATDT}). The escape
sequence \term{\bs T} in this string is replaced with the phone number
taken from the system entry \file{sys} file. \prog{uucico} then waits for
the modem to return the string \term{CONNECT}, which signals that a
connection with the remote modem has been established successfully.


%% dialcode substitution isn't that much of a win to bother people
%% with understanding it.
% In the modem chat, you can use one of two escape sequences to make
% \prog{uucico} insert the telephone number. One is \term{\bs T} mentioned
% above, the other is \term{\bs D}. The difference between them is that
% the latter does not support dialcode substitution, while the former
% does. With dialcode substitution, the phone number may contain alphabetic
% strings that are mapped to real telephone numbers using the \file{dialcode}
% file. For instance, you might choose to replace the area code in the phone
% number with the names of the city.


Often, 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 will return some error message indicating the
reason.  Modem chats are not capable to detect such messages;
\prog{uucico} will continue to wait for the expected string until it
times out. The UUCP log file will therefore only show a bland ``timed
out in chat script'' instead of the true reason.


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


The last command in the example shown above tells UUCP to toggle the
DTR line before starting the modem chat. Most modems can be configured
to go on-hook when detecting a change on the DTR line, and enter
command mode.\footnote{
  You can also configure some modems to reset themselves when
  detecting a transition on DTR.  Some of them, however, don't
  seem to like this, and occasionally get hung.
}

\index{UUCP!modem|)}

\subsection{UUCP Over TCP}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!over TCP/IP}
\index{TCP!UUCP}

Absurd as it may sound at the first moment, using UUCP to transfer data
over TCP not that bad an idea, especially when transferring large
amount of data such as Usenet news.  On TCP-based links, news is
generally exchanged using the NNTP protocol, where 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 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 standard way to transfer these
batches is to use UUCP over TCP.


In \file{sys}, you would specify a system to be called via TCP
in the following way:


\begin{tscreen}
\begin{verbatim}
system          gmu
address         news.groucho.edu
time            Any
port            tcp-conn
chat            ogin: vstout word: clouseau
\end{verbatim}
\end{tscreen}


The \keyword{address} command gives the IP address of the host, or its
fully qualified domain name.  The corresponding \file{port} entry would
read:


\begin{tscreen}
\begin{verbatim}
port            tcp-conn
type            tcp
service         540
\end{verbatim}
\end{tscreen}


The entry states that a TCP connection should be used when a \file{sys}
entry references \keyword{tcp-conn}, and that \prog{uucico} should
attempt to connect to the TCP network port 540 on the remote host.  This
is the default port number of the UUCP service. Instead of the port
number, you may also give a symbolic port name to the \keyword{service}
command. The port number corresponding to this name will be looked up
in \file{/etc/services}. The common name for the UUCP service is
\keyword{uucpd}.



\subsection{Using a Direct Connection}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% The intricacies of specifying a direct line.                  %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!direct lines}

Assume you use a direct line connecting your system \host{vstout}
to \host{tiny}. Very much like in the modem case, you have to
write a system entry in the \file{sys} file. The \keyword{port} command
identifies the serial port \keyword{tiny} is hooked up to.


\begin{tscreen}
\begin{verbatim}
system          tiny
time            Any
port            direct1
speed           38400
chat            ogin: cathcart word: catch22
\end{verbatim}
\end{tscreen}


In the \file{port} file, you have to describe the serial port for the
direct connection. A \keyword{dialer} entry is not needed, because
there's no need for dialing.


\begin{tscreen}
\begin{verbatim}
port            direct1
type            direct
speed           38400
\end{verbatim}
\end{tscreen}




\section{The Do's and Dont's of UUCP~-- Tuning Permissions}
\label{uucp.permissions}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Security Options						%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{security!UUCP|(}
\index{access!UUCP|(}

\subsection{Command Execution}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!restrict!command execution}
\index{UUCP!command execution}

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~-- allowing them to execute any command on your system is
definitely not a good idea.


\index{SMTP!batched}
\index{rmail@\prog{rmail}}
\index{rnews@\prog{rnews}}
\index{UUCP!mail}
\index{UUCP!news}
By default, the only commands Taylor UUCP allows other systems to
execute on your machine are \prog{rmail} and \prog{rnews}, which are
commonly used to to exchange email and Usent news over UUCP. The default
search path used by \prog{uuxqt} is a compile-time option, but should
usually contain \file{/bin}, \file{/usr/bin}, and \file{/usr/local/bin}.
To change the set of commands for a particular system, you can use the
\keyword{commands} keyword in the \file{sys} file. Similarly, the search
path can be changed with the \keyword{command-path} statement.  For
instance, you may want to allow system \host{pablo} to execute the
\prog{rsmtp} command in addition to \prog{rmail} and
\prog{rnews}:\footnote{
  \prog{rsmtp} is used to deliver mail with batched SMTP. This is
  described in the mail chapters.
}


\begin{tscreen}
\begin{verbatim}
system          pablo
...
commands        rmail rnews rsmtp
\end{verbatim}
\end{tscreen}



\subsection{File Transfers}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!restrict!file transfer}
\index{UUCP!file transfer}

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 \keyword{request} to \keyword{no}, and
the remote system will not be able either to 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
\keyword{transfer} to \keyword{no}.  By default, users on both the
local and the remote system are allowed to up- and download files.


In addition, you can configure the directories to and from which files may
be copied. 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 will be allowed
to receive files only from the public UUCP directory, \publicspool.
This is the traditional place to make files publicly available; very
much like FTP servers on the Internet.  It is commonly referred to using
the tilde character.



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


\begin{tscreen}
\begin{verbatim}
system          pablo
...
local-send      /home ~
local-receive   /home ~/receive
remote-send     ~ !~/incoming !~/receive
remote-receive  ~/incoming
\end{verbatim}
\end{tscreen}


The \keyword{local-send} command allows users on your host to send any
files below \file{/home} and from the public UUCP directory to
\host{pablo}. The \keyword{local-receive} command allows them to
receive files either to the world-writable \file{receive} directory in
the \pubdir, or any world-writable directory below \file{/home}.  The
\keyword{remote-send} directive allows \host{pablo} to request files
from \publicspool, except for files below the \file{incoming} and
\file{receive} directories. This is signaled to \prog{uucico} by
preceding the directory names with exclamation marks. Finally, the
last line allows \host{pablo} to upload any files to \host{incoming}.


One of the biggest problems with file transfers using UUCP is that
will only receive files to directories that are world-writable.
This may tempt some users to set up traps for other users, etc.
However, there's no way escaping this problem except disabling UUCP
file transfers altogether.


\subsection{Forwarding}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!restrict!forwarding}
\index{UUCP!forwarding}

UUCP provides a mechanism to have other systems execute file transfers
on your behalf.  For instance, this allows you to make \host{seci}
retrieve a file from \host{uchile} for you, and send it to your
system.  The following command would achieve this:


\begin{tscreen}
\begin{verbatim}
$ uucp -r seci!uchile!~/find-ls.gz ~/uchile.files.gz
\end{verbatim}
\end{tscreen}


This technique of passing a job through several systems is called
\emph{forwarding}.   In the above example, the reason to use forwarding
may be that \host{seci} has UUCP access to \host{uchile}, but your
host doesn't.  However, if you run a 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.


By default, Taylor UUCP disallows forwarding altogether. To enable
forwarding for a particular system, you can use the \keyword{forward}
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 \host{seci} would have to add the following lines to
the \file{sys} file to allow \host{pablo} to request files from
\host{uchile}:


\begin{tscreen}
\begin{verbatim}
####################
# pablo
system          pablo
...
forward         uchile
####################
# uchile
system          uchile
...
forward-to      pablo
\end{verbatim}
\end{tscreen}


The \keyword{forward-to} entry for \host{uchile} is necessary so that
any files returned by it are actually passed on to \host{pablo}.
Otherwise UUCP would drop them. This entry uses a variation of the
\keyword{forward} command that permits \host{uchile} only to send
files to \host{pablo} through \host{seci}; not the other way round.


To permit forwarding to any system, use the special keyword \keyword{ANY}
(capital letters required).



\section{Setting up your System for Dialing in}
\label{uucp.dialin}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This section describes how to set up your system so that      %
% people can dial in.                                           %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!configure as server|(}
\index{UUCP!calling in}
\index{server!UUCP|(}

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. This will be the topic of the current section.


\subsection{Setting up \prog{getty}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{uucp.dialin.uugetty}
\index{UUCP!and getty@and \prog{getty}}
\index{uugetty@\prog{uugetty}}
\index{getty@\prog{getty}}
\index{mgetty@\prog{mgetty}}

If you want to use a serial line as a dialin port, you have to enable
a \prog{getty} process on this port.  However, some \prog{getty}
implementations aren't really suitable for this, because you usually
want to use a serial port for dialing in and out.  You therefore have
to make sure to use a \prog{getty} that is able to share the line with
other programs like \prog{uucico}, or \prog{minicom}. One program that
does this is \prog{uugetty} from the \file{getty\_ps} package.  Most
\linux{} distributions have it; check for \prog{uugetty} in your
\file{/sbin} directory.  Another program I am aware of is Gert
Doering's \prog{mgetty}, which also supports reception of facsimiles.
You can also obtain the latest versions of these from
\host{sunsite.unc.edu} as either binary or source.

%%% This is actually too complicated
% \prog{getty} uses a different type of serial port than those you use to
% dial out. For instance, when running \prog{getty} on a serial port, say
% COM4, it will use the dialin device file \file{ttyS3} instead of the
% callout device \file{cua3}.
% To avoid that an outgoing UUCP call disrupts the session of a user who
% dialed into your machine, the kernel forbids opening the corresponding
% callin and callout devices at the same time. That is, when \prog{uucico}
% tries to open \file{cua3} while a user is logged in in \file{ttyS3}, the
% open will fail and return an error indicating that the device is busy.
%
% ...and what all this means for the various getty operation modes...


Explaining the differences in the way \prog{uugetty} and \prog{mgetty}
handle logins is beyond the scope of this little section; for more
information, please refer to the Serial HOWTO by Grag Hankins, as well
as the documentation that comes along with \prog{getty\_ps} and
\prog{mgetty}.


\subsection{Providing UUCP Accounts}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{uucp.dialin.accounts}
\index{UUCP!accounts}
\index{UUCP!set up logins|(}

Next, 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 \host{pablo}, you would probably give it
\user{Upablo} as the user name.


For systems that dial in through the serial port, you usually have to
add these accounts to the system password file, \file{/etc/passwd}. A
good practice is to put all UUCP logins in a special group such as
\user{uuguest}.  The account's home directory should be set to the public
spool directory \publicspool; its login shell must be \prog{uucico}.


If you have the shadow password suite installed, you can do this with
the \prog{useradd} command:


\begin{tscreen}
\begin{verbatim}
# useradd -d /var/spool/uucppublic -G uuguest -s /usr/lib/uucp/uucico Upablo
\end{verbatim}
\end{tscreen}


If you don't use the shadow password suite, you probably have to edit
\file{/etc/passwd} by hand, adding a line like that shown below, where
5000 and 150 are the numerical uid and gid assigned to user
\user{Upablo} and group \user{uuguest}, respectively.


\begin{tscreen}
\begin{verbatim}
Upablo:x:5000:150:UUCP Account:/var/spool/uucppublic:/usr/lib/uucp/uucico
\end{verbatim}
\end{tscreen}


After installing the account, you have to activate it by setting its
password with the \prog{passwd} command.


To serve UUCP systems that connect to your site over TCP, you have to
set up \prog{inetd} to handle incoming connections on the
\keyword{uucp} port.  You do this by adding the following line to
\file{/etc/inetd.conf}:\footnote{
  Note that usually, \prog{tcpd} has mode 700, so that you must
  invoke it as user \user{root}, not \user{uucp} as you would
  usually do.
}


\begin{tscreen}
\begin{verbatim}
uucp   stream  tcp   nowait  root  /usr/sbin/tcpd  /usr/lib/uucp/uucico -l
\end{verbatim}
\end{tscreen}


\index{UUCP!passwd file@\file{passwd} file}
The \option{-l} option makes \prog{uucico} perform its own login
authorization. It will prompt for a login name and a password just like the
standard \prog{login} program, but will rely on its private password
database instead of \file{/etc/passwd}.  This private password file is
named \uucplib\file{/passwd} and contains pairs of login names and
passwords:


\begin{tscreen}
\begin{verbatim}
Upablo  IslaNegra
Ulorca  co'rdoba
\end{verbatim}
\end{tscreen}


Of course, this file must be owned by \user{uucp} and have permissions
of 600.


\index{mgetty@\prog{mgetty}}
If this database sounds like such a good idea you would like to use on
normal serial logins, too, you will be disappointed to hear that this
isn't possible at the moment without major contortions. First off, you
need Taylor UUCP~1.05 for this, because it allows \prog{getty} to pass
the login name of the calling user to \prog{uucico} using the
\option{-u} option.\footnote{
  The \option{-u} option is present in 1.04, too, but is only a no-op.
} Then, you have to trick the \prog{getty} you are using into invoking
\prog{uucico} instead of the usual \prog{/bin/login}. With
\file{getty\_ps}, you can do this by setting the \keyword{LOGIN} option in
the configuration file. However, this disables interactive logins
altogether.  \prog{mgetty}, on the other hand, has a nice feature that
allows you to invoke different login commands based on the name the user
provided. For instance, you can tell \prog{mgetty} to use \prog{uucico} for
all users that provide a login name beginning with a capital U, but let
everyone else be handled by the standard \prog{login} command.


To protect your UUCP users from callers giving a false system name
and snarfing all their mail, you should add \keyword{called-login}
commands to each system entry in the \file{sys} file. This is
described in section~\ref{uucp.security.called-login} above.

\index{UUCP!set up logins|)}


\subsection{Protecting Yourself Against Swindlers}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\namedlabel{uucp.security.called-login}{Protecting Yourself Against Swindlers}
\index{security!UUCP logins|(}
\index{UUCP!login security|(}

One of the biggest problems about 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 a way to check this. 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.


Unless you know you can trust all sites that call your system to be honest,
you \emph{must} guard against this sort of impostors. The cure against
this disease is to require each system to use a particular login name
by specifying a \keyword{called-login} in \file{sys}. A sample system entry
may look like this:


\begin{tscreen}
\begin{verbatim}
system          pablo
... usual options ...
called-login    Upablo
\end{verbatim}
\end{tscreen}


The upshot of this is that whenever a system logs in and pretends it is
\host{pablo}, \prog{uucico} will check whether it has logged in as
\user{Upablo}. If it hasn't, the calling system will be turned down, and
the connection is dropped. You should make it a habit to add the
\keyword{called-login} command to every system entry you add to your
\file{sys} file. It is important that you do this for \emph{all} sytems,
regardless of whether they will ever call your site or not. For those sites
that never call you, you should probably set \keyword{called-login} to some
totally bogus user name, such as \user{neverlogsin}.




\subsection{Be Paranoid~-- Call Sequence Checks}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!call sequence check|(}

Another way to fend off and detect impostors is to use call sequence
checks.  Call sequence checks help you protect against intruders that
somehow managed to find out the password you log into your UUCP system
with.


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


But call sequence checks do more for you than this: even if some very
clever person should detect your call sequence number as well as your
password, you will find this out. When the attacker call your UUCP feed
and steals your mail, this will increase the feeds call sequence number
by one.  The next time \emph{you} call your feed and try to log in, the
remote \prog{uucico} will refuse you, because the numbers don't match
anymore!


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
it, \prog{uucico} will put a message into the log file saying something
like ``Out of sequence call rejected''. 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 ``Handshake failed (RBADSEQ)''.


To enable call sequence checks, you have to add following command to the
system entry:


\begin{tscreen}
\begin{verbatim}
# enable call sequence checks
sequence        true
\end{verbatim}
\end{tscreen}


Beside this, you have to create the file containing the sequence number
itself.  Taylor UUCP keeps the sequence number is in a file called
\file{.Sequence} in the remote site's spool directory. It \emph{must}
be owned by \user{uucp}, and must be mode 600 (i.e. readable and
writeable only by \user{uucp}).  It is best to initialize this file with
an arbitrary, agreed-upon start value.  Otherwise, an attacker might
manage to guess the number by trying out all values smaller than, say,
60.


\begin{tscreen}
\begin{verbatim}
# cd /var/spool/uucp/pablo
# echo 94316 > .Sequence
# chmod 600 .Sequence
# chown uucp.uucp .Sequence
\end{verbatim}
\end{tscreen}


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

\index{UUCP!call sequence check|)}

\index{security!UUCP logins|)}
\index{UUCP!login security|)}

\index{server!UUCP|)}
\index{security!UUCP|)}
\index{access!UUCP|)}



\subsection{Anonymous UUCP}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!anonymous}
\index{anonymous UUCP}

If you want to provide anonymous UUCP access to your system, you first
have to set up a special account for it as described above.  A common
practive is to give it a login name and a password of \user{uucp}.


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
\file{sys} file entry, because the \keyword{system} command requires the
system's name, which you don't have. Taylor UUCP solves this dilemma
through the \keyword{unknown} command. \keyword{unknown} can be used in
the \file{config} file to specify any command that can usually appear in
a system entry:


\begin{tscreen}
\begin{verbatim}
unknown         remote-receive ~/incoming
unknown         remote-send ~/pub
unknown         max-remote-debug none
unknown         command-path /usr/lib/uucp/anon-bin
unknown         commands rmail
\end{verbatim}
\end{tscreen}


This will restrict unknown systems to downloading files from below the
\file{pub} directory and uploading files to the \file{incoming}
directory below \publicspool. The next line will make \prog{uucico}
ignore any requests from the remote system to turn on debugging
locally.  The last two lines permit unknown systems to execute
\prog{rmail}; but the command path specified makes \prog{uucico} look
for the \prog{rmail} command in a private directory named
\file{anon-bin} only. This allows you to provide some special
\prog{rmail} that, for instance, forwards all mail to the super-user
for examination. This allows anonymous users to reach the maintainer
of the system, but prevents them at the same time from injecting any
mail to other sites.


To enable anonymous UUCP, you must specify at least one \keyword{unknown}
statement in \file{config}. Otherwise \prog{uucico} will reject any unknown
systems.

\index{UUCP!configure as server|)}

\section{UUCP Low-Level Protocols}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{uucp.protocols}
\index{UUCP!protocol|(}

To negotiate session control and file transfers with the remote end,
\prog{uucico} uses a set of standardized messages. This is often
referred to as the high-level protocol. 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 is
employed which is mostly transparent to the higher levels. This is to
make error checks possible when using unreliable lines, for instance.


\subsection{Protocol Overview}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{protocol!UUCP}

As UUCP is used over different types of connections, such as serial
lines or TCP, or even X.25, specific low-level protocols are needed. In
addition, several implementations of UUCP have introduced different
protocols that do roughly the same thing.


Protocols can be divided into two categories: streaming and
packet-oriented protocols. Protocols of the latter variety transfer a
file as a whole, possibly computing a checksum over it. This is nearly
free of any 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.


On the other hand, packet protocols split up the file into several
chunks of equal size. Each packet is sent and received separately, a
checksum is computed, and an acknowledgement is returned to the sender.
To make this more efficient, sliding-window protocols were invented,
which allow for a limited number (a window) of outstanding
acknoledgements at any time.  This greatly reduces the amount of time
\prog{uucico} has to wait during a transmission.  Still, the relatively
large overhead compared to a streaming protocol make packet protocls
inefficient for use over TCP.


The width of the data path also makes a difference. Sometimes, sending
eight-bit characters over a serial connection is impossible, for
instance if the connection goes through a stupid terminal server.  In
this case, characters with the eighth bit set have to be quoted on
transmission.  When you transmit eight-bit characters over a seven-bit
connection, they have to be Under worst-case assumptions, this doubles
the amount of data to be transmitted, although compression done by the
hardware may compensate for this.  Lines that can transmit arbitrary
eight-bit characters are usually called eight-bit clean. This is the
case for all TCP connections, as well as for most modem connections.


The following protocols are available with Taylor UUCP 1.04:

\begin{dispitems}
\ditem[\emph{g}]
	This is the most common protocol and should be understood by
        virtually all \prog{uucico}'s. It does thorough error checking
        and is therefore well-suited for noisy telephone links.
        \emph{g}~requires an eight-bit clean connection.  It is a
        packet-oriented protocol which uses a sliding-window
        technique.

\ditem[\emph{i}]
	This is a bidirectional packet protocol which can send and
	receive files at the same time. It requires a full-duplex
	connection and an eight-bit clean data path. It is currently
	understood only by Taylor UUCP.

\ditem[\emph{t}]
	This is a protocol intended for use over a TCP connection, or
	other truly error-free networks.  It uses packets of 1024 bytes
	and requires an eight-bit clean connection.

\ditem[\emph{e}]
	This should basically do the same as \emph{t}. The main
	difference is that \emph{e}~is a streaming protocol.

\ditem[\emph{f}]
	This is intended for use with reliable X.25 connections.  It is
	a streaming protocol and expects a seven-bit data path.
	Eight-bit characters are quoted, which can make it very
	inefficient.

\ditem[\emph{G}]
	This is the System V Release 4 version of the \emph{g}~protocol.
	It is also understood by some other versions of UUCP.

\ditem[\emph{a}]
	This protocol is similiar to ZMODEM. It requires an eight bit
	connection, but quotes certain control characters like XON and
	XOFF.

\end{dispitems}


\subsection{Tuning the Transmission Protocol}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!protocol!tuning}

All protocols allow for some variation in packet sizes, timeouts, and
the like.  Usually, the defaults provided work well under standard
circumstances, but may not be optimal for your situation.  The \emph{g}
protocol, for instance, uses window sizes from 1 to 7, and packet sizes
in powers of 2 ranging from 64 through 4096.\footnote{
  Most binaries included in \linux{} distributions default to a window
  size of 7 and 128 byte packets.
}  If your telephone line is usually so noisy that it drops more than
5 percent 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 ACKs for every 128 bytes may prove
wasteful, so that you might increase the packet size to 512 or even
1024.


Taylor UUCP provides a meachanism to suit your needs by tuning these
parameters with the \keyword{protocol-parameter} command in the
\file{sys} file.  For instance, to set the \emph{g}~protocol's packet
size to 512 when talking to \host{pablo}, you have to add:


\begin{tscreen}
\begin{verbatim}
system          pablo
...
protocol-parameter g  packet-size  512
\end{verbatim}
\end{tscreen}


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


\subsection{Selecting Specific Protocols}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!protocol!selection}

Not every implementation of \prog{uucico} speaks and understand each
protocol, so during the initial handshake phase, both processes have to
agree on a common protocol.  The master \prog{uucico} offers the slave a
list of supported protocols by sending \term{P\var{protlist}}, from
which the slave may pick one.


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


\begin{tscreen}
\begin{verbatim}
port            serial1
...
protocols       igG
\end{verbatim}
\end{tscreen}


This will require any incoming or outgoing connection through this port
to use \emph{i}, \emph{g}, or \emph{G}. If the remote system does not
support any of these, the conversation will fail.

\index{UUCP!protocol|)}


\section{Troubleshooting}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Short and quick UUCP FAQ                                      %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{uucp.misc.faq}
\index{UUCP!troubleshooting}

This section describes what may go wrong with your UUCP connection, and
makes suggestions where to look for the error.  However, the questions
were compiled off the top of my head. There's much more that can go
wrong.


\index{UUCP!checking}
In any case, enable debugging with \option{-xall}, and take a look at
the output in \file{Debug} in the spool directory.  It should help you
to quickly recognize where the problem lies.  Also, I have always found
it helpful to turn on my modem's speaker when it didn't connect. With
Hayes-compatible modems, this is accomplished by adding ``\term{ATL1M1 OK}''
to the modem chat in the \file{dial} file.


The first check always should be whether all file permissions are set
correctly.  \prog{uucico} should be setuid \user{uucp}, and all files in
\uucplib, \uucpspool{} and \publicspool{} should be owned by
\user{uucp}. There are also some hidden files\footnote{
  That is, files whose name begins with a dot. Such files aren't
  normally displayed by the \prog{ls} command.
} in the spool directory which must be owned by \user{uucp} as well.


{\bf \prog{uucico} keeps saying ``Wrong time to call''}:
This probably means that in the system entry in \file{sys}, you didn't
specify a \keyword{time} command that details when the remote system may
be called, or you gave one which actually forbids calling at the current
time. If no call schedule is given, \prog{uucico} assumes that the
system may never be called.


{\bf \prog{uucico} complains that the site is already locked}:
This means that \prog{uucico} detected a lock file for the remote
system in \uucpspool.  The lock file may be from an earlier call to
the system that crashed, or was killed. However, it's also likely that
there's another \prog{uucico} process sitting around that is trying to
dial the remote system and got stuck in a chat script, etc. If this
\prog{uucico} process doesn't succeed in connecting to the remote
system, kill it with a hangup signal, and remove any lock files it left
lying around.


{\bf I can connect to the remote site, but the chat script fails}:
Look at the text you receive from the remote site. If it's garbled, this
might be a speed-related problem.  Otherwise, confirm if it really
agrees with what your chat script expects.  Remember, the chat script
starts with an expect string. If you receive the login prompt, then 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.


{\bf My modem does not dial}:
If your modem doesn't indicate that the DTR line has been raised when
\prog{uucico} calls out, you possibly haven't given the right device to
\prog{uucico}. If your modem recognizes DTR, check with a terminal
program that you can write to it. If this works, turn on echoing with
\keyword{\bs E} at the start of the modem chat. If it doesn't echo your
commands during the modem chat, check if your line speed is too high or
low for your modem. 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.


{\bf My modem tries to dial, but doesn't get out}:
Insert a delay into the phone number. This is especially useful when
dialing out from a company's internal telephone net.  For people in
Europe, who usually dial pulse-tone, try touch-tone.  In some countries,
postal services have been upgrading their nets recently. Touch-tone
sometimes helps.


{\bf I log file says I have extremely high packet loss rates}:
This looks like a speed problem. Maybe the link between computer and
modem is too slow (remember to adapt it to the highest effective rate
possible)? Or is it your hardware that is too slow to service interrupts
in time? With a NSC~16550A chipset on your serial port, 38kbps are said
to work reasonably well; however, without FIFOs (like 16450 chips), 9600
bps is the limit. Also, you should make sure hardware handshake is
enabled on the serial line.


Another likely cause is that hardware handshake isn't enabled on the
port.  Taylor UUCP 1.04 has no provisions for turning on RTS/CTS
handshake.  You have to enable this explicitly from \file{rc.serial}
using the following command:


\begin{tscreen}
\begin{verbatim}
$ stty crtscts < /dev/cua3
\end{verbatim}
\end{tscreen}


{\bf I can log in, but handshake fails}:
Well, there can be a number of problems. The output in the log file
should tell you a lot. Look at what protocols the remote site offers (It
sends a string \term{P}\var{protlist} during the handshake).  Maybe they
don't have any in common (did you select any protocols in \file{sys} or
\file{port}?).


If the remote system sends \term{RLCK}, there is a stale lockfile for
you on the remote system. If it's not because you're already connected
to the remote system on a different line, ask to have it removed.


If it sends \term{RBADSEQ}, the other site has conversation count checks
enabled for you, but numbers didn't match. If it sends \term{RLOGIN},
you were not permitted to login under this id.


\section{Log Files}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This section-to-be describes the function of the logfiles,    %
% and says a little about how to read them.                     %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\index{UUCP!logging and debugging|(}


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 \file{Log} and contains all information about
connections established and files transferred. A typical excerpt looks
like this (after a little reformatting to make it fit the page):


\begin{tscreen}
\begin{verbatim}
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)
\end{verbatim}
\end{tscreen}


\index{UUCP!statistics}
The next important log file is \file{Stats}, which lists file transfer
statistics.  The section of \file{Stats} corresponding to the above
transfer looks like this:


\begin{tscreen}
\begin{verbatim}
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)
\end{verbatim}
\end{tscreen}


Again, the lines have been split to make it fit the page.

The third file if \file{Debug}. This is the place where debugging
information is written. If you use debugging, you should make sure
that this file has a protection mode of 600. Depending on the debug
mode you selected, it may contain the login and password you use to
connect to the remote system.


\index{UUCP!HDB}
Some UUCP binaries included in \linux{} distributions have been compiled
to use HDB-style logging. HDB UUCP uses a whole bunch of log files
stored below \uucpspool\file{/.Log}. This directory contains three more
directories, named \prog{uucico}, \prog{uuxqt}, and \prog{uux}.  They
contain the logging output generated by each of the corresponding
commands, sorted into different files for each site. Thus, output from
\prog{uucico} when calling site \host{pablo} will go into
\file{.Log/uucico/pablo}, while the subsequent \prog{uuxqt} run will
write to \file{.Log/uuxqt/pablo}. The lines written to the various
lofiles are however the same as with Taylor logging.


When you enable debugging output with HDB-style logging compiled in, it
will go to the \file{.Admin} directory below \uucpspool. During outgoing
calls, debugging information will be sent to \file{.Admin/audit.local},
while the output from \prog{uucico} when someone calls in will go to
\file{.Admin/audit}.

\index{UUCP!logging and debugging|)}



\index{UUCP|)}
\index{configuring!UUCP|)}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                               %
%                E N D   O F   C H A P T E R                    %
%                                                               %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
