Basic setup and installation instructions

Step 0:  familiarize yourself with the territory

The installation of uupc requires that you understand a fair bit about
how uucp communications work, about how uucp- and Internet-based electronic
mail works, about the Domain Name System and the uucp maps, and about how
modems work.  Quite simply, this is not a job for someone who is a complete
novice concerning these subjects... it's not a "plug-and-play" task.

If you have not done a uucp installation on some other system (Unix, most
likely), or have not used Internet-style electronic mail systems for at
least a few months, I would strongly recommend that you do some additional
reading before starting the installation of uupc.  Two good handbooks...
oriented towards the email user, and the email administrator respectively,
are:

TITLE: Using UUCP and USENET
AUTHOR: Todino, Grace
AUTHOR: Dougherty, Dale
SUBJECT: Introduction
PUBLISHER: O'Reilly & Associates, Inc.
DATE: 1990
PAGES: 210
ISBN: 0-937175-10-2
APPROX_COST: 21.95
KEYWORDS: Nutshell Handbook
SUGGESTED_BY: Mitch Wright <mitch@hq.af.mil>
SUPPLIERS
	E-mail: ... uunet!ora!nuts
	Phone#: 1-800-338-NUTS

TITLE: Managing UUCP and USENET
AUTHOR: O'Reilly, Tim
AUTHOR: Todino, Grace
SUBJECT: Introduction
PUBLISHER: O'Reilly & Associates, Inc.
DATE: 1990
PAGES: 289
ISBN: 0-937175-48-X
APPROX_COST: 24.95
KEYWORDS: Nutshell Handbook
SUGGESTED_BY: Mitch Wright <mitch@hq.af.mil>
SUPPLIERS
	E-mail: ... uunet!ora!nuts
	Phone#: 1-800-338-NUTS

You may find these books at a good computer-oriented bookstore in your
area... if not, you can order them directly from the publisher.  
[Disclaimer:  I haven't read them myself... I learned about uucp the hard
way, before these books were available.  They have a very good reputation
among people on USENET, and I recommend them on that basis.]

So... borrow or buy copies, read them, and understand them.  Then, go on
to the next section.  I'll wait.

...

Ok.  On to the next topic.

Another good source of information is the network or system or electronic
mail administrator at a local well-connected USENET site.  Many of these
peoples hack networking code for the love of it, as well as doing it for
pay.  They are frequently willing to share their knowledge, if approached
properly.  Bribes help... chocolate in exotic forms, and an offer of a good
Szechuan dinner are legitimate tender.

Another note concerning system administrators.  A friendly sysadmin may be
willing to provide you with a uucp connection (a "mail feed") without
charge, from a system under her or his administrative control.  The chances
of this occurring vary quite a bit from case to case.  If you can convince
a sysadmin that you are a friendly, responsible individual (or small company)
which understands the ropes, is willing to be a "good network neighbor",
won't cause problems, etc. then you may very well be able to establish a
useful netmail connection at little or no cost.  If you come across as a
demanding, annoying, trouble-making bozo, you'll get the cold shoulder, and
will end up with no alternative but to subscribe to a commercial service for
your netmail connection... this will cost you hard cash.  Support your local
sysadmin... and, once you've earned her trust, do NOT abuse it.  You do
NOT want to develop a bad reputation on The Net... it can stick like glue.

Step 1: What you'll need

To get hooked up to the outside world via uupc, you'll need a number of
things:  some hardware, some software, some paperware.

Hardware:

