Installation Notes for UUCP Version 1.2, written by Will Rose.

     This package is intended for installation by inexperienced users.  If
you can't install it, please email cwr@pnet01.cts.com with the problem, and
I'll firstly try and help, and secondly try and fix it in the next release.

Initial installation.

     The simplest installation process assumes that you have not run UUCP
on your system before, and that you wish to bring up a standard version.
It assumes that the package is in its original form of twelve uuencoded
messages.  If the numbering has held good, message three should be the dial
package.  If in doubt, check the 'begin' line which should include '3.shar.Z'.

     Unpacking is a question of uudecoding, uncompressing and unsharring
each messages.  Some messages contain documents, and some code.  Files
that have the ending .sh after unpacking are shell scripts.

     The initial installation process goes as follows:

     Make two directories on your system, one for the dial package and one for
the rest of the package.  In this example, they are referred to as src/uucp
and src/dial, for convenience.  Move the dial mesage to src/dial and unpack it,
and then unpack the rest of the messages in src/uucp.  You will probably want
to keep original copies of the messages around as backup, but the .Z files and
shar files can be removed after they have been unpacked.  You may also want to
unpack the documentation, messages 1 and 2, in another directory again, and
also the patch message, message 11, which contains patches to other programs
to help them work with UUCP, but this is not essential.

     If you are running a Motorola processor, or are not using ACK, you will
need to edit the Makefiles and change the object file type.  (The files are set
up initially for PC Minix 1.5.10 and ACK.)  If you are using bcc, then set the
compiler define _BCC in the Makefiles in both the uucp and dial directories.
Bcc cannot pass structures as arguments to functions, so the standard dial(3)
interface has to be changed to pass a pointer to the CALL structure.

     Rename 'Make.dial' to 'Makefile', and type 'make' in the dial directory.
This will build a library called libmodemcap.a; on an XT, it takes a minute
or two.  Move the library to /usr/lib, and copy dial.h to src/uucp.

     Switch to the src/uucp directory.

     UUCP expects to find sh in /bin, cp, mv, mail and mkdir in /usr/bin, and
