.\" @(#)sortmail.1 2.9 02/03/11; Copyright (c) 1990-2002 - Ed Falk
.\" $Id: sortmail.1,v 1.4 2003/08/02 01:56:29 efalk Exp $
.\"
.\"  to view:  tbl sortmail.1 | nroff -man
.\"
.TH SORTMAIL 1 "21 Apr 1991"
.SH NAME
sortmail \- classify incoming mail
.SH SYNOPSIS
.B sortmail
[
.B \-v
] [
.B \-terse
] [
.B \-home
.I path
] [
.B \-mailbox
.I path
] [
.B \-mailrc
.I initfile
] [
.B \-sortmailrc
.I initfile
] [
.B \-inbox
.I filename
] [
.B \-mbox
] [
.B \-pop|pop3|pop2
.I user:password@host
] [
.B \-pop|pop3|pop2
.I /path
] [
.B -keep
] [
.B -noapop
] [
.I var=value
] [
.B -dumpCrcs
.I dbmname
] [
.B -verify
] [
.B -version
]
.I username
.SH DESCRIPTION
.B Sortmail
reads and classifies email according to patterns you specify.  It can
be used to process incoming mail, filter mailing lists, process mail
folders or download mail from POP servers.

For processing incoming mail,
create this \fB.forward\fP file in your home directory:

	"| /\fIpath\fP/sortmail \fIuser\fP"

Where "/\fIpath\fP/sortmail" is the full path where you installed
sortmail, and \fIuser\fP is your own userid.  The userid must be
specified because when mail arrives, \fBsortmail\fP could be run as
root, daemon, or any number of other uid's.

Once your \fB.forward\fP file is set up,
.B sortmail
will classify incoming mail according to the patterns in $HOME/.sortmailrc.
Your \fB.sortmailrc\fP file is similar to a news KILL file, but somewhat
more powerful.  You can discard mail, have it delivered to your mailbox,
have it filed into a folder, forward it to another address
or even pipe it through a shell command.

Don't let the long list of options and command below frighten you.
New users might do well to skip to the EXAMPLES section below, and/or
read the README and sample files in /usr/share/doc/sortmail.

When \fBsortmail\fP starts up, it first reads the following config files:
/usr/lib/sortmailrc, /usr/local/lib/sortmailrc, /etc/sortmailrc,
/usr/etc/sortmailrc,
/usr/local/etc/sortmailrc, $HOME/.mailrc and $HOME/.sortmailrc.

