FreeBSD Manual Pages
SMAILRTRS(5) Local SMAILRTRS(5) NAME smailrtrs - /usr/local/etc/smail/routers: Smail router configuration THE ROUTERS FILE The routers file describes the operations, and their order, for han- dling 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 do- main name. For example, if a routing database has a route to the domain ``amdahl.com'' but not to the domain ``futatsu.uts.am- dahl.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 prefer- ence 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 ei- ther 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 inter- nals 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 data- base. 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 work- stations may be all configured with the same routers file and thus have the option of using a private alias file, without the neces- sity 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 as- sociated with the key, separated by a colon or whitespace. dbm Use the BSD dbm(3x) or ndbm(3x) [or db(3x) ndbm emulation] rou- tines 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) data- base. NIS+ is not compatible with NIS (otherwise known as YP). The file parameter must be a NIS+ indexed name, which is de- scribed in the nis(1) manual page. The search string is re- placed 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 inde- pendent 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 at- tributes, 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 re- quired 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 dis- agreement 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 attrib- utes, 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 re- fresh 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. Op- tionally, 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 al- ways executed as an unprivileged user. The queryprogram driver supports the domain, required, and try attrib- utes, as defined in the description of the pathalias driver. The pro- gram and its arguments are described in terms of a cmd attribute which is a string consisting of white-space-separated tokens which are ex- panded to form a program name and the arguments to pass to that pro- gram. 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 at- tribute 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 pro- gram. If the read_path attribute is also enabled, then the trans- port 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 gen- eral, 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 ex- plicit 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 IN- ADDR_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 re- solve target domain names. It is fully compliant with the RFC 974 and RFC 1134 standards, and uses MX records. This router driver is avail- able 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 er- ror 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 or- der, 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 net- work 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 do- main 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 rea- son. 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 do- main 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_do- mains = ``!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 con- sisting 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 regis- tered in the DNS for that address. Similarly, mail for the domains ``bitnet'', ``ie'', and ``earn'' will be routed to ``earn-re- lay.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 depend- ing 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 us- ing 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 the do- main and required attributes, which work the same way as 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). The stripping of any domain matching a string listed in the domain attribute is done first so hosts that have a domain com- ponent matching any one of the strings listed in the domain at- tribute will still be ``matched'' by this router and will be looked up. This attribute might be used to ensure only unqualified names be searched for in the /etc/hosts file and thus allow for routing of local e-mail even when the DNS is unavailable. However if other local SMTP peers do any reverse-DNS checking the values resulting from /etc/hosts lookups will likely fail consistency checks on all known systems. Note the hostname passed to the transport will be the host returned in the h_name field of the hostent structure returned by the gethostby- name(3N) library routine. This means the traditional hack of including unqualified names first in the entries in the /etc/hosts file will re- sult in the name not being properly qualified. Ideally of course un- qualified names should never be used anywhere except by human users on their command lines and software should always qualify such hostnames as early as possible and from there on deal with those names internally in their fully qualified form. 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 (without only_local_domain) 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 attributes: host type: string Specifies the next host to which the message should be sent. NOTE: This attribute is deprecated and should no longer be used. route type: string Specifies the route by which the next host can be reached. NOTE: This attribute is deprecated and should no longer be used. path type: string If the host and path attributes are not set then this attribute de- fines a host or UUCP-style `!'-path path that will be parsed to de- fines the smart host. Note there is no allowance for any variable expansion, i.e. the path must not end in ``%s'' as is done with the paths used by the pathalias driver. If no transport or method attribute is given for this router file en- try, 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. In configurations supporting TCP/IP networking the default transport for routers using the smarthost driver is inet_zone_smtp which means that the path should normally be just a hostname. 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. NOTE: At the present time, a transport or method attribute is re- quired, as the software is not yet in place that can rescan the routers in the required ways. 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 With this example a recipient address of ``Ted.Husted.Jr@wall- drug.uucp'' will be rewritten so that the next host's hostname is ``am- dahl'' and the remaining part of the address is ``Ted.Hustead.Jr@wall- drug.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 exam- ple, if the machine ``glotz'' wished to use ``amdahl'' as its smart host, through its neighbouring site ``namei'', it could use: smart_uucp_host: transport=uux, driver=smarthost; path=namei!amdahl It is possible to set the default path and/or the default 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 = namei!amdahl smart_transport = uux Then, since the default smart_host router is essentially just: smart_host: driver=smarthost the configuration would be essentially the same as in the smart_uucp_host example above. A config file containing just smart_path = amdahl and with just the default routers configuration would be equivalent to the first smart_host example above. These config file attributes are used only if the path driver attribute is not given in the smart_host entry. Note also that if the smart_path attribute from the config file is used, the smart_transport will over- ride a transport or method attribute. Note that clients which should only use a smart host and which should never deliver any mail locally can be configured by setting their local config file hostnames and uucp_name attributes to emtpy strings, dis- abling more_hostnames, and finally explicitly setting their pri- mary_name to be their true client hostname (i.e. so that no hostname is considered to be local). The hub machine should then be configured with its more_hostnames list including all of the client hostnames (i.e. so that it treats the client hostnames as if they were aliases for the local host). In an TCP/IP environment the DNS MX records for the clients should of course also point at the hub host. This makes it possible to use the same Smail binary on both a mail hub and all its local leaf clients and have only a very simple config file on the clients. 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, op- tional, 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 entry specifies how to rewrite the address, or whether not to rewrite it at all. If the ad- dress 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 ad- dress, 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 re- mainder was a simple mailbox (user name), and leaving the remainder un- changed if it was more complex. The format field is a string to be variable expanded to produce the rewritten address(es). 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. The result is treated in the same way as the right- hand-side of an aliasfile entry, i.e. it is a field of one or more RFC 822 addresses, and thus unqualified mailboxes will be qualified with ``$visible_name''. For example (assuming ``proto=lsearch''): # rewrite subdomains of "somedomain.example" to a local # mailbox using the local part as a suffix of the # string "special-", but do not rewrite addresses using # a domain part of just "somedomain.example" .somedomain.example + special-$user somedomain.example - # rewrite any sub-domain of example.org to a local # mailbox name made up of the local part followed by # the domain part .example.org + $user-$host # rewrite any sub-domain of example.net to a route to # another host, perhaps one on a private network .example.net + <@somehost.pvt:$user@$host> # look up the local part in the aliases file # "example-aliases" and if not found then fail the # address example.com + ${lookup:user:lsearch{aliases.example} then {$value} else {:fail:"There is no mailbox <$user@$host>."}} # to preserve the local-part from a regular expression # match in the rewrite result use the following entry and # use entries like this in the lookup database file (which # in this example is /usr/local/etc/smail/aliases.expand): # # "woods.*" ${mailbox}@proven.example.com # expand.example.com + ${lookup:user:lsearch{aliases.expand} then {${eval:value}} else {:fail:"There is no mailbox <$user@$host>."}} Note the entries using ``:fail:'' will produce an intelligible bounce thus 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 opti- misation 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 net- work. The rerouter driver supports the following private attributes in ex- actly 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 attrib- utes: 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 exclu- sion 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 fol- lowing the last occurrence of the local hostname is used re-rout- ing. 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 er- rors 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 at- tribute, 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 re- sulting name. Repeat this step until a match is found or no compo- nents 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 do- main. 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 ex- pensive (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 propa- gated 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 notori- ously inaccurate, and often contain very unrealistic link costs, re- sulting 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 actu- ally making them. So in short, folks, don't use re-routing if it isn't absolutely neces- sary. 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: smart_host a router using the smart_host driver and the always attribute, but with no path setting. It will only be activated if the smart_path global configuration variable is set, and of course then all the remaining routers will be ignored so this would only be used to forward mail to a central mail hub. rewrite a router using the rewrite driver and the always attribute to allow forced rewriting of addresses using the /usr/lo- cal/etc/smail/rewrite database. Normally this router must appear first in order for it to work properly. inet_addrs a router using the gethostbyaddr driver to match literals forms of IP addresses, delivering with the smtp transport. A router using the gethostbyaddr driver should always come be- fore any router using the bind driver so as to avoid trying to look up literal IP addresses in the DNS. bind_hosts a router using the bind driver to route using normal Internet DNS MX records and deliver via the inet_zone_bind_smtp trans- port. inet_hosts a router using the gethostbyname driver to match hosts on an IP network, delivering with the smtp transport. Although on many systems the gethostbyname driver may search the /etc/hosts file before searching the DNS for host domain names, all routers using this driver MUST come after all the routers using the bind driver in order to force the proper, and RFC-man- dated, order of searching for MX records first. Delivering e- mail directly to a host domain name instead of its listed MX is not likely what's desired and may even introduce privacy issues. uucp_neighbours a router using the uuname driver to route to direct UUCP neigh- bours via the uux transport. 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 Instal- lation 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 soft- ware. Smail-3 RELEASE-3_2_0_121 SMAILRTRS(5)
NAME | THE ROUTERS FILE | THE ROUTER DRIVERS | DEFAULT CONFIGURATION | FILES | SEE ALSO | BUGS | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=smailrtrs&sektion=5&manpath=FreeBSD+8.2-RELEASE+and+Ports>