The base standard for the format of the aliases and forward files should be the format used by the BSD sendmail program. This format is simple yet powerful enough for most needs.

A sendmail-compatible aliases file consists of relations between alias names and the lists of entities to that the aliases expand. Each entry is of the form:

    alias-name:   address, ...

If an aliasinclude director (see the sub-section The Mailing-list Drivers below) is defined then any address may also be of the form

    :include:/pathname/to/list/of/addresses

The following is a sample alias file for a machine nsavax:

    # Sample aliasing file for nsavax 
    #
    # redirect root's mail 
    root: brown, casey
    #
    # mail sent to MAILER-DAEMON should go to postmaster
    MAILER-DAEMON: postmaster 
    #
    # brown maintains netnews and mail 
    postmaster: brown
    netnews: brown 
    #
    # copy fawn on all north's mail
    north: north, fawn
    #
    # post important information to network 
    msgs: local-msgs@ciacray, local-msgs@nscprofs, local-msgs@nsavax
    local-msgs: "|/usr/ucb/msgs -s"     # deliver to msgs program
    #
    # administrivia
    rnews: "|/usr/lib/news/uurec"       # read news messages from mail
    #
    # mailing lists for accessing users on the local network 
    nsavax-users:    :include:/usr/lib/mail/nsavax-users 
    ciacray-users:   :include:/usr/lib/mail/ciacray-users 
    nscprofs-users:  :include:/usr/lib/mail/nscprofs-users
    #
    # mail to everybody on the local network 
    everybody: nsavax-users, # well, almost everybody
               ciacray-users,
               nscprofs-users
    #
    # save mail to mailing list requests and send to moderator 
    funding-request: /usr/log/funding-req, reagan@nscprofs 
    covert-bugs-request: /usr/log/covert-bugs-req, james.bond@ciacray
    #
    # broadcast to mailing lists, and save a copy 
    funding:    # excludes congress    
                :include:/usr/list/funding, 
                # save all messages here 
                /usr/log/funding
    #
    covert-bugs: # includes kgb 
                 :include:/usr/list/covert-bugs, 
                 /usr/log/covert-bugs # save all messages here

It has the following driver attributes:

file

type: string

Define the name of the file containing the database. Except when this is not appropriate for the proto being used, if this does not begin with a slash (``/''), it will be referenced relative to the smail_lib_dir directory.

interval

type: number

A sleep interval between open retries, in seconds. On systems which have one second granularities on wakeup times and where, as a result, sleep times can be nearly 0 seconds, this number should be at least 2.

modemask

type: number

A mask, ala umask(2), defining the maximum permissiveness allowed for the permissions on the alias file. For example, a modemask of 022 disallows write access to all but the file owner. This value should be chosen to strike a reasonable compromise between security and user convenience. It should also take into account the use of the owners and owngroups attributes described below. A paragraph below describes the consequences for a file not meeting this criteria.

optional

type: boolean

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

owners

type: string

A list of permissible owners for the alias file. A paragraph below describes the consequences for a file not meeting this criteria.

owngroups

type: string

A list of permissible owning groups for the alias file. A paragraph below describes the consequences for a file not meeting this criteria.

proto

type: string

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

reopen

type: boolean

If this attribute is on, the alias file will be closed and reopened after each call to the driver. This is useful for systems that have a shortage of file descriptors yet wish to access a large number of databases.

retries

type: number

the maximum count of open retries. This should be greater than zero if the system does not have an atomic rename(2) system call, as the alias file may not always exist while being modified.

tryagain

type: boolean

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

If any of the attributes modemask, owners, or owngroups reject the file as a possible security problem, all addresses returned are flagged with the caution bit set. See the generic director attribute nobody for more information.

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

bsearch

Use a binary search to look through a sorted file arranged as lines which begin with a key and are followed by the value associated with the key, separated by a colon or whitespace. The file should be sorted by the key, not by the line. The mksort(8) utility sorts lines correctly. Care should be taken when using the regular sort(1) to ensure that the sort uses proper delimiters.

dbm

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

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.

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:'' part is optional and defaults to the default YP domain for the local host.

nialias

Use the NeXT NetInfo database, for getting user aliasing information.

nisplus

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

    # search for alias expansions stored in a NIS+ database 
    nisaliases:
            driver = aliasfile;
            file = "[alias=%s],mail_aliases.org_dir", 
            proto = nisplus

The lookup routine within smail allows you to choose which field to get from the NIS+ database by prepending the file with a string like ``@2,''. That example would use field number 2 from the table. The default action, as in the nisaliases example above, is to use field 1. (Field 0 is usually the index value.)