.SH OPTIONS
.TP 15
.B \-v
Verbose.  A message is printed stderr or a log file of your
choosing for every mail message.  A second
.B \-v
causes a lot more information to be printed.
.TP 15
.B \-terse
Set verbosity to 1, omit timestamps.
.TP 15
\fB\-home\fP \fIpath\fP
Set user's home directory, overriding the default taken from the user's
passwd entry.
.TP 15
\fB\-mailbox\fP \fIpath\fP
Set the user's system mailbox, overriding the default for your system
(\fB/var/mail/\fP\fIuser\fP).
.TP 15
\fB\-mailrc\fP \fIpath\fP
Set the .mailrc file, overriding the default of
\fB~/.mailrc\fP.
.I Path
may be specified as \fB/\fP\fIfullpath\fP, \fB~/\fP\fIpath\fP,
\fB~\fP\fIuser\fP/\fIpath\fP, or \fIpath\fP.
The last form is the same as ~/\fIpath\fP.
.TP 15
\fB\-sortmailrc\fP \fIpath\fP
Set the .sortmailrc file, overriding the default of
\fB~/.sortmailrc\fP.
.I Path
may be specified as with -mailrc, above.
.TP 15
\fB\-inbox\fP \fIfilename\fP
Take input from named file instead of stdin.  Filename may be /\fIabspath\fP
"~/\fIpath\fP", "~user/\fIpath\fP" or "+\fIfoldername\fP".  When POP2
.\"or IMAP
protocol is used, this option can be used to select the inbox instead
of the default mailbox.
.TP 15
\fB\-mbox\fP
Indicates that input is a standard Berkeley mailbox containing multiple
messages, rather than a
single message.  Used to process an entire mailbox at once.
.TP 15
\fB\-pop\fP \fIuser:password@host\fP
Sortmail connects to the specified server, downloads mail and
processes it.  If password is not specified, the user is prompted
interactively.  \fBNote:\fP it is \fBhighly\fP recommended that you
do \fInot\fP specify the password on the command line on a multi-user
system, see below.
.IP
.B Sortmail
attempts to use
.\"imap,
pop3 and pop2 protocols in that order.
For obvious reasons, the user id may not contain ':'.
.IP
Many providers assign usernames that contain '@', e.g. user@foo.com.
In this case, the argument to -pop will look something like
user@foo.com@pop.foo.com.
.IP
For security reasons,
.B sortmail
attempts to hide this information from the "ps" command, but
this does not work under all operating systems (e.g. Solaris).  It is
strongly discouraged to specify the password on the command line for
this reason.
.TP 15
\fB\-pop\fP \fI/path\fP
This variant of the -pop command reads a single line from the specified
file, containing \fIuser:password@host\fP.  This is more secure
than specifying the password on the command line.  File must be specified
as a full pathname, starting with '/'.
.TP 15
\fB\-pop3\fP \fIuser:password@host\fP
.TP 15
\fB\-pop3\fP \fI/path\fP
Sortmail connects to the specified pop3 server, downloads mail and
processes it.
.TP 15
\fB\-pop2\fP \fIuser:password@host\fP
.TP 15
\fB\-pop2\fP \fI/path\fP
Sortmail connects to the specified pop2 server, downloads mail and
processes it.
.\".TP 15
.\"\fB\-imap\fP \fIuser:password@host|file\fP
.\"Sortmail connects to the specified imap server, downloads mail and
.\"processes it.
.TP 15
.B -keep
For POP
.\"or IMAP
use or when -inbox and -mbox are specified.
Indicates that all messages are to be left in the source input box
instead of being deleted.
.TP 15
.B -noapop
For POP3, do not attempt to use APOP authentication.  This option is used
when dealing with broken servers which do not handle APOP correctly.
.TP 15
\fIvariable=value\fP
Set a variable on the command line.  Spaces are not permitted in the
string.
.TP 15
\fB\-dumpCrcs\fP \fIdbmname\fP
Dump the bounce-check database in \fIdbmname\fP.{dir,pag} for
debugging purposes.
.TP 15
.B -verify
Verify only.  Examine the mailrc and sortmailrc files for errors and exit.
.TP 15
.B -version
Print version and exit.  If this option fails, you have version 1.something.

.SH SORTMAILRC FORMAT

Your .sortmailrc file is a series of lines in the form

	\fBset\fP \fIvariable=value\fP
.P
	/\fIregular-expression\fP/\fImodifiers\fP:\fIcommand\fP[:\fIcommand\fP...]
.P
	[\fIip-address\fP]\fImodifiers\fP:\fIcommands..\fP
.P
	[\fIip-address/mask\fP]\fImodifiers\fP:\fIcommands..\fP
.P
	[\fIip-address - ip-address\fP]\fImodifiers\fP:\fIcommands..\fP
.P
	(\fIlogical-expression\fP):\fIcommand\fP[:\fIcommand\fP...]
.P
	\fBincluderc\fP \fIfilename\fP
.P
	\fBlistinclude\fP \fIfilename\fP
.P
	\fBlistexclude\fP \fIfilename\fP
.P
	\fBheader\fP \fIheaderline\fP
.P
	\fBreplace\fP \fIheaderline\fP
.P
	\fBbouncecheck\fP \fIdbmname\fP

where \fIregular-expression\fP is any \fBed(1)\fP-style regular
expression, \fImodifier\fP is any of \fBi, t, f, s, h, a, o\fP, and
\fIcommand\fP is one of \fBm, j, v, f\fP\ \fIfile\fP,
\fBa\fP \fIfile\fP, \fBd\fP \fIfile\fP, \fB+\fP\fIfile\fP,
or \fB|\fP\ \fIcommand\fP.  Multiple commands may be placed on a line,
separated by ':'s.  If you need to place a ':' within a command for any
reason, escape it with '\\'.
.P
Users of rn-style KILLfiles will be familiar with this format.
.P
The [\fIip-address\fP] form specifies a literal IP address to be matched
(e.g. 192.168.3.4) or a partial IP address (e.g. 192.168.3).  This differs
from a regular expression in that the '.' character must match literally,
and the pattern must match at the start (e.g. 129.192.168.3 would not
match the pattern given above.)  (Note that the '[]' characters are literal
here, and do not denote an optional argument.)
.P
IP addresses may also be specified as a range, e.g. "[192.168.0.0/16]"
would match all IP addresses containing 192.168 in the first 16 bits.
Finally, IP addresses may also be specified as e.g.
"[192.168.0.0 - "192.168.255.255]".

