.\" @(#) utilities,v 1.2 1990/10/24 05:17:59 tron Exp
.NH
Basics of Using the Smail Utilities
.PP
There are a fairly large number of utility programs that are included
in the
.B Smail3.1
release.  Most of these utilities are useful in creating, maintaining
and displaying databases which can be used by smail for directing and
routing.  These database manipulation tools are layered such that a
small set of low-level utilities are available for creating databases
in various formats, such as sorted files or DBM files (using the
.I dbm (3X)
library).  In addition, the
.B mkline
and
.B pathalias
tools can be used in formatting raw alias and path data for use by
the database creation tools.  Built on top of these lower level tools
are configuration-driven tools such as
.B mkaliases
and
.B mkpath ,
which handle things at a higher level.
.PP
Most of these smail utilities are installed under the smail library
directory, which is normally
.I /usr/lib/smail .
.NH 2
Building Simple Databases
.PP
Sorted databases, and
.I dbm -based
databases, can be used by smail directors based on the aliasfile
driver or by routers based on the pathalias driver.  The first command
to know about when creating these databases is
.B mkline .
This command takes an alias file or path file as input, strips
comments and unnecessary white-space, and joins continuation lines.
For example, given the alias file:
.DS I
.ta .5i 3i
# Sample alias file
Postmaster:
	tron@futatsu	# Ronald S. Karr
	chongo@eek	# Landon Noll
