mailsurr(4) mailsurr(4)
NAME
mailsurr - surrogate commands for routing and transport of mail
DESCRIPTION
The mailsurr file contains routing and transport surrogate commands
used by the mail command. Each entry in mailsurr has three
whitespace-separated, single quote delimited fields:
'sender' 'recipient' 'command'
or a line that begins
Defaults:
Entries and fields may span multiple lines, but leading whitespace on
field continuation lines is ignored. Fields must be less than 1024
characters long after expansion.
The sender and recipient fields are regular expressions. If the sender
and recipient fields match those of the message currently being pro-
cessed, the associated command is invoked.
The command field may have one of the following five forms:
A[ccept]
D[eny]
T[ranslate] R=[|]string
< S=...;C=...;F=...; command
> command
Regular Expressions
The sender and recipient fields are composed of regular expressions
(REs) which are digested by the regexp(5) compile and advance pro-
cedures in the C library. The regular expressions matched are those
from ed(1), with simple parentheses () playing the role of \(\) and
the addition of the + and ? operators from egrep(1). Any single quotes
embedded within the REs must be escaped by prepending them with a
backslash or the RE is not interpreted properly.
The mail command prepends a circumflex (^) to the start and appends a
dollar sign ($) to the end of each RE so that it matches the entire
string. Therefore it would be an error to use ^RE$ in the sender and
recipient fields. To provide case insensitivity, all REs are converted
to lowercase before compilation, and all sender and recipient informa-
tion is converted to lowercase before comparison. This conversion is
done only for the purposes of RE pattern matching; the information
contained within the message's header is not modified.
Page 1 Reliant UNIX 5.44 Printed 11/98
mailsurr(4) mailsurr(4)
The sub-expression pattern matching capabilities of regexp may be used
in the command field, that is, (...), where 1 <= n <= 9. Any
occurrences of \\n in the replacement string are themselves replaced
by the corresponding (...) substring in the matched pattern. The sub-
expression fields from both the sender and recipient fields are acces-
sible, with the fields numbered 1 to 9 from left to right.
Accept and Deny Commands
Accept instructs rmail to continue its processing with the mailsurr
file, but to ignore any subsequent matching Deny. That is, uncondi-
tionally accept this message for delivery processing. Deny instructs
rmail to stop processing the mailsurr file and to send a negative
delivery notification to the originator of the message. Whichever is
encountered first takes precedence.
Translate Command
Translate allows optional on-the-fly translation of recipient address
information. The recipient replacement string is specified as
R=string.
For example, given a command line of the form
'.+' '([^!]+)@(.+)\.EUO\.ATT\.com' 'Translate R=attmail!\\2!\\1'
and a recipient address of rob@sysa.EUO.ATT.COM the resulting reci-
pient address would be attmail!sysa!rob.
Should the first character after the equal sign be a "|", the
remainder of the string is taken as a command line to be directly exe-
cuted by rmail. If any sh(1) syntax is required (metacharacters or
redirection), then the surrogate command must be of the form:
sh -c "shell command line..."
Special care must be taken to escape properly any embedded back-
slashes and single or double quotes, since rmail uses double quoting
to group whitespace delimited fields that are meant to be considered
as a single argument to execl(2). It is assumed that the executed com-
mand will write one or more replacement strings on stdout, one per
line. If more than one line is returned, each is assumed to be a dif-
ferent recipient for the message. This mechanism is useful for mailing
list expansions. As stated above, any occurrences of \\n are replaced
by the appropriate substring before the command is executed. If the
invoked command does not return at least one replacement string (no
output or just a newline), the original string is not modified. For
example, the command line
'.+' '(.+)' 'Translate R=|/usr/bin/findpath \\1'
allows local routing decisions to be made.
Page 2 Reliant UNIX 5.44 Printed 11/98
mailsurr(4) mailsurr(4)
If the recipient address string is modified, mailsurr is rescanned
from the beginning with the new address, and any prior determination
of Accept is discarded.
< command
The intent of a < command is that it is invoked as part of the trans-
port and delivery mechanism, with the ready-for-delivery message
available to the command at its standard input. As such, there are
three conditions possible when the command exits:
Success The command successfully delivered the message. What actu-
ally constitutes successful delivery may be different within
the context of different surrogates. The rmail process
assumes that no more processing is required for the message
for the current recipient.
Continue The command performed some function (logging remote message
traffic, for example) but did not do what would be con-
sidered message delivery. The rmail process continues to
scan the mailsurr file looking for some other delivery
mechanism.
Failure The command encountered some catastrophic failure. The rmail
process stops processing the message and sends to the origi-
nator of the message a non-delivery notification that
includes any stdout and stderr output generated by the com-
mand.
The semantics of the < command field in the mailsurr file allow the
specification of exit codes that constitute success, continue, and
failure for each surrogate command individually. The syntax of the
exit state specification is:
< WS [exitstateid=ec[,ec[,...]];][exitstateid=ec[,ec[,...]];
[...]]] WS surrogatecmdline
WS is whitespace. exitstateid can have the value S, C, or F.
exitstateids can be specified in any order. ec can be:
- any integer 0 <= n <= 255 [Negative exit values are not possible.
See exit(2) and wait(2).]
- a range of integers of the form lowerlimit-upperlimit where the
limits are >= 0 and <= 255, and
- *, which implies anything
For example, a command field of the form:
'< S=1-5,99;C=0,12;F=*; command %R'
Page 3 Reliant UNIX 5.44 Printed 11/98
mailsurr(4) mailsurr(4)
indicates that exit values of 1 through 5, and 99, are to be con-
sidered success, values of 0 (zero) and 12 indicate continue, and that
anything else implies failure. If not explicitly supplied, default
settings are S=0;C=*;.
It may be possible for ambiguous entries to exist if two exit states
have the same value, for example, S=12,23;C=*;F=23,52; or
S=*;C=9;F=*;. To account for this, rmail looks for explicit exit
values (that is, not *) in order of success, continue, failure. Not
finding an explicit match, rmail then scans for * in the same order.
It is possible to eliminate an exit state completely by setting that
state's value to an impossible number. Since exit values must be
between 0 and 255 (inclusive), a value of 256 is a good one to use.
For example, if you had a surrogate command that was to log all mes-
sage traffic, a mailsurr entry of
'(.+)' '(.+)' '<S=256;C=*; /usr/lib/mail/surrcmd/logger
\\1 \\2'
would always indicate continue. Surrogate commands are executed by
rmail directly. If any shell syntax is required (metacharacters,
redirection, etc.), then the surrogate command must be of the form:
sh -c "shell command line..."
Special care must be taken to properly escape any embedded backslashes
and other characters special to the shell.
If there are no matching < commands, or all matching < commands exit
with a continue indication, rmail attempts to deliver the message
itself by assuming that the recipient is local and delivering the mes-
sage to /var/mail/recipient.
> command
The intent of a > command is that it is invoked after a successful
delivery to do any post-delivery processing that may be required.
Matching > commands are executed only if some < command indicates a
successful delivery (see the previous section) or local delivery pro-
cessing is successful. The mailsurr file is rescanned and all matching
> commands, not just those following the successful < command, are
executed in order. The exit status of an > command is ignored.
Page 4 Reliant UNIX 5.44 Printed 11/98
mailsurr(4) mailsurr(4)
Defaults: Line
The default settings may be redefined by creating a separate line in
the mailsurr file of the form
Defaults: [S=...;][C=...;][F=...;]
Defaults: lines are honored and the indicated default values redefined
when the line is encountered during the normal processing of the mail-
surr file. Therefore, to redefine the defaults globally, the Defaults:
line should be the first line in the file. It is possible to have mul-
tiple Defaults: lines in the mailsurr file, where each subsequent line
overrides the previous one.
Surrogate Command Keyword Replacement
Certain special sequences are textually-substituted in surrogate com-
mands before they are invoked:
%n Recipient's full name.
%R Full return path to the originator (useful for sending
replies or delivery failure notifications.)
%c Value of the Content-Type: header line if present.
%C text or binary, depending on an actual scan of the content.
This is independent of the value of any Content-Type header
line encountered (useful when calling ckbinarsys.)
%S Value of the Subject: header line, if present.
%l Value of the Content-Length: header line.
%L Local system name. This will be either CLUSTER from
mailcnfg or the value returned by uname.
%U Local system name, as returned by uname.
%X Value of SMARTERHOST in mailcnfg.
%D Local domain name. This will be either DOMAIN from
mailcnfg, or the value returned by getdomainname.
\\n Corresponding (...) substring in the matched patterns. This
implies that the regexp limitation of 9 substrings is
applied to the sender and recipient REs collectively.
%keywords Other keywords as specified in /etc/mail/mailcnfg. See
mailcnfg(4).
The sequences %L, %U, %D, and %keywords are permitted within the
sender and recipient fields as well as in the command fields.
Page 5 Reliant UNIX 5.44 Printed 11/98
mailsurr(4) mailsurr(4)
An example of the mailsurr entry that replaces the uux built-in of
previous versions of rmail looks like this:
'.+' '([^@!]+)!(.+)' '< /usr/bin/uux - \\1!rmail (\\2)'
Mail Surrogate Examples
Some examples of mail surrogates include the distribution of message-
waiting notifications to LAN-based recipients and lighting message-
waiting lamps, the ability to mail output to printers, and the logging
of all rmail requests between remote systems (messages passing through
the local system). The following is a sample mailsurr file:
# Some common remote mail surrogates follow. To activate any
# or all of them, remove the # (comment indicators) from
# the beginning of the appropriate lines. Remember that they
# will be tried in the order they are encountered in the file,
# so put preferred surrogates first.
# Prevent all shell meta-characters
'.+' '.*[`;&|^<>()].*' 'Deny'
# Map all names of the form local-machine!user -> user
'.+' '%L!(.+)' 'Translate R=\1'
# Map all names of the form uname!user -> user
# Must be turned on when using mail in a cluster environment.
'.+' '%U!(.+)' 'Translate R=\1'
# Map all names of the form user@host -> host!user
'.+' '([^!@]+)@(.+)' 'Translate R=\2!\1'
# Map all names of the form host.uucp!user -> host!user
'.+' '([^!@]+)\.uucp!(.+)' 'Translate R=\1!\2'
# Map all names of the form host.local-domain!user -> host!user
# DOMAIN= within /etc/mail/mailcnfg will override getdomainname.
'.+' '([^!@]+)%D!(.+)' 'Translate R=\1!\2'
# Allow access to 'attmail' from remote system 'sysa'
'sysa!.*' 'attmail!.+' 'Accept'
# Deny access to 'attmail' from all other remotes
'.+!.+' 'attmail!.+' 'Deny'
# Send mail for 'laser' to attached laser printer
# Make certain that failures are reported via return mail.
'.+' 'laser' '< S=0;F=*; lp -dlaser'
# Run all local names through the mail alias processor
#
'.+' '[^!@]+' 'Translate R=|/usr/bin/mailalias %n'
Page 6 Reliant UNIX 5.44 Printed 11/98
mailsurr(4) mailsurr(4)
# For remote mail via nusend
#'.+' '([^!]+)!(.+)' '< /usr/bin/nusend -d \\1 -s -e -!"rmail \\2" -'
# For remote mail via usend
'.+' '([^!]+)!(.+)' '< /usr/bin/usend -s -d\\1 -uNoLogin -!"rmail \\2" - '
# For remote mail via uucp
'.+' '([^!@]+)!.+' '<S=256;C=0;
/usr/lib/mail/surrcmd/ckbinarsys -t %C -s \\1'
'.+' '([^!@]+)!(.+)' '< /usr/bin/uux - \\1!rmail (\\2)'
# For remote mail via smtp
#'.+' '([^!@]+)!(.+)' '< /usr/lib/mail/surrcmd/smtpqer %R %n'
# If none of the above work, then let a router change the address.
#'.+' '.*[!@].*' 'Translate R=| /usr/lib/mail/surrcmd/smail -A %n'
# If none of the above work, then ship remote mail off to a smarter host.
# Make certain that SMARTERHOST= is defined within /etc/mail/mailcnfg.
#'.+' '.*[!@].*' 'Translate R=%X!%n'
# Log successful message deliveries
'(.+)' '(.+)' '>/usr/lib/mail/surrcmd/logger \1 \2'
Note that invoking mail to read mail does not involve the mailsurr
file or any surrogate processing.
Security
Surrogate commands execute with the permissions of rmail (user ID of
the invoker, group ID of mail). This allows surrogate commands to
validate themselves, checking that their effective group ID was mail
at invocation time. This requires that all additions to mailsurr be
scrutinized before insertion to prevent any unauthorized access to
users' mail files. All surrogate commands are executed with the path
/usr/lib/mail/surrcmd:/usr/bin.
Debugging New mailsurr Entries
To debug mailsurr files, use the -T option of the mail command. The -T
option requires an argument that is taken as the pathname of a test
mailsurr file. If null (as in -T ""), the system mailsurr file is
used. Enter
mail -T testfile recipient
and some trivial message (such as testing), followed by a line with
either just a dot (.) or a cntl-D. The result of using the -T option
is displayed on standard output and shows the inputs and resulting
transformations as mailsurr is processed by the mail command for the
indicated recipient.
Mail messages will never be sent or delivered when using the -T
option.
Page 7 Reliant UNIX 5.44 Printed 11/98
mailsurr(4) mailsurr(4)
NOTES
It would be unwise to install new entries into the system mailsurr
file without verifying at least their syntactic correctness through
mail -T ...
FILES
/etc/mail/mailsurr
/usr/lib/mail/surrcmd/*
Surrogate commands
/etc/mail/mailcnfg
Initialization information for mail
SEE ALSO
ed(1), egrep(1), mail(1), sh(1), uux(1), ckbinarsys(1M), exec(2),
exit(2), wait(2), popen(3S), mailcnfg(4), regexp(5).
Page 8 Reliant UNIX 5.44 Printed 11/98