.SH SEARCH MODIFIERS
.LP
These modifiers affect how the regular expression is applied to the
incoming mail.  The default is 's'.
.TP 6
.B i
Ignore case.
.TP 6
.B o
Evaluate variables in pattern only once, when sortmailrc file is read.
Without this option, variables are evaluated every time the pattern
is tested.  If the pattern contains no variables, this modifier has no
effect.
.TP 6
.B s
Test the "Subject:\ " line of the mail against the regular expression.
.TP 6
.B t
Test the "To:\ ", "Cc:\ " and "Apparently-To:\ " lines of the
mail against the regular expression.
.TP 6
.B f
Test the "From:\ " line of the mail against the regular expression.
.TP 6
.B r
Test the Received: lines of the incoming mail against the regular expression.
.TP 6
.B h
Test the entire header of the incoming mail against the regular expression.
.TP 6
.B a
Test the entire incoming mail message against the regular expression.
.LP
Any combination of s,t,f,h,a may be used.  If none are specified, 's' is
assumed.

.SH SEARCH COMMANDS
.LP
These commands are executed for any message which matches a search pattern.
.TP 10
.B :m
Send the message to the user's mailbox.
.TP
\fB:m\fP \fIaddress\fP
Forward the mail to the specified address.
.TP 10
.B :j
Delete the message ("junk" it.)
.TP 10
\fB:e\fP \fIn\fP
Set the exit code to \fIn\fP.  When processing is complete, sortmail
will exit with the given exit code instead of zero.
.TP 10
\fB:E\fP \fIn\fP
Exit immediately with exit code \fIn\fp.
.TP 10
.B :k
Keep the message.  When downloading messages from a POP
.\"or IMAP
server,
or when -inbox and -mbox are specified,
messages are normally deleted from the mailbox once transfer is successful.
This option causes the message to be left behind.
.TP 10
\fB:f\fP \fIfolder\fP
Append the message to the given mail folder.  \fIfolder\fP may be in
the formats ~/\fIpath\fP, /\fIabspath\fP, ~\fIuser/path\fP, or
+\fIname\fP.  The latter form expands to ~/\fIfolder/name\fP where
\fIfolder\fP is the value specified for the \fB$folder\fP variable
(default is "\fBfolders\fP".)
.TP 10
\fB:+\fP\fIfolder\fP
Shorthand for "\fBf +\fP\fIfolder\fP".
.TP 10
\fB:d\fP \fIfile\fP
Append the message to the given file in digest form.  \fIfile\fP
may be in the formats ~/\fIpath\fP, /\fIabspath\fP, ~\fIuser/path\fP,
or +\fIname\fP.
.IP
"Digest" form is a stripped form where each message contains only the
"From:", "Subject:" and "Date:" headers, and messages are separated by
a line of dashes.
.TP 10
\fB:a\fP \fIfile\fP
"Archive".  Identical to digest.
.TP 10
\fB:|\fP \fIcommand\fP
Pipe the mail message through the given \fIshell-command\fP.
sh(1) is used.
.TP 10
.B :c
Continue processing.  Normally,
.B sortmail
applies search expressions to mail messages until a match is found.  At
this point, the message is dispatched and
.B sortmail
is finished.  This command causes
.B sortmail
to continue comparing the message to more patterns.  This option may be
considered "continue", "Cc" or "copy" at your whim.  Thus, a message
may be sent to more than one destination.

.SH COMMANDS
.LP
The following is a list of commands which may be contained within
a .mailrc or .sortmailrc file.
.TP 6
\fBset\fP \fIvariable = value\fP
Set an environment variable.
Variables used by sortmail are listed below.  Quotes around the string
are not needed.  Special characters such as '$' or '\\' may be quoted
with '\\'.  Variables may be included within the value string in the form
$\fIname\fP or ${\fIname\fP}.
.IP
Note that the \fBset\fP command is processed immediately when the
initfile is read.
Other commands are processed as mail messages are read.
Thus, all \fBset\fP commands are processed before any other
commands, regardless of their order in the init files.
.TP 6
\fBlistinclude\fP \fIfilename\fP
Used for mailing list administration (see below).  Ignore this command
if you're not using sortmail to administer a mailing list.
.IP
This command specifies a file containing a list of addresses which are
permitted to post to the list.  Each line of the file contains one
regular expression, which represents the email address of a list
member.  Lines in the format

	User Name	<address>

