4.3BSD/usr/contrib/pathalias/pathalias.1

Compare this file to the similar file:
Show the results in this format: 

.\" Thanks to Alan Silverstein for help with the manual entry.
.TH PATHALIAS 1 
.SH NAME
pathalias, makedb \- electronic address router
.SH SYNOPSIS
.B pathalias
[
.B \-ivc
] [
.BI \-t \0link
] [
.BI \-l \0host
] [
.BI \-d \0link
] [
.ig
.\" the -g option is for pathparse.  it's not really used by pathalias.
.BI \-g \0file
] [
..
.I files
]
.PP
.B makedb
[
.B \-a
] [
.BI \-o \0dbmfile
] [
.I files ...
]
.ad b
.SH DESCRIPTION
.I pathalias
computes the shortest paths and corresponding routes from one host
(computer system) to all other known, reachable hosts.
.I pathalias
reads host-to-host connectivity
information on standard input or in the named
.IR files ,
and writes a list of
host-route pairs on the standard output.
.PP
.I makedb
takes
.I pathalias
output and creates or appends to a
.IR dbm (3)
database.
.PP
Here are the
.I pathalias
options:
.TP 6
.B \-i
Ignore case:  map all host names to lower case.
By default, case is significant.
.TP
.B \-c
Print costs: print the path cost (see below) before each host-route pair.
.TP
.B \-v
Verbose: report some statistics on the standard error output.
.ig
.\" the -g option is for pathparse and is not for public consumption (yet!).
.TP
.BI \-g \0file
Dump the edges of the graph into the named file.
..
.TP
.BI \-l \0host
Set local host name to
.IR host .
By default,
.I pathalias
discovers the local host name in a system-dependent way.
.TP
.BI \-d \0arg
Declare a dead link, host, or network (see below).
If
.I arg
is of the form ``host1!host2,'' the link from host1 to host2
is treated as an extremely high cost (\fIi.e.\fP, \s-1DEAD\s0) link.
If
.I arg
is a single host name,
that host is treated as dead
and is be used as an intermediate host of last resort on any path.
If
.I arg
is a network name, the network requires a gateway.
.TP
.BR  \-t \0arg
Trace input for link, host or network on the standard error output.
The form of
.I arg
is as above.
.PP
Here are the
.I makedb
options:
.TP 6
.B \-a
Append to an existing database;
by default,
.I makedb
truncates the database.
.TP
.BI \-o \0dbmfile
Identify the output file base name.
.SS \fIpathalias\fP Input Format
A line beginning with white space continues the preceding line.
Anything following `#' on an input line is ignored.
.PP
A list of host-to-host connections consists of a ``from'' host in column 1,
followed by white space,
followed by a comma-separated list of ``to' hosts, called
.IR links .
A link may be preceded or followed by a network character to use
in the route.
Valid network characters are `!' (default), `@', `:', and `%'.
A link (and network character, if present) may be
followed by a ``cost'' enclosed in parentheses.
Costs may be arbitrary
arithmetic expressions involving numbers, parentheses, `+', `\-', `*',
and `/'.
The following symbolic costs are
recognized:
.PP
.RS
.nf
.ta 14mR 17m
\s-1LOCAL\s0	25	(local-area network connection)
\s-1DEDICATED\s0	95	(high speed dedicated link)
\s-1DIRECT\s0	200	(toll-free call)
\s-1DEMAND\s0	300	(long-distance call)
\s-1HOURLY\s0	500	(hourly poll)
\s-1EVENING\s0	1800	(time restricted call)
\s-1DAILY\s0	5000	(daily poll, also called \s-1POLLED\s0)
\s-1WEEKLY\s0	30000	(irregular poll)
.fi
.RE
.PP
In addition,
.SM DEAD
is a very large number (effectively infinite),
and
.SM HIGH
and
.SM LOW
are \-5 and +5 respectively,
for baud-rate or quality bonuses/penalties.
These symbolic costs represent an imperfect measure of bandwidth,
monetary cost, and frequency of connections.
For most mail traffic, it is important to minimize the number
of intermediaries in a route,
thus,
.IR e.g. ,
.SM HOURLY
is far greater than
.SM DAILY
/ 24.
If no cost is given,
a default of 4000 is used.
.PP
For the most part, arithmetic expressions that mix symbolic constants
other than
.SM HIGH
and
.SM LOW
make no sense.
.IR E.g. ,
if a host calls a local neighbor whenever there is work,
and additionally polls every evening,
the cost is
.SM DIRECT,
.B not
.SM DIRECT+EVENING.
.PP
Some examples:
.PP
.RS
.nf
.ta 10m 15m
down	princeton!(\s-1DEDICATED\s0), tilt,
	%thrash(\s-1LOCAL\s0)
princeton	topaz!(\s-1DEMAND\s0+\s-1LOW\s0)
topaz	@rutgers(\s-1LOCAL\s0)
.fi
.RE
.PP
If a link is encountered more than once,
the least-cost occurrence dictates the cost and network character.
Links are treated as bidirectional, to the extent that a
.SM DEAD
reverse link is assumed unless better information is available.
.PP
The set of names by which a host is known by its neighbors is
called its
.IR aliases .
Aliases are declared as follows:
.PP
.RS
name = alias, alias ...
.RE
.PP
The name used in the route to or through aliased hosts
is the name by which the host is known
to its predecessor in the route.
.PP
Fully connected networks, such as the
.SM ARPANET
or a local-area network,
are declared as follows:
.PP
.RS
net = {host, host, ...}
.RE
.PP
The host-list may be preceded or followed by a routing
character, and may be followed by a cost:
.PP
.RS
.nf
princeton-ethernet = {down, up, princeton}!(\s-1LOCAL\s0)
\s-1ARPA\s0 = @{sri-unix, mit-ai, su-score}(\s-1DEDICATED\s0)
.fi
.RE
.PP
See also the sections on
.I gateways
and
.I domains
below.
.PP
Connection data may be given while hiding host names
by declaring
.PP
.RS
private {host, host, ...}
.RE
.PP
.I pathalias
will not generate routes for private hosts, but may produce routes
through them.
The scope of a private declaration extends from the declaration to the end of
the input file in which it appears.
It is best to put private declarations at the beginning of the appropriate
input file.
.SS Output Format
A list of host-route pairs is written to the standard output,
where route is a string appropriate for use with
.IR printf (3),
.IR e.g. ,
.PP
.RS
.nf
.ta 10m 20m
rutgers	princeton!topaz!%s@rutgers
.fi
.RE
.PP
The ``%s'' in the route string should be replaced by the
user name at the destination host.
(This task is normally performed by a mailer.)
.PP
Except for
.I domains
(see below),
the name of a network is never used in
expansions.
Thus, in the earlier example, the path from down to
up would be ``up!%s,'' not ``princeton-ethernet!up!%s.''
.SS Gateways
A network is represented by
a pseudo-host and a set of network members.
Links from the members to the network have the weight given in
the input, while the cost from the network to the members is zero.
If a network is declared dead on the command line (with the
.B \-d
option),
the member-to-network links are marked dead,
which discourages paths to members by way of the network.
.PP
If the input also shows a link from a host to the network,
then that host will be preferred as a gateway.
Gateways need not be network members.
.PP
.IR E.g. ,
suppose
.SM CSNET
is declared dead on the command line
and the input contains
.PP
.RS
.nf
.ta 10m 20m
\s-1CSNET\s0 = {...}
csnet-relay	\s-1CSNET\s0
.fi
.RE
.PP
Then routes to
.SM CSNET
hosts will use csnet-relay as a gateway.
.PP
.I pathalias
discourages forwarding beyond dead networks.
.SS Domains
A host or network whose name begins with `.' is called
a domain.
Domains are presumed to require gateways,
.IR i.e. ,
they are \s-1DEAD\s0.
The route given by a path through a domain is similar to
that for a network, but here
the domain name is tacked onto the end of the next host.
Subdomains are permitted.
.IR E.g. ,
.PP
.RS
.nf
.ta 1i
.ta 10m 20m
harvard	.\s-1EDU\s0
\&.\s-1EDU\s0 = {.\s-1BERKELEY\s0}
\&.\s-1BERKELEY\s0	ernie
.fi
.RE
.PP
yields
.PP
.RS
.nf
.ta 10m 20m
ernie	...!harvard!ernie.\s-1BERKELEY\s0.\s-1EDU\s0!%s
.fi
.RE
.PP
Output is given for the nearest gateway
to a domain,
.IR e.g. ,
the example above gives
.PP
.RS
.nf
.ta 10m 25m
\&.\s-1EDU\s0	...!harvard!%s
.fi
.RE
.PP
Output is given for a subdomain if it has a different
route than its parent domain, or if all of its ancestor domains are private.
.SS Databases
.I Makedb
builds a
.IR dbm (3)
database from the standard input or from the named
.IR files .
(\fIMakedb\fP replaces the obsolete 
.B \-b
option of
.IR pathalias ,
which is no longer recognized.)
Input is expected to be sequence of
.SM ASCII
records,
each consisting of a key field and a data field separated by a single tab.
If the tab is missing, the data field is assumed to be empty.
.SH FILES ET AL.
.ta \w'/usr/local/lib/palias.{dir,pag}     'u
/usr/local/lib/palias.{dir,pag}	default dbm output
.br
newsgroup mod.map	likely location of some input files
.br
.IR getopt (3),
available from newsgroup mod.sources (if not in the C library).
.SH BUGS
The order of arguments is significant.
In particular,
.B \-i
and
.B \-t
should appear early.
.PP
.I pathalias
can generate hybrid (\fIi.e.\fP ambiguous) routes, which are
abhorrent and most certainly should not be given as examples
in the manual entry.
.PP
Multiple `@'s in routes are prohibited by many mailers, so
.I pathalias
resorts to the ``magic %'' rule when appropriate.
This convention is not documented anywhere, including here.
.PP
Domains constitute a futile attempt to defeat anarchy and otherwise
retard progress.
.SH AUTHORS
Steve Bellovin (ulysses!smb)
.br
Peter Honeyman (princeton!honey)