Mercurial > hg > Applications > mh
comparison doc/slocal.me @ 0:bce86c4163a3
Initial revision
author | kono |
---|---|
date | Mon, 18 Apr 2005 23:46:02 +0900 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:bce86c4163a3 |
---|---|
1 .\" This file is automatically generated. Do not edit! | |
2 .\" @(#)$Id$ | |
3 .SC SLOCAL 1 | |
4 .NA | |
5 slocal \- special local mail delivery | |
6 .SY | |
7 /usr/local/mh/lib/slocal \%[address\ info\ sender] | |
8 .na | |
9 .br | |
10 \%[\-addr\ address] | |
11 \%[\-info\ data] | |
12 \%[\-sender\ sender] | |
13 .br | |
14 \%[\-user\ username] | |
15 \%[\-mailbox\ mbox] | |
16 \%[\-file\ file] | |
17 .\" \%[\-home\ homedir] | |
18 .br | |
19 \%[\-maildelivery\ deliveryfile] | |
20 \%[\-verbose] \%[\-noverbose] | |
21 \%[\-debug] | |
22 \%[\-help] | |
23 .ad | |
24 .DE | |
25 \fISlocal\fP is a program designed to allow you to have | |
26 your inbound mail processed according to a complex | |
27 set of selection criteria. | |
28 You do not normally invoke \fIslocal\fP yourself, | |
29 rather \fIslocal\fP is invoked on your behalf by your system's | |
30 Message Transfer Agent. | |
31 | |
32 The message selection | |
33 criteria used by \fIslocal\fP | |
34 is specified in the file \fI\&.maildelivery\fP | |
35 in the user's home directory. The format of this file | |
36 is given below. | |
37 | |
38 The message delivery address and message sender are | |
39 determined from the Message Transfer Agent | |
40 envelope information, if possible. Under \fISendMail\fP, | |
41 the sender will obtained from the UUCP \*(lqFrom\ \*(rq | |
42 line, if present. The user may override these values | |
43 with command line arguments, or arguments to | |
44 the `\-addr' and `\-sender' switches. | |
45 | |
46 The message is normally read from the standard input. | |
47 The `\-file' switch sets the name of the file from which | |
48 the message should be read, instead of reading stdin. | |
49 The `\-user' switch tells \fIslocal\fP | |
50 the name of the user for whom it is delivering mail. | |
51 The `\-mailbox' switch tells \fIslocal\fP the name | |
52 of the user's maildrop file. | |
53 | |
54 The `\-info' switch may be used to pass an arbitrary | |
55 argument to sub-processes which \fIslocal\fP may | |
56 invoke on your behalf. | |
57 The `\-verbose' switch causes \fIslocal\fP | |
58 to give information on stdout about its progress. | |
59 The `\-debug' switch produces more verbose debugging output on stderr. | |
60 | |
61 .Uh "Message Transfer Agents" | |
62 If your MTA is \fISendMail\fP, | |
63 you should include the line | |
64 .sp | |
65 .nf | |
66 .in +.5i | |
67 \*(lq|\ /usr/local/mh/lib/slocal\ \-user\ username\*(rq | |
68 .in -.5i | |
69 .fi | |
70 .sp | |
71 in your \&.forward file in your home directory. | |
72 This will cause \fISendMail\fP to invoke \fIslocal\fP on your behalf. | |
73 | |
74 If your MTA is \fIMMDF-I\fP, | |
75 you should (symbolically) link /usr/local/mh/lib/slocal to the file | |
76 bin/rcvmail in your home directory. | |
77 This will cause \fIMMDF-I\fP to invoke \fIslocal\fP on your behalf | |
78 with the correct \*(lq\fIaddress\ info\ sender\fP\*(rq arguments. | |
79 | |
80 If your MTA is \fIMMDF-II\fP, | |
81 then you should not use \fIslocal\fP. | |
82 An equivalent functionality is already provided by \fIMMDF-II\fP; | |
83 see maildelivery(5) for details. | |
84 | |
85 .Uh "The Maildelivery File" | |
86 | |
87 The \fI\&.maildelivery\fR file | |
88 controls how local delivery is performed. | |
89 Each line of this file | |
90 consists of five fields, separated by white-space or comma. | |
91 Since double-quotes are honored, | |
92 these characters may be included in a single argument by enclosing the | |
93 entire argument in double-quotes. | |
94 A double-quote can be included by preceding it with a backslash. | |
95 Lines beginning with `#' are ignored. | |
96 The format of each line in the \fI\&.maildelivery\fR file is: | |
97 | |
98 | |
99 \fBheader pattern action result string\fR | |
100 .sp | |
101 .in +.5i | |
102 .ti -.5i | |
103 \fBheader\fP: | |
104 .br | |
105 The name of a header field that is to be searched for a pattern. | |
106 This is any field in the headers of the message that might be present. | |
107 The following special fields are also defined: | |
108 .sp | |
109 .in +1i | |
110 .ta +1i | |
111 .ti -1i | |
112 \fIsource\fR the out-of-band sender information | |
113 .ti -1i | |
114 \fIaddr\fR the address that was used to cause delivery to the recipient | |
115 .ti -1i | |
116 \fIdefault\fR this matches \fIonly\fR if the message hasn't been delivered yet | |
117 .ti -1i | |
118 \fI*\fR this always matches | |
119 .in -1i | |
120 | |
121 .ti -.5i | |
122 \fBpattern\fR: | |
123 .br | |
124 The sequence | |
125 of characters to match in the specified header field. | |
126 Matching is case-insensitive, but does not use regular expressions. | |
127 | |
128 .ti -.5i | |
129 \fBaction\fR: | |
130 .br | |
131 The action to take to deliver the message: | |
132 .sp | |
133 .in +1i | |
134 .ta +1i | |
135 .ti -1i | |
136 \fIdestroy\fR This action always succeeds. | |
137 | |
138 .ti -1i | |
139 \fIfile\fR or > Append | |
140 the message to the file named by \fBstring\fR. | |
141 The message is appended to the file in the maildrop | |
142 format which is used by your message transport system. | |
143 If the message can be appended to the file, | |
144 then this action succeeds. | |
145 When writing to the file, | |
146 a \*(lqDelivery\-Date:\ date\*(rq header is added | |
147 which indicates the date and time that message was appended to the file. | |
148 | |
149 .ti -1i | |
150 \fImbox\fR Identical | |
151 to \fIfile\fR, | |
152 but always appends the message using the format used by \fIpackf\fR | |
153 (the MMDF mailbox format). | |
154 | |
155 .ti -1i | |
156 \fIpipe\fR or | Pipe | |
157 the message as the standard input to the command named by \fBstring\fR, | |
158 using the Bourne shell \fIsh\fR(1) to interpret the string. | |
159 Prior to giving the string to the shell, | |
160 it is expanded with the following built-in variables: | |
161 .sp | |
162 .in +1i | |
163 .ta +1i | |
164 .ti -1i | |
165 $(sender) the out-of-band sender information | |
166 .ti -1i | |
167 $(address) the address that was used to cause delivery to the recipient | |
168 .ti -1i | |
169 $(size) the size of the message in bytes | |
170 .ti -1i | |
171 $(reply\-to) either the \*(lqReply\-To:\*(rq or \*(lqFrom:\*(rq field | |
172 of the message | |
173 .ti -1i | |
174 $(info) the out-of-band information specified | |
175 .in -1i | |
176 .ti -1i | |
177 \fIqpipe\fR or | |
178 .ti -1i | |
179 \fI<caret>\fR Similar to \fIpipe\fR, | |
180 but executes the command directly, | |
181 after built-in variable expansion, | |
182 without assistance from the shell. | |
183 This action can be used to avoid quoting special characters | |
184 which your shell might interpret. | |
185 .in -1i | |
186 | |
187 .ti -.5i | |
188 \fBresult\fR: | |
189 .br | |
190 Indicates how the action should be performed: | |
191 | |
192 .in +1i | |
193 .ta +1i | |
194 .ti -1i | |
195 \fIA\fR Perform the action. | |
196 If the action succeeds, then the message is considered delivered. | |
197 | |
198 .ti -1i | |
199 \fIR\fR Perform the action. | |
200 Regardless of the outcome of the action, | |
201 the message is not considered delivered. | |
202 | |
203 .ti -1i | |
204 \fI?\fR Perform | |
205 the action only if the message has not been delivered. | |
206 If the action succeeds, then the message is considered delivered. | |
207 | |
208 .ti -1i | |
209 \fIN\fR Perform | |
210 the action only if the message has not been delivered | |
211 and the previous action succeeded. | |
212 If this action succeeds, then the message is considered delivered. | |
213 .sp | |
214 .in -1i | |
215 .in -.5i | |
216 To summarize, here's an example: | |
217 .sp | |
218 .if t .in +.5i | |
219 .nf | |
220 .ta \w'default 'u +\w'mh-workersxx 'uC +\w'destroy 'uC +\w'result 'u | |
221 #\fIfield\fR \fIpattern\fR \fIaction\fR \fIresult\fR \fIstring\fR | |
222 # lines starting with a '#' are ignored, as are blank lines | |
223 # | |
224 # file mail with mmdf2 in the \*(lqTo:\*(rq line into file mmdf2.log | |
225 \fITo mmdf2 file A mmdf2.log\fP | |
226 # Messages from mmdf pipe to the program err-message-archive | |
227 \fIFrom mmdf pipe A /bin/err-message-archive\fP | |
228 # Anything with the \*(lqSender:\*(rq address \*(lqmh-workers\*(rq | |
229 # file in mh.log if not filed already | |
230 \fISender mh-workers file ? mh.log\fP | |
231 # \*(lqTo:\*(rq unix \- put in file unix-news | |
232 \fITo Unix > A unix-news\fP | |
233 .\" # if the address is jpo=mmdf \- pipe into mmdf-redist | |
234 .\" \fIaddr jpo=mmdf | A mmdf-redist\fP | |
235 # if the address is jpo=ack \- send an acknowledgement copy back | |
236 \fIaddr jpo=ack \fP|\fI R \*(lq/bin/resend\0\-r\0$(reply-to)\*(rq\fP | |
237 # anything from steve \- destroy! | |
238 \fIFrom steve destroy A \-\fP | |
239 # anything not matched yet \- put into mailbox | |
240 \fIdefault \- > ? mailbox\fP | |
241 # always run rcvtty | |
242 \fI* \- \fP|\fI R /mh/lib/rcvtty\fP | |
243 .re | |
244 .fi | |
245 .if t .in -.5i | |
246 | |
247 The file is always read completely, | |
248 so that several matches can be made and several actions can be taken. | |
249 The \fI\&.maildelivery\fR file must be owned either by the user or by root, | |
250 and must be writable only by the owner. | |
251 If the \fI\&.maildelivery\fR file cannot be found, | |
252 or does not perform an action which delivers the message, | |
253 then the file /usr/local/mh/lib/maildelivery is read according to the same rules. | |
254 This file must be owned by the root and must be writable only by the root. | |
255 If this file cannot be found | |
256 or does not perform an action which delivers the message, | |
257 then standard delivery to the user's maildrop is performed. | |
258 | |
259 .Uh "Sub-process environment" | |
260 When a process is invoked, its environment is: | |
261 the user/group-ids are set to recipient's ids; | |
262 the working directory is the recipient's home directory; | |
263 the umask is 0077; | |
264 the process has no /dev/tty; | |
265 the standard input is set to the message; | |
266 the standard output and diagnostic output are set to /dev/null; | |
267 all other file-descriptors are closed; | |
268 the envariables \fB$USER\fR, \fB$HOME\fR, \fB$SHELL\fR are set | |
269 appropriately, | |
270 and no other envariables exist. | |
271 | |
272 The process is given a certain amount of time to execute. | |
273 If the process does not exit within this limit, | |
274 the process will be terminated with extreme prejudice. | |
275 The amount of time is calculated as ((size x 60) + 300) seconds, | |
276 where size is the number of bytes in the message. | |
277 | |
278 The exit status of the process is consulted in determining the success of the | |
279 action. | |
280 An exit status of zero means that the action succeeded. | |
281 Any other exit status (or abnormal termination) means that the action failed. | |
282 | |
283 In order to avoid any time limitations, | |
284 you might implement a process that began by \fIforking\fR. | |
285 The parent would return the appropriate value immediately, | |
286 and the child could continue on, | |
287 doing whatever it wanted for as long as it wanted. | |
288 This approach is somewhat risky if the parent is going to return an | |
289 exit status of zero. | |
290 If the parent is going to return a non-zero exit status, | |
291 then this approach can lead to quicker delivery into your maildrop. | |
292 .Fi | |
293 ^/usr/local/mh/lib/mtstailor~^MH tailor file | |
294 ^$HOME/\&.maildelivery~^The file controlling local delivery | |
295 ^/usr/local/mh/lib/maildelivery~^Rather than the standard file | |
296 ^/var/mail/$USER~^The default maildrop | |
297 .Sa | |
298 rcvstore(1), mhook(1), mh\-format(5) | |
299 .De | |
300 `\-noverbose' | |
301 .Ds | |
302 `\-maildelivery \&.maildelivery' | |
303 .Ds | |
304 `\-mailbox /var/mail/$USER' | |
305 .Ds | |
306 `\-file' defaults to stdin | |
307 .Ds | |
308 `\-user' defaults to the current user | |
309 .Co | |
310 None | |
311 .Hi | |
312 \fISlocal\fP is designed to be backward-compatible with the | |
313 \fImaildelivery\fP facility provided by \fIMMDF-II\fP. | |
314 Thus, the \fI\&.maildelivery\fP file syntax is limited, | |
315 as is the functionality of \fIslocal\fP. | |
316 | |
317 In addition to an exit status of zero, | |
318 the \fIMMDF\fR values \fIRP_MOK\fR (32) and \fIRP_OK\fR (9) | |
319 mean that the message has been fully delivered. | |
320 Any other non-zero exit status, | |
321 including abnormal termination, | |
322 is interpreted as the \fIMMDF\fR value \fIRP_MECH\fR (200), | |
323 which means \*(lquse an alternate route\*(rq | |
324 (deliver the message to the maildrop). | |
325 .Bu | |
326 Only two return codes are meaningful, others should be. | |
327 | |
328 \fISlocal\fP is designed to be | |
329 backwards-compatible with the \fImaildelivery\fP functionality provided | |
330 by \fBMMDF-II\fP. | |
331 | |
332 Versions of \fIMMDF\fR with the \fImaildelivery\fR mechanism aren't | |
333 entirely backwards-compatible with earlier versions of \fIMMDF\fP. | |
334 If you have an \fIMMDF-I\fP old-style hook, | |
335 the best you can do is to have a one-line | |
336 \fI\&.maildelivery\fR file: | |
337 | |
338 .ti +.5i | |
339 default \- pipe A \*(lqbin/rcvmail $(address) $(info) $(sender)\*(rq | |
340 .En |