will only use the \fIaddress\fP part of the line.  This allows the
mailing list itself to be used as the include list.
.IP
Multiple include lists may be specified with multiple \fBlistinclude\fP
commands.
If the listinclude command is used, posters to the list must be found in
at least one of the lists.
If no include files are specified, anybody may post.
.IP
Messages which are rejected are handled according to the \fB$reject\fP
variable, which must exist and which contains either a filename or
a search command (see below.)
.IP
For more on include and exclude files, see \fBMAILING LISTS\fP, below.
.TP 6
\fBlistexclude\fP \fIfilename\fP
Specify a list of addresses which are not permitted to post
to the list.  Same format as \fBlistinclude\fP.  In order to post
to the list, a user must be in the \fBlistinclude\fP file(s) (if any)
and \fInot\fP in the \fBlistexclude\fP file(s).
.TP 6
\fBreplace\fP \fIHeader: value\fP
Used for mailing list processing.  Headers lines matching the specified
header are replaced with the new value.  If no match is found, the line
is appended to the message header.  Typically used to change the "From:
" header to specify the list address rather than the originator, and to
set an "Errors-To: " header.

If the \fIvalue\fP field is empty, the specified header line is deleted.
.TP 6
\fBheader\fP \fIHeader: value\fP
Same format as \fBreplace\fP, except that header lines are always appended
to the header, not replaced.  Typically used to add comments.
.TP 6
\fBbouncecheck\fP \fIdbmname\fP
Last resort mechanism for detecting mail loops.  A crc-32 hash of the
text portion of the message is computed and stored in \fIdbmname\fP.{dir,pag}.
If another message with the same hash code is encountered in the next
60 days, the message is rejected and disposed of as described in \fB$reject\fP
.IP
This is not a perfect mechanism, however, as broken mailers may choose
to add some comments to the message before bouncing it back.
.TP 6
\fBincluderc\fP \fIfilename\fP
Process commands from named file.  Include files may be nested.

.SH VARIABLES
Variables are used in the form $\fIname\fP or ${\fIname\fP}.  Variables
may appear anywhere in the init file.
.LP
\fBSortmail\fP uses the following variables, which may be changed in
your \fB.mailrc\fP or \fB.sortmailrc\fP files.  Variables may also
be set on the command line.
.TP 10
.B default
Command(s) used to handle unclassifiable mail.  The default behavior is
to put unclassifiable mail into 
\fImailbox\fP.  Another reasonable value might be "\fB+other\fP".
.TP 10
.B delay
Used to prevent runaway mail loops; especially useful for mailing list
administration.  Specifies a delay in seconds to be imposed before mail
is forwarded to another address or piped through a command.  For example,
a 600-second delay (ten minutes) would limit a mail loop to one message
every ten minutes.
.TP 10
.B folder
The user's mail folders directory.  Mail folders are denoted by a
leading '+' in their name, and are stored in ~\fIuser/$folder\fP/.
Default is "\fBfolders\fP".  Many people choose to set this to "Mail"
instead.
.TP 10
.B from
Used for mailing list administration.
Specifies the value of the "From " line when mail is forwarded to the
list.  Not all versions of sendmail will honor this.  You may need
to make sortmail suid-uucp or add your username to the "trusted users"
entry in /etc/sendmail.cf.
.TP 10
.B HOME
The user's home directory.  Used to find initialization files and the
user's \fIfolders\fP directory.  Default is ~\fIuser\fP.
.TP 10
.B lines
Count of lines of text in the message.  Set by sortmail and updated for
every message.
.TP 10
.B logfile
Debugging messages are sent to the specified log file.  If sortmail is
executed from the command line, the default is stderr.  Otherwise the
default is /tmp/sortmail.log.
.IP
If logfile cannot be opened, stderr is used.  Note
that when sortmail is used from your .forward file to filter incoming
messages, messages sent to stderr will be sent back to the sender as bounces.
.TP 10
.B mailbox
The user's mail box.  Default is \fB/var/mail/\fP\fIuser\fP.
.TP 10
.B mailrc
Full path of the user's \fB.mailrc\fP file.  There's no real point in
changing this.
.TP 10
.B maxlines
Maximum number of message lines which will be searched during pattern
matching.  Restricting this value can make searches quicker and prevent
the /tmp directory from filling.  Default value is 5000.
.TP 10
.B reject
Used for mailing list administration.
Specifies the file or command to which rejected mail is sent.
.TP 10
.B sendmail
The command used to deliver mail.  Default value is
"/usr/lib/sendmail -om -oi".  If '%f' occurs in the string, it will be
expanded to the temporary file name containing the message.  Otherwise,
the message will be delivered to the command's standard input.
.IP
Special values "SMTP" and "SMTP hostname" cause the message to be delivered
directly to an SMTP port.
.TP 10
.B size
Size of message in bytes.  Set by sortmail and updated for every message.
.TP 10
.B sortmailrc
Full path of the user's \fB.sortmailrc\fP file.  There's no real point in
changing this.
.TP 10
.B timeout
Timeout in seconds for POP
.\"and IMAP
connections.
.TP 10
.B user
The user on behalf of whom \fBsortmail\fP is running.  This value must
be specified on the command line when sortmail is executed from
a .forward file, but may be changed later.  It is used
to determine the user's home directory, among other things.
.TP 10
.B vacation
If set, mail to \fIuser\fP will also be piped through vacation(1).
.TP
.B TMPDIR
Directory used for temporary files.  Default is "/tmp".