Though you wouldn't necessarily want to do this, the following example allows you to send mail to all the members of groups in your NIS+ group list as if each were a separate mail list.

    # use NIS+ groups as mail lists
    nisgroups:
            driver = aliasfile;
            file = "@3,[name=%s],group.org_dir", 
            proto = nisplus

A simple entry in the director file is:

    # don't perform any authentication on the alias file 
    aliases: driver=aliasfile;
            file=/usr/lib/aliases, proto=dbm

Sendmail-compatible forward files have the same structure as mailing lists. This format is:

    address, address, ...

If a forwardinclude director (see the sub-section The Mailing-list Drivers below) is defined then any address may also be of the form

    :include:/pathname/to/list/of/addresses

An example forward file for the user ``james.bond'' on the host ``nsavax'' is:

    # send to my own machine, but keep a copy here 
    # just in case it doesn't make it there. 
    bond%british-ss@ciacray, james.bond

    "|$HOME/bin/gone-fishing myuserid"

    #! /bin/sh
    :
    cat > /dev/null
    mailx -s 'Yep, gone fishing' \"$SENDER\" < $HOME/.fishing.msg

In the above script the variables shown are available from the command's environment. See the smailtrns(5) manual page for list of the available environment variables.

Also note that some value unique to the user should appear on the command line. This will ensure that if a given message is delivered to more than one user who uses the same command line then each will indeed receive a copy. If the command lines were identical duplicate delivery suppression done by smail would cause only one user to receive a copy of the message.

The current list of private driver attributes for the forwardfile driver is:

caution

type: string

This string defines a list of users and directories which should cause addresses to be flagged with the caution bit.

Each entry in the list is expanded individually. If this string expansion fails, it is ignored.

A number, or a number range (in the form low_number-high_number) can be used to indicate numerical user-ID numbers that should be treated with caution. Typically, this string is ``0'', thus preventing file and shell command from being performed as the superuser, or ``0-99'' to prevent access with any so-called ``system'' ID.

checkowner

type: boolean

If set, then one of the permissible owners will be the user-ID associated with the address (in addition to any listed in the owners attribute).

file

type: string

The name of a file containing the forward information for a user. This string will be expanded with the local name passed to the director available as $user and any associated home directory available as $HOME. If this string expansion fails, it is ignored.

forwardto

type: boolean

If set, then the file must begin with ``Forward to '' to be considered a forward file. Also, only the first line is scanned for addresses. This ``feature'' mimics the capability found in some systems for storing forwarding information in user mailboxes.

lock

type: boolean

Makes the director lock the file before reading it (assuming that your Unix supports locking of files for reading).

modemask

type: number

A mode mask defining the maximum permissiveness allowed for the permissions on a forward file. Analogous to the modemask attribute for the aliasfile driver.

prefix

type: string

This attribute requires that an address begin with the specified string to be matched by the director. Any use of the $user variable in the file or owner attribute will expand with this prefix already removed.

suffix

type: string

This attribute requires that an address end with the specified string to be matched by the director. Any use of the $user variable in the file or owner attribute will expand with this suffix already removed.

Both a prefix and a suffix attribute can be specified for a forwardfile director instance. In this case both the prefix and the suffix strings are required to match for the director to match an address.

owners

type: string

Specifies an optional colon-separated list of users who may own the forward file (in addition to the user-ID associated with the address if the checkowner attribute is also set).

owngroups

type: string

Specifies an optional colon-separated list of groups who may own the forward file.

unsecure

type: string

This string defines a list of users and directories which should cause addresses to be flagged with the unsecure bit. This will prevent delivery to pipes or files. Each list entry is expanded. If this string expansion fails, it is ignored. A number, or a number range (in the form low_number-high_number) can be used to indicate numerical user-IDs that should be treated with caution.

If none of the attributes owners, owngroups, or checkowner is given, no checks are made on ownership restrictions. The default modemask is 0, effectively disabling checks for file mode restrictions.

NOTE: Unless the file attribute references $HOME or begins with the string ``~/'' the forward file driver can be used to provide forward files for users or names that are not listed in the passwd file. In this case $user merely expands to the address passed to the forwardfile driver. This feature can be used for setting up forwarding for obsolete accounts or mailing list directories.

