slocal - asynchronously filter and deliver new mail


SYNOPSIS

       /usr/lib/nmh/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 deter­
       mined  from  the  Message Transfer Agent envelope informa­
       tion,  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 incom­
       ing 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 argu­
       ment 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

       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
       If your MTA is sendmail, you should include the line

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

       in  your  .forward file in your home directory.  This will
       cause sendmail to invoke slocal on your behalf when a mes­
       sage arrives.

       If  your  MTA  is  MMDF-I,  you should (symbolically) link
       /usr/lib/nmh/slocal to the file bin/rcvmail in  your  home
       directory.   This  will  cause  MMDF-I to invoke slocal on
       your behalf with the correct  "address info sender"  argu­
       ments.

       If  your  MTA  is MMDF-II, then you should not use slocal.
       An equivalent functionality is already provided  by  MMDF-
       II; see maildelivery(5) for details.

   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

            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 mes­
            sage 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(1) 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  informa­
                                tion
                      $(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 spec­
                                ified

            qpipe or <caret> 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  his  is  handled  by
                      piping the message to the nmh program `rcv­
                      store', although this  may  change  in  the
                      future.

            Indicates how the action should be performed:

            A         Perform  the  action.   If  the action suc­
                      ceeds,  then  the  message  is   considered
                      delivered.

            R         Perform the action.  Regardless of the out­
                      come of the action, the message is not con­
                      sidered delivered.

            ?         Perform  the action only if the message has
                      not been delivered.   If  the  action  suc­
                      ceeds,   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 sev­
       eral 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/mailde­
       livery.   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 per­
       form 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
       #

       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       /nmh/lib/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  pro­
       cess  will  be  terminated  with  extreme  prejudice.  The
       amount of time is calculated as ((size / 60) +  300)  sec­
       onds,  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 imple­
       ment a process that began by forking.   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



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-for­
       mat(5)


DEFAULTS

       `-noverbose'
       `-nosuppressdup'
       `-maildelivery .maildelivery'
       `-mailbox /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,  includ­
       ing 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.


Man(1) output converted with man2html