*  A Mac running System 4.2 or later (NOTE:  I haven't tested this
software with anything prior to 6.0.3;  earlier versions of the System should
work, but I can't promise this).

*  A modem (preferably one which understands the Hayes command-set.  Speeds of
2400 bits/second (V.22bis) or faster are recommended, especially if you plan
to send or receive a lot of mail.  High-speed modems (V.32, V.32bis, Telebit
PEP) are supported.  Talk to the administrator of the system(s) with which
you plan to communicate, and find out what sorts of modems they support...
then use that to influence your purchase decision, if any.

*  A Mac-to-modem cable.  A standard "Mac Plus/SE/II to Hayes-compatible modem"
cable is appropriate in most cases.  If you wish to use a "hardware handshaking"
cable, make SURE that it connects the Mac's handshake output to DTR as well
as to RTS... if it doesn't, uupc won't be able to hang up the phone properly.

Software:

*  The uupc 3.1 (or later) software distribution.  This includes the uupc
program itself, the pcmail program, and some auxiliary configuration and
data files.

*  ResEdit.  You'll need it to customize the configuration file.  No fancy
ResEdit editors or pickers are required.  Any version of ResEdit which is
new enough, old enough, or tweaked enough to run on your Mac should do the
job.

*  A terminal emulator program of some sort (recommended but not essential).
It'll help you in the process of configuring your modem, and figuring out
your chat scripts.

*  An alternate mail reading/writing program (optional) (shameless plug).
The "pcmail" program which comes with uupc is a bare-bones shell... it's
functional, but not terribly convenient or pretty.  You may wish to use one
which is better suited to the Mac environment.  Send email to
"dplatt@snulbug.mtview.ca.us" for information about Fernmail, a shareware
mail program which is compatible with uupc.  'Nuff said.  Send email to 
"sdorner@qualcomm.com" to get information about Eudora, which is also 
compatible with uupc.

Paperware:

*  A uucp "node name"... a shorthand name by which your system can be
distingished from every other uucp system in the universe.  Must consist of
lower-case letters, and digits, only.  Its first seven characters must be
unique from any other uucp system name in use... your nodename can be longer
than seven characters, but only the first seven count.  "All the good names
are taken", so you'll have to be inventive, or very bland (there are lots
of combinations of randomly-chosen letters and digits which aren't in use,
but they're _boring_).

Please DO NOT simply pick an interesting-sounding name at random, and start
using it without further checking.  If you choose a name which is already
in use elsewhere, and which has been "registered" to the system which got
the name first, all sorts of bad things will happen.  You'll have trouble
getting mail delivered properly, you'll probably receive mail which wasn't
intended for you, you may end up being treated as an "intermediate node" for
torrents of third-party mail that you can't handle properly, and people will
yell at you a lot.  Don't do this, please.  Instead, make sure that the name
you want to use isn't in use.

How to check?  Well, the "bible" of uucp node-names is the set of USENET
articles which are posted to the comp.mail.maps newsgroup on an ongoing
basis.  Check with that friendly system adminstrator I mentioned above...
or with any of the commercial uucp hookup services listed in the
"Finding somebody to talk to" document... and
ask them to run a map-search for you.  If the name you want isn't in use,
you (or another sysadmin) can mail off a map-file to your regional map
coordinator, and thus reserve the name for your own use.  Please DO
register your name... if you don't, some innocent party may start using it
in the future, and all of the bad things I mentioned above will happen.

*  A site to connect with.  You'll need to establish communications with at
least one existing uucp site... the more well-connected the better.  See the
"Finding somebody to talk do" documentation for some suggestions as to
how you might find such a site.
 
*  A domain name.  Strongly recommended, but not required.  If your uucp 
neighbor is on the Internet, and is willing to act as an "MX forwarder" 
for you, you'd probably find it very much worthwhile to register your Mac 
as having an officially-supported Internet domain name.  If your neighbor 
is a commercial Internet service provider, they can almost certainly help 
you with the paperwork necessary to register yourself.  Registration in 
the .us domain is free.

*  The details on how to connect with your uucp neighbor.  You'll need to
know their modem phone number, the communications speed, and the sequence
of steps required to log onto their system.


Step 2: Setting up the folders

uupc uses a set of several folders, in which it stores various files
needed for its operation.  For the sake of convenience, these folders
are usually stored within one central organizing folder, on a single hard
disk.  This isn't a hard requirement;  you may place these folders anywhere
on your hard disk(s) that you wish, as long as you tell uupc where they are.
[Note... you cannot use System 7 Finder aliases with uucp, as it doesn't
know how to resolve them.]

You'll need to tell uupc where each of these folders is, by editing a
'STR ' resource in uupc's settings file.  In each 'STR ' resource,
you'll place the complete pathname of the folder.  For example, the
default configuration file suggests the following layout:

     name         typical value              meaning

     HOME         My disk:uucp:home:jones    Your personal mail files
     MAILDIR      My disk:uucp:mail          incoming mail
     CONFDIR      My disk:uucp:config        config files
     TEMPDIR      My disk:uucp:tmp           temp files
     SPOOLDIR     My disk:uucp:spool         uucp spool files
     PUBDIR       My disk:uucp:public        anybody-can-read

In each of these 'STR ' resources, you'll need to replace the text "My disk"
with the name of the Macintosh disk on which you wish these folders to be
placed.

You don't actually have to create each of these folders yourself... if you
set up the UUPC Settings file correctly, uupc will create the folders
the first time it needs to access them.

So... decide where you want your uucp folder hierarchy to be placed.  Copy
the "Sample UUPC Settings" file from the uupc distribution, and change its
name to "UUPC Settings".  Edit the resources in the UUPC Settings file
to match the directory hierarchy you've decided upon.

Step 3: Setting up the user configuration

You'll need to edit some of the other 'STR ' resources in the UUPC Settings
file, to configure uupc with the information it will need to operate.

     name             typical value       meaning

     MAILBOX          mbox                user's mailbox file
     NAME             Fred Jones          your real name
     USERNAME         jones               your username
     NODENAME         mynode              uucp site name
     DOMAIN           mynode.uucp         domain-style site name
     MAILSERVICE      hisnode             primary uucp neighbor
     SPEED            2400                default port speed
     TIMEDIFF         -0800 (PST)         timezone
     DLSTIMEDIFF      -0700 (PDT)         timezone during Daylight Savings
                                          Time (OPTIONAL!)
     MAILCOPY         mail.sent           copy of outbound mail
     ALIAS            Alias               name of alias file in your
                                          home directory
     SEQUENCEFILE     SEQF                name of sequence file
	 SLEEPTIME        5                   number of minutes between
	                                      queue runs in automatic mode
	 PASSWORD         LemmeIn             password that other uucp sites
	                                      should use when calling you
     ROUTEVIA         other,bill          comma-separated list of sites to
	                                      which mail can be sent directly.
	                                      (OPTIONAL!)
	 MBOX                                 Multi-user mailbox identifier
	                                      (OPTIONAL!  Normally blank or
	                                      not present!)

Your USERNAME should match the last level of the HOME folder path (e.g.
"jones" matches the last part of "My disk:home:jones").  MAILSERVICE
should be the name of your primary uucp neighbor... the site to which
all outgoing mail should be sent (except for sites on the ROUTEVIA list;
mail for those sites is sent directly to them).

The ROUTEVIA resource has been extended (effective with uupc 3.1) to 
permit domain-addressed mail to be routed to specific uucp neighbor 
sites.  See the "Advanced setup notes" document for details.  If the 
ROUTEVIA resource is not present, all outbound mail is sent via the 
MAILSERVICE neighbor;  all other neighbors will be receive-only.

uupc 3.1 can be configured to be aware of Daylight Savings Time.  See the 
"Advanced setup notes" document for details.

Now... either place the UUPC Settings file in the same folder as the uupc
and pcmail applications, or drop it into your System folder.

Step 4:  Trial run

Double-click on the uupc 3.0 application icon. uupc should start up, open a
window, and report that it's going idle. As soon as it does, select Quit
from the File menu.

You should find that uupc has created several of the folders mentioned in
your UUPC Settings file.  In particular, the directory named in your CONFDIR
string should have been created in the correct place.  If it wasn't, or if
any I/O error messages occurred when you ran uupc 3.0, go back and re-check
your UUPC Settings file.

Step 5:  Installing your Systems and Schedule files.

Copy the sample Systems file into the configuration folder, and change its
name to "Systems".  This is the file which will identify the systems that
your Mac can connect with via uucp, the times at which such connections
are permitted to be made, the modem speed and setup information required,
and the set of prompts and commands that your Mac must exchange with each
neighboring system in order to access that system's uucp software.

Edit the Systems file, based on the information you collected way back up
in Step 1.  The format of the Systems file is described in the
"UUPC 3.0 Systems file format" document.  Be sure to comment out any
entries that you don't plan on using (for example, all of the sample
ones!)

You may also wish to copy the sample Schedule file into the configuration
folder and change its name to "Schedule".  This file specifies the times
at which your system should place calls to ("poll") other uucp systems
to check for inbound mail.

Step 6:  Placing a call

Double-click on the uupc 3.0 application icon. uupc should start up, open a
window, and report that it's going idle. Pull down the Call menu, but
don't select anything.  You should see, at the bottom of this menu, a list
of each of the systems you added to the Systems file.

Select the name of your primary uucp neighbor from the Call menu.  uupc
will initiate a call.  If everything goes well, uupc will dial the neighbor's
phone number on your modem, connect to your neighbor's modem, log in, go
through uucp startup, exchange a couple of "I have nothing for you, do you
have something for me" messages, and then hang up.

Step 7:  Sending mail

Double-click on the pcmail icon.  A dialog box will appear, giving
you the chance to select input and output files (don't bother, this
time) and to enter a command line.  The command line will contain the
string "pcmail 3.0".  Click on the end of the command line, and edit it
so that it reads

      "pcmail 3.0" MAILSERVICE!NODENAME!USERNAME

but instead of typing any of the capitalized words, type in the actual
value from your configuration file.  For example, if you were using the
sample values shown above (NOT a good idea!) you'd type

      "pcmail 3.0" hisnode!mynode!jones

Click the OK button.  A normal window will appear.  Type in the following
text (removing the indentations on each line so that each line begins
in column 1):

       Subject: This message should come back to me
		
       This is a test.  If it works correctly, this message should go
       out to my mail relay site, and be sent right back here.

Note that you WILL NOT BE ABLE to edit any line of the message after you
press return!

When you've entered the message, type control-D.  pcmail will queue the
message for delivery, and ask you to press Return to exit.  Do so.

Double-click on the uupc icon.  From the Call menu, select "Any site with
jobs pending".  uupc should initiate a call to your primary neighbor, and
deliver the outbound mail (two files will be transmitted).

Wait a few minutes to let your neighbor process the mail and prepare to
send it back to you. Sometimes 10 seconds is enough, sometimes a half-hour
or more is required.  Initiate a call to your neighbor by selecting its
name from the Call menu.  uupc should place a call, and should receive the
mail (two files will be received).  After disconnecting, uupc should
deliver the mail to your mailbox... you should see an "rmail" command
being executed.

Double-click on the pcmail icon again.  When the options dialog appears,
click OK.  pcmail should show you the header line of your mail (as message
number zero).  Type "p" to print the message, then "d" to delete it.
Finally, type "q" to quit, and hit return to exit the program.  Your
uupc system is now up and functioning!

Step 8:  Troubleshooting

Probably, things won't go this smoothly.  To figure out why things aren't
working, it's usually best to try placing a call in debugging mode, watch the
messages as they scroll by, and try to figure out where things are going awry.

To do this, select the "Call system" command from the File menu.  In the
resulting dialog box, type the name of the system you want to call, and
set the debug level to a value between 1 and 9 (2 and 5 are good values to
start with).  Then, watch the window and make a note of how far uupc
gets... or doesn't get... in placing its call.

See the "Troubleshooting" document for ideas on how to go about tracing
down the cause of the problem.