An example of useful forwardfile director entries are:

    # Put forwarding addresses for obsolete accounts under 
    # the /u/obsolete directory.  These will contain only 
    # forwarding addresses.  This is maintained by users in 
    # the group "admin" or "staff".
    #
    obsolete:
            driver=forwardfile;
            file=/u/obsolete/$user,
            owngroups=admin:staff

    #
    # Handle per-user forward files in each user's home 
    # directory.  This is roughly compatible with BSD 
    # sendmail, though performs some access checks, and 
    # is very cautious of directories which are remotely 
    # accessible.  ~/.forward entries for root, uucp, and
    # daemon will operate from the nobody uid.  Root may
    # also own a user's ~/.forward file.  The ~/.forward
    # files must not be group or world writable.
    #
    dotforward:
            driver=forwardfile, nobody;
            file=~/.forward, unsecure=~uucp:~ftp, 
            caution=root:uucp:daemon, checkowner, 
            owners=root, modemask=022

    # 
    # allow the "Forward to " feature to be used from user 
    # mailbox files as used in AT&T UNIX System V. 
    #
    forwardto:
            driver=forwardfile, nobody;
            file=/usr/spool/mail/$user, caution=root, 
            checkowner, modemask=002

    # 
    # define a mailing list directory, with any shell commands 
    # executed under the nobody user-ID. Any file in this 
    # directory defines the name and contents of a mailing list. 
    # 
    lists:
            driver=forwardfile, caution, sender_okay,
            owner="owner-${strip:lc:user}";
            file=/usr/lib/smail/lists/${strip:lc:user}

Mailing-list drivers match addresses of the form

    :include:/pathname/to/list/of/addresses

The mailing list file is given by the pathname following the :include: prefix string.

Mailing-list drivers come in two forms, one form for mailing-lists derived by aliasing drivers (aliasinclude), and another form for mailing-lists derived by forwarding drivers (forwardinclude). The reason for having two forms is that security options take different forms depending on where mailing-lists come from. Also, by having them separately recognised it is possible to allow pipes and files in mailing-lists from alias files but not from forward files. Note that if a new driver is written that does not comply to the standards for alias drivers and forwarding drivers, and that can produce mailing lists, a new mailing-list driver may need to be written for it as well.

The format of a mailing list file is the same as that of a forward file: a simple list of addresses, with optional comments.

The driver attributes are common to both of the mailing-list drivers:

copyowners

type: boolean

If set, attributes related to ownership restrictions are taken from the director which produced the mailing list address.

copysecure

type: boolean

The modemask is copied from the director which produced the mailing list address.

interval

type: number

The sleep interval, in seconds, between retries. For some systems that have one second timing granularity, this number must be at least 2 to guarantee a non-zero sleep interval.

match_director

type: string

Names the specific director that this entry matches expansions of. This can be used to assign different attributes from alternate uses of the aliasfile and forwardfile directors.

modemask

type: number

The maximum permissiveness of file modes.

owners

type: string

A list of allowed owners.

owngroups

type: string

A list of allowed owning groups.

retries

type: number

The maximum count of open retries.

The user director driver routes mail to local users. When the mailbox name matches the username a director instance using this driver will mark this address as fully-resolved and tag it with a transport name.

The user driver's attributes are:

prefix

type: string

The prefix attribute specifies a regular expression which must match at the beginning of the mailbox name. The string matching the prefix is removed from the mailbox name prior to determining if the remaining string matches a valid username on the local host. If the remaining part of the mailbox does match a local username then the matching prefix string will be saved in the $user_prefix variable, as well as being exported in the MBOX_PREFIX environment variable by any transport using the pipe driver. Note that on systems with POSIX RE libraries case is ignored if the ignore-case attribute is set.

suffix

type: string

The suffix attribute specifies a regular expression which must match at the end of the mailbox name. The string matching the suffix is removed from the mailbox name prior to determining if the remaining string matches a valid username on the local host. If the remaining part of the mailbox does match a local username then the matching suffix string will be saved in the $user_suffix variable, as well as being exported in the MBOX_SUFFIX environment variable by any transport using the pipe driver. Note that on systems with POSIX RE libraries case is ignored if the ignore-case attribute is set.

transport

type: string

The name of the transport instance to associate with an address if this director matches the address to a local username.

ignore-case

type: boolean

If set, the user director driver ignores the case of the username when matching. Note that names from the password file are lowercased when they are inserted into the internal username cache, so unless you wish to bounce mail when the address contains upper-case characters, this attribute should always be set, and it is set by default.

A typical user director entry in the director file is:

    user: driver=user; transport=local

The altuser director directs mail to a mailbox for known user on the local host as per the user director, but using an alternate file with a format like that of /etc/passwd. This file may be accessed by any of the standard search methods, and so the interface looks just like that of aliasfile. This director succeeds if the local address matches a user in the alternate passwd file and will put an entry on the list of fully-resolved addresses.

The driver attributes are:

