SLOCAL(1)                                               SLOCAL(1)

NAME
       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.

       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.

       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
       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.

       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.

       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 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 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  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.  This is done by piping the mes-
                      sage to the nmh program `rcvstore'.

       result:
            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.

       To summarize, here's an example:

       #
       # .maildelivery file for nmh's slocal
       #
       # Blank lines and lines beginning with a '#'
       # are ignored.
       #
       # FIELD   PATTERN   ACTION  RESULT  STRING
       #
       # file mail with mmdf2 in the "To:" line into file mmdf2.log
       To        mmdf2     file    A       mmdf2.log

       # Messages from mmdf pipe to the program message-archive
       From      mmdf      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  +    ?       nmh-workers

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

       # if the address is jpo=ack, then send an acknowledgement back
       addr      jpo=ack   |       R       "/bin/resend -r $(reply-to)"

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

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

       # always run rcvtty
       *         -         |       R       /nmh/lib/rcvtty

       The file  is  always  read  completely,  so  that  several
       matches can be made and several actions can be taken.  The
       .maildelivery file must be owned either by the user or  by
       root,  and  must  be  writable  only by the owner.  If the
       .maildelivery file cannot be found, or does not perform an
       action   which   delivers   the  message,  then  the  file
       /etc/nmh/maildelivery is read according to the same rules.
       This  file  must be owned by the root and must be writable
       only by the root.  If this file cannot be  found  or  does
       not  perform  an  action  which delivers the message, then
       standard delivery to the user's maildrop is performed.

       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
       approach  can lead to quicker delivery into your maildrop.
       ^/etc/nmh/mts.conf~^nmh     mts     configuration     file
       ^$HOME/.maildelivery~^The  file controlling local delivery
       ^/etc/nmh/maildelivery~^Rather  than  the  standard   file
       ^/var/spool/mail/$USER~^The  default  maildrop rcvdist(1),
       rcvpack(1), rcvstore(1), rcvtty(1), mh-format(5)  `-nover-
       bose'   `-nosuppressdup'   `-maildelivery   .maildelivery'
       `-mailbox /var/spool/mail/$USER' `-file' defaults to stdin
       `-user' defaults to the current user None Slocal was orig-
       inally designed to be backward-compatible with the mailde-
       livery  facility  provided by MMDF-II.  Thus, the .mailde-
       livery file syntax is somewhat limited.   But  slocal  has
       been  modified  and extended, so that is it no longer com-
       patible 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).  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.

[nmh-0.27]                    MH.6.8                            1