.LP
In addition,
.B sortmail
defines the following environment variables before passing a message
to another program.
.TP 10
.B FROM
The sender of the message
.TP 10
.B SUBJECT
The subject line from the incoming message

.SH EXAMPLES
.LP
Here is a sample \fB.sortmailrc\fP file:
.LP
.RS
.nf
set default=+other
/MAILER-DAEMON/f:+bounces
/falk/t:m
/bldg8/t:m
/joe/f:m:c
/for brenda/s:k
/scubaclub/t:+scuba
/scuba/s:+scuba
/marko/f:j
/testing/t:m falk@lab
/jym@apple/f:| /home/falk/bin/fixjim
/^Precedence: junk/h:+other
(/bill/f && /dive/s):+scuba
[211.114.0.0/16]r:j
.fi
.RE
.LP
In this example, the folder directory and other variables have whatever
values were specified in \fB.mailrc\fP.  Unclassifiable mail will be sent to
the folder "+other".  Mail from "MAILER-DAEMON" is sent to the folder
"+bounces".  Mail to "falk" or "bldg8" is sent
directly to my mailbox.
.LP
Mail from my friend joe is sent directly to my mailbox, and processing
continues in order to see if there's somewhere else it should go as well.
.LP
Mail labeled "for brenda" is left at the POP server untouched.  (This
only works if the email is being downloaded from a POP server; it would
be lost otherwise.)
.LP
Mail to the scuba club or with "scuba" in the
subject line is sent to the "+scuba" folder.  Mail from marko is
thrown away unread.  Mail to the "testing" alias
is forwarded to my account on another machine.
.LP
Mail from my friend jym, who
formats his mail in a funny way is passed through a shell script which
cleans up his messages and appends them to my mailbox.  Mail messages
with "^Precedence:\ junk" anywhere in the header are filed in +other.
.LP
The next-to-last line shows a feature new to sortmail version 2:  logical
expressions.  In this case, mail from bill with the subject "dive"
is added to the scuba folder.  Logical expressions are described in
detail below.
.LP
Finally, the last line shows another feature new to sortmail
version 2:  IP ranges.  In this case, all email with an IP
address in the "211.114.0.0/16" range in a "Received:" line will
be junked unread.

Note that the patterns are applied in the order given; it is important,
for example, that the "MAILER-DAEMON" pattern precede the "falk" pattern
so that mail from MAILER-DAEMON is filed in +bounces even if directed
to me personally.  Similarly, mail from marko will not be junked
if addressed to me personally.

