1SLOCAL(1)                   General Commands Manual                  SLOCAL(1)
2
3
4

NAME

6       slocal - asynchronously filter and deliver new mail to nmh
7

SYNOPSIS

9       /usr/libexec/nmh/slocal [-help] [-version] [-addr address] [-info data]
10            [-sender sender] [-user username] [-mailbox mbox] [-file file]
11            [-maildelivery deliveryfile] [-verbose | -noverbose] [-suppressdup
12            | -nosuppressdup] [-debug]
13

DESCRIPTION

15       slocal is a program designed to allow you to  have  your  inbound  mail
16       processed according to a complex set of selection criteria.  You do not
17       normally invoke slocal yourself,  rather  slocal  is  invoked  on  your
18       behalf  by your system's Message Transfer Agent (such as sendmail) when
19       the message arrives.
20
21       The message selection criteria used by slocal is specified in the  file
22.maildelivery”  in  the  user's  home  directory.   You can specify an
23       alternate file with the -maildelivery file option.  The syntax of  this
24       file is specified below.
25
26       The message delivery address and message sender are determined from the
27       Message Transfer Agent envelope information, if possible.  Under  send‐
28       mail,  the sender will obtained from the UUCP “From:” line, if present.
29       The user may override these values with the -addr and -sender switches.
30
31       The message is normally read from the standard input.  The -file switch
32       sets  the  name  of  the  file  from  which the message should be read,
33       instead of reading stdin.  This is useful when debugging a “.maildeliv‐
34       ery” file.
35
36       The  -user  switch  tells  slocal  the  name of the user for whom it is
37       delivering mail.  It must exist on  the  local  system.   The  -mailbox
38       switch tells slocal the name of the user's mail drop file.
39
40       slocal  is  able  to detect and suppress duplicate messages.  To enable
41       this, use the option -suppressdup.  slocal will keep  a  database  con‐
42       taining  the  Message-ID's  of  incoming  messages,  in order to detect
43       duplicates.  Depending on your configuration, this database will be  in
44       either ndbm or Berkeley db format.
45
46       The  -info switch may be used to pass an arbitrary argument to sub-pro‐
47       cesses which slocal may invoke on your behalf.
48
49       The -verbose switch causes slocal to give information on  stdout  about
50       its progress.  The -debug switch produces more verbose debugging output
51       on stderr.  These flags are useful when  creating  and  debugging  your
52.maildelivery”  file,  as  they  allow  you  to  see the decisions and
53       actions that slocal is taking, as well as check for  syntax  errors  in
54       your “.maildelivery” file.
55
56   Message Transfer Agents
57       Most  modern  MTAs including sendmail, postfix and exim support a .for‐
58       ward file for directing incoming mail.  You should include the line
59
60                     “| /usr/libexec/nmh/slocal -user username”
61
62       in your .forward file in your home directory.  This will cause your MTA
63       to invoke slocal on your behalf when a message arrives.
64
65   The Maildelivery File
66       The  “.maildelivery”  file  controls  how  slocal  filters and delivers
67       incoming mail.  Each line of this file consists of five  fields,  sepa‐
68       rated  by  whitespace or comma.  Since double-quotes are honored, these
69       characters may be included in a single argument by enclosing the entire
70       argument in double-quotes.  A double-quote can be included by preceding
71       it with a backslash.  Lines beginning with  `#'  and  blank  lines  are
72       ignored.
73
74       The format of each line in the “.maildelivery” file is:
75
76            header    pattern   action    result    string
77
78       header:
79            The  name  of a header field (such as To, Cc,  or From) that is to
80            be searched for a pattern.  This is any field in  the  headers  of
81            the message that might be present.
82
83            The following special fields are also defined:
84
85            source    the out-of-band sender information
86
87            addr      the  address  that  was  used  to  cause delivery to the
88                      recipient
89
90            default   this matches only if the message hasn't  been  delivered
91                      yet
92
93            *         this always matches
94
95       pattern:
96            The sequence of characters to match in the specified header field.
97            Matching is case-insensitive, but does  not  use  regular  expres‐
98            sions.
99
100       action:
101            The  action  to  take  to  deliver the message.  When a message is
102            delivered, a “Delivery-Date: date” header is added which indicates
103            the date and time that message was delivered.
104
105            destroy
106                This action always succeeds.
107
108            file, mbox, or >
109                Append  the  message to the file named by string.  The message
110                is appended to the file in mbox (uucp) format.   This  is  the
111                format  used  by most other mail clients (such as mailx, elm).
112                If the message can be appended to the file, then  this  action
113                succeeds.
114
115            mmdf
116                Identical  to  file,  but always appends the message using the
117                MMDF mailbox format.
118
119            pipe or |
120                Pipe the message as the standard input to the command named by
121                string,  using  the  Bourne  shell sh to interpret the string.
122                Prior to giving the string to the shell, it is  expanded  with
123                the following built-in variables:
124
125                $(sender)     the out-of-band sender information
126
127                $(address)    the  address  that was used to cause delivery to
128                              the recipient
129
130                $(size)       the size of the message in bytes
131
132                $(reply-to)   either the “Reply-To:” or “From:” field  of  the
133                              message
134
135                $(info)       the out-of-band information specified
136
137            qpipe or ^
138                Similar  to  pipe,  but  executes  the command directly, after
139                built-in  variable  expansion,  without  assistance  from  the
140                shell.  This action can be used to avoid quoting special char‐
141                acters which your shell might interpret.
142
143            folder or +
144                Store the message in the nmh folder  named  by  string.   Cur‐
145                rently  this  is handled by piping the message to the nmh pro‐
146                gram rcvstore, although this may change in the future.
147
148       result:
149            Indicates how the action should be performed:
150
151            A   Perform the action.  If the action succeeds, then the  message
152                is considered delivered.
153
154            R   Perform  the action.  Regardless of the outcome of the action,
155                the message is not considered delivered.
156
157            ?   Perform the action only if the message has not been delivered.
158                If  the action succeeds, then the message is considered deliv‐
159                ered.
160
161            N   Perform the action only if the message has not been  delivered
162                and  the  previous action succeeded.  If this action succeeds,
163                then the message is considered delivered.
164
165            The delivery file is  always  read  completely,  so  that  several
166            matches can be made and several actions can be taken.
167
168   Security of Delivery Files
169       In order to prevent security problems, the “.maildelivery” file must be
170       owned either by the user or by root, and must be writable only  by  the
171       owner.  If this is not the case, the file is not read.
172
173       If  the  “.maildelivery”  file  cannot be found, or does not perform an
174       action which delivers the message, then slocal will check for a  global
175       delivery file at /etc/nmh/maildelivery.  This file is read according to
176       the same rules.  This file must be owned by root and must  be  writable
177       only by root.
178
179       If a global delivery file cannot be found or does not perform an action
180       which delivers the message, then standard delivery to the  user's  mail
181       drop is performed.
182
183   Example Delivery File
184       To summarize, here's an example delivery file:
185
186       #
187       # .maildelivery file for nmh's slocal
188       #
189       # Blank lines and lines beginning with a '#' are ignored
190       #
191       # FIELD   PATTERN   ACTION  RESULT  STRING
192       #
193
194       # File mail with foobar in the “To:” line into file foobar.log
195       To        foobar    file    A       foobar.log
196
197       # Pipe messages from coleman to the program message-archive
198       From      coleman   pipe    A       /bin/message-archive
199
200       # Anything to the “nmh-workers” mailing list is put in
201       # its own folder, if not filed already
202       To        nmh-workers  folder ?     nmh-workers
203
204       # Anything with Unix in the subject is put into
205       # the file unix-mail
206       Subject   unix      file    A       unix-mail
207
208       # I don't want to read mail from Steve, so destroy it
209       From      steve     destroy A       -
210
211       # Put anything not matched yet into mailbox
212       default   -        file    ?       mailbox
213
214       # always run rcvtty
215       *         -        pipe    R       /usr/libexec/nmh/rcvtty
216
217   Sub-process environment
218       When  a  process is invoked, its environment is: the user/group-ids are
219       set to recipient's ids; the working directory is the  recipient's  home
220       directory; the umask is 0077; the process has no /dev/tty; the standard
221       input is set to the message; the standard output and diagnostic  output
222       are  set to /dev/null; all other file-descriptors are closed; the envi‐
223       ronment variables $USER, $HOME, $SHELL are set  appropriately,  and  no
224       other environment variables exist.
225
226       The  process  is  given  a  certain  amount of time to execute.  If the
227       process does not exit within this limit, the process will be terminated
228       with  extreme  prejudice.  The amount of time is calculated as ((size /
229       60) + 300) seconds, where size is the number of bytes  in  the  message
230       (with 30 minutes the maximum time allowed).
231
232       The  exit status of the process is consulted in determining the success
233       of the action.  An exit status of zero means that the action succeeded.
234       Any  other  exit status (or abnormal termination) means that the action
235       failed.
236
237       In order to avoid any time limitations, you might implement  a  process
238       that  began  by  fork()-ing.   The  parent would return the appropriate
239       value immediately, and the child could continue on, doing  whatever  it
240       wanted  for  as  long as it wanted.  This approach is somewhat risky if
241       the parent is going to return an exit status of zero.  If the parent is
242       going  to return a non-zero exit status, then this approach can lead to
243       quicker delivery into your mail drop.
244

FILES

246       /etc/nmh/mts.conf          nmh mts configuration file
247       $HOME/.maildelivery        The file controlling local delivery
248       /etc/nmh/maildelivery      Rather than the standard file
249       /var/mail/$USER            The default mail drop
250

SEE ALSO

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

DEFAULTS

255       `-noverbose'
256       `-nosuppressdup'
257       `-maildelivery' defaults to $HOME/.maildelivery
258       `-mailbox' defaults to /var/mail/$USER
259       `-file' defaults to stdin
260       `-addr' defaults to the current user
261       `-user' defaults to the current user
262
263       -addr and -user will be set the the user part of the Local-Mailbox pro‐
264       file entry, if set.
265

CONTEXT

267       None
268

HISTORY

270       slocal  was  originally  designed  to  be  backward-compatible with the
271       maildelivery facility provided by MMDF-II.  Thus,  the  “.maildelivery
272       file  syntax  is  somewhat  limited.   But slocal has been modified and
273       extended, so that is it no longer compatible with MMDF-II.
274
275       In addition to an exit status of zero, the MMDF values RP_MOK (32)  and
276       RP_OK  (9)  mean  that the message has been fully delivered.  Any other
277       non-zero exit status, including abnormal termination, is interpreted as
278       the  MMDF  value  RP_MECH  (200),  which means “use an alternate route”
279       (deliver the message to the mail drop).
280

BUGS

282       Only two return codes are meaningful, others should be.
283
284       slocal was originally designed  to  be  backwards-compatible  with  the
285       maildelivery functionality provided by MMDF-II.
286
287
288
289nmh-1.7.1                         2016-05-02                         SLOCAL(1)
Impressum