Provided by: smail_3.2.0.115-7.1_i386 bug

NAME

       /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 entry 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 smailmeth(5) manual page.

THE ROUTER DRIVERS

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

   The Pathalias Driver
       WARNING: The pathalias router driver is in dire need of a full
       internals rewrite.  It should not be used unless necessary.  Use the
       rewrite router driver instead.

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

       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.

       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.    If not set, and if tryagain is
           also not set, then the message will be frozen in the error queue
           and tagged with a configuration error.

           This option might be useful in a networking environment where
           workstations may be all configured with the same routers file and
           thus have the option of using 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 colon-separated list of domains which the target name is required
           to be within for this router entry to match the target and act to
           route it.  The names are not stripped before the database is
           searched, 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.  If not set, and if optional is
           also not set, then the message will be frozen in the error queue
           and tagged with a configuration error.

           This is useful in a networking environment where failure to open a
           database (such as a remote YP/NIS database) may be a result of the
           database 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 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 driver is
       available only on systems that have a 4.3BSD compatible or newer
       resolver library.  It is highly recommended that this router driver 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 nameserver.  If attempts to connect to the nameserver fail,
           then routing is retried at a later time, on the assumption that the
           nameserver is only down temporarily.  If this attribute is not set,
           then a failure to connect to the nameserver will cause the router
           to be ignored.  This allows a bind router to be optional based on
           whether or not the nameserver 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 unfiltered (i.e. lowest priority) MX resource record
           to be encountered which points to the local host.  If this
           attribute is set, then such an MX resource record will be permitted
           but will be ignored -- i.e. it will cause the address not to be
           matched.

           NOTE:  This attribute is NOT set by default.  If you think you need
           to turn this flag on to make your configuration work the way you
           want then you probably have your router instances in the wrong
           order, so move your UUCP router(s) above the BIND router(s).

           WARNING:  This attribute is deprecated and will disappear in future
           versions of Smail.

       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, which it should normally be by
           default, then match a host only if it has a valid MX record.

           Note that an MX record is only valid if it points to a canonical
           hostname.  See however the descriptions of smtp_bad_mx_targets and
           allow_one_mx_target_cname_hack in smailconf(5).

           If all domain names that can accept mail have an MX record pointing
           to a valid mail exchanger host, then no attempts will made to send
           mail to other ‘‘hosts’’ such as printers or terminal concentrators
           which have only A records.  However RFC 974 still requires that
           SMTP mailers route to hosts without MX records (and indeed far too
           much of the Public Internet still relies on this several decade old
           silliness), so if a router instance using the gethostbyname driver
           follows a router using this driver then Smail can still meet the
           ancient RFC 974 requirements.

           Note that RFC 2821 does not allow an Internet mailer to route to a
           host with an A record if there were also any MX records for that
           same host, even if all those MX records were unusable for any
           reason.  This means that a router using this bind driver MUST occur
           before any instance of any router using the gethostbyname driver if
           Smail is to conform with this requirement.

           NOTE:  This attribute is set by default.

           WARNING:  This attribute is deprecated and will disappear in future
           versions of Smail.

       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.  Negative matches can be forced by preceding the
           domain with an exclamation mark (!).

           For example 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:
           mx_domains = ‘‘!york.ac.uk:ac.uk’’

       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’’.

           WARNING:  This attribute is deprecated and will disappear in future
           versions of Smail.

       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 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 that RFC 2821 does not allow an Internet mailer to route to a
           host with an A record if there were also any MX records for that
           same host, even if all those MX records were unusable for any
           reason.  This means that a router using the bind driver MUST occur
           before any instance of any router using this gethostbyname driver
           if Smail is to conform with this requirement.

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

   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 driver 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 in exactly
       the same way as in the pathalias router: domain, file, interval,
       optional, proto, required, retries, reopen, tryagain.

       The algorithm of the rewrite router driver 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@$host"}}

       Note the last entry, with the double quotes, 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.

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

       The rerouter driver also supports the following unique private
       attributes:

       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 Driver 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:

       rewrite
              a router using the rewrite driver and the always attribute to
              allow forced rewriting of addresses using the /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.

FILES

       /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.

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

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

       /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.