SMAIL(5)

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

SUMMARY
/usr/local/etc/smail/config - see smailconf(5)
/usr/local/etc/smail/qualify - see smailqual(5)
/usr/local/etc/smail/directors - see smaildrct(5)
/usr/local/etc/smail/routers - see smailrtrs(5)
/usr/local/etc/smail/transports - see smailtrns(5)
/usr/local/etc/smail/retry - see smailrtry(5)
/usr/local/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 begin with a character in column 1 that is not white space or the character `#'. Entries 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 character `_'.

String values may be enclosed in double quotes, in which case backslash escapes are processed as in C. 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 `.

Numbers are as in C, with a prefix of 0 specifying an octal constant and a prefix of 0x specifying a hexadecimal constant. 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.

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

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.

user
addr
    a user name or remaining address string associated with an address.

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

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:

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.

shquote
    make the whole string single quoted (i.e. one shell argument), and properly escape any internal quote characters. This tidies up a string 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
and:

    smart_user="|/local/sbin/phquery -f ${shquote:sender} ${shquote:user}"
with a $sender value of ``foo';rm /etc/passwd'' and a $user value of ``got ya!'' will become:

    |/local/sbin/phquery -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:

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

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

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

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

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

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

/var/spool/smail/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/spool/smail/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/spool/smail/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). 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.

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.