directors -- System Administration

Describe how to resolve local mail addresses
/usr/lib/mail/directors

The program  smail reads file /usr/lib/mail/directors for  the rules on how
to resolve addresses on your  local host.  Please note that under COHERENT,
the default configuration of smail does  not use this file; however, if you
wish, you can create it to change smail's default rules for resolving local
addresses.

Structure of Configuration Files

smail can use five varieties of configuration files:

-> One or  two configuration files,  which perform global  configuration of
   smail-- including naming the other configuration files.

-> One directors  file, which describes  how to deliver mail  on your local
   system.

-> One  routers  file,  which describes  resolve  the  addresses of  remote
   systems.

-> One transports  file, which describes how to move  mail from your system
   to selected remote systems.

-> One methods file, which matches hosts with methods of transporting mail.

smail permits you  to name these files as you  choose; under COHERENT, they
are named as follows:

    /usr/lib/mail/config
    /usr/lib/mail/directors
    /usr/lib/mail/methods
    /usr/lib/mail/routers
    /usr/lib/mail/transports

Each  is  described in  its  own Lexicon  entry.   However, the  directors,
routers,  and  transports file  all  have the  same  format; the  following
describes it.

Each file consists of a set  of entries; each entry, in turn, describes the
attributes of one director, router,  or transport.  The order of entries in
director and  router is  important, in that  the directors and  routers are
invoked  in the  order stated  in the  file.  The order  of entries  in the
transport file is not important.

An entry in one of these files defines the following:

-> A name by which that entry is known.

-> A driver that implements the function for that entry.

-> A set of generic attributes from  a set that can be applied to any entry
   in the file.

-> A set of driver-specific attributes, from a set that can be applied only
   to entries that use the specified driver.

For example, directorsu specifies  the attributes for a director that reads
aliases from a file /private/usr/lib/aliases:

    # read aliases from a file private to one machine on the network
    private_aliases:
        driver=aliasfile, owner=owner-$user ;
        file=/private/usr/lib/aliases

This  entry  is  named  private_aliases,  and  depends upon  the  low-level
director  driver routine  named  aliasfile. Errors  found while  processing
addresses found by this director are sent to an address formed by prefixing
the string  owner- to the  name of the  alias; these aliases  are stored in
file /private/usr/lib/aliases.  The director-driver aliasfile  implements a
general  mechanism  for looking  up  aliases  stored in  a  data base.   By
default, aliases are  kept in a DBM-style data base  that is built from the
text file  /usr/lib/mail/aliases. For details on this  file and its format,
see the Lexicon entry for aliases. For details on how DBM-style data bases,
see the Lexicon entry for libgdbm.

The  separation between generic  attributes and  driver-specific attributes
mirrors  the internal  design of  smail. Above  the driver  level, routines
exist that implement aspects of drivers, routers, and transports but do not
depend upon the specific means for performing the operation.  These higher-
level functions can be  manipulated through the generic attributes.  On the
other hand,  the drivers  that actually  perform these operations  accept a
different set  of attributes to control  their behavior.  In the  case of a
driver thats read or writes to a file, a file attribute usually exists.  In
the  case of  a driver  that executes  a program,  a cmd  attribute usually
exists to specify how that program is to be invoked.

Attributes of a Director

The following the generic attributes can  be used in an entry in directors.
Each  attribute is  followed by  its type  (Boolean or  string).  To  set a
string attribute, its name should be  followed by an `=', then the value to
which you  are setting it.   To set a  Boolean attribute, prefix  it with a
`+'; to unset a Boolean attribute, prefix it with a `-'.

caution (Boolean)
     If set, then be cautious  of the addresses this director produces.  If
     the attribute  nobody is not set, then  reject file, shell-command, or
     :include:filename-style mailing-list addresses.

default_group (string)
     If the driver does not associate a group to an address returned by it,
     then associate  the group identifier  for this group  name.  This will
     override the group identifier set by the attribute default_user.

default_home (string)
     If  the driver  does not  associate a home  directory with  an address
     returned by it, then use this directory as the default home directory.
     smail expands  the value of this attribute to  form the directory path
     name.  At present, variable $user is not available for this expansion.
     If the string expansion fails, smail ignores it.

default_user (string)
     If  the driver  does  not associate  a  user or  group  to an  address
     returned  by  it,   then  associate  the  user  identifier  and  group
     identifier of this user.

driver (string)
     This attribute  names the set of low-level functions  that do the work
     of directing local mail.  This attribute is required.

nobody (Boolean)
     If set, then  smail accesses files or runs shell  commands as the user
     specified by its  attribute nobody, for addresses flagged with caution
     by either the caution generic attribute or by the driver.  Association
     of  nobody  with an  address  overrides  the attributes  default_user,
     default_group,  set_user,  and set_group.  This  attribute  is set  by
     default.

