phpMan > info > slocal(1)

SLOCAL(1mh)                                                        SLOCAL(1mh)

NAME
       slocal - asynchronously filter and deliver new mail to nmh

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

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  be-
       half  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 al-
       ternate 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  send-
       mail,  the sender will obtained from the UUCP "From:" line, if present.
       The user may override these values with 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, in-
       stead of reading stdin.  This is useful when debugging  a  ".maildeliv-
       ery" file.

       The  -user  switch tells slocal the name of the user for whom it is de-
       livering mail.  It must exist on the local system.  The -mailbox switch
       tells slocal the name of the user's mail drop file.

       slocal  is  able  to detect and suppress duplicate messages.  To enable
       this, use the option -suppressdup.  slocal will keep  a  database  con-
       taining  the  Message-ID's of incoming messages, in order to detect du-
       plicates.  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-pro-
       cesses 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 ac-
       tions 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 .for-
       ward 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 in-
       coming mail.  Each line of this file consists of five fields, separated
       by whitespace or comma.  Since double-quotes are honored, these charac-
       ters may be included in a single argument by enclosing the entire argu-
       ment  in double-quotes.  A double-quote can be included by preceding it
       with a backslash.  Lines beginning with `#' and  blank  lines  are  ig-
       nored.

       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 re-
                      cipient

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

       action:
            The  action to take to deliver the message.  When a message is de-
            livered, 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 char-
                acters which your shell might interpret.

            folder or +
                Store the message in the nmh folder  named  by  string.   Cur-
                rently  this  is handled by piping the message to the nmh pro-
                gram 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 deliv-
                ered.

            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 ac-
       tion 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 root and must  be  writable
       only by 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  mail
       drop 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 envi-
       ronment 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 mail drop.

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 mail drop

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

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

       -addr and -user will be set the the user part of the Local-Mailbox pro-
       file entry, if set.

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 ex-
       tended, 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" (de-
       liver the message to the mail drop).

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.

nmh-1.7.1                         2016-05-02                       SLOCAL(1mh)