.sp \n(PDu
uucp:	gam@woof	# Gordon Moffett
.TA
.DE
the
.B mkline
command would produce, on its standard output:
.DS I
Postmaster:tron@futatsu chongo@eek
uucp:gam@woof
.DE
.PP
By removing comments and continuation lines, programs that create
databases can read single line records.
.PP
Sorted databases can be created using either the
.B sort
command or the smail
.B mksort
utility.
.B Mksort
does not have any line length restrictions, and can thus be used for
aliases and paths containing arbitrarily large records.  It does
require the ability to read all of its input files into memory.  In
addition, some versions of the
.B sort
command are reported to have a bug related to the use of the
.B \-f
flag, for performing case-independent sorting.  To creat a sorted
version of the alias file listed above, use the following command:
.DS I
mkline \fIaliasfile\fP | mksort \-f > \fIaliasfile\fP.sort
.DE
Here,
.I aliasfile
is the pathname containing the file of interest.  The
.B \-f
flag performs a sort in a case-independent manner, as required for the
smail
.B bsearch
file lookup method.  This command line could also be used to create a
sorted paths file.  Smaller systems may wish to use
.B sort
to avoid high memory usage, or errors due to running out of memory.
Path files can be quite large.
.PP
DBM databases can be created using the
.B mkdbm
utility.  To create a database can be used by the smail
.B dbm
file lookup method, for aliasfile directors and pathalias routers, use
a command such as:
.DS I
mkline \fIfile\fP | mkdbm \-f -o \fIname\fP
.DE
where
.I file
is the source text for the database and
.I name
is the name for the DBM database.  This will create two files,
.I name .pag
and
.I name .dir
containing the actual data.  The
.B \-f
flag causes the keys to be converted to lower case before being stored
in the database.
.PP
Rather than require that you enter a complex command every time you
have changed the primary
.I aliases
file, the
.B mkaliases
utility exists to do this for you.  It uses the configuration defined
in the EDITME file to determine how your aliases file is to be built,
and where it is to be found, and builds it for you.  For example, if
your alias database is stored as a DBM file with a name of
.I /usr/lib/aliases ,
then the command
.DS I
mkaliases
.DE
will execute the shell command:
.DS I
mkline /usr/lib/aliases | mkdbm -f -v -o /usr/lib/aliases
.DE
.NH 2
Building Path Databases
.PP
Quite often, the building of path databases is more complex than
taking one file and running it through a mkline|mksort or a
mkline|mkdbm pipeline.  Map data is often used, which must be
processed by the
.B pathalias
program to produce paths.  As well, this map data can come from a
variety of sources, both from map data published monthly in the USENET
newsgroup
.B comp.mail.maps
and from private sources, such as maps of local area networks, or
a private map entry for the local host.
.PP
The
.B mkpath
utility is used to organize the path building process.  It takes a
configuration file, describing where map files can be found, along
with directives controlling other data, and feeds all of this to
pathalias.  It produces paths on the standard output.
.PP
An example of a configuration file for mkpath is the following file,
.I world.conf :
.DS I
.ta \w'safemap'u+3n
# get the usenet world maps
cd      /usr/spool/uumaps
safemap d.*
safemap u.*
.sp \n(PDu
# merge in the new maps
cd      /usr/lib/smail/maps
safemap newmap/*.map
.sp \n(PDu
# merge in our external map
delete  `uuname -l`
map     world.map private.map tweak.map
.TA
.DE
The configuration file above takes map files beginning with
.I d.
and
.I u.
from the directory
.I /usr/spool/uumaps ,
and map files under
.I /usr/lib/smail/maps/newmap .
These map files are sent as input to pathalias, the name of the local
host is deleted from the connectivity information that pathalias has
collected, and then the files
.I world.map ,
.I private.map
and
.I tweak.map
are sent to pathalias.  The reason for deleting the local host
connectivity information is that links from the local host should not
be determined based on information in the maps published by other
sites.  After processing all of this, a sorted list of path file
entries is written to the standard output.  The above configuration
file could be used to create a sorted paths file using the command:
.DS I
mkpath world.conf > world.path
.DE
A complete set of examples is distributed with smail in the source
directory
.I samples/amdahl/maps .
.NH 2
Storing and Displaying Information about Hosts
.PP
The
.B uuwho
command can be used by users or site administrators to get a listing
of the map entry for a known site.  It makes use of a database which
is formed by the
.B mkuuwho
command.  Mkuuwho takes a mkpath configuration file and produces a
database which associates each site name with the location of the
map entry for that site.  The mkpath configuration file is used only
for determining where the map files are to be found.
.PP
With the configuration file used above as an example for
.B mkpath ,
the following command can be used to create an accompanying uuwho
database:
.DS I
mkuuwho -u uuwho world.conf
.DE
This will create a DBM database, in the files
.I uuwho.pag
and
.I uuwho.dir .
After the database is created, the command:
.DS I
uuwho foobar
.DE
could be used to display a map entry such as:
.DS I
.ta \w'Postal Address'u+3n
System name:	foobar
Organization:	Foo Bar, Inc.
System type:	pdp 11/45, v6 modified
Contact person:	Joe Stud, III
Email Address:	foobar!stud3
Telephone:	+1 605 555 2175
Postal Address:	Foo Bar, Inc., Wall SD 57790
Long/Lat:	44 00 43 N / 102 19 59 W
News links:	namei glotz hoptoad kgbvax kremvax
.sp \n(PDu
#
#	upstream sites
.sp \n(PDu
.ta \w'foobar'u+3n
foobar	glotz(HOURLY+LOW), namei(HOURLY+HIGH)
#
#	downstream sites
foobar	kgbvax(HOURLY*4), kremvax(HOURLY*4)
#
#	our alt.drugs feed
foobar	hoptoad(DAILY)
.TA
.DE
.NH 2
Extracting Maps From USENET
.PP
The
.B getmap
utility can be used to extract map entries from the maps published in
the USENET newsgroup
.B comp.mail.maps .
To use this utility with netnews version 2.11, for automated map
extraction, first put the following line into your news
.I sys
file:
.DS I
maps:comp.mail.maps,world:F:/usr/spool/uumaps/work/batch
.DE
This line will cause netnews to put a line in
.I /usr/spool/uumaps/work/batch
every time an article is posted to the
.B comp.mail.maps
newsgroup.  This line contains the pathname to the article file.
.PP
Periodically, the
.B getmap
utility can be executed to process the
.I batch
file, extracting any map data that has been received.  Getmap should
be executed from cron under a user and group that can write to the map
directory,
.I /usr/spool/uumaps .
It will mail any errors to the address
.B postmaster .
The period of execution should preclude the loss of any map data as a
result of a articles being expired, but does not necessarily need to
be daily.
.NH 2
Smail Cleanup Utilities
.PP
As discussed in a previous section, the utilities
.B checkerr
and
.B savelog
exist to clean up after smail.  The
.B checkerr
utility checks for processing errors, sending errors to the mail
administrator whenever they are found.  The
.B savelog
utility can be used to perform log truncation and compression, so that
the filesystem containing the smail logfile does not eventually fill
up.  Both of these utilities should be executed on a daily basis from
cron.
.PP
The
.B getmap
utility also keeps a log of its activities, in the file
.I /usr/spool/uumaps/work/getmap.log .
Sites that use this utility to extract maps from USENET should use the
.B savelog
utility to truncate and compress this log as well.  However, this
should not grow very quickly, so a running the necessary savelog
command on a monthly basis is reasonable, particularly since this is
the period over which map data is published.