.SH LOGICAL EXPRESSIONS
Logical expressions allow you to specify more complicated rules for
processing mail.  For example, you could specify that all mail from
a certain domain with a size greater than a certain amount be deleted
unread unless a specific keyword were to be found in the header.
.LP
Logical expressions consist of the following operators, grouped in order
of precedence:
.TS
center box;
c|l.
\fIn\fP	integer constant
$\fIvar\fP	variable.
/\fIpattern\fP/	regular expression.  Evaluates as 0 or 1.
=
!	logical not
=
*	multiply
/	divide
=
+	add
-	subtract
=
<	less than
<=	less than or equal
>	greater than
>=	greater than or equal
=
==	equal
!=	not equal
=
&	logical AND
&&	logical AND
=
|	logical OR
||	logical OR
=
,	comma
.TE
.LP
Order of precedence in expression evaluation may be modified by use of
parenthesis.
.LP
\':' commands may follow any close-parenthesis or regular expression.  See
examples below.
.LP
The second form of logical AND and OR operations ("&&" and "||") are
optimized in this way:  If the left half of an AND is false, or the left
half of an OR is true, then the right hand is not evaluated.  Thus, you
should place a simple expression (such as a subject match) to the left
and a complex expression (such as a message body search) to the right.
If the simple expression evalutes to false or true respectively, the
complex expression is not tested.
.LP
The first form of logical AND and OR operations ("&" and "|") always
test both sides of the expression.
.LP
The comma operator deserves a bit of explanation for those not familiar with
the C language.  The comma operator evalutes the expressions on both sides
and returns the expression on the right -- ignoring the one on the left.
Thus, the expression "3 , 4" evaluates as 4.  The comma operator is
useful only when the expression on the left has some sort of side
effect when evaluated -- i.e. it contains ':' commands.

.LP
Here are some sample expressions:
.IP
(/joe/f):m
.LP
mail from joe comes directly to me.  This is the same as /joe/f:m
.IP
(/joe/f && /dive/s):+scuba
.LP
mail from joe with "dive" in the subject line goes to the scuba folder.
.IP
(/joe/f && !/dive/s):m
.br
/joe/f:+scuba
.LP
mail from joe \fIwithout\fP "dive" in the subject line goes directly to
me.  Else, mail from joe goes to the scuba folder.
.IP
(/joe/f && $lines > 1000):j
.LP
Looks like joe posted another long boring vacation report to the scuba list.
Junk it.
.IP
.nf
(/earthlink/r && $size > 32768 &&
	!(/key west/ia || /caymans/ia) ):j
.fi
.LP
Junk it if it came from or passed through earthlink (as shown by the
Received: lines), \fIand\fP the size is greater than 32k \fIand\fP it
does not contain the phrase "key west" or "caymans" anywhere in the
message body.  Case is ignored in the body search.  Note that we
examine the message body last to avoid downloading the message
unnecessarily.
.LP
Note also that logical expressions may be continued across multiple lines
as needed.
.IP
(1):+maillog:c
.LP
An extremely simple expression.  (1) is always true, so all mail that
reaches this expression is filed to the folder "maillog".  The ":c"
command causes processing to continue.
.LP
This expression is a very good one to have at the top of your .sortmailrc
when testing a new configuration.  All incoming mail is copied to a backup
log before more complex expressions are tested.
.IP
(/joe/f:+joemail && /scuba/:+scuba)
.LP
This example shows the use of ':' commands within an expression.
Mail from joe goes to the "joemail" folder.  If it
also contains the subject "scuba", it goes to the scuba folder as well.
.IP
(/joe/f:+joemail , /scuba/:+scuba)
.LP
This example shows the use of the ',' operator.  Mail from joe goes
to the joemail folder.  Whether or not this matches, the mail is tested
again to see if it belongs in the scuba folder.  If so, then processing
is finished.
.IP
.nf
(/sex/:+sex && /drugs/:+drugs && /rock-n-roll/:+rock):+bacchanalia
.fi
.LP
This pattern does not do what it looks like it was intended to do.
That is, at first glance it looks as if the pattern is intended to
place all messages containing "sex" in the subject into the sex folder,
all "drugs" messages into the drugs folder, all "rock-n-roll" messages
into the rock folder \fIand\fP place messages into the bacchanalia
folder if they match on all three keys.  However, logical expressions
are only evaluated as far as necessary.  If the "sex" pattern is not
matched, the next two will not be tested at all.  A "rock-n-roll" message
would be missed by this pattern.
.LP
In this case, the '&' operator should be used instead of '&&'.

