mailsurr(4) FILE FORMATS 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 whi-
tespace on field continuation lines is ignored. Fields must
be less than 1024 characters long after expansion (see
below).
The sender and recipient fields are regular expressions. If
the sender and recipient fields match those of the message
currently being processed, 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) com-
pile and advance procedures 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 lower case
before compilation, and all sender and recipient information
is converted to lower case before comparison. This conver-
sion is done only for the purposes of RE pattern matching;
the information contained within the message's header is not
modified.
The sub-expression pattern matching capabilities of regexp
may be used in the command field, that is, (...), where 1 <
1
mailsurr(4) FILE FORMATS mailsurr(4)
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 accessible, 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, unconditionally 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 reci-
pient 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 result-
ing recipient 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 executed by rmail. If any sh(1) syntax is required
(metacharacters, redirection, etc.), then the surrogate com-
mand 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 command 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 different
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 new-
line), the original string is not modified. For example,
the command line
'.+' '(.+)' 'Translate R=|/usr/bin/findpath \\1'
allows local routing decisions to be made.
If the recipient address string is modified, mailsurr is
rescanned from the beginning with the new address(es), and
any prior determination of Accept (see above) is discarded.
2
mailsurr(4) FILE FORMATS mailsurr(4)
< command
The intent of a < command is that it is invoked as part of
the transport 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 mes-
sage. What actually 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 considered 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 originator of
the message a non-delivery notification that
includes any stdout and stderr output gen-
erated by the command.
The semantics of the < command field in the mailsurr file
allow the specification of exit codes that constitute suc-
cess, continue, and failure for each surrogate command indi-
vidually. The syntax of the exit state specification is:
< WS [exit_state_id=ec[,ec[,...]];][exit_state_id=ec[,ec[,...]];
[...]]] WS surrogate_cmd_line
WS is whitespace. exit_state_id can have the value S, C, or
F. exit_state_ids 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 lower_limit-upper_limit
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'
indicates that exit values of 1 through 5, and 99, are to be
considered success, values of 0 (zero) and 12 indicate con-
tinue, and that anything else implies failure. If not
explicitly supplied, default settings are S=0;C=*;.
3
mailsurr(4) FILE FORMATS mailsurr(4)
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 expli-
cit match, rmail then scans for ``*'' in the same order.
It is possible to eliminate an exit state completely by set-
ting 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 message 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
back-slashes and other characters special to the shell as
stated in the ``Translate'' section above.
If there are no matching < commands, or all matching < com-
mands exit with a continue indication, rmail attempts to
deliver the message itself by assuming that the recipient is
local and delivering the message to /var/mail/recipient.
> command
The intent of a > command is that it is invoked after a suc-
cessful 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 processing 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.
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 mailsurr file. Therefore, to redefine the
defaults globally, the Defaults: line should be the first
line in the file. It is possible to have multiple Defaults:
lines in the mailsurr file, where each subsequent line over-
rides the previous one.
4
mailsurr(4) FILE FORMATS mailsurr(4)
Surrogate Command Keyword Replacement.
Certain special sequences are textually-substituted in sur-
rogate commands before they are invoked:
%n the recipient's full name.
%R the full return path to the originator (use-
ful for sending replies, delivery failure
notifications, etc.)
%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 the value of the Subject: header line, if
present.
%l value of the Content-Length: header line.
%L the local system name. This will be either
CLUSTER from mailcnfg or the value returned
by uname.
%U the local system name, as returned by uname.
%X the value of SMARTERHOST in mailcnfg.
%D the local domain name. This will be either
DOMAIN from mailcnfg, or the value returned
by getdomainame.
\\n as described above, the corresponding (...)
substring in the matched patterns. This
implies that the regexp limitation of 9 sub-
strings is applied to the sender and reci-
pient 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.
An example of the mailsurr entry that replaces the uux
``built-in'' of previous versions of rmail is:
'.+' '([^@!]+)!(.+)' '< /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,
5
mailsurr(4) FILE FORMATS mailsurr(4)
# 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 getdomainame(3).
'.+' '([^!@]+)%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'
# 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.
6
mailsurr(4) FILE FORMATS mailsurr(4)
#'.+' '.*[!@].*' '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 com-
mand. 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 test_file recipient
and some trivial message (like ``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 reci-
pient.
Mail messages will never be sent or delivered when using the
-T option.
FILES
/etc/mail/mailsurr
/usr/lib/mail/surrcmd/* surrogate commands
/etc/mail/mailcnfg initialization information for
mail
SEE ALSO
ckbinarsys(1M), mailcnfg(4)
mail(1), sh(1), uux(1), ed(1), egrep(1), in the User's
Reference Manual
exec(2), exit(2), wait(2), popen(3), regexp(5), getdomain-
name(3) in the Programmer's Reference Manual
7
mailsurr(4) FILE FORMATS mailsurr(4)
NOTES
It would be unwise to install new entries into the system
mailsurr file without verifying at least their syntactical
correctness via `mail -T ...' as described above.
8