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