.tr ~
.de NP
.IP "\fI\\$1\fP" 10
..
.de II
.nr P- \\n()P	 \" save the preceeding IP space
.nr )P 0	\" now set it to 0
.NP "\\$1\fP"
.nr )P \\n(P-	 \" restore the preceeding IP space
..
.ds M \fI.maildelivery\fP
.TH MAILDELIVERY 5 "1 October, 1985"
.SH NAME
maildelivery
.SH SYNOPSIS
User delivery specification file
.SH DESCRIPTION
The delivery of mail by the local channel can run through various
courses, including using a user tailorable file.
The delivery follows the following strategy, giving up at any point
it considers the message delivered.
.RS
.IP "1)" 4
If the address indicates a pipe or file default
then that is carried out.
.IP "2)" 4
The file \*M
(or something similar) in the home directory is read if it exists
and the actions in it are followed.
.IP "3)" 4
A system-wide file is consulted next, such as
.I /usr/lib/maildelivery
and the actions are similar to 2.
.IP "4)" 4
If the message still hasn't been delivered, then it is put into
the user's normal mailbox 
.RI ( .mail
or
.IR mailbox )
depending on the system.
.RE
.PP
The format of the \*M file is
.RS
.B field
.I <FS>
.B pattern
.I <FS>
.B action
.I <FS>
.B result
.I <FS>
.B string
.RE
where
.br
.NP field
is name of a field that is to be searched for a pattern.
This is any header field that you might find in a message.
The most commonly used headers are usually
From, to, cc, subject and sender.
As well as the standard headers, there are some psuedo-headers
that are can also be used. These are :-
.RS
.II source
The out of band sender information. This is the address MMDF would
use for reporting delivery problems with the message.
.II addr
the address that was used to mail to you, normally 'yourname' or 
\&'yourname=string' (see below).
.II default
if the message hasn't been delivered yet, this field is matched.
.II *
this case is always true regardless of any other action.
.RE
.NP pattern
is some sequence of characters that may be matched in the
above
.IR field .
Case is not significant.
.IP \fIaction\fP 10
is one of the mail delivery actions supported by the
local channel.  Currently the supported actions are
.B file
or
.BR > ,
which
appends the message to the given file, with delimiters;
.B pipe
or
.BR | ,
which starts up a process with the message
as the standard input;
and
.B destroy
which throws the message away.
There is also
.B qpipe
or
.BR ^ ,
which fakes a pipe command and is quicker than the standard pipe,
but does not do header reformatting.
.br
For piped commands, the exit status of the command is significant.
An exit status of 0 implies that the command succeeded and everything
went well. An exit status of octal 0300-0377 indicates that a permanent
failure occured and the message should be rejected; these error codes
are given in mmdf.h. Any other exit
status indicates a temporary failure and the delivery attempt will
be aborted and restarted at a later time.
.NP result
is one of the letters A, R or ? which stand for
Accept, Reject and "Accept if not delivered yet".
They have the following effects:
.RS
.II A
If the result of this line's action is OK, then the message can be
considered delivered.
.II R
The message is not to be considered delivered by this action.
.II ?
This is equivalent to
.I A
except that the action is not carried
out if the message has already been accepted.
.RE
.PP
The file is always read completely so that several matches
can be made, and several actions taken.
As a security check, the \*M file must be owned by either
the user or root, and must not have group or general
write permission. In addition the system delivery file has the above
restrictions but must also be owned by root.
If the field specified does not need a pattern a dash (\-)
or similar symbol is usually inserted to show that the field is present
but not used.
The field separator character can be either a tab, space or comma (,).
These characters can be included in a string by quoting them with
double quotes (") (double quotes can be included with a backslash '\e').
.PP
MMDF treats local addresses which contain an equals sign ('=')
in a special manner.  Everything in a local address
from an equals sign to the '@' is ignored and passed on to the
local channel.  The local channel will make the entire string available
for matching against the
.I addr
string of the \*M file.
For example, if you were to
subscribe to a digest as "foo=digest@bar.NET",
.B submit
and the local channel will verify
that it is legal to deliver
to "foo", but then the entire string "foo=digest" will be available
for string matching against the \*M file for the
.B addr
field.
.SH ENVIRONMENT
The environment in which piped programs are run
contains a few standard features, specifically:
.ne 5
.sp
.nf
HOME is set to the user's home directory.
USER is set to the user's login name.
SHELL is set to the user's login shell (defaults to /bin/sh).
.sp
.fi
The default umask is set up to 077, this gives a very protective
creation mask.
Initgroups is called if the 4.2 version of UNIX is running.
If further requirements are needed, then a shell script
can be run first to set up more complex environments.
.PP
There are certain built-in variables that you can give to
a piped program.  These are
.IR $(sender) ,
.IR $(address) ,
.IR $(size) ,
.I $(reply-to)
and
.IR $(info) .
.I $(sender)
is set to the return address for the message.
.I $(address)
is set to the address that was used to mail to you, normally `yourname'
or `yourname=string'.
.I $(size)
is set to the size in bytes of this message.
.I $(reply-to)
is set to the Reply-To: field (or the From: field if the former is
missing) and so can be used for automatic replies.
.I $(info)
is the info field from the internal mail header and is probably only
of interest to the system maintainers.
.SH EXAMPLE
.PP
Here is a rough idea of what a \*M file looks like:
.ne 12
.nf
.sp
# lines \fIstarting\fP with a '#' are ignored.
# as are blank lines
# file mail with mmdf2 in the "To:" line into file mmdf2.log
To~~~~mmdf2~~~~file~~~~A~~~~mmdf2.log
# Messages from mmdf pipe to the program err-message-archive
From~~~~mmdf~~~~pipe~~~~A~~~~err-message-archive
# Anything with the "Sender:" address "uk-mmdf-workers"
# file in mmdf2.log if not filed already
Sender~~~~uk-mmdf-workers~~~~file~~~~?~~~~mmdf2.log
# "To:" unix \- put in file unix-news
To~~~~Unix~~~~>~~~~A~~~~unix-news
# if the address is jpo=mmdf \- pipe into mmdf-redist
Addr~~~~jpo=mmdf~~~~|~~~~A~~~~mmdf-redist
# if the address is jpo=ack \- send an acknowledgement copy back
Addr~~~~jpo=ack~~~~|~~~~R~~~~"resend~~\-r~~$(reply-to)"
# anything from steve \- destroy!
from~~~~steve~~~~destroy~~~~A~~~~\-
# anything not matched yet \- put into mailbox
default~~~~\-~~~~>~~~~?~~~~mailbox
# always run rcvalert
*~~~~\-~~~~|~~~~R~~~~rcvalert
.sp
.fi
.SH FILES
$HOME/.maildelivery
\- the file's normal location.
.br
/usr/lib/maildelivery \-
the system file. This should be protected against attack.  It
may contain contents such as:
.ne 4
.sp
.nf
default~~~~\-~~~~pipe~~~~A~~~~stdreceive
*~~~~\-~~~~|~~~~R~~~~ttynotify
.fi
.sp
This allows interfacing to non-standard mail systems,
ones that don't believe in delimiter-separated mailboxes.
.SH "SEE ALSO"
rcvtrip(1)
.SH BUGS
And why not?