Procmail: Instructions

Table of Contents

Obtaining ready-made .procmailrc and recipe files for startup

The instructions in this section explain how to obtain a basic set of ready-made procmail files, suitable for use with minor modifications (e.g., replace the generic "username" with your username, remove a # symbol to activate a recipe, customize a vacation message, etc.). If you would rather create your own files, skip this section and proceed directly to the section Creating a .procmailrc file and a .procmail directory.

The required files are contained in a tarfile (an archive file) called procsetup.tar. The UNIX "tar" command extracts these files to your UNIX account: 

	.procmailrc
	.procmail/	(a subdirectory)

and in the .procmail subdirectory: 

	.procmail/rc.testing
	.procmail/rc.maillists
	.procmail/rc.vacation
	.procmail/vacation.msg  (sample vacation message)

Caution: Any existing files with the names listed above will be overwritten without warning when you extract the tar file. To preserve such files, rename them or move them to a different subdirectory.

To obtain the setup files, log on to your central UNIX account and type the following commands: 

	cd
	tar -xvf /www/htdocs/evelyn/procsetup.tar
See instructions in the remaining sections of the Web document "Procmail: Instructions" to find out how to test your .procmailrc setup, and how to customize and use the mailing list and vacation recipes included in the package.
Procmail Instructions: Table of Contents
Main Procmail page
[Help Center]

Creating a .procmailrc file and a .procmail directory

Use the UNIX editor of your choice to create a file called .procmailrc in your home directory. These instructions assume that you use the Pico editor.

  1. At the UNIX % prompt, type     cd   and press Enter.

    2.  
  2. Create the directory where you will store the procmail log and rc files by typing
    3.    mkdir .procmail
    at the UNIX % prompt.
     
  3. Start the Pico editor by typing     pico .procmailrc   and pressing Enter.

    4.  
  4. Type the following lines into the new .procmailrc file:
    5.      # Comment:  Set VERBOSE=on in next line when debugging.
     VERBOSE=off

     # Replace "mail" with the name of your mail directory.
     # If you use Pine, your mail directory is called mail.
     # This directory must exist before you start using procmail.

     MAILDIR=$HOME/mail

     # Directory for storing procmail log and rc files
     PMDIR=$HOME/.procmail

     LOGFILE=$PMDIR/log

     # Next line for testing.  Add # at beginning when not needed.
     INCLUDERC=$PMDIR/rc.testing

     # To sort mailing list mail to a folder, remove # from next line.
     #INCLUDERC=$PMDIR/rc.maillists

     # To send vacation message, remove # from next INCLUDERC line.
     # In most cases, next line should be last in this file.
     #INCLUDERC=$PMDIR/rc.vacation
    Note:  The two INCLUDERC lines near the end of the sample file above show how and where you would include command files to file mailing list messages and send a vacation message.  In the sample above, the # signs preceding INCLUDERC make these lines comments so they are ignored by procmail. See details on the rc files in the section on Creating and testing special-purpose recipes.  Remove the # symbol from the beginning of each of the two lines once you have created those files, to allow procmail to run them.
     
  5. Save the new .procmailrc file and exit from the Pico editor.
Procmail Instructions: Table of Contents
Main Procmail page
[Help Center]

Creating and testing an rc file

Create a recipe file called rc.testing whose purpose is to file mail with the word "test" (in upper, lower, or mixed case) anywhere in the Subject: line in a folder called IN.testing in your mail directory.  The file rc.testing must be placed in your .procmail directory.

Follow these step-by-step directions:

  1. Type     cd .procmail  at the UNIX % prompt.

    2.  
  2. Type     pico rc.testing    to open the new file in the Pico editor.

    3.  
  3. Enter the following lines in the new file (the first line contains a zero, not the letter "O"):
    4.      # Procmail recipe to send mail whose Subject: line contains
     # "test" anywhere to the mail folder IN.testing
     :0: IN.testing.lock
     * ^Subject:.*test
     IN.testing
  4. Important:  Before proceeding, be sure you have modified your .localenv file in a previous login session, as described in the Web document Procmail.

    5.  
  5. Save rc.testing and exit from the Pico editor.

    6.  
  6. Start your mail program (e.g., Pine) and send yourself two messages, one with and one without the word "test" in the Subject: line.  Note that the check is case-insensitive and not limited by word boundaries:  It will file mail having "test", "Test", or "TeSt", and words such as "testament", "contest", or "untested" in the Subject: line, in the designated mail folder, IN.testing.

    7.  
  7. Check for delivery of your messages. The one with "test" in the Subject: line should be in the folder IN.testing in your mail directory. (In Pine, view folders (L), look for a new folder called IN.testing, and find your message in that folder.) The other message should be in your inbox.
If either message was not delivered correctly, see troubleshooting suggestions under Common Problems and Questions in the main Procmail Web document.

Note: The Usenet Filtering Mail FAQ and other procmail documentation tell you to set up a .forward file in your home directory. On the University of Delaware central UNIX systems, in order for this recipe and others to work as expected, do not use a .forward file on your account.

Procmail Instructions: Table of Contents
Main Procmail page
[Help Center]

Understanding the procmail test recipe

The following table gives a line-by-line, element-by-element explanation of the test recipe:
 
Notation in recipe file 
  
Meaning 
:0: IN.testing.lock 
  Begin recipe line (one per recipe) 
     :0      Begin new recipe
          :           Use lockfile
               IN.testing.lock 
 
 		                Lockfile name  
* ^Subject:.*test 
  Condition line  
     *        Begin condition
          ^Subject:           Match "Subject:" at beginning of line...
                          .*test 

 
 		              ...followed by any sequence of characters  
             that includes "test", except a newline character  
IN.testing 
     IN.testing 
 
 
 		 Action line (one per recipe) 
      Put message in mail directory folder IN.testing 
Notes:
 
  • A lockfile ensures that no two processes can change the same file at the same time. The lockfile name must match the name of the mail folder.


  • To specify conditions, use UNIX regular expressions, extended regular expressions, and extensions  developed especially for use with procmail (e.g., ^TO or ^FROM_MAILER) that check for particular conditions on the "To:" and "From:" lines.  For more information on regular expressions as used in procmail, see man procmailrc.

    •  
  • To specify several conditions that must all be met, use a new line starting with * for each condition. Procmail performs the instruction specified on the action line only when all listed conditions are met.

    •  
  • When checking for words at the beginning of a line, do not leave a blank between the caret (^) and the word you are looking for.

    •  
  • The test recipe finds the string "test" regardless of case (upper, lower, or mixed) anywhere on the Subject line, even if it is part of another word such as contest or untested.  To narrow the filter, change the syntax of the condition line as follows (in both cases, the square brackets contain exactly one space and one tab):
  • To check for words in the "To:" line, use the format
    •     ^TOusername
    where both letters in TO are capitalized and there is no space between TO and the "username" to be matched.  This format applies only to the "To:" header line.
     
  • You may specify a different function on the action line.  To send mail to another address, replace the last line in the procmail recipe above with
    •     ! userid@host.domain
    For example:
        ! username@udel.edu
    Do not specify a lock file when you send mail via the action line - the system locks mail files as needed. The "begin recipe" line should read        :0
    (i.e., a colon followed by zero, with nothing else on the line). To pipe a message or part of a message to a program or script, start the action line with the pipe symbol ( | ) followed by the name of the script or program.

  • Once procmail has delivered a message according to the specification on the action line, it will take no further action on that message unless you tell it to continue, using one of a variety of "flags" on the "begin recipe" line (see man procmailrc for further information on flags).

    •  
  • You may add comments (preceded by #) as separate lines in the rc file, or at the end of action or "begin recipe" lines, but not on lines that specify conditions.


    • Procmail Instructions: Table of Contents
    Main Procmail page
    [Help Center]

    Creating and testing special-purpose recipes

    This section contains some special-purpose recipes you might find useful.  To use any of these recipes or others you create, add an appropriate INCLUDERC line to your .procmailrc file, e.g.: 
           INCLUDERC rc.urgent_mail
    Any time you change your .procmailrc file, you should test to make sure it is still working properly. Remove the # symbol at the beginning of the 
           INCLUDERC rc.testing
    line and send yourself another set of test messages, with and without the word "test" in the Subject line, and with appropriate combinations of specific conditions to check for, as called for in your new recipe(s). You may not be able to test a recipe that processes mailing lists until you receive messages from the lists you are subscribed to.

    Once you are satisfied, comment out the rc.testing line in your .procmailrc file by adding a # symbol at the beginning of that line.
     

  • Recipes that combine conditions

    • AND

    If you would like procmail to take an action only if incoming messages meet all conditions in a set (AND), write each condition on a separate line preceding the action line.  If any of the ANDed conditions could also be met individually by other recipes called by your .procmailrc file, INCLUDE the recipe with the more restrictive conditions (the recipe with multiple conditions) first.

    The following rc file (rc.edstatsoft) sends all EDSTAT-L messages with the word "software" anywhere in the Subject: line to a file called IN.edstat.software. 

         :0: IN.edstat.software.lock 

     # Is this an EDSTAT-L message?
     * ^TOedstat-l    
     
     # Does the Subject include "software"?
     * ^Subject:.*software   

     # If both conditions met, deliver to folder listed next: 
     IN.edstat.software
    If the .procmailrc file INCLUDEs an rc file that redirects EDSTAT-L messages more generally to a different folder, the two rc files must be INCLUDEd in the correct order for the appropriate filtering to take place. The sample .procmailrc file INCLUDEs the rc.maillists recipe which files EDSTAT-L messages in the mail folder IN.edstat (see "Recipe for filing messages from mailing lists" below). In order for the rc.edstatsoft recipe to be processed first, so it can selectively redirect EDSTAT-L messages referring to software to the mail folder IN.edstat.software, the INCLUDERC commands in .procmailrc must be ordered as follows: 
        ... 
    INCLUDERC rc.edstatsoft 
    INCLUDERC rc.maillists 
    ...
    OR

    The following methods illustrate different ways of setting up OR conditions.
     

  • Use the logical OR symbol (vertical bar) on the condition line in the rc file.  For example, to file messages with the word "quiz" or "test" in the Subject: line in the student.work folder, write an rc file with this recipe:
    •     :0: student.work.lock 
    * ^Subject:.*(quiz|test) 
    student.work
    Notice that the same action line applies to either condition.
     
  • Write a different recipe for each condition and put all recipes in the same rc file.  Procmail will carry out the action corresponding to the first set of conditions matched and ignore subsequent recipes containing other conditions.  The action line may be different in each recipe.  The rc.maillists recipe, shown below, uses this method.

    •  
  • Write an rc file for each condition and INCLUDE the files on separate lines in the .procmailrc file.  Procmail will carry out the action corresponding to the first set of conditions matched and ignore the rest of the recipes.  The action line will most likely be different in each rc file.

    •  
  • Recipe for filing messages from mailing lists

    • The following recipe allows you to file mailing-list messages separately from the rest of your mail.  For this example, assume that you are subscribed to EDUCOM's Edupage and to a list on teaching statistics called EDSTAT-L. You would like to file mail from Edupage in a folder called IN.edupage and messages from EDSTAT-L in a folder called IN.edstat, both in your mail directory. Create a new rc file called rc.maillists in your .procmail directory and put both recipes in the same file, as follows: 

          :0: IN.edupage.lock

      # Next line checks the To: line for edupage.
      * ^TOedupage
      IN.edupage

      :0: IN.edstat.lock
          # Next line checks the To: line for edstat-l
      * ^TOedstat-l
      IN.edstat
  • Vacation recipe

    • The vacation recipe rc.vacation, adapted from the procmail man pages (man procmailex), sends an automated response (vacation.msg) to your correspondents while you are away from your mail, delivers your mail as usual, and records the sender's e-mail address in the file vacation.cache in your mail directory.

    The sample .procmailrc file contains an INCLUDERC line for the vacation recipe. To activate the recipe:

    When you return to your mail:

    The vacation recipe and message files

    Create the file rc.vacation in your .procmail directory and insert the code shown below, replacing "username@udel.edu" with your complete e-mail address.  Some comment lines are included for clarity. 

          :0 Whc: vacation.lock
    
      # The three (ANDed) conditions address the following:
      # Reply if mail is addressed to me.
      # Don't reply to daemons or mailing lists (! = not).
      # Avoid mail loops (don't reply to mail I might send myself).

      * $^To:.*\<$\LOGNAME\>
      * !^FROM_DAEMON
      * !^X-Loop: username@udel.edu

      # Store sender's address in vacation.cache if not there already.
      | formail -rD 8192 vacation.cache 

      # If sender's address not in cache (e=previous recipe failed), send
      # mail containing vacation message.  Note:  Trailing backslashes (\)
      # required to denote continuation of single action line.

       :0 ehc
      | (formail -rA"Precedence: junk" \
                  -A"X-Loop: username@udel.edu" ; \
         cat $PMDIR/vacation.msg \
        ) | $SENDMAIL -oi -t
    Use a UNIX text editor such as pico to create the file vacation.msg in the .procmail directory. This file should contain the vacation message you would like your correspondents to receive. The message could contain text like the following, where you replace returndate with the appropriate date: 
    	I will be away from my mail until returndate.  Your message
	will be read when I return.
  • Activating and testing special-purpose recipes

    • The mailing list and vacation recipe files are already INCLUDEd, but inactive, in the sample .procmailrc file.  To activate these recipes, remove the # symbol before the corresponding INCLUDERC lines: 

           INCLUDERC=$PMDIR/rc.maillists
       INCLUDERC=$PMDIR/rc.vacation
    The rc.vacation recipe should send you an auto-reply the first time, and only the first time, you send yourself mail.  By the same token, your correspondents will receive just one vacation message from you in your absence.

      

    Procmail Instructions: Table of Contents
    Main Procmail page
    [Help Center]
    Technology Home Page
    University of Delaware Home Page
    Last modified: Mar. 21, 1998
    This page maintained by Evelyn V. Stevens.
    Copyright © University of Delaware, 1998.