Provided by: nmh_1.3-1_i386 bug

NAME

       slocal - asynchronously filter and deliver new mail

SYNOPSIS

       /usr/lib/mh/slocal [address info sender] [-addr address] [-info data]
            [-sender sender] [-user username] [-mailbox mbox] [-file file]
            [-maildelivery deliveryfile] [-verbose | -noverbose] [-suppressdup
            | -nosuppressdup] [-debug] [-version] [-help]

DESCRIPTION

       Slocal is a program designed to allow you to  have  your  inbound  mail
       processed according to a complex set of selection criteria.  You do not
       normally invoke slocal yourself,  rather  slocal  is  invoked  on  your
       behalf  by your system's Message Transfer Agent (such as sendmail) when
       the message arrives.

       The message selection criteria used by slocal is specified in the  file
       ".maildelivery"  in  the  user's  home  directory.   You can specify an
       alternate file with the -maildelivery file option.  The syntax of  this
       file is specified below.

       The message delivery address and message sender are determined from the
       Message  Transfer  Agent  envelope  information,  if  possible.   Under
       sendmail,  the  sender  will  obtained  from  the UUCP "From:" line, if
       present.   The  user  may  override  these  values  with  command  line
       arguments, or arguments to the -addr and -sender switches.

       The message is normally read from the standard input.  The -file switch
       sets the name of the file  from  which  the  message  should  be  read,
       instead   of   reading   stdin.    This  is  useful  when  debugging  a
       ".maildelivery" file.

       The -user switch tells slocal the name of  the  user  for  whom  it  is
       delivering  mail.   The  -mailbox  switch  tells slocal the name of the
       user's maildrop file.

       slocal is able to detect and suppress duplicate  messages.   To  enable
       this,  use  the  option  -suppressdup.   slocal  will  keep  a database
       containing the Message-ID's of incoming messages, in  order  to  detect
       duplicates.   Depending on your configuration, this database will be in
       either ndbm or Berkeley db format.

       The -info switch may be used to pass  an  arbitrary  argument  to  sub-
       processes which slocal may invoke on your behalf.

       The  -verbose  switch causes slocal to give information on stdout about
       its progress.  The -debug switch produces more verbose debugging output
       on  stderr.   These  flags  are useful when creating and debugging your
       ".maildelivery" file, as they  allow  you  to  see  the  decisions  and
       actions  that  slocal  is taking, as well as check for syntax errors in
       your ".maildelivery" file.

   Message Transfer Agents
       Most modern  MTAs  including  sendmail,  postfix  and  exim  support  a
       .forward file for directing incoming mail.  You should include the line

            "| /usr/lib/mh/slocal -user username"

       in your .forward file in your home directory.  This will cause your MTA
       to invoke slocal on your behalf when a message arrives.

   The Maildelivery File
       The ".maildelivery" file  controls  how  slocal  filters  and  delivers
       incoming  mail.   Each  line  of  this  file  consists  of five fields,
       separated by white-space or comma.  Since  double-quotes  are  honored,
       these  characters may be included in a single argument by enclosing the
       entire argument in double-quotes.  A double-quote can  be  included  by
       preceding  it  with  a  backslash.   Lines beginning with `#' and blank
       lines are ignored.

       The format of each line in the ".maildelivery" file is:

            header    pattern   action    result    string

       header:
            The name of a header field (such as To, Cc,  or From) that  is  to
            be  searched  for  a pattern.  This is any field in the headers of
            the message that might be present.

            The following special fields are also defined:

            source    the out-of-band sender information

            addr      the address that was  used  to  cause  delivery  to  the
                      recipient

            default   this  matches  only if the message hasn't been delivered
                      yet

            *         this always matches

       pattern:
            The sequence of characters to match in the specified header field.
            Matching   is   case-insensitive,   but   does   not  use  regular
            expressions.

       action:
            The action to take to deliver the  message.   When  a  message  is
            delivered, a "Delivery-Date: date" header is added which indicates
            the date and time that message was delivered.

            destroy      This action always succeeds.  file, mbox, or > Append
                         the message to the file named by string.  The message
                         is appended to the file in mbox (uucp) format.   This
                         is  the  format used by most other mail clients (such
                         as mailx, elm).  If the message can  be  appended  to
                         the file, then this action succeeds.

            mmdf         Identical  to  file,  but  always appends the message
                         using the MMDF mailbox format.

            pipe or |    Pipe the message as the standard input to the command
                         named  by  string,  using  the  Bourne  shell  sh  to
                         interpret the string.  Prior to giving the string  to
                         the shell, it is expanded with the following built-in
                         variables:

                         $(sender)     the out-of-band sender information

                         $(address)    the address  that  was  used  to  cause
                                       delivery to the recipient

                         $(size)       the size of the message in bytes

                         $(reply-to)   either the "Reply-To:" or "From:" field
                                       of the message

                         $(info)       the out-of-band information specified

            qpipe or ^   Similar to pipe, but executes the  command  directly,
                         after built-in variable expansion, without assistance
                         from the shell.  This action can  be  used  to  avoid
                         quoting  special  characters  which  your shell might
                         interpret.

            folder or +  Store the message in the nmh folder named by  string.
                         Currently  this  is  handled by piping the message to
                         the nmh program rcvstore, although this may change in
                         the future.

       result:
            Indicates how the action should be performed:

            A   Perform  the action.  If the action succeeds, then the message
                is considered delivered.

            R   Perform the action. Regardless of the outcome of  the  action,
                the message is not considered delivered.

            ?   Perform the action only if the message has not been delivered.
                If  the  action  succeeds,  then  the  message  is  considered
                delivered.

            N   Perform  the action only if the message has not been delivered
                and the previous action succeeded.  If this  action  succeeds,
                then the message is considered delivered.

            The  delivery  file  is  always  read  completely, so that several
            matches can be made and several actions can be taken.

   Security of Delivery Files
       In order to prevent security problems, the ".maildelivery" file must be
       owned  either  by the user or by root, and must be writable only by the
       owner.  If this is not the case, the file is not read.

       If the ".maildelivery" file cannot be found, or  does  not  perform  an
       action  which delivers the message, then slocal will check for a global
       delivery file at /etc/nmh/maildelivery.  This file is read according to
       the  same  rules.   This  file  must  be  owned by the root and must be
       writable only by the root.

       If a global delivery file cannot be found or does not perform an action
       which  delivers  the  message,  then  standard  delivery  to the user's
       maildrop is performed.

   Example Delivery File
       To summarize, here's an example delivery file:

       #
       # .maildelivery file for nmh's slocal
       #
       # Blank lines and lines beginning with a '#' are ignored
       #
       # FIELD   PATTERN   ACTION  RESULT  STRING
       #

       # File mail with foobar in the "To:" line into file foobar.log
       To        foobar    file    A       foobar.log

       # Pipe messages from coleman to the program message-archive
       From      coleman   pipe    A       /bin/message-archive

       # Anything to the "nmh-workers" mailing list is put in
       # its own folder, if not filed already
       To        nmh-workers  folder ?     nmh-workers

       # Anything with Unix in the subject is put into
       # the file unix-mail
       Subject   unix      file    A       unix-mail

       # I don't want to read mail from Steve, so destroy it
       From      steve     destroy A       -

       # Put anything not matched yet into mailbox
       default   -        file    ?       mailbox

       # always run rcvtty
       *         -        pipe    R       /usr/lib/mh/rcvtty

   Sub-process environment
       When a process is invoked, its environment is: the  user/group-ids  are
       set  to  recipient's ids; the working directory is the recipient's home
       directory; the umask is 0077; the process has no /dev/tty; the standard
       input  is set to the message; the standard output and diagnostic output
       are set to  /dev/null;  all  other  file-descriptors  are  closed;  the
       environment  variables  $USER, $HOME, $SHELL are set appropriately, and
       no other environment variables exist.

       The process is given a certain amount  of  time  to  execute.   If  the
       process does not exit within this limit, the process will be terminated
       with extreme prejudice.  The amount of time is calculated as  ((size  /
       60)  +  300)  seconds, where size is the number of bytes in the message
       (with 30 minutes the maximum time allowed).

       The exit status of the process is consulted in determining the  success
       of the action.  An exit status of zero means that the action succeeded.
       Any other exit status (or abnormal termination) means that  the  action
       failed.

       In  order  to avoid any time limitations, you might implement a process
       that began by fork()-ing.  The  parent  would  return  the  appropriate
       value  immediately,  and the child could continue on, doing whatever it
       wanted for as long as it wanted.  This approach is  somewhat  risky  if
       the parent is going to return an exit status of zero.  If the parent is
       going to return a non-zero exit status, then this approach can lead  to
       quicker delivery into your maildrop.

FILES

       /etc/nmh/mts.conf          nmh mts configuration file
       $HOME/.maildelivery        The file controlling local delivery
       /etc/nmh/maildelivery      Rather than the standard file
       /var/mail/$USER            The default maildrop

SEE ALSO

       rcvdist(1), rcvpack(1), rcvstore(1), rcvtty(1), mh-format(5)

DEFAULTS

       `-noverbose'
       `-nosuppressdup'
       `-maildelivery' defaults to $HOME/.maildelivery
       `-mailbox' deaults to /var/mail/$USER
       `-file' defaults to stdin
       `-user' defaults to the current user

CONTEXT

       None

HISTORY

       Slocal  was  originally  designed  to  be  backward-compatible with the
       maildelivery facility provided by MMDF-II.  Thus,  the  ".maildelivery"
       file  syntax  is  somewhat  limited.   But slocal has been modified and
       extended, so that is it no longer compatible with MMDF-II.

       In addition to an exit status of zero, the MMDF values RP_MOK (32)  and
       RP_OK  (9)  mean  that the message has been fully delivered.  Any other
       non-zero exit status, including abnormal termination, is interpreted as
       the  MMDF  value  RP_MECH  (200),  which means "use an alternate route"
       (deliver the message to the maildrop).

BUGS

       Only two return codes are meaningful, others should be.

       Slocal was originally designed  to  be  backwards-compatible  with  the
       maildelivery functionality provided by MMDF-II.