.SH MAILING LISTS
Skip this section unless you're using sortmail to administer a mailing
list.
.P
In a homogeneous environment, it is usually not necessary to use sortmail
or any other mail filter.  You would simply create the alias in /etc/aliases
and let sendmail(8) handle everything.
.LP
However, in a heterogeneous environment, there can be problems.  The
internet document Rfc822 specifies the handling of internet mail, but
there are many mailers out there which do not honor Rfc822 and cause
trouble.  Not surprisingly, many of the major service providers are
among the worst troublemakers.
.LP
What typically happens is that for some reason, some member of your
mailing list suddenly cannot receive mail.  The service provider at the
user's end bounces an error message back to the list itself rather than
to the original sender or the administrator.  The error message is then
resent to the list subscribers -- including the the one who cannot
receive mail, causing another bounce.  This creates a loop, sending and
resending bounce messages to everybody on the loop every few minutes.
Murphy's Law states that this will happen while you are on vacation.
.LP
Here is how to administer a mailing list:
.LP
First, (as root) edit /etc/aliases and add the following lines:

	scubaclub: "| /usr/yourname/sortmail -sortmailrc scubaclubrc yourname"
.br
	scubaclub-real: :include:/usr/yourname/scubalist
.br
	scubaclub-request: yourname
.br
	owner-scubaclub: yourname
.LP
The first entry indicates that mail to the scuba club goes through
sortmail, using a specific sortmailrc file.  The second entry is the
actual scuba club alias to which sortmail will forward the mail.  The
third entry is a standard list address which will be used by users to
contact you directly; this should always exist for any mailing list.
The final entry is used by the sendmail system to send internal errors
back to you.
.LP
(Most unix systems require you to run newaliases(8) after editing
/etc/aliases.)
.LP
Second, create /usr/yourname/scubalist, containing the names and addresses
of everybody in the list.
.DT
.br
	yourname	<youraddress>
.br
	Joe Shmoe	<joe@foo.com>
.br
	Jane Doe	<jane@bar.com>
.br
	(etc.)
.LP
Third, create a sortmailrc file which will be used to filter incoming mail.
.LP
.RS
.nf
# general variables

set alias = scubaclub
set owner = yourname
set site = yourhost.com
set digestDir = ~/Maillists/Scubaclub

# mail that makes it through the filter gets mailed to
# the list and archived.
set default = m $alias-real@$site:a $digestDir/archive

# mail that gets rejected is mailed to me
set reject = m $owner

# catch anything that looks like a bounce or a loop

/Mailer-Daemon/f:m $owner
/MAILER-DAEMON/f:m $owner
/Postmaster/f:m $owner
/scubaclub/f:m $owner
/X-List-Name: scubaclub/h:m $owner
bouncecheck $digestDir/bounceDb

# (For some reason, we can't set Errors-To to $owner@$site,
# because if we do, sendmail will expand $owner into an
# invalid value before connecting to SMTP.  It would probably
# be ok if I didn't have a personal .forward file.  By adding
# a '\\' to the address, we avoid the problem.)

replace Reply-To: $alias@$site
replace Errors-To: \\\\$owner@$site
header Comment: send add/delete requests to $alias-request@$site
header X-List-Name: $alias
.fi
.RE
.LP
In this example, the variables $alias, $owner, $site and $digestDir
are not used internally by sortmail, but are created for convenience
and generality.
.LP
The search patterns are used to detect possible mail loops, and as
such, always send mail to the owner.  Mail that makes it without
matching any of the patterns is sent to the list.
.LP
As a last resort, the mail is processed by the bouncecheck command
which maintains a database of previously-seen messages and will reject
any message that seems to be a repeat.
.LP
If mail passes through all the patterns unmatched, it is
probably a valid message.  In this case, the message is processed
by the commands in \fB$other\fP, which mail the message to the
actual alias, and append a digest version of the message to
~/Maillists/Scubaclub/archive.
.LP
Finally, the headers of outgoing mail are modified.  The "Reply-To:"
header is added so that replies to mail from the
list are sent to the list at large, and not just to the sender of the
original message.  The "Errors-To:" header is added so that bounces
will be sent to the administrator instead of to the list in general.
(Not all mail transfer agents honor the "Errors-To:" header.)
.LP
The "X-List-Name:" header line serves two purposes.  First, it lets
recipients know what they're receiving.  Secondly, it
is a trick used to help detect bounces.
It is added so that it may be searched for in incoming mail.  If an
incoming message contains this header, it is likely that this is a
bounce, and is sent to the administrator for inspection.

