From b301e74e7ac3bfe1e7f6386c868af0b094aa5221 Mon Sep 17 00:00:00 2001 From: ache Date: Wed, 25 May 1994 19:04:00 +0000 Subject: Documentation added --- gnu/libexec/uucp/doc/uucp.texi | 4036 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 4036 insertions(+) create mode 100644 gnu/libexec/uucp/doc/uucp.texi (limited to 'gnu/libexec') diff --git a/gnu/libexec/uucp/doc/uucp.texi b/gnu/libexec/uucp/doc/uucp.texi new file mode 100644 index 0000000..5ab7411 --- /dev/null +++ b/gnu/libexec/uucp/doc/uucp.texi @@ -0,0 +1,4036 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename uucp.info +@settitle Taylor UUCP +@setchapternewpage odd +@c %**end of header + +@iftex +@finalout +@end iftex + +@ignore +----------------------------------------------------------------------> +Franc,ois Pinard says: + +Hi, Ian! This is the promised merging of the current documents from +Taylor UUCP 1.01, plus the patches to documentation you sent to me, into +a taylor.texi file. Many things remain to do, among which: + +- merging in the Taylor UUCP program man pages. +----------------------------------------------------------------------< +@end ignore + +@ifinfo +This file documents Taylor UUCP, version 1.05. + +Copyright @copyright{} 1992, 1993, 1994 Ian Lance Taylor + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``Copying'' are included exactly as in the original, and +provided that the entire resulting derived work is distributed under the +terms of a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the section entitled ``Copying'' may be included in a +translation approved by the author instead of in the original English. +@end ifinfo + +@titlepage +@title Taylor UUCP +@subtitle Version 1.05 +@author Ian Lance Taylor @code{} + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1992, 1993, 1994 Ian Lance Taylor + +Published by Ian Lance Taylor @code{}. + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``Copying'' are included exactly as in the original, and +provided that the entire resulting derived work is distributed under the +terms of a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the section entitled ``Copying'' may be included in a +translation approved by the author instead of in the original English. +@end titlepage + +@node Top, Copying, (dir), (dir) +@top Taylor UUCP 1.05 + +This is the documentation for the Taylor UUCP package, version 1.05. +The programs were written by Ian Lance Taylor. The author can be +reached at @code{}, or @samp{c/o Cygnus Support, Building +200, 1 Kendall Square, Cambridge, MA, 02139, USA}. + +There is a mailing list for discussion of the package. To join (or get +off) the list, send mail to +@code{}. Mail to this address is +answered by a person, not a program. When joining the list, please give +the address at which you wish to receive mail; do not rely on the +message headers. To send a message to the list, send it to +@code{}. + +Jeff Ross has volunteered to maintain patches for UUCP releases. They +may be obtained via anonymous FTP from ftp.fdu.edu, in the directory +pub/taylor-uucp. + +@menu +* Copying:: Taylor UUCP copying conditions +* Introduction:: Introduction to Taylor UUCP +* Overall Installation:: Taylor UUCP installation +* Configuration Files:: Taylor UUCP configuration files +* Protocols:: UUCP protocol internals +* Hacking:: Hacking Taylor UUCP +* Acknowledgements:: Acknowledgements + +* Index (concepts):: Concept index +* Index (configuration file):: Index to new configuration files + + --- The Detailed Node Listing --- + +Taylor UUCP Overall Installation + +* Configuration:: Configuring Taylor UUCP +* Compilation:: Compiling Taylor UUCP +* Testing:: Testing Taylor UUCP +* Installation:: Installing Taylor UUCP +* TCP:: TCP together with Taylor UUCP + +Installing Taylor UUCP + +* Running uucico:: Running uucico +* Using UUCP for mail and news:: Using UUCP for mail and news. +* Trimming UUCP Log Files:: Trimming UUCP Log Files + +Using UUCP for mail and news. + +* Sending mail or news:: Sending mail or news via UUCP +* Receiving mail or news:: Receiving mail or news via UUCP + +Taylor UUCP Configuration Files + +* Configuration File Format:: Configuration file format +* Configuration File Overview:: Configuration File Overview +* Configuration Examples:: Examples of configuration files +* Time Strings:: How to write time strings +* Chat Scripts:: How to write chat scripts +* config File:: The main configuration file +* sys File:: The system configuration file +* port File:: The port configuration files +* dial File:: The dialer configuration files +* Security:: Security issues + +Examples of Configuration Files + +* config File Examples:: Examples of the main configuration file +* Leaf Example:: Call a single remote site +* Gateway Example:: The gateway for several local systems + +The Main Configuration File + +* Miscellaneous (config):: Miscellaneous config file commands +* Configuration File Names:: Using different configuration files +* Log File Names:: Using different log files +* Debugging Levels:: Debugging levels + +The System Configuration File + +* Defaults and Alternates:: Using defaults and alternates +* Naming the System:: Naming the system +* Calling Out:: Calling out +* Accepting a Call:: Accepting a call +* Protocol Selection:: Protocol selection +* File Transfer Control:: File transfer control +* Miscellaneous (sys):: Miscellaneous sys file commands +* Default sys File Values:: Default values + +Calling Out + +* When to Call:: When to call +* Placing the Call:: Placing the call +* Logging In:: Logging in + +Hacking Taylor UUCP + +* System Dependence:: System Dependence +* Naming Conventions:: Naming Conventions +* Patches:: Patches +@end menu + +@node Copying, Introduction, Top, Top +@unnumbered Taylor UUCP Copying Conditions + +This package is covered by the GNU Public License. See the file +@file{COPYING} for details. If you would like to do something with this +package that you feel is reasonable, but you feel is prohibited by the +license, contact me to see if we can work it out. + +Here is some propaganda from the Free Software Foundation. If you find +this stuff offensive or annoying, remember that you probably did not +spend any money to get this code. I did not write this code to make +life easier for developers of UUCP packages, I wrote it to help end +users, and I believe that these are the most appropriate conditions for +distribution. + +All the programs, scripts and documents relating to Taylor UUCP are +@dfn{free}; this means that everyone is free to use them and free to +redistribute them on a free basis. The Taylor UUCP-related programs are +not in the public domain; they are copyrighted and there are +restrictions on their distribution, but these restrictions are designed +to permit everything that a good cooperating citizen would want to do. +What is not allowed is to try to prevent others from further sharing any +version of these programs that they might get from you. + +Specifically, we want to make sure that you have the right to give away +copies of the programs that relate to Taylor UUCP, that you receive +source code or else can get it if you want it, that you can change these +programs or use pieces of them in new free programs, and that you know +you can do these things. + +To make sure that everyone has such rights, we have to forbid you to +deprive anyone else of these rights. For example, if you distribute +copies of the Taylor UUCP related programs, you must give the recipients +all the rights that you have. You must make sure that they, too, +receive or can get the source code. And you must tell them their +rights. + +Also, for our own protection, we must make certain that everyone finds +out that there is no warranty for the programs that relate to Taylor +UUCP. If these programs are modified by someone else and passed on, we +want their recipients to know that what they have is not what we +distributed, so that any problems introduced by others will not reflect +on our reputation. + +The precise conditions of the licenses for the programs currently being +distributed that relate to Taylor UUCP are found in the General Public +Licenses that accompany them. + +@node Introduction, Overall Installation, Copying, Top +@chapter Introduction to Taylor UUCP + +General introductions to UUCP are available, and perhaps one day I will +write one. In the meantime, here is a very brief one that concentrates +on the programs provided by Taylor UUCP. + +Taylor UUCP is a complete UUCP package. It is covered by the GNU Public +License, which means that the source code is always available. It is +composed of several programs; most of the names of these programs are +based on earlier UUCP packages. + +@table @code + +@item uucp + +The @code{uucp} program is used to copy file between systems. It is +similar to the standard Unix @code{cp} program, except that you can +refer to a file on a remote system by using @samp{system!} before the +file name. For example, to copy the file @file{notes.txt} to the system +@samp{airs}, you would say @samp{uucp notes.txt airs!~/notes.txt}. In +this example @samp{~} is used to name the UUCP public directory on +@samp{airs}. + +@item uux + +The @code{uux} program is used to request the execution of a program on +a remote system. This is how mail and news are transferred over UUCP. +As with @code{uucp}, programs and files on remote systems may be named +by using @samp{system!}. For example, to run the @code{rnews} program +on @samp{airs} passing it standard input, you would say @samp{uux - +airs!rnews}. The @samp{-} means to read standard input and set things +up such that when @code{rnews} runs on @samp{airs} it will receive the +same standard input. + +@end table + +Neither @code{uucp} nor @code{uux} actually do any work immediately. +Instead, they queue up requests for later processing. They then start a +daemon process which processes the requests and calls up the appropriate +systems. Normally the system will also start the daemon periodically to +check if there is any work to be done. The advantage of this approach +is that it all happens automatically. You don't have to sit around +waiting for the files to be transferred. The disadvantage is that if +anything goes wrong it might be a while before anybody notices. + +@table @code + +@item uustat + +The @code{uustat} program does many things. By default it will simply +list all the jobs you have queued with @code{uucp} or @code{uux} that +have not yet been processed. You can use @code{uustat} to remove any of +your jobs from the queue. You can also it use it to show the status of +the UUCP system in various ways, such as showing the connection status +of all the remote systems your system knows about. The system +administrator can use @code{uustat} to automatically discard old jobs +while sending mail to the user who requested them. + +@item uuname + +The @code{uuname} program by default lists all the remote systems your +system knows about. You can also use it to get the name of your local +system. It is mostly useful for shell scripts. + +@item uulog + +The @code{uulog} program can be used to display entries in the UUCP log +file. It can select the entries for a particular system or a particular +user. You can use it to see what has happened to your queued jobs in +the past. + +@item uuto +@item uupick + +@code{uuto} is a simple shell script interface to @code{uucp}. It will +transfer a file, or the contents of a directory, to a remote system, and +notify a particular user on the remote system when it arrives. The +remote user can then retrieve the file(s) with @code{uupick}. + +@item cu + +The @code{cu} program can be used to call up another system and +communicate with it as though you were directly connected. It can also +do simple file transfers, though it does not provide any error checking. + +@end table + +These eight programs just described, @code{uucp}, @code{uux}, +@code{uuto}, @code{uupick}, @code{uustat}, @code{uuname}, @code{uulog}, +and @code{cu} are the user programs provided by Taylor UUCP@. +@code{uucp}, @code{uux}, and @code{uuto} add requests to the work queue, +@code{uupick} extracts files from the UUCP public directory, +@code{uustat} examines the work queue, @code{uuname} examines the +configuration files, @code{uulog} examines the log files, and @code{cu} +just uses the UUCP configuration files. + +The real work is actually done by two daemon processes, which are +normally run automatically rather than by a user. + +@table @code + +@item uucico + +The @code{uucico} daemon is the program which actually calls the remote +system and transfers files and requests. @code{uucico} is normally +started automatically by @code{uucp} and @code{uux}. Most systems will +also start it periodically to make sure that all work requests are +handled. @code{uucico} checks the queue to see what work needs to be +done, and then calls the appropriate systems. If the call fails, +perhaps because the phone line is busy, @code{uucico} leaves the +requests in the queue and goes on to the next system to call. It is +also possible to force @code{uucico} to call a remote system even if +there is no work to be done for it, so that it can pick up any work that +may be queued up remotely. + +@need 1000 +@item uuxqt + +The @code{uuxqt} daemon processes execution requests made by the +@code{uux} program on remote systems. It also processes requests made +on the local system which require files from a remote system. It is +normally started by @code{uucico}. + +@end table + +Suppose you, on the system @samp{bantam}, want to copy a file to the +system @samp{airs}. You would run the @code{uucp} command locally, with +a command like @samp{uucp notes.txt airs!~/notes.txt}. This would queue +up a request on @samp{bantam} for @samp{airs}, and would then start the +@code{uucico} daemon. @code{uucico} would see that there was a request +for @samp{airs} and attempt to call it. When the call succeeded, +another copy of @code{uucico} would be started on @samp{airs}. The two +copies of @code{uucico} would tell each other what they had to do and +transfer the file from @samp{bantam} to @samp{airs}. When the file +transfer was complete the @code{uucico} on @samp{airs} would move it +into the UUCP public directory. + +UUCP is often used to transfer mail. This is normally done +automatically by mailer programs. When @samp{bantam} has a mail message +to send to @samp{ian} at @samp{airs}, it executes @samp{uux - airs!rmail +ian} and writes the mail message to the @code{uux} process as standard +input. The @code{uux} program, running on @samp{bantam}, will read the +standard input and store it, as well as the @code{rmail} request itself, +on the work queue for @samp{airs}. @code{uux} will then start the +@code{uucico} daemon. The @code{uucico} daemon will call up +@samp{airs}, just as in the @code{uucp} example, and transfer the work +request and the mail message. The @code{uucico} daemon on @samp{airs} +will put the files on a local work queue. When the communication +session is over, the @code{uucico} daemon on @samp{airs} will start the +@code{uuxqt} daemon. @code{uuxqt} will see the request to run, and will +run @samp{rmail ian} with the mail message as standard input. The +@code{rmail} program, which is not part of the UUCP package, is then +responsible for either putting the message in the right mailbox on +@samp{airs} or forwarding the message on to another system. + +Taylor UUCP comes with a few other programs that are useful when +installing and configuring UUCP. + +@table @code + +@item uuchk + +The @code{uuchk} program reads the UUCP configuration files and displays +a rather lengthy description of what it finds. This is useful when +configuring UUCP to make certain that the UUCP package will do what you +expect it to do. + +@item uuconv + +The @code{uuconv} program can be used to convert UUCP configuration +files from one format to another. This can be useful for administrators +converting from an older UUCP. Taylor UUCP is able to read and use old +configuration file formats, but some new features can not be selected +using the old formats. + +@item uusched + +The @code{uusched} script is just provided for compatibility with older +UUCP releases. It starts @code{uucico} to call, one at a time, all the +systems for which work has been queued. + +@item tstuu + +The @code{tstuu} program is a test harness for the UUCP package; it can +help check that the package has been configured and compiled correctly. +However, it uses pseudo-terminals, which means that it is less portable +than the rest of the package. If it works, it can be useful when +initially installing Taylor UUCP. + +@end table + +@node Overall Installation, Configuration Files, Introduction, Top +@chapter Taylor UUCP Overall Installation + +These are the installation instructions for the Taylor UUCP package. + +@menu +* Configuration:: Configuring Taylor UUCP +* Compilation:: Compiling Taylor UUCP +* Testing:: Testing Taylor UUCP +* Installation:: Installing Taylor UUCP +* TCP:: TCP together with Taylor UUCP +@end menu + +@node Configuration, Compilation, Overall Installation, Overall Installation +@section Configuring Taylor UUCP + +You will have to decide what types of configuration files you want to +use. This package supports a new sort of configuration file; see +@ref{Configuration Files}. It also supports V2 configuration files +(@file{L.sys}, @file{L-devices}, etc.) and HDB configuration files +(@file{Systems}, @file{Devices}, etc.). No documentation is provided +for V2 or HDB configuration files. All types of configuration files can +be used at once, if you are so inclined. Currently using just V2 +configuration files is not really possible, because there is no way to +specify a dialer (there are no built in dialers, and the program does +not know how to read @file{acucap} or @file{modemcap}); however, V2 +configuration files can be used with a new style dial file (@pxref{dial +File}), or with a HDB @file{Dialers} file. + +Use of HDB configuration files has two known bugs. A blank line in the +middle of an entry in the @file{Permissions} file will not be ignored as +it should be. Dialer programs, as found in some versions of HDB, are +not recognized directly. If you must use a dialer program, rather than +an entry in @file{Devices}, you must use the @code{chat-program} command +in a new style dial file; see @ref{dial File}. You will have to invoke +the dialer program via a shell script or another program, since an exit +code of 0 is required to recognize success; the @code{dialHDB} program +in the @file{contrib} directory may be used for this purpose. + +The @code{uuconv} program can be used to convert from V2 or HDB +configuration files to the new style (it can also do the reverse +translation, if you are so inclined). It will not do all of the work, +and the results should be carefully checked, but it can be quite useful. + +If you are installing a new system, you will, of course, have to write +the configuration files; see @ref{Configuration Files}. + +You must also decide what sort of spool directory you want to use. If +you will be using only these programs for UUCP, I recommend +@samp{SPOOLDIR_TAYLOR}; otherwise select the spool directory +corresponding to your existing UUCP package. The details of the spool +directory choices are described at somewhat tedious length in +@file{unix/spool.c}. + +@node Compilation, Testing, Configuration, Overall Installation +@section Compiling Taylor UUCP + +@enumerate + +@item +Take a look at the top of @file{Makefile.in} and set the appropriate +values for your system. These control where the programs are installed +and which user on the system owns them (normally they will be owned by a +special user @code{uucp} rather than a real person; they should probably +not be owned by @code{root}). + +@item +Run the shell script @code{configure}. This script was generated using +the @code{autoconf} program written by David MacKenzie of the Free +Software Foundation. It takes a while to run. It will generate the +file @file{config.h} based on @file{config.h.in}, and, for each source +code directory, will generate @file{Makefile} based on +@file{Makefile.in}. + +You can pass certain arguments to @code{configure} in the environment. +Because @code{configure} will compile little test programs to see what +is available on your system, you must tell it how to run your compiler. +It recognizes the following environment variables: + +@table @samp +@item CC +The C compiler. If this is not set, then if @code{configure} can find +@samp{gcc} it will use it, otherwise it will use @samp{cc}. +@item CFLAGS +Flags to pass to the C compiler when compiling the actual code. If this +is not set, @code{configure} will use @samp{-g}. +@item LDFLAGS +Flags to pass to the C compiler when only linking, not compiling. If +this is not set, @code{configure} will use the empty string. +@item LIBS +Libraries to pass to the C compiler. If this is not set, +@code{configure} will use the empty string. +@item INSTALL +The program to run to install UUCP in the binary directory. If this is +not set, then if @code{configure} finds the BSD @code{install} program, +it will set this to @samp{install -c}; otherwise, it will use @samp{cp}. +@item INSTALLDATA +The program to run to install UUCP data files, such as the man pages and +the info pages. If this is not set, then if @code{configure} finds the +BSD @code{install} program, it will set this to @samp{install -c -m +644}; otherwise, it will use @samp{cp}. +@end table + +Suppose you want to set the environment variable @samp{CC} to +@samp{rcc}. If you are using @code{sh} or @code{bash}, invoke +@code{configure} as @samp{CC=rcc configure}. If you are using +@code{csh}, do @samp{setenv CC rcc; sh configure}. + +On some systems you will want to use @samp{LIBS=-lmalloc}. On Xenix +derived versions of Unix do not use @samp{LIBS=-lx} because this will +bring in the wrong versions of certain routines; if you want to use +@samp{-lx} you must specify @samp{LIBS=-lc -lx}. + +If @code{configure} fails for some reason, or if you have a very weird +system, you may have to configure the package by hand. To do this, copy +the file @file{config.h.in} to @file{config.h} and edit it for your +system. Then for each source directory (the top directory, and the +subdirectories @file{lib}, @file{unix}, and @file{uuconf}) copy +@file{Makefile.in} to @file{Makefile}, find the words within @kbd{@@} +characters, and set them correctly for your system. + +@item +Igor V. Semenyuk provided this (lightly edited) note about ISC Unix 3.0. +The @code{configure} script will default to passing @samp{-posix} to +@code{gcc}. However, using @samp{-posix} changes the environment to +POSIX, and on ISC 3.0, at least, the default for POSIX_NO_TRUNC is 1. +This means nothing for uucp, but can lead to a problem when uuxqt +executes rmail. IDA sendmail has dbm configuration files named +@file{mailertable.@{dir,pag@}}. Notice these names are 15 characters +long. When uuxqt compiled with @samp{-posix} executes rmail, which in +turn executes sendmail, the later is run under POSIX environment too! +This leads to sendmail bombing out with @samp{'error opening 'M' +database: name too long' (mailertable.dir)}. It's rather obscure +behaviour, and it took me a day to find out the cause. I don't use +@samp{-posix}, instead I run @code{gcc} with @samp{-D_POSIX_SOURCE}, and +add @samp{-lcposix} to @samp{LIBS}. + +@item +On some versions of BSDI there is a bug in the shell which causes the +default value for @samp{CFLAGS} to be set incorrectly. If @samp{echo +$@{CFLAGS--g@}} echoes @samp{g} rather than @samp{-g}, then you must set +@samp{CFLAGS} in the environment before running configure. There is a +patch available from BSDI for this bug. (From David Vrona). + +@item +On AIX 3.2.5, and possibly other versions, @samp{cc -E} does not work, +reporting @samp{Option NOROCONST is not valid}. Test this before +running configure by doing something like @samp{touch /tmp/foo.c; cc -E +/tmp/foo.c}. This may give a warning about the file being empty, but it +should not give the @samp{Option NOROCONST} warning. The workaround is +to remove the @samp{,noroconst} entry from the @samp{options} clause in +the @samp{cc} stanza in @file{/etc/xlc.cfg}. (From Chris Lewis). + +@item +You should verify that @code{configure} worked correctly by checking +@file{config.h} and the instances of @file{Makefile}. + +@item +Edit @file{policy.h} for your local system. The comments should explain +the various choices. The default values are intended to be reasonable, +so you may not have to make any changes. + +@item +Type @samp{make} to compile everything. The @file{tstuu.c} file is not +particularly portable; if you can't figure out how to compile it you can +safely ignore it, as it is only used for testing (to use STREAMS +pseudo-terminals, tstuu.c must be compiled with +@samp{-DHAVE_STREAMS_PTYS}; this is not automatically determined at the +moment). If you have any other problems there is probably a bug in the +@code{configure} script. + +@item +Please report any problems you have. That is the only way they will get +fixed for other people. Supply a patch if you can (@pxref{Patches}), or +just ask for help. + +@end enumerate + +@node Testing, Installation, Compilation, Overall Installation +@section Testing Taylor UUCP + +This package is in use at hundreds, perhaps thousands, of sites, and has +been running at @file{airs.com} for several years. However, it will +doubtless fail in some situations. Do not rely on this code until you +have proven to yourself that it will work. + +You can use the @code{uuchk} program to test your configuration files. +It will read them and print out a verbose description. This program +should not be made setuid, because it will display passwords if it can +read them. + +If your system supports pseudo-terminals, and you compiled the code to +support the new style of configuration files, you should be able to use +the @code{tstuu} program to test the @code{uucico} daemon (if your +system supports STREAMS based pseudo-terminals, you must compile tstuu.c +with @samp{-DHAVE_STREAMS_PTYS}, at least at the moment; the STREAMS +based code was contributed by Marc Boucher). + +To run @code{tstuu}, just type @samp{tstuu} with no arguments while +logged in to the compilation directory (since it runs @file{./uucp}, +@file{./uux} and @file{./uucico}). It will run a lengthy series of +tests (it takes over ten minutes on a slow VAX). You will need a fair +amount of space available in @file{/usr/tmp}. You will probably want to +put it in the background. Do not use @kbd{^Z}, because the program +traps on @code{SIGCHLD} and winds up dying. It will create a directory +@file{/usr/tmp/tstuu} and fill it with configuration files, and create +spool directories @file{/usr/tmp/tstuu/spool1} and +@file{/usr/tmp/tstuu/spool2}. + +If your system does not support the @code{FIONREAD} call, the +@samp{tstuu} program will run very slowly. This may or may not get +fixed in a later version. + +The program will finish with an execute file named +@file{X.@var{something}} and a data file named @file{D.@var{something}} +in the directory @file{/usr/tmp/tstuu/spool1} (or, more likely, in +subdirectories, depending on the choice of @code{SPOOLDIR} in +@file{policy.h}). Two log files will be created in the directory +@file{/usr/tmp/tstuu}. They will be named @file{Log1} and @file{Log2}, +or, if you have selected @code{HAVE_HDB_LOGGING} in @file{policy.h}, +@file{Log1/uucico/test2} and @file{Log2/uucico/test1}. You can test +@code{uuxqt} by running the command @samp{./uuxqt -I +/usr/tmp/tstuu/Config1}. This should leave a command file +@file{C.@var{something}} and a data file @file{D.@var{something}} in +@file{/usr/tmp/tstuu/spool1} or in subdirectories. Again, there should +be no errors in the log file. + +Assuming you compiled the code with debugging enabled, the @samp{-x} +switch can be used to set debugging modes; see the @code{debug} command +for details (@pxref{Debugging Levels}). Use @samp{-x all} to turn on +all debugging and generate far more output than you will ever want to +see. The @code{uucico} daemons will put debugging output in the files +@file{Debug1} and @file{Debug2} in the directory @file{/usr/tmp/tstuu}. +After that, you're pretty much on your own. + +On some systems you can also use @code{tstuu} to test @code{uucico} +against the system @code{uucico}, by using the @samp{-u} switch. For +this to work, change the definitions of @code{ZUUCICO_CMD} and +@code{UUCICO_EXECL} at the top of @file{tstuu.c} to something +appropriate for your system. The definitions in @file{tstuu.c} are what +I used for Ultrix 4.0, on which @file{/usr/lib/uucp/uucico} is +particularly obstinate about being run as a child; I was only able to +run it by creating a login name with no password whose shell was +@file{/usr/lib/uucp/uucico}. Calling login in this way will leave fake +entries in @file{wtmp} and @file{utmp}; if you compile @file{tstout.c} +(in the @file{contrib} directory) as a setuid @code{root} program, +@code{tstuu} will run it to clear those entries out. On most systems, +such hackery should not be necessary, although on SCO I had to su to +@code{root} (@code{uucp} might also have worked) before I could run +@file{/usr/lib/uucp/uucico}. + +You can test @code{uucp} and @code{uux} (give them the @samp{-r} switch +to keep them from starting @code{uucico}) to make sure they create the +right sorts of files. Unfortunately, if you don't know what the right +sorts of files are, I'm not going to tell you here. + +If @code{tstuu} passes, or you can't run it for some reason or other, +move on to testing with some other system. Set up the configuration +files (@pxref{Configuration Files}), or use an existing configuration. +Tell @code{uucico} to dial out to the system by using the @samp{-s} +system switch (e.g. @samp{uucico -s uunet}). The log file should tell +you what happens. + +If you compiled the code with debugging enabled, you can use debugging +mode to get a great deal of information about what sort of data is +flowing back and forth; the various possibilities are described under +the @code{debug} command (@pxref{Debugging Levels}). When initially +setting up a connection @samp{-x chat} is probably the most useful (e.g. +@samp{uucico -s uunet -x chat}); you may also want to use @samp{-x +handshake,incoming,outgoing}. You can use @samp{-x} multiple times on +one command line, or you can give it comma separated arguments as in the +last example. Use @samp{-x all} to turn on all possible debugging +information. The debugging information is written to a file, normally +@file{/usr/spool/uucp/Debug}, although the default can be changed in +@file{policy.h} and the @file{config} file can override the name with +the @code{debugfile} command. The debugging file may contain passwords +and some file contents as they are transmitted over the line, so the +debugging file is only readable by the @code{uucp} user. + +You can use the @samp{-f} switch to force @code{uucico} to call out even +if the last call failed recently; using @samp{-S} when naming a system +has the same effect. Otherwise the status file (in the @file{.Status} +subdirectory of the main spool directory, normally +@file{/usr/spool/uucp}) will prevent too many attempts from occurring in +rapid succession. + +Again, please let me know about any problems you have and how you got +around them. If you do report a problem, please include the version +number of the package you are using, and a sample of the debugging file +showing the problem (debugging information is usually what is needed, +not just the log file). General questions such as ``why doesn't uucico +dial out'' are impossible to answer without much more information. + +@node Installation, TCP, Testing, Overall Installation +@section Installing Taylor UUCP + +You can install the executable files by becoming @code{root} and typing +@samp{make install}. Or you can look at what @samp{make install} does +and do it by hand. It tries to preserve your old programs, if any, but +it only does this the first time Taylor UUCP is installed (so that if +you install several versions of Taylor UUCP, you can still go back to +your original UUCP programs). You can retrieve the original programs by +typing @samp{make uninstall}. + +Note that by default the programs are compiled with debugging +information, and they are not stripped when they are installed. You may +want to strip the installed programs to save disk space. See your +system documentation for strip for more information. + +However, simply installing the executable files is not enough. You must +also arrange for them to be used correctly. + +@menu +* Running uucico:: Running uucico +* Using UUCP for mail and news:: Using UUCP for mail and news. +* Trimming UUCP Log Files:: Trimming UUCP Log Files +@end menu + +@node Running uucico, Using UUCP for mail and news, Installation, Installation +@subsection Running uucico + +By default @code{uucp} and @code{uux} will automatically start up +@code{uucico} to call another system whenever work is queued up. +However, the call may fail, or you may have put in time restrictions +which prevent the call at that time (perhaps because telephone rates are +high) (@pxref{When to Call}). Also, a remote system may have work +queued up for your system, but may not be calling you for some reason +(perhaps you have agreed that your system should always place the call). +To make sure that works get transferred between the systems withing a +reasonable time period, you should arrange to periodically invoke +@code{uucico}. + +These periodic invocations are normally caused by entries in the +@file{crontab} file. The exact format of @file{crontab} files, and how +new entries are added, varies from system to system; check your local +documentation (try @samp{man cron}). + +To attempt to call all systems with outstanding work, use the command +@samp{uucico -r1}. To attempt to call a particular system, use the +command @samp{uucico -s @var{system}}. To attempt to call a particular +system, but only if there is work for it, use the command @samp{uucico +-C -s @var{system}}. + +A common case is to want to try to call a system at a certain time, with +periodic retries if the call fails. A simple way to do this is to +create an empty UUCP command file, known as a @dfn{poll file}. If a +poll file exists for a system, then @samp{uucico -r1} will place a call +to it. If the call succeeds, the poll file will be deleted. + +The file can be easily created using the @samp{touch} command. The name +of a poll file currently depends on the type of spool directory you are +using, as set in @file{policy.h}. If you are using +@code{SPOOLDIR_TAYLOR} (the default), put something like this in your +@file{crontab} file: +@example +touch /usr/spool/uucp/@var{sys}/C./C.A0000 +@end example +In this example @var{sys} is the system you wish to call, and +@samp{/usr/spool/uucp} is your UUCP spool directory. +If you are using @code{SPOOLDIR_HDB}, use +@example +touch /usr/spool/uucp/@var{sys}/C.@var{sys}A0000 +@end example + +For example, I use the following crontab entries locally: + +@example +45 * * * * /bin/echo /usr/lib/uucp/uucico -r1 | /bin/su uucpa +40 4,10,15 * * * touch /usr/spool/uucp/uunet/C./C.A0000 +@end example + +Every hour, at 45 minutes past, this will check if there is any work to +be done, and, if there is, will call the appropriate system. Also, at +4:40am, 10:40am and 3:40pm this will create a poll file file for +@samp{uunet}, forcing the next check to call @samp{uunet}. + +@node Using UUCP for mail and news, Trimming UUCP Log Files, Running uucico, Installation +@subsection Using UUCP for mail and news. + +Taylor UUCP does not include a mail package. All Unix systems come with +some sort of mail delivery agent, typically @code{sendmail} or +@code{MMDF}. Source code is available for some alternative mail +delivery agents, such as @code{IDA sendmail} and @code{smail}. + +Taylor UUCP also does not include a news package. The two major Unix +news packages are @code{C-news} and @code{INN}. Both are available in +source code form. + +Configuring and using mail delivery agents is a notoriously complex +topic, and I will not be discussing it here. Configuring news systems +is usually simpler, but I will not be discussing that either. I will +merely describe the interactions between the mail and news systems and +UUCP. + +A mail or news system interacts with UUCP in two ways: sending and +receiving. + +@menu +* Sending mail or news:: Sending mail or news via UUCP +* Receiving mail or news:: Receiving mail or news via UUCP +@end menu + +@node Sending mail or news, Receiving mail or news, Using UUCP for mail and news, Using UUCP for mail and news +@unnumberedsubsubsec Sending mail or news via UUCP + +When mail is to be sent from your machine to another machine via UUCP, +the mail delivery agent will invoke @code{uux}. It will generally run a +command such as @samp{uux - @var{system}!rmail}, where @var{system} is +the remote system to which the mail is being sent. It may pass other +options to @code{uux}, such as @samp{-r} or @samp{-g}. + +News also invokes @code{uux} in order to transfer articles to another +system. The only difference is that news will use @code{uux} to invoke +@code{rnews} on the remote system, rather than @code{rmail}. + +You should arrange for your mail and news systems to invoke the Taylor +UUCP version of @code{uux} when sending mail via UUCP. If you simply +replace any existing version of @code{uux} with the Taylor UUCP version, +this will probably happen automatically. However, if both versions +exist on your system, you will probably have to modify the mail and news +configuration files in some way. + +Actually, if both the system UUCP and Taylor UUCP are using the same +spool directory format, the system @code{uux} will probably work fine +with the Taylor @code{uucico} (the reverse is not the case: the Taylor +@code{uux} requires the Taylor @code{uucico}). However, data transfer +will be somewhat more efficient if the Taylor @code{uux} is used. + +@node Receiving mail or news, , Sending mail or news, Using UUCP for mail and news +@unnumberedsubsubsec Receiving mail or news via UUCP + +As noted in @ref{Sending mail or news}, mail is sent by requesting a +remote execution of @code{rmail}. To receive mail, then, all that is +necessary is for UUCP to invoke @code{rmail} itself. + +Any mail delivery agent will provide an appropriate version of +@code{rmail}; you must simply make sure that it is in the command path +used by UUCP (it almost certainly already is). The default command path +is set in @file{policy.h}, and it may be overridden for a particular +system by the @code{command-path} command (@pxref{Miscellaneous (sys)}). + +Similarly, for news UUCP must be able to invoke @code{rnews}. Any news +system will provide a version of @code{rnews}, and you must ensure that +is in a directory on the path that UUCP will search. + +@node Trimming UUCP Log Files, , Using UUCP for mail and news, Installation +@subsection Trimming UUCP Log Files + +You should also periodically trim the log files, as they will otherwise +continue to grow without limit. The names of the log files are set in +@file{policy.h}, and may be overridden in the configuration file +(@pxref{config File}). By default they are are +@file{/usr/spool/uucp/Log} and @file{/usr/spool/uucp/Stats}. + +You may find the @code{savelog} program in the @file{contrib} directory +to be of use. There is a manual page for it in @file{contrib} as well. + +@node TCP, , Installation, Overall Installation +@section TCP together with Taylor UUCP + +If your system has a Berkeley style socket library, or a System V style +TLI interface library, you can compile the code to permit making +connections over TCP. Specifying that a system should be reached via +TCP is easy, but nonobvious. + +If you are using the new style configuration files, see +@ref{Configuration Files}. Basically, you can just add the line +@samp{port type tcp} to the entry in the system configuration file. By +default UUCP will get the port number by looking up @samp{uucp} in +@file{/etc/services}; if @samp{uucp} is not found, port 540 will be +used. You can set the port number to use with the command @samp{port +service @var{xxx}}, where @var{xxx} can be either a number or a name to +look up in @file{/etc/services}. You can specify the address of the +remote host with @samp{address @var{a.b.c}}; if you don't give an +address, the remote system name will be used. You should give an +explicit chat script for the system when you use TCP; the default chat +script begins with a carriage return, which will not work with some UUCP +TCP servers. + +If you are using V2 configuration files, add a line like this to +@file{L.sys}: + +@example +@var{sys} Any TCP uucp @var{host}.@var{domain} chat-script +@end example + +This will make an entry for system @var{sys}, to be called at any time, +over TCP, using port number @samp{uucp} (as found in +@file{/etc/services}; this may be specified as a number), using remote +host @file{@var{host}.@var{domain}}, with some chat script. + +@need 1000 +If you are using HDB configuration files, add a line like this to +Systems: + +@example +@var{sys} Any TCP - @var{host}.@var{domain} chat-script +@end example + +and a line like this to Devices: + +@example +TCP uucp - - +@end example + +You only need one line in Devices regardless of how many systems you +contact over TCP. This will make an entry for system @var{sys}, to be +called at any time, over TCP, using port number @samp{uucp} (as found in +@file{/etc/services}; this may be specified as a number), using remote +host @file{@var{host}.@var{domain}}, with some chat script. + +The @code{uucico} daemon can also be run as a TCP server. To use the +default port number, which is a reserved port, @code{uucico} must be +invoked by root (or it must be set user ID to root, but I don't +recommend doing that). + +Basically, you must define a port, either using the port file +(@pxref{port File}) if you are using the new configuration method or +with an entry in Devices if you are using HDB; there is no way to define +a port using V2. If you are using HDB the port must be named +@samp{TCP}; a line as shown above will suffice. You can then start +@code{uucico} as @samp{uucico -p TCP} (after the @samp{-p}, name the +port; in HDB it must be @samp{TCP}). This will wait for incoming +connections, and fork off a child for each one. Each connection will be +prompted with @samp{login:} and @samp{Password:}; the results will be +checked against the UUCP (not the system) password file +(@pxref{Configuration File Names}). + +Of course, you can get a similar effect by using the BSD @code{uucpd} +program. + +You can also have @code{inetd} start up @code{uucico} with the @samp{-l} +switch, which will cause it to prompt with @samp{login:} and +@samp{Password:} and check the results against the UUCP (not the system) +password file (you may want to also use the @samp{-D} switch to avoid a +fork, which in this case is unnecessary). This may be used in place of +@code{uucpd}. + +@node Configuration Files, Protocols, Overall Installation, Top +@chapter Taylor UUCP Configuration Files + +This chapter describes the configuration files accepted by the Taylor +UUCP package if compiled with @code{HAVE_TAYLOR_CONFIG} defined in +@file{policy.h}. + +The configuration files are normally found in the directory +@var{newconfigdir}, which is defined by the @file{Makefile} variable +@file{newconfigdir}; by default @var{newconfigdir} is +@file{/usr/local/conf/uucp}. However, the main configuration file, +@file{config}, is the only one which must be in that directory, since it +may specify a different location for any or all of the other files. You +may run any of the UUCP programs with a different main configuration +file by using the @samp{-I} option; this can be useful when testing a +new configuration. When you use the @samp{-I} option the programs will +revoke any setuid privileges. + +@menu +* Configuration File Format:: Configuration file format +* Configuration File Overview:: Configuration File Overview +* Configuration Examples:: Examples of configuration files +* Time Strings:: How to write time strings +* Chat Scripts:: How to write chat scripts +* config File:: The main configuration file +* sys File:: The system configuration file +* port File:: The port configuration files +* dial File:: The dialer configuration files +* Security:: Security issues +@end menu + +@node Configuration File Format, Configuration File Overview, Configuration Files, Configuration Files +@section Configuration File Format + +All the configuration files follow a simple line-oriented +@samp{@var{keyword} @var{value}} format. Empty lines are ignored, as +are leading spaces; unlike HDB, lines with leading spaces are read. The +first word on each line is a keyword. The rest of the line is +interpreted according to the keyword. Most keywords are followed by +numbers, boolean values or simple strings with no embedded spaces. + +The @kbd{#} character is used for comments. Everything from a @kbd{#} +to the end of the line is ignored unless the @kbd{#} is preceded by a +@kbd{\} (backslash); if the @kbd{#} is preceeded by a @kbd{\}, the +@kbd{\} is removed but the @kbd{#} remains in the line. This can be +useful for a phone number containing a @kbd{#}. To enter the sequence +@samp{\#}, use @samp{\\#}. + +The backslash character may be used to continue lines. If the last +character in a line is a backslash, the backslash is removed and the +line is continued by the next line. The second line is attached to the +first with no intervening characters; if you want any whitespace between +the end of the first line and the start of the second line, you must +insert it yourself. + +However, the backslash is not a general quoting character. For example, +you cannot use it to get an embedded space in a string argument. + +Everything after the keyword must be on the same line. A @var{boolean} +may be specified as @kbd{y}, @kbd{Y}, @kbd{t}, or @kbd{T} for true and +@kbd{n}, @kbd{N}, @kbd{f}, or @kbd{F} for false; any trailing characters +are ignored, so @code{true}, @code{false}, etc., are also acceptable. + +@node Configuration File Overview, Configuration Examples, Configuration File Format, Configuration Files +@section Configuration File Overview + +UUCP uses several different types of configuration files, each +describing a different kind of information. The commands permitted in +each file are described in detail below. This section is a brief +description of some of the different types of files. + +The @file{config} file is the main configuration file. It describes +general information not associated with a particular remote system, such +as the location of various log files. There are reasonable defaults for +everything that may be specified in the @file{config} file, so you may +not actually need one on your system. + +There may be only one @file{config} file, but there may be one or more +of each other type of file. The default is one file for each type, but +more may be listed in the @file{config} file. + +The @file{sys} files are used to describe remote systems. Each remote +system to which you connect must be listed in a @file{sys} file. A +@file{sys} file will include information for a system, such as the speed +(baud rate) to use, or when to place calls. + +For each system you wish to call, you must describe one or more ports; +these ports may be defined directly in the @file{sys} file, or they may +be defined in a @file{port} file. + +The @file{port} files are used to describe ports. A port is a +particular hardware connection on your computer. You would normally +define as many ports as there are modems attached to your computer. A +TCP connection is also described using a port. + +The @file{dial} files are used to describe dialers. Dialer is +essentially another word for modem. The @file{dial} file describes the +commands UUCP should use to dial out on a particular type of modem. You +would normally define as many dialers as there are types of modems +attached to your computer. For example, if you have three Telebit +modems used for UUCP, you would probably define three ports and one +dialer. + +There are other types of configuration files, but these are the +important ones. The other types are described below. + +@node Configuration Examples, Time Strings, Configuration File Overview, Configuration Files +@section Examples of Configuration Files + +This section provides few typical examples of configuration files. +There are also sample configuration files in the @file{sample} +subdirectory of the distribution. + +@menu +* config File Examples:: Examples of the main configuration file +* Leaf Example:: Call a single remote site +* Gateway Example:: The gateway for several local systems +@end menu + +@node config File Examples, Leaf Example, Configuration Examples, Configuration Examples +@subsection config File Examples +@cindex config file examples + +To start with, here are some examples of uses of the main configuration +file, @file{config}. For a complete description of the commands that +are permitted in @file{config}, see @ref{config File}. + +In many cases you will not need to create a @file{config} file at all. +The most common reason to create one is to give your machine a special +UUCP name. Other reasons might be to change the UUCP spool directory or +to permit any remote system to call in. + +If you have an internal network of machines, then it is likely that the +internal name of your UUCP machine is not the name you want to use when +calling other systems. For example, here at @file{airs.com} our +mail/news gateway machine is named @file{elmer.airs.com} (it is one of +several machines all named @file{@var{localname}.airs.com}). If we did +not provide a @file{config} file, then our UUCP name would be +@file{elmer}; however, we actually want it to be @file{airs}. +Therefore, we use the following line in @file{config}: + +@example +nodename airs +@end example + +@cindex changing spool directory +@cindex spool directory (changing) +The UUCP spool directory name is set in @file{policy.h} when the code is +compiled. You might at some point decide that it is appropriate to move +the spool directory, perhaps to put it on a different disk partition. +You would use the following commands in @file{config} to change to +directories on the partition @file{/uucp}: + +@example +spool /uucp/spool +pubdir /uucp/uucppublic +logfile /uucp/spool/Log +debugfile /uucp/spool/Debug +@end example + +You would then move the contents of the current spool directory to +@file{/uucp/spool}. If you do this, make sure that no UUCP processes +are running while you change @file{config} and move the spool directory. + +@cindex anonymous UUCP +Suppose you wanted to permit any system to call in to your system and +request files. This is generally known as @dfn{anonymous UUCP}, since +the systems which call in are effectively anonymous. By default, +unknown systems are not permitted to call in. To permit this you must +use the @code{unknown} command in @file{config}. The @code{unknown} +command is followed by any command that may appear in the system file; +for full details, see @ref{sys File}. + +I will show two possible anonymous UUCP configurations. The first will +let any system call in and download files, but will not permit them to +upload files to your system. + +@example +# No files may be transferred to this system +unknown receive-request no +# The public directory is /usr/spool/anonymous +unknown pubdir /usr/spool/anonymous +# Only files in the public directory may be sent (the default anyhow) +unknown remote-send ~ +@end example + +@noindent +Setting the public directory is convenient for the systems which call +in. It permits to request a file by prefixing it with @file{~/}. For +example, assuming your system is known as @samp{server}, then to +retrieve the file @file{/usr/spool/anonymous/INDEX} a user on a remote +site could just enter @samp{uucp server!~/INDEX ~}; this would transfer +@file{INDEX} from @samp{server}'s public directory to the user's local +public directory. Note that when using @samp{csh} or @samp{bash} the +@kbd{!} and the second @kbd{~} must be quoted. + +The next example will permit remote systems to upload files to a special +directory named @file{/usr/spool/anonymous/upload}. Permitting a remote +system to upload files permits it to send work requests as well; this +example is careful to prohibit commands from unknown systems. + +@example +# No commands may be executed (the list of permitted commands is empty) +unknown commands +# The public directory is /usr/spool/anonymous +unknown pubdir /usr/spool/anonymous +# Only files in the public directory may be sent; users may not download +# files from the upload directory +unknown remote-send ~ !~/upload +# May only upload files into /usr/spool/anonymous/upload +unknown remote-receive ~/upload +@end example + +@node Leaf Example, Gateway Example, config File Examples, Configuration Examples +@subsection Leaf Example + +@cindex leaf site +@cindex sys file example (leaf) +A relatively common simple case is a @dfn{leaf site}, a system which +only calls or is called by a single remote site. Here is a typical +@file{sys} file that might be used in such a case. For full details on +what commands can appear in the @file{sys} file, see @ref{sys File}. + +This is the @file{sys} file that is used at @file{airs.com}. We use a +single modem to dial out to @file{uunet}. This example shows how you +can specify the port and dialer information directly in the @file{sys} +file for simple cases. It also shows the use of the following: + +@table @code + +@item call-login +Using @code{call-login} and @code{call-password} allows the default +login chat script to be used. In this case, the login name is specified +in the call-out login file (@pxref{Configuration File Names}). + +@item call-timegrade +@file{uunet} is requested to not send us news during the daytime. + +@item chat-fail +If the modem returns @samp{BUSY} or @samp{NO CARRIER} the call is +immediately aborted. + +@item protocol-parameter +Since @file{uunet} tends to be slow, the default timeout has been +increased. + +@end table + +This @file{sys} file relies on certain defaults. It will allow +@file{uunet} to queue up @samp{rmail} and @samp{rnews} commands. It +will allow users to request files from @file{uunet} into the UUCP public +directory. It will also allow @file{uunet} to request files from the +UUCP public directory; in fact @file{uunet} never requests files, but +for additional security we could add the line @samp{request false}. + +@example +# The following information is for uunet +system uunet + +# The login name and password are kept in the callout password file +call-login * +call-password * + +# We can send anything at any time. +time any + +# During the day we only accept grade `Z' or above; at other times +# (not mentioned here) we accept all grades. uunet queues up news +# at grade `d', which is lower than `Z'. +call-timegrade Z Wk0755-2305,Su1655-2305 + +# The phone number. +phone 7389449 + +# uunet tends to be slow, so we increase the timeout +chat-timeout 120 + +# We are using a preconfigured Telebit 2500. +port type modem +port device /dev/ttyd0 +port speed 19200 +port carrier true +port dialer chat "" ATZ\r\d\c OK ATDT\D CONNECT +port dialer chat-fail BUSY +port dialer chat-fail NO\sCARRIER +port dialer complete \d\d+++\d\dATH\r\c +port dialer abort \d\d+++\d\dATH\r\c + +# Increase the timeout and the number of retries. +protocol-parameter g timeout 20 +protocol-parameter g retries 10 +@end example + +@node Gateway Example, , Leaf Example, Configuration Examples +@subsection Gateway Example + +@cindex gateway +@cindex sys file example (gateway) +Many organizations have several local machines which are connected by +UUCP, and a single machine which connects to the outside world. This +single machine is often referred to as a @dfn{gateway} machine. + +For this example I will assume a fairly simple case. It should still +provide a good general example. There are three machines, @file{elmer}, +@file{comton} and @file{bugs}. @file{elmer} is the gateway machine for +which I will show the configuration file. @file{elmer} calls out to +@file{uupsi}. As an additional complication, @file{uupsi} knows +@file{elmer} as @file{airs}; this will show how a machine can have one +name on an internal network but a different name to the external world. +@file{elmer} has two modems. It also has an TCP/IP connection to +@file{uupsi}, but since that is supposed to be reserved for interactive +work (it is, perhaps, only a 9600 baud SLIP line) it will only use it if +the modems are not available. + +A network this small would normally use a single @file{sys} file. +However, for pedagogical purposes I will show two separate @file{sys} +files, one for the local systems and one for @file{uupsi}. This is done +with the @code{sysfile} command in the @file{config} file. Here is the +@file{config} file. + +@example +# This is config +# The local sys file +sysfile /usr/local/lib/uucp/sys.local +# The remote sys file +sysfile /usr/local/lib/uucp/sys.remote +@end example + +Using the defaults feature of the @file{sys} file can greatly simplify +the listing of local systems. Here is @file{sys.local}. Note that this +assumes that the local systems are trusted; they are permited to request +any world readable file and to write files into any world writable +directory. + +@example +# This is sys.local +# Get the login name and password to use from the call-out file +call-login * +call-password * + +# The systems must use a particular login +called-login Ulocal + +# Permit sending any world readable file +local-send / +remote-send / + +# Permit requesting into any world writable directory +local-receive / +remote-receive / + +# Call at any time +time any + +# Use port1, then port2 +port port1 + +alternate + +port port2 + +# Now define the systems themselves. Because of all the defaults we +# used, there is very little to specify for the systems themselves. + +system comton +phone 5551212 + +system bugs +phone 5552424 +@end example + +The @file{sys.remote} file describes the @file{uupsi} connection. The +@code{myname} command is used to change the UUCP name to @file{airs} +when talking to @file{uupsi}. + +@example +# This is sys.remote +# Define uupsi +system uupsi + +# The login name and password are in the call-out file +call-login * +call-password * + +# We can call out at any time +time any + +# uupsi uses a special login name +called-login Uuupsi + +# uuspi thinks of us as `airs' +myname airs + +# The phone number +phone 5554848 + +# We use port2 first, then port1, then TCP + +port port2 + +alternate + +port port1 + +alternate + +# We don't bother to make a special entry in the port file for TCP, we +# just describe the entire port right here. We use a special chat +# script over TCP because the usual one confuses some TCP servers. +port type TCP +address uu.psi.com +chat ogin: \L word: \P +@end example + +The ports are defined in the file @file{port} (@pxref{port File}). For +this example they are both connected to the same type of 2400 baud +Hayes-compatible modem. + +@example +# This is port + +port port1 +type modem +device /dev/ttyd0 +dialer hayes +speed 2400 + +port port2 +type modem +device /dev/ttyd1 +dialer hayes +speed 2400 +@end example + +Dialers are described in the @file{dial} file (@pxref{dial File}). + +@example +# This is dial + +dialer hayes + +# The chat script used to dial the phone. \D is the phone number. +chat "" ATZ\r\d\c OK ATDT\D CONNECT + +# If we get BUSY or NO CARRIER we abort the dial immediately +chat-fail BUSY +chat-fail NO\sCARRIER + +# When the call is over we make sure we hangup the modem. +complete \d\d+++\d\dATH\r\c +abort \d\d+++\d\dATH\r\c +@end example + +@node Time Strings, Chat Scripts, Configuration Examples, Configuration Files +@section Time Strings +@cindex time strings + +Several commands use time strings to specify a range of times. This +section describes how to write time strings. + +A time string may be a list of simple time strings separated with a +vertical bar @kbd{|} or a comma @kbd{,}. + +Each simple time string must begin with @samp{Su}, @samp{Mo}, @samp{Tu}, +@samp{We}, @samp{Th}, @samp{Fr}, or @samp{Sa}, or @samp{Wk} for any +weekday, or @samp{Any} for any day. + +Following the day may be a range of hours separated with a hyphen using +24 hour time. The range of hours may cross 0; for example +@samp{2300-0700} means any time except 7 AM to 11 PM. If no time is +given, calls may be made at any time on the specified day(s). + +The time string may also consist of the single word @samp{Never}, which +does not match any time, or a single word with a name defined in a +previous @code{timetable} command (@pxref{Miscellaneous (config)}). + +Here are a few sample time strings with an explanation of what they +mean. + +@table @samp + +@item Wk2305-0855,Sa,Su2305-1655 + +This means weekdays before 8:55 AM or after 11:05 PM, any time Saturday, +or Sunday before 4:55 PM or after 11:05 PM. These are approximately the +times during which night rates apply to phone calls in the U.S.A. Note +that this time string uses, for example, @samp{2305} rather than +@samp{2300}; this will ensure a cheap rate phone call even if the +computer clock is running up to five minutes ahead of the real time. + +@item Wk0905-2255,Su1705-2255 + +This means weekdays from 9:05 AM to 10:55 PM, or Sunday from 5:05 PM to +10:55 PM. This is approximately the opposite of the previous example. + +@item Any + +This means any day. Since no time is specified, it means any time on +any day. + +@end table + +@node Chat Scripts, config File, Time Strings, Configuration Files +@section Chat Scripts +@cindex chat scripts + +Chat scripts are used in several different places, such as dialing out +on modems or logging in to remote systems. Chat scripts are made up of +pairs of strings. The program waits until it sees the first string, +known as the @dfn{expect} string, and then sends out the second string, +the @dfn{send} string. + +Each chat script is defined using a set of commands. These commands +always end in a string beginning with @code{chat}, but may start with +different strings. For example, in the @file{sys} file there is one set +of commands beginning with @code{chat} and another set beginning with +@code{called-chat}. The prefixes are only used to disambiguate +different types of chat scripts, and this section ignores the prefixes +when describing the commands. + +@table @code + +@item chat @var{strings} +@findex chat + +Specify a chat script. The arguments to the @code{chat} command are +pairs of strings separated by whitespace. The first string of each pair +is an expect string, the second is a send string. The program will wait +for the expect string to appear; when it does, the program will send the +send string. If the expect string does not appear within a certain +number of seconds (as set by the @code{chat-timeout} command) the chat +script fails and, typically, the call is aborted. If the final expect +string is seen (and the optional final send string has been sent), the +chat script is successful. + +An expect string may contain additional subsend and subexpect strings, +separated by hyphens. If the expect string is not seen, the subsend +string is sent and the chat script continues by waiting for the +subexpect string. This means that a hyphen may not appear in an expect +string; on an ASCII system, use @samp{\055} instead. + +An expect string may simply be @samp{""}, meaning to skip the expect +phase. Otherwise, the following escape characters may appear in expect +strings: + +@table @samp +@item \b +a backspace character +@item \n +a newline or line feed character +@item \N +a null character (for HDB compatibility) +@item \r +a carriage return character +@item \s +a space character +@item \t +a tab character +@item \\ +a backslash character +@item \@var{ddd} +character @var{ddd}, where @var{ddd} are up to three octal digits +@item \x@var{ddd} +character @var{ddd}, where @var{ddd} are hexadecimal digits. +@end table + +As in C, there may be up to three octal digits following a backslash, +but the hexadecimal escape sequence continues as far as possible. To +follow a hexadecimal escape sequence with a hex digit, interpose a send +string of @samp{""}. + +A chat script expect string may also specify a timeout. This is done by +using the escape sequence @samp{\W@var{seconds}}. This escape sequence +may only appear at the very end of the expect string. It temporarily +overrides the timeout set by @code{chat-timeout} (described below) only +for the expect string to which it is attached. + +A send string may simply be @samp{""} to skip the send phase. +Otherwise, all of the escape characters legal for expect strings may be +used, and the following escape characters are also permitted: + +@table @samp +@item EOT +send an end of transmission character (@kbd{^D}) +@item BREAK +send a break character (may not work on all systems) +@item \c +suppress trailing carriage return at end of send string +@item \d +delay sending for 1 or 2 seconds +@item \e +disable echo checking +@item \E +enable echo checking +@item \K +same as @samp{BREAK} (for HDB compatibility) +@item \p +pause sending for a fraction of a second +@end table + +Some specific types of chat scripts also define additional escape +sequences that may appear in the send string. For example, the login +chat script defines @samp{\L} and @samp{\P} to send the login name and +password, respectively. + +A carriage return will be sent at the end of each send string, unless +the @kbd{\c} escape sequence appears in the string. Note that some UUCP +packages use @kbd{\b} for break, but here it means backspace. + +Echo checking means that after writing each character the program will +wait until the character is echoed. Echo checking must be turned on +separately for each send string for which it is desired; it will be +turned on for characters following @kbd{\E} and turned off for characters +following @kbd{\e}. + +@item chat-timeout @var{number} +@findex chat-timeout + +The number of seconds to wait for an expect string in the chat script +before timing out and sending the next subsend or failing the chat +script entirely. The default value is 10 for a login chat or 60 for +any other type of chat. + +@item chat-fail @var{string} +@findex chat-fail + +If the @var{string} is seen at any time during a chat script, the chat +script is aborted. The string may not contain any whitespace +characters; escape sequences must be used for them. Multiple +@code{chat-fail} commands may appear in a single chat script. The +default is to have none. + +This permits a chat script to be quickly aborted if an error string is +seen. For example, a script used to dial out on a modem might use the +command @samp{chat-fail BUSY} to stop the chat script immediately if the +string @samp{BUSY} was seen. + +The @code{chat-fail} strings are considered in the order they are +listed, so if one string is a suffix of another the longer one should be +listed first. Of course, if one string is contained within another, the +smaller string will always be found before the larger string could +match. + +@item chat-seven-bit @var{boolean} +@findex chat-seven-bit + +If the argument is true, all incoming characters are stripped to seven +bits when being compared to the expect string. Otherwise all eight bits +are used in the comparison. The default is true, because some Unix +systems generate parity bits during the login prompt which must be +ignored while running a chat script. This has no effect on any +@code{chat-program}, which must ignore parity by itself if necessary. + +@item chat-program @var{strings} +@findex chat-program + +Specify a program to run before executing the chat script. This program +could run its own version of a chat script, or it could do whatever it +wants. If both @code{chat-program} and @code{chat} are specified, the +program is executed first followed by the chat script. + +The first argument to the @code{chat-program} command is the program +name to run. The remaining arguments are passed to the program. The +following escape sequences are recognized in the arguments: + +@table @kbd +@item \Y +port device name +@item \S +port speed +@item \\ +backslash +@end table + +Some specific uses of @code{chat-program} define additional escape +sequences. + +Arguments other than escape sequences are passed exactly as they appear +in the configuration file, except that sequences of whitespace are +compressed to a single space character (this exception may be removed in +the future). + +If the @code{chat-program} command is not used, no program is run. + +On Unix, the standard input and standard output of the program will be +attached to the port in use. Anything the program writes to standard +error will be written to the UUCP log file. No other file descriptors +will be open. If the program does not exit with a status of 0, it will +be assumed to have failed. This means that the dialing programs used by +some versions of HDB may not be used directly, but you may be able to +run them via the @code{dialHDB} program in the @file{contrib} directory. + +The program will be run as the @code{uucp} user, and the environment +will be that of the process that started @code{uucico}, so care must be +taken to maintain security. + +No search path is used to find the program; a full path name must be +given. If the program is an executable shell script, it will be passed +to @file{/bin/sh} even on systems which are unable to execute shell +scripts. + +@end table + +Here is a simple example of a chat script that might be used to reset a +Hayes compatible modem. + +@example +chat "" ATZ OK-ATZ-OK +@end example + +The first expect string is @samp{""}, so it is ignored. The chat script +then sends @samp{ATZ}. If the modem responds with @samp{OK}, the chat +script finishes. If 60 seconds (the default timeout) pass before seeing +@samp{OK}, the chat script sends another @samp{ATZ}. If it then sees +@samp{OK}, the chat script succeeds. Otherwise, the chat script fails. + +For a more complex chat script example, see @ref{Logging In}. + +@node config File, sys File, Chat Scripts, Configuration Files +@section The Main Configuration File +@cindex config file +@cindex main configuration file +@cindex configuration file (config) + +The main configuration file is named @file{config}. + +Since all the values that may be specified in the main configuration +file also have defaults, there need not be a main configuration file at +all. + +Each command in @file{config} may have a program prefix, which is a +separate word appearing at the beginning of the line. The currently +supported prefixes are @samp{uucp} and @samp{cu}. Any command prefixed +by @samp{uucp} will not be read by the @code{cu} program. Any command +prefixed by @samp{cu} will only be read by the @code{cu} program. For +example, to use a list of systems known only to @code{cu}, list them in +a separate file @file{@var{file}} and put @samp{cu sysfile +@file{@var{file}}} in @file{config}. + +@menu +* Miscellaneous (config):: Miscellaneous config file commands +* Configuration File Names:: Using different configuration files +* Log File Names:: Using different log files +* Debugging Levels:: Debugging levels +@end menu + +@node Miscellaneous (config), Configuration File Names, config File, config File +@subsection Miscellaneous config File Commands + +@table @code + +@item nodename @var{string} +@findex nodename +@itemx hostname @var{string} +@findex hostname +@itemx uuname @var{string} +@findex uuname +@cindex UUCP system name +@cindex system name + +These keywords are equivalent. They specify the UUCP name of the local +host. If there is no configuration file, an appropriate system function +will be used to get the host name, if possible. + +@item spool @var{string} +@findex spool +@cindex spool directory +@cindex /usr/spool/uucp + +Specify the spool directory. The default is from @file{policy.h}. This +is where UUCP files are queued. Status files and various sorts of +temporary files are also stored in this directory and subdirectories of +it. + +@item pubdir @var{string} +@findex pubdir in config file +@cindex public directory +@cindex uucppublic +@cindex /usr/spool/uucppublic + +Specify the public directory. The default is from @file{policy.h}. +When a file is named using a leading @kbd{~/}, it is taken from or to +the public directory. Each system may use a separate public directory +by using the @code{pubdir} command in the system configuration file; see +@ref{Miscellaneous (sys)}. + +@item lockdir @var{string} +@findex lockdir +@cindex lock directory + +Specify the directory to place lock files in. The default is from +@file{policy.h}; see the information in that file. Normally the lock +directory should be set correctly in @file{policy.h}, and not changed +here. However, changing the lock directory is sometimes useful for +testing purposes. + +@item unknown @var{string} @dots{} +@findex unknown +@cindex unknown systems + +The @var{string} and subsequent arguments are treated as though they +appeared in the system file (@pxref{sys File}). They are used to apply +to any unknown systems that may call in, probably to set file transfer +permissions and the like. If the @code{unknown} command is not used, +unknown systems are not permitted to call in. + +@item max-uuxqts @var{number} +@findex max-uuxqts + +Specify the maximum number of @code{uuxqt} processes which may run at +the same time. Having several @code{uuxqt} processes running at once +can significantly slow down a system, but since @code{uuxqt} is +automatically started by @code{uucico}, it can happen quite easily. The +default for @code{max-uuxqts} is 0, which means that there is no limit. +If HDB configuration files are being read and the code was compiled +without @code{HAVE_TAYLOR_CONFIG}, then if the file @file{Maxuuxqts} in +the configuration directory contains a readable number it will be used as +the value for @code{max-uuxqts}. + +@item run-uuxqt @var{string} or @var{number} +@findex run-uuxqt + +Specify when @code{uuxqt} should be run by @code{uucico}. This may be a +positive number, in which case @code{uucico} will start a @code{uuxqt} +process whenever it receives the given number of execution files from +the remote system, and, if necessary, at the end of the call. The +argument may also be one of the strings @samp{once}, @samp{percall}, or +@samp{never}. The string @samp{once} means that @code{uucico} will +start @code{uuxqt} once at the end of execution. The string +@samp{percall} means that @code{uucico} will start @code{uuxqt} once per +call that it makes (this is only different from @code{once} when +@code{uucico} is invoked in a way that causes it to make multiple calls, +such as when the @samp{-r1} argument is used without the @samp{-s} +argument). The string @samp{never} means that @code{uucico} will never +start @code{uuxqt}, in which case @code{uuxqt} should be periodically +run via some other mechanism. The default depends upon which type of +configuration files are being used; if @code{HAVE_TAYLOR_CONFIG} is used +the default is @samp{once}, otherwise if @code{HAVE_HDB_CONFIG} is used +the default is @samp{percall}, and otherwise, for @code{HAVE_V2_CONFIG}, +the default is @samp{10}. + +@item timetable @var{string} @var{string} +@findex timetable + +The @code{timetable} defines a timetable that may be used in +subsequently appearing time strings; @ref{Time Strings}. The first +string names the timetable entry; the second is a time string. + +The following @code{timetable} commands are predefined. The NonPeak +timetable is included for compatibility. It originally described the +offpeak hours of Tymnet and Telenet, but both have since changed their +schedules. + +@example +timetable Evening Wk1705-0755,Sa,Su +timetable Night Wk2305-0755,Sa,Su2305-1655 +timetable NonPeak Wk1805-0655,Sa,Su +@end example + +If this command does not appear, then obviously no additional timetables +will be defined. + +@item v2-files @var{boolean} +@findex v2-files + +If the code was compiled to be able to read V2 configuration files, a +false argument to this command will prevent them from being read. +This can be useful while testing. The default is true. + +@item hdb-files @var{boolean} +@findex hdb-files + +If the code was compiled to be able to read HDB configuration files, a +false argument to this command will prevent them from being read. +This can be useful while testing. The default is true. + +@end table + +@node Configuration File Names, Log File Names, Miscellaneous (config), config File +@subsection Configuration File Names + +@table @code + +@item sysfile @var{strings} +@findex sysfile + +Specify the system file(s). The default is the file @file{sys} in the +directory @var{newconfigdir}. These files hold information about other +systems with which this system communicates; see @ref{sys File}. +Multiple system files may be given on the line, and the @code{sysfile} +command may be repeated; each system file has its own set of defaults. + +@item portfile @var{strings} +@findex portfile + +Specify the port file(s). The default is the file @file{port} in the +directory @var{newconfigdir}. These files describe ports which are used +to call other systems and accept calls from other systems; see @ref{port +File}. No port files need be named at all. Multiple port files may be +given on the line, and the @code{portfile} command may be repeated. + +@item dialfile @var{strings} +@findex dialfile + +Specify the dial file(s). The default is the file @file{dial} in the +directory @var{newconfigdir}. These files describe dialing devices +(modems); @xref{dial File}. No dial files need be named at all. +Multiple dial files may be given on the line, and the @code{dialfile} +command may be repeated. + +@item dialcodefile @var{strings} +@findex dialcodefile +@cindex configuration file (dialcode) +@cindex dialcode file +@cindex dialcode configuration file + +Specify the dialcode file(s). The default is the file @file{dialcode} +in the directory @var{newconfigdir}. These files specify dialcodes that +may be used when sending phone numbers to a modem. This permits using +the same set of phone numbers in different area-codes or with different +phone systems, by using dialcodes to specify the calling sequence. When +a phone number goes through dialcode translation, the leading alphabetic +characters are stripped off. The dialcode files are read line by line, +just like any other configuration file, and when a line is found whose +first word is the same as the leading characters from the phone number, +the second word on the line (which would normally consist of numbers) +replaces the dialcode in the phone number. No dialcode file need be +used. Multiple dialcode files may be specified on the line, and the +@code{dialcodefile} command may be repeated; all the dialcode files will +be read in turn until a dialcode is located. + +@item callfile @var{strings} +@findex callfile +@cindex call out file +@cindex call configuration file +@cindex call out login name +@cindex call out password +@cindex configuration file (call) + +Specify the call out login name and password file(s). The default is +the file @file{call} in the directory @var{newconfigdir}. If the call +out login name or password for a system are given as @kbd{*} +(@pxref{Logging In}), these files are read to get the real login name or +password. Each line in the file(s) has three words: the system name, +the login name, and the password. The login name and password may +contain escape sequences like those in a chat script expect string +(@pxref{Chat Scripts}). This file is only used when placing calls to +remote systems; the password file described under @code{passwdfile} +below is used for incoming calls. The intention of the call out file is +to permit the system file to be publically readable; the call out files +must obviously be kept secure. These files need not be used. Multiple +call out files may be specified on the line, and the @code{callfile} +command may be repeated; all the files will be read in turn until the +system is found. + +@item passwdfile @var{strings} +@findex passwdfile +@cindex passwd file +@cindex passwd configuration file +@cindex configuration file (passwd) +@cindex call in login name +@cindex call in password + +Specify the password file(s) to use for login names when @code{uucico} +is doing its own login prompting, which it does when given the +@samp{-e}, @samp{-l} or @samp{-w} switches. The default is the file +@file{passwd} in the directory @var{newconfigdir}. Each line in the +file(s) has two words: the login name and the password (e.g. @code{Ufoo +foopas}). They may contain escape sequences like those in a chat script +expect string (@pxref{Chat Scripts}). The login name is accepted before +the system name is known, so these are independent of which system is +calling in; a particular login may be required for a system by using the +@code{called-login} command in the system file (@pxref{Accepting a +Call}). These password files are optional, although one must exist if +@code{uucico} is to present its own login prompts. + +As a special exception, a colon may be used to separate the login name +from the password, and a colon may be used to terminate the password. +This means that the login name and password may not contain a colon. +This feature, in conjunction with the @code{HAVE_ENCRYPTED_PASSWORDS} +macro in @file{policy.h}, permits using a standard Unix +@file{/etc/passwd} as a UUCP password file, providing the same set of +login names and passwords for both @code{getty} and @code{uucico}. + +Multiple password files may be specified on the line, and the +@code{passwdfile} command may be repeated; all the files will be read in +turn until the login name is found. + +@end table + +@node Log File Names, Debugging Levels, Configuration File Names, config File +@subsection Log File Names + +@table @code + +@item logfile @var{string} +@findex logfile +@cindex log file + +Name the log file. The default is from @file{policy.h}. Logging +information is written to this file. If @code{HAVE_HDB_LOGGING} is +defined in @file{policy.h}, then by default a separate log file is used +for each system. Using this command to name a log file will cause all +the systems to use it. + +@item statfile @var{string} +@findex statfile +@cindex statistics file + +Name the statistics file. The default is from @file{policy.h}. +Statistical information about file transfers is written to this file. + +@item debugfile @var{string} +@findex debugfile +@cindex debugging file + +Name the file to which all debugging information is written. The +default is from @file{policy.h}. This command is only effective if the +code has been compiled to include debugging (this is controlled by the +@code{DEBUG} macro in @file{policy.h}). If debugging is on, messages +written to the log file are also written to the debugging file to make +it easier to keep the order of actions straight. The debugging file is +different from the log file because information such as passwords can +appear in it, so it must be not be publically readable. + +@end table + +@node Debugging Levels, , Log File Names, config File +@subsection Debugging Levels + +@table @code + +@item debug @var{string} @dots{} +@findex debug in config file + +Set the debugging level. This command is only effective if the code has +been compiled to include debugging. The default is to have no +debugging. The arguments are strings which name the types of debugging +to be turned on. The following types of debugging are defined: + +@table @samp +@item abnormal +Output debugging messages for abnormal situations, such as recoverable errors. +@item chat +Output debugging messages for chat scripts. +@item handshake +Output debugging messages for the initial handshake. +@item uucp-proto +Output debugging messages for the UUCP session protocol. +@item proto +Output debugging messages for the individual link protocols. +@item port +Output debugging messages for actions on the communication port. +@item config +Output debugging messages while reading the configuration files. +@item spooldir +Output debugging messages for actions in the spool directory. +@item execute +Output debugging messages whenever another program is executed. +@item incoming +List all incoming data in the debugging file. +@item outgoing +List all outgoing data in the debugging file. +@item all +All of the above. +@end table + +The debugging level may also be specified as a number. A 1 will set +@samp{chat} debugging, a 2 will set both @samp{chat} and +@samp{handshake} debugging, and so on down the possibilities. Currently +an 11 will turn on all possible debugging, since there are 11 types of +debugging messages listed above; more debugging types may be added in +the future. The @code{debug} command may be used several times in the +configuration file; every debugging type named will be turned on. When +running any of the programs, the @samp{-x} switch (actually, for +@code{uulog} it's the @samp{-X} switch) may be used to turn on +debugging. The argument to the @samp{-x} switch is one of the strings +listed above, or a number as described above, or a comma separated list +of strings (e.g. @samp{-x chat,handshake}). The @samp{-x} switch may +also appear several times on the command line, in which case all named +debugging types will be turned on. The @samp{-x} debugging is in +addition to any debugging specified by the @code{debug} command; there +is no way to cancel debugging information. The debugging level may also +be set specifically for calls to or from a specific system with the +@code{debug} command in the system file (@pxref{Miscellaneous (sys)}). + +The debugging messages are somewhat idiosyncratic; it may be necessary +to refer to the source code for additional information in some cases. + +@end table + +@node sys File, port File, config File, Configuration Files +@section The System Configuration File +@cindex sys file +@cindex system configuration file +@cindex configuration file (sys) + +By default there is a single system configuration, named @file{sys} in +the directory @var{newconfigdir}. This may be overridden by the +@code{sysfile} command in the main configuration file; see +@ref{Configuration File Names}. + +These files describe all remote systems known to the UUCP package. + +@menu +* Defaults and Alternates:: Using defaults and alternates +* Naming the System:: Naming the system +* Calling Out:: Calling out +* Accepting a Call:: Accepting a call +* Protocol Selection:: Protocol selection +* File Transfer Control:: File transfer control +* Miscellaneous (sys):: Miscellaneous sys file commands +* Default sys File Values:: Default values +@end menu + +@node Defaults and Alternates, Naming the System, sys File, sys File +@subsection Defaults and Alternates + +The first set of commands in the file, up to the first @code{system} +command, specify defaults to be used for all systems in that file. Each +@file{sys} file uses a different set of defaults. + +Subsequently, each set of commands from @code{system} up to the next +@code{system} command describe a particular system. Default values may +be overridden for specific systems. + +Each system may then have a series of alternate choices to use when +calling out or calling in. The first set of commands for a particular +system, up to the first @code{alternate} command, provide the first +choice. Subsequently, each set of commands from @code{alternate} up to +the next @code{alternate} command describe an alternate choice for +calling out or calling in. + +When a system is called, the commands before the first @code{alternate} +are used to select a phone number, port, and so forth; if the call fails +for some reason, the commands between the first @code{alternate} and the +second are used, and so forth. Well, not quite. Actually, each +succeeding alternate will only be used if it is different in some +relevant way (different phone number, different chat script, etc.). If +you want to force the same alternate to be used again (to retry a phone +call more than once, for example), enter the phone number (or any other +relevant field) again to make it appear different. + +The alternates can also be used to give different permissions to an +incoming call based on the login name. This will only be done if the +first set of commands, before the first @code{alternate} command, uses +the @code{called-login} command. The list of alternates will be +searched, and the first alternate with a matching @code{called-login} +command will be used. If no alternates match, the call will be +rejected. + +The @code{alternate} command may also be used in the file-wide defaults +(the set of commands before the first @code{system} command). This +might be used to specify a list of ports which are available for all +systems (for an example of this, see @ref{Gateway Example}) or to +specify permissions based on the login name used by the remote system +when it calls in. The first alternate for each system will default to +the first alternate for the file-wide defaults (as modified by the +commands used before the first @code{alternate} command for this +system), the second alternate for each system to the second alternate +for the file-wide defaults (as modified the same way), and so forth. If +a system specifies more alternates than the file-wide defaults, the +trailing ones will default to the last file-wide default alternate. If +a system specifies fewer alternates than the file-wide defaults, the +trailing file-wide default alternates will be used unmodified. The +@code{default-alternates} command may be used to modify this behaviour. + +This can all get rather confusing, although it's easier to use than to +describe concisely; the @code{uuchk} program may be used to ensure that +you are getting what you want. + +@node Naming the System, Calling Out, Defaults and Alternates, sys File +@subsection Naming the System + +@table @code + +@item system @var{string} +@findex system + +Specify the remote system name. Subsequent commands up to the next +@code{system} command refer to this system. + +@item alternate [@var{string}] +@findex alternate + +Start an alternate set of commands (@pxref{Defaults and Alternates}). +An optional argument may be used to name the alternate. This name will +be put in the log file if the alternate is used to call the system. +There is no way to name the first alternate (the commands before the +first @code{alternate} command). + +@item default-alternates @var{boolean} +@findex default-alternates + +If the argument is false, any remaining default alternates (from the +defaults specified at the top of the current system file) will not be +used. The default is true. + +@item alias @var{string} +@findex alias + +Specify an alias for the current system. The alias may be used by local +@code{uucp} and @code{uux} commands, as well as by the remote system +(which can be convenient if a remote system changes its name). The +default is to have no aliases. + +@item myname @var{string} +@findex myname + +Specifies a different system name to use when calling the remote system. +Also, if @code{called-login} is used and is not @samp{ANY}, then, when a +system logs in with that login name, @var{string} is used as the local +system name. Because the local system name must be determined before +the remote system has identified itself, using @code{myname} and +@code{called-login} together for any system will set the local name for +that login; this means that each locally used system name must have a +unique login name associated with it. This allows a system to have +different names for an external and an internal network. The default is +to not use a special local name. + +@end table + +@node Calling Out, Accepting a Call, Naming the System, sys File +@subsection Calling Out + +This section describes commands used when placing a call to another +system. + +@menu +* When to Call:: When to call +* Placing the Call:: Placing the call +* Logging In:: Logging in +@end menu + +@node When to Call, Placing the Call, Calling Out, Calling Out +@subsubsection When to Call + +@table @code + +@item time @var{string} [@var{number}] +@findex time + +Specify when the system may be called. The first argument is a time +string; see @ref{Time Strings}. The optional second argument specifies +a retry time in minutes. If a call made during a time that matches the +time string fails, no more calls are permitted until the retry time has +passed. By default an exponentially increasing retry time is used: +after each failure the next retry period is longer. A retry time +specified in the @code{time} command is always a fixed amount of time. + +The @code{time} command may appear multiple times in a single alternate, +in which case if any time string matches the system may be called. When +the @code{time} command is used for a particular system, any @code{time} +or @code{timegrade} commands that appeared in the system defaults are +ignored. + +The default time string is @samp{Never}. + +@item timegrade @var{character} @var{string} [@var{number}] +@findex timegrade + +The @var{character} specifies a grade. It must be a single letter or +digit. The @var{string} is a time string (@pxref{Time Strings}). All +jobs of grade @var{character} or higher (where @kbd{0} > @kbd{9} > +@kbd{A} > @kbd{Z} > @kbd{a} > @kbd{z}) may be run at the specified time. +An ordinary @code{time} command is equivalent to using @code{timegrade} +with a grade of @kbd{z}, permitting all jobs. If there are no jobs of a +sufficiently high grade according to the time string, the system will +not be called. Giving the @samp{-s} switch to @code{uucico} to force it +to call a system causes it to assume there is a job of grade @kbd{0} +waiting to be run. + +The optional third argument specifies a retry time in minutes. See the +@code{time} command, above, for more details. + +Note that the @code{timegrade} command serves two purposes: 1) if there +is no job of sufficiently high grade the system will not be called, and +2) if the system is called anyway (because the @samp{-s} switch was +given to @code{uucico}) only jobs of sufficiently high grade will be +transferred. However, if the other system calls in, the +@code{timegrade} commands are ignored, and jobs of any grade may be +transferred (but see @code{call-timegrade} below). Also, the +@code{timegrade} command will not prevent the other system from +transferring any job it chooses, regardless of who placed the call. + +The @code{timegrade} command may appear multiple times without using +@code{alternate}. When the @code{timegrade} command is used for a +particular system, any @code{time} or @code{timegrade} commands that +appeared in the system defaults are ignored. + +If this command does not appear, there are no restrictions on what grade +of work may be done at what time. + +@item max-retries @var{number} +@findex max-retries + +Gives the maximum number of times this system may be retried. If this +many calls to the system fail, it will be called at most once a day +whatever the retry time is. The default is 26. + +@item success-wait @var{number} + +A retry time, in seconds, which applies after a successful call. This +can be used to put a limit on how frequently the system is called. For +example, an argument of 1800 means that the system will not be called +more than once every half hour. The default is 0, which means that +there is no limit. + +@item call-timegrade @var{character} @var{string} +@findex call-timegrade + +The @var{character} is a single character @kbd{A} to @kbd{Z}, @kbd{a} to +@kbd{z}, or @kbd{0} to @kbd{9} and specifies a grade. The @var{string} +is a time string as described under the @code{time} command. If a call +is placed to the other system during a time which matches the time +string, the remote system will be requested to only run jobs of grade +@var{character} or higher. Unfortunately, there is no way to guarantee +that the other system will obey the request (this UUCP package will, but +there are others which will not); moreover job grades are historically +somewhat arbitrary, so specifying a grade will only be meaningful if the +other system cooperates in assigning grades. This grade restriction +only applies when the other system is called, not when the other system +calls in. + +The @code{call-timegrade} command may appear multiple times without +using @code{alternate}. If this command does not appear, or if none of +the time strings match, the remote system will be allowed to send +whatever grades of work it chooses. + +@end table + +@node Placing the Call, Logging In, When to Call, Calling Out +@subsubsection Placing the Call + +@table @code + +@itemx speed @var{number} +@findex speed in sys file +@item baud @var{number} +@findex baud in sys file + +Specify the speed (the term @dfn{baud} is technically incorrect, but +widely understood) at which to call the system. This will try all +available ports with that speed until an unlocked port is found. The +ports are defined in the port file. If both @code{speed} and +@code{port} commands appear, both are used when selecting a port. To +allow calls at more than one speed, the @code{alternate} command must be +used (@pxref{Defaults and Alternates}). If this command does not +appear, there is no default; the speed may be specified in the port +file, but if it is not then the natural speed of the port will be used +(whatever that means on the system). Specifying an explicit speed of 0 +will request the natural speed of the port (whatever the system sets it +to), overriding any default speed from the defaults at the top of the +file. + +@item port @var{string} +@findex port in sys file + +Name a particular port or type of port to use when calling the system. +The information for this port is obtained from the port file. If this +command does not appear, there is no default; a port must somehow be +specified in order to call out (it may be specified implicitly using the +@code{speed} command or explicitly using the next version of +@code{port}). There may be many ports with the same name; each will be +tried in turn until an unlocked one is found which matches the desired +speed. + +@item port @var{string} @dots{} + +If more than one string follows the @code{port} command, the strings are +treated as a command that might appear in the port file (@pxref{port +File}). If a port is named (by using a single string following +@code{port}) these commands are ignored; their purpose is to permit +defining the port completely in the system file rather than always +requiring entries in two different files. In order to call out, a port +must be specified using some version of the @code{port} command, or by +using the @code{speed} command to select ports from the port file. + +@item phone @var{string} +@findex phone +@itemx address @var{string} +@findex address + +Give a phone number to call (when using a modem port) or a remote host +to contact (when using a TCP or TLI port). The commands @code{phone} +and @code{address} are equivalent; the duplication is intended to +provide a mnemonic choice depending on the type of port in use. + +When used with a modem port, an @kbd{=} character in the phone number +means to wait for a secondary dial tone (although only some modems +support this); a @kbd{-} character means to pause while dialing for 1 +second (again, only some modems support this). If the system has more +than one phone number, each one must appear in a different alternate. +The @code{phone} command must appear in order to call out on a modem; +there is no default. + +When used with a TCP port, the string names the host to contact. It may +be a domain name or a numeric Internet address. If no address is +specified, the system name is used. + +When used with a TLI port, the string is treated as though it were an +expect string in a chat script, allowing the use of escape characters +(@pxref{Chat Scripts}). The @code{dialer-sequence} command in the port +file may override this address (@pxref{port File}). + +When used with a port that not a modem or TCP or TLI, this command is +ignored. + +@end table + +@node Logging In, , Placing the Call, Calling Out +@subsubsection Logging In +@table @code + +@item chat @var{strings} +@findex chat in sys file +@item chat-timeout @var{number} +@findex chat-timeout in sys file +@item chat-fail @var{string} +@findex chat-fail in sys file +@item chat-seven-bit @var{boolean} +@findex chat-seven-bit in sys file +@item chat-program @var{strings} +@findex chat-program in sys file + +These commands describe a chat script to use when logging on to a remote +system. Chat scripts are explained in @ref{Chat Scripts}. + +Two additional escape sequences may be used in send strings. + +@table @samp +@item \L +Send the login name, as set by the @code{call-login} command. +@item \P +Send the password, as set by the @code{call-password} command. +@end table + +Three additional escape sequences may be used with the +@code{chat-program} command. These are @samp{\L} and @samp{\P}, which +become the login name and password, respectively, and @samp{\Z}, which +becomes the name of the system of being called. + +The default chat script is: + +@example +chat "" \r\c ogin:-BREAK-ogin:-BREAK-ogin: \L word: \P +@end example + +This will send a carriage return (the @kbd{\c} suppresses the additional +trailing carriage return that would otherwise be sent) and waits for the +string @samp{ogin:} (which would be the last part of the @samp{login:} +prompt supplied by a Unix system). If it doesn't see @samp{ogin:}, it +sends a break and waits for @samp{ogin:} again. If it still doesn't see +@samp{ogin:}, it sends another break and waits for @samp{ogin:} again. +If it still doesn't see @samp{ogin:}, the chat script aborts and hangs +up the phone. If it does see @samp{ogin:} at some point, it sends the +login name (as specified by the @code{call-login} command) followed by a +carriage return (since all send strings are followed by a carriage +return unless @kbd{\c} is used) and waits for the string @samp{word:} +(which would be the last part of the @samp{Password:} prompt supplied by +a Unix system). If it sees @samp{word:}, it sends the password and a +carriage return, completing the chat script. The program will then +enter the handshake phase of the UUCP protocol. + +This chat script will work for most systems, so you will only be +required to use the @code{call-login} and @code{call-password} commands. +In fact, in the file-wide defaults you could set defaults of +@samp{call-login *} and @samp{call-password *}; you would then just have +to make an entry for each system in the call-out login file. + +Some systems seem to flush input after the @samp{login:} prompt, so they +may need a version of this chat script with a @kbd{\d} before the +@kbd{\L}. When using UUCP over TCP, some servers will not be handle the +initial carriage return sent by this chat script; in this case you may +have to specify the simple chat script @samp{ogin: \L word: \P}. + +@item call-login @var{string} +@findex call-login + +Specify the login name to send with @kbd{\L} in the chat script. If the +string is @samp{*} (e.g. @samp{call-login *}) the login name will be +fetched from the call out login name and password file +(@pxref{Configuration File Names}). The string may contain escape +sequences as though it were an expect string in a chat script +(@pxref{Chat Scripts}). There is no default. + +@item call-password @var{string} +@findex call-password + +Specify the password to send with @kbd{\P} in the chat script. If the +string is @samp{*} (e.g. @samp{call-password *}) the password will be +fetched from the call-out login name and password file +(@pxref{Configuration File Names}). The string may contain escape +sequences as though it were an expect string in a chat script +(@pxref{Chat Scripts}). There is no default. + +@end table + +@node Accepting a Call, Protocol Selection, Calling Out, sys File +@subsection Accepting a Call + +@table @code + +@item called-login @var{strings} +@findex called-login + +The first @var{string} specifies the login name that the system must use +when calling in. If it is @samp{ANY} (e.g. @samp{called-login ANY}) any +login name may be used; this is useful to override a file-wide default +and to indicate that future alternates may have different login names. +Case is significant. The default value is @samp{ANY}. + +Different alternates (@pxref{Defaults and Alternates}) may use different +@code{called-login} commands, in which case the login name will be used +to select which alternate is in effect; this will only work if the first +alternate (before the first @code{alternate} command) uses the +@code{called-login} command. + +Additional strings may be specified after the login name; they are a +list of which systems are permitted to use this login name. If this +feature is used, then normally the login name will only be given in a +single @code{called-login} command. Only systems which appear on the +list, or which use an explicit @code{called-login} command, will be +permitted to use that login name. If the same login name is used more +than once with a list of systems, all the lists are concatenated +together. This feature permits you to restrict a login name to a +particular set of systems without requiring you to use the +@code{called-login} command for every single system; you can achieve a +similar effect by using a different system file for each permitted login +name with an appropriate @code{called-login} command in the file-wide +defaults. + +@item callback @var{boolean} +@findex callback + +If @var{boolean} is true, then when the remote system calls +@code{uucico} will hang up the connection and prepare to call it back. +The default is false. + +@item called-chat @var{strings} +@findex called-chat +@item called-chat-timeout @var{number} +@findex called-chat-timeout +@item called-chat-fail @var{string} +@findex called-chat-fail +@item called-chat-seven-bit @var{boolean} +@findex called-chat-seven-bit +@item called-chat-program @var{strings} +@findex called-chat-program + +These commands may be used to define a chat script (@pxref{Chat +Scripts}) that is run whenever the local system is called by the system +being defined. The chat script defined by the @code{chat} command +(@pxref{Logging In}), on the other hand, is used when the remote system +is called. This called chat script might be used to set special modem +parameters that are appropriate to a particular system. It is run after +protocol negotiation is complete, but before the protocol has been +started. See @ref{Logging In} for additional escape sequence which may +be used besides those defined for all chat scripts. There is no default +called chat script. If the called chat script fails, the incoming call +will be aborted. + +@end table + +@node Protocol Selection, File Transfer Control, Accepting a Call, sys File +@subsection Protocol Selection + +@table @code + +@item protocol @var{string} +@findex protocol in sys file + +Specifies which protocols to use for the other system, and in which +order to use them. This would not normally be used. For example, +@samp{protocol tfg}. + +The default depends on the characteristics of the port and the dialer, +as specified by the @code{seven-bit} and @code{reliable} commands. If +neither the port nor the dialer use either of these commands, the +default is to assume an eight-bit reliable connection. The commands +@samp{seven-bit true} or @samp{reliable false} might be used in either +the port or the dialer to change this. Each protocol has particular +requirements that must be met before it will be considered during +negotiation with the remote side. + +The @samp{t} and @samp{e} protocols are intended for use over TCP or +some other communication path with end to end reliability, as they do no +checking of the data at all. They will only be considered on a TCP port +which is both reliable and eight bit. + +The @samp{i} protocol is a bidirectional protocol. It requires an +eight-bit connection. It will run over a half-duplex link, such as +Telebit modems in PEP mode, but for efficient use of such a connection +you must use the @code{half-duplex} command (@pxref{port File}). + +The @samp{g} protocol is robust, but requires an eight-bit connection. + +The @samp{G} protocol is the System V Release 4 version of the @samp{g} +protocol. + +The @samp{a} protocol is a Zmodem like protocol, contributed by Doug +Evans. It requires an eight-bit connection, but unlike the @samp{g} or +@samp{i} protocol it will work if certain control characters may not be +transmitted. + +The @samp{j} protocol is a variant of the @samp{i} protocol which can +avoid certain control characters. The set of characters it avoids can +be set by a parameter. While it technically does not require an eight +bit connection (it could be configured to avoid all characters with the +high bit set) it would be very inefficient to use it over one. It is +useful over a eight-bit connection that will not transmit certain +control characters. + +The @samp{f} protocol is intended for use with X.25 connections; it +checksums each file as a whole, so any error causes the entire file to +be retransmitted. It requires a reliable connection, but only uses +seven-bit transmissions. It is a streaming protocol, so, while it can +be used on a serial port, the port must be completely reliable and flow +controlled; many aren't. + +The @samp{v} protocol is the @samp{g} protocol as used by the DOS +program UUPC/Extended. It is provided only so that UUPC/Extended users +can use it; there is no particular reason to select it. + +The protocols will be considered in the order shown above. This means +that if neither the @code{seven-bit} nor the @code{reliable} command are +used, the @samp{t} protocol will be used over a TCP connection and the +@samp{i} protocol will be used over any other type of connection +(subject, of course, to what is supported by the remote system; it may +be assumed that all systems support the @samp{g} protocol). + +Note that currently specifying both @samp{seven-bit true} and +@samp{reliable false} will not match any protocol. If this occurs +through a combination of port and dialer specifications, you will have +to use the @code{protocol} command for the system or no protocol will be +selected at all (the only reasonable choice would be @samp{protocol f}). + +A protocol list may also be specified for a port (@pxref{port File}), +but if there is a list for the system the list for the port is ignored. + +@item protocol-parameter @var{character} @var{string} @dots{} +@findex protocol-parameter in sys file + +@var{character} is a single character specifying a protocol. The +remaining strings are a command specific to that protocol which will be +executed if that protocol is used. A typical command is something like +@samp{window 7}. The particular commands are protocol specific. + +The @samp{i} protocol supports the following commands, all of which take +numeric arguments: + +@table @code +@item window +The window size to request the remote system to use. This must be +between 1 and 16 inclusive. The default is 16. +@item packet-size +The packet size to request the remote system to use. This must be +between 1 and 4095 inclusive. The default is 1024. +@item remote-packet-size +If this is between 1 and 4095 inclusive, the packet size requested by +the remote system is ignored and this is used instead. The default is +0, which means that the remote system's request is honored. +@item sync-timeout +The length of time, in seconds, to wait for a SYNC packet from the remote +system. SYNC packets are exchanged when the protocol is started. The +default is 10. +@item sync-retries +The number of times to retry sending a SYNC packet before giving up. +The default is 6. +@item timeout +The length of time, in seconds, to wait for an incoming packet before +sending a negative acknowledgement. The default is 10. +@item retries +The number of times to retry sending a packet or a negative +acknowledgement before giving up and closing the connection. The +default is 6. +@item errors +The maximum number of errors to permit before closing the connection. +The default is 100. +@item error-decay +The rate at which to ignore errors. Each time this many packets are +received, the error count is decreased by one, so that a long connection +with an occasional error will not exceed the limit set by @code{errors}. +The default is 10. +@item ack-frequency +The number of packets to receive before sending an acknowledgement. The +default is half the requested window size, which should provide good +performance in most cases. +@end table + +The @samp{g}, @samp{G} and @samp{v} protocols support the following +commands, all of which take numeric arguments, except +@code{short-packets} which takes a boolean argument: + +@table @code +@item window +The window size to request the remote system to use. This must be +between 1 and 7 inclusive. The default is 7. +@item packet-size +The packet size to request the remote system to use. This must be a +power of 2 between 32 and 4096 inclusive. The default is 64 for the +@samp{g} and @samp{G} protocols and 512 for the @samp{v} protocol. Many +older UUCP packages do not support packet sizes larger than 64, and many +others do not support packet sizes larger than 128. Some UUCP packages +will even dump core if a larger packet size is requested. The packet +size is not a negotiation, and it may be different in each direction. +If you request a packet size larger than the remote system supports, you +will not be able to send any files. +@item startup-retries +The number of times to retry the initialization sequence. The default +is 8. +@item init-retries +The number of times to retry one phase of the initialization sequence +(there are three phases). The default is 4. +@item init-timeout +The timeout in seconds for one phase of the initialization sequence. The +default is 10. +@item retries +The number of times to retry sending either a data packet or a request +for the next packet. The default is 6. +@item timeout +The timeout in seconds when waiting for either a data packet or an +acknowledgement. The default is 10. +@item garbage +The number of unrecognized bytes to permit before dropping the +connection. This must be larger than the packet size. The default is +10000. +@item errors +The number of errors (malformed packets, out of order packets, bad +checksums, or packets rejected by the remote system) to permit before +dropping the connection. The default is 100. +@item error-decay +The rate at which to ignore errors. Each time this many packets are +received, the error count is decreased by one, so that a long connection +with an occasional error will not exceed the limit set by @code{errors}. +The default is 10. +@item remote-window +If this is between 1 and 7 inclusive, the window size requested by the +remote system is ignored and this is used instead. This can be useful +when dealing with some poor UUCP packages. The default is 0, which +means that the remote system's request is honored. +@item remote-packet-size +If this is between 32 and 4096 inclusive the packet size requested by +the remote system is ignored and this is used instead. There is +probably no good reason to use this. The default is 0, which means that +the remote system's request is honored. +@item short-packets +If this is true, then the code will optimize by sending shorter packets +when there is less data to send. This confuses some UUCP packages, such +as System V Release 4 (when using the @samp{G} protocol) and Waffle; +when connecting to such a package, this parameter must be set to false. +The default is true for the @samp{g} and @samp{v} protocols and false +for the @samp{G} protocol. +@end table + +The @samp{a} protocol is a Zmodem like protocol contributed by Doug +Evans. It supports the following commands, all of which take numeric +arguments except for @code{escape-control}, which takes a boolean +argument: + +@table @code +@item timeout +Number of seconds to wait for a packet to arrive. The default is 10. +@item retries +The number of times to retry sending a packet. The default is 10. +@item startup-retries +The number of times to retry sending the initialization packet. The +default is 4. +@item garbage +The number of garbage characters to accept before closing the +connection. The default is 2400. +@item send-window +The number of characters that may be sent before waiting for an +acknowledgement. The default is 1024. +@item escape-control +Whether to escape control characters. If this is true, the protocol may +be used over a connection which does not transmit certain control +characters, such as @code{XON} or @code{XOFF}. The connection must +still transmit eight bit characters other than control characters. The +default is false. +@end table + +The @samp{j} protocol can be used over an eight bit connection that will +not transmit certain control characters. It accepts the same protocol +parameters that the @samp{i} protocol accepts, as well as one more: + +@table @code +@item avoid +A list of characters to avoid. This is a string which is interpreted as +an escape sequence (@pxref{Chat Scripts}). The protocol does not have a +way to avoid printable ASCII characters (byte values from 32 to 126, +inclusive); only ASCII control characters and eight-bit characters may +be avoided. The default value is @samp{\021\023}; these are the +characters @code{XON} and @code{XOFF} which many connections use for +flow control. If the package is configured to use @code{HAVE_BSD_TTY}, +then on some versions of Unix you may have to avoid @samp{\377} as well, +due to the way some implementations of the BSD terminal driver handle +signals. +@end table + +The @samp{f} protocol is intended for use with error-correcting modems +only; it checksums each file as a whole, so any error causes the entire +file to be retransmitted. It supports the following commands, both of +which take numeric arguments: + +@table @code +@item timeout +The timeout in seconds before giving up. The default is 120. +@item retries +How many times to retry sending a file. The default is 2. +@end table + +The @samp{t} and @samp{e} protocols are intended for use over TCP or +some other communication path with end to end reliability, as they do no +checking of the data at all. They both support a single command, which +takes a numeric argument: + +@table @code +@item timeout +The timeout in seconds before giving up. The default is 120. +@end table + +The protocol parameters are reset to their default values after each +call. + +@end table + +@node File Transfer Control, Miscellaneous (sys), Protocol Selection, sys File +@subsection File Transfer Control + +@table @code + +@item send-request @var{boolean} +@findex send-request + +The @var{boolean} determines whether the remote system is permitted to +request files from the local system. The default is yes. + +@item receive-request @var{boolean} +@findex receive-request + +The @var{boolean} determines whether the remote system is permitted to +send files to the local system. The default is yes. + +@item request @var{boolean} +@findex request + +A shorthand command, equivalent to specifying both @samp{send-request +@var{boolean}} and @samp{receive-request @var{boolean}}. + +@item call-transfer @var{boolean} +@findex call-transfer + +The @var{boolean} is checked when the local system places the call. It +determines whether the local system may do file transfers queued up for +the remote system. The default is yes. + +@item called-transfer @var{boolean} +@findex called-transfer + +The @var{boolean} is checked when the remote system calls in. It +determines whether the local system may do file transfers queued up for +the remote system. The default is yes. + +@item transfer @var{boolean} +@findex transfer + +Equivalent to specifying both @samp{call-transfer @var{boolean}} +@samp{called-transfer @var{boolean}}. + +@item call-local-size @var{number} @var{string} +@findex call-local-size + +The @var{string} is a time string (@pxref{Time Strings}). The +@var{number} is the size in bytes of the largest file that should be +transferred at a time matching the time string if the local system +placed the call and the request was made by the local system. This +command may appear multiple times in a single alternate. If this +command does not appear, or if none of the time strings match, there are +no size restrictions. + +With all the size control commands, the size of a file from the remote +system (as opposed to a file from the local system) will only be checked +if the other system is running this package; other UUCP packages will +not understand a maximum size request, nor will they provide the size of +remote files. + +@item call-remote-size @var{number} @var{string} +@findex call-remote-size + +Specify the size in bytes of the largest file that should be +transferred at a given time by remote request when the local system +placed the call. This command may appear multiple times in a single +alternate. If this command does not appear, there are no size +restrictions. + +@item called-local-size @var{number} @var{string} +@findex called-local-size + +Specify the size in bytes of the largest file that should be transferred +at a given time by local request when the remote system placed the call. +This command may appear multiple times in a single alternate. If this +command does not appear, there are no size restrictions. + +@item called-remote-size @var{number} @var{string} +@findex called-remote-size + +Specify the size in bytes of the largest file that should be transferred +at a given time by remote request when the remote system placed the +call. This command may appear multiple times in a single alternate. If +this command does not appear, there are no size restrictions. + +@item local-send @var{strings} +@findex local-send + +Specifies that files in the directories named by the @var{strings} may +be sent to the remote system when requested locally (using @code{uucp} +or @code{uux}). The directories in the list should be separated by +whitespace. A @kbd{~} may be used for the public directory. On a Unix +system, this is typically @file{/usr/spool/uucppublic}; the public +directory may be set with the @code{pubdir} command. Here is an example +of @code{local-send}: + +@example +local-send ~ /usr/spool/ftp/pub +@end example + +Listing a directory allows all files within the directory and all +subdirectories to be sent. Directories may be excluded by preceding +them with an exclamation point. For example: + +@example +local-send /usr/ftp !/usr/ftp/private ~ +@end example + +@noindent +means that all files in @file{/usr/ftp} or the public directory may be +sent, except those files in @file{/usr/ftp/private}. The list of +directories is read from left to right, and the last directory to apply +takes effect; this means that directories should be listed from top +down. The default is the root directory (i.e., any file at all may be +sent by local request). + +@item remote-send @var{strings} +@findex remote-send + +Specifies that files in the named directories may be sent to the remote +system when requested by the remote system. The default is @kbd{~}. + +@item local-receive @var{strings} +@findex local-receive + +Specifies that files may be received into the named directories when +requested by a local user. The default is @kbd{~}. + +@item remote-receive @var{strings} +@findex remote-receive + +Specifies that files may be received into the named directories when +requested by the remote system. The default is @kbd{~}. On Unix, the +remote system may only request that files be received into directories +that are writeable by the world, regardless of how this is set. + +@item forward-to @var{strings} +@findex forward-to + +Specifies a list of systems to which files may be forwarded. The remote +system may forward files through the local system on to any of the +systems in this list. The string @samp{ANY} may be used to permit +forwarding to any system. The default is to not permit forwarding to +other systems. Note that if the remote system is permitted to execute +the @code{uucp} command, it effectively has the ability to forward to +any system. + +@item forward-from @var{strings} +@findex forward-from + +Specifies a list of systems from which files may be forwarded. The +remote system may request files via the local system from any of the +systems in this list. The string @samp{ANY} may be used to permit +forwarding to any system. The default is to not permit forwarding from +other systems. Note that if a remote system is permitted to execute the +@code{uucp} command, it effectively has the ability to request files +from any system. + +@item forward @var{strings} +@findex forward + +Equivalent to specifying both @samp{forward-to @var{strings}} and +@samp{forward-from @var{strings}}. This would normally be used rather +than either of the more specific commands. + +@end table + +@node Miscellaneous (sys), Default sys File Values, File Transfer Control, sys File +@subsection Miscellaneous sys File Commands + +@table @code + +@item sequence @var{boolean} +@findex sequence + +If @var{boolean} is true, then conversation sequencing is automatically +used for the remote system, so that if somebody manages to spoof as the +remote system, it will be detected the next time the remote system +actually calls. This is false by default. + +@item command-path @var{string} +@findex command-path + +Specifies the path (a list of whitespace separated directories) to be +searched to locate commands to execute. This is only used for commands +requested by @code{uux}, not for chat programs. The default is from +@file{policy.h}. + +@item commands @var{strings} +@findex commands + +The list of commands which the remote system is permitted to execute +locally. For example: @samp{commands rnews rmail}. If the value is +@samp{ALL} (case significant), all commands may be executed. The +default is @samp{rnews rmail}. + +@item free-space @var{number} +@findex free-space + +Specify the minimum amount of file system space (in bytes) to leave free +after receiving a file. If the incoming file will not fit, it will be +rejected. This initial rejection will only work when talking to another +instance of this package, since older UUCP packages do not provide the +file size of incoming files. Also, while a file is being received, +@code{uucico} will periodically check the amount of free space. If it +drops below the amount given by the @code{free-space} command, the file +transfer will be aborted. The default amount of space to leave free is +from @file{policy.h}. This file space checking may not work on all +systems. + +@item pubdir @var{string} +@findex pubdir in sys file + +Specifies the public directory that is used when @kbd{~} is specifed in +a file transfer or a list of directories. This essentially overrides +the public directory specified in the main configuration file for this +system only. The default is the public directory specified in the main +configuration file (which defaults to a value from @file{policy.h}). + +@item debug @var{string} @dots{} +@findex debug in sys file + +Set additional debugging for calls to or from the system. This may be +used to debug a connection with a specific system. It is particularly +useful when debugging incoming calls, since debugging information will +be generated whenever the call comes in. See the @code{debug} command +in the main configuration file (@pxref{Debugging Levels}) for more +details. The debugging information specified here is in addition to +that specified in the main configuration file or on the command line. + +@item max-remote-debug @var{string} @dots{} +@findex max-remote-debug + +When the system calls in, it may request that the debugging level be set +to a certain value. This command may be used to put a limit on the +debugging level which the system may request, to avoid filling up the +disk with debugging information. Only the debugging types named in the +@code{max-remote-debug} command may be turned on by the remote system. +To prohibit any debugging, use @samp{max-remote-debug none}. + +@end table + +@node Default sys File Values, , Miscellaneous (sys), sys File +@subsection Default sys File Values + +The following are used as default values for all systems; they can be +considered as appearing before the start of the file. + +@example +time Never +chat "" \r\c ogin:-BREAK-ogin:-BREAK-ogin: \L word: \P +chat-timeout 10 +callback n +sequence n +request y +transfer y +local-send / +remote-send ~ +local-receive ~ +remove-receive ~ +command-path [ from @file{policy.h} ] +commands rnews rmail +max-remote-debug abnormal,chat,handshake +@end example + +@node port File, dial File, sys File, Configuration Files +@section The Port Configuration File +@cindex port file +@cindex port configuration file +@cindex configuration file (port) + +The port files may be used to name and describe ports. By default there +is a single port file, named @file{port} in the directory +@var{newconfigdir}. This may be overridden by the @code{portfile} +command in the main configuration file; see @ref{Configuration File +Names}. + +Any commands in a port file before the first @code{port} command specify +defaults for all ports in the file; however, since the @code{type} +command must appear before all other commands for a port, the defaults +are only useful if all ports in the file are of the same type (this +restriction may be lifted in a later version). All commands after a +@code{port} command up to the next @code{port} command then describe +that port. There are different types of ports; each type supports its +own set of commands. Each command indicates which types of ports +support it. There may be many ports with the same name; if a system +requests a port by name then each port with that name will be tried +until an unlocked one is found. + +@table @code + +@item port @var{string} +@findex port in port file + +Introduces and names a port. + +@item type @var{string} +@findex type + +Define the type of port. The default is @samp{modem}. If this command +appears, it must immediately follow the @code{port} command. The type defines +what commands are subsequently allowed. Currently the types are: + +@table @samp +@item modem +For a modem hookup. +@item stdin +For a connection through standard input and standard output, as when +@code{uucico} is run as a login shell. +@item direct +For a direct connection to another system. +@item tcp +For a connection using TCP. +@item tli +For a connection using TLI. +@item pipe +For a connection through a pipe running another program. +@end table + +@item protocol @var{string} +@findex protocol in port file + +Specify a list of protocols to use for this port. This is just like the +corresponding command for a system (@pxref{Protocol Selection}). A +protocol list for a system takes precedence over a list for a port. + +@item protocol-parameter @var{character} @var{strings} [ any type ] +@findex protocol-parameter in port file + +The same command as the @code{protocol-parameter} command used for +systems (@pxref{Protocol Selection}). This one takes precedence. + +@item seven-bit @var{boolean} [ any type ] +@findex seven-bit in port file + +This is only used during protocol negotiation; if the argument is true, +it forces the selection of a protocol which works across a seven-bit +link. It does not prevent eight bit characters from being transmitted. +The default is false. + +@item reliable @var{boolean} [ any type ] +@findex reliable in port file + +This is only used during protocol negotiation; if the argument is +false, it forces the selection of a protocol which works across +an unreliable communication link. The default is true. It would +be more common to specify this for a dialer rather than a port. + +@item half-duplex @var{boolean} [ any type ] +@findex half-duplex in port file + +If the argument is true, it means that the port only supports +half-duplex connections. This only affects bidirectional protocols, and +causes them to not do bidirectional transfers. + +@item device @var{string} [ modem, direct and tli only ] +@findex device + +Names the device associated with this port. If the device is not named, +the port name is taken as the device. Device names are system +dependent. On Unix, a modem or direct connection might be something +like @file{/dev/ttyd0}; a TLI port might be @file{/dev/inet/tcp}. + +@itemx speed @var{number} [modem and direct only ] +@findex speed in port file +@item baud @var{number} [ modem and direct only ] +@findex baud in port file + +The speed this port runs at. If a system specifies a speed but no port +name, then all ports which match the speed will be tried in order. If +the speed is not specified here and is not specified by the system, the +natural speed of the port will be used by default. + +@itemx speed-range @var{number} @var{number} [ modem only ] +@findex speed-range +@item baud-range @var{number} @var{number} [ modem only ] +@findex baud-range + +Specify a range of speeds this port can run at. The first number is the +minimum speed, the second number is the maximum speed. These numbers +will be used when matching a system which specifies a desired speed. +The simple @code{speed} (or @code{baud}) command is still used to +determine the speed to run at if the system does not specify a speed. +For example, the command @samp{speed-range 300 19200} means that the +port will match any system which uses a speed from 300 to 19200 baud +(and will use the speed specified by the system); this could be combined +with @samp{speed 2400}, which means that when this port is used with a +system that does not specify a speed, the port will be used at 2400 +baud. + +@item carrier @var{boolean} [ modem and direct only ] +@findex carrier in port file + +The argument indicates whether the port supports carrier. + +If a modem port does not support carrier, the carrier detect signal will +never be required on this port, regardless of what the modem chat script +indicates. The default for a modem port is true. + +If a direct port supports carrier, the port will be set to expect +carrier whenever it is used. The default for a direct port is false. + +@item hardflow @var{boolean} [ modem and direct only ] +@findex hardflow + +The argument indicates whether the port supports hardware flow control. +If it does not, hardware flow control will not be turned on for this +port. The default is true. Hardware flow control is only supported on +some systems. + +@item dial-device @var{string} [ modem only ] +@findex dial-device + +Dialing instructions should be output to the named device, rather than +to the normal port device. The default is to output to the normal port +device. + +@item dialer @var{string} [ modem only ] +@findex dialer in port file + +Name a dialer to use. The information is looked up in the dial file. +There is no default. Some sort of dialer information must be specified +to call out on a modem. + +@item dialer @var{string} @dots{} [ modem only ] + +Execute a dialer command. If a dialer is named (by using the first form +of this command, described just above), these commands are ignored. +They may be used to specify dialer information directly in simple +situations without needing to go to a separate file. There is no +default. Some sort of dialer information must be specified to call out +on a modem. + +@item dialer-sequence @var{strings} [ modem or tcp or tli only ] +@findex dialer-sequence + +Name a sequence of dialers and tokens (phone numbers) to use. The first +argument names a dialer, and the second argument names a token. The +third argument names another dialer, and so on. If there are an odd +number of arguments, the phone number specified with a @code{phone} +command in the system file is used as the final token. The token is +what is used for @kbd{\D} or @kbd{\T} in the dialer chat script. If the +token in this string is @kbd{\D}, the system phone number will be used; +if it is @kbd{\T}, the system phone number will be used after undergoing +dialcodes translation. A missing final token is taken as @kbd{\D}. + +This command currently does not work if @code{dial-device} is specified; +to handle this correctly will require a more systematic notion of chat +scripts. Moreover, the @code{complete} and @code{abort} chat scripts, +the protocol parameters, and the @code{carrier} and @code{dtr-toggle} +commands are ignored for all but the first dialer. + +This command basically lets you specify a sequence of chat scripts to +use. For example, the first dialer might get you to a local network and +the second dialer might describe how to select a machine from the local +network. This lets you break your dialing sequence into simple modules, +and may make it easier to share dialer entries between machines. + +This command is to only way to use a chat script with a TCP port. This +can be useful when using a modem which is accessed via TCP. + +When this command is used with a TLI port, then if the first dialer is +@samp{TLI} or @samp{TLIS} the first token is used as the address to +connect to. If the first dialer is something else, or if there is no +token, the address given by the @code{address} command is used +(@pxref{Placing the Call}). Escape sequences in the address are +expanded as they are for chat script expect strings (@pxref{Chat +Scripts}). The different between @samp{TLI} and @samp{TLIS} is that the +latter implies the command @samp{stream true}. These contortions are +all for HDB compatibility. Any subsequent dialers are treated as they +are for a TCP port. + +@item lockname @var{string} [ modem and direct only ] +@findex lockname + +Give the name to use when locking this port. On Unix, this is the name +of the file that will be created in the lock directory. It is used as +is, so on Unix it should generally start with @samp{LCK..}. For +example, if a single port were named both @file{/dev/ttycu0} and +@file{/dev/tty0} (perhaps with different characteristics keyed on the +minor device number), then the command @code{lockname LCK..ttycu0} could +be used to force the latter to use the same lock file name as the +former. + +@item service @var{string} [ tcp only ] +@findex service + +Name the TCP port number to use. This may be a number. If not, it will +be looked up in @file{/etc/services}. If this is not specified, the +string @samp{uucp} is looked up in @file{/etc/services}. If it is not +found, port number 540 (the standard UUCP-over-TCP port number) will be +used. + +@item push @var{strings} [ tli only ] +@findex push + +Give a list of modules to push on to the TLI stream. + +@item stream @var{boolean} [ tli only ] +@findex stream + +If this is true, and the @code{push} command was not used, the +@samp{tirdwr} module is pushed on to the TLI stream. + +@item server-address @var{string} [ tli only ] +@findex server-address + +Give the address to use when running as a TLI server. Escape sequences +in the address are expanded as they are for chat script expect strings +(@pxref{Chat Scripts}). + +@item command @var{strings} [ pipe only ] +@findex command + +Give the command, with arguments, to run when using a pipe port type. +When a port of this type is used, the command is executed and uucico +communicates with it over a pipe. This permits uucico or cu to +communicate with another system which can only be reached through some +unusual means. A sample use might be @samp{command /bin/rlogin -E -8 -l +@var{login} @var{system}}. The command is run with the full privileges +of UUCP; it is responsible for maintaining security. + +@end table + +@node dial File, Security, port File, Configuration Files +@section The Dialer Configuration File +@cindex dial file +@cindex dialer configuration file +@cindex configuration file (dial) + +The dialer configuration files define dialers. By default there is a +single dialer file, named @file{dial} in the directory +@var{newconfigdir}. This may be overridden by the @code{dialfile} +command in the main configuration file; see @ref{Configuration File +Names}. + +Any commands in the file before the first @code{dialer} command specify +defaults for all the dialers in the file. All commands after a +@code{dialer} command up to the next @code{dialer} command are +associated with the named dialer. + +@table @code + +@item dialer @var{string} +@findex dialer in dial file + +Introduces and names a dialer. + +@item chat @var{strings} +@findex chat in dial file +@item chat-timeout @var{number} +@findex chat-timeout in dial file +@item chat-fail @var{string} +@findex chat-fail in dial file +@item chat-seven-bit @var{boolean} +@findex chat-seven-bit in dial file +@item chat-program @var{strings} +@findex chat-program in dial file + +Specify a chat script to be used to dial the phone. See @ref{Chat +Scripts} for full details on chat scripts. + +Taylor UUCP will sleep for one second between attempts to dial out on a +modem. If your modem requires a longer wait period, you must start your +chat script with delays (@samp{\d} in a send string). + +The chat script will be read from and sent to the port specified by the +@code{dial-device} command for the port, if there is one. + +The following escape addition escape sequences may appear in send +strings: + +@table @kbd +@item \D +send phone number without dialcode translation +@item \T +send phone number with dialcode translation +@item \M +do not require carrier +@item \m +require carrier (fail if not present) +@end table + +See the description of the dialcodes file (@pxref{Configuration File +Names}) for a description of dialcode translation. If the port does not +support carrier (as set by the @code{carrier} command in the port file) +@kbd{\M} and @kbd{\m} are ignored. If both the port and the dialer +support carrier (as set by the @code{carrier} command in the port file +and the @code{carrier} command in the dialer file), then every chat +script implicitly begins with @kbd{\M} and ends with @kbd{\m}. There is +no default chat script for dialers. + +The following additional escape sequences may be used in +@code{chat-program}: + +@table @kbd +@item \D +phone number without dialcode translation +@item \T +phone number with dialcode translation +@end table + +If the program changes the port in any way (e.g., sets parity) the +changes will be preserved during protocol negotiation, but once the +protocol is selected it will change the port settings. + +@item dialtone @var{string} +@findex dialtone + +A string to output when dialing the phone number which causes the modem +to wait for a secondary dial tone. This is used to translate the +@kbd{=} character in a phone number. The default is a comma. + +@item pause @var{string} +@findex pause + +A string to output when dialing the phone number which causes the modem +to wait for 1 second. This is used to translate the @kbd{-} character +in a phone number. The default is a comma. + +@item carrier @var{boolean} +@findex carrier in dial file + +If the argument is true, the dialer supports the modem carrier signal. +After the phone number is dialed, @code{uucico} will require that +carrier be on. One some systems, it will be able to wait for it. If +the argument is false, carrier will not be required. The default is +true. + +@item carrier-wait @var{number} +@findex carrier-wait + +If the port is supposed to wait for carrier, this may be used to +indicate how many seconds to wait. The default is 60 seconds. Only +some systems support waiting for carrier. + +@item dtr-toggle @var{boolean} @var{boolean} +@findex dtr-toggle + +If the first argument is true, then DTR is toggled before using +the modem. This is only supported on some systems and some ports. The +second @var{boolean} need not be present; if it is, and it is +true, the program will sleep for 1 second after toggling DTR. +The default is not to toggle DTR. + +@item complete-chat @var{strings} +@findex complete-chat +@item complete-chat-timeout @var{number} +@findex complete-chat-timeout +@item complete-chat-fail @var{string} +@findex complete-chat-fail +@item complete-chat-seven-bit @var{boolean} +@findex complete-chat-seven-bit +@item complete-chat-program @var{strings} +@findex complete-chat-program + +These commands define a chat script (@pxref{Chat Scripts}) which is run +when a call is finished normally. This allows the modem to be reset. +There is no default. No additional escape sequences may be used. + +@item complete @var{string} +@findex complete + +This is a simple use of @code{complete-chat}. It is equivalent to +@code{complete-chat "" @var{string}}; this has the effect of sending +@var{string} to the modem when a call finishes normally. + +@item abort-chat @var{strings} +@findex abort-chat +@item abort-chat-timeout @var{number} +@findex abort-chat-timeout +@item abort-chat-fail @var{string} +@findex abort-chat-fail +@item abort-chat-seven-bit @var{boolean} +@findex abort-chat-seven-bit +@item abort-chat-program @var{strings} +@findex abort-chat-program + +These commands define a chat script (@pxref{Chat Scripts}) to be run +when a call is aborted. They may be used to interrupt and reset the +modem. There is no default. No additional escape sequences may be +used. + +@item abort @var{string} +@findex abort + +This is a simple use of @code{abort-chat}. It is equivalent to +@code{abort-chat "" @var{string}}; this has the effect of sending +@var{string} to the modem when a call is aborted. + +@item protocol-parameter @var{character} @var{strings} +@findex protocol-parameter in dial file + +Set protocol parameters, just like the @code{protocol-parameter} command +in the system configuration file or the port configuration file; see +@ref{Protocol Selection}. These parameters take precedence, then those +for the port, then those for the system. + +@item seven-bit @var{boolean} +@findex seven-bit in dial file + +This is only used during protocol negotiation; if it is true, it +forces selection of a protocol which works across a seven-bit link. It +does not prevent eight bit characters from being transmitted. The +default is false. It would be more common to specify this for a +port than for a dialer. + +@item reliable @var{boolean} +@findex reliable in dial file + +This is only used during protocol negotiation; if it is false, it +forces selection of a protocol which works across an unreliable +communication link. The default is true. + +@item half-duplex @var{boolean} [ any type ] +@findex half-duplex in dial file + +If the argument is true, it means that the dialer only supports +half-duplex connections. This only affects bidirectional protocols, and +causes them to not do bidirectional transfers. + +@end table + +@node Security, , dial File, Configuration Files +@section Security + +This discussion of UUCP security applies only to Unix. It is a bit +cursory; suggestions for improvement are solicited. + +UUCP is traditionally not very secure. Taylor UUCP addresses some +security issues, but is still far from being a secure system. + +If security is very important to you, then you should not permit any +external access to your computer, including UUCP. Any opening to the +outside world is a potential security risk. + +By default Taylor UUCP provides few mechanisms to secure local users of +the system from each other. You can allow increased security by putting +the owner of the UUCP programs (normally @code{uucp}) into a separate +group; the use of this is explained in the following paragraphs, which +refer to this separate group as @code{uucp-group}. + +When the @code{uucp} program is invoked to copy a file to a remote +system, it will by default copy the file into the UUCP spool directory. +When the @code{uux} program is used, the @samp{-C} switch must be used +to copy the file into the UUCP spool directory. In any case, once the +file has been copied into the spool directory, other local users will +not be able to access it. + +When a file is requested from a remote system, UUCP will only permit it +to be placed in a directory which is writable by the requesting user. +The directory must also be writable by UUCP. A local user can create a +directory with a group of @code{uucp-group} and set the mode to permit +group write access. This will allow the file be requested without +permitting it to be viewed by any other user. + +There is no provision for security for @code{uucp} requests (as opposed +to @code{uux} requests) made by a user on a remote system. A file sent +over by a remote request may only be placed in a directory which is +world writable, and the file will be world readable and writable. This +will permit any local user to destroy or replace the contents of the +file. A file requested by a remote system must be world readable, and +the directory it is in must be world readable. Any local user will be +able to examine, although not necessarily modify, the file before it is +sent. + +There are some security holes and race conditions that apply to the +above discussion which I will not elaborate on. They are not hidden +from anybody who reads the source code, but they are somewhat technical +and difficult (though scarcely impossible) to exploit. Suffice it to +say that even under the best of conditions UUCP is not completely +secure. + +For many sites, security from remote sites is a more important +consideration. Fortunately, Taylor UUCP does provide some support in +this area. + +The greatest security is provided by always dialing out to the other +site. This prevents anybody from pretending to be the other site. Of +course, only one side of the connection can do this. + +If remote dialins must be permitted, then it is best if the dialin line +is used only for UUCP. If this is the case, then you should create a +call-in password file (@pxref{Configuration File Names}) and let +@code{uucico} do its own login prompting. For example, to let remote +sites log in on a port named @samp{entry} in the port file (@pxref{port +File}) you might invoke @samp{uucico -p entry}. This would cause +@code{uucico} to enter an endless loop of login prompts and daemon +executions. The advantage of this approach is that even if remote users +break into the system by guessing or learning the password, they will +only be able to do whatever @code{uucico} permits them to do. They will +not be able to start a shell on your system. + +If remote users can dial in and log on to your system, then you have a +security hazard more serious than that posed by UUCP. But then, you +probably knew that already. + +Once your system has connected with the remote UUCP, there is a fair +amount of control you can exercise. You can use the @code{remote-send} +and @code{remote-receive} commands to control the directories the remote +UUCP can access. You can use the @code{request} command to prevent the +remote UUCP from making any requests of your system at all; however, if +you do this it will not even be able to send you mail or news. If you +do permit remote requests, you should be careful to restrict what +commands may be executed at the remote system's request. The default is +@code{rmail} and @code{rnews}, which will suffice for most systems. + +If different remote systems call in and they must be granted different +privileges (perhaps some systems are within the same organization and +some are not) then the @code{called-login} command should be used for +each system to require that they different login names. Otherwise it +would be simple for a remote system to use the @code{myname} command and +pretend to be a different system. The @code{sequence} command can be +used to detect when one system pretended to be another, but since the +sequence numbers must be reset manually after a failed handshake this +can sometimes be more trouble than it's worth. + +@node Protocols, Hacking, Configuration Files, Top +@chapter UUCP protocol internals + +A detailed description of how the various UUCP protocols work is posted +monthly to the newsgroups @samp{comp.mail.uucp}, @samp{news.answers} and +@samp{comp.answers}. There is no need to read this information in order +to use Taylor UUCP. It is intended for people who are interested in how +the UUCP code works. + +@node Hacking, Acknowledgements, Protocols, Top +@chapter Hacking Taylor UUCP + +This chapter provides the briefest of guides to the Taylor UUCP source +code itself. + +@menu +* System Dependence:: System Dependence +* Naming Conventions:: Naming Conventions +* Patches:: Patches +@end menu + +@node System Dependence, Naming Conventions, Hacking, Hacking +@section System Dependence + +The code is carefully segregated into a system independent portion and a +system dependent portion. The system dependent code is in the +@file{unix} subdirectory, and also in the files @file{tcp.c}, +@file{tli.c} and @file{sysh.unx} (also known as @file{sysdep.h}). + +With the right configuration parameters, the system independent code +calls only ANSI C functions. Some of the less common ANSI C functions +are also provided in the @file{lib} directory. The replacement function +@code{strtol} in @file{lib/strtol.c} assumes that the characters @kbd{A} +to @kbd{F} and @kbd{a} to @kbd{f} appear in strictly sequential order. +The function @code{igradecmp} in @file{uuconf/grdcmp.c} assumes that the +upper and lower case letters appear in order. Both assumptions are true +for ASCII and EBCDIC, but neither is guaranteed by ANSI C. Disregarding +these caveats, I believe that the system independent portion of the code +is strictly conforming. + +That's not too exciting, since all the work is done in the system +dependent code. I think that this code can conform to POSIX 1003.1, +given the right compilation parameters. I'm a bit less certain about +this, though. + +The code is in use on a 16 bit segmented system with no function +prototypes, so I'm certain that all casts to long and pointers are done +when necessary. + +@node Naming Conventions, Patches, System Dependence, Hacking +@section Naming Conventions + +I use a modified Hungarian naming convention for my variables and +functions. As with all naming conventions, the code is rather opaque if +you are not familiar with it, but becomes clear and easy to use with +time. + +The first character indicates the type of the variable (or function +return value). Sometimes additional characters are used. I use the +following type prefixes: + +@table @samp +@item a +array; the next character is the type of an element +@item b +byte or character +@item c +count of something +@item e +stdio FILE * +@item f +boolean +@item i +generic integer +@item l +double +@item o +file descriptor (as returned by open, creat, etc.) +@item p +generic pointer +@item q +pointer to structure +@item s +structure +@item u +void (function return values only) +@item z +character string +@end table + +A generic pointer (@code{p}) is sometimes a @code{void *}, sometimes a +function pointer in which case the prefix is pf, and sometimes a pointer +to another type, in which case the next character is the type to which +it points (pf is overloaded). + +An array of strings (@code{char *[]}) would be named @code{az} (array of +string). If this array were passed to a function, the function +parameter would be named @code{paz} (pointer to array of string). + +Note that the variable name prefixes do not necessarily indicate the +type of the variable. For example, a variable prefixed with i may be +int, long or short. Similarly, a variable prefixed with b may be a char +or an int; for example, the return value of getchar would be caught in +an int variable prefixed with b. + +For a non-local variable (extern or file static), the first character +after the type prefix is capitalized. + +Most static variables and functions use another letter after the type +prefix to indicate which module they come from. This is to help +distinguish different names in the debugger. For example, all static +functions in @file{protg.c}, the @samp{g} protocol source code, use a +module prefix of @samp{g}. This isn't too useful, as a number of +modules use a module prefix of @samp{s}. + +@node Patches, , Naming Conventions, Hacking +@section Patches + +I am always grateful for any patches sent in. Much of the flexibility +and portability of the code is due to other people. Please do not +hesitate to send me any changes you have found necessary or useful. + +When sending a patch, please send the output of the Unix @code{diff} +program invoked with the @samp{-c} option (if you have the GNU version +of @code{diff}, use the @samp{-p} option). Always invoke @code{diff} +with the original file first and the modified file second. + +If your @code{diff} does not support @samp{-c} (or you don't have +@code{diff}), send a complete copy of the modified file (if you have +just changed a single function, you can just send the new version of the +function). In particular, please do not send @code{diff} output without +the @samp{-c} option, as it is useless. + +If you have made a number of changes, it is very convenient for me if +you send each change as a separate mail message. Sometimes I will think +that one change is useful but another one is not. If they are in +different messages it is much easier for me to apply one but not the +other. + +I rarely apply the patches directly. Instead I work my way through the +hunks and apply each one separately. This ensures that the naming +remains consistent, and that I understand all the code. + +If you can not follow all these rules, then don't. But if you do, it +makes it more likely that I will incorporate your changes. I am not +paid for my UUCP work, and my available time is unfortunately very +restricted. The package is important to me, and I do what I can, but I +can not do all that I would like, much less all that everybody else +would like. + +Finally, please do not be offended if I do not reply to messages for +some time, even a few weeks. I am often behind on my mail, and if I +think your message deserves a considered reply I will often put it aside +until I have time to deal with it. + +@node Acknowledgements, Index (concepts), Hacking, Top +@chapter Acknowledgements + +This is a list of people who gave help or suggestions while I was +working on the Taylor UUCP project. Appearance on this list does not +constitute endorsement of the program, particularly since some of the +comments were criticisms. I've probably left some people off, and I +apologize for any oversight; it does not mean your contribution was +unappreciated. + +@ifinfo +First of all, I would like to thank the people at Infinity Development +Systems (formerly AIRS, which lives on in the domain name, at least for +now) for permitting me to use their computers and @file{uunet} access. +I would also like to thank Richard Stallman @code{} +for founding the Free Software Foundation and John Gilmore +@code{} for writing the initial version of gnuucp which +was a direct inspiration for this somewhat larger project. Chip +Salzenberg @code{} has contributed many patches. +Franc,ois Pinard @code{} tirelessly tested the +code and suggested many improvements. He also put together the initial +version of this document. Doug Evans contributed the zmodem protocol. +Marc Boucher @code{} contributed the code supporting the +pipe port type. Finally, Verbus M. Counts @code{} +and Centel Federal Systems, Inc. deserve special thanks, since they +actually paid me money to port this code to System III. +@end ifinfo +@iftex +First of all, I would like to thank the people at Infinity Development +Systems (formerly AIRS, which lives on in the domain name, at least for +now) for permitting me to use their computers and @file{uunet} access. +I would also like to thank Richard Stallman @code{} +for founding the Free Software Foundation and John Gilmore +@code{} for writing the initial version of gnuucp which +was a direct inspiration for this somewhat larger project. Chip +Salzenberg @code{} has contributed many patches. +@tex +Fran\c cois Pinard +@end tex +@code{} tirelessly tested the code and +suggested many improvements. He also put together the initial version +of this document. Doug Evans contributed the zmodem protocol. Marc +Boucher @code{} contributed the code supporting the pipe +port type. Finally, Verbus M. Counts @code{} and +Centel Federal Systems, Inc. deserve special thanks, since they actually +paid me money to port this code to System III. +@end iftex + +In alphabetical order: + +@example +"Earle F. Ake - SAIC" @code{} +@code{mra@@searchtech.com} (Michael Almond) +@code{cambler@@zeus.calpoly.edu} (Christopher J. Ambler) +Brian W. Antoine @code{} +@code{jantypas@@soft21.s21.com} (John Antypas) +@code{james@@bigtex.cactus.org} (James Van Artsdalen) +@code{nba@@sysware.DK} (Niels Baggesen) +@code{uunet!hotmomma!sdb} (Scott Ballantyne) +Zacharias Beckman @code{} +@code{mike@@mbsun.ann-arbor.mi.us} (Mike Bernson) +@code{bob@@usixth.sublink.org} (Roberto Biancardi) +@code{statsci!scott@@coco.ms.washington.edu} (Scott Blachowicz) +@code{bag%wood2.cs.kiev.ua@@relay.ussr.eu.net} (Andrey G Blochintsev) +@code{spider@@Orb.Nashua.NH.US} (Spider Boardman) +Gregory Bond @code{} +Marc Boucher @code{} +@code{dean@@coplex.com} (Dean Brooks) +@code{jbrow@@radical.com} (Jim Brownfield) +@code{dave@@dlb.com} (Dave Buck) +@code{gordon@@sneaky.lonestar.org} (Gordon Burditt) +@code{dburr@@sbphy.physics.ucsb.edu} (Donald Burr) +@code{mib@@gnu.ai.mit.edu} (Michael I Bushnell) +Brian Campbell @code{} +Andrew A. Chernov @code{} +@code{mafc!frank@@bach.helios.de} (Frank Conrad) +Ed Carp @code{} +@code{mpc@@mbs.linet.org} (Mark Clements) +@code{verbus@@westmark.westmark.com} (Verbus M. Counts) +@code{cbmvax!snark.thyrsus.com!cowan} (John Cowan) +Bob Cunningham @code{} +@code{kdburg@@incoahe.hanse.de} (Klaus Dahlenburg) +Damon @code{} +@code{hubert@@arakis.fdn.org} (Hubert Delahaye) +@code{markd@@bushwire.apana.org.au} (Mark Delany) +Allen Delaney @code{} +@code{denny@@dakota.alisa.com} (Bob Denny) +@code{ssd@@nevets.oau.org} (Steven S. Dick) +@code{gert@@greenie.gold.sub.org} (Gert Doering) +@code{gemini@@geminix.in-berlin.de} (Uwe Doering) +Hans-Dieter Doll @code{} +Mark W. Eichin @code{} +Andrew Evans @code{} +@code{dje@@cygnus.com} (Doug Evans) +Marc Evans @code{} +Dan Everhart @code{} +@code{kksys!kegworks!lfahnoe@@cs.umn.edu} (Larry Fahnoe) +@code{fenner@@jazz.psu.edu} (Bill Fenner) +@code{jaf@@inference.com} (Jose A. Fernandez) +"David J. Fiander" @code{} +Thomas Fischer @code{} +@code{louis@@marco.de} (Ju"rgen Fluk) +@code{erik@@eab.retix.com} (Erik Forsberg) +@code{andy@@scp.caltech.edu} (Andy Fyfe) +Lele Gaifax @code{} +@code{Peter.Galbavy@@micromuse.co.uk} +@code{hunter@@phoenix.pub.uu.oz.au} (James Gardiner [hunter]) +Terry Gardner @code{} +@code{ol@@infopro.spb.su} (Oleg Girko) +@code{jimmy@@tokyo07.info.com} (Jim Gottlieb) +Benoit Grange @code{} +@code{elg@@elgamy.jpunix.com} (Eric Lee Green) +@code{ryan@@cs.umb.edu} (Daniel R. Guilderson) +@code{greg@@gagme.chi.il.us} (Gregory Gulik) +Richard H. Gumpertz @code{} +Michael Haberler @code{} +Daniel Hagerty @code{} +@code{jh@@moon.nbn.com} (John Harkin) +@code{guy@@auspex.auspex.com} (Guy Harris) +Petri Helenius @code{} +@code{gabe@@edi.com} (B. Gabriel Helou) +Bob Hemedinger @code{} +Andrew Herbert @code{} +Peter Honeyman @code{} +@code{jhood@@smoke.marlboro.vt.us} (John Hood) +Bill Irwin @code{} +@code{pmcgw!personal-media.co.jp!ishikawa} (Chiaki Ishikawa) +@code{bei@@dogface.austin.tx.us} (Bob Izenberg) +@code{djamiga!djjames@@fsd.com} (D.J.James) +Rob Janssen @code{} +@code{harvee!esj} (Eric S Johansson) +Kevin Johnson @code{} +Alan Judge @code{} +@code{chris@@cj_net.in-berlin.de} (Christof Junge) +@code{tron@@Veritas.COM} (Ronald S. Karr) +Brendan Kehoe @code{} +@code{warlock@@csuchico.edu} (John Kennedy) +@code{kersing@@nlmug.nl.mugnet.org} (Jac Kersing) +Gabor Kiss @code{} +@code{gero@@gkminix.han.de} (Gero Kuhlmann) +@code{rob@@pact.nl} (Rob Kurver) +@code{kent@@sparky.IMD.Sterling.COM} (Kent Landfield) +@code{lebaron@@inrs-telecom.uquebec.ca} (Gregory LeBaron) +@code{karl@@sugar.NeoSoft.Com} (Karl Lehenbauer) +@code{alex@@hal.rhein-main.de} (Alexander Lehmann) +@code{merlyn@@digibd.com} (Merlyn LeRoy) +@code{clewis@@ferret.ocunix.on.ca} (Chris Lewis) +@code{gdonl@@ssi1.com} (Don Lewis) +@code{libove@@libove.det.dec.com} (Jay Vassos-Libove) +@code{bruce%blilly@@Broadcast.Sony.COM} (Bruce Lilly) +Ted Lindgreen @code{} +@code{andrew@@cubetech.com} (Andrew Loewenstern) +"Arne Ludwig" @code{} +Matthew Lyle @code{} +@code{djm@@eng.umd.edu} (David J. MacKenzie) +John R MacMillan @code{} +Giles D Malet @code{} +@code{mem@@mv.MV.COM} (Mark E. Mallett) +@code{pepe@@dit.upm.es} (Jose A. Manas) +@code{peter@@xpoint.ruessel.sub.org} (Peter Mandrella) +@code{martelli@@cadlab.sublink.org} (Alex Martelli) +W Christopher Martin @code{} +Yanek Martinson @code{} +@code{jm@@aristote.univ-paris8.fr} (Jean Mehat) +@code{me@@halfab.freiburg.sub.org} (Udo Meyer) +@code{les@@chinet.chi.il.us} (Leslie Mikesell) +@code{mmitchel@@digi.lonestar.org} (Mitch Mitchell) +Emmanuel Mogenet @code{} +@code{rmohr@@infoac.rmi.de} (Rupert Mohr) +Jason Molenda @code{} +@code{ianm@@icsbelf.co.uk} (Ian Moran) +@code{brian@@ilinx.wimsey.bc.ca} (Brian J. Murrell) +@code{service@@infohh.rmi.de} (Dirk Musstopf) +@code{lyndon@@cs.athabascau.ca} (Lyndon Nerenberg) +@code{rolf@@saans.north.de} (Rolf Nerstheimer) +@code{tom@@smart.bo.open.de} (Thomas Neumann) +@code{mnichols@@pacesetter.com} +Richard E. Nickle @code{} +@code{stephan@@sunlab.ka.sub.org} (Stephan Niemz) +@code{nolan@@helios.unl.edu} (Michael Nolan) +david nugent @code{} +Jim O'Connor @code{} +Petri Ojala @code{} +@code{oneill@@cs.ulowell.edu} (Brian 'Doc' O'Neill) +@code{abekas!dragoman!mikep@@decwrl.dec.com} (Mike Park) +Tim Peiffer @code{peiffer@@cs.umn.edu} +@code{don@@blkhole.resun.com} (Don Phillips) +"Mark Pizzolato 415-369-9366" @code{} +John Plate @code{} +@code{dplatt@@ntg.com} (Dave Platt) +@code{eldorado@@tharr.UUCP} (Mark Powell) +Mark Powell @code{} +@code{pozar@@kumr.lns.com} (Tim Pozar) +@code{putsch@@uicc.com} (Jeff Putsch) +@code{ar@@nvmr.robin.de} (Andreas Raab) +Jarmo Raiha @code{} +Scott Reynolds @code{} +@code{mcr@@Sandelman.OCUnix.On.Ca} (Michael Richardson) +Kenji Rikitake @code{} +@code{arnold@@cc.gatech.edu} (Arnold Robbins) +@code{steve@@Nyongwa.cam.org} (Steve M. Robbins) +Serge Robyns @code{} +Lawrence E. Rosenman @code{} +Jeff Ross @code{} +Aleksey P. Rudnev @code{} +"Heiko W.Rupp" @code{} +@code{wolfgang@@wsrcc.com} (Wolfgang S. Rupprecht) +@code{tbr@@tfic.bc.ca} (Tom Rushworth) +@code{jsacco@@ssl.com} (Joseph E. Sacco) +@code{rsalz@@bbn.com} (Rich Salz) +@code{sojurn!mike@@hobbes.cert.sei.cmu.edu} (Mike Sangrey) +Nickolay Saukh @code{} +@code{heiko@@lotte.sax.de} (Heiko Schlittermann) +Eric Schnoebelen @code{} +@code{russell@@alpha3.ersys.edmonton.ab.ca} (Russell Schulz) +@code{scott@@geom.umn.edu} +Igor V. Semenyuk @code{} +Christopher Sawtell @code{} +@code{schuler@@bds.sub.org} (Bernd Schuler) +@code{uunet!gold.sub.org!root} (Christian Seyb) +@code{s4mjs!mjs@@nirvo.nirvonics.com} (M. J. Shannon Jr.) +@code{peter@@ficc.ferranti.com} (Peter da Silva) +@code{vince@@victrola.sea.wa.us} (Vince Skahan) +@code{frumious!pat} (Patrick Smith) +@code{roscom!monty@@bu.edu} (Monty Solomon) +@code{sommerfeld@@orchard.medford.ma.us} (Bill Sommerfeld) +Julian Stacey @code{} +Harlan Stenn @code{} +Ralf Stephan @code{} +@code{johannes@@titan.westfalen.de} (Johannes Stille) +@code{chs@@antic.apu.fi} (Hannu Strang) +@code{ralf@@reswi.ruhr.de} (Ralf E. Stranzenbach) +@code{sullivan@@Mathcom.com} (S. Sullivan) +Shigeya Suzuki @code{} +@code{swiers@@plains.NoDak.edu} +Oleg Tabarovsky @code{} +John Theus @code{} +@code{rd@@aii.com} (Bob Thrush) +ppKarsten Thygesen @code{} +Graham Toal @code{} +@code{rmtodd@@servalan.servalan.com} (Richard Todd) +Martin Tomes @code{} +Len Tower @code{} +Mark Towfiq @code{} +@code{mju@@mudos.ann-arbor.mi.us} (Marc Unangst) +Tomi Vainio @code{} +Andrew Vignaux @code{} +@code{vogel@@omega.ssw.de} (Andreas Vogel) +@code{jos@@bull.nl} (Jos Vos) +@code{jv@@nl.net} (Johan Vromans) +David Vrona @code{} +@code{Marcel.Waldvogel@@nice.usergroup.ethz.ch} (Marcel Waldvogel) +@code{steve@@nshore.org} (Stephen J. Walick) +@code{syd@@dsinc.dsi.com} (Syd Weinstein) +@code{gerben@@rna.indiv.nluug.nl} (Gerben Wierda) +@code{jbw@@cs.bu.edu} (Joe Wells) +@code{frnkmth!twwells.com!bill} (T. William Wells) +Peter Wemm @code{} +@code{mauxci!eci386!woods@@apple.com} (Greg A. Woods) +Michael Yu.Yaroslavtsev @code{} +Alexei K. Yushin @code{} +@code{jon@@console.ais.org} (Jon Zeeff) +Matthias Zepf @code{} +Eric Ziegast @code{} +@end example + +@node Index (concepts), Index (configuration file), Acknowledgements, Top +@unnumbered Concept Index + +@printindex cp + +@node Index (configuration file), , Index (concepts), Top +@unnumbered Configuration File Index + +@printindex fn + +@contents +@bye -- cgit v1.1