.\" $Header: deliver.8,v 2.7 90/03/06 15:11:55 chip Exp $
.\"
.\" Man page for deliver.
.\"
.\" $Log:	deliver.8,v $
.\" Revision 2.7  90/03/06  15:11:55  chip
.\" New location.
.\" 
.\" Revision 2.6  90/03/06  13:20:21  chip
.\" Document the error delivery file.
.\" 
.\" Revision 2.5  90/02/23  16:35:38  chip
.\" \Fix problems determining legality of user references.
.\" 
.\" Revision 2.4  89/11/10  14:09:46  network
.\" Document cases in which the log files are not written.
.\" 
.\" Revision 2.3  89/11/10  13:34:58  network
.\" Document recursion and logging.
.\" 
.\" Revision 2.2  89/10/04  10:49:10  network
.\" Document the "Undel.mail" and "DROP" features.
.\" 
.\" Revision 2.1  89/06/09  12:25:19  network
.\" Update RCS revisions.
.\" 
.\" Revision 1.8  89/06/09  12:23:42  network
.\" Baseline for 2.0 release.
.\" 
.TH DELIVER 8
.SH NAME
deliver \- deliver local mail
.SH SYNOPSIS
.B deliver
[ options ] address ...
.SH DESCRIPTION
The
.I deliver
program collects a mail message from the standard input and delivers it.
It is intended to take over the delivery of all local mail, a job usually
handled by
.I /bin/mail
(System V),
.I /usr/lib/sendmail
(BSD), or
.I /usr/lib/mail/mail.local
(Xenix).
.PP
.I deliver
introduces flexibility in the handling of local mail delivery.  All files
used to control
.I deliver
are shell scripts.  Thus anything that can be called by a shell
script can be used to control mail delivery.
.SH OPTIONS
.TP
.B \-b
Interpret all arguments as mailbox filenames instead of addresses.  Note
that the user running
.I deliver
must have write permissions on the given mailbox files.  He may also need
write permissions on their parent directories, depending on the existence
of the mailbox file and the local locking protocol.
.TP
.B \-n
Interpret arguments as addresses, but do not run any delivery files; simply
deliver the message to the mailbox(es) of the given user(s).  This option is
most useful when
.I deliver
is executed recursively, since it prevents further recursion.
.TP
.B \-A
Print resolved addresses; do not deliver the message.  Note that
.I deliver
still collects a message from the standard input, since delivery files may
do different things depending on message content.  For simple testing,
redirect standard input from /dev/null.
.TP
.B \-d
Be verbose; don't deliver to any mailboxes or catch any signals.
.TP
.B \-v
Be verbose, but still deliver.
.TP
.B \-t
Do not remove temporary files before exiting.
.TP
.BI \-r " sender"
Put
.I sender
on the generated From_ line.  Default is to use the address on the From_
line in the input, or else the name corresponding to the real uid, or else
"unknown".
.TP
.BI \-h " hostname"
Set the host name.  The default is configuration dependent.
.TP
.BI \-s " system delivery file"
Specify an alternate system delivery file.  The default is
.I /var/deliver/deliver.sys.
For security reasons, this option disables setuid privileges.
.TP
.BI \-p " post-user delivery file"
Specify an alternate post-user delivery file.  The default is
.I /var/deliver/deliver.post.
For security reasons, this option disables setuid privileges.
.TP
.BI \-e " error delivery file"
Specify an alternate error delivery file.  The default is
.I /var/deliver/deliver.err.
For security reasons, this option disables setuid privileges.
.TP
.BI \-u " user delivery file"
Specify an alternate user delivery file.  The default is
.I .deliver
(in each user's home directory).
For security reasons, this option disables setuid privileges.
.PP
All command line options are put into environment variables, examined by
.I deliver
on startup; thus all flags are propagated when
.I deliver
is invoked recursively.
.SH ENVIRONMENT
For mail systems based on
.I smail
2.x, the LMAIL (local mailer) macro can be changed to call
.I deliver.
For mail systems based on
.I smail
3.x or
.I sendmail,
a similar arrangement may be made; or individual users can invoke
.I deliver
by mentioning it in their
.I .forward
files.
.PP
For Xenix systems,
.I deliver
may be used as a direct replacement for
.IR /usr/lib/mail/mail.local.
.PP
For stock Unix systems, it may be possible to make
.I /bin/rmail
a link to
.I deliver;
however, this configuration has not been tested and is not recommended.
Any postmaster motivated enough to install
.I deliver,
and who wants something better than the standard
.I /bin/rmail,
should install
.I smail.
.SH OPERATION
By default,
.I deliver
deposits mail in the system mailbox for the named user(s).  Also, as a
necessity for use with
.I smail
2.x,
.I deliver
also understands UUCP-style bang addresses well enough to forward the
message correctly, using
.I uux.
.PP
However, this basic behavior only scratches the surface: the usefulness of
.I deliver
derives from its flexibility; its behavior can be made to depend on the
recipient(s), content or any other aspect of mail messages.
.PP
When
.I deliver
starts execution, it interprets its arguments in one of three ways.  If the
.B \-b
(mailbox) option was specified, then all arguments are interpreted as
mailbox pathnames.  Otherwise, if a system delivery file exists and the
.B \-n
(no delivery files) option was not specified,
.I deliver
executes the system delivery file with all of deliver's arguments
as its arguments.
.I deliver
interprets the delivery file's output as described below.  This procedure
gives the postmaster control over delivery to non-existent hosts and users.
If the
.B \-n
option is specified or if there is no system delivery file,
.I deliver
interprets all its arguments as mail addresses.
.PP
After possibly executing the system delivery file,
.I deliver
looks in its list of destinations for valid user names without explicitly
named mailboxes.  If any of these users have user delivery files in
their home directories, and if the
.B \-n
option was not specified,
.I deliver
executes each user's delivery file with the name of the given user as its
only argument.
.PP
After executing any user delivery files,
.I deliver
looks in its list of destinations for simple user names and UUCP
addresses.  If any are found, if the post-user delivery file exists,
and if the
.B \-n
option was not specified,
.I deliver
executes the post-user delivery file with these addresses as its arguments.
.PP
After executing the post-user delivery file (if any),
.I deliver
attempts delivery to all requested destinations.
.PP
After delivery to all destinations,
.I deliver
looks in its list of destinations for failures of any kind.  If any
failed destinations are found, and if the
.B \-n
option was not specified,
.I deliver
executes the error delivery file with the complete list of failed
addresses as its arguments.  If the error delivery file generates
any destinations,
.I deliver
attempts delivery to them.  However, if such delivery fails,
.I deliver
will not execute the error delivery file more than once.
.SH "DELIVERY FILES"
Delivery files are shell scripts.  They are executed by
.I deliver
to control delivery to users.  Note that delivery files do
.I not
control delivery to explicitly named mailboxes.  (See the
.B \-b
option.)
.PP
The default shell used to execute delivery files is
configuration-dependant.  Typically it is the Bourne shell (/bin/sh).
However, you can make
.I deliver
execute a given delivery file with a different shell by putting a
Berkeley-style "#!" line at the top of the delivery file.  For
example, if the first line of a delivery file is "#!/bin/perl", then
.I deliver
will execute /bin/perl instead of /bin/sh, but only for that one
delivery file.
.PP
On each system the postmaster may create a
.I system delivery file
to controls delivery of all messages.
The system delivery file, if it exists, is executed
with the name(s) specified on the
.I deliver
command line as its arguments.
.PP
The postmaster may also create a
.I post-user delivery file
which is executed after any user delivery files, but before delivery of the
message to any mailboxes.  This file is particularly useful for implementing
system-wide aliases, since it can deal with addresses generated by user
delivery files, whereas the system delivery file cannot.
.PP
Each user may create a
.I user delivery file
in his home directory.  User delivery files are always executed with exactly
one argument: the name of the user in whose home directory the file is
found.
.PP
Finally, the postmaster may create an
.I error delivery file.
After
.I deliver
has attempted delivery to all requested destinations, and if delivery
to one or more of those destinations failed,
.I deliver
executes the error delivery file with the list of failed adresses as
its arguments.  Note that failed addresses may contain whitespace,
shell metacharacters or other strangeness--be careful!
.PP
Recursive execution of
.I deliver
is useful, especially with the
.B \-b
(mailbox) and
.B \-n
(no delivery files) flags.  For example, a user may wish to transform a
message body before it is stored in a mailbox.  This may be done with a user
delivery file and recursive execution of
.I deliver.
For example, the following user delivery file translates all incoming
message bodies to lower case, and stores them in the user's default mailbox:
.TP
(cat $HEADER; tr '[A-Z]' '[a-z]' <$BODY) | deliver -n "$1"
.PP
When
.I deliver
executes a delivery file, it sets several environment variables, listed
below.
Note that these environment variables are both set and used by
.I deliver;
therefore, all command line options automatically propagate when
.I deliver
is run recursively (within a delivery file).  The environment variable
names set and used by
.I deliver
are:
.TP
.B DELPID
The process id of the running
.I deliver
process.  Used by a child
.I deliver
to determine its parent's process id.
.B DELLEVEL
The
.I deliver
recursion level.  Each time
.I deliver
is called recursively, this value is incremented.  When the maximum
recursion level (default: eight) is exceeded,
.I deliver
assumes infinite recursion and aborts.
.B DELFLAGS
The command line flags, if any, specified on the
.I deliver
command line.
.TP
.B SYSDELFILE
The system delivery filename.
.TP
.B POSTDELFILE
The post-user delivery filename.
.TP
.B ERRDELFILE
The error delivery filename.
.TP
.B USERDELFILE
The user delivery filename, relative to the home directory of each user.
.TP
.B HOSTNAME
The local host name, either the real hostname or a name specified with the
.B \-h
option to
.I deliver.
.TP
.B SENDER
The sender, either an address specified with
.B \-r
option to
.I deliver,
or the address given in the From_ line of the message, or the user who
invoked
.I deliver.
.TP
.B HEADER
The name of the temporary file containing the message header.
.TP
.B BODY
The name of the temporary file containing the message body.
.PP
.I deliver
monitors the standard output of delivery files for lines in four formats:
.TP
.B "host1!host2!user"
Send the message with UUCP via the given bang path.
.TP
.B "user"
Append the message to the given user's default mailbox.  The location
of a user's default mailbox is configuration-dependant.
.TP
.B "user:mailbox"
Append the message to the specified mailbox in the given user's
context.  If the mailbox name is not an absolute pathname, it is
interpreted relative to the given user's home directory.  For security
reasons, only the superuser may request delivery to a specific mailbox
in another user's context.
.TP
.B "user|command"
Execute the specified command in the given user's context, and feed the
message to its standard input.  For security reasons, only the
superuser may request command execution in another user's context.
.TP
.B "user?error message"
Do not attempt delivery to the given user.  Diagnostic messages,
including the bounce notice (if any), will include the specified
message.  For security reasons, only delivery files executing as the
superuser may report an error for another user.
.PP
Note that for the "user:mailbox", "user|command" and "user?error
message" forms, the user name may be omitted (for example: "?Sorry").
If the user name is omitted, the current user context is assumed.
.SH "UNDELIVERED MAIL"
When
.I deliver
executes a delivery file, it expects a complete list of all users (and,
optionally, mailboxes) that should receive the message.  If a delivery file
produces no output,
.I deliver
saves the message in the "undelivered mail" mailbox named "Undel.mail"
in the home directory of the delivery file's owner.  (System,
post-user and error delivery files are "owned" by root.)
.PP
Sometimes a delivery file writer really does want
.I deliver
to drop a message.  For example, if a delivery file stores a message by
running "deliver -b", then there's no need for the parent
.I deliver
to save the message again.  A delivery file can tell
.I deliver
not to save the message by outputting the string "DROP".  A delivery file's
outputting "DROP" the "undelivered mail" safety net for that delivery file.
Think of "DROP" as shorthand for: "Trust me.  I know what I'm doing."
However, if the delivery file outputs any names and/or addresses in addition
to "DROP", then "DROP" has no effect.
.PP
Note, however, that the error delivery file is an exception to the
"DROP" rule.  The error delivery file never receives valid addresses
as arguments, so producing no output is considered completely normal.
.SH "SECURITY"
If
.I deliver
is setuid root -- which it should be for normal operation -- then the system
delivery file is executed as root.  Be
.I "very careful"
about its permissions and its contents!  Carelessness here can easily
create a security problem.
.PP
All user delivery files are executed in the context of the user in whose
home directory they reside.  A user's "context" includes the uid, gid, and
home directory as specified in /etc/passwd.
.PP
For security reasons, if a user's home directory is writable to the world,
.I deliver
will ignore any delivery file that might be found there.
.PP
For security reasons, no user can request writing a mailbox as another
user.  Otherwise, any user could modify other users' private files.
.SH LOGGING
.I Deliver
records its activity in two files: the "delivery log", named
.IR /var/adm/deliver.log,
and the "error log", named
.IR /var/adm/deliver.errlog.
.PP
The deliver log is a record of activity of each
.I deliver
process.
Each delivery log entry include the users or mailboxes named on the command
line, the users and/or mailboxes where delivery succeeded, and those where
it failed.  Note that
.I deliver
will write to the delivery log only if it already exists.
.PP
The error log is a record of any problems encounted during delivery.  Each
error log entry includes all diagnostic output, a copy of the message
header, and other miscellaneous information that might prove helpful.
.PP
If
.I deliver
is performing a "dry run" -- that is, if the
.B \-d
(debug) or
.B \-A
(print address) flag is specified -- it will not write to either log file.
.PP
If you want a delivery log, you must create the delivery log file yourself.
If the delivery log file does not exist,
.I deliver
will not create it.
.PP
If the
.B \-v
(verbose) flag is specified,
.I deliver
will not write to the error log.
.SH LOCKING
Several preprocessor labels may be defined during compilation to control
the method(s) used by
.I deliver
to lock mailboxes.  These labels are:
.RS
.PP
.B ML_DOTLOCK
Lock on exclusive creation of the mailbox name with ".lock"
appended.  (Version 7 and early BSD mailers use this method.)
.PP
.B ML_DOTMLK
Lock on exclusive creation of
.I /tmp/basename.mlk,
where
.I basename
is the last component of the mailbox pathname.  (Xenix mailers use this
method.)
.PP
.B ML_LOCKF
Exclusively lock mailbox with lockf().
.PP
.B ML_FCNTL
Exclusively lock mailbox with fcntl().
.PP
.B ML_LOCKING
Exclusively lock mailbox with locking().
.PP
.RE
One or both of ML_DOTLOCK and ML_DOTMLK may be specified.  At most one of
ML_LOCKF, ML_FCNTL or ML_LOCKING may be specified.
.SH FILES
/var/deliver/deliver.sys      system delivery file
.br
/var/deliver/deliver.post     post-user delivery file
.br
/var/deliver/deliver.err      error delivery file
.br
~user/.deliver                  user delivery file(s)
.br
/var/adm/deliver.log            delivery log
.br
/var/adm/deliver.errlog         error log
.br
/etc/systemid                   system name (Xenix only)
.SH SUPPORT
Enhancements, enhancement requests, trouble reports, etc., should be mailed
to <chip@tct.uucp> or <uunet!ateng!tct!chip>.
.SH "SEE ALSO"
.IR mail (1),
.IR uux (1),
.IR smail (8),
.IR sendmail (8)