INSTALLING HERMES
=================

I recommend that you attempt to read this file from offset 0 to
end-of-file ("cover to cover" just doesn't make sense here, does it?)
before you install HERMES on your system. The file needs more work,
but it will tell you a couple of things you'll want to know.

**************************************************************************

   I INSIST THAT YOU READ THE FILE "COPYRITE.TXT" (IF YOU HAVEN'T
   ALREADY) BEFORE READING ANY FURTHER! YOU MAY NOT INSTALL AND USE
   HERMES WITHOUT READING AND ACCEPTING THE CONTENTS OF THAT FILE!

**************************************************************************

To install HERMES, you should have an empty hard disk partition
available (one of C: through P:). Installing HERMES on a
floppy-disk-only system might work if you only want to exchange e-mail,
but working with such a system will be frustrating at best. I recommend
5 MB for a mail-only system, and 10 MB or more if you also want to
access the world of Usenet news. You can also use of more than one
partition. Your system should have a real-time clock. If it doesn't,
you have to rememeber have to set the system time set every time you
use Hermes, or things will go terribly wrong.

You will need a shell or command-line interpreter (HUSH.TTP is a simple
but sufficient one) and an ASCII text editor (ME, TEMPUS, ELVIS, 
STEVIE ...). The editor must accept a file name on the commandline, 
and must be callable from any folder (that excludes WORDPLUS). GEM-based 
editors might spell trouble; for TEMPUS, a simple shell program called 
TED is provided. There is another shell programm called 7 that is useful
for using the 7UP editor; it should work with other GEM editors as well.

All examples in the text assume you have four users on your system
(named joe, postmaster, root and server) and two UUCP neighbours (named
heaven7 and cloud9), of which only heaven7 is allowed to call in.

This is actually a major pitfall! If you don't delete those "fake"
neighbours when defining your "real" neighbours, and then try to send
me a mail message (not THAT strange an idea, really, most probably you
WILL do that sooner or later), then HERMES will possibly forward that
mail into heaven7's spool directory; but since your system most probably
never exchanges data with heaven7, that mail will just sit there and
never get sent.

FOLDERS
-------

HERMES requires you to create quite a large number of directories. If
you install HERMES on a partition of its own, I recommend you follow a
UNIX-like style (okay, it's loosely modelled after UNIX System V
Release 4), shown here for the G: partition. (Oh yes, UNIX is a 
trademark of whoever owns it this week.) This is actually what the
prototype installation looks like; you will later see how things can
be moved around.

# The HERMES binaries go here:
G:\bin
#
# System configuration files:
G:\etc
#
# User files
G:\home
# Every user needs a home folder:
# Remember to clean this up when you install HERMES on your system!
G:\home\joe
G:\home\postmaster
G:\home\root
G:\home\server
#
# Temporary files:
G:\tmp
#
# Just about everything else that doesn't change all that often:
G:\usr
# Other binaries, your own shell scripts, and such
G:\usr\bin
# Stuff:
G:\usr\lib
# Mail routing information:
G:\usr\lib\mail
# News system configuration files:
G:\usr\lib\news
# On-line documentation goes here
G:\usr\man
# Program maunal pages
G:\usr\man\man1
# File format manual pages (in case you wonder: modelled after System V)
G:\usr\man\man4
# Miscellaneous manual pages
G:\usr\man\man5
# Files you want to share with the world:
G:\usr\public
#
# System files that change often:
G:\var
# Log files:
G:\var\adm
# Lock files
G:\var\lock
# Mailbox files (incoming mail for local users) go here
G:\var\mail
# Everything that comes and goes all by itself:
G:\var\spool
# All mail and news go here first:
G:\var\spool\mqueue
# The news system will install a tree of folders under here:
G:\var\spool\news
# Every UUCP neighbour needs a spool directory of its own:
# Remember to clean this up when you install HERMES on your system!
G:\var\spool\uucp
G:\var\spool\uucp\cloud9
G:\var\spool\uucp\heaven7
# Public folder for UUCP requests
G:\var\spool\uupublic
#

If HERMES has to share a partition with other software, you can keep
everything under a \HERMES folder. Although the rest of this document
assumes you have installed HERMES in the UNIX-like folder structure
outlined above, you can move things around to your heart's content. The
CONFIG.SYS file, discussed next, tells HERMES where everything else is.
If you don't quite get the hang of all the folders, don't worry. Maybe
you won't need all of them.

DOCUMENTATION FILES
-------------------

You'll see references to other documentation files written as
"pathalia(1)" or some such. That means "look at a file named
'pathalia' with any extension in the folder 'man1'". This somewhat
odd notation also has its root in the UNIX usage.

CONFIG.SYS
----------

This is the central configuration file that tells HERMES where to find
all the stuff it needs, and a lot of other things as well. It must be
placed in a folder called either \ETC, \HERMES, \HERMES\ETC, or
\MERCURY (for historical reasons, you guessed it), either on the 
current drive or on any drive from C: to P:. Under MiNT, the 
search will always begin on the "universal" drive, U:.

It is simple text file that can be created and maintained with a text
editor. It consists of lines in the following format (yes, it IS
historical):

0002 "cloud9" # Site name

i. e., a four-digit number, a value enclosed in double quotes, and an
optional comment after a '#' character. Comment-only lines are allowed,
as are blank lines. Every line has a NAME as well as a NUMBER. Instead
of giving the NUMBER, you can also give the NAME, in double quotes,
like this:

"SITENAME" "cloud9"

Both lines accomplish exactly the same thing.

Many of the lines are optional, and HERMES can sometimes find the
values of other lines by itself.

If there is an environment variable that is named like the
CONFIG.SYS line (i e, SITENAME), it silently overrides the CONFIG.SYS
line (!). If (and only if) values are read from the file (rather than
from the environment), they are checked for consistency (e. g. if files
and directories exist, etc). At this time, slashes are converted to
backslashes in file, program and folder names. If the drive letter is
given as '@' rather than 'A', etc., it will then be replaced by the
letter of the drive where CONFIG.SYS was found (this works in a
few other places as well). The prototype installation makes 
use of this feature. The following table lists the CONFIG.SYS lines
with their numbers, names, types, if they are mandatory or not, 
and a sample value. Types are explained after the table, as are 
the star marks after some of the lines.

   2 "SITENAME"     Str  1 "mysite"
   3 "ORGA"         Str  0 "Just my private little system"
   4 "DOMAIN"       Str  1 ".some.domain"
   5 "LOGDIR"       Dir  1 "G:\usr\adm"
   6 "POSTMASTER"   User 1 "postmaster"
   9 "PASSWD"       File 1 "G:\etc\passwd" *
  10 "REDIAL"       Num  1 "1"
  12 "ACTIVE"       File 1 "G:\usr\lib\news\active"
  13 "SYSFILE"      File 1 "G:\usr\lib\news\sys"
  14 "MAILQ"        Dir  1 "G:\usr\spool\mqueue"
  15 "HOSTS"        File 0 "G:\etc\hosts" *
  17 "RELAY"        Site 1 "cloud9"
  18 "NEWSDIR"      Dir  1 "G:\usr\spool\news"
  19 "DOMAINFILE"   File 1 "G:\etc\mydomain"
  20 "EDITOR"       Prog 1 "G:\bin\ted.ttp"
  21 "TEMP"         Dir  1 "G:\tmp"
  22 "PATHSFILE"    File 0 "G:\usr\lib\mail\paths"
  27 "SERVER"       User 0 "server"
  28 "SERVDIR"      Dir  0 "G:\usr\public"
 102 "STDALIAS"     File 0 "G:\usr\lib\mail\alias"
 103 "XHOSTS"       File 0 "G:\etc\xhosts" *
 107 "DOQUEUE"      Cmd  0 "G:\bin\hush.ttp G:\etc\doqueue.hsh"
 108 "PATH"         Path 1 "G:\bin;G:\usr\bin;C:\util"
 109 "LOGIN"        Cmd  0 "G:\bin\login.ttp -a"
 110 "ENVINIT"      File 0 "G:\etc\envinit"
 111 "TZ"           Str  1 "MET"
 112 "SPATHS"       File 0 "G:\usr\lib\mail\spaths"
 113 "MDBS"         File 0 "G:\usr\lib\mail\mdbs"
 114 "UUCPPUBLIC"   Dir  1 "G:\usr\spool\uupublic"
 115 "MAILMODE"     File 0 "G:\etc\mailmode" *
 117 "MANPATH"      Path 0 "G:\usr\man"
 118 "MIDILOGIN"    Cmd  0 "G:\bin\login.ttp -abMIDI"
 119 "LOCKDIR"      Dir  0 "G:\usr\lock"
 120 "SEQF"         File 0 "G:\etc\seqf"
 121 "MAILDIR"      Dir  1 "G:\usr\mail"
 122 "HISTORYFILE"  File 1 "G:\usr\spool\news\history"
 123 "NEWSDEFFILE"  File 0 "G:\usr\spool\news\news.def"
 124 "TZOFFSET"     Num  1 "-3600"

Check Types:
------------

Str: Can be any string value. No checks performed.

Dir: The name of an existing folder. The root folder (of any drive)
cannot be used (!).

File: The name of an existing file. If no folder is specified, HERMES
looks for the file in the folder where CONFIG.SYS resides. If the value
is not present, the name of the value will be used instead (e g if
CONFIG.SYS was found in G:\ETC, the assumed name of the password file
is G:\ETC\PASSWD). Thus, the lines marked with a star are redundant if
CONFIG.SYS is in G:\ETC.

Prog: The name of an executable file. If no folder and extension is
specified, and the PATH is already set at this point in the file (e g
by putting line 0108 before the line with the Prog value), the program
will be used on the path, with the extensions .TOS, .TTP, .PRG, and
.APP (in that order). If the value is not present, the name of the
value will be used instead (e g the editor will be used as "EDITOR.TOS"
etc. on the path).

Cmd: The name of an executable file, optionally followed by
command-line arguments. See Prog above. Warning: The '@' translation
will ONLY be applied to the name of the program, NOT to any arguments
that may follow!

User: The name of user in the PASSWD file (see below).

Num: An integer number, expressed in decimal.

Path: A list of existing folders, separated by either spaces, commas,
or semicolons.

Site: The name of a site in the XHOSTS file (see below).

"Mandatory" doesn't mean you have to put that line into the CONFIG.SYS
file, as long as HERMES can find the name of the file or program by
following the rules mentioned above.

EXPLANATION OF CONFIG.SYS VALUES

   2 "SITENAME"
      The so-called UUCP name of your system. It should consist of one
      to seven lower-case letters, decimal digits and hyphens, with
      a letter as the first and a letter or digit as the last character.
      These are rather strict rules. You'll be on the safe side of you
      adhere to them, but other names may work just as well. If possible,
      use a unique name for your site. Ask a local guru how to find out
      if your name is unique.

   3 "ORGA"
      An optional description of your organization (if any). You can
      also use a funny organization name if you like, but remember that
      jokes get stale over time.

   4 "DOMAIN"
      Your domain. The complete name of your site is formed by appending
      this value to the site name from line #2. Use ".uucp" if you
      don't have a domain (and ask the guru from line 2 to find out
      how to get one, because not having a real domain is acceptable
      only as a temporary solution).

   5 "LOGDIR"
      A folder where all the log files go. Look at them regularly, or at
      least delete them regularly, or they will take up all your disk
      space.

   6 "POSTMASTER"
      The name of the local user that gets all mail about mailing
      problems. You can use your own login name, but I recommend a
      separate account. The user named here receives all mail addressed
      to "MAILER-DAEMON", "news", "postmaster", "usenet", and "uucp",
      no matter what her login name is (although it is typically
      actually "postmaster").

   9 "PASSWD"
      The list of all local users. See passwd(4) for details. Remember to
      clean this up when you install HERMES on your system!

  10 "REDIAL"
      The number of times UUCICO will re-dial a number if the line is
      busy.

  12 "ACTIVE"
      The list of all newsgroup that you tolerate on your site. See
      active(4) for details.

  13 "SYSFILE"
      The list of all sites you will be sending news to, and what news.
      See sys(4) for details.

  14 "MAILQ"
      The folder where every mail (and news article) is put first.
      This folder is written to by MMAIL and UUCICO, and read from
      by RSMTP, RMAIL, and RNEWS.

  15 "HOSTS"
      This file is written from the XHOSTS file (see hosts(4)). If
      you don't use other UUCP software, don't keep a file names "HOSTS"
      in your configuration folder, and don't put this line in your
      CONFIG.SYS file.

  17 "RELAY"
      The neighbouring site that gets all the mail for sites that are
      not included in your PATHS or MDBS file (if any). If you don't
      name a relay host, such mail will fail. If you have only one
      neighbour, put its name here.

  18 "NEWSDIR"
      All news articles live in the folder tree that gets built here
      by RNEWS and NHM. Keep your hands off this folder (apart from
      maintaining the file EXPIRE.DEF that also lives there)!

  19 "DOMAINFILE"
      This is a text file that contains the names of all domains you're
      in, one per line, each including the leading period. This is
      absolutely necessary, even if you have only one domain.

  20 "EDITOR"
      Your favourite text editor. If you use TEMPUS, use the shell
      program TED that is part of the HERMES distribution.

  21 "TEMP"
      A folder for temporary files. Check regularly for forgotten
      files, or delete everything in it on a regular basis. See line 119,
      "LOCKDIR".

  22 "PATHSFILE"
      Mail route database, normally built by PATHALIA (in UNIX, this
      program is called "pathalias", but that's nine characters) from
      map data. See pathalia(1) for details.

  27 "SERVER"
      If you use the program FILESERV to implement a mail file server,
      you need this line to tell FILESERV to which local mailbox
      requests are mailed. Must be included in the PASSWD file.

  28 "SERVDIR"
      If you use FILESERV, the FILESERV.INF (see fileserv(1)) file
      lives here. Normally, you would put all the stuff the server
      can send out somewhere in this folder or sub-folders.

 102 "STDALIAS"
      A text file that contains mail aliases that are available to
      all users on the system. Each line holds one alias, with
      the alias name at the beginning, followed by white space,
      followed by the full mail address. See mmail(1).

 103 "XHOSTS"
      The hosts database. Description in xhosts(4). Remember to clean
      this up when you install HERMES on your system.

 107 "DOQUEUE"
      Normally, the name of a shell (e g, HUSH) and a script file
      that the shell is to run to process files in the MAILQ folder.
      This script should at least include RSMTP, RMAIL, RNEWS, and
      (if you use it) FILESERV.

 108 "PATH"
      A list of folders where binary programs reside. Same as for any
      run-of-the-mill command-line interpreter.

 109 "LOGIN"
      If you want your site to be "pollable" (allow other computers to
      call your computer), UUWORK needs to know what proram to call
      once a connection to the calling modem is established. Usually,
      the HERMES program LOGIN is called with the option "-a", maybe
      also "-b AUX" or "-i". See login(1) and uuwork(1).

 110 "ENVINIT"
      This text file contains line of the form "NAME=value". These lines
      are copied into the environment when the CONFIG.SYS file is read.
      A convenient way to set configuration parameters for other
      software.

 111 "TZ"
      Your local timezone. You must change this value every time you
      set your system's real time clock (you'll need one!) to daylight-
      saving time (or back to normal time). See also parameter 124
      and "TIME ZONES", below.

 112 "SPATHS"
      The FILESERV program can make use of a separate PATHS file (this
      one). The idea is to limit access to the server to users on sites
      listed here (but that can be easily circumvented), or to keep
      the server from using fast but expensive links.

 113 "MDBS"
      Binary form of the PATHS file, written by the MDBS program (see
      mdbs(1) and rmail(1)). Much faster to use and usually smaller than
      the PATHS file itself (which makes sense, despite the fact that
      the PATHS file is also kept around, because those files are
      inhaled into core memory by all programs that use them).

 114 "UUCPPUBLIC"
      If you offer anonymous UUCP, or want to request files from your
      UUCP neighbours, you'll need this folder (see uucico(1)).

 115 "MAILMODE"
      A text file that tells BATCHMAI how to prepare mail for your
      neighbours. You need this file for sending batched SMTP mail
      (see batchmai(1)).

 117 "MANPATH"
      A list of folders with on-line documentation. See man(1).

 118 "MIDILOGIN"
      Same as line #109, but called when characters (at least two
      of them in short succession) arrive at the MIDI port. See
      login(1) and uuwork(1).

 119 "LOCKDIR"
      A directory where lock files are maintained. If you don't specify
      one, the TEMP directory (#21) is used. If you do, you can safely
      have TEMP point to a RAM disk.

 120 "SEQF"
      Just a very small file that helps HERMES keep track of what
      temporary file names have already been generated. When you
      install HERMES, you should supply a file that consists of
      a single line "0" (without the quotes).

 121 "MAILDIR"
      This is a directory where all incoming mail for local users will
      end up. Every user gets a mailbox file (UN*X style) that holds
      all his mail. The mailbox file will have the login name of the
      user (truncated to eight characters) as its name. If there is no
      file for a certain user, or the file is empty, that user doesn't
      have any mail right now. The file will grow (or be created in the
      first place) when mail arrives, and shrink (or be deleted) as
      mail messages are deleted by that user.

 122 "HISTORYFILE"
      This is a file that keeps track of the news articles that your
      news system has seen. This is useful for eliminating duplicate
      articles. Don't mess with this file, it is maintained by RNEWS
      and NHM! Although it usually is kept in $NEWSDIR, it can be
      a good idea to put it on a different partition since it is
      updated very often.
      
 123 "NEWSDEFFILE"
      This file keeps track of newsgroups and articles. If you don't
      specify a name, it will be $NEWSDIR\news.def. The idea behind
      letting you relocate and rename that is that some UNIX-based
      software expects a UNIX-style active file with a certain name.
      You can have line #123 point to that, because a HERMES news.def
      file looks exactly like a UNIX active file.
      
 124 "TZOFFSET"
      The difference between your world time (Universal Time Coordinated,
      or UTC, formerly known as Greenwich Meridian Time, or GMT) and
      local time zone, in seconds. If you live west of Greenwich,
      this value should be positive. See also parameter 111, and
      "TIME ZONES", below.
                                   
TIME ZONES
==========

In order to work correctly, HERMES must know something about the time zone
you live in. HERMES requires that your system's real time clock is set
to the correct local time (rather than world time). You tell HERMES
what your time zone is called in TZ (CONFIG.SYS parameter 111), and what
it actually is in TZOFFSET (CONFIG.SYS parameter 124).

Some typical values for these two parameters:

City, [State,]         | Winter        | Summer
Country                | TZ   TZOFFSET | TZ   TZOFFSET
-----------------------+---------------+--------------
Tokoy, Japan           | JST    -32400 | JST    -32400
Berlin, Germany        | MET     -3600 | MEST    -7200
London, United Kingdom | UTC         0 | WEST    -3600
New York, NY, USA      | EST     18000 | EDT     14400
San Francisco, CA, USA | PST     28800 | PDT     25200

Another possibility for TZ is a so-called "numeric" time zone name,
like this:

City, [State,]         | Winter        | Summer
Country                | TZ   TZOFFSET | TZ   TZOFFSET
-----------------------+---------------+--------------
Tokoy, Japan           | +0900  -32400 | +0900  -32400
Berlin, Germany        | +0100   -3600 | +0200   -7200
London, United Kingdom | +0000       0 | +0100   -3600
New York, NY, USA      | -0500   18000 | -0400   14400
San Francisco, CA, USA | -0800   28800 | -0700   25200
