![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mailsurr.4 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10no / lbin / mailx / man|
Return to mailsurr.4 CVS log | Up to [Research Unix] / researchv10no / lbin / mailx / man |
1.1 root 1: '\"macro stdmacro
2: .if n .pH g4.mailsurr %W% of %G%
3: .\" Emphasis
4: .de Em
5: \f2\\$1\fP\\$2
6: ..
7: .nr X
8: .if \nX=0 .ds x} mailsurr 4 "Essential Utilities" "\&"
9: .if \nX=1 .ds x} mailsurr 4 "Essential Utilities"
10: .if \nX=2 .ds x} mailsurr 4 "" "\&"
11: .if \nX=3 .ds x} mailsurr "" "" "\&"
12: .TH \*(x}
13: .SH NAME
14: \f4mailsurr\f1 \- surrogate commands for routing and transport of mail
15: .SH DESCRIPTION
16: The \f4mailsurr\f1 file contains routing and transport surrogate
17: commands used by the \f4mail\fP command.
18: Each entry in \f4mailsurr\f1 has three whitespace-separated,
19: single quote delimited fields:
20: .P
21: .RS
22: .ft 4
23: \&'\f2sender\fP' '\f2recipient\fP' '\f2command\fP'
24: .ft 1
25: .RE
26: .P
27: or a line that begins
28: .P
29: .RS
30: .ft 4
31: Defaults:
32: .ft 1
33: .RE
34: .P
35: Entries and fields may span multiple lines,
36: but leading whitespace on field continuation lines is ignored.
37: Fields must be less than 1024 characters long after expansion (see
38: below).
39: .PP
40: The sender and recipient fields are regular expressions.
41: If the sender and recipient fields match those of the message currently
42: being processed, the associated command is invoked.
43: .PP
44: The \f2command\fP field may have one of the following five forms:
45: .P
46: .RS
47: .ft 4
48: .nf
49: \f4A\f1[\f4ccept\f1]
50: \f4D\f1[\f4eny\f1]
51: \f4T\f1[\f4ranslate\f1] \f4R=\f1[\f4\(bv\f1]\f2string\f1
52: \f4< S=...;C=...;F=...;\f2 command\f1
53: \f4>\fP \f2command\f1
54: .fi
55: .ft 1
56: .RE
57: .SS "Regular Expressions"
58: The sender and recipient fields are composed of regular
59: expressions (REs) which are digested by the \f4regexp\fP(5)
60: \f4compile\fP and \f4advance\fP procedures
61: in the C library.
62: The regular expressions matched are those from \f4ed\fP(1), with simple
63: parentheses \f4()\fP playing the role of \f4\e(\e)\fP and the addition of
64: the \f4+\fP and \f4?\fP operators from \f4egrep\fP(1).
65: Any single quotes embedded within the REs
66: .Em must
67: be escaped by prepending them with a backslash or
68: the RE is not interpreted properly.
69: .PP
70: The \f4mail\fP command prepends a circumflex (\f4^\f1)
71: to the start and appends a dollar sign (\f4$\f1) to the
72: end of each RE so that it matches the entire string.
73: Therefore it would be an error
74: to use \f4^\f2RE\f4$\f1 in the sender and recipient fields.
75: To provide case insensitivity, all REs are
76: converted to lower case before compilation,
77: and all sender and recipient information is converted to
78: lower case before comparison.
79: This conversion is done only for the purposes of RE pattern matching;
80: the information contained within the
81: message's header is
82: .Em not
83: modified.
84: .PP
85: The sub-expression pattern matching capabilities of \f4regexp\fP may be used
86: in the command field,
87: that is, \f4(\f1...\f4)\f1, where 1 \(<= \f2n\fP \(<= 9.
88: Any occurrences of \f4\e\e\f2n\f1 in the
89: replacement string are themselves replaced by the corresponding \f4(\f1...\f4)\f1
90: substring in the matched pattern.
91: The sub-expression fields from both the sender and recipient fields are
92: accessible, with the fields numbered 1 to 9 from left to right.
93: .SS "Accept and Deny Commands"
94: \f4Accept\fP instructs \f4rmail\fP to continue its processing with the \f4mailsurr\f1
95: file,
96: but to ignore any subsequent matching \f4Deny\fP.
97: That is, unconditionally accept this message for delivery processing.
98: \f4Deny\fP instructs \f4rmail\fP to stop processing the \f4mailsurr\f1 file
99: and to send a negative delivery notification to the originator of the message.
100: Whichever is encountered first takes precedence.
101: .SS "Translate Command"
102: \f4Translate\fP allows optional on-the-fly translation of recipient address
103: information.
104: The \f2recipient\fP replacement string is specified as \f4R=\f2string\f1.
105: .PP
106: For example, given a command line of the form
107: .P
108: .RS 2
109: .nf
110: \f4\&'.+' '([^!]+)@(.+)\e.EUO\e.ATT\e.com' 'Translate R=attmail!\e\e2!\e\e1'\f1
111: .fi
112: .RE
113: .P
114: and a recipient address of \[email protected]\fP
115: the resulting recipient address would be \f4attmail!sysa!rob\fP.
116: .PP
117: Should the first character after the equal sign be a `\(bv',
118: the remainder of the string is taken as a command line
119: to be directly executed by \f4rmail\fP.
120: If any \f4sh\fP(1) syntax is required
121: (metacharacters, redirection, etc.),
122: then the surrogate command must be of the form:
123: .P
124: .RS
125: \f4sh \-c "\f2shell command line...\f4"\f1
126: .RE
127: .P
128: Special care must be taken to escape properly any embedded back-slashes
129: and single or double quotes,
130: since \f4rmail\fP uses double quoting to group
131: whitespace delimited fields that are meant to be considered as a single
132: argument to \f4execl\fP(2).
133: It is assumed that the executed command will write one or more replacement
134: strings on \f4stdout\fP, one per line.
135: If more than one line is returned,
136: each is assumed to be a different recipient for the message.
137: This mechanism is useful for mailing list expansions.
138: As stated above, any occurrences of \f4\e\e\f2n\f1 are replaced by the
139: appropriate substring
140: .Em before
141: the command is executed.
142: If the invoked command does not return at least one replacement string
143: (no output or just a newline),
144: the original string is
145: .Em not
146: modified.
147: For example, the command line
148: .P
149: .RS
150: \f4\&'.+' '(.+)' 'Translate R=\(bv/usr/bin/findpath \e\e1'\fP
151: .RE
152: .P
153: allows local routing decisions to be made.
154: .PP
155: If the recipient address string is modified, \f4mailsurr\fP
156: is rescanned from the beginning with the new address(es),
157: and any prior determination of \f4Accept\fP (see above) is discarded.
158: .SS "\f4<\fP \f2command\fP"
159: The intent of a \f4<\fP command is that it is invoked as part of the transport
160: and delivery mechanism,
161: with the ready-for-delivery message available to the command
162: at its standard input.
163: As such, there are three conditions possible when the command exits:
164: .RS
165: .TP 10
166: Success
167: The command successfully delivered the message.
168: What actually constitutes successful delivery may be different
169: within the context of different surrogates.
170: The \f4rmail\fP process assumes that no more processing
171: is required for the message for the current recipient.
172: .TP 10
173: Continue
174: The command performed some function
175: (logging remote message traffic, for example)
176: but did not do what would be considered message delivery.
177: The \f4rmail\fP process continues to scan the
178: \f4mailsurr\f1 file looking for some
179: other delivery mechanism.
180: .TP 10
181: Failure
182: The command encountered some catastrophic failure.
183: The \f4rmail\fP process
184: stops processing the message and sends to the originator of the message
185: a non-delivery notification that includes any \f4stdout\fP and \f4stderr\fP
186: output generated by the command.
187: .RE
188: .PP
189: The semantics of the \f4<\fP command field in the \f4mailsurr\fP file allow
190: the specification of exit codes that constitute success, continue, and
191: failure for each surrogate command individually.
192: The syntax of the exit state specification is:
193: .P
194: .RS
195: .nf
196: \f4<\f1 WS [\f2exit_state_id\f4=\f2ec\f1[\f4,\f2ec\f1[,...]]\f4;\f1][\f2exit_state_id\f4=\f2ec\f1[,\f2ec\f1[,...]]\f4;\f1
197: [...]]] WS\0\f2surrogate_cmd_line\f1
198: .fi
199: .RE
200: .P
201: .SM
202: .I WS
203: is whitespace.
204: \f2exit_state_id\fP can have the value \f4S\fP, \f4C\fP, or \f4F\fP.
205: \f2exit_state_id\fPs can be specified in any order.
206: \f2ec\fP can
207: be:
208: .IP
209: any integer 0 \(<= \f2n\fP \(<= 255
210: [Negative exit values are not possible.
211: See \f4exit\fP(2) and \f4wait\fP(2).]
212: .IP
213: a range of integers of the form \f2lower_limit\f1\-\f2upper_limit\f1
214: where the limits are \(>= 0 and \(<= 255, and
215: .IP
216: \f4\(**\fP, which implies \f2anything\fP
217: .PP
218: For example, a command field of the form:
219: .P
220: .RS
221: \&'\f4< S=1-5,99;C=0,12;F=\(**; \f2command\fP %R'\f1
222: .RE
223: .P
224: indicates that exit values of 1 through 5, and 99,
225: are to be considered success,
226: values of 0 (zero) and 12 indicate continue,
227: and that anything else implies failure.
228: If not explicitly supplied, default settings are \f4S=0;C=\(**;\fP.
229: .PP
230: It may be possible for ambiguous entries to exist
231: if two exit states have the same
232: value, for example, \f4S=12,23;C=\(**;F=23,52\fP; or \f4S=\(**;C=9;F=\(**;\fP.
233: To account for this, \f4rmail\fP looks for
234: .Em explicit
235: exit
236: values (that is,
237: .Em not
238: \&``\(**'') in
239: order of success, continue, failure.
240: Not finding an explicit match,
241: \f4rmail\fP then scans for ``\(**'' in the same order.
242: .PP
243: It is possible to eliminate an exit state completely by setting that
244: state's value to an impossible number.
245: Since exit values must be between 0 and 255 (inclusive),
246: a value of 256 is a good one to use.
247: For example, if you had a surrogate command that was to log all message
248: traffic, a \f4mailsurr\f1 entry of
249: .P
250: .RS 2
251: .nf
252: \f4\&'(.+)'\0'(.+)'\0'\f4<\fPS=256;C=*;\0/usr/lib/mail/surrcmd/logger \e\e1 \e\e2'\f1
253: .fi
254: .RE
255: .P
256: would always indicate continue.
257: .PP
258: Surrogate commands are executed by \f4rmail\fP directly.
259: If any shell syntax is required
260: (metacharacters, redirection, etc.),
261: then the surrogate command must be of the form:
262: .P
263: .RS
264: \f4sh \-c "\f2shell command line...\f4"\f1
265: .RE
266: .P
267: Special care must be taken to properly escape any embedded
268: back-slashes and other characters special to the shell
269: as stated in the ``Translate'' section above.
270: .PP
271: If there are no matching \f4<\fP commands,
272: or all matching \f4<\fP commands exit with a continue indication,
273: \f4rmail\fP attempts to deliver the message itself by assuming
274: that the recipient is local and delivering
275: the message to \f4/var/mail/\fP\f2recipient\fP.
276: .SS "\f4>\f1 command"
277: The intent of a \f4>\fP command is that it is invoked
278: .Em after
279: a successful delivery to do any post-delivery processing that may be required.
280: Matching \f4>\fP commands are executed only if some \f4<\fP command indicates a
281: successful delivery (see the previous section)
282: or local delivery processing is successful.
283: The \f4mailsurr\f1 file is rescanned and
284: all matching \f4>\fP commands,
285: not just those following the successful \f4<\fP command,
286: are executed in order.
287: The exit status of an \f4>\fP command is ignored.
288: .SS "Defaults: Line"
289: The default settings may be redefined by creating a separate
290: line in the \f4mailsurr\f1 file of the form
291: .P
292: .RS
293: .nf
294: \f4Defaults: \f1[\f4S=\f1...\f4;\f1][\f4C=\f1...\f4;\f1][\f4F\f1=...\f4;\f1]
295: .fi
296: .ft 1
297: .RE
298: .P
299: \f4Defaults:\fP lines are honored and the indicated default values
300: redefined when the line is encountered during the normal processing
301: of the \f4mailsurr\f1 file.
302: Therefore, to redefine the defaults globally, the \f4Defaults:\fP
303: line should be the first line in the file.
304: It is possible to have multiple \f4Defaults:\fP lines in the \f4mailsurr\f1 file,
305: where each subsequent line overrides the previous one.
306: .SS "Surrogate Command Keyword Replacement."
307: Certain special sequences are textually-substituted
308: in surrogate commands before they are invoked:
309: .P
310: .RS
311: .PD 0
312: .TP 11
313: \f4%n\f1
314: the recipient's full name.
315: .TP
316: \f4%R\f1
317: the full return path to the originator (useful for sending replies,
318: delivery failure notifications, etc.)
319: .TP
320: \f4%c\f1
321: value of the \f5Content-Type:\fP header line if present.
322: .TP
323: \f4%C\f1
324: \&``\f5text\fP'' or ``\f5binary\fP'', depending on an actual scan of the content.
325: This is independent of the value of any \f5Content-Type\fP header line encountered
326: (useful when calling \f4ckbinarsys\fP.)
327: .TP
328: \f4%S\f1
329: the value of the \f5Subject:\fP header line, if present.
330: .TP
331: \f4%l\f1
332: value of the \f5Content-Length:\fP header line.
333: .TP
334: \f4%L\f1
335: the local system name.
336: This will be either \f4CLUSTER\fP from \f4mailcnfg\fP or the value returned
337: by \f4uname\fP.
338: .TP
339: \f4%U\f1
340: the local system name, as returned by \f4uname\fP.
341: .TP
342: \f4%X\f1
343: the value of \f4SMARTERHOST\fP in \f4mailcnfg\fP.
344: .TP
345: \f4%D\f1
346: the local domain name.
347: This will be either \f4DOMAIN\fP from \f4mailcnfg\fP, or the value returned by
348: \f4getdomainame\fP.
349: .TP
350: \f4\e\e\f2n\f1
351: as described above, the corresponding (...)
352: substring in the matched patterns.
353: This implies that the \f4regexp\fP limitation of 9 substrings is applied
354: to the sender and recipient REs collectively.
355: .TP
356: \f4%\f2keywords\f1
357: Other keywords as specified in \f4/etc/mail/mailcnfg\fP.
358: See \f4mailcnfg\fP(4).
359: .RE
360: The sequences \f4%L\fP, \f4%U\fP, \f4%D\fP, and \f4%\f2keywords\f1 are
361: permitted within the sender and recipient fields as well as in the command
362: fields.
363: .PD
364: .PP
365: An example of the \f4mailsurr\f1 entry that replaces the
366: \f4uux\fP ``built-in'' of previous versions of \f4rmail\fP is:
367: .P
368: .RS
369: .nf
370: \f4\&'.+' '([^@!]+)!(.+)' '< /usr/bin/uux \- \e\e1!rmail (\e\e2)'\fP
371: .fi
372: .RE
373: .SS "Mail Surrogate Examples"
374: Some examples of mail surrogates include the distribution of message-waiting
375: notifications to LAN-based recipients and lighting Message-Waiting Lamps,
376: the ability to mail output to printers,
377: and the logging of all \f4rmail\fP requests between remote systems
378: (messages passing through the local system).
379: The following is a sample \f4mailsurr\f1 file:
380: .P
381: .nf
382: .ft 4
383: \s-1#
384: # Some common remote mail surrogates follow. To activate any
385: # or all of them, remove the `#' (comment indicators) from
386: # the beginning of the appropriate lines. Remember that they
387: # will be tried in the order they are encountered in the file,
388: # so put preferred surrogates first.
389:
390: # Prevent all shell meta-characters
391: \&'.+' '.*[`;&|^<>()].*' 'Deny'
392:
393: # Map all names of the form local-machine!user -> user
394: \&'.+' '%L!(.+)' 'Translate R=\\1'
395:
396: # Map all names of the form uname!user -> user
397: # Must be turned on when using mail in a cluster environment.
398: #'.+' '%U!(.+)' 'Translate R=\\1'
399:
400: # Map all names of the form user@host -> host!user
401: \&'.+' '([^!@]+)@(.+)' 'Translate R=\\2!\\1'
402:
403: # Map all names of the form host.uucp!user -> host!user
404: \&'.+' '([^!@]+)\\.uucp!(.+)' 'Translate R=\\1!\\2'
405:
406: # Map all names of the form host.local-domain!user -> host!user
407: # DOMAIN= within /etc/mail/mailcnfg will override getdomainame(3).
408: \&'.+' '([^!@]+)%D!(.+)' 'Translate R=\\1!\\2'
409:
410: # Allow access to `attmail' from remote system `sysa'
411: \&'sysa!.*' 'attmail!.+' 'Accept'
412:
413: # Deny access to `attmail' from all other remotes
414: \&'.+!.+' 'attmail!.+' 'Deny'
415:
416: # Send mail for `laser' to attached laser printer
417: # Make certain that failures are reported via return mail.
418: \&'.+' 'laser' '\f4<\fP S=0;F=*; lp \-dlaser'
419:
420: # Run all local names through the mail alias processor
421: #
422: \&'.+' '[^!@]+' 'Translate R=|/usr/bin/mailalias %n'
423:
424: # For remote mail via nusend
425: #'.+' '([^!]+)!(.+)' '\f4<\fP /usr/bin/nusend \-d \e\e1 \-s \-e \-!"rmail \e\e2" \-'
426:
427: # For remote mail via usend
428: \&'.+' '([^!]+)!(.+)'
429: '\f4<\fP /usr/bin/usend \-s \-d\e\e1 \-uNoLogin \-!"rmail \e\e2" \- '
430:
431: # For remote mail via uucp
432: \&'.+' '([^!@]+)!.+' '\f4<\fPS=256;C=0;
433: /usr/lib/mail/surrcmd/ckbinarsys \-t %C \-s \e\e1'
434: \&'.+' '([^!@]+)!(.+)' '\f4<\fP /usr/bin/uux \- \e\e1!rmail (\e\e2)'
435:
436: # For remote mail via smtp
437: #'.+' '([^!@]+)!(.+)' '< /usr/lib/mail/surrcmd/smtpqer %R %n'
438:
439: # If none of the above work, then let a router change the address.
440: #'.+' '.*[!@].*' 'Translate R=| /usr/lib/mail/surrcmd/smail -A %n'
441:
442: # If none of the above work, then ship remote mail off to a smarter host.
443: # Make certain that SMARTERHOST= is defined within /etc/mail/mailcnfg.
444: #'.+' '.*[!@].*' 'Translate R=%X!%n'
445:
446: # Log successful message deliveries
447: \&'(.+)' '(.+)' '\f4>\fP/usr/lib/mail/surrcmd/logger \\1 \\2'\s0
448: .ft 1
449: .fi
450: .PP
451: Note that invoking \f4mail\fP to read mail does not
452: involve the \f4mailsurr\f1 file or any surrogate processing.
453: .SS "Security"
454: Surrogate commands execute
455: with the permissions of \f4rmail\fP (user \s-1ID\s+1 of the invoker,
456: group \s-1ID\s+1 of mail).
457: This allows surrogate commands to validate themselves,
458: checking that their effective group \s-1ID\s+1 was \f4mail\fP at invocation time.
459: This requires that all additions to \f4mailsurr\f1 be scrutinized before
460: insertion to prevent any unauthorized access to users' mail files.
461: All surrogate commands are executed with the path
462: \f4/usr/lib/mail/surrcmd:/usr/bin\fP.
463: .SS "Debugging New \f4mailsurr\f1 Entries"
464: To debug \f4mailsurr\fP files,
465: use the \f4\-T\fP option of the \f4mail\fP command.
466: The \f4\-T\fP option requires an argument that is taken as the
467: pathname of a test \f4mailsurr\fP file.
468: If null (as in \f4\-T ""\fP),
469: the system \f4mailsurr\f1 file is used.
470: Enter
471: .P
472: .RS
473: .nf
474: \f4mail\ \-T \f2test_file\0recipient\f1
475: .fi
476: .RE
477: .P
478: and some trivial message (like ``\f4testing\fP''),
479: followed by a line with either just a dot (``\f4.\fP'') or a cntl-D.
480: The result of using the \f4\-T\fP option is displayed on standard output and
481: shows the inputs and resulting transformations as \f4mailsurr\f1 is
482: processed by the \f4mail\fP command for the indicated \f2recipient\fP.
483: .PP
484: Mail messages will never be sent or delivered when using the \f4\-T\fP option.
485: .SH "FILES"
486: .PD 0
487: .TP 27
488: \f4/etc/mail/mailsurr\fP
489: .TP 27
490: \f4/usr/lib/mail/surrcmd/\(**\fP
491: surrogate commands
492: .TP 27
493: \f4/etc/mail/mailcnfg\fP
494: initialization information for \f4mail\fP
495: .PD
496: .SH SEE ALSO
497: \f4ckbinarsys\fP(1M),
498: \f4mailcnfg\fP(4)
499: .br
500: \f4mail\fP(1),
501: \f4sh\fP(1),
502: \f4uux\fP(1),
503: \f4ed\fP(1),
504: \f4egrep\fP(1),
505: in the \f2User's Reference Manual\f1
506: .br
507: \f4exec\fP(2),
508: \f4exit\fP(2),
509: \f4wait\fP(2),
510: \f4popen\fP(3),
511: \f4regexp\fP(5),
512: \f4getdomainname\f1(3)
513: in the \f2Programmer's Reference Manual\f1
514: .SH "NOTES"
515: It would be unwise to install new entries into the system
516: \f4mailsurr\f1 file without verifying at least their syntactical
517: correctness via `\f4mail\fP \f4\-\T\fP \f2...\fP' as described above.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.