Provided by: smail_3.2.0.115-7_i386 bug

NAME

       config, directors, routers, transports, retry, qualify - configuration
       files used by smail

SUMMARY

       /etc/smail/config - see smailconf(5)
       /etc/smail/qualify - see smailqual(5)
       /etc/smail/directors - see smaildrct(5)
       /etc/smail/routers - see smailrtrs(5)
       /etc/smail/transports - see smailtrns(5)
       /etc/smail/retry - see smailrtry(5)
       /etc/smail/methods/ - see smailmeth(5),

DESCRIPTION

       The config, qualify, directors, routers, transports, and retry files
       describe the rules used by smail(8) in processing and delivering mail.
       The actual paths show above may differ from system to system (though
       the values given in this manual should be correct for the system it was
       installed on) and, in addition, the paths to these files may be changed
       in the config file or possibly on the command line.

       Smail is compiled with a default configuration.  This default
       configuration is suitable for many sites that communicate to other
       systems via UUCP, or SMTP.  For such sites, no configuration files are
       necessary, though it may still be convenient to have a simple config
       file to set some attributes described in the smailconf(5) manual page.
       See the smail(8) manual page for instructions on viewing the current
       configuration, including all of the default values.

COMMON FORMAT CONVENTIONS

       In all files used by smail, entries or variable definitions begin with
       a character in column one that is not white space or the character ‘#’.
       Entries (and variable definitions) continue until the next line which
       begins with a character other than white-space or the character ‘#’, or
       until the end of the file is encountered.

       Comments begin with the character ‘#’, in any column and end at the
       next newline.  A ‘#’ in the first column does not signify the end of an
       entry.

       Variable and attribute names in configuration files are formed of
       characters from the set of letters, numbers and the underscore
       character (_).

       Entries in the directors, routers, and transports, files consist of an
       entry name, followed by a colon character, and then a group of comma-
       separated, named, attributes which are assigned values with a type of
       string, number, or boolean.  Each group of attributes is optionally
       split into two sub-groups by a semicolon separator character.

       Multi-line un-quoted attribute definitions can be created by putting a
       backslash (\) as a continuation marker at the end of the line.  The
       newline and any whitespace at the beginning of the next line will be
       ignored and the value will be concatenated directly with no separation
       to the value(s) from the previous line(s).

       Configuration variable definitions in the config file are parsed
       similarly to entries in the other files and continue until the next
       non-comment line without leading whitespace, but consist only of a
       variable name, optionally followed by an equals character (=) and then
       the value (optional whitespace around the ‘=’ is ignored).  Thus they
       can also be assigned values with a type of string, number, or boolean.
       The special characters used to separate attributes and groups of
       attributes in entries are allowed un-quoted in variable string values,
       and thus these values may continue on multiple lines unquoted without
       using a backslash (\) continuation character.

       String values may be enclosed in double quotes, in which case backslash
       escapes are processed as in the C language, with the exception of a
       backslash at the end of a line wich causes leading whitespace on the
       next line to be ignored (i.e. not included in the value, just as if it
       were unquoted).  If string values are not enclosed in double quotes,
       the values are limited to characters from the set of letters, digits
       and the characters ! @ $ % ^ & * - _ + ~ / ? | < > : [ ] { } . ’ and ‘.
       Space, tab, semicolon (;), and comma (,) characters are also allowed in
       unquoted string values in the config file.

       Number values are interpreted as in the C language, with a zero (0)
       digit prefix specifying an octal constant and a prefix of ‘0x’
       specifying a hexadecimal constant, and otherwise being interpreted as
       base-ten integers.  In addition, a suffix of ‘k’ or ‘K’ specifies a
       multiplier of 1024 and a suffix of ‘m’ or ‘M’ specifies a multiplier of
       1048576, or 1024K.

       Boolean values are assigned by prefixing a leading ‘+’ character to the
       attribute name to give it a value of true, and a leading ‘-’ character
       to give it a value of false.  Just giving the attribute name with no
       prefix character also gives it a value of true.

   Item Lists
       Some variables and attributes with the type of string are really lists
       of items (such as hostnames, hostname regular expressions, IP
       addresses, etc.).  Lists are normally simply colon (:) separated
       values.  Generally the colon may be preceded and/or followed by
       arbitrary whitespace, though of course in an attribute value (i.e.
       anywhere except in the config file) this means the value must be quoted
       or the whitespace characters must be each escaped with a backslash (\).

       In some cases an optional semicolon (;) separated sub-field may be
       given to given with an item value as well.  In that case the first sub-
       field is the primary item value and the second sub-field is, in most
       cases, a string treated as an error message or other descriptive text
       to be associated with the item.  Note that the message text is not
       quoted (and is not separately quotable) so it must not contain another
       colon (‘:’) character.  Escape processing as described above cannot
       protect a field separator.  Note that in an attribute definition (i.e.
       anywhere except in the config file, though currently no attributes
       allow sub-fields) if you use the semicolon separator to specify a sub-
       field then you must either escape it with a backslash or enclose the
       entire attribute definition in double quotes.  The text message may
       contain semicolons itself though since it extends to the end of the
       field (i.e. to the next colon (‘:’) character).

       Items in a list of hostnames or IP addresses may be negated by
       prefixing them with an exclamation mark (!).  When some value is being
       compared to the items in the list then a match of a negated item will
       cause the remainder of the items in the list to be ignored and for a
       no-match condition to be immediately indicated (thus implementing a
       ‘‘first match wins’’ algorithm).  For example in a list of IP addresses
       the following would match any address in the range 10.0.0.0 through
       10.255.255.255 except 10.1.1.1:

           ! 10.1.1.1 : 10/8

   IP and IP Network Address Representation
       As mentioned above some lists may contain strings representing IP
       addresses.  They are specified in a format compatible with
       inet_net_pton(3).  Generally speaking this means a host may be
       specified in the standard four-octet ASCII form, and any CIDR network
       may be specified by a four-octet number follwed by a slash (‘/’) and a
       number specifying the number of bits in the network portion.

       The magic keyword localnet represents a run-time generated pattern
       constructed to represent the classical IP network for the local address
       of the current connection.  This keyword is of little use to anyone
       using either a supernet, or a subnet of anything larger than a Class C
       (/24) network.

       Optionally if smail has been compiled with ‘‘HAVE=LIBWHOSON’’ then
       there is also support for a magic keyword whoson which can be used to
       query a WHOSON server for additonal IP numbers which are currently
       authorised to relay mail remotely via SMTP.

   Hostname Regular Expressions
       As mentioned above some lists may contain hostname regular expressions.
       These are simply regular expression strings which are matched against
       hostnames.  The expression is implicitly anchored at the beginning and
       end of the hostname.

       Note that the backslash character (‘\’) must be quoted with itself
       since it is also the escape character for all configuration entries.

       Note that a case-insensitive match is always done if the host
       platform’s underlying regular expression library is POSIX compliant.

