SMAILRTRS(5)

NAME
/usr/local/etc/smail/routers - smail router configuration

THE ROUTERS FILE
The routers file describes the operations, and their order, for handling remote addresses. For example, some possibilities are to look up domain names in a routing database, to match a special domain-literal form, or call a program to return a list of neighbouring hosts.

  Generic Routers Attributes
The following list describes the possible generic attributes for router file entries:

always
    type: boolean

    Routers will not always find a complete match for a particular domain name. For example, if a routing database has a route to the domain ``amdahl.com'' but not to the domain ``futatsu.uts.amdahl.com'' then the routing driver might return the route to just ``amdahl.com''. Generally, the route for the longest match of the target domain is used. However, if the always attribute is set, then any match found by the current router will be used in preference to routes that might have been returned by routers later in the router list. This is useful for hardwiring a certain number of routes within a small database. For example, this is useful for Internet sites that gateway for a small number of UUCP sites in the UUCP zone, or for hardwiring routes to internal SMTP hosts that may also be reachable over the public Internet via other gateways.

driver
    type: string

    The driver attribute names a specific set of low-level functions which will do the work of routing remote mail. This attribute is required.

method
    type: string

transport
    type: string

    The router driver has the option of specifically setting a transport to use for remote delivery. If the driver does not do so, then either a method or a transport attribute must exist to specify how the mail is to be delivered. A method attribute specifies a file which contains a table relating domain names to transports. A transport attribute specifies a specific transport. If the method file does not contain a match for all domains, then the transport named with the transport attribute is used. The format of a method file is given in the next section.

THE ROUTER DRIVERS
This section details the usage and driver-specific attributes for all of the router drivers distributed with smail.

  The Pathalias Driver
The pathalias router computes routes from a database in the style produced by the pathalias program. It has the following driver-specific attributes:

domain
    type: string

    A list of domains to be stripped from the end of a hostname before it is searched for in the database. Multiple domains in this list are separated by colons.