owner (string)
     This names the address to be  sent mail if an error occurs while smail
     is processing the addresses produced by this director.  This string is
     expanded with the variable  $user set to the local-form address passed
     to the  director.  By deafault, the value  owner-$user. If this string
     expansion fails, smail ignores it.

sender_okay (Boolean)
     If  set, then  it is  always  okay for  this attribute  to produce  an
     address equal to the sender.  This effectively turns on the ``me too''
     flag for  this director.  This should generally  be set for forwarding
     directors  and  should  not  be  set  for  aliasing  and  mailing-list
     directors.

set_group (string)
     Associate this  group's identifier with the  addresses that the driver
     returns.   This overrides  any group identifier  set by  the attribute
     set_user.

set_home (string)
     Associate  this home  directory  with all  addresses  returned by  the
     driver.  This will be expanded in the same manner as default_home.

set_user (string)
     Associate the user and  group identifiers for this user with addresses
     that the driver returns.  This overrides any values set by the driver.

smail requires  that two addresses exist:  Postmaster and Mailer-Daemon. To
avoid the  necessity of an  alias for these  two users, smail  contains two
implicit directors embedded into the directing code; it uses them as a last
resort.  The  first such director  maps the address  Mailer-Daemon onto the
address Postmaster; and the second maps Postmaster onto the address root.

The Preloaded Directors

If smail does not find a  copy of file directors in directory /usr/lib/mail
(which is  the case  by default  under COHERENT), it  uses its  the default
configuration.  The  default director configuration  supports the following
directors:

Include Files
     smail expands local addresses of the form :include:filename   into   a
     list of  addresses contained in the ASCII file  filename. The files to
     which these  addresses refer are called mailing  list files. This form
     of  local address  can  appear in  any  alias file,  forward file,  or
     mailing-list file.  A user cannot supply such an address himself.

Alias Files
     This  director scans  for entries  in an DBM-style  data base  that is
     built from text file /usr/lib/mail/aliases. If this data base does not
     exist,  smail ignores  it --  its  absence does  not trigger  an error
     condition.   If smail  encounters an  error while  it is  resolving an
     address produced by an alias, it  mails an error message to an address
     that has the  string ``owner-'' prefixed to the name  of the alias, if
     such a local address is defined.

Forward Files
     A user may have a file  named .forward in his home directory.  If such
     a file  exists, smail scans  it for addresses.   If a user  has such a
     file in his  home directory, smail directs all mail  sent to that user
     to  the  address  or addresses  it  contains.   The  file can  contain
     addresses that specify other files or shell commands as recipients.

     If the  .forward file is  owned by root  or by the  user himself, then
     deliveries  to any  shell commands  or files  are performed  under the
     user's user and group identifiers.   If smail enters an error while it
     is resolving this list of addresses, it mails an error message to your
     system's postmaster.

     In the  .forward file for the user root,  deliveries to shell commands
     and file addresses are  performed under an unprivileged user and group
     identifier (by  default, user  nobody). The  same is true  for forward
     files that  were not  owned by  root or by  the given  user.  Finally,
     shell command  and file addresses  are not allowed at  all in .forward
     files that are directories that can accessed by remote systems.

Mailbox Forwarding
     As an alternate  way to forward mail, the mailbox  file for a user may
     contain a line of the form:

         Forward to address, address ...

     Onlyone line  is read  from this file,  so addresses cannot  be placed
     across multiple  lines.  The  comments that  apply to a  .forward file
     also apply  to this use of  a mailbox file, except  that smail assumes
     that a mailbox is not accessible by users on other systems.

     A  user is  matched  by name,  either  in upper  or  lower case,  with
     delivery to that user being performed using a transport by the name of
     local. A user can also be matched by name if the user name is prefixed
     by real-. Delivery is performed by a transport named local.

Mailing Lists
     Mailing list files can be created under a mailing-list directory -- by
     default, directory /usr/lib/mail/lists.  To create a new mailing list,
     create a  file in  this directory that  contains a list  of addresses.
     The  basename of  this file  determines the  local address  that smail
     expands into this list of  addresses.  For example, a file named info-
     smail could  be created, that  contains a list  of recipient addresses
     for a mailing list named ``info-smail''.  smail then forwards any mail
     message  mailed  to  address  info-smail  to  every  address  in  file
     /usr/lib/mail/lists/info-smail.

     If smail  encounters an error  as it is  attempting to deliver  a mail
     message to an address within a list file, it mails an error message to
     a local address  comprised of the base name of  the list file prefixed
     with the string ``owner-'', if such an address is defined.