STRING EXPANSIONS

       Some string values will be variable and filename expanded before being
       used.  When this is done, certain substrings, beginning with a ‘$’,
       will be replaced by the value of the corresponding smail variable.  The
       names of expansion variables are either a single character, or are
       multiple characters from the set of letters, digits, and underscore.  A
       variable name can also be enclosed between ‘{’ and ‘}’ characters, to
       isolate the variable name from the surrounding text.

       In addition to variables, a number of meta-expansions modifiers can be
       used.  These expansions take the form:

           ${meta_name:name}

       where meta_name defines some modifier operation to perform on the value
       of the variable name.  Multiple modifiers can be specified, and they
       are processed from right to left.  For example:

           ${lc:strip:user}

       This strips quotes from the value of the variable user and then
       converts characters to lower case.

       When a string to be expanded begins with the character ‘~’, a home
       directory is substituted.  If only ‘~’ is given, or ‘~/’ is given, then
       the home directory associated with an address is substituted.  If the
       form ‘‘~username’’ is given, where ‘‘username’’ is the name of a user
       on the local host, that user’s home directory is substituted.

   Conditionals
       Conditionals can be used to include text based on whether or not a
       particular value is non-empty.  Conditionals are of the form:

           ${if condition [:] string}

       or

           ${if condition {string1} {string2}}

       The first form includes string if the condition is true.  The second
       form includes string1 if the condition is true, or string2 if the
       condition is false.  For readability, the word else can be inserted
       before the second clause.

       Possible conditions are:

       !condition
           Negate the boolean value of condition.

       def:variable
           True if the given expansion variable is defined and is non-empty.

       header:header
           True if the message contains a header field named header.

       origin:local
           True if the message originated locally.

       origin:remote
           True if the message was received from a remote machine.

       dest:local
           True if the message is being delivered to an address on the local
           host.

       dest:remote
           True if the message is being delivered to a remote host.

       xform:transformation
           True if the transformation being applied to the message, for
           delivery by the assigned transport, matches the given type.  Valid
           types are: local, inet, uucp, or none.

       eq{variable}{string}
           True if the given expansion of variable matches the given string.

       gt{variable}{string}
           True if the given expansion of variable is lexicographically
           greater than the given string.

       lt{variable}{string}
           True if the given expansion of variable is lexicographically less
           than the given string.

       or{{ condition } ... }
           True if any of the given conditions are true.

       and{{ condition } ... }
           True if all of the given conditions are true.

   File lookups
       String expansions can use lookup procedures to convert a key, taken
       from a an expansion variable, into a string found in a file or other
       accessible database.  These expansions are defined using the form:

           ${lookup:variable:proto{file-expansion}\
                  [:]then-clause}

       or

           ${lookup:variable:proto{file-expansion}\
                   [then] {then-clause}\
                   [else] {else-clause}}

       Lookups operate by taking the value of the indicated variable as a key
       for lookup in a file.  The proto string defines how the lookup is to be
       performed, and file-expansion is a string defining the file or database
       to search.  If the key is found, then the then-clause is expanded,
       otherwise the else-clause is expanded.  A $value reference in either
       clause is replaced by the value found by the lookup.  For readability,
       the word then can be inserted before the then-clause, and the word else
       can be inserted before the else-clause.

       Allowed lookup methods are:

       bsearch
              Use a binary search to locate the key in a sorted file,
              organised as lines beginning with a key separated from a value
              by blanks.

       lsearch
              Use a linear search to locate the key in a plain file, again
              organised as lines beginning with a key separated from a value
              by blanks.

              Comments in this file begin with ‘#’ and continue until end-of-
              line.  Blank lines are ignored.

              If Smail has been compiled with
              ‘‘MISC_DEFINES=USE_LSEARCH_REGEXCMP’’ then a line where the
              first field is surrounded in double quotes ("") specifies a
              regular expression (without the quotes) against which the key is
              matched using the host platform’s underlying regular expression
              library.

       dbm    Look up the key in a dbm database.

       yp     Look up the key in a Sun NIS database.

       aliasyp
              Look up the key in a Sun NIS database.  This differs from yp in
              that a NUL byte is added to the end of the key before lookup.

       nialias
              Look up the key in a NeXT netinfo database.

       nisplus
              Look up the key in a Sun NIS+ (Sun NIS Version 3) database. NIS+
              is not compatible with NIS (otherwise known as YP).  The file
              expansion parameter must be a NIS+ indexed name.  The lookup
              routine within smail allows you to prepend the file-expansion
              with a string like ‘‘@2,’’ to use field number 2 from the result
              instead of using field 1 by default.

   Variables
       The complete set of available variable names depends upon context, but
       the following are always available:

       compile_date
       ld_date
           the date when the current smail binary was compiled.

       compile_num
       ld_num
           a decimal number giving the number of times smail has been compiled
           since the creation of the source file src/ldinfo.c.

       ctime
           the date and time, in the form returned by the ctime(3) function.

       date
           The date and time in ARPAnet (RFC 822) format.

       spool_date
           The date and time that the message was received by the local host,
           in ARPAnet (RFC 822) format.

       grade
           The priority character for the current message.  See the grades
           attribute in the smailconf(X_MAN_5_EXT) manual for more information
           on this value.

       ident_sender
           The identification code of the user that sent the mail over its
           last hop as determined by the RFC 1413 protocol (other protocols
           may be added in future versions).  This will generally only be set
           for mail received by SMTP.  It is most useful for putting into the
           Received: message header field.  This string has a null value if no
           sender-ID can be determined.

       ident_method
           The identification method used to generate the ident_sender.
           Currently this will always be ‘‘rfc1413’’.

           This variable will be null if ident_sender is also null.

       message_id
       id  the message-ID for the current message.

       message_size
       size
           the total size of the spooled message.

       message_body_size
       body_size
           the size of the body of the message, which excludes the message
           header fields, and also excludes any overhead within the message
           spool file.

       pid
       $   the current process-ID.

       primary_name
       primary
           the canonical name for the local host.

       release_date
       release
           the release date of the smail sources.

       sender
       from
           the address of the sender of a message.

       sender_name
       fullname
           the full-name of the sender, taken either from the ‘‘-F’’ command
           line argument, or from the password file.

       sender_host
           the sending host, if one is known.  This is set automatically for
           mail received via UUCP or SMTP.  It can also be set with ‘‘-oMs’’
           from the command line.

       sender_host_address
           the sending host’s address, if one is known.  This is set
           automatically for mail received via SMTP.  It can also be set with
           ‘‘-oMa’’ from the command line.

       sender_proto
           the sending protocol (e.g. ‘‘smtp’’ or ‘‘uucp’’), if one is known.
           This is set automatically for mail received via UUCP or SMTP.  It
           can also be set with ‘‘-oMr’’ from the command line.

       sender_program
           The program that queued the message.  For mail received via UUCP,
           this will be, typically, ‘‘rmail’’.  Otherwise, the sender program
           will likely by set to ‘‘sendmail’’ or ‘‘smail’’, depending upon the
           program that typically is invoked for receiving mail.

       uucp_name
           the UUCP-network name for the local host.

       version
           a short version string for Smail.

       version_string
           a verbose version string.

       visible_name
       name
           the local host name used in outgoing addresses.

       smail_lib_dir
       lib_dir
           the value of the config file variable smail_lib_dir, which is the
           directory in which configuration files are found.

       In addition, the following variables are defined if they are available
       in the current context:

       HOME
       home
           the home directory of a user associated with an address.

       host
           the remote host string associated with a remote address.

       local_domain
           The local domain an address may have matched, if it matched a local
           domain.

       user
       addr
           a user name or remaining local part of the address after all
           rewriting.

       user_prefix
           any string matching the regular expression given in the optional
           prefix attribute of a director instance using the user director
           driver.

       user_suffix
           any string matching the regular expression given in the optional
           suffix attribute of a director instance using the user director
           driver.

       input_addr
           The address specified in the message, or in an alias or mailing
           list expansion, that is being processed.

       mailbox
           The ‘‘local part’’ of the input address.

       route
           Any route specification from the input address.

       director
           The name of the director that matched the address, if appropriate.

       router
           The name of the router that matched the address, if appropriate.

       transport
           The name of the transport to be used for delivering to the address,
           if the address has been successfully resolved.

   Meta-Expansion Modifiers
       The following modifiers are available for meta-expansions.  Note that
       multiple modifiers can be specified and that they are interpreted
       strictly from left to right.

       eval    expand all variable expansions, file lookups, etc. in specified
               variable.  (This is probably only useful when used on the
               command line with -bP.)

       lc      convert to lower case.

       parent  interpret the value within the context of the parent local
               address that produced the associated address.  This is useful
               when the local address that produced an address is desired.
               Expansion fails if no parent exists.

       quote   enclose the value in quotes, if it would not otherwise be a
               valid local-form address, within the rules of RFC 822.  Uses
               backslash escapes as appropriate.

       rxquote make the whole string only match exactly when used as a regular
               expression (RE) by properly escaping any RE meta-characters.
               This can be used when expanding lists of hostnames within other
               lists, for example.

       shquote make the value of a variable into a single quoted string (i.e.
               one shell argument), and properly escape any internal quote
               characters.  This tidies up a variable value that may have been
               supplied from an untrusted source to allow it to be passed to a
               shell command without nasty effects.  Note that you only have
               to use ‘‘${shquote:’’ on string values that will be passed as
               arguments on a shell command line.  In some cases even the pipe
               driver does not use the shell.

       strip   Remove backslashes and double quotes from a value.  If a
               double-quote is preceded by a backslash, the backslash is
               removed, but the double quote is not.  Sequences of whitespace
               characters and dots are converted to exactly one dot character.

       top     interpret the value within the context of the original address,
               supplied to the mailer, that produced the associated address.

       uc      convert to upper case.

       The following are sample string expansions:

           /usr/spool/mail/${lc:user}

       with a $user value of Tron will become:

           /usr/spool/mail/tron

       whereas:

           Received: by $primary_name ($version_string)
                     id <$message_id@primary_name>;
                     $spool_date

       will become something such as:

           Received: by futatsu.uts.amdahl.com (smail 3.0.2 03-dec-87)
                     id <m0c87zK-007zXpC@futatsu.uts.amdahl.com>;
                     Tue, 8 Dec 87 19:45 PST

       and:

           $host!rmail ${strip:addr}

       with an $addr value of ‘‘Ronald S. Karr’’ and a $host value of
       ‘‘amdahl’’ will become:

           amdahl!rmail Ronald.S.Karr

       Another important example

           smart_user="|/bin/mquery -f ${shquote:lc:sender} ${shquote:lc:user}"

       with a $sender value of:

           Foo’;rm /etc/passwd;’

       and a $user value of ‘‘Got Ya!’’ will become:

           |/bin/mquery -f ’foo’"’"’;rm /etc/passwd;’"’"’’ ’got ya!’

       (but he won’t have ‘‘got’’ you because you used ‘‘${shquote:’’!)

       If a value does not exist (such as $HOME being used when no associated
       home directory is known, or when a string begins with ‘‘~username’’ and
       ‘‘username’’ is not a known use, or when $host is used for a local
       address) then the expansion fails.

DIRECTOR, ROUTER AND TRANSPORT FILE FORMATS

       The directors, routers, and transports configuration files share a
       common format, which is described in this section.  The specific
       contents for each file are described in separate manual pages.

       Each entry in one of these files specifies a name for the entry, a set
       of generic attributes and a set of driver-specific attributes.  The
       generic attributes and the driver attributes define the characteristics
       for the entry.

       The list of possible generic attributes are common to all entries in a
       configuration file.  One generic attribute is always required:  the
       driver attribute.  This attribute names the underlying set of internal
       functions that will be used when using that entry.  The list of
       possible driver attributes are specific to each different driver.

       The form of an entry is:

           entry_name:
               generic_attribute, ... ; driver_attribute, ...

       where a comma separates the definitions for specific attributes and
       where a semicolon separates the generic attributes from the driver
       attributes.  It is not an error for an entry to end in a comma or
       semicolon.  The form for generic and driver attributes is the same as
       for entries in the config file.

       As an example, consider an entry in the transport file that specifies
       use of the program /bin/mail to deliver mail to local users.  The mail
       messages are to contain a Return-Path: header field, and the /bin/mail
       program is to be given no more than 20 addresses per invocation.  A
       simple entry to specify this is:

           # call /bin/mail to deliver to local users local:
           max_addrs=20,
           return_path,
           driver=pipe;
           cmd="/bin/mail $($user$)"

INTERACTION BETWEEN DIRECTORS, ROUTERS AND TRANSPORTS

       To better understand the use of the directors, routers, and transports
       this section describes, briefly, how address resolving and delivery is
       accomplished in Smail.  Of course the configuration specified in these
       files is intimately involved in this process.

       When Smail is given a list of addresses to which a message is to be
       delivered, the list is processed iteratively until a list of resolved
       addresses is produced.  When an address is resolved, the transport (the
       part of Smail that performs delivery of messages to local users or
       remote hosts) and all data required by the transport to perform the
       message delivery will be known.

       To accomplish this the Smail program goes through the following steps:

       a.  Each address is parsed to find a domain name, called the target,
           and the remaining part of the address, called the remainder.  As a
           simple example, in the address ‘‘tron@uts.amdahl.com’’, the domain
           part ‘‘uts.amdahl.com’’ is the target and ‘‘tron’’ is the
           remainder.  In the address ‘‘sun!amdahl!tron’’, the target is
           ‘‘sun’’ and the remainder is ‘‘amdahl!tron’’.  More information on
           e-mail addressing forms can usually be found in mailaddr(7).

       b.  Each local address is given to the directors, in the order
           specified by the directors file, until one of the directors says
           that it knows what to do with that address.

           That director has the option of returning a new list of addresses
           or of putting the address on a list of resolved addresses.  If new
           addresses are produced, they are put on the input list, to be
           processed from step ‘a’ again.

       c.  The addresses returned by the directors are classified as either to
           be delivered to some remote host, or locally deliverable.

       d.  Each remote address is passed to the routers, in the order
           specified by the routers file, until one of the routers is able to
           match the target name for the address.  If no router is able to
           match the complete target, then the first router with the longest
           match will be used.  The router specifies the transport to be used
           for delivery to that address, plus some other information required
           by the transport, such as the next_host and next_addr values.  The
           transport may be specified either by a router attribute or it may
           come from a method file.

       e.  When all addresses have been resolved, they are sorted out and
           passed to the transports.  It is the job of the transport to
           deliver a message to the set of addresses that it is handed.

       It is important to note that all domain names (and normally all local
       usernames) are matched independent of case, so that, for example,
       ‘‘Postmaster’’, ‘‘POSTMASTER’’, ‘‘PostMaster’’, and ‘‘postmaster’’ all
       compare equal.

       In addition an internal hash table is kept of all regular recipient
       addresses on a per-transport basis, that is, all addresses which do not
       specify files or shell commands.  This table is used to prevent
       duplicate deliveries.

FILES

       The following files and directories are from a typical smail
       configuration:

       /etc/smail/config
           Optional general smail configuration. This file can override
           compiled-in configuration.

       /etc/smail/transports
           Optional configuration for smail transports; i.e., configured
           methods of mail delivery. This file replaces the compiled-in
           transport configuration.

       /etc/smail/directors
           Optional configuration for smail directors, i.e., configured
           methods for resolving local addresses. This file replaces the
           compiled-in director configuration.

       /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/mail
           The top of the spool directory hierarchy.

       /var/mail/input
           The directory containing messages to be processed and delivered.

       /var/mail/msglog
           A directory of transaction logs for individual messages.

       /var/mail/lock
           A directory used in smail input spool files.

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

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

       /var/mail/error
           Messages that failed due to a small set of fatal error such as a
           configuration error are placed in this directory. Currently the
           site administrator must move these back into /var/mail/input when
           the error condition is resolved.

       /var/mail
           The directory for user mailbox files.

SEE ALSO

       binmail(1), mailx(1) under System V, Mail(1) under BSD, resolver(3),
       mailaddr(7), named(8), pathto(1), smailconf(5), smaildrct(5),
       smailmeth(5), smailqual(5), smailrtrs(5), smailrtry(5), smailtrns(5),
       smail(8).  whosond(8).

       Smail Administration and Installation Guide.

       DARPA Internet Requests for Comments: RFC 821, RFC 822, RFC 974, RFC
       976, and RFC 1123.

       Regular expression documentation for your host, perhaps in
       re_format(7), regex(3), ed(1), or grep(1).

BUGS

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

       Some database files cannot contain ‘‘#’’ in the left-hand field and
       have no other mechanism for introducing comments.

       There should be a way of specifying that different errors encountered
       by smail should result in different actions (i.e., mailing a message to
       the postmaster, storing a detailed error message in a file).

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.