.LP
If some of your list members wish to receive messages in "digest" form,
you can split the list into two sections, one normal and one for the
members who want digests.  Add the following line to /etc/aliases:

	scubaclub-digest: :include:/usr/yourname/scubadigest

and change $default in /usr/yourname/scubaclubrc:

.nf
 set default = m $alias-real@foo:a $digestDir/archive:d $digestDir/digest
.fi

Now, incoming messages will be copied to ~/Maillists/Scubaclub/digest
as well as to ~/Maillists/Scubaclub/archive.  On a nightly basis, execute
a program that will test to see if ~/Maillists/Scubaclub/digest is
non-empty, and if so, mail it to scubaclub-digest@yourhost and empty it.
.LP
.RS
.nf
#! /bin/sh
#
# collect the digest file, prepend some header info and transmit

digest=/usr/yourname/Maillists/Scubaclub/digest
alias=scubaclub
host=yourhost.com

if [ ! -s $digest ] ; then
  exit 0
fi

cat $digest | \
awk "
BEGIN {
  print \\"Return-Path: $alias@$host\\"
  print \\"Date: `date`\\"
  print \\"From: $alias@$host\\"
  print \\"To: $alias@$host\\"
  print \\"Subject: $alias digest\\"
  print \\"X-List-Name: $alias\\"
  print \\"\\"
  print \\"\\"
}
{print}" | \\
/usr/lib/sendmail -om -oi -f$alias@$host $alias-digest

rm $digest
touch $digest
chmod a+w $digest
.fi
.RE

.SH NOTES
Remember that sortmail can be executed under any userid (e.g. root,
daemon or the sender of the mail) depending on who sent the mail, and
whether or not it came from the local machine.  Because of this, you
cannot depend on any user environment to be available, especially
environment variables and path.  All filenames and program names should
be specified as full paths, except that "~", "~user" and "+folder"
forms are understood.  The permissions of sortmail and every directory
along its path should be such that any user can execute it.

If you pipe incoming mail through a program, that program should not
generate any output to stdout or stderr whatsoever.  If it does, that
output will be sent back to the originator of the mail as if the mail
had bounced.

Always test your setup thoroughly, especially when administering mail
lists.  Mistakes usually result in bounce messages being sent to
the originator of mail.  This can be catastrophic with a mail list.
When testing a mail list, start with a test list containing only your
name and a known bad address to test bounce handling.  Use of a logfile
and \fB-v\fP is recommended for the first few days after installing.

The bounce detection mechanism tries to be robust, but as the saying goes,
you can never make a system that's foolproof because some fools are
ingenious.  No matter how thorough the detection mechanism is, there is
a broken mailer out there somewhere that can defeat it.

Never leave a mailing list unattended; that's when bounce loops always seem
to start.  If you go on vacation, either temporarily shut the list down,
or designate someone who can turn it off in an emergency.

.SH EXIT STATUS
The following exit values are returned:
.TP 5
.B 0
Normal exit, mail delivered successfully.
.TP
.B 1
Normal exit, but no messages waiting (-mbox and -pop options)
.TP
.B 2
User error in command line options.
.TP
.B 3
Error in .mailrc or .sortmailrc file.
.TP
.B 4
Out of memory
.TP
.B 5
Cannot determine user name
.TP
.B 6
Cannot determine user directory
.TP
.B 7
Cannot open a temporary file.  In this case,
.B sortmail
attempts to recover by writing the incoming mail to the user's inbox.
.TP
.B 8
Cannot open bounce-check database (-dumpCrcs command)
.TP
.B 9
Cannot open input file (-inbox option).

.SH BUGS
If multiple instances of sortmail are executing and printing status
messages to the same logfile, the output may become jumbled.
.P
The \fBmaxlines\fP variable is not yet implemented.

.SH SEE ALSO
Mail(1), procmail(1), fetchmail(1).
.SH COPYRIGHT
Copyright 1990, 1999 by Edward A. Falk (falk@efalk.org)

Permission is hereby granted, free of charge, to any
person obtaining a copy of this software and
associated documentation files (the "Software"), to
deal in the Software without restriction, including
without limitation the rights to use, copy, modify,
merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom
the Software is furnished to do so, subject to the
following conditions:
.P
The above copyright notice and this permission notice
shall be included in all copies or substantial
portions of the Software.
.P
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
.P
regex.[ch] is covered by the GNU copyleft.