.TH PATHALIAS 1 "Public-Domain Utilities"
.SH NAME
pathalias - mail routing tool
.SH SYNOPSIS
.B pathalias
[
.B -cDfiv
] [
.B -d
.I link
] [
.B -g
.I edgeout
][
.B -l
.I host
] [
.B -o
.I outfile
] [
.B -s
.I tree
] [
.B -t
.I trace
]
.I file
\...
.SH DESCRIPTION
Pathalias computes the shortest paths and corresponding routes from one
host (computer system) to all other known, reachable hosts. Pathalias
reads host-to-host connectivity information on standard input or in the
named
.I files ,
and writes a list of
host-route pairs on the specified
.I outfile ,
or on the standard output.
.SH OPTIONS
.IP \-c
Print costs: print the path cost before each host-route pair.
.IP \-D
Terminal domains: see
.I domains
section.
.IP \-f
First hop cost: the printed cost is the cost to the first relay in a path,
instead of the cost of the path itself; implies (and overrides) the
.B \-c
option.
.IP \-i
Ignore case:  map all host names to lower case.
By default, case is significant.
.IP \-v
Verbose: report some statistics on the standard error output.
.IP -d <arg>
Declare a dead link, host, or network.
If
.I arg
is of the form ``host-1!host-2,'' the link from host-1 to host-2
is treated as an extremely high cost (i. e., DEAD) link.
If
.I arg
is a single host name,
that host is treated as dead
and is used as a relay host of last resort on any path.
If
.I arg
is a network name, the network requires a gateway.
.IP \-g <file>
Dump the edges of the graph into the named file.
.IP \-l <host>
Set local host name to
.I host .
By default, pathalias discovers the local host name by looking at the
environment variable
.B SITENAME
(see below.)
.IP \-o <outfile>
By default, output is written on the standard output. For shells with
unreliable or no redirection, this option was added to explicitely name
an output file.
.IP \-t <arg>
Trace input for link, host or network on the standard error output.
The form of
.I arg
is as given for
.I -d .
.SS Pathalias 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
.I 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 `/'.
Negative costs are prohibited. The following symbolic costs are recognized:
.PP
.IP "LOCAL (25)"
local-area network connection
.IP "DEDICATED (95)"
high speed dedicated link
.IP "DIRECT (200)"
toll-free call
.IP "DEMAND (300)"
long-distance call
.IP "HOURLY (500)"
hourly poll
.IP "EVENING (1800)"
time restricted call
.IP "DAILY (5000)"
daily poll, also called POLLED
.IP "WEEKLY (30000)"
irregular poll
(These descriptions may not be meaningful outside the U. S.)
In addition,
.IP DEAD
is a very large number (effectively infinite),
.IP "HIGH and LOW"
are \-5 and +5 respectively,
for baud-rate or quality bonuses/penalties,
and
.IP FAST
is \-80, for adjusting costs of links that use high-speed (9.6 Kbaud or more) modems.
.PP
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 hosts in a route,
thus, e.g. HOURLY \&* 24 is much larger than DAILY. If no cost is given,
a default of 4000 is used.
.PP
For the most part, arithmetic expressions that mix symbolic constants
other than HIGH, LOW, and FAST make no sense.
E.g., if a host calls a local neighbor whenever there is work, and
additionally polls every evening, the cost is DIRECT, not DIRECT+EVENING.
.PP
Some examples:
.PP
.RS
.nf
down	princeton!(\s-1DEDICATED\s0), tilt,
	%thrash(\s-1LOCAL\s0)
princeton	topaz!(\s-1DEMAND\s0+\s-1LOW\s0)
topaz	@rutgers(\s-1LOCAL\s0+1)
.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 but asymmetric:
for each link declared in the input, a DEAD reverse link is assumed.
.PP
If the ``to'' host in a link is surrounded by angle brackets,
the link is considered terminal, and further links beyond this one are
heavily penalized.
E.g., with input
.PP
.RS
.nf
seismo	<research>(10), research(100), ihnp4(10)
research	allegra(10)
ihnp4	allegra(50)
.fi
.RE
.PP
the path from seismo to research is direct, but the path from seismo
to allegra
uses ihnp4 as a relay, not research.
.PP
The set of names by which a host is known to its neighbors is
called its 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 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 (`!'
default), and may be followed by a cost (default 4000). The network name
is optional; if not given, pathalias makes one up.
.PP
.RS
.nf
etherhosts = {rahway, milan, joliet}!(\s-1LOCAL\s0)
ringhosts = @{gimli, alida, almo}(\s-1DEDICATED\s0)
= {etherhosts, ringhosts}(0)
.fi
.RE
.PP
The routing character used in a route to a network member is the one
encountered when ``entering'' the network. See also the sections on
.I gateways
and
.I domains .
.PP
Connection data may be given while hiding host names
by declaring
.PP
.RS
private {host, host, ...}
.RE
.PP
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, or to a
private declaration with an empty host list, whichever comes first.
The latter scope rule offers a way to retain the semantics of private
declarations when reading from the standard input.
.PP
Dead hosts, links, or networks may be presented in the input stream by
declaring
.PP
.RS
dead {arg, ...}
.RE
.PP
where
.I arg
has the same form as the argument to the
.B \-d
option.
.PP
To force a specific cost for a link, delete all prior declarations with
.PP
.RS
delete {host-1!host-2}
.RE
.PP
and declare the link as desired. To delete a host and all its links, use
.PP
.RS
delete {host}
.RE
.PP
Error diagnostics refer to the file in which the error was found.
To alter the file name, use
.PP
.RS
file {filename}
.RE
.PP
Fine-tuning is possible by adjusting the weights
of all links from a given host, as in
.PP
.RS
adjust {host-1, host-2(LOW), host-3(\-1)}
.RE
.PP
If no cost is given a default of 4000 is used.
.PP
.SS Output Format
A list of host-route pairs is written to the standard output,
where route is a string appropriate for use with
.I printf(3),
e.g.,
.PP
.RS
.nf
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 domains the name of a network is never used in routes.
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,
the member-to-network links are marked dead,
which effectively prohibits access to the network
from its members.
.PP
However, if the input also shows an explicit link from any host to the
network, then that host can be used as a gateway.
(In particular, the gateway need not be a network member.)
.PP
E.g., if CSNET is declared dead and the input contains
.PP
.RS
.nf
CSNET = {...}
csnet-relay	CSNET
.fi
.RE
.PP
then routes to CSNET hosts will use csnet-relay as a gateway.
.SS Domains
A network whose name begins with `.' is called a domain. Domains are
presumed to require gateways, i. e. they are DEAD. 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.
.PP
E.g.,
.PP
.RS
.nf
harvard	.\s-1EDU\s0	# harvard is gateway to .EDU domain
\&.\s-1EDU\s0	= {.\s-1BERKELEY\s0, .\s-1UMICH\s0}
\&.\s-1BERKELEY\s0	= {ernie}
.fi
.RE
.PP
yields
.PP
.RS
.nf
ernie	...!harvard!ernie.\s-1BERKELEY\s0.\s-1EDU\s0!%s
.fi
.RE
.PP
Output is given for the nearest gateway
to a domain, e.g., the example above gives
.PP
.RS
.nf
\&.\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 its ancestor domains are private.
.PP
If the
.B \-D
option is given on the command line, pathalias treats a link from a
domain to a host member of that domain as terminal. This property extends
to host members of subdomains, etc, and discourages routes that use any
domain member as a relay.
.SH ENVIRONMENT
.IP SITENAME
	Name of the local site. If this variable is not set, and the
.B \-l
	option is not given, the name of the local site is taken to be
.B lostinspace ,
	which most probably is wrong.
.SH BUGS
The
.B \-i
option should be the default.
.PP
The order of arguments is significant.
In particular,
.B \-i
and
.B \-t
should appear early.
.PP
Pathalias can generate hybrid (i. e. ambiguous) routes, which are
abhorrent and most certainly should not be given as examples
in the manual entry. Experienced mappers largely shun `@' when preparing
input; this is historical, but also reflects UUCP's facile syntax for
source routes.
.PP
Multiple `@'s in routes are loathsome, so pathalias resorts to the
``magic %'' rule when necessary. This convention is not documented
anywhere, including here.
.PP
The
.B \-D
option elides insignificant routes to domain members.
This is benign, perhaps even beneficial, but confusing, since the
behavior is undocumented and somewhat unpredictable.
.SH AUTHOR
Steve Bellovin, as told to Peter Honeyman. Addition of
.B \-o
option and port to the Atari ST/TOS by Martin P. Ibert.
.SH "SEE ALSO"
P. Honeyman and S.M. Bellovin, ``PATHALIAS0 or The Care and Feeding of
Relative Addresses,'' in \Proc. Summer USENIX Conf., Atlanta, 1986.
.SH "COPYRIGHT NOTE"
This program is supplied with HERMES for your convenience. It is not covered
by the HERMES license regulations, and is in the public domain, as far as
I know.
