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-
       delivering  recipes.   If  a delivering recipe is found to
       match, procmail considers the mail (you guessed it) deliv-
       ered  and  will  cease  processing the rcfile after having
       successfully executed the action line of the recipe.  If a
       non-delivering 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-
       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).





            (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:




       $    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,

       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               /usr/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/lib/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:/usr/local/bin
       :/usr/X11/bin and USER=$LOGNAME.




       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$LOCKEXT  as lockfile prior to writing
                   to this mailbox.  You do not need to set  this
                   variable, since it already points to the stan-
                   dard 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.





                   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).







                   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.


                   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.





                   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-
                   service can be customised  by  setting  it  to
                   either   `service@',   `@hostname',  or  `ser-
                   vice@hostname'.    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:







       ^^        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
       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)
       |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