pwfile

type: string

The name of a file which contains the key/value association database.

proto

type: string

Names the protocol used in opening and searching the database. Possible values are bsearch, lsearch, or dbm , with the same meanings as for these attributes in the aliasfile driver.

modemask

type: number

A mask, ala umask(2), defining the maximum permissiveness allowed for the permissions on the pwfile. For example, a modemask of 022 disallows write access to all but the file owner. This value should be chosen to strike a reasonable compromise between security and user convenience. If some of these bits are set, the secure flag is not set for the related addresses. It should also take into account the use of the owners and owngroups attributes described below.

owners

type: string

A list of permissible owners for the pwfile. If the pwfile is owned by another user, the caution bit is set for the returned addresses.

owngroups

type: string

A list of permissible groups owners for the pwfile. If the pwfile is owned by some other group, the caution bit is set for the returned addresses.

retries

type: number

The maximum count of open(2) retries. This should be greater than zero if the system does not have an atomic rename(2) system call, as the pwfile may not always exist while being edited, etc.

interval

type: number

The sleep interval, in seconds, between retries of the pwfile open. For systems that have one second timing granularity, this number must be at least 2 to guarantee a non-zero sleep interval.

The private driver attribute flags are:

reopen

type: boolean

If this attribute is on, the alias file will be closed and reopened after each call to the driver. This is useful for systems that have a shortage of file descriptors yet wish to access a large number of databases.

tryagain

type: boolean

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

It may be that you wish all local addresses that you don't recognise to be sent elsewhere. For example, there could be a host in your domain that knows where most of the domain's users reside. The smartuser driver is a convenient way of handling this case, by redirecting mail for unknown users to another host. Note that this must be the last director entry, if it is used, because it is generally non-discriminatory.

The possible driver attributes for the smartuser driver are:

new_user

type: string

This defines the new address to direct mail to. This string will be string expanded with $user set to the local address name, and with $HOME being any the associated home directory, if there is one. It is a configuration error for this string expansion to fail.

It is possible to set the new_user value in the config file. This is done by setting the config attribute called smart_user to a valid e-mail address, possibly including an expansion of the $user variable. For example, the config file could contain the following line:

    smart_user = $user@gateway.domain

WARNING: Do not forget the quoting rules if you set smart_user to a pipe command. The contents of variables such as $user, $sender, etc., are under the control of the remote user. If this string is passed to the pipe transport and thus to a shell command line it is extremely important that expansion of these variables be very carefully protected by proper shell quoting.

For example:

  new_user="|/local/sbin/phquery -f ${shquote:sender} ${shquote:user}"

Note also that if this command is itself a script it must also treat the values of these arguments as potentially containing meta characters and such. Similarly for any program which may pass these values on to another via another shell comamnd line.

well_formed_only

type: boolean

If set, the smartuser driver only matches an address if it contains characters exclusively from the set of letters, digits, whitespace, as well as `-', `_', `+', and `.'.

If the well_formed_only attribute is on, any use of the $user variable in the new_user value will have any groups of one or more whitespace characters or ``.'' characters collapsed into exactly one dot. If it is off, the $user value may be enclosed in double-quotes, with backslash escapes where appropriate. This prevents the the value of $user from changing the form of the address.

transport

type: string

If set, this defines a transport that unknown user's mail is passed to. This would be useful for either passing to a program that really can deliver the mail, or alternatively specifying a transport (probably a piped program), which can generate a more detailed error message and help information than the default smail diagnostics. The well_formed_only and new_user attributes work as detailed above - if no new user is specified by either new_user or the system smartuser configurations, then the user is passed on unchanged.

prefix

type: string

The prefix attribute specifies a regular expression which must match at the beginning of the mailbox name. the matching prefix string will be saved in the $user_prefix variable, as well as being exported in the MBOX_PREFIX environment variable by any transport using the pipe driver. Note that on systems with POSIX RE libraries case of the prefix string is ignored.

suffix

type: string

The suffix attribute specifies a regular expression which must match at the end of the mailbox name. The matching suffix string will be saved in the $user_suffix variable, as well as being exported in the MBOX_SUFFIX environment variable by any transport using the pipe driver. Note that on systems with POSIX RE libraries case of the suffix string is ignored.

A sample entry is:

    smartuser:
            driver=smartuser;
            new_user=$user@gateway.domain,
            well_formed_only

    john

    John Q. Public

    john@gateway.domain

    John.Q.Public@gateway.domain

    "John Q. Public"@gateway.domain

    \unusual"address"in\deed

    "\\unusual\"address\"in\\deed"@gateway.domain