rmail and lmail in /usr/local/bin.  If you've put these programs somewhere
else, edit uucp.h accordingly.  (If you aren't using lmail or rmail, obviously
their paths don't matter).

     If you are using umail or wmail as mailers, you may want recompile them
with the replacement source files that you will find in patch.shar.  They will
then work more smoothly with this (or any other) UUCP.

     If you are using wnews, then you may want to patch and recompile this as
well.  The patches firstly allow UUCP and inews to use the same local system
name file format, secondly ensure that SIGHUP is ignored in rnews, and thirdly
allow the scratch file path and uncompress program to be redefined in wnews.h.
(UUCP can use a name file written by the standard WNEWS, but not vice-versa.)

     The file 'times.msg' deals with a kernel patch for the PC Minix times(2)
call; without it, the times(2) call always returns zero, but all this means
is that file transfers using the 'f' and 't' protcols are shown in the SYSLOG
as taking zero time.

     The UUCP conversation-level protocol normally terminates messages with
'\0'.  If you are on a net that doesn't permit nulls, redefine EFRAME in
uucico.h to '\n'.

     If you are using a machine with more than 500K of memory available to
processes, you could try removing the #define NOUUXQT from uucico.h.  This
will allow uucico to exec uuxqt on completion of data transfers, which is
a lot more convenient than running it separately.  However, if uuxqt hasn't
the memory to exec the programs it needs to run itself (eg. rmail), then
it will delete the command file and its associated data files anyway, and
you will lose your data with nothing to show for it.  (A typical series of
chained programs, starting from uuxqt, might be: uuxqt -> rmail -> sh -> uux.
Clearly a lot of memory is used even without uucico.)

     Anything that might need to be redefined has been put in one or another
of the header files - uucp.h covers the whole package, and uucico.h and cu.h
cover their specific binaries.  Some sections of the code are #defined out,
but that's for convenience in porting/testing.

     Now type 'make': the build process takes about 90 minutes on a 10MHz XT.
If there are no obvious errors, become root and type 'make Install'.  Check
this script before you run it: it puts the generally-available UUCP commands
in /usr/local/bin, which may not match your system set-up.  (Restricting
/usr/bin to the standard Minix distribution commands makes updating easier).
Install takes a couple of minutes to make all the directories, copy the files
over, and set them to the correct permissions.

     Edit /etc/password to give uucp, and preferably uucpadm, a login.  A
sample password file entry is in the file 'Samples'; this file also contains
other typical files and directory permissions.  The uucp and nuucp logins
run uucico as a shell, and thus are unsuitable for humans; they may or may
not be password protected.  The uucpadm login has the same uid and gid as
uucp, but invokes the standard shell, so that an administrator can act as
uucp while tidying up, removing dead files and so on.  The uucpadm login
should either be password protected, or have a null password so that it
can be accessed only via su. (The entry for uucpadm in /etc/passwd should
come after all uucp login entries.  Uucpadm will then have a username of
uucp; to read uucpadm's mail, call mail with a defined mailbox file).

     Edit /usr/lib/uucp/L.sys to include the names and phone numbers of
the sites you wish to contact.  Include one local BBS which doesn't run
UUCP, for testing.

Initial tests - uucheck, uulog, uustat, uusub, uuschk, uupick, uuto.

     The file 'Samples' contains a small UUCP LOGFILE and SYSLOG and a
uuencoded R_stat, L_stat, R_sub and L_sub, as examples of the sort of
databases that UUCP produces.  They are included to allow you to test the
local functioning of the suite, before testing its on-line operation.
Since on-line operation will produce new data files, you can skip this
step if you wish.  To use the files, uudecode the '.uue' files and copy:

     LOGFILE to /usr/spool/uucp/LOGFILE
     SYSLOG to /usr/spool/uucp/SYSLOG
     R_stat to /usr/lib/uucp/R_stat
     R_sub to /usr/lib/uucp/R_sub
     L_stat to /usr/lib/uucp/L_stat
     L_sub to /usr/lib/uucp/L_sub

     The new files should be chowned to uucp.  Note that since you probably
aren't cwr, options which search the data files for the name of the current
user by default will say nothing.  (You could always make a temporary login
with uid 101 and su to it for testing).

     If you run uucheck, it will show that a number of files are missing.
These files should be irrelevant, being either inessential or generated by
UUCP itself.  If uucheck marks a missing file as 'essential', however, you
should investigate and find out why.  This message may indicate a real problem,
but uucheck is fairly dumb.  It's a good starting place for checking out the
UUCP suite, but with experience you can do better.

     Now run uulog, and you should get a display of the LOGFILE.  You can
also try out the various uulog options from the man page.  The Doc file
man1c contains the UUCP man pages in Minix helpfile format; if you are using
the standard Minix man(1), then just copy man1c to /usr/man and enter
'man 1c' to build the index.

     Uustat -s penny should give a summary of jobs for penny (a remote site)
and uustat -m penny should give a summary of penny's traffic.  If you su to
uucpadm and run uustat -c 1 the summaries should be zeroed out, ready for
uucp and uucico to start reloading them with your own jobs; or you can
delete R_stat and L_stat, and touch the files to re-enable accounting.

     Uusub -l should give you a summary of connection statistics, and uusub -r
a summary of traffic statistics.  Su to root or uucpadm, and run uusub -f to
clear out the old statistics; to rebuild R_sub and L_sub from the current
LOGFILE and SYSLOG, run uusub (without options) as root or uucpadm.  Since
you will be dealing with a different set of sites, check the uusub -a and -d
options in the man pages and run them as necessary.

     Uupick and uuto use a complex directory structure based on PICKDIR.  The
easiest way of initialising this is to su to uucpadm, so that the directories
will have the right group and owner, and enter 'uuto file your_site!your_name'.
This copies 'file' to '/usr/spool/uucppublic/receive/your_name/your_site/file',
creating the directories as necessary.  To allow general use, these directories
are made with permissions 0777.  For security, you may wish to change them to
0755; the owner and group should be left as uucp.mail.

     Revert to your own account, and enter 'uupick'.  This should ask if you
wish to retrieve the whole directory 'your_site'; answer 'n', and it should
ask what is to be done with the original file, 'file'.  Enter 'd' to delete
it or 'm' to move it to your current directory.  (If you are collecting files
for uucpadm, you will need to use uupick's -u option).  Uupick uses 'mv', which
overwrites local files unless their protection bits are set, so be careful.
If there are problems with uupick and uuto, the first place to look is file
and directory permissions.  Try creating the appropriate directories by
hand, with permissions 0777, and moving files between them and a temp directory
also with 0777 permissions.  Then reduce permissions until something breaks.

     If you have doubts about any of the non-ASCII data files (R_stat etc.),
look at the man page for uuschk, and run it with the appropriate options to
view the problematic file(s) directly.

Test callout - cu.

     The next step is to test the serial port, the modem, and the L.sys and
L-devices files.  This is done with cu, (CallUnix), which is an extremely
simple (in fact rudimentary) terminal program.  However, it uses several of
the UUCP data files, such as the L.sys and L-devices files and the modemcap
database.  If cu works, then talking to any UUCP site should just be a matter
of finding a log-on script.  It is because cu is so useful for debugging that
it is included here; for general use, Kermit is a much better program.

     Check that you have no getty on your dial-out port, and that there is
an L.sys entry for a local BBS (use the current entry for zn9 as a pattern).
Check that L-devices has an entry for the modem port (patterned on the ACU
entry in the current L-devices).  Then (if zn9 is in fact the BBS) try the
command 'cu zn9'.  You should hear the modem dialling out and connecting.
Once you are connected to the remote, enter <CR> and then  '~'.  There is
a certain art to this - if you get it right, you should get a prompt of the
form '[your_site]'.  Enter the command '.'<CR> and after a pause cu will
hang up the modem and exit.  To silence the modem speaker for future dialling
(assuming a Hayes modem), edit the /etc/modemcap file and replace 'M1' in
the 'is' string with 'M0'.

     Success means that most of the UUCP system works.  If things go wrong,
or you have to switch off the modem to hang up, check the /usr/spool/uucp
directory for any files whose names start with LCK.  These stop multiple
accesses to ports (and sites) by programs such as cu, uucp, Kermit, and so
on.  Delete them all before you continue; you may find the shell script uulck
useful here.  You may also find it helpful to try to talk to the modem with
term, or Kermit, and see if you can get any response from it at all.  The
Hayes command ATI returns a 3-digit number (supposedly the revision level)
which is useful for checking that you can actually reach the modem.  ATZ
usually returns the modem to a default state.

     Cu is also handy as a way of testing the initial log-on script needed
to access a site; you can run it with 'cu site | tee buffer' and have a
record of your conversation with 'site' stored in the file 'buffer'.

     In some circumstances cu takes some default settings from the current
terminal.  It may be worth running 'stty default' before running cu, just
to make sure everything is standard.

Test file transfer - uucp and uucico.

     The next test is to call out and try to transfer files.  You will need
a remote site that accepts anonymous uucp logins, or anyway a login from your
specific machine.  Then edit L.sys to include a chat script such as that shown
for osu-cis, su to root or uucpadm, and try '/usr/lib/uucico -x12 -s sysname'.
This should poll the remote site, and put an enormous amount of debugging
output onto the screen and into the LOGFILE.  You can change the maximum amount
of detail by commenting out '#define VERBOSE" in uucico.h and recompiling; this
stops the protocol drivers writing the contents of individual packets into the
LOGFILE.  Don't use -x12 with VERBOSE if you expect any file transfers to take
place; the LOGFILE will then probably become big enough to crash your system.
Try -x6 instead, which still gives a lot of output.

     Given that you can poll a remote site, you can expect file transfers
to work; the 'g' protocol is universal and standard among UUCP installations.
Further debugging is usually a matter of getting the chat script right for
logging onto a particular site, and dealing with lockfiles and communication
failures.  UUCP is essentially a spooling system, so errors may not become
apparent until some time after a command has been entered, which doesn't make
debugging any easier.

     One particularly annoying problem is that of time-out in the log-in
script.  If you are calling with debugging at -x12 it may take too long
for the local system to write debugging information into the log file.
The remote then times out, having received no reply within its time limit
(typically 30-50 seconds).  The cure is to run with a lower level of debugging,
which doesn't help with solving any other problems that there may be.

     Once the system is working on a straight dial-out or dial-in port, you
can add a uugetty to permit dial-in and dial-out on the same port.  The Minix
uugetty has had a mixed history, and there may be problems bringing it up on
your system; which is why initial checking is best done without it.

Testing uux and uuxqt.

     The first test of uux is probably:

     cd /tmp ; uux !ls -l /tmp \>outfile ; /usr/lib/uucp/uuxqt

Then wait for disk activity to die away, and try:

     cat outfile ; uulog ; mail

This should give you firstly a listing of your /tmp directory, secondly
various logfile entries that cover the uux/uuqt/uucp tasks, and thirdly a
message about your command's output status (which should be 0).  If it doesn't,
check that uucp has write permission in the /tmp directory, and that the L-cmds
file includes 'ls' and 'rmail'.  If these checks don't cure the problem, run
uux and see if it generates a reasonable command file, edit the command file
if necessary, and then run 'uuxqt -x12' and see what it actually does with the
file you wrote.  If you are linked to another site for mail or news you may
have to change the GOODREP define in uucp.h and recompile uuxqt, to get the
required response to Z entries in command files.  (See the uuxqt man page).

Administration.

     UUCP itself produces a lot of miscellanous files to clutter up its
directories, never mind the files that end up there because of transfer
failures and other glitches, and if you are running news and mail the various
logfiles also grow rapidly.  The system needs active administration to keep
this junk to a manageable level; the amount of administration necessary will
obviously depend on the amount of traffic.  This package includes three shell
scripts, uudemon.hr, uudemon.day, and uudemon.wk which can be run by cron to
automate some maintenance tasks.  To see what they do, just read them; they
can be used as a basis for you to build something that fits your particular
system's needs.  Another simple but useful shell script is uudir, which shows
you just what sort of a state UUCP has got its directories into.

     The two scripts uupoll and uutry are intended to simplify calling and
polling sites; their operation is described in their headers.  They assume
that the modem port is tty1, so you may need to edit them before use.

     As set up, UUCP has minimal security; the FOREIGN file, for instance,
is not used.  You may want to read the man pages, or any other source
of UUCP information, to decide just what level of security you need.  Two
very good references are the Nutshell Handbooks "Using UUCP and Usenet"
and "Managing UUCP and Usenet".  The Waite Group's "UNIX Communications"
and Kochan and Woods "UNIX networking" are also useful, if more limited.
There is a general discussion on UUCP security in the file 'protection.doc'.

Rebuilding UUCP.

     If you rebuild the system, you can use 'make install' to reinstall it.
The data files R_stat, L_stat etc. will not be overwritten. 

Removing UUCP.

     'make remove' removes the entire UUCP suite and all its directories,
apart from the source directory and the man pages.

