% -*-LaTeX-*-
% Converted automatically from troff to LaTeX by tr2tex on Mon Mar 11 13:18:15 1991
% tr2tex was written by Kamal Al-Yahya at Stanford University
% (Kamal%Hanauma@SU-SCORE.ARPA)


\documentstyle[troffman]{article}
\begin{document}
%
% input file: pathalias.8
%
% @(#)pathalias.8	9.5 88/05/10
\phead{PATHALIAS}{8}{5/10/88}
 "Public Domain"
\shead{NAME}
pathalias, makedb, arpatxt -- mail routing tools
\shead{SYNOPSIS}
{\bf pathalias}
[
{\bf --ivcDf}
] [
{\bf --t}{\it \ link}
] [
{\bf --l}{\it \ host}
] [
{\bf --d}{\it \ link}
] [
%.ig
% for pathparse.
{\bf --g}{\it \ file}
] [
%..
{\it files} ...
]
\par
{\bf makedb}
[
{\bf --a}
] [
{\bf --o}{\it \ dbmfile}
] [
{\it files} ...
]
\par
{\bf arpatxt}
[
{\bf --@fi}
] [
{\bf --g}{\it \ gateway}
] [
{\bf --p}{\it \ privatefile}
] [
{\bf --d}{\it \ directory}
] [
{\it files} ...
]
%.ad b
\shead{DESCRIPTION}
{\it Pathalias}
computes the shortest paths and corresponding routes from one host
(computer system) to all other known, reachable hosts.
{\it Pathalias}
reads host-to-host connectivity
information on standard input or in the named
{\it files}{\rm ,}
and writes a list of
host-route pairs on the standard output.
\par
Here are the
{\it pathalias}
options:
\begin{TPlist}{{\bf --i}}
\item[{{\bf --i}}]
Ignore case:  map all host names to lower case.
By default, case is significant.
\item[{{\bf --c}}]
Print costs: print the path cost before each host-route pair.
\item[{{\bf --v}}]
Verbose: report some statistics on the standard error output.
\item[{{\bf --D}}]
Terminal domains: see 
{\it domains} 
section.
\item[{{\bf --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
{\bf --c}
option.
%.ig
% the -g option is for pathparse and is not for public consumption (yet!).
\item[{{\bf --g}{\it \ file}
}]
Dump the edges of the graph into the named file.
%..
\item[{{\bf --l}{\it \ host}
}]
Set local host name to
{\it host}{\rm .}
By default,
{\it pathalias}
discovers the local host name in a system-dependent way.
\item[{{\bf --d}{\it \ arg}
}]
Declare a dead link, host, or network.
If
{\it arg}
is of the form ``host-1!host-2,'' the link from host-1 to host-2
is treated as an extremely high cost (%
\it i.e.\rm%
, DEAD link.
If
{\it 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
{\it arg}
is a network name, the network requires a gateway.
\item[{{\bf --t}{\it \ arg}
}]
Trace input for link, host or network on the standard error output.
The form of
{\it arg}
is as above.
\end{TPlist}
{\it Makedb}
takes
{\it pathalias}
output and creates or appends to a
{\it dbm}{\rm (3)}
database.
\par
Here are the
{\it makedb}
options:
\begin{TPlist}{{\bf --a}}
\item[{{\bf --a}}]
Append to an existing database;
by default,
{\it makedb}
truncates the database.
\item[{{\bf --o}{\it \ dbmfile}
}]
Identify the output file base name.
\end{TPlist}
{\it Arpatxt}
converts the Internet hosts table
{\it hosts.txt}
into
{\it pathalias}
input.
\par
Here are the
{\it arpatxt}
options:
\begin{TPlist}{{\bf --@}}
\item[{{\bf --@}}]
Generate
{\it pathalias}
input that specifies `@' style addressing.  The default
is to produce
{\it pathalias}
input that specifies `!' style addressing.
\item[{{\bf --f}}]
``Filter mode'' --- write output on stdout.  Normally,
{\it arpatxt}
writes the description of each domain into a separate file.
\item[{{\bf --i}}]
Map output to lower case.
\item[{{\bf --g}{\it \ arg}
}]
Declare a gateway to the Internet or one of its subdomains.  If
{\it arg}
contains one or more dots, the left-hand side component that contains
no dots is declared a gateway to the domain to the right of the dot.
Otherwise,
{\it arg}
is declared a gateway to the Internet as a whole.
\item[{{\bf --p}{\it \ privatefile}
}]
{\it Privatefile}
contains a list of host names that conflict with other names.
\item[{{\bf --d}{\it \ directory}
}]
Write output files in
{\it directory}{\rm .}
%.SS \fIPathalias\fP Input Format
A line beginning with white space continues the preceding line.
Anything following `\#' on an input line is ignored.
\end{TPlist}
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
{\it links}{\rm .}
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:
\par
\ind{1\parindent}
\nofill
%.ta 14mR 17m
LOCAL25	(local-area network connection)
DEDICATED95	(high speed dedicated link)
DIRECT200	(toll-free call)
DEMAND300	(long-distance call)
HOURLY500	(hourly poll)
EVENING1800	(time restricted call)
DAILY5000	(daily poll, also called POLLED
WEEKLY30000	(irregular poll)
\fill
\ind{0\parindent}
\par
In addition,
%.SM DEAD
is a very large number (effectively infinite),
%.SM HIGH
and
%.SM LOW
are --5 and +5 respectively,
for baud-rate or quality bonuses/penalties,
and
%.SM FAST
is --80, for adjusting costs of links that use high-speed (9.6 Kbaud or more) modems.
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,
{\it e.g.}{\rm ,}
%.SM HOURLY
* 24
is much larger than
%.SM DAILY.
If no cost is given,
a default of 4000 is used.
\par
For the most part, arithmetic expressions that mix symbolic constants
other than
%.SM HIGH,
%.SM LOW,
and
%.SM FAST
make no sense.
{\it E.g.}{\rm ,}
if a host calls a local neighbor whenever there is work,
and additionally polls every evening,
the cost is
%.SM DIRECT,
{\bf not}
%.SM DIRECT+EVENING.
\par
Some examples:
\par
\ind{1\parindent}
\nofill
%.ta 10m 15m
down	princeton!(DEDICATED, tilt,
	\%thrash(LOCAL
princeton	topaz!(DEMANDLOW
topaz	@rutgers(LOCAL1)
\fill
\ind{0\parindent}
\par
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
%.SM DEAD
reverse link is assumed.
\par
If the ``to'' host in a link is surrounded by angle brackets,
the link is considered
{\it terminal}{\rm ,}
and
further links beyond this one are heavily penalized.
{\it E.g.}{\rm ,}
with input
\par
\ind{1\parindent}
\nofill
%.ta 10m 15m
seismo	$<$research$>$(10), research(100), ihnp4(10)
research	allegra(10)
ihnp4	allegra(50)
\fill
\ind{0\parindent}
\par
the path from seismo to research is direct, but the path from seismo
to allegra
uses ihnp4 as a relay, not research.
\par
The set of names by which a host is known to its neighbors is
called its
{\it aliases}{\rm .}
Aliases are declared as follows:
\par
\ind{1\parindent}
name = alias, alias ...
\ind{0\parindent}
\par
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.
\par
Fully connected networks, such as the
%.SM ARPANET
or a local-area network,
are declared as follows:
\par
\ind{1\parindent}
net = \{host, host, ...\}
\ind{0\parindent}
\par
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,
{\it pathalias}
makes one up.
\par
\ind{1\parindent}
\nofill
etherhosts = \{rahway, milan, joliet\}!(LOCAL
ringhosts = @\{gimli, alida, almo\}(DEDICATED
= \{etherhosts, ringhosts\}(0)
\fill
\ind{0\parindent}
\par
The routing character used in a route to a network member is the one
encountered when ``entering'' the network.
See also the sections on
{\it gateways}
and
{\it domains} .
\par
Connection data may be given while hiding host names
by declaring
\par
\ind{1\parindent}
private \{host, host, ...\}
\ind{0\parindent}
\par
{\it 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.
\par
Dead hosts, links, or networks may be presented in the input stream by declaring
\par
\ind{1\parindent}
dead \{arg, ...\}
\ind{0\parindent}
\par
where
{\it arg}
has the same form as the argument to the
{\bf --d}
option.
\par
To force a specific cost for a link, delete all prior declarations with
\par
\ind{1\parindent}
delete \{host-1!host-2\}
\ind{0\parindent}
\par
and declare the link as desired.
To delete a host and all its links, use
\par
\ind{1\parindent}
delete \{host\}
\ind{0\parindent}
\par
Error diagnostics refer to the file in which the error was found.
To alter the file name, use
\par
\ind{1\parindent}
file \{filename\}
\ind{0\parindent}
\par
Fine-tuning is possible by adjusting the weights
of all links from a given host, as in
\par
\ind{1\parindent}
adjust \{host-1, host-2(LOW), host-3(--1)\}
\ind{0\parindent}
\par
If no cost is given a default of 4000 is used.
\par
Input from compressed (and uncompressed) files can be
piped into 
{\it pathalias}
with the following script.
\par
\ind{1\parindent}
\nofill
for i in \$*; do
	case \$i in
	*.Z)	echo "file \{`expr \$i : '.Z'`\}
		zcat \$i ;;
	*)	echo "file \{\$i\}"
		cat \$i ;;
	esac
	echo "private \{\}"
done
\fill
\ind{0\parindent}
\par
%.SS Output Format
A list of host-route pairs is written to the standard output,
where route is a string appropriate for use with
{\it printf}{\rm (3),}
{\it e.g.}{\rm ,}
\par
\ind{1\parindent}
\nofill
%.ta 10m 20m
rutgers	princeton!topaz!\%s@rutgers
\fill
\ind{0\parindent}
\par
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.)
\par
Except for
{\it domains}{\rm ,}
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.
\par
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.)
\par
{\it E.g.}{\rm ,}
if
%.SM CSNET
is declared dead
and the input contains
\par
\ind{1\parindent}
\nofill
%.ta 10m 20m
CSNET= \{...\}
csnet-relay	CSNET\fill
\ind{0\parindent}
\par
then routes to
%.SM 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,
{\it i.e.}{\rm ,}
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.
\par
{\it E.g.}{\rm ,}
\par
\ind{1\parindent}
\nofill
%.ta 1i
%.ta 10m 20m 30m
harvard	.EDU\# harvard is gateway to .EDU domain
.EDU= \{.BERKELEY .UMICH
.BERKELEY= \{ernie\}
\fill
\ind{0\parindent}
\par
yields
\par
\ind{1\parindent}
\nofill
%.ta 10m 20m
ernie	...!harvard!ernie.BERKELEYEDU\%s
\fill
\ind{0\parindent}
\par
Output is given for the nearest gateway
to a domain,
{\it e.g.}{\rm ,}
the example above gives
\par
\ind{1\parindent}
\nofill
%.ta 10m 25m
.EDU...!harvard!\%s
\fill
\ind{0\parindent}
\par
Output is given for a subdomain if it has a different
route than its parent domain, or if all its ancestor domains are private.
\par
If the
{\bf --D}
option is given on the command line,
{\it pathalias}
treats a link from a domain to a host member of that domain as terminal.
This property extends to host members of subdomains,
{\it etc}{\rm ,}
and discourages
routes that use any domain member as a relay.
%.SS Databases
{\it Makedb}
builds a
{\it dbm}{\rm (3)}
database from the standard input or from the named
{\it files}{\rm .}
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.
\shead{FILES ET AL.}
%.ta \w'/usr/local/lib/palias.{dir,pag}     'u
/usr/local/lib/palias.\{dir,pag\}	default dbm output
\nwl
newsgroup comp.mail.maps	likely location of some input files
\nwl
{\it getopt}{\rm (3),}
available from comp.sources.unix archives (if not in the C library).
\shead{BUGS}
The
{\bf --i}
option should be the default.
\par
The order of arguments is significant.
In particular,
{\bf --i}
and
{\bf --t}
should appear early.
\par
{\it Pathalias}
can generate hybrid (%
\it i.e. \rm%
 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 UUCPs
facile syntax for source routes.
\par
Multiple `@'s in routes are loathsome, so
{\it pathalias}
resorts to the ``magic \%'' rule when necessary.
This convention is not documented anywhere, including here.
\par
The
{\bf --D}
option elides insignificant routes to domain members.
This is benign, perhaps even beneficial, but confusing, since the
behavior is undocumented and somewhat unpredictable.
\shead{SEE ALSO}
P. Honeyman and S.M. Bellovin, ``PATHALIAS%
\it or \rm%
 The Care and Feeding
of Relative Addresses,''
in %
\it Proc. Summer USENIXConf.\rm%
, Atlanta, 1986.
\end{document}
