.TH pathalias "" "" "Command"
.PC "Generate a set of paths among computers"
.fi
\fB/usr/lib/mail/pathalias [\-ivcDf] [\-d \fIlink\^\fB] [\-l \fIhost\^\fB] [\-t \fIlink\^\fB] [ \fIdatafile ... \^\fB]\fR
.PP
.HS
.IC \fB\-c\fR
Print each path's cost
.IC \fB\-D\fR
Terminal domains
.IC "\fB\-d \fIarg\fR
\fBarg\fR names a dead link
.IC \fB\-f\fR
Cost is that to the first hop in a route, not that of the entire route
.IC \fB\-i\fR
Ignore case of input text
.IC "\fB\-l \fIhost\fR"
Set the name of the local host to \fIhost\fR
.IC "\fB\-t \fIarg\fR"
Write trace information for \fIarg\fR onto the standard error
.IC \fB\-v\fR
Verbose:
report some statistics on the standard error output.
.HE
The command
.B pathalias
computes the shortest path and corresponding route
from a host to every other known, reachable host.
It reads host-to-host connectivity information from the standard input or
.IR datafile ,
then writes a list of host-route pairs onto the standard output.
This command normally is used only by administrators of busy systems, to
maintain the path information used by
.BR smail .
.PP
.B pathalias
recognizes the following command-line options:
.IP \fB\-c\fR
Print costs:
print the path cost before each host-route pair.
.IP \fB\-D\fR
Terminal domains:
see
.B domains
section, below.
.IP "\fB\-d \fIarg\fR
.I arg
is a dead link, host, or network.
If
.I arg
is of
the form
.DS
	\fIhost-1\^\fB!\fIhost-2\fR
.DE
.IP
.B pathalias
treats the link from
.I host-1
to
.I host-2
as an extremely high-cost (i.e., dead) link.
If
.I arg
is a single host name,
.B pathalias
treats that host as dead and uses it on any path
only as the relay host of last resort.
If
.I arg
names a network, the network requires a gateway.
.IP \fB\-f\fR
First-hop cost:
the printed cost is the cost to the first relay in a path,
instead of the cost of the entire path.
This option implies (and overrides) option
.BR -c .
.IP \fB\-i\fR
Ignore case:
map all host names to lower case.
By default, case is significant.
.IP "\fB\-l \fIhost\fR"
Set the name of the local host to
.IR host .
By default,
.B pathalias
reads file
.B /etc/uucpname
to discover the name of your system.
.IP "\fB\-t \fIarg\fR"
Output trace information for
.I arg
onto the standard error.
.IP \fB\-v\fR
Verbose:
report some statistics on the standard error output.
.SH "Input Format"
A line that begins with white space continues the preceding line.
.B pathalias
ignores anything following a `#'.
.PP
A list of a host-to-host connection consists of a
.B from
host in column one, followed by white space, followed by a
comma-separated list of
.B 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)
can be followed by a ``cost'' enclosed between parentheses.
.PP
The
.I cost
is an arithmetic expression that
includes numbers, parentheses, and the operators `+', `-', `*', and `/'.
It cannot be negative.
.B pathalias
recognizes the following symbolic costs:
.IP \fBLOCAL\fR 1.0i
A local-area-network connection.
Set cost to 25.
.IP \fBDEDICATED\fR
A high-speed dedicated link.
Set cost to 95.
.IP \fBDIRECT\fR
A toll-free telephone call.
Set cost to 200.
.IP \fBDEMAND\fR
A long-distance telephone call.
Set cost to 300.
.IP \fBHOURLY\fR
An hourly poll.
Set cost to 500.
.IP \fBEVENING\fR
A time-restricted telephone call.
Set cost to 1,800.
.IP \fBDAILY\fR
A daily poll (also called \fBPOLLED\fR).
Set cost to 5,000.
.IP \fBWEEKLY\fR
An irregular poll.
Set cost to 30,000.
.PP
In addition, the symbolic cost
.B DEAD
is a very large number (effectively, infinite);
.B HIGH
and
.B LOW
are -5 and +5, respectively, for baud-rate or quality bonuses/penalties;
and
.B FAST
is \-80, for adjusting costs of links that use high-speed modems (9600 baud
or faster).
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;
for this reason,
.B "HOURLY"
times  24 is much larger than
.BR DAILY .
If no cost is given,
.B pathalias
uses a default cost of 4,000.
.PP
For the most part, an arithmetic expression that mixes symbolic
constants other than
.BR HIGH ,
.BR LOW ,
and
.B FAST
makes no sense.
For example, if a host calls a local neighbor whenever
there is work, and in addition polls every evening, the cost is
.BR DIRECT ,
not
.BR DIRECT+EVENING .
.SH Examples
Consider the following input:
.DM
	down      princeton!(DEDICATED), tilt,
	          %thrash(LOCAL)
	princeton topaz!(DEMAND+LOW)
	topaz     @rutgers(LOCAL+1)
.DE
.PP
If a link is encountered more than once, the least-cost occurrence
dictates the cost and network character.
.B pathalias
treats links as bidirectional but asymmetric:
for each link declared in the input,
.B pathalias
assumes a
.B DEAD
reverse link.
.PP
If the ``to'' host in a link is enclosed by angle brackets,
.B pathalias
regards the link as being terminal,
and heavily penalizes all links beyond it.
For example, when given the input
.DM
	seismo    <research>(10), research(100), ihnp4(10)
	research  allegra(10)
	ihnp4     allegra(50)
