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.