The Smart User
     If  smail cannot  match a  local address  by any  other means,  it can
     forward that mail to another system  -- one that presumably has a more
     complete data base -- via the director smartuser.

     To declare  another system to  be a ``smart user,''  set the attribute
     smart_user  within file  /usr/lib/mail/config. For  example, attribute
     forwards mail to the host mwc.com:

         smart_user = $user@mwc.com

     If you  do not set  this attribute, then smail  ignores the smart-user
     director.

Example Entries

The  order  of  entries within  directors  determines  the  order in  which
operations are  attempted.  If  a director  matches an address,  then smail
calls no  other director to expand or resolve  that address.  The following
gives  a   version  of  directors   that  is  equivalent   to  the  default
configuration:

    # aliasinclude - expand ":include:filename" addresses
    #    produced by alias files
    aliasinclude:
        driver = aliasinclude,  # use this special-case driver
        nobody;                 # associate nobody user with addresses
    #  when mild permission violations
    #  are encountered

        copysecure,    # get permissions from alias director
        copyowners     # get owners from alias director

    # forwardinclude - expand ":include:filename" addresses
    #    produced by forward files
    forwardinclude:
        driver = forwardinclude, # use this special-case driver
        nobody;

        copysecure,    # get perms from forwarding director
        copyowners     # get owners from forwarding director

    # aliases - search for alias expansions stored in a database
    aliases:
        driver = aliasfile,      # general-purpose aliasing director
        -nobody,                 # all addresses are associated
                                 # with nobody by default, so setting
                                 # this is not useful.
        owner = owner-$user;     # problems go to an owner address

        file = /usr/lib/aliases,
        modemask = 002,
        optional,                # ignore if file does not exist
        proto = lsearch

    # dotforward - expand .forward files in user home directories
    dotforward:
        driver = forwardfile,    # general-purpose forwarding director
        owner = Postmaster,      # problems go to the user's mailbox
        nobody,
        sender_okay;             # sender never removed from expansion

        file = ~/.forward,       # .forward file in home directories
        checkowner,              # the user can own this file
        owners = root,           # or root can own the file
        modemask = 002,          # it should not be globally writable
        caution = daemon:root,   # don't run things as root or daemon
                                 # be extra careful of remotely
                                         # accessible home directories
        unsecure = "~ftp:~uucp:~nuucp:/tmp:/usr/tmp"

    # forwardto - expand a "Forward to " in user mailbox files
    #
    # This emulates the V6/V7/System-V forwarding mechanism which uses a
    # line of forward addresses stored at the beginning of user mailbox
    # files prefixed with the string "Forward to "
    forwardto:
        driver = forwardfile,
        owner = Postmaster, nobody, sender_okay;

        file = /usr/mail/${lc:user}, # the mailbox file for System V
        forwardto,                   # enable "Forward to " function
        checkowner,                  # the user can own this file
        owners = root,               # or root can own the file
        modemask = 0002,             # under System V, group mail can write
        caution = daemon:root        # don't run things as root or daemon

        # user - match users on the local host with delivery to their mailboxes
        user:     driver = user;# driver to match usernames

        transport = local        # local transport goes to mailboxes

    # real_user - match usernames when prefixed with the string "real-"
    #
    # This is useful for allowing an address which explicitly delivers to
    # a user's mailbox file.  For example, errors in a .forward file
    # expansion can be delivered here, or forwarding loops between
    # multiple machines can be resolved by using a real-username address.
    real_user:
        driver = user;

        transport = local,
        prefix = "real-"         # for example, match real-root

    # lists - expand mailing lists stored in a list directory
    #
    # mailing lists can be created simply by creating a file in the
    # /usr/lib/smail/lists directory.
    lists:    driver = forwardfile,
        caution,                 # flag all addresses with caution
        nobody,                  # and then associate the nobody user
        owner = owner-$user;     # system V sites may wish to use
    # o-$user, as owner-$user may be
    # too long for a 14-char filename.

        # map the name of the mailing list to lower case
        file = lists/${lc:user}

    # smart_user - a partially specified smartuser director
    #
    # If the config file attribute smart_user is defined as a string such
    # as "$user@domain-gateway" then users not matched otherwise will be
    # sent off to the host "domain-gateway".
    #
    # If the smart_user attribute is not defined, this director is ignored.
    smart_user:
        driver = smartuser;      # special-case driver

    # do not match addresses which cannot be made into valid
    # RFC822 local addresses without the use of double quotes.
        well_formed_only

See Also

Administering COHERENT,
config [smail],
.forward,
mail [overview],
routers,
smail,
transports

Notes

Copyright © 1987, 1988 Ronald S. Karr and Landon Curt Noll.  Copyright
© 1992 Ronald S. Karr.

For  details on  the distribution rights  and restrictions  associated with
this software, see file COPYING, which  is included with the source code to
the smail system; or type the command: smail -bc.

© 2012 by Stephen A. Ness