	Sketchy documentation for beta test gnuucp

	John Gilmore
	8 April 1989

This directory contains source for gnuucp, a free program that
implements the Unix uucp file transfer protocol on Unix systems and
on a variety of non-Unix systems.

Gnuucp is not derived from any AT&T or Unix code.  It is a further
development of the "uuslave" program, which was certified by AT&T to be
unlicensed.  (See the file ATT.CERTIFICATION in this directory.)
Gnuucp can be freely given to anyone, whether they have a Unix license
or not.  Gnuucp is copyright by the Free Software Foundation and can
only be distributed under the rules of the "GNU General Public
License".  Basically, you can give it to anyone, for free or for money,
but you have to provide source code, and the recipients must be able to
redistribute it on the same terms.

Currently gnuucp consists of these source files:

	gnuuio.c	system program for moving files; high level protocol
	gio.c		"g" packet protocol implementation for gnuuio
	uumisc.c	miscellaneous subroutines
	locking.c	subroutines for multitask interlocking
	uucp.c		user command to queue file transfers
	uux.c		user command to queue command transfers
	uuq.c		user command to list and delete queue entries
	uusnap.c	user command to summarize queue and current status
	uuname.c	user command to list known uucp site names
	uuxqt.c		system program to run received commands (e.g. rmail)
	rmail.c		system program to handle email from Unix machines
	sysdep.c	this is a link to, or copy of, a file from below.

The system dependent part of gnuucp comes in a different file for each
supported system type.  You link or copy the right sysdep.foo file
to "sysdep.c" before compiling.  Pick one of these, or make your own:

	sysdep.unix	BSD and Sys V Unix
	sysdep.msdos	MSDOS (MSC and Turbo C)
	sysdep.st	Atari ST
	sysdep.cpm	CP/M-80
	sysdep.amiga	Commodore Amiga
	sysdep.vms	DEC VMS

Some of these ports have not been tested in a while, and will need work.

There are also some header files:

	uucp.h		General uucp information and configuration
	sysdep.h	Definitions of the routines in sysdep.c
	includes.h	System include files, #ifdef'd for each system

There are two more files for MSDOS systems, comport.h and comport.asm, which
contain an interrupt-driven routine for handling the serial port.

Note that on brain damaged file systems, the file names may be truncated.


	Compiling gnuucp on a supported system

Pick which system you are on, and copy or link sysdep.whatever to
sysdep.c.

Edit the Makefile to change the DEFS variable for the options you
want.  First, the system you're compiling for:

	-DBSD	Berkeley Unix
	-DSYSV	Unix System V
	-DCPM	CP/M-80
	-DMSDOS	Mess-Dos
	-DST	Atari ST
	-DVMS
	-DAMIGA

It also has some other options:

	-DSUBDIR (Unix only) Keep queue files in subdirectories like 4.2BSD
	-DMSC	(MSDOS only) Microsoft C
	-DTURBO	(MSDOS only) Turbo C

For msdos, you have to assemble comport.asm and link with it too.
Two MSDOS makefiles are included.
VMS users see README.VMS and VMS.COM.


	Running gnuucp

Gnuucp can receive phone calls as well as making phone calls.  Note
that the program in gnuucp that does all the phone work is called
"gnuuio"; it corresponds to the Unix program "uucico".

When receiving calls, one way is designed for small micros
and such; gnuuio will sit and wait for someone to call on the modem,
and will then prompt them with "login: " and "Password:" and check the
answers.  When another machine calls in and supplies the right login
and password, it will run the uucp protocol to talk to that machine.
Then it hangs up the phone and goes back to listening for another call.
You get this mode by giving gnuuio an argument, which is the device
name of the serial port that it should listen on.

The other mode is for larger machines or BBS's where there already exist
programs to listen for callers on the phones.  When such a program
decides that the caller is a uucp machine, it can run gnuuio with no
arguments, the same way Unix runs uucico.  Gnuuio will immediately
begin the uucp protocol negotiations on its standard input.  When it is
done transferring files, it will hang up the phone and exit.  In this
role, it acts much like the Unix "uucico" program which implements
uucp, and which is called when another machine logs in to your machine
with a login like "uucp" or "Uhoptoad".

Gnuuio can also be run in "master" mode, where it will call out on an
autodial modem.  If you run "gnuuio -s", it will call any system that
there is work queued up for.  If you run "gnuuio -ssystem" it will
only call one system.  You can force a call to a system, even if it
is not the right time of day for it, by using "-S" rather than "-s".

The programs for queueing up transfers for other systems need more
work.  uux.c is in fairly good shape (it works on Unix and should
work soon on MSDOS), but uucp.c needs some work.  These programs
just do things on your local machine, leaving files behind for gnuuio
to notice.  If run without the "-r" switch, and if your gnuucp.ctl
file gives the pathname to run gnuuio by, these programs will automatically
run gnuuio when they finish.

Except when listening for logins, gnuuio will change directories to a
standard place (/usr/spool/uucp on Unix systems; changeable in the
gnuucp.ctl file) and will leave its debugging logs in "gnuucp.log" in
that directory.

A control file, (/usr/lib/uucp/gnuucp.ctl or /etc/uucp/gnuucp.ctl on
Unix systems; configurable in your "sysdep" file) is a text file
containing parameters like your system name, the name of the gnuucp
spool directory, the default debugging level, a list of which serial
ports exist, what baud rates work on them, and what kind of dialers
they have, etc.  You will need to edit it.  This file allows users to
change a bunch of common parameters without having to recompile from
source.  One of the lines in gnuucp.ctl gives the name of the
"sysfile".  Gnuucp uses standard Unix "L.sys" (or "System") files,
which supply the system names, phone numbers, and login sequences for
neighboring machines.

Gnuucp programs take a -xN option, where N is a number, to control the amount
of debugging output produced.  Specifying -x5, for example, gives you
all the output for levels 0 through 5.

	-1	no output (default)
	0	error messages and a copy of the LOGFILE output
	1	login trace -- errors only
	2	login trace -- full trace
	3	file transfer commands -- errors only
	4	file transfer commands -- full trace
	5	packets -- errors only
	6	packets -- full trace
	7	file name munging trace
	8	file directory scanning trace
	9	every byte that goes over the serial port

For hints on debugging and porting gnuucp, see the file PORTING.

Copyright 1990 John Gilmore; distribution via GNU General Public License.
{sun,pacbell,uunet,pyramid,amdahl}!hoptoad!gnu               gnu@toad.com
