PROCMAILRC(5)
NAME
procmailrc - procmail rcfile
SYNOPSIS
$HOME/.procmailrc
DESCRIPTION
For a quick start, see NOTES at the end of the procmail(1)
man page.
The rcfile can contain a mixture of environment variable
assignments (some of which have special meanings to proc-
mail), and recipes. In their most simple appearance, the
recipes are simply one line regular expressions that are
searched for in the header of the arriving mail, the first
recipe that matches is used to determine where the mail
has to go (usually a file). If processing falls off the
end of the rcfile, procmail will deliver the mail to
$DEFAULT.
There are two kinds of recipes: delivering and non-deliv-
ering recipes. If a delivering recipe is found to match,
procmail considers the mail (you guessed it) delivered and
will cease processing the rcfile after having successfully
executed the action line of the recipe. If a non-deliver-
ing recipe is found to match, processing of the rcfile
will continue after the action line of this recipe has
been executed.
Delivering recipes are those that cause header and/or body
of the mail to be written into a file, absorbed by a pro-
gram or forwarded to a mailaddress.
Non-delivering recipes are those that cause the output of
a program or filter to be captured back by procmail or
those that start a nesting block.
You can tell procmail to treat a delivering recipe as if
it were a non-delivering recipe by specifying the `c' flag
on such a recipe. This will make procmail generate a car-
bon copy of the mail by delivering it to this recipe, yet
continue processing the rcfile.
By using any number of recipes you can presort your mail
extremely straightforward into several mailfolders. Bear
in mind though that the mail can arrive concurrently in
these mailfolders (if several procmail programs happen to
run at the same time, not unlikely if a lot of mail
arrives), to make sure this does not result in a mess,
proper use of lockfiles is highly recommended.
The environment variable assignments and recipes can be
freely intermixed in the rcfile. If any environment vari-
able has a special meaning to procmail, it will be used
appropriately the moment it is parsed. (i.e. you can
change the current directory whenever you want by specify-
ing a new MAILDIR, switch lockfiles by specifying a new
LOCKFILE, change the umask at any time, etc., the possi-
bilities are endless :-).
The assignments and substitutions of these environment
variables are handled exactly like in sh(1) (that includes
all possible quotes and escapes), with the added bonus
that blanks around the '=' sign are ignored and that, if
an environment variable appears without a trailing '=', it
will be removed from the environment. Any program in
backquotes started by procmail will have the entire mail
at its stdin.
Comments
A word beginning with # and all the following characters
up to a NEWLINE are ignored. This does not apply to con-
dition lines, which cannot be commented.
Recipes
A line starting with ':' marks the beginning of a recipe.
It has the following format:
:0 [flags] [ : [locallockfile] ]
<zero or more conditions (one per line)>
<exactly one action line>
Conditions start with a leading `*', everything after that
character is passed on to the internal egrep literally,
except for leading and trailing whitespace. These regular
expressions are completely compatible to the normal
egrep(1) extended regular expressions. See also Extended
regular expressions.
Conditions are anded; if there are no conditions the
result will be true be default.
Flags can be any of the following:
H Egrep the header (default).
B Egrep the body.
D Tell the internal egrep to distinguish between upper
and lower case (contrary to the default which is to
ignore case).
A This recipe will depend on the last preceding recipe
(on the current block-nesting level) without the `A'
or `a' flag. This allows you to chain actions that
depend on a common condition.
a Has the same meaning as the `A' flag, but will depend
on the successful completion of the immediately pre-
ceding recipe as well.
E This recipe only executes if the immediately preced-
ing recipe was not executed. Execution of this
recipe also disables any immediately following
recipes with the 'E' flag. This allows you to spec-
ify `else if' actions.
e This recipe only executes if the immediately preced-
ing recipe failed. This allows you to specify
`error' actions.
h Feed the header to the pipe (default).
b Feed the body to the pipe (default).
f Consider the pipe as a filter.
c Generate a carbon copy of this mail. This only makes
sense on delivering recipes. The only non-delivering
recipe this flag has an effect on is on a nesting
block, in order to generate a carbon copy this will
clone the running procmail process (lockfiles will
not be inherited), whereas the clone will proceed as
usual and the parent will jump across the block.
w Wait for the filter or program to finish and check
its exitcode (normally ignored); if the filter is
unsuccessful, then the text will not have been fil-
tered.
W Has the same meaning as the `w' flag, but will sup-
press any `Program failure' message.
i Ignore any write errors on this recipe (i.e. usually
due to an early closed pipe).
r Raw mode, do not try to ensure the mail ends with an
empty line, write it out as is.
There are some special conditions you can use that are not
straight regular expressions. To select them, the condi-
tion must start with:
! Invert the condition.
$ Evaluate the remainder according to sh(1) substitu-
tion rules inside double quotes, skip leading whites-
pace, then reparse it.
? Use the exitcode of the specified program.
<< Check if the total length of the mail is shorter than
the specified (in decimal) number of bytes.
>> Analogous to '<'.
variablename ??
Match the remainder against the value of this envi-
ronment variable (this cannot be a pseudo variable).
Special cases are `B', `H', `HB' and `BH', which
merely override the default header/body search area
defined for this recipe.
\ To quote any of the above at the start of the line.
Local lockfile
If you put a second (trailing) ':' on the first recipe
line, then procmail will use a locallockfile (for this
recipe only). You can optionally specify the locallock-
file to use; if you don't however, procmail will use the
destination filename (or the filename following the first
'>>') and will append $LOCKEXT to it.
Recipe action line
The action line can start with the following characters:
! Forwards to all the specified mail addresses.
| Starts the specified program, possibly in $SHELL if
any of the characters $SHELLMETAS are spotted. You
can optionally prepend this pipe symbol with vari-
able=, which will cause stdout of the program to be
captured in the environment variable. If you spec-
ify just this pipe symbol, without any program,
then procmail will pipe the mail to stdout.
{ Followed by at least one space, tab or newline will
mark the start of a nesting block. Everything up
till the next closing brace will depend on the con-
ditions specified for this recipe. Unlimited nest-
ing is permitted. The closing brace exists merely
to delimit the block, it will not cause procmail to
terminate in any way. If the end of a block is
reached processing will continue as usual after the
block. On a nesting block, the flags `H' and `B'
only affect the conditions leading up to the block,
the flags `h' and `b' have no effect whatsoever.
Anything else will be taken as a mailbox name (either a
filename or a directory, absolute or relative to the cur-
rent directory (see MAILDIR)). If it is a (possibly yet
inexistent) filename, the mail will be appended to it.
If it is a directory, the mail will be delivered to a
newly created, guaranteed to be unique file named $MSGPRE-
FIX* in the specified directory. If the directory name
ends in "/.", then this directory is presumed to be an MH
folder; i.e. procmail will use the next number it finds
available. When procmail is delivering to directories,
you can specify multiple directories to deliver to (using
hardlinks).
Environment variable defaults
LOGNAME, HOME and SHELL
Your (the recipient's) defaults
SHELLMETAS &|<>~;?*[
SHELLFLAGS -c
ORGMAIL /var/spool/mail/$LOGNAME
(Unless -m has been specified, in
which case it is unset)
MAILDIR $HOME/
(Unless the name of the first suc-
cessfully opened rcfile starts with
`./', in which case it defaults to
`.')
DEFAULT $ORGMAIL
MSGPREFIX msg.
SENDMAIL /usr/sbin/sendmail
HOST The current hostname
COMSAT no
(If an rcfile is specified on the
command line)
LOCKEXT .lock
Other cleared or preset environment variables are IFS,
ENV, PWD, PATH=$HOME/bin:/bin:/usr/bin:/sbin:/usr/sbin
:/usr/local/bin:/usr/local/sbin:/usr/bin/X11 and
USER=$LOGNAME.
Environment
Before you get lost in the multitude of environment vari-
ables, keep in mind that all of them have reasonable
defaults.
MAILDIR Current directory while procmail is executing
(that means that all paths are relative to
$MAILDIR).
DEFAULT Default mailbox file (if not told otherwise,
procmail will dump mail in this mailbox).
Procmail will automatically use $DEFAULT$LOCK-
EXT as lockfile prior to writing to this mail-
box. You do not need to set this variable,
since it already points to the standard system
mailbox.
LOGFILE This file will also contain any error or diag-
nostic messages from procmail (normally none
:-) or any other programs started by procmail.
If this file is not specified, any diagnostics
or error messages will be mailed back to the
sender. See also LOGABSTRACT.
VERBOSE You can turn on extended diagnostics by set-
ting this variable to `yes' or `on', to turn
it off again set it to `no' or `off'.
LOGABSTRACT Just before procmail exits it logs an abstract
of the delivered message in $LOGFILE showing
the `From ' and `Subject:' fields of the
header, what folder it finally went to and how
long (in bytes) the message was. By setting
this variable to `no', generation of this
abstract is suppressed. If you set it to
`all', procmail will log an abstract for every
successful delivering recipe it processes.
LOG Anything assigned to this variable will be
appended to $LOGFILE.
ORGMAIL Usually the system mailbox (ORiGinal MAILbox).
If, for some obscure reason (like `filesystem
full') the mail could not be delivered, then
this mailbox will be the last resort. If
procmail fails to save the mail in here (deep,
deep trouble :-), then the mail will bounce
back to the sender.
LOCKFILE Global semaphore file. If this file already
exists, procmail will wait until it has gone
before proceeding, and will create it itself
(cleaning it up when ready, of course). If
more than one lockfile are specified, then the
previous one will be removed before trying to
create the new one. The use of a global lock-
file is discouraged, whenever possible use
locallockfiles (on a per recipe basis)
instead.
LOCKEXT Default extension that is appended to a desti-
nation file to determine what local lockfile
to use (only if turned on, on a per-recipe
basis).
LOCKSLEEP Number of seconds procmail will sleep before
retrying on a lockfile (if it already
existed); if not specified, it defaults to 8
seconds.
LOCKTIMEOUT Number of seconds that have to have passed
since a lockfile was last modified/created
before procmail decides that this must be an
erroneously leftover lockfile that can be
removed by force now. If zero, then no time-
out will be used and procmail will wait for-
ever until the lockfile is removed; if not
specified, it defaults to 1024 seconds. This
variable is useful to prevent indefinite
hangups of sendmail/procmail. Procmail is
immune to clock skew across machines.
TIMEOUT Number of seconds that have to have passed
before procmail decides that some child it
started must be hanging. The offending pro-
gram will receive a TERMINATE signal from
procmail, and processing of the rcfile will
continue. If zero, then no timeout will be
used and procmail will wait forever until the
child has terminated; if not specified, it
defaults to 960 seconds.
MSGPREFIX Filename prefix that is used when delivering
to a directory (not used when delivering to an
MH directory).
HOST If this is not the hostname of the machine,
processing of the current rcfile will immedi-
ately cease. If other rcfiles were specified
on the command line, processing will continue
with the next one. If all rcfiles are
exhausted, the program will terminate, but
will not generate an error (i.e. to the mailer
it will seem that the mail has been deliv-
ered).
UMASK The name says it all (if it doesn't, then for-
get about this one :-). Anything assigned to
UMASK is taken as an octal number. If not
specified, the umask defaults to 077. If the
umask permits o+x, all the mailboxes procmail
delivers to directly will receive an o+x mode
change. This can be used to check if new mail
arrived.
SHELLMETAS If any of the characters in SHELLMETAS appears
in the line specifying a filter or program,
the line will be fed to $SHELL instead of
being executed directly.
SHELLFLAGS Any invocation of $SHELL will be like:
"$SHELL" "$SHELLFLAGS" "$*";
SENDMAIL If you're not using the forwarding facility
don't worry about this one. It specifies the
program being called to forward any mail.
It gets invoked as: "$SENDMAIL" "$@";
NORESRETRY Number of retries that are to be made if any
`process table full', `file table full', `out
of memory' or `out of swap space' error should
occur. If this number is negative, then proc-
mail will retry indefinitely; if not speci-
fied, it defaults to 4 times. The retries
occur with a $SUSPEND second interval. The
idea behind this is, that if e.g. the swap
space has been exhausted or the process table
is full, usually several other programs will
either detect this as well and abort or crash
8-), thereby freeing valuable resources for
procmail.
SUSPEND Number of seconds that procmail will pause if
it has to wait for something that is currently
unavailable (memory, fork, etc.); if not spec-
ified, it will default to 16 seconds. See
also: LOCKSLEEP.
LINEBUF Length of the internal line buffers, cannot be
set smaller than 128. All lines read from the
rcfile should not exceed $LINEBUF characters
before and after expansion. If not specified,
it defaults to 2048. This limit, of course,
does not apply to the mail itself, which can
have arbitrary line lengths, or could be a
binary file for that matter.
DELIVERED If set to `yes' procmail will pretend (to the
mail agent) the mail has been delivered. If
mail cannot be delivered after having met this
assignment (set to `yes'), the mail will be
lost (i.e. it will not bounce).
TRAP When procmail terminates it will execute the
contents of this variable. A copy of the mail
can be read from stdin. Any output produced
by this command will be appended to $LOGFILE.
Possible uses for TRAP are: removal of tempo-
rary files, logging customised abstracts, etc.
See also EXITCODE and LOGABSTRACT.
EXITCODE When procmail terminates and this variable has
been set to a positive numeric value, procmail
will use this as the exitcode. If this vari-
able is set but empty, procmail will set the
exitcode to whatever the TRAP program returns.
If this variable has not been set, procmail
will set it shortly before calling up the TRAP
program.
LASTFOLDER This variable is assigned to by procmail when-
ever it is delivering to a folder or program.
It always contains the name of the last folder
(or program) procmail delivered to.
MATCH This variable is assigned to by procmail when-
ever it is told to extract text from a match-
ing regular expression. It will contain all
text matching the regular expression past the
`\/' token.
SHIFT Assigning a positive value to this variable
has the same effect as the `shift' command in
sh(1). This command is most useful to extract
extra arguments passed to procmail when acting
as a generic mailfilter.
INCLUDERC Names an rcfile (relative to the current
directory) which will be included here as if
it were part of the current rcfile. Unlimited
nesting is permitted.
COMSAT Comsat(8)/biff(1) notification is on by
default, it can be turned off by setting this
variable to `no'. Alternatively the biff-ser-
vice can be customised by setting it to either
`service@', `@hostname', or `service@host-
name'. When not specified it defaults to
biff@localhost.
DROPPRIVS If set to `yes' procmail will drop all privi-
leges it might have had (suid or sgid). This
is only useful if you want to guarantee that
the bottom half of the /etc/procmailrc file is
executed on behalf of the recipient.
Extended regular expressions
The following tokens are known to both the procmail inter-
nal egrep and the standard egrep(1):
^ Start of a line.
$ End of a line.
. Any character except a newline.
a* Any sequence of zero or more a's.
a+ Any sequence of one or more a's.
a? Either zero or one a.
[^-a-d] Any character which is not either a dash, a, b,
c, d or newline.
de|abc Either the sequence `de' or `abc'.
(abc)* Zero or more times the sequence `abc'.
These were only samples, of course, any more complex com-
bination is valid as well.
The following token meanings are special procmail exten-
sions:
^ or $ Match a newline (for multiline matches).
^^ Anchor the expression at the very start of the
search area, or if encountered at the end of the
expression, anchor it at the very end of the
search area.
\<< or \>> Match the character before or after a word.
They are merely a shorthand for `[^a-zA-Z0-9_]',
but can also match newlines. Since they match
actual characters, they are only suitable to
delimit words, not to delimit inter-word space.
\/ Splits the expression in two parts. Everything
matching the right part will be assigned to the
MATCH environment variable.
EXAMPLES
Look in the procmailex(5) man page.
CAVEATS
Continued lines in an action line that specifies a program
always have to end in a backslash, even if the underlying
shell would not need or want the backslash to indicate
continuation. This is due to the two pass parsing process
needed (first procmail, then the shell (or not, depending
on SHELLMETAS)).
Don't put comments on the regular expression condition
lines in a recipe, these lines are fed to the internal
egrep literally (except for continuation backslashes at
the end of a line).
Leading whitespace on continued regular expression condi-
tion lines is usually ignored (so that they can be
indented), but not on continued condition lines that are
evaluated according to the sh(1) substitution rules inside
double quotes.
Watch out for deadlocks when doing unhealthy things like
forwarding mail to your own account. Deadlocks can be
broken by proper use of LOCKTIMEOUT.
Any default values that procmail has for some environment
variables will always override the ones that were already
defined. If you really want to override the defaults, you
either have to put them in the rcfile or on the command
line as arguments.
Environment variables set inside the shell-interpreted-`|'
action part of a recipe will not retain their value after
the recipe has finished since they are set in a subshell
of procmail. To make sure the value of an environment
variable is retained you have to put the assignment to the
variable before the leading `|' of a recipe, so that it
can capture stdout of the program.
If you specify only a `h' or a `b' flag on a delivering
recipe, and the recipe matches, then, unless the `c' flag
is present as well, the body respectively the header of
the mail will be silently lost.
SEE ALSO
procmail(1) procmailsc(5) procmailex(5) sh(1) csh(1)
mail(1) mailx(1) binmail(1) uucp(1) aliases(5)
sendmail(8) egrep(1) grep(1) biff(1) comsat(8)
lockfile(1) formail(1)
BUGS
The only substitutions of environment variables that can
be handled by procmail itself are of the type $name,
${name}, ${name:-text}, ${name:+text}, ${name-text},
${name+text}, $#, $n, $$, $?, $_, $- and $=; whereas $_
will be substituted by the name of the current rcfile, $-
by $LASTFOLDER and $= will contain the score of the last
recipe. When the -a or -m options are used, "$@" will ex-
pand to respectively the specified argument (list); but
only when passed as in the argument list to a program.
Procmail does not support the expansion of `~'.
A line buffer of length $LINEBUF is used when processing
the rcfile, any expansions have to fit within this limit;
if they don't, behaviour is undefined.
If the global lockfile has a relative path, and the cur-
rent directory is not the same as when the global lockfile
was created, then the global lockfile will not be removed
if procmail exits at that point (remedy: use absolute
paths to specify global lockfiles).
A locallockfile on the recipe that marks the start of a
nested block does not work as expected.
When capturing stdout from a recipe into an environment
variable, exactly one trailing newline will be stripped.
MISCELLANEOUS
If the regular expression contains `^TO' it will be sub-
stituted by `(^((Original-)?(Resent-)?(To|Cc|Bcc)|(X-
Envelope|Apparently(-Resent)?)-To):(.*[^a-zA-Z])?)', which
should catch all destination specifications.
If the regular expression contains `^FROM_DAEMON' it will
be substituted by `(^(Precedence:.*(junk|bulk|list)
|(((Resent-)?(From|Sender)|X-Envelope-From):|>>?From
)(.*[^(.%@a-z0-9])?(Post(ma?(st(e?r)?|n)|office)
|(send)?Mail(er)?|daemon|mmdf|root|n?uucp|smtp|response
|LISTSERV|owner|request|bounce|serv(ices?|er)
|Admin(istrator)?)([^).!:a-z0-9].*)?$[^>>]))', which should
catch mails coming from most daemons (how's that for a
regular expression :-).
If the regular expression contains `^FROM_MAILER' it will
be substituted by `(^(((Resent-)?(From|Sender)|X-Envelope-
From):|>>?From )(.*[^(.%@a-z0-9])?(Post(ma(st(er)?|n)
|office)|(send)?Mail(er)?|daemon|mmdf|root|n?uucp|smtp
|response|serv(ices?|er)|Admin(istrator)?)([^).!:a-
z0-9].*)?$[^>>])' (a stripped down version of
`^FROM_DAEMON'), which should catch mails coming from most
mailer-daemons.
When assigning boolean values to variables like VERBOSE,
DELIVERED or COMSAT, procmail accepts as true every string
starting with: a non-zero value, `on', `y', `t' or `e'.
False is every string starting with: a zero value, `off',
`n', `f' or `d'.
If the action line of a recipe specifies a program, a sole
backslash-newline pair in it on an otherwise empty line
will be converted into a newline.
NOTES
Since unquoted leading whitespace is generally ignored in
the rcfile you can indent everything to taste.
The leading `|' on the action line to specify a program or
filter is stripped before checking for $SHELLMETAS.
Files included with the INCLUDERC directive containing on-
ly environment variable assignments can be shared with sh.
For really complicated processing you can even consider
calling procmail recursively.
AUTHOR
Stephen R. van den Berg at RWTH-Aachen, Germany
berg@pool.informatik.rwth-aachen.de