.DE
.PP
.B pathalias
generates a direct path from site
.B seismo
to site
.BR research ;
however, the path from
.B seismo
to
.B allegra
uses
.B ihnp4
as a relay, not
.BR research .
.PP
The set of names by which a host is known to its neighbors
is called its
.IR aliases .
Aliases are declared as follows:
.DS
	\fIname \fB= \fIalias\^\fB, \fIalias ...\fR
.DE
.PP
.I name
is the name by which the host is known to its predecessor in the route.
.PP
Fully connected networks, such as the Internet or a local-area network,
are declared as follows:
.DS
	\fInet \fB= {\fIhost\^\fB, \fIhost\^\fB, ...}\fR
.DE
.PP
The list of hosts may be preceded or followed by a routing
character (by default, `!'), and may be followed by a cost (default 4,000).
The network name is optional; if not given,
.B pathalias
makes one up.
Consider the following input:
.DM
	etherhosts = {rahway, milan, joliet}!(LOCAL)
	ringhosts = @{gimli, alida, almo}(DEDICATED)
	= {etherhosts, ringhosts}(0)
.DE
.PP
The routing character used in a route to a network member
is the one encountered when ``entering'' the network.
For details, see the sections on gateways and domains, below.
.PP
If you wish to give connection data, but also wish to hide the host names,
use a declaration of the form:
.DS
	\fBprivate {\fIhost\^\fB, \fIhost\^\fB, ...}\fR
.DE
.PP
.B pathalias
will not generate a route
.I to
a private host, but it may produce routes
.I through
it.
The scope of a
.B private
declaration extends from the declaration either to the end of the
input file in which it appears, or to a
.B private
declaration with an empty host list, whichever comes first.
The latter scope rule lets you retain the semantics of a
.B private
declarations when you pass data to
.B pathalias
via the standard input.
.PP
Dead hosts, links, or networks may be presented in the
input stream by declaring
.DS
	\fBdead {\fIarg\^\fB, ...}\fR
.DE
.PP
where
.I arg
has the same form as the argument to the command-line option
.BR \-d .
.PP
To force a specific cost for a link, use
.DS
	\fBdelete {\fIhost-1\^\fB!\fIhost-2\^\fB}\fR
.DE
.PP
to delete all prior declarations, then re-declare the link as desired.
To delete a host and all its links, use the instruction:
.DS
	\fBdelete {\fIhost\^\fB}\fR
.DE
.PP
Diagnostic messages name the file in which
.B pathalias
found the error.
To change the file's name, use the instruction:
.DS
	\fBfile {\fIfilename\^\fB}\fR
.DE
.PP
You can fine-tune an entry by adjusting the weights of all
links from a given host.
For example:
.DS
	\fBadjust {\fIhost-1\^\fB, \fIhost-2\^\fB(LOW), \fIhost-3\^\fB(-1)}\fR
.DE
.PP
If no cost is given,
.B pathalias
uses a default of 4,000.
.PP
The following script pipes into
.B pathalias
input from compressed (and uncompressed) files:
.DM
	for i in $*; do
		case $i in
			*.Z)	echo "file {`expr $i : '.Z'`}
				zcat $i ;;
			*)	echo "file {$i}"
				cat $i ;;
		esac
		echo "private {}"
	done
.DE
.SH "Output Format"
.B pathalias
writes to the standard output a list of host-route pairs,
where the route is a string appropriate for use with
.BR printf() ,
e.g.:
.DM
	rutgers  princeton!topaz!%s@rutgers
.DE
.PP
.B %s
in the route string is replaced by the name of the user to whom the message
is being sent.
This task normally is performed by a mailer, e.g.,
.B mail
or
.BR elm .
.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
.BR up!%s ,
not
.BR princeton-ethernet!up!%s .
.SH Gateways
.B pathalias
represents a network by a pseudo-host and a set of network members.
Links from the members to the network have the weight given in the input,
whereas the cost from the network to its 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
If, however, 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.
For example, if CSNET is declared dead and the input contains
.DM
	CSNET = {...}
	csnet-relay CSNET
.DE
.PP
then routes to CSNET hosts will use
.B csnet-relay
as a gateway.
.SH Domains
A network whose name begins with `.' is called a
.IR domain .
Domains are assumed to require gateways, i.e., they are
.BR 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.
For example, the definition
.DM
	harvard  .EDU   # harvard is gateway to .EDU domain
	.EDU   = {.BERKELEY, .UMICH}
	.BERKELEY = {ernie}
.DE
.PP
yields:
.DM
	ernie   ...!harvard!ernie.BERKELEY.EDU!%s
.DE
.PP
Output is given for the nearest gateway to a domain.
For example, the example above yields:
.DM
	.EDU   ...!harvard!%s
.DE
.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 you use its command-line option
.BR \-D ,
.B 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 "Files"
.nf
\fB/usr/local/lib/palias.dir\fR \(em Default output
\fB/usr/local/lib/palias.pag\fR \(em Default output
\fBcomp.mail.maps\fR \(em Likely location of some input files
.SH "See Also"
.Xr "commands," commands
.Xr "mail [overview]," mail.o
.Xr "pathmerge," pathmerge
.Xr "smail" smail
.br
Honeyman P., Bellovin, S.M.:
PATHALIAS, or the care and feeding of relative addresses.
Atlanta, \fIProceedings of the Summer USENIX Conference\fR, 1986.
.SH Notes
This command is not used by the implementation of
.B smail
that \*(CO uses.
It is included, however, for compatibility with other implementations.
.PP
The order of arguments is significant.
In particular, options
.B \-i
and
.B \-t
should appear early.
