From: SMTP%"ram@acri.fr" 18-FEB-1995 10:53:01.05 To: USRC CC: Subj: v47i063: mailagent - Flexible mail filtering and processing package, v3.0, Patch32 Resent-Date: 16 Feb 1995 14:14:52 -0600 Path: decwrl!gossip.pyramid.com!olivea!hookup!newshost.marcam.com!news.mathworks.com!udel!gatech!howland.reston.ans.net!vixen.cso.uiuc.edu!news.ksu.ksu.edu!news.mid.net!news.nde.state.ne.us!nlcnews.nlc.state.ne.us!sparky!not-for-mail From: ram@acri.fr (Raphael Manfredi) Newsgroups: comp.sources.misc Subject: v47i063: mailagent - Flexible mail filtering and processing package, v3.0, Patch32 Followup-To: comp.sources.d Date: 16 Feb 1995 14:14:52 -0600 Organization: Advanced Computer Research Institute, Lyon, France Lines: 1048 Sender: kent@sparky.sterling.com Approved: kent@sparky.sterling.com Message-Id: <3i0bns$hpb@sparky.sterling.com> Nntp-Posting-Host: sparky.sterling.com X-Md4-Signature: cb1ced1a4469b657801830f09c8ef941 To: unix-sources@pa.dec.com Resent-Message-Id: <"VlwL72.0.r67.ecLHl"@ftp-gw-1.pa.dec.com> Resent-From: unix-sources@pa.dec.com X-Mailing-List: archive/latest/486 X-Loop: unix-sources@pa.dec.com Precedence: list Resent-Sender: unix-sources-request@pa.dec.com Submitted-by: ram@acri.fr (Raphael Manfredi) Posting-number: Volume 47, Issue 63 Archive-name: mailagent/patch32 Environment: UNIX, Perl Patch-To: mailagent: Volume 41, Issue 1-26 [The latest patch for mailagent version 3.0 is #34.] System: mailagent version 3.0 Patch #: 32 Priority: LOW Subject: added new file setup.cf for initial configuration setup Subject: now uses new header_append and header_prepend routines Subject: new routine stdout_log for -I switch usage Subject: forgot to add interfaces for BEEP and PROTECT Subject: new routines header_prepend and header_append Subject: can now fake a missing From: line in header Subject: was not properly propagating rule-file variable definitions Subject: one more test for SAVE to check new fromfake feature Subject: added checks for new fromfake config variable Subject: regenerated with metaconfig 3.0 PL51 Subject: three new files Date: Thu Feb 16 15:57:15 MET 1995 From: Raphael Manfredi Description: Added new file setup.cf for initial configuration setup, via the -I switch. That new option greatly simplifies the initial configuration setup. If you run 'mailagent -I' with an existing ~/.mailagent, it will be "merged" with the current set of configuration variables (that is, new variables that were added after you initially configured mailagent, in subsequent patches). Your configuration is also checked for, to avoid nasty surprises at run-time... Forgot to add interfaces for BEEP and PROTECT, hence making it impossible to invoke those commands from a perl escape. Can now fake a missing From: line in header, unless prevented to do so by the new 'fromfake' config variable. That way, messages can be saved in MH folders even if the (local) sendmail did not bother adding a From: header, relying on the leading From envelope to identify the sender... Was not properly propagating rule-file variable definitions. Variables defined in rule files are dynamically scoped, as stated by the new paragraph in the manual page. New regression tests: . added test for the new -I switch . one more test for SAVE to check new fromfake feature . added checks for new fromfake config variable Regenerated Configure and config_h.SH with metaconfig 3.0 PL51. Three new files. Repeat-By: Fix: From rn, say "| patch -p -N -d DIR", where DIR is your mailagent source directory. Outside of rn, say "cd DIR; patch -p -N If you send a mail message of the following form it will greatly speed processing: Subject: Command @SH mailpatch PATH mailagent 3.0 LIST ^ note the c where PATH is a return path FROM ME TO YOU either in Internet notation, or in bang notation from some well-known host, and LIST is the number of one or more patches you need, separated by spaces, commas, and/or hyphens. Saying 35- says everything from 35 to the end. To get some more detailed instructions, send me the following mail: Subject: Command @SH mailhelp PATH Index: patchlevel.h Prereq: 31 4c4 < #define PATCHLEVEL 31 --- > #define PATCHLEVEL 32 Index: agent/man/mailagent.SH Prereq: 3.0.1.10 *** agent/man/mailagent.SH.old Thu Feb 16 15:43:38 1995 --- agent/man/mailagent.SH Thu Feb 16 15:43:39 1995 *************** *** 20,26 **** .TH MAILAGENT $manext "Version $VERSION PL$PATCHLEVEL" ''' @(#) Manual page for mailagent's filter -- (c) ram February 1991 ''' ! ''' $Id: mailagent.SH,v 3.0.1.10 1995/01/25 15:17:42 ram Exp $ ''' ''' Copyright (c) 1990-1993, Raphael Manfredi ''' --- 20,26 ---- .TH MAILAGENT $manext "Version $VERSION PL$PATCHLEVEL" ''' @(#) Manual page for mailagent's filter -- (c) ram February 1991 ''' ! ''' $Id: mailagent.SH,v 3.0.1.11 1995/02/16 14:28:45 ram Exp $ ''' ''' Copyright (c) 1990-1993, Raphael Manfredi ''' *************** *** 31,36 **** --- 31,40 ---- ''' of the source tree for mailagent 3.0. ''' ''' $Log: mailagent.SH,v $ + ''' Revision 3.0.1.11 1995/02/16 14:28:45 ram + ''' patch32: documents new -I switch and new fromfake config variable + ''' patch32: random cleanup, mainly suppressing spurious "the" articles + ''' ''' Revision 3.0.1.10 1995/01/25 15:17:42 ram ''' patch27: new option letter 't' for mailagent -s ''' patch27: new commands BEEP and PROTECT *************** *** 96,102 **** .SH NAME mailagent \- an automatic mail-processing tool .SH SYNOPSIS ! \fBmailagent\fR [ \fB\-dhilqtFV\fR ] [ \fB\-s{umaryt}\fR ] [ \fB\-f\fI file\fR ] [ \fB\-e\fI rule\fR ] [ \fB\-c\fI config\fR ] [ \fB\-L\fI loglevel\fR ] [ \fB\-r\fI rulefile\fR ] [ \fB\-o\fI override\fR ] [ \fImailfile\fR ] .SH DESCRIPTION --- 100,107 ---- .SH NAME mailagent \- an automatic mail-processing tool .SH SYNOPSIS ! \fBmailagent\fR [ \fB\-dhilqtFIV\fR ] [ \fB\-s{umaryt}\fR ] ! [ \fB\-f\fI file\fR ] [ \fB\-e\fI rule\fR ] [ \fB\-c\fI config\fR ] [ \fB\-L\fI loglevel\fR ] [ \fB\-r\fI rulefile\fR ] [ \fB\-o\fI override\fR ] [ \fImailfile\fR ] .SH DESCRIPTION *************** *** 206,220 **** script which needs to be edited. You'll have to delete shell comments in the \fIfilter\fR script by yourself if your shell cannot deal with them. ''' ! .SS "Configuring The Mailagent" .PP ! You have to copy the \fImailagent.cf\fR file held in the mailagent sub-directory \fI$privlibexp\fR (hereafter named Lib) as a \fI.mailagent\fR in your home directory. Edit it to configure the whole processing. In particular, you have to choose a spool directory (hereafter named Spool) and a log directory (hereafter named Log). .PP ! Following is a description of each of those fields, followed by a suggested value, when applicable. Fields marked as optional may not be present in the configuration file. Some fields have a close relationship with others, and that is given too. --- 211,245 ---- script which needs to be edited. You'll have to delete shell comments in the \fIfilter\fR script by yourself if your shell cannot deal with them. ''' ! .SS "Configuring Mailagent" ! .PP ! If \fImailagent\fR is in your path, you may automatically configure a default ! installation by running: ! .Ex ! mailagent -I ! .Ef ! which will create a \fI~/.mailagent\fR file from an existing template, ! customize some important variables for your site, and make some basic ! sanity checks. Everything the command does is output on the screen for ! checking purposes, and any problem found is reported. .PP ! Otherwise, you have to copy the \fImailagent.cf\fR file held in the mailagent sub-directory \fI$privlibexp\fR (hereafter named Lib) as a \fI.mailagent\fR in your home directory. Edit it to configure the whole processing. In particular, you have to choose a spool directory (hereafter named Spool) and a log directory (hereafter named Log). .PP ! Note that using the automatic installation procedure above does not ! prevent you from going through the file and modifying it as you wish. ! In fact, you are greatly encouraged to do this, especially for the ! home directory setting, the logging level and the \fIpath\fR or \fIp_host\fR ! variables. Once you are done, ! rerun the \fImailagent -I\fR command to make sure everything is fine. ! Still, you will have to plug in mailagent by creating a \fI~/.forward\fR ! file, as explained in a few sections. ! .PP ! Following is a description of each of the fields you will find in ! the \fI~/.mailagent\fR file, followed by a suggested value, when applicable. Fields marked as optional may not be present in the configuration file. Some fields have a close relationship with others, and that is given too. *************** *** 229,235 **** Remote sending authorizations (not implemented yet). .TP .I autoclean ! Set to ON (case insensitively), the mailagent will perform automatic cleaning of the database entries under \fIhash\fR by removing all the items older than \fIagemax\fR. This is an optional field, omitting it defaults to OFF. (suggested: OFF, unless you use ONCE, UNIQUE or RECORD commands, or activate --- 254,260 ---- Remote sending authorizations (not implemented yet). .TP .I autoclean ! Set to ON (case insensitively), mailagent will perform automatic cleaning of the database entries under \fIhash\fR by removing all the items older than \fIagemax\fR. This is an optional field, omitting it defaults to OFF. (suggested: OFF, unless you use ONCE, UNIQUE or RECORD commands, or activate *************** *** 321,326 **** --- 346,356 ---- lines in mail messages. If you use MH or if your mail reader does not use those lines to separate messages, then you may set it to OFF. (suggested: ON) .TP + .I fromfake + Whether or not \fImailagent\fR should fake a From: line into the message + header when it is absent. Naturally, it requires a valid leading From line to + operate! (optional, defaults to ON, suggested: ON). + .TP .I hash The directory used for name hashing by the built-in database used by ONCE, UNIQUE and RECORD commands. Optional, unless you make use of those commands *************** *** 424,430 **** to be used. Optional, defaults to \fI.msg_prefix\fR. .TP .I name ! First name of the user, used by the mailagent when referring to you. This sets the value of the %U macro. .TP .I newcmd --- 454,460 ---- to be used. Optional, defaults to \fI.msg_prefix\fR. .TP .I name ! First name of the user, used by mailagent when referring to you. This sets the value of the %U macro. .TP .I newcmd *************** *** 438,444 **** .TP .I nfslock Set it to ON to ensure NFS-secure locks. The difference is that the hostname ! is used in conjunction with the PID to obtain a lock. However, the mailagent has to fork/exec to obtain that information. This is an optional parameter which is set to OFF by default. (suggested: OFF if you deliver mail from only one machine, even though it's via NFS). --- 468,474 ---- .TP .I nfslock Set it to ON to ensure NFS-secure locks. The difference is that the hostname ! is used in conjunction with the PID to obtain a lock. However, mailagent has to fork/exec to obtain that information. This is an optional parameter which is set to OFF by default. (suggested: OFF if you deliver mail from only one machine, even though it's via NFS). *************** *** 593,599 **** (optional, defaults to: 077). .TP .I user ! Login name of the user who runs the mailagent. This sets the value of the %u macro. .TP .I vacation --- 623,629 ---- (optional, defaults to: 077). .TP .I user ! Login name of the user who runs mailagent. This sets the value of the %u macro. .TP .I vacation *************** *** 609,615 **** ''' .SS "Available Logging Levels" .PP ! The following log levels can be used while running the mailagent: .Ex 0 No logging 1 Major problems only --- 639,645 ---- ''' .SS "Available Logging Levels" .PP ! The following log levels can be used while running mailagent: .Ex 0 No logging 1 Major problems only *************** *** 626,634 **** 20 Lot more verbose .Ef ''' ! .SS "Setting The Mail Agent" .PP ! Once you have configured the mailagent in a \fI~/.mailagent\fR (where \fI~\fR stands for your home directory), you must tell \fIsendmail\fR how to invoke it. This is done by setting a \fI~/.forward\fR file which looks like this (leading and trailing double quotes are a mandatory part of it): --- 656,664 ---- 20 Lot more verbose .Ef ''' ! .SS "Plugging Mailagent" .PP ! Once you have configured mailagent in a \fI~/.mailagent\fR (where \fI~\fR stands for your home directory), you must tell \fIsendmail\fR how to invoke it. This is done by setting a \fI~/.forward\fR file which looks like this (leading and trailing double quotes are a mandatory part of it): *************** *** 677,683 **** an empty file (or a non-existing file for that matter). You are ready to proceed... .PP ! Send yourself a mail and give the mailagent time to process your mail. The subject of the message should be 'test' (in fact, anything but 'Command'). You may want to run a "\fItail -f logfile\fR" to see what's happening. At the end of the processing, the logfile should contain something like the following --- 707,713 ---- an empty file (or a non-existing file for that matter). You are ready to proceed... .PP ! Send yourself a mail and give mailagent time to process your mail. The subject of the message should be 'test' (in fact, anything but 'Command'). You may want to run a "\fItail -f logfile\fR" to see what's happening. At the end of the processing, the logfile should contain something like the following *************** *** 768,774 **** .SH OPTIONS There is a limited set of options which may be used when calling the mailagent directly. Only one special option at a time may be specified. ! Invoking the mailagent as \fImailqueue\fR is equivalent to using the \fB\-l\fR option. .TP 15 .B \-c\fI file\fR --- 798,804 ---- .SH OPTIONS There is a limited set of options which may be used when calling the mailagent directly. Only one special option at a time may be specified. ! Invoking mailagent as \fImailqueue\fR is equivalent to using the \fB\-l\fR option. .TP 15 .B \-c\fI file\fR *************** *** 808,816 **** Print out a usage message on the standard error and exit. .TP .B \-i ! Interactive mode, directs the mailagent to print a copy of all the log messages on \fIstderr\fR. .TP .B \-l List the mailagent queue. Recently queued mails which are waited for by the \fIfilter\fR are \fIskipped\fR for about half an hour, to avoid race conditions. --- 838,855 ---- Print out a usage message on the standard error and exit. .TP .B \-i ! Interactive mode, directs mailagent to print a copy of all the log messages on \fIstderr\fR. .TP + .B \-I + Install a \fI~/.mailagent\fR file from template, or merge new configuration + variables into an existing file; then perform sanity checks and create + mandatory files or directories. This option may be viewed as an help + into setting up \fImailagent\fR's environment. In any case, the + created/merged \fI~/.mailagent\fR file should be manually verified before + letting \fImailagent\fR deal with your mail by hooking it + into \fI~/.forward\fR. + .TP .B \-l List the mailagent queue. Recently queued mails which are waited for by the \fIfilter\fR are \fIskipped\fR for about half an hour, to avoid race conditions. *************** *** 831,837 **** may be as many \fB\-o\fR options on the command line as necessary. .TP .B \-q ! Force processing of the mailagent's queue. Only the mails not tagged as \fIskipped\fR by the \fB\-l\fR option will be processed. .TP .B \-r\fI file\fR --- 870,876 ---- may be as many \fB\-o\fR options on the command line as necessary. .TP .B \-q ! Force processing of mailagent's queue. Only the mails not tagged as \fIskipped\fR by the \fB\-l\fR option will be processed. .TP .B \-r\fI file\fR *************** *** 855,861 **** same for the last twelve versions of those same rules. .TP .B \-t ! Put the mailagent in a special tracking mode where all the rule matches and executed actions are printed on the standard output. This is mostly useful for debugging a rule file. See also the \fItrack\fR parameter in the configuration file. --- 894,900 ---- same for the last twelve versions of those same rules. .TP .B \-t ! Put mailagent in a special tracking mode where all the rule matches and executed actions are printed on the standard output. This is mostly useful for debugging a rule file. See also the \fItrack\fR parameter in the configuration file. *************** *** 863,869 **** .B \-V Print version number and exit. .PP ! If you invoke the mailagent without options and without any arguments, the program waits for a mail on its standard input. If an argument is provided, it is the name of a file holding one mail to be processed. This is the normal calling procedure from the filter, the argument being the location of the --- 902,908 ---- .B \-V Print version number and exit. .PP ! If you invoke mailagent without options and without any arguments, the program waits for a mail on its standard input. If an argument is provided, it is the name of a file holding one mail to be processed. This is the normal calling procedure from the filter, the argument being the location of the *************** *** 872,878 **** ''' D e f a u l t R u l e s ''' .SH "USING THE DEFAULT RULES" ! If you do not want to use the filtering feature of the mailagent, then the default built-in rules will be used. Those are really simple: all the mails are left in your mailbox and mails with a line "Subject: Command" anywhere in the message will be processed. Commands are looked for on lines starting with --- 911,917 ---- ''' D e f a u l t R u l e s ''' .SH "USING THE DEFAULT RULES" ! If you do not want to use the filtering feature of mailagent, then the default built-in rules will be used. Those are really simple: all the mails are left in your mailbox and mails with a line "Subject: Command" anywhere in the message will be processed. Commands are looked for on lines starting with *************** *** 890,902 **** ''' .SS "Configuring Help" .PP ! The help text the mailagent will send to people must be copied from \fILib/mailagent/agenthelp\fR into your own spool directory, as specified in your \fI~/.mailagent\fR. Two macros may be used: .TP 10 .I =DEST= This will be expanded to the sender's address (the one who sent you ! the mail currently processed by the mailagent). .TP .I =MAXSIZE= This stands for the maximum size set before \fIkit\fR is used to send --- 929,941 ---- ''' .SS "Configuring Help" .PP ! The help text mailagent will send to people must be copied from \fILib/mailagent/agenthelp\fR into your own spool directory, as specified in your \fI~/.mailagent\fR. Two macros may be used: .TP 10 .I =DEST= This will be expanded to the sender's address (the one who sent you ! the mail currently processed by mailagent). .TP .I =MAXSIZE= This stands for the maximum size set before \fIkit\fR is used to send *************** *** 1347,1353 **** case however, the name of the variable must be preceded by a single #. This differentiates the back-reference \fI1\fR from the variable \fI#1\fR, although \fI1\fR is a funny name for a variable. The need for # also prevents the ! common mistake of writing %#, as the mailagent will loudly complain if the first parameter of SUBST or TR is not a digit between 1 and 99 or does not start with a #. .PP --- 1386,1392 ---- case however, the name of the variable must be preceded by a single #. This differentiates the back-reference \fI1\fR from the variable \fI#1\fR, although \fI1\fR is a funny name for a variable. The need for # also prevents the ! common mistake of writing %#, as mailagent will loudly complain if the first parameter of SUBST or TR is not a digit between 1 and 99 or does not start with a #. .PP *************** *** 1362,1368 **** If the variable name begins with a colon ':', then the variable is made persistent. That is to say it will keep its value across different mailagent invocations. The variable is simply stored (with the leading ':' removed) in ! the mailagent's database and is thus subject to the aging policy set up in the ~/.mailagent. .PP Within PERL commands or mail hooks using perl (see the MAIL HOOKS section), --- 1401,1407 ---- If the variable name begins with a colon ':', then the variable is made persistent. That is to say it will keep its value across different mailagent invocations. The variable is simply stored (with the leading ':' removed) in ! mailagent's database and is thus subject to the aging policy set up in the ~/.mailagent. .PP Within PERL commands or mail hooks using perl (see the MAIL HOOKS section), *************** *** 1730,1736 **** QUEUE Queue mail again. A successful queuing counts as if mail had been saved. Mail queued that way will not be processed during the next 30 minutes. Note ! that unless the mailagent is invoked on a regular basis by \fIcron\fR, the mail will remain in the queue until another mail arrives. (Fails when mail cannot be queued) .TP --- 1769,1775 ---- QUEUE Queue mail again. A successful queuing counts as if mail had been saved. Mail queued that way will not be processed during the next 30 minutes. Note ! that unless mailagent is invoked on a regular basis by \fIcron\fR, the mail will remain in the queue until another mail arrives. (Fails when mail cannot be queued) .TP *************** *** 1949,1959 **** By using the PERL command, you have the ability to perform filtering and other sophisticated actions directly in \fIperl\fR. This is really different from what you could do by feeding your mail to a perl script. First of all, no ! extra process is created: the script is loaded directly in the mailagent and compiled in a special package called \fImailhook\fR. Secondly, you have a perl interface to all the filtering commands: each filtering action is associated to a perl function (spelled lower-cased). Finally, some pre-defined ! variables are set for you by the mailagent. .PP Before we go any further, please note that as there is no extra process created, you \fBmust not\fR call the perl \fIexit\fR function. Use \fI&exit\fR instead, --- 1988,1998 ---- By using the PERL command, you have the ability to perform filtering and other sophisticated actions directly in \fIperl\fR. This is really different from what you could do by feeding your mail to a perl script. First of all, no ! extra process is created: the script is loaded directly into mailagent and compiled in a special package called \fImailhook\fR. Secondly, you have a perl interface to all the filtering commands: each filtering action is associated to a perl function (spelled lower-cased). Finally, some pre-defined ! variables are set for you by mailagent. .PP Before we go any further, please note that as there is no extra process created, you \fBmust not\fR call the perl \fIexit\fR function. Use \fI&exit\fR instead, *************** *** 2014,2020 **** control structures like \fBif\fR and \fBfor\fR, raw regular expressions, etc... .PP The special \fIperl\fR @INC array (which controls the search path for ! \fIrequire\fR) is slightly modified by prepending the mailagent's own private library path. This leaves the door open for future mailagent library perl scripts which may be required by the perl script. Furthermore, the following special variables are set-up by perl before invoking your --- 2053,2059 ---- control structures like \fBif\fR and \fBfor\fR, raw regular expressions, etc... .PP The special \fIperl\fR @INC array (which controls the search path for ! \fIrequire\fR) is slightly modified by prepending mailagent's own private library path. This leaves the door open for future mailagent library perl scripts which may be required by the perl script. Furthermore, the following special variables are set-up by perl before invoking your *************** *** 2068,2074 **** .TP .I \$sender The sender of the message (may have a comment), derived in the same way the ! Sender: line is computed by the mailagent. .TP .I \$subject The subject of the message. --- 2107,2113 ---- .TP .I \$sender The sender of the message (may have a comment), derived in the same way the ! Sender: line is computed by mailagent. .TP .I \$subject The subject of the message. *************** *** 2109,2115 **** ''' .SS "Program Environment" .PP ! All the programs started by the mailagent via RUN and friends inherit the following environment variables: HOME, USER and NAME, respectively set from the configuration parameters \fIhome\fR, \fIuser\fR and \fIname\fR. If the mailagent is invoked by the \fIfilter\fR, then the PATH is also set according --- 2148,2154 ---- ''' .SS "Program Environment" .PP ! All the programs started by mailagent via RUN and friends inherit the following environment variables: HOME, USER and NAME, respectively set from the configuration parameters \fIhome\fR, \fIuser\fR and \fIname\fR. If the mailagent is invoked by the \fIfilter\fR, then the PATH is also set according *************** *** 2149,2155 **** in \fIu@a.b.c\fR), converted to lower-case. .TP %C ! CPU name on which the mailagent runs. That is a fully qualified hostname with the domain name, e.g. \fIlyon.eiffel.com\fR. .TP %D --- 2188,2194 ---- in \fIu@a.b.c\fR), converted to lower-case. .TP %C ! CPU name on which mailagent runs. That is a fully qualified hostname with the domain name, e.g. \fIlyon.eiffel.com\fR. .TP %D *************** *** 2424,2430 **** .Ef This relies on the macro substitution mechanism to send only once a day the message held in \fI~/.message\fR. Do not use the tag \fIvacation\fR, unless ! you know what you are doing: this is the tag used internally by the mailagent in vacation mode. Recall that no selector nor pattern is understood as "Subject: *", hence the rule is always executed because that pattern always matches. --- 2463,2469 ---- .Ef This relies on the macro substitution mechanism to send only once a day the message held in \fI~/.message\fR. Do not use the tag \fIvacation\fR, unless ! you know what you are doing: this is the tag used internally by mailagent in vacation mode. Recall that no selector nor pattern is understood as "Subject: *", hence the rule is always executed because that pattern always matches. *************** *** 2615,2621 **** .Ef .SH "VACATION MODE" .PP ! When it's time to take some vacation, it is possible to set up the mailagent in vacation mode. Every \fIvacperiod\fR, the message \fIvacfile\fR will be sent back to the user (with macros substitutions) if the user is explicitly listed in the \fITo\fR or \fICc\fR field and if the sender is not a special --- 2654,2660 ---- .Ef .SH "VACATION MODE" .PP ! When it's time to take some vacation, it is possible to set up mailagent in vacation mode. Every \fIvacperiod\fR, the message \fIvacfile\fR will be sent back to the user (with macros substitutions) if the user is explicitly listed in the \fITo\fR or \fICc\fR field and if the sender is not a special *************** *** 2630,2636 **** behavior can of course be overloaded by suitable rules (by testing and issuing the vacation message yourself via MESSAGE). .PP ! Internally, the mailagent uses a ONCE command tagged \fI(%r, vacation, \$vacperiod)\fR. This implies you must not use the \fIvacation\fR tag in your own ONCE commands, unless you know what you are doing. --- 2669,2675 ---- behavior can of course be overloaded by suitable rules (by testing and issuing the vacation message yourself via MESSAGE). .PP ! Internally, mailagent uses a ONCE command tagged \fI(%r, vacation, \$vacperiod)\fR. This implies you must not use the \fIvacation\fR tag in your own ONCE commands, unless you know what you are doing. *************** *** 2664,2669 **** --- 2703,2715 ---- .I maildir is the location of your mail folders. Any relative path is understood as starting from \fImaildir\fR. If it is not set, \fI~/Mail\fR is used. + .PP + Those variables remain active while in the scope of the rule file. + Should an alternate rule file be used (via rules hook or the APPLY command), + the current values are propagated to the new rule set unless overridden in + the alternate rule file. In any case, the previous value is restored when + control is transferred back to the previous set of rules. That is, those + variables are dynamically instead of statically scoped. .SH "AUTOMATIC ACKNOWLEDGMENTS" Anywhere in the mail, there can be an @RR left-justified line which will send back an acknowledgment to the sender of the mail. The @RR may optionally *************** *** 2697,2703 **** both original \fIreceived:\fR and \fIReturn-path:\fR fields, internally known through their normalized representation. .SH "MAIL HOOKS" ! The mail hooks allow the mailagent to transparently invoke some scripts or perform further processing on the message. Those hooks are activated via the SAVE, STORE or LEAVE commands. Namely, saving in a folder whose executable bit is set will raise a special processing. By default, the folder is taken --- 2743,2749 ---- both original \fIreceived:\fR and \fIReturn-path:\fR fields, internally known through their normalized representation. .SH "MAIL HOOKS" ! The mail hooks allow mailagent to transparently invoke some scripts or perform further processing on the message. Those hooks are activated via the SAVE, STORE or LEAVE commands. Namely, saving in a folder whose executable bit is set will raise a special processing. By default, the folder is taken *************** *** 2749,2755 **** .I perl This hook is the same as \fIaudit\fR but it is executed without forking a new mailagent, and ! you have the perl interface to the mailagent's filtering commands. There is no difference with the PERL command, because it is implemented that way, by calling a mailagent and forcing the PERL command to be executed. This is similar in spirit to Larry Wall's famous \fIperl\fR language and it is --- 2795,2801 ---- .I perl This hook is the same as \fIaudit\fR but it is executed without forking a new mailagent, and ! you have the perl interface to mailagent's filtering commands. There is no difference with the PERL command, because it is implemented that way, by calling a mailagent and forcing the PERL command to be executed. This is similar in spirit to Larry Wall's famous \fIperl\fR language and it is *************** *** 2761,2767 **** concerned). .PP For those hooks which are finally ran by perl, the special @INC array has ! the mailagent's own private library path prepended to it, so that \fIrequire\fR first looks in this place. ''' ''' F o l d e r s --- 2807,2813 ---- concerned). .PP For those hooks which are finally ran by perl, the special @INC array has ! mailagent's own private library path prepended to it, so that \fIrequire\fR first looks in this place. ''' ''' F o l d e r s *************** *** 2823,2840 **** the folder path). If you want to compress all your folders, then simply put a single '*' inside this file. .PP ! When attempting delivery, the mailagent will check the folder name against the list of patterns in the compress file. If there is a match, the folder is ! flagged as compressed. Then the mailagent attempts decompression if there is already a compressed form (a .Z file) and if no uncompressed form is present. Delivery is then made to the uncompressed folder. However, re-compression is not done immediately, since it is still possible to get messages to that folder in a single batch delivery. Should disk space become so tight that decompression ! of other folders is impossible, the mailagent will re-compress the folders it has already uncompressed. Otherwise, it waits until the last moment. .PP If for some reason there is a .Z compressed folder which cannot be decompressed, ! the mailagent will deliver the mail to the plain folder. Further delivery to that folder will be faced with both a compressed and a plain version of the folder, and that will get you a warning in the log file, but delivery will be made automatically to the plain file. --- 2869,2886 ---- the folder path). If you want to compress all your folders, then simply put a single '*' inside this file. .PP ! When attempting delivery, mailagent will check the folder name against the list of patterns in the compress file. If there is a match, the folder is ! flagged as compressed. Then mailagent attempts decompression if there is already a compressed form (a .Z file) and if no uncompressed form is present. Delivery is then made to the uncompressed folder. However, re-compression is not done immediately, since it is still possible to get messages to that folder in a single batch delivery. Should disk space become so tight that decompression ! of other folders is impossible, mailagent will re-compress the folders it has already uncompressed. Otherwise, it waits until the last moment. .PP If for some reason there is a .Z compressed folder which cannot be decompressed, ! mailagent will deliver the mail to the plain folder. Further delivery to that folder will be faced with both a compressed and a plain version of the folder, and that will get you a warning in the log file, but delivery will be made automatically to the plain file. *************** *** 2970,2976 **** Write a perl subroutine to implement the FOLD action and put that into an external file. Say we write the subroutine \fIfold\fR and we store that in a \fIfold.pl\fR file. This is naturally the difficult part, where ! you need to know some basic things about the mailagent internals. .IP \(bu Choose where you want to store your \fIfold.pl\fR file. Then check the syntax with \fIperl \-c\fR, just to be sure... --- 3016,3022 ---- Write a perl subroutine to implement the FOLD action and put that into an external file. Say we write the subroutine \fIfold\fR and we store that in a \fIfold.pl\fR file. This is naturally the difficult part, where ! you need to know some basic things about mailagent internals. .IP \(bu Choose where you want to store your \fIfold.pl\fR file. Then check the syntax with \fIperl \-c\fR, just to be sure... *************** *** 3005,3011 **** .Ef The \fIcmd_name\fR is the name of the command you wish to add. In our previous example, it would be FOLD. The next field, \fIpath\fR, tells ! the mailagent where the file containing the command implementation is located. Say we store it in \fI~/mail/cmds/fold.pl\fR. The \fIfunction\fR field is the name of the \fIperl\fR function implementing FOLD, which may be found in \fIfold.pl\fR. Here, we named our function \fIfold\fR. Note that --- 3051,3057 ---- .Ef The \fIcmd_name\fR is the name of the command you wish to add. In our previous example, it would be FOLD. The next field, \fIpath\fR, tells ! mailagent where the file containing the command implementation is located. Say we store it in \fI~/mail/cmds/fold.pl\fR. The \fIfunction\fR field is the name of the \fIperl\fR function implementing FOLD, which may be found in \fIfold.pl\fR. Here, we named our function \fIfold\fR. Note that *************** *** 3045,3051 **** within your function, hence switching to the \fImailhook\fR package in the body of the routine but leaving its name in the \fInewcmd\fR package.) .PP ! Since the mailagent will dynamically load the implementation of your command the first time it is run, by loading the specified perl script into memory and evaluating it, I suggest you put each command implementation in a separate file, to avoid storing potentially unneeded code in memory. --- 3091,3097 ---- within your function, hence switching to the \fImailhook\fR package in the body of the routine but leaving its name in the \fInewcmd\fR package.) .PP ! Since mailagent will dynamically load the implementation of your command the first time it is run, by loading the specified perl script into memory and evaluating it, I suggest you put each command implementation in a separate file, to avoid storing potentially unneeded code in memory. *************** *** 3069,3075 **** .PP Each command is called from within an \fIeval\fR construct, so you may safely use \fIdie\fR or call external library routines that use \fIdie\fR. ! If you use \fIrequire\fR, be aware that the mailagent is setting up a special \fI@INC\fR array by putting its private library path first, so you may place all your \fImailagent\fR-related library files in this place. ''' --- 3115,3121 ---- .PP Each command is called from within an \fIeval\fR construct, so you may safely use \fIdie\fR or call external library routines that use \fIdie\fR. ! If you use \fIrequire\fR, be aware that mailagent is setting up a special \fI@INC\fR array by putting its private library path first, so you may place all your \fImailagent\fR-related library files in this place. ''' *************** *** 3129,3135 **** .PP There is one more variable worth knowing about: \fI\$main'FILTER\fR, which is the suitable X-Filter line that should be appended in \fBall\fR the mail you ! send via the mailagent, in order to avoid loops. Also when you save mails to a folder, it's wise adding this line in case a problem arises: you may then identify the culprit. ''' --- 3175,3181 ---- .PP There is one more variable worth knowing about: \fI\$main'FILTER\fR, which is the suitable X-Filter line that should be appended in \fBall\fR the mail you ! send via mailagent, in order to avoid loops. Also when you save mails to a folder, it's wise adding this line in case a problem arises: you may then identify the culprit. ''' *************** *** 3317,3323 **** .I &main'xeqte(filter-actions) Execute a series of actions separated by the ';' character, calling \fIrun_command\fR to actually perform the job. Return the continuation status. ! Note that \$FT_ABORT will \fInever\fR be returned, since the mailagent usually stops after having executed one set of actions, only continuing if it saw an RESTART or a REJECT. What ABORT does is skipping the remaining commands on the line and exiting as if all the commands had been run. You --- 3363,3369 ---- .I &main'xeqte(filter-actions) Execute a series of actions separated by the ';' character, calling \fIrun_command\fR to actually perform the job. Return the continuation status. ! Note that \$FT_ABORT will \fInever\fR be returned, since mailagent usually stops after having executed one set of actions, only continuing if it saw an RESTART or a REJECT. What ABORT does is skipping the remaining commands on the line and exiting as if all the commands had been run. You *************** *** 3332,3338 **** .SS Example .PP Writing your own commands is not easy, since it requires some basic knowledge ! regarding the mailagent internals. However, once you are familiar with that, it should be relatively straightforward. .PP Here is a small example. We want to write a command to bounce back a mail --- 3378,3384 ---- .SS Example .PP Writing your own commands is not easy, since it requires some basic knowledge ! regarding mailagent internals. However, once you are familiar with that, it should be relatively straightforward. .PP Here is a small example. We want to write a command to bounce back a mail *************** *** 3384,3390 **** .PP Note the use of the \$ever_saved variable to mark the mail as saved once it has been bounced. Indeed, should the SENDBACK action be the only one ! action to be run, we do not want the mailagent to LEAVE the mail in the mailbox because it has never been saved (this default behavior being a precaution only -- better safe than sorry). ''' --- 3430,3436 ---- .PP Note the use of the \$ever_saved variable to mark the mail as saved once it has been bounced. Indeed, should the SENDBACK action be the only one ! action to be run, we do not want mailagent to LEAVE the mail in the mailbox because it has never been saved (this default behavior being a precaution only -- better safe than sorry). ''' *************** *** 4071,4077 **** ''' .SS Conclusion .PP ! The generic mail server implemented in the mailagent can be used to implement a mailing list manager, a vote server, an archive server, etc... Unfortunately, it does not currently have the notion of state, with a command set dedicated to each state, so it is not possible to implement an intelligent --- 4117,4123 ---- ''' .SS Conclusion .PP ! The generic mail server implemented in mailagent can be used to implement a mailing list manager, a vote server, an archive server, etc... Unfortunately, it does not currently have the notion of state, with a command set dedicated to each state, so it is not possible to implement an intelligent *************** *** 4143,4149 **** mailagent is running, that mail is queued and will be processed later by the \fImain\fR mailagent. .PP ! For the same reason, the mails sent back by the mailagent are queued by \fIsendmail\fR, to avoid the cost of mail transfer while processing commands. .SH "SECURITY" To avoid any problems, the \fIfilter\fR will refuse to run if the configuration --- 4189,4195 ---- mailagent is running, that mail is queued and will be processed later by the \fImain\fR mailagent. .PP ! For the same reason, messages sent back by mailagent are queued by \fIsendmail\fR, to avoid the cost of mail transfer while processing commands. .SH "SECURITY" To avoid any problems, the \fIfilter\fR will refuse to run if the configuration *************** *** 4154,4160 **** .PP Indeed, if someone can write into your \fI~/.mailagent\fR file, then he can easily change your \fIrules\fR configuration parameter to point to another ! faked rule file and then send you a mail, which will trigger the mailagent, running as you. Via the RUN command, this potential intruder could run any command, using your privileges, and could set a Trojan horse for later perusal. Applying the same logic, the rule file must also be protected tightly. --- 4200,4206 ---- .PP Indeed, if someone can write into your \fI~/.mailagent\fR file, then he can easily change your \fIrules\fR configuration parameter to point to another ! faked rule file and then send you a mail, which will trigger mailagent, running as you. Via the RUN command, this potential intruder could run any command, using your privileges, and could set a Trojan horse for later perusal. Applying the same logic, the rule file must also be protected tightly. *************** *** 4188,4194 **** mailagent's log file. .TP Queue/agent.wait ! list of mails waiting to be processed and stored outside of the mailagent's spool directory. .TP Queue/qmXXXXX --- 4234,4240 ---- mailagent's log file. .TP Queue/agent.wait ! list of mails waiting to be processed and stored outside of mailagent's spool directory. .TP Queue/qmXXXXX *************** *** 4211,4224 **** .PP A version number must currently contain a dot. Moreover, an old system (i.e. a system with an \fIo\fR in the patches column) must have a version ! number, so that the mailagent can compute the name of the directory holding the patches. .PP The lock file is deliberately ignored when \fB\-q\fR option is used (in fact, it is ignored whenever an option is specified). This may result in having mails processed more than once. .PP ! The mailagent is at the mercy of any \fIperl\fR bug, and there is little I can do about it. Some spurious warnings may be emitted by the data-loaded version, although they do not appear with the plain version. .PP --- 4257,4270 ---- .PP A version number must currently contain a dot. Moreover, an old system (i.e. a system with an \fIo\fR in the patches column) must have a version ! number, so that mailagent can compute the name of the directory holding the patches. .PP The lock file is deliberately ignored when \fB\-q\fR option is used (in fact, it is ignored whenever an option is specified). This may result in having mails processed more than once. .PP ! Mailagent is at the mercy of any \fIperl\fR bug, and there is little I can do about it. Some spurious warnings may be emitted by the data-loaded version, although they do not appear with the plain version. .PP Index: README *** README.old Thu Feb 16 15:43:33 1995 --- README Thu Feb 16 15:43:33 1995 *************** *** 114,120 **** super-user privileges). By not running "make install.man", you avoid the installation of the manual pages. ! 4) Read the manual entry before running. 5) IMPORTANT! Communicate any problem and suggested patches to me, ram@acri.fr (Raphael Manfredi), so we can keep this distribution in --- 114,120 ---- super-user privileges). By not running "make install.man", you avoid the installation of the manual pages. ! 4) Read the manual entry and the FAQ before running. 5) IMPORTANT! Communicate any problem and suggested patches to me, ram@acri.fr (Raphael Manfredi), so we can keep this distribution in *** End of Patch 32 *** exit 0 # Just in case...