file
    type: string

    This defines the name of the file containing the database. Except when it does not make sense as a result of the proto used, if this does not begin with a slash (`/'), it will be referenced relative to the smail_lib_dir directory.

interval
    type: number

    The number of seconds to wait between open retries.

optional
    type: boolean

    If set, then if the open fails, assume an empty alias file. This is useful for optional databases. For example, in a networking environment, workstations may be configured with the option of having a private alias file, without the necessity of creating such a file on each host.

proto
    type: string

    Names the protocol used in opening and searching the database. Possibilities are discussed below.

reopen
    type: boolean

    If set, the pathalias will be closed and reopened after each call to the pathalias driver. This is useful in environments where file descriptors are scarce but many databases are desired.

required
    type: string

    A list of domains which targets are required to be for a match. The names are not stripped, unless they are also specified by the domain attribute.

retries
    type: number

    The maximum number of retries for opening a file. This is useful on systems without an atomic rename system call. On such systems there will be a window of vulnerability when new databases are moved into place where no file will exist.

try type: string

    A list of domains to be stripped only if the target was not found in the database without the domain stripped. (This is currently not supported.)

tryagain
    type: boolean

    If set, then if the open fails, the resolution of local addresses will be attempted at a later time. This is useful in a networking environment where failure to open a database (such as a remote YP database) may be a result of a server machine being down or temporarily inaccessible.

The current list of possible values for the proto attribute is:

bsearch
    Use a binary search to look through a sorted file arranged as lines which begin with a key and are followed by the value associated with the key, separated by a colon or whitespace.

dbm Use the BSD dbm(3x) or ndbm(3x) [or db(3x) ndbm emulation] routines to search for the key. The keys and data in the dbm database must end in a NUL byte. If only the dbm library is available then only one dbm database can be used by smail, while the ndbm routines will allow any number of databases. However, it is always okay for multiple routers and directors to use the same dbm database, if this is useful.

lsearch
    Use a linear search using the same read routine used to read config files. `#'-style comments are allowed and the beginning of each file entry should be the key, followed by whitespace or a colon character. The rest of the entry should be the value associated with the key.

yp  Use the Sun YP service to access a paths database stored on a remote machine. In this case the value for the file attribute is of the form:

        domain_name:database_name
    where the ``domain_name:'' portion is optional and defaults to the default YP domain for the local host.

aliasyp
    This is a variant of the YP protocol that is compatible with the standard Sun mail.aliases YP service. This database has a different format from other databases which must be taken into account when sending requests. Typically this is not useful for a path database.

nisplus
    Look up the key in a remote Sun NIS+ (Sun NIS version 3) database. NIS+ is not compatible with NIS (otherwise known as YP). The file parameter must be a NIS+ indexed name, which is described in the nis(1) manual page. The search string is replaced with ``%s'' where it can be filled in by smail's NIS+ lookup routine. See the nisplus entry in the smail manual page and the more detailed example in the nisplus entry in the smaildrct(X_MAN_5_EXT) manual page.

All database lookups are either independent of case or, when case independent lookups are impossible, case-folded. Thus, keys in DBM or YP databases must be in lower case.

As an example of the use of the domain, try, and required driver attributes, if the domain value is ``uucp'' then any domain name that ends in ``.uucp'' will have the ``.uucp'' part removed before being looked up. Alternately, if the the try value is ``uucp'' then ``.uucp'' is stripped only if the original was not found. If the required value is ``uucp'' then a domain name is not a candidate for a match unless it ends in ``.uucp''. The effects of domain and try are not cumulative and a domain name is applied to the required attribute value before being applied to domain and try in that order.

Note that the length of any stripped string is added to the count of characters matched for purposes of deciding which router had the most complete match.

A sample pathalias router entry is:

    pathalias:
            transport=uux,
            driver=pathalias;
            file=paths,
            proto=bsearch,
            domain=uucp
An example of a pathalias file for the site ``walldrug'' is:

    .amdahl.com         amdahl!%s
    amdahl              amdahl!%s
    dgcad               namei!glotz!nsavax!dgcad!%s
    glotz               namei!glotz!%s
    hoptoad             hoptoad!%s
    kgbvax              kgbvax!%s
    kremvax             kremvax!%s
    namei               namei!%s
    nsavax              namei!glotz!nsavax!%s
This data base associates a host or domain name, on the left hand side, with a path, on the right hand side. The right hand side should be a UUCP-style `!'-path ending in a ``%s''. The format is intended to be more general, with the ``%s'' showing where to put a user name. Indeed pathalias(8) can produce paths involving both right and left operators such as:

    decwrl              decwrl!%s@ucbvax
This form is not recommended in general because of a historical disagreement over the precedence of ``!'' and ``@'' which is not always resolved correctly by the pathalias program. By standardising on UUCP-style `!'-paths, as will be produced from the USENET maps, we avoid many routing ambiguities. If the path is just ``%s'', it denotes a name for the local host.

  The Uuname Driver
Some sites in the UUCP zone may wish to use a direct path to their neighbours, without relying on a pathalias database. Alternately, a site may wish to use the pathalias routes to their neighbours only in the case that a domain address is given (i.e., ``neighbour.uucp'').

A simple driver that meets these requirements is the uuname driver, which reads a list of hostnames from the output of a shell command (normally /usr/bin/uuname) and uses this list to match neighbouring hostnames.

An example entry for a site that wishes to route to their neighbours for domain names that may end in ``.uucp'' is:

    uuname:
            transport=uux,
            driver=uuname;
            cmd=/usr/bin/uuname,
            domain=uucp
An alternative is a site that wishes to bypass the pathalias router only for explicit target matches, so that the form ``neighbour.UUCP will be routed through, as an example, pathalias. This can be done by not specifying a domain, as in:

    uuname:
            transport=uux,
            driver=uuname;
            cmd=/usr/bin/uuname
The uuname driver also supports the domain, required, and try attributes, and all three domain-style attributes can be colon separated lists. See the pathalias driver for more details on these attributes.

In addition, there is a string attribute, statfile which names a file which can be used to determine when the output of the shell command will change. For example, when used with the uuname command this would normally be one of /usr/lib/uucp/L.sys, /usr/lib/uucp/Systems, or /etc/uucp/Systems depending on whether a site is using HoneyDanBer or stock V7-style UUCP. If a statfile attribute is defined, then smail daemons that expect to deliver multiple messages will cache the output of the shell command. The specified pathname will then be checked at regular intervals to determine if the command should be reissued to refresh the cached information.

  The Queryprogram Driver
If no other router driver meets a particular routing requirement, but a shell script or C program can be written which does, the queryprogram driver can be used to access this script or program. This driver runs a program, with arguments, and examines its exit status and standard output for information. The program should return an exit status of zero to indicate a match for the target host, non-zero otherwise. Optionally, this program can write a path and a transport on its standard output to provide additional information. If a path is not returned then a one-hop path to the target host is assumed. The program is always executed as an unprivileged user.

The queryprogram driver supports the domain, required, and try attributes, as defined in the description of the pathalias driver. The program and its arguments are described in terms of a cmd attribute which is a string consisting of white-space-separated tokens which are expanded to form a program name and the arguments to pass to that program. The variable $host can be used to obtain the target host string. White space or punctuation from an expansion variable do not delimit arguments (i.e. variables expand into one argument). Two additional boolean attributes affect the driver's behaviour:

read_path
    type: boolean

    If this attribute is enabled, then a !-path is read as the first white-space delimited field in the first line of output from the program. If no output is produced by the program, or this attribute is not enabled, then a one-hop path to the target host is assumed. A path should consist of a list of hostnames separated by exclamation point (`!') characters.

read_transport
    type: boolean

    If this attribute is enabled, then a transport is read as a white-space delimited field from the first line of output from the program. If the read_path attribute is also enabled, then the transport is taken from the second field, otherwise it is taken from the first. If no output was generated by the program, or the field did not exist in the output, then the normal methods for determining the transport are used.

A trivial example of the use of this driver is the router file entry:

    match_bar:
            driver=queryprogram,
            transport=bar;
            cmd="/bin/test X${lc:host} = Xfoo"
This router will use the program test(1) to determine if the target host is ``foo''. If this is the target host, then it is assumed to be a neighbouring host which can be reached over the transport ``bar''.

A more complex example is to create a shell script such as:

    # match_fubar.sh - match hosts on the fubar networks
    case "$1" in
    foo)    echo "foo foo_transport"; exit 0;;
    bar)    echo "foo!bar foo_transport"; exit 0;;
    curds)  echo "curds curds_transport"; exit 0;;
    whey)   echo "curds!whey curds_transport"; exit 0;;
    esac
    exit 1
By setting up a router file entry such as:

    match_fubar:
            driver=queryprogram;
            cmd="/bin/sh $lib_dir/match_fubar.sh ${lc:host}",
            read_path, read_transport
a complete, though not particularly optimal, router is created which can match the hosts ``foo'', ``bar'', ``curds'', and ``whey'' and cause messages to these hosts to be delivered using one of the transports ``foo_transport'' or ``curds_transport''.

The queryprogram driver is not very efficient, as it requires a fork() & exec() for each host. However, it is a very simple to construct a new router using this driver, so it is useful for prototyping. In general, a new form of routing requirement is most efficiently handled by writing a new router driver.

  The Gethostbyname Driver
In a networking environment, hostnames on a network can be matched using this driver, which calls the gethostbyname(3N) library routine. This routine is only available on systems that supply a BSD compatible networking library. Driver attributes for this driver include domain, required, and try attributes, which are compatible with the pathalias and uuname drivers.

Additional private attributes are:

only_local_domain
    type: boolean

    Do not match hosts that have a domain component (i.e., that contain a dot) - i.e. domain names. The domain attribute is applied before the only_local_domain attribute, so hosts that have a domain component consisting only of one of the strings listed with the domain attribute can be matched.

    the gethostbyname driver will only match a target host completely. The hostname given to the transport will be the host as given by the h_name field of the hostent structure.

    NOTE: The hostname given to gethostbyname() will be down-cased, so that upper-case or mixed-case names can be matched correctly.

  The Gethostbyaddr Driver
Also in a network environment, it is useful to be able to specify explicit Internet addresses using a target such as: ``[192.168.2.1]'' which might be the internet address for a private internal host to which e-mail might be routed to.

The gethostbyaddr driver matches targets of this form, which is defined by square brackets surrounding only digits and dot characters.

The gethostbyaddr driver has the following private attributes:

check_for_local
    type: boolean

    If set, see if the hostname returned by gethostbyaddr(3n) matches one of the known names for the local host. The address INADDR_LOOPBACK, which normally represents 127.0.0.1 (the address most commonly used for host loopback interfaces), also counts as a local host. If a local host is detected then the remainder address will be re-parsed and re-routed thus short-cutting one hop in the delivery of the message.

    NOTE: This attribute is set by default.

fail_if_error
    type: boolean

    If set, then any literal IP address target which does not fit the form of an internet address is considered an error. If not set, then such addresses are merely not matched by the driver.

    NOTE: This attribute is set by default.

  The Bind Driver
The bind driver uses the Berkeley Internet Name Domain server, to resolve target domain names. It is fully compliant with the RFC 974 and RFC 1134 standards, and uses MX records. This router is available only on systems that have a 4.3BSD compatible or newer resolver library. It is highly recommended that this router be used for machines that are on the Internet, rather than using the gethostbyname router.

The following private attributes vary the behaviour of the bind driver:

defer_no_connect
    type: boolean

    If this boolean attribute is set, then we must be able to connect to the server. If attempts to connect to the server fail, then routing is retried at a later time, on the assumption that the server is only down temporarily. If this attribute is not set, then a failure to connect to the server will cause the router to be ignored. This allows a bind router to be optional based on whether or not the server exists.

    NOTE: This attribute is set by default.

local_mx_okay
    type: boolean

    If this boolean attribute is not set, then it is considered an error for an MX resource record to be encountered which points to the local host. If this attribute is set, then such an MX resource record will cause the address not to be matched. The precedence number for the resource record is taken into account here, so that an MX resource record which points to the local host is ignored if there are other records with a lower precedence number.

defnames
    type: boolean

    This boolean attribute is passed to the BIND resolver routines as the ``RES_DEFNAMES'' flag. If set, then hostnames which do not contain dots will have a default domain appended to them before lookups. For example, this allows for hosts on a local area network to be referenced using the basename of the host rather than requiring the full domain name.

ignore_domains
    type: string

    If this string is set, then it is used as a colon-separated list of domain names. If a hostname ends in any of these domains, then the router will not match the host, and will not result in any queries. This can be set to a list of domains that are known not to exist, such as ``uucp'' and ``bitnet'', to prevent expensive lookups which will never be successful.

domain_required
    type: boolean

    If this boolean attribute is set, then a hostname with only one domain component (i.e., no dots) will not be matched. This should probably be set if defnames is not set, to prevent lookups for UUCP hostnames that will not be found in the DNS.

    NOTE: This attribute is set by default.

mx_only
    type: boolean

    If this boolean attribute is set, then match a host only if it has an MX record. This is not currently useful on the Internet as a whole, though it does have uses in managing networks disconnected from the Internet, but that use the DNS to manage the domain name space. If all domain names that can accept mail have an MX entry pointing to them, then no attempts will made to send mail to other ``hosts'' such as printers or terminal concentrators which have only A records.

mx_domains
    type: string

    This is a list of colon separated domains which, if they match the tail of a fully qualified domain name, will force mx_only mode for that domain. This allows the advantages of mx_only for areas that do conform to the specifications - most of the Internet does not, yet. Negative matches can be forced by preceding the domain with a bang (!). For example: mx_domains = ``!york.ac.uk:ac.uk''

    This allows you to send to any host in the york.ac.uk domain but only to MX registered hosts in the ac.uk domain.

gateways
    type: string

    A list of gateways and corresponding domains for explicit routing using the bind processing logic for the gateway address. The string consists of a sequence of lists. Each list consists of strings separated by colons, and the lists are separated by a string consisting of a single `+' character. Each list consists of the name of a gateway, followed by a list of domains that should be routed to that gateway. The gatewayed domains will match either against a complete address, or against the terminating domain of an address. For example:

        gateways = "uknet.ac.uk:uucp:+:\
                    earn-relay.ac.uk:bitnet:ie:earn"
    In this example, if an address of the form ``<anything>.uucp'' is being processed, it will be converted to ``uknet.ac.uk'' before any other processing is done. The new name will then be looked up in the DNS and routed accordingly. Thus mail for ``<anything>.uucp'' will always be sent to ``uknet.ac.uk'', by whatever route is registered in the DNS for that address. Similarly, mail for the domains ``bitnet'', ``ie'', and ``earn'' will be routed to ``earn-relay.ac.uk''.

dns_search
    type: boolean

    If set allow the resolver to search its domain list for matches. This experimental and might not have the effect you expect depending on your resolver search capabilities.

widen_domains
    type: string

    A list of domains, separated by colons, to be tacked onto the end of the address if it isn't found directly in the DNS. For example:

        widen_domains = "cam.ac.uk:ac.uk"
    With this setting, an address such as ``psy.ox'' will first be tried as it stands, then ``psy.ox.cam.ac.uk'' will be tried, and if that fails, ``psy.ox.ac.uk'' will be tried.

All matches found by the bind driver are considered full matches, for the purposes of prioritising results from different routers. Matches are considered full even in the presence of wildcards in MX records.

  The Smarthost Driver
Sometimes it is handy to be able to redirect mail to a host that you don't know about to some other host that has more routing information. This other host is called a ``smart'' host, and can be named by using the smarthost driver.

The smarthost driver has the following private driver attribute:

path
    type: string

    This define a host or UUCP-style `!'-path path that defines the smart host.

If no transport or method attribute is given for this router file entry, this address will be resent through all the routing drivers. An exception is that an address cannot be sent to the smarthost driver twice, as this would mean that the path to the smarthost was not known.

The global configuration variable auth_domains affects the smarthost router by restricting the set of domain names that can be matched by the smarthost router to domain names that are outside of the domains listed in auth_domains.

For example, if the site ``namei'' wanted to use ``amdahl''s routing database for mail delivery to non-neighbouring sites they could use a router file entry of:

    smart_host: driver=smarthost; path=amdahl
or

    smart_host: transport=uusmtp,
        driver=smarthost; path=amdahl
NOTE: At the present time, a transport or method attribute is required, as the software is not yet in place that can rescan the routers in the required ways.

Then, a recipient address of ``Ted.Husted.Jr@walldrug.uucp'' will be rewritten so that the hostname is ``amdahl'' and the remaining part of the address is ``Ted.Hustead.Jr@walldrug.uucp.''

Alternately, in the second form for the entry, the transport, uux, would be known immediately and be passed the hostname ``amdahl'' immediately, with a $user value of ``Ted.Hustead.Jr@walldrug.uucp.''

By specifying a UUCP-style `!'-path it is possible to route mail to a smart host that you would not otherwise be able to route to. For example, if the machine ``glotz'' wished to use ``amdahl'' as its smart host, through its neighbouring site ``namei'', it could use:

    smart_host: driver=smarthost; path=namei!amdahl
or

    smart_host: transport=demand, driver=smarthost; path=namei!amdahl
It is possible to set the path and/or the transport in the config file. This is done by setting the config file attributes smart_path and smart_transport. For example, the config file could contain the following:

    smart_path = amdahl
    smart_transport = uusmtp
Then, if the entry in the routers file contained:

    smart_host: driver=smarthost
the configuration would be essentially the same as in the second smart_host example above. This makes it possible to share copies of the router file among several machines, with the smart host configuration specific to one machine being set in its private configuration file.

These config file attributes are used only if the path driver attribute is not given in the smart_host entry. If the smart_path attribute from the config file is used, the smart_transport will override a transport or method attribute.

  The Rewrite Driver
The rewrite driver is a pathalias-like driver that matches addresses against a database and gives back a new address that is subsequently re-parsed.

The rewrite driver supports the following private attributes, which are supported in exactly the same way as in the pathalias router: file, proto, domain, required, retries, interval, reopen, tryagain, optional, cacheopen.

The algorithm of the rewrite router is given a target domain name and looks it up in the database using the same search strategy as the pathalias driver. The best match wins, as with pathalias. If a match is found, the information on the matching line specifies how to rewrite the address, or whether not to rewrite it at all. If the address is not rewritten, the driver behaves as if it had not been matched at all. If the address is rewritten, the driver sets the input address up as the parent (just as with an alias) of the rewritten address, and returns the rewritten address to be re-parsed. The match_always attribute has no effect on this driver - partial matches are treated like full matches.

Each line in the rewrite database has the following format:

    domain flag format
The ``domain'' portion is matches exactly as with the pathalias driver. It can be a simple hostname, fully qualified domain name, or a partial domain name beginning with a dot (`.').

The flag is one of `-', meaning rewriting should not be done (the router then behaves as if the target had not been matched), or `+', meaning rewriting should be done, using the specified format if the remainder was a simple mailbox (user name), and leaving the remainder unchanged if it was more complex.

The format is a string to be variable expanded to produce the rewritten address. The expansion is performed in a context in which $user refers to the remainder and $host refers to the target. See the smail(5) manual page for more information about the syntax of string expansions.

For example:

.special.com + special-$user
special.com  -
.foo.org + $user-$host
foo.org + ${lookup:user:lsearch{foo-aliases}{$value}{postmaster}}
foo.com + ${lookup:user:lsearch{foo-aliases}{$value}{"$user at $host"}}

Note the last entry will produce a nice looking bounce making this driver a superb way of implementing virtual domains without requiring extra directors or other such integral configuration changes.

  The Rerouter Driver
The rerouter driver is an experimental router driver that can do optimisation of UUCP-zone !-paths addresses. For example, given an address of:

    host1!host2!host3!host4!host!user
The rerouter driver could realize that a more efficient path exists to ``host'' and rewrite this as:

    host6!host!user
Before you say to yourself how neat this would be and how much of a savings this would be for the world, you must realize that such re-routing is dangerous and should be configured-in only with a great deal of consideration and attention to detail in your re-routing database. The rerouter driver is probably only of use in a privately managed network.

Here are the private attributes supported by the rerouter driver:

file
    type: string

    An expansion string defining a file that selects which hosts or domains will be considered candidates for re-routing. If the string, after expansion, does not begin with a slash (`/'), it will be opened relative to smail_lib_dir. The format of the file is described later in this section.

proto
    type: string

    The lookup protocol to use in searching through the database specified by the file attribute. The list of possible lookup protocols for the rerouter driver is the same as for the pathalias driver.

domain
    type: string

    A colon-separated list of default domains for hosts in the database. Targets ending in any of these domains will have the domain stripped (including a preceding dot) before the database is searched. A target containing only the domain (e.g., just ``.uucp'') will remain unchanged.

required
    type: string

    A colon-separated list of domain names that are must be part of a domain name for that target to be considered a candidate for re-routing.

reopen
    type: boolean

    If set, then reopen the database for each call to the rerouter driver, and close before each return. This is necessary for systems that would not otherwise have a sufficient number of available file descriptors for all of their routing and directing needs.

optional
    type: boolean

    if set, then if the open of the database file fails, assume an empty file.

tryagain
    type: boolean

    if set, then if the open fails, try again on a later queue run.

matchall
    type: boolean

    If set, reroute all bang path addresses. The re-routing database isn't used at all in this mode, so even hosts that have an exclusion flag (`-') in the database will be rerouted. WARNING: Use this only for debugging purposes. Unconditional re-routing is an offence against the community!

matchlocal
    type: boolean

    If set, then address containing forms for the local host (within the bounds of the required attributes) are considered candidates for re-routing. The path starting with the component directly following the last occurrence of the local hostname is used re-routing. For example, if the local hostname is ``geminix'', then the input path:

        host1!host2!geminix!host!user
    might be rewritten as:

        host4!host!user

matchdb
    type: boolean

    If set, a database lookup is done for the target. Otherwise, the reroute database isn't used. This must be set of you intend to set the file attribute to point to a database.

bounceonly
    type: boolean

    This attribute combines with the matchlocal attribute to do limited re-routing that bypasses multiple occurrences of the local host, but only for bounce messages (messages generated for returning errors to the originator of a message). This attribute affects only the use of the matchlocal attribute, and has no other affect on the rerouter driver.

The rerouter driver operates only on pure !-path addresses. For such addresses, the !-path is scanned from right to left for hostnames that are considered candidates for re-routing. If such a host is found, the path is truncated to contain everything from that component to the end of the path. In the case of a match resulting from the matchlocal attribute, the matching component is also removed from the path.

Given a truncated path generated by the rerouter driver, the address is passed back into the smail address resolver engine to be routed based on the other routers. This goes all the way back to the beginning of the address resolution process, rather than continuing on with the list of routers, as would happen for a non-matching target hostname.

  The Rerouter Database Format
If a database file is used to define candidate hosts for re-routing, the file will be presumed to contain entries consisting of a hostname or a domain name beginning with a period, followed by `+' or `-'. For example, the database file might contain:

    .do.main        +
    .bar            +
    .foo.bar        -
    host1.foo.bar   +
    host2           +
    host2.abc       +
    host3           +
    host4           +
If a match is found on the given hostname, then the `+' or `-' is used to indicate whether the hostname is a candidate for re-routing. A `+' indicates that the host is a candidate and a `-' indicates that the host is not a candidate.

The rules for finding an entry in the database are:

1.  Look for an exact match of the target hostname. If not found, and the domain begins with a dot, look for a match without the dot.

2.  If that fails, strip the first component of the domain, leaving the initial dot on the second component. Look for a match on the resulting name. Repeat this step until a match is found or no components remain.

This lookup algorithm, together with the `+' or `-' field can be used to enable re-routing for all but a certain subset of hosts within a domain.

  General Recommendations for Rerouter Use
While re-routing can be useful, and can improve the flow of mail through the UUCP zone, it can be disastrous if done wrong.

Here are two situations where it can be useful to reroute mail:

1.  If your site is on the Internet, and it is a backbone for a domain of UUCP sites that are connected to your site, then your site might have access to routing informations that isn't available to the UUCP sites (MX records etc.). Using shortcuts over the Internet instead of sending the mail along the original slow and maybe expensive (telephone charges) path can be a major advantage.

2.  If one or more links that in your direct neighbourhood (one or two hops away) have changed and the new UUCP maps haven't yet propagated widely enough to make other sites aware of these changes, you could use re-routing to temporarily correct the incoming bang paths that were generated from the old maps.

However, before you enable re-routing you should make sure that your routing databases are really truly accurate. It's not enough that you install the posted USENET maps automatically. These maps are notoriously inaccurate, and often contain very unrealistic link costs, resulting in non-optimal routes. Therefore, it is necessary to check all routes that might be used for re-routing line by line whenever it is rebuilt from the maps.

If you can't or don't want to do this, don't use re-routing! Or at least only use it for sites in your direct neighbourhood. Re-routing with a poorly maintained routing database is a disservice to the net! The simplest way to setup re-routing is to limit the set of hosts that you use for re-routing and ensure that the routes to all of those hosts are stable and accurate. Making a separate paths file-based router is the simplest way of ensuring that stable paths are used.

Also, if you think that you have the administrative resources for re-routing, do so only when you are willing to keep in touch with the maintainers of other re-routing sites in your area. Mail loops between two re-routing sites are a serious problem that can be reduced only by discussing changes you want to make to your routing in advance of actually making them.

So in short, folks, don't use re-routing if it isn't absolutely necessary. Please don't use it as a means to inflate your ego. Instead, maintaining a re-routing host is a responsible task that needs lots of time and determination. Please restrain yourself, for the sake of fast and flawless mail delivery.

  Rerouter Hostname Non-Uniqueness
One more point, which is actually an important one, is that hostnames within UUCP-zone are not always unique. Just because you recognizee a hostname on the end of path does not mean that it is the host that you think it is. To avoid conflicts arising from non-unique names it is best to avoid re-routing for hostnames that are not qualified within a domain.

The only safe way to reroute an address is to reroute from left to right rather than right to left, and to stop as soon as a host is found which is not a re-routing candidate. However, such a policy greatly limits the usefulness of re-routing or at least it greatly increases the number of entries in your re-routing database that are necessary for re-routing to be useful.

DEFAULT CONFIGURATION
The default internal routers configuration can be viewed by typing smail -oR /no-such-file -v -bP ROUTERS

The default router configuration is normally something like this:

force_smtp
    a router using the pathalias driver and the always attribute to allow forced routing with the /usr/local/etc/smail/forcesmtp database, and delivery via the smtp transport.

force_paths
    a router using the pathalias driver and the always attribute to allow forced routing with the /usr/local/etc/smail/forcepaths database, and delivery via the uux transport.

rewrite
    a router using the rewrite driver and the always attribute to allow forced rewriting of addresses using the /usr/local/etc/smail/rewrite database.

inet_addrs
    match literals forms of IP internet addresses, deliver with the smtp transport.

bind_hosts
    a router using the bind driver to route using normal Internet DNS MX records and deliver via the inet_zone_bind_smtp transport.

inet_hosts
    a router using the gethostbyname driver to match hosts on an IP network, delivering with the smtp transport.

uucp_neighbours
    a router using the uuname driver to route to direct UUCP neighbours via the uux transport.

paths
    a router using the pathalias driver and a database stored as a sorted ASCII file in /usr/local/etc/smail/paths to route to the UUCP network, delivering via the uux transport.

smart_host
    a router using the smarthost driver, and by default configured to deliver via the uux transport to the host defined by the smart_path attribute.

FILES

/usr/local/etc/smail/routers
    Optional configuration for smail routers, i.e., configured methods for resolving or routing to remote hosts. This file replaces the compiled-in router configuration.

/usr/local/etc/smail/aliases
    A file of aliases for local addresses.

/usr/local/etc/smail/paths
    A file of paths to remote hosts.

/usr/local/etc/smail/lists/
    A directory of mailing list files.

~/.forward
    Lists of forwarding addresses for local users.

/var/log/smail/logfile
    A log of smail transactions.

/var/log/smail/paniclog
    A log of configuration or system errors encountered by smail.

SEE ALSO
smail(5), smailconf(5), smaildrct(5), smailmeth(5), smailqual(5), smailrtry(5), smailtrns(5), smail(8). Smail Administration and Installation Guide. DARPA Internet Requests for Comments RFC 821, RFC 822, RFC 974, RFC 976, and RFC 1123.

BUGS
Colons cannot be included in the value of a list element.

Database files cannot contain ``#'' in the left-hand field.

COPYRIGHT
Copyright (C) 1987, 1988 Ronald S. Karr and Landon Curt Noll Copyright (C) 1992 Ronald S. Karr

See a file COPYING, distributed with the source code, or type smail -bc to view distribution rights and restrictions associated with this software.