Product Overview

• An @SH command processor, to remain compatible with the first implementation. In this simplest usage, all the mail messages are left in your mailbox, with special processing raised on messages whose subject is Command. Please refer to the section entitled USING THE DEFAULT RULES if you wish to use this feature.
• A complete mail filter, which helps you sort your mail based on various sorting criteria and actions. Filtering is specified in a rule file and supersedes the default Command mail processing (which may be turned on again by explicitly setting up a rule for it). This should be the most common use of mailagent and is fully documented under the section entitled USING THE FILTER. You may deliver mail to plain Unix-style folders but also to MMDF and MH ones.
• A replacement for the vacation program, which will automatically answer your mail while you are not there. You only need to supply a message to be sent back and the frequency at which this will occur. Some simple macro substitutions allow you to re-use some parts of the mail header into your vacation message, for a more personalized reply. See the VACATION MODE section for more details.
• A generic mail server, which will let you implement a real mail server without the hassle of the lower-level concerns like error recovery, logging or command parsing. The full documentation can be found in the section GENERIC MAIL SERVER at the end of this manual page.

It is possible to extend the mailagent filtering commands by implementing them in perl and then having them automagically loaded when used. Those extended commands will behave exactly like built in ones, as documented in the EXTENDING FILTERING COMMANDS section.

Learning From Examples

Choosing The Filter Program

On some platforms, sendmail does not correctly reset its UID when processing mails in its own queue. In that case, you need to get a private copy of the C filter program and make it setuid to yourself. The filter will then correctly reset its UID if invoked with an effective UID different from yours (it may also require the setgid bit to reset GID as well). If this is indeed the case on your system, make sure you use the path configuration variable to set a proper PATH, as the filter will spawn a perl process with the '-S' option, looking for a mailagent script.

Even if you do not need to get a setuid copy of the filter program, it is wise to set up a proper path: someone might break into your account by putting a mailagent Trojan horse in the appropriate location. Also make sure the mailagent program is protected against writing, as well as the directory which holds it, or someone might substitute his own version of the script and break security. I believe the setuid filter program to be safe, but overlooking is always possible so please report any security hole to me.

The filter script can be found in the Lib/mailagent directory. It needs some tailoring so you should copy it into your home directory and edit it to suit your needs. Comments held in it should be self explanatory. There is only a small section at the head of the script which needs to be edited. You'll have to delete shell comments in the filter script by yourself if your shell cannot deal with them.

As of version 3.0 PL44, I advise you to prefer the C version if you are concerned about security. If you are in a position where multiple architectures can process your .forward, then a shell wrapper selecting the proper executable based on the architecture will be required.

Configuring Mailagent

	mailagent -I

Otherwise, you have to copy the mailagent.cf file held in the mailagent sub-directory /usr/local/lib/mailagent (hereafter named Lib) as a .mailagent 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).

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 path or p_host variables. Once you are done, rerun the mailagent -I command to make sure everything is fine. Still, you will have to plug in mailagent by creating a ~/.forward file, as explained in a few sections.

Following is a description of each of the fields you will find in the ~/.mailagent 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.

agemax

Period after which an entry in the database should be removed (suggested: 1y) This field is optional, but needed if autoclean is on.

authfile

Remote sending authorizations (not implemented yet).

autoclean

Set to ON (case insensitively), mailagent will perform automatic cleaning of the database entries under hash by removing all the items older than agemax. This is an optional field, omitting it defaults to OFF. (suggested: OFF, unless you use ONCE, UNIQUE or RECORD commands, or activate the vacation mode.)

biff

Whether or not biffing is wanted when mailagent delivers mail to a folder. Set it to ON (case insensitively) to allow local biffing if you are logged in. (optional, defaults to: OFF)

biffchars

The charset to use when biffing on the terminal. Set it to utf-8 if you are using UTF-8 terminals. (optional, defaults to: iso-8859-1).

biffhead

When biffing is enabled, this variable lists which headers should be printed out. Headers should be given in their normalized format and be separated with commas. (optional, defaults to: From, To, Subject, Date).

bifflen

The maximum length of the message body that should be printed when biffing. (optional, defaults to 560).

bifflines

The maximum number of lines of the message body that should be printed when biffing. Actually, mailagent attempts to print that amount of lines, provided the total amount of characters printed is less than bifflen. (optional, defaults to 7).

biffmh

When turned ON, the body of the message is compacted before biffing by removing consecutive spaces and replacing newlines with a single space. The message itself is not altered physically of course, only the output on the screen is concerned. Since this may yield to a difficult-to-read message, I suggest you also turn on biffnice when using this option. (optional, defaults to: OFF).

biffmsg

The path to a file describing the format biffing should use. If not set, a default hardwired format is used. Season to taste. (suggested: ~/.biffmsg).

biffnice

Whether the message should be reformatted to nicely fit into the terminal. (optional, defaults to OFF, suggested: ON when biffmh is also ON).

biffnl

Controls whether "blank" body lines should be printed or not. By "blank" lines, we mean lines not containing words. Set it to ON to print such blank lines, to OFF if you wish to get a more compact view of the body within the limits fixed by bifflen and bifflines. (optional, defaults to ON).

biffquote

Controls whether the leading attribution line introducing a trimmed quotation should be part of the biff message or not. When turned OFF, the attribution line is trimmed along and this is reported in the trimming message, when bifftrim is ON. (optional, defaults to ON).

bifftrim

Controls whether trimmed lines within the biff message should be replaced by a message stating how many of them were trimmed. Only used by the %-T biffing macro. When turned OFF, it automatically turns off biffquote as well. (optional, defaults to ON).

bifftrlen

States how many lines long a leading quotation should be before performing any trimming. Only used by the %-T biffing macro. (optional, defaults to 2).

callout

The name of the callout queue file where batched jobs are kept. This parameter must be defined when using the AFTER command. (suggested: $spool/callout)

cleanlaps

Cleaning period for database entries. The value of the last clean up is saved into the context file. This is optional, but needed if autoclean is on. (suggested: 1M)

comfile

Name of the file containing authorized commands. Needed when PROCESS is used. (suggested: $spool/commands).

compress

Name of the file containing the list of compressed folders. See section about folder compression. This is an optional parameter. (suggested: ~/.compress).

compspecs

Name of the file containing specifications for how to handle different types of compression formats. See section about folder compression. This is an optional parameter. (suggested: $spool/compressors).

comptag

The default compression tag when creating new folders. If not specified, the default is 'gzip'.

comserver

Name of the file containing authorized SERVER commands and their definition. This is an optional parameter if you don't plan to use the generic mail server. (suggested: $spool/server).

context

File holding the mailagent context. The context saves some variables which need to be kept over the life of the process. Needed if auto cleaning is activated. (suggested: $spool/context)

distlist

A list of all the available distributions. See the sample held in Lib/mailagent/distribs. Needed by PROCESS only. (suggested: $spool/distribs)

domain

Your domain name, without the leading dot, as in example.com. The value is appended to the value of email when that variable does not have any '@', to construct a fully qualified e-mail address. See also the hidenet variable. (optional, defaults to the domain name determined at build time).

email

Your electronic mail address. If left unspecified, mailagent will try to guess it. This address is used by mailagent when trying to send something to the user (you!). (suggested: specify your e-mail address).

emergdir

Name of the directory which should be used for dumps, preferably. This is optional. (suggested: ~/tmp/lost+mail)

execsafe

Whether to be strict before using exec() to launch a new process or not. The value of this variable is used in place of secure when checking executable files. (defaults to OFF, suggested: ON if possible).

execskip

Whether to skip the exec() security checks alltogether. Don't turn this ON unless you really trust all the users having access to your machine or file server. (optional, default to OFF, suggested: OFF).

fromall

Whether or not mailagent should escape all the From lines in the message, not only those it thinks should appear dangerous (i.e. a From after a blank line). This option only makes sense when fromesc is also activated. It is ignored otherwise, and therefore is optional. By default, it is assumed to be OFF. (suggested: OFF, until you have reasons to believe your mail user-agent is confused in this mode: when it happens, your user agent will split mail for no apparent reason).

fromesc

Whether or not mailagent should escape potentially dangerous From 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)

fromfake

Whether or not mailagent 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).

groupsafe

If turned OFF, then group-writable files will be managed as if they were secure, from a security point of view. Leave it to ON if possible, or you may pass by a huge security hole without your noticing (optional, defaults to ON, suggested: ON).

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 or activate auto cleaning. The directory is placed in the spool area. (suggested: $spool/dbr).

helpdir

Directory where help files for SERVER commands are kept. (suggested: $spool/help)

hidenet

When set to ON, the value of the variable domain is the fully qualified name used. When OFF, the hostname is prepended to the domain. If the hostname is already fully qualified, then the value of domain is ignored. Assuuming domain is set to example.com and the hostname is host, then the fully qualified name will be host.example.com if hidenet is OFF, and example.com if ON. (optional, defaults to whatever was determined at build time)

home

Defines where the home directory is. This must be accurate.

level

Log level, see below for a definition of available levels (suggested: 9).

linkdirs

When set to ON, carefully checks symbolic links to directories when performing security checks on sensitive files. This will (recursively) check for each symbolic link level that the target directory is not world writable or group writable and that the parent directory of each target link is not world writable. If the secure option is OFF, this parameter is ignored. (optional, defaults to: ON, suggested: ON when secure is also ON).

lockdekay

The delay in seconds between two locking attempts. (optional, defaults to: 2).

lockhold

The maximum delay in seconds for holding a lock. After that time, the lock will be broken. (optional, defaults to: 3600).

lockmax

Maximum number of locking attempts before giving up. (optional, defaults to: 20).

locksafe

When locking a file, mailagent normally makes lockmax attempts separated by lockdelay seconds, and then gives up. When facing a delivery to a mailbox, it may make sense to continue even if no lock was grabbed, or even if only a partial locking was done (e.g. one of the .lock or flock()-style locking succeeded). This variable controls how safe you want to be. Set it to OFF to let mailagent continue its mailbox delivery even though no locking was done, to ON if you want strict locking, to PARTIAL if you can live with partial locking. Messages not saved in a folder are dumped to an emergency mailbox. (optional, defaults to ON).

lockwarn

This variable controls the time after which mailagent should start emiting a warning when busy trying to acquire a lock. It is a comma separated list of values, in seconds. If two values are given, the first is the initial time threshold, the second is the repeat period. For instance, a value of "15,60" would cause a warning after 15 seconds, then every 60 seconds until the lock is taken or the locking attempt time is expired (see lockmax and lockdelay). If only one value is given, it is taken as being both the initial threshold and the period. (optional, defaults to: 20,300).

log

Name of the log file which will be put in Log directory. (suggested: agentlog).

logdir

Logging directory. (suggested: ~/var/log).

mailbox

The name of the system mailbox file, which by default is the value of the user configuration variable. This is an optional parameter.

maildrop

Location of the system mail spool directory. If none is provided, then the mailagent will use the value determined by Configure.

mailopt

Options to be passed to the mailer (see sendmail). (optional, suggested: -odq -i, when using sendmail).

maxcmds

Maximum number of commands that are allowed to be executed by a SERVER command before flushing the remaining of the mail message. (suggested: 10).

maxerrors

Maximum number of errors for the SERVER command before flushing the remaining of the mail message. (suggested: 10).

maxsize

Maximum size in bytes of files before using kit for sending files. This is used by PROCESS. (suggested: 150000).

mboxlock

The format to be used for locking mailboxes before delivering to them. This string goes through a small macro substitution mechanism to make it more general. The file name derived after macro substitution is the name of the lock that will be used, given the name of the file that is to be locked. Available macros are:

%D: the file directory name
%f: the file name to be locked (full path)
%F: the file base name (last path component)
%p: the current process pid number
%%: a plain % character




    

Common locking formats are "%f.lock" and "%D/.%F.lock". Of course, to be able to use this feature, mailagent must not have been configured to use flock()-style locking only. (optional, defaults to: %f.lock).

mhprofile

The name of the MH profile to be used. This is needed only when attempting to save in an MH folder. If this optional parameter is not set, the default value ~/.mh_profile is used.

mmdf

Set this to ON if you wish to be able to save mail in MMDF-style mailboxes. (suggested: OFF, unless you use MMDF or MH).

mmdfbox

The value of this variable only matters when mmdf is on. If set to ON, then new folders will be created as MMDF ones. This variable is not used when saving to an existing folder, since in that case the mailagent will automatically determine the type and save the message accordingly. (suggested: OFF, unless you use MMDF or wish to use MH's mshf).

msgprefix

Name of the file to put in directory folders, specifying the message prefix to be used. Optional, defaults to .msg_prefix.

name

First name of the user, used by mailagent when referring to you. This sets the value of the %U macro.

newcmd

Name of the file describing new filtering commands. See section Extending Filtering Commands for more details. Leave this optional parameter out unless you are a mailagent expert. (suggested: $spool/newcmd).

newsopt

Options to be passed to the news posting program (see sendnews). (optional, suggested: leave empty when using inews).

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

passwd

File where SERVER power passwords are kept -- encrypted usually. (suggested: $powers/passwd).

path

Minimum path to be used by C filter program. To set a specific path for a machine host, set up a p_host variable. This will be prepended to the default PATH variable supplied by other programs. (suggested: /bin:/usr/bin:/usr/ucb). Note that the host name must be specified without any domain name appended to it (e.g. for an host name of lyon.eiffel.com, use variable p_lyon). If your host name contains an '-' in it, you must write it as a '_', since '-' is not a valid character for a perl variable name.

perlib

This variable may be used to change the perl search path for required files. Directories should be separated using a ':' character, just like a shell PATH. This path is prepended to the default perl search path. Any directory not starting with a '/' (after ~name substitution) is taken relatively to the mailagent private lib directory determined at configuration time.

plsave

Name of the file used to save the patchlevels for archived distributions. This is only used by the commands invoked via PROCESS. (suggested: $spool/plsave).

powerdir

Directory listing user clearances for SERVER powers. (suggested: $powers/clearance)

powerlist

Name of file containing SERVER power aliases. Since power names can be arbitrary long but some filesystems still have a 14 character limitation on filename length, internal aliases are created and maintained by mailagent. (suggested: $powers/aliases).

powerlog

File where SERVER power requests are logged, in addition to the agentlog. Since those are a security concern, it is a good idea to log them separately. If not defined, log them only in agentlog. (suggested: $logdir/powerlog).

powers

Directory for SERVER power administration. (suggested: $spool/powers)

proglist

A small description for the available distributions. See the sample held in Lib/mailagent/proglist. This is used by PROCESS only. (suggested: $spool/proglist)

queue

Queue directory (messages waiting to be processed). Required, of course. (suggested: $spool/queue)

queuehold

Maximum number of seconds a mail can sit in the mailagent queue before being actually processed. During that time, mailagent will not try to process the message even when -q is used. (optional, defaults to: 1800).

queuelost

Maximum number of seconds after which mailagent should flag messages still in its queue as being old. (optional, defaults to: 86400, i.e. a day).

queuewait

Time in seconds telling the C filter program how long it must wait before launching mailagent. (optional, defaults to: 60, but can be lowered to 0 if you don't want to wait to delay getting new messages).

rulecache

The name of the file used to cache the latest compiled rules. Since usually mailagent works mainly with one same rule file, this saves the overhead of recompiling all the rules each time. (optional, suggested: $spool/rulecache).

rulemac

Set this to ON to enable macro substitutions in rule patterns. (optional, defaults to: OFF).

rules

The name of the file holding the filtering rules (optional, suggested: ~/.rules).

runmax

Timeout for RUN commands and friends. (optional, defaults to: 3600).

scriptcc

Flag indicating whether a copy of the SERVER session transcript should be send to the user running mailagent. (suggested: OFF).

secure

When set to ON, mailagent and the C filter will perform extensive security checks on sensitive files. This includes checks for group writability, ownerships and protection testing on the directory where the file resides, and checks on symbolic links to directories (mailagent only, when linkdirs is ON too). Note that secure is assumed to be ON, whatever its real setting, when running as super-user. (suggested: ON).

sendmail

The name of the program used to send mail. That program must accept the mail message with headers on its standard input and a list of recipients on the command line. If not specified, will use the mailer chosen at configuration time (sendmail usually). The command line used to mail a message will be sendmail mailopt address(es). (optional, suggested: /usr/lib/sendmail).

sendnews

The name of the program used to post news. That program must accept the news article with headers on its standard input. If not specified, will use the news posting program chosen at configuration time (inews usually). The command line used to post an article will be sendnews -h newsopt. (optional, suggested: /usr/local/bin/inews).

seq

File used to compute job numbers (suggested: .seq).

servdir

The directory name where shell and perl server commands are stored. This is the default lookup place. Optional parameter unless SERVER is used. (suggested: $spool/cmds).

servshell

This is the name of the shell used to launch SERVER shell commands (actually to process the wrapper file that will ultimately exec() the command). On some systems like HPUX 10.x, this has to be set to /usr/old/bin/sh to get the plain old Bourne shell, because /bin/sh is a braindead POSIX shell that closes file descriptors greater than 2 upon exec(), whereas the Bourne shell does not. (optional, suggested: /bin/sh unless you're on HPUX 10.x, as explained before).

spool

Spool directory, required (suggested: ~/var/mailagent).

statfile

File where statistics should be gathered. If no such file exists, no statistics will be recorded (suggested: $spool/mailagent.st).

tofake

Whether or not mailagent should fake a To: line into the message header when it is absent, which will be used for filtering purposes (no physical alteration of the header occur). It uses Alternate-To: headers if found, otherwise it assumes the message was send to the user and takes the value from the user configuration variable. (optional, defaults to ON, suggested: ON; turn it OFF only if you want to identify missing To: lines to detect SPAM).

tome

This optional variable may contain a comma separated list of alternate logins that are also valid for the user (mail aliases). This is used in vacation mode to check whether the mail was sent to the user or to a mailing list. Matching is anchored on the login name, so saying "ro*" will match both root and rom.

track

Set to on (case insensitively), this turns on the -t option which tracks all the rule matches and the actions on standard output. This is optional (suggested: OFF).

timezone

The time zone value for environment variable TZ (optional).

tmpdir

Directory for temporary files. Required (suggested: /tmp).

umask

Default umask which is reset by mailagent before processing a message. Assumed to be decimal unless starting with '0' (for octal) or '0x' (for hexadecimal). The octal format is the easiest way to specify it nonetheless. (optional, defaults to: 077).

user

Login name of the user who runs mailagent. This sets the value of the %u macro.

vacation

A flag set to ON or OFF to switch the vacation mode accordingly.

vacfile

The name of the file to be sent back in vacation mode (suggested: ~/.vacation).

vacfixed

When ON, all changes to the vacation file (even locally) by means of the VACATION command are forbidden. This is useful if you usually have many customized vacation messages for different people but temporarily want to force one unique message (optional, defaults to: OFF).

vacperiod

The minimum time elapsed between two vacation messages to a given address (suggested: 1d).

Available Logging Levels

0	No logging
1	Major problems only
2	Failed deliveries
3	Successful deliveries
4	Deferred messages
5	Successful filter actions
6	Unusual but benign incidents
7	Informative messages
8	Non-delivery filter actions
9	Mail reception
12	Debug
19	Verbose
20	Lot more verbose

Plugging Mailagent

"| exec /users/ram/mail/filter >>/users/ram/.bak 2>&1"

It is very important to redirect error messages to some file within your home directory. For one thing, that will get you out of trouble if strange things start to happen, but more to the point, it makes your .forward file unique. Older sendmail program, in an heroic attempt to "optimize" delivery, will silently remove duplicate recipients, and if a recipient has a .forward, its literal content is used in place of his e-mail address. Therefore, two local recipients with the same filtering string will be considered as one unique recipient and only one of them will get the message...

If your system does not allow shell redirection from within the .forward, you can use this instead (only supported by the C filter):

"| exec /users/ram/mail/filter -o /users/ram/.bak"

Note that the .forward file only pipes the mail to the filter program and does not leave any copy in the mailbox. It is up to you to decide in the rule file whether you want to trash the mail away or leave it in the mailbox. If you do not have a rule file (i.e. you left a blank entry in your ~/.mailagent, or you named a non-existent file, or your file is simply empty), don't worry: the default action is to leave the mail in the mailbox.

Allowed Commands

Testing Your Installation

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 "tail -f logfile" to see what's happening. At the end of the processing, the logfile should contain something like the following (names of temporaries may -and will- of course differ; timestamps have been removed):

got the right to process mail
building default rules
parsing mail
analyzing mail
in mode 'INITIAL' for ALL
selector 'All' on '<1,->', pattern '/^Subject: [Cc]ommand/'
matching '/^Subject: [Cc]ommand/' on 'All' (<1,->) was false
NOTICE no match, leaving in mailbox
XEQ (LEAVE)
starting LEAVE
starting SAVE /usr/spool/mail/ram
LEFT [qm7831] in mailbox
FILTERED [qm7831] from ram (Raphael Manfredi)
mailagent continues
mailagent exits

If you do not get that, there is a problem somewhere. Start by looking at the ~/.bak file (or whatever file the .forward uses to redirect output of the filter). If you see something like:

FATAL no valid queue directory
DUMPED in ~/mbox.filter

The ~/.bak file may also contain error messages stating that perl was not found. In that case, there should be an error message in the logfile:

ERROR mailagent failed, [qm7886] left in queue

Queuing of mail also happens when another mailagent is running. If the logfile says:

denied right to process mail

If none of these occurs, then maybe sendmail did not process your ~/.forward at all or the file has a syntax error. Check your mailbox, and if your mail is in there, your .forward has not been processed. Otherwise, ask your system administrator to check sendmail's logfile. A correct entry would appear as (with leading timestamps and syslog stamps removed):

message-id=<9202041919.AA07882@york.eiffel.com>
from=ram, size=395, class=0, received from local
to="| /york/ram/mail/filter >>/york/ram/.bak 2>&1", delay=00:00:05, stat=Sent

If you still cannot find why the mail was not correctly processed, you should make sure you normally receive mail by removing (or renaming) your ~/.forward and sending yourself another test mail. Also make sure your home directory is world readable and "executable".

If you are using the C filter, make sure it is running on the right platform. There may be a low-level routing of all your mail to a mailhost machine, responsible for the final delivery, and the filter program will run on that machine, which may be a different platform than the one you compiled filter on. Also make sure your home directory is mounted on that machine, or the mail transport agent will be unable to locate your .forward file, less process it.

This kind of centralized mail delivery is good only when a few people have mail processing hooks (i.e. .forward files piping mail to a program); otherwise it's better to route mail to each user's workstation or machine, for local processing, to avoid an excessive workload on the mailhost machine, especially if it is a dedicated NFS server. If you are a system administrator installing mailagent and expect many people to use it, keep this in mind.

Configuring Help

=DEST=

This will be expanded to the sender's address (the one who sent you the mail currently processed by mailagent).

=MAXSIZE=

This stands for the maximum size set before kit is used to send files back (parameter maxsize in your ~/.mailagent file).

You may use the default help file or design one that will give even more details to the poor user.

Distribution Files

File proglist contains a small description for programs. The name of the program appears after a single star. It is followed by lines in free format. An optional three-dashes line separates each program's description. Note that a leading tab will be added to each line of description.

The distribs file holds lines of the following form:

progname version path archived compressed patches

progname

is the program name (the same as the one mentioned in proglist).

version

is the current version number. If none, a three-dashed line may be used.

path

is the path where the distribution is stored. The ~ will be expanded into your home directory. Note that if the distribution is stored in archived form, the path name is the one of the archive without the ending extension (which may be .cpio.Z or .tar.Z).

archived

is either y or n depending on whether the distribution is archived or not.

compressed

is either y or n depending on whether the distribution is compressed or not. This could be guessed from the extension's name, but we must think of file systems with short names.

patches

is y or n depending on whether the distribution is maintained or not by you. If you put a p, this means official patches are available, although you do not maintain the distribution. Finally, an o means that this is an old version, where only patches are available, but maildist will not work. In that case, assuming the version number is 1.0, old patches are expected in a bugs-1.0 directory.

You may include comments in both files: all lines starting with a leading # will be ignored.

Testing Your Mail Agent

Subject: Command
@SH mailhelp

If you have done everything right but it still does not work properly, increase log level to 20 and resend your command mail. Then check the log file. The diagnosis should be easier.

Once this works, you should check your distribs and proglist files by sending yourself the following mail:

Subject: Command
@SH maillist

Rule File Syntax

Comments are introduced by a leading '#' , which must be on the left margin. Unlike shell comments, a '#' which is not left justified will not be understood as a comment, unless there is a space following '#'. Spaces or tabs are allowed in front of '#'.

All the statements in the rule file must end with a ';'. There are mainly four parts in each line. A list of comma separated modes, between '<' and '>', which give the set of modes in which the rule applies. The special mode ALL will match everything. The filter begins in the mode INITIAL. Omitting the mode defaults to "<ALL>". It is possible to guard a rule against some specific mode by negating it, which is done by prefixing the mode with '!'. Negated modes take precedence other plain modes, meaning "<!ALL>" will never be matched, ever, and that "<MODE, !MODE>" is equivalent to "<!MODE>".

Then comes a list of selectors. Those selectors must be space separated and end with ':'. They represent the names of header fields which must be looked at by the forthcoming pattern. An empty selector list defaults to "Subject:". Special selectors "All:", "Body:" and "Head:" apply to the whole message, its body or its header. A commonly used selector list is "To Cc:" which tests the recipient fields of the header. If the selector name is preceded by an exclamation mark '!', then the logical value of the test for that selector is negated.

The list of selectors may end with an optional range specification, given as <min, max>, before the final ':' character marking the end of the selector list. The minimum or the maximum may be given as '-', in which case it is replaced with the minimal or maximal possible value. Indices for selection begin at 1 (not 0), for instance: <3, 7>. If no range selection is given, then the default <1, -> is used. Ranges normally select lines within the matching buffer, unless the selector is expecting a list in which case it operates on the list items. For instance, Body <3, 5>: would select lines #3 to #5 (included) from the mail body, whereas To Cc <1,3>: would focus on the first three addresses on each To: or Cc: header lines. Negative values refer to that many lines or addresses back from the end, i.e. Cc <-2,->: selects the last two addresses on the Cc: line. A single number such as <2> is understood as <2, 2>, i.e. it select only one item in the list, <-> meaning everything (and being therefore redundant).

The selector is then followed by a pattern within '/' or by a single name. In order to ease the writing of the rules, the semantic of a single name varies depending on the selector used. For the special selectors "From:", "To:", "Cc:", "Sender:", their associated "Resent-" fields, "Reply-To:", "Envelope:" and "Apparently-To:", a single name is understood as a match on the login name of the address. Note that if no "To:" field is present in the header, one will be forged from the "Apparently-To:" for the purpose of filtering only (i.e. no physical modification on the header is done). If the login name of the address is a full name of the form First.Last, only the last name is kept, and is lower-cased. If only a single name is given, only shell metacharacters * and ? are allowed, as well as intervals [].

If the pattern is preceded by a single exclamation mark '!', then the matching status is negated (i.e. it will succeed if the pattern is not found). If a single word is used for non-special selectors, the same rules apply but the pattern is anchored at the beginning and the end for an exact match. With a pattern starting with '/', any regular expression understood by perl may be used and your pattern will not be modified in any way. The other special selector "Newsgroups:" works as "To:", excepted that newsgroups names are expected and a match is attempted on every item in the list. Every pattern match on a single name for an address-type field (i.e. "Newsgroups:" excluded), are made in case-insensitive mode. Otherwise, you can force a case-insensitive match by appending a trailing i option, as in /pattern/i.

There is also a little magic involved when matching on an address field. Namely, if the pattern is not a single word and is anchored at the beginning, then only the address part of the field will be kept. For instance, if we have a From: field whose value is Raphael Manfredi <ram@eiffel.com>, then the pattern /Raphael/ would match, but not /^Raphael/. Instead, /^ram@.*$/ would match, but this is more easily done with a single word pattern ram, for it only focuses on the login name of the address and would also match if the address was written as eiffel.com!ram. A single address in Internet form, as in ram@eiffel.com is implicitely matching on the address part of the field, and you must not escape the '.' as you would have to in a regular expression.

This may sound a little complex, but this design is meant to make things easier for the user. Here are some other examples:

# Match ram@eiffel.com as well as ram@educ.emse.fr.
From: ram
# Match root@eiffel.com, ram but not ribbon@eiffel.com
From: r[oa]*
# Match gue@eiffel.fr but not algue@eiffel.fr
To Cc: /^gue@eiffel\.fr/
# This will match gue@eiffel.fr as well as algue@eiffel.com
To Cc: /gue@eiffel/
# Match comp.lang.perl but not comp.lang.perl.poetry (?)
Newsgroups: comp.lang.perl
# Accept anything but messages coming from root
From: !root

Then comes the action to be taken when a match occurs. There are only a limited set of valid actions which will be described soon in detail. The action is enclosed in curly braces '{' and '}' and actions are separated or terminated (depending on your taste) by a ';'. Action names are spelled in upper-case for readability, but case is irrelevant. If you want to put a ';' within the rule, it must be escaped by preceding it with a backslash. A double backslash is translated into a single one, and any other escape sequence involving the backslash character is ignored (i.e. \n would be kept verbatim).

Note that a rule should be ended by a single ';' after the last '}'. It is possible to omit this final ';', but that single token is the re-synchronizing point for error recovery. One could argue however that there should be no syntax error, and thus the ';' ought to be safely omitted. Whenever in doubt, check your rule file with the -d option.

Here is a prototypical rule (using perl regular expressions; please refer to the subsection Regular Expressions for more information):

<ROOT> From: /^\w+@eiffel.com$/ { SAVE eiffel };

It is possible to have more than one selection for a rule. Identical selectors are logically or'ed while different ones are and'ed. The selections are comma separated. For instance,

From: root, To: ram, From: ram, Subject: /\btest\b/ { DELETE };

From: root, ram, To: ram, Subject: /\btest\b/ { DELETE };

Anywhere in the rule file, it is possible to define some variables. The list of recognized variables is given later. For now, let's say that maildir is the default folder directory. This variable is used by the SAVE command when the argument is not an absolute path. Setting

maildir = ~/mail;

Finally, there is a special construct to load patterns from a file. A pattern enclosed in double quotes means that the patterns to be applied should be taken from the specified file. The file is expected to be in the directory mailfilter if it is not an absolute path (~ substitution occurs). If the variable is not set maildir will be used. If by chance (!) maildir is not set either, the home directory is used. The file should contain one pattern per line, shell comments (#) being allowed at the beginning of each line.

An action may be followed by other rules. Hence the following is perfectly valid:

From:
	ram		{ SAVE ram }
	/plc/i		{ SAVE plc }
	root		{ SAVE ~/admin }
	/xyz/		{ DELETE }
	"users"		{ LEAVE }
	;

Selector Combination

From: ram, To Cc: root, !Subject: /test/, From: raphael

Let D be the set of direct selectors and N the set of negated selectors, which form a partition of R, the set of all the selectors in the rule. That is to say, R is the union of D and N, and D intersected with N is the empty set (trivial proof: a selector is either direct or negated). If either D or N is empty, then it's not a partition but in that case we have either D = R or else N = R.

Let's define the logical value of a set S as being the logical value the filter would return if those rules were actually written. Then the logical value of D is the logical value of each of its item with the AND logical operator distributed among them, i.e. the logical value of { a, b, c } is the value of (a AND b AND c). Let's write it AND(D). The logical value of each of the items is the logical value of the selector itself if it is not multiple, or it is the logical value of all the occurrences of the multiple selector within the rule, with the logical OR operation distributed among them. That is to say, in the above example, the value of From is true iff the From: fields contains ram OR raphael. Let's write that OR[From].

To be sound, we have to apply De Morgan's Law on N, hence the following rules: the logical value of N is OR(N) and given a negated selector s, its logical value is AND[s]. And finally, the logical value of R is that of D AND N, with by convention having the logical value of the empty set be true.

For those who do not know De Morgan's Law, here it is: given two logical propositions p and q, then the following identities occur:

NOT (p AND q) <=> (NOT p) OR (NOT q)
NOT (p OR q) <=> (NOT p) AND (NOT q)

p AND (q OR r) <=> (p AND q) OR (p AND r)
p OR (q AND r) <=> (p OR q) AND (p OR r)

The attentive reader will certainly have noted that I have not specified the logical value of a group selector. Well, given a group selector G, we decompose it into a DG and NG partition, DG being the subset of (atomic) direct selectors of G and NG being the subset of (atomic) negated selectors. Then the logical value of DG is OR(DG) and the logical value of NG is AND(NG); the global logical value of G being that of DG OR NG. In case either DG or NG is empty, then we don't have a partition, but by convention the value of the empty set is false, and one of the sets is equal to G. Note that within a group selector, the rules are exactly the dual of the rules within R.

Now the only rule which is not logical is whether a group selector belongs to D or N. I've chosen, for analogy reasons, to make the group selector belong to D if it does not start by '!' and to N otherwise. That is, !To Cc: belongs to N whilst Cc !To: belongs to D. Apart from that, order within the group selector is irrelevant: To Cc: is equivalent to Cc To:, so the behavior in the quotient set is sound.

Here are some examples:

# Match anything: (not from ram OR not from root) is always true.
From: !ram, !root
# Match anything but reject mails coming from ram OR root
!From: ram, root
# Reject mails whose headers matching /^Re.*/ contain the word test
!^Re.*: /\btest\b/
# Keep mails whose subject contains test AND host
!Subject: !/test/, !/host/
# Matches if ram is listed in the To OR the Cc line
To Cc: ram

Minimal Header

Envelope:

This is the address found in the mail envelope, i.e. the address where the mail seems to originate from. This can be different from the From: address field if the mail originates from a trusted user, in sendmail's terminology. If you don't know what that is, simply ignore it.

From:

User who wrote the mail. If this line is missing, uses the address found in the first From line.

Length:

The physical length of the body, in bytes, once content-transfer-encoding (if any) has been removed.

Lines:

The amount of lines in the body (decoded, if necessary).

To:

The main recipient(s) of the message. If this line is missing but a set of Apparently-To: lines is found, then those addresses are used instead. If no such line exists, then assume the mail was directed to the user (which seems a reasonable assumption :-).

Sender:

User who sent the mail. This may differ from the From: line. If no such field exists, then the address in the first From line is used (mail envelope).

Relayed:

This computed header is a comma-separated list of all the hosts where the message was relayed, in the proper transmission order. Each item in this list can be a machine name such as mail.hp.com or an IP address such as [15.125.38.12]. The list is derived from the Received: lines present in the message.

Reply-To:

Where any reply should be sent. If no Reply-To: field is present, then the Return-Path is used (with <> stripped out), or the From: line is parsed to extract the e-mail address of the author.

Variables

For example, let's say the user receives cron outputs from various machines and wishes to save them on a per-machine basis, differentiating between daily outputs and weekly ones. Here is a solution:

Subject: /output for host (\w+)/	{ ASSIGN host '%1'; REJECT };
Subject: /^Daily output/	{ SAVE %#host/daily.%D };
Subject: /^Weekly output/	{ SAVE %#host/weekly.%m-%d };

Here are some actions to canonicalize the host name into lower case and strip down the domain name, if any:

{ TR #host /A-Z/a-z/; SUBST #host /^([^.]*)\..*/$1/ };

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.

Within PERL commands or mail hooks using perl (see the MAIL HOOKS section), you can manipulate those (so-called) external variables via a set of interface functions located in the extern package (i.e. you must prefix each of the function name with its package name, set becoming extern'set). The following three interface functions are provided:

val(name)

Return the value of the variable name (the leading ':' is not part of the name, in any of these three interface functions).

set(name, value)

Set the external variable name to hold value. No interpretation is done by the function on the actual content of the value you are providing.

age(name)

Returns the age of the variable, i.e. the elapsed time in seconds since the last modification made by set.

There is currently no way for erasing a variable from the database. But if you do not use the variable any more, it will be removed when its age becomes greater than the maximum age specified by the agemax configuration variable.

Regular Expressions

For instance:

To: /(.*)/, Subject: /Output from (\w+)/ { ASSIGN to '%1'; SAVE %2 };

Subject: /host (\w+)/, /from (\w+)/ { ASSIGN match '%1' };

Subject: /from/, /host (\w+)/, To: /(.*)/ { SAVE %1; REJECT };

However, this behavior can be used to selectively store a news article which has been mailed to you in a folder whose name is the newsgroup name in dot form. Assuming we want to give priority to comp.lang.perl, we could say:

Newsgroups:
	/(comp.lang.perl)/,
	/(comp.mail.mh)/,
	/(comp.compilers)/,
	/([^,]*)/		{ SAVE %1 };

There is also a special macro %&, which lists (it's a comma separated list) all the selectors specified via a regular expression which indeed matched. For instance:

Re.*: /york/		{ ASSIGN which '%&' };

Should you have more than one such specified selector within a single rule, then it might be worth knowing that all the set of matching selectors are recorded within %&, each set terminated with a ';'. If a negated selector is used, then %& will record all the fields which did not contain the pattern, assuming the selection succeeded (otherwise nothing is recorded).

Available Actions

ABORT [-tf] [mode]

Abort application of filtering rules immediately. See REJECT for the meaning of the optional parameters. (Does not modify existing status)

AFTER [-sanc] (time) action

Records a callback for after the specified time, where action will be performed. By default, a mailagent filtering action is assumed (-a option), on the current mail message. A shell command (-c) may be given instead, receiving the current mail message as standard input. Finally, a plain shell command may be run (with no input) using the -s option. The option -n may be used when the current mail message does not need to be kept for input. For instance:

AFTER -an (1 day) DO ~/process:proc'run(%u)




    

would call proc'run defined in the ~/process file in one day from now, without giving any input (the action here does not require any).

When running mailagent commands, the initial working mode is set to _CALLOUT_. This may matter if you call APPLY for instance. If the recorded time is less or equal than the current time (which is now), the callback will occur when mailagent is done with the messages in its queue, before exiting. This allows for the following cute trick, found out by Randal Schwartz:

AFTER (now)		# fork a copy I can mangle
	STRIP Reply-To \; RESYNC \;
	ANNOTATE -du Reply-To %2 \; RESYNC \;
	NOTIFY message %r \; DELETE \;
	;




    

Note that the command is not called AT because the call will only be performed at the next mailagent invocation after the specified time has elapsed. Dates are specified using the same format as in SELECT. (Fails if the action cannot be recorded in the callout queue).

ANNOTATE [-du] field value

Annotate message by adding field into the mail header, with the supplied value. This is like the MH command anno, but the annotation is performed at the end of the header, whereas MH does it at the top. Normally, an extra field is added, with the current date as field value.

This can be suppressed by using the -d option. If value is omitted, only the date field is generated (hence it is an error to use the -d option without supplying a value). As with all the commands which alter the header, a RESYNC is necessary for the filter part to actually see the new header.

The -u option means "unique", and prevents ANNOTATE from executing if the specified field is already present in the header. Don't forget to RESYNC between successive ANNOTATE commands using this option if the field refers to a previous ANNOTATE target. (Fails when no annotation takes place)

APPLY rulefile

Get the rules held in rulefile and apply them to the current message. The filter will begin in whatever mode you were when using this command, but no feed back will occur, i.e. any mode changing will be lost when returning from the command.

Variables (see the %# macro) are propagated back and forth through APPLY, meaning you see variables set by the caller, and you may change their values or create new variables for the caller to later use.

If mail is saved during the application of the rules, then the corresponding flag is set in the main filter (the one that started the APPLY command). You may nest them, of course. (Fails if mail is not saved by the rules held in rulefile)

ASSIGN var value

Assign the value to the user-defined variable var, which may further be accessed as %#var for macro substitution or #var in the TR and SUBST commands in place of the variable name. Note that there is no leading # in front of the variable name. The value you provide is first ran through perl to see if it contains some arithmetic operations. If the evaluation is successful, the resulting value is used instead. If an error occurs in this evaluation process, then the literal value provided is used. To avoid the evaluation, you may enclose the whole value in simple quotes. Those will be trimmed before the assignment takes place. If you actually want simple quotes in the first AND last position, you have to double each of them. (Does not modify existing status)

BACK command

Execute command and take its output as new actions to be performed on the mail (hence performing something analogous to `command` in shell). If there is no output, nothing is done. BACK commands can be nested, although this may lead to surprises this manpage will not disclose (but I assure you it will be funny, assuming we have the same sense of humor... :-). Note that both the standard output and the standard error from the command are used.

If the command fails, the output is mailed back to the user and no action is performed. Furthermore, normal feedback does not occur here: any output from the command is taken as filter actions, which means the semantics of PASS, for instance, is changed: we do not take a body back but commands. (The execution status is that of the command)

BEEP [-l] count

This command may be used to tune the amount of beeps emitted when biffing on the terminal, for each %a expansion. By default, that amount is set to 1. Using the -l option alters the beep count locally for the rule. Otherwise, the default amount is changed.

Note that this simply expands %a into the suitable amount of Ctrl-G characters. Your terminal must be allowed to issue consecutive bells for this to work. Very often, terminals are configured so that the first bell received disables further beeps for some period, to avoid cascades of bells. If you use xterm for instance, you should use:

xterm -xrm "XTerm*BellSuppressTime: 0"




    

to enable consecutive bells. Otherwise, xterm will swallow them during 200 ms, hence making the BEEP command ineffective, apparently. (Does not modify existing status)

BEGIN [-ft] state

Enter a new state. An explicit REJECT or RESTART is necessary to abort the processing of the current rule. The processing begins in the state INITIAL. If the -f (resp. -t) flag is specified, then the state change only occurs if the last command status indicated a failure (resp. a success). A state name can contain alphanumeric characters and underscores. (Does not modify existing status)

BIFF [-l] on|off|path

Allow or disallow biffing dynamically. When biffing is turned on via the configuration file or via this command, a message is printed on some of the terminals where the user is logged when mail is received, as explained under the section MAIL BIFFING.

Instead of on or off, you can specify a file name (~ substitution allowed) being the new path to be used for the biffing format template.

If you use the -l option, changes are made locally, for the duration of the rule only. If you REJECT to go to some other rule, your changes will be lost. The global value of the altered parameters is changed on the first local usage and restored when a new rule is entered. (Does not alter execution status)

BOUNCE address(es)

Bounce the message to the specified address(es) and acts as if a save had been done. The only difference with FORWARD is that no Resent-like lines are added to the header. If an address is specified in double quotes, it is taken as the name of a file to be loaded to get addresses (one address per line, shell comments (#) allowed). The file name resolving is the same as the one used for pattern loading. (Fails if mail cannot be resent)

DO routine [(arg1, arg2, ... , argn)]

Calls the perl routine, with the supplied arguments if any. This is a very low level hook into mailagent's internal. The routine can be specified by itself (package'name, package being main by default), or identified by a leading tag, followed by a ':', then the routine name as before. The tag can be a path to a file where the routine is defined, or a command name (for user-defined commands which are loaded dynamically). For instance

DO UNKIT:newcmd'unkit('true')




    

would lookup the user-defined UNKIT command, load the file where it is defined (in the newcmd package), then call the routine with 'true' as argument. The package specified determines where the loading is done, so be sure it is consistent with the definition in the file where the routine is defined. (Fails if the routine cannot be located and executed)

DELETE

Delete the current message. Actually, this does not do anything, it just marks the mail as saved. If no further action involving saving is done, then the mail will never show up in the mailbox. (Never fails)

FEED [-be] program

Feed the whole message to a program and get the output back as the new message. Hence the program appears as a filter for the whole message. It does not tag the message as having been saved. A RESYNC is automatically done upon return. (Returns the status of program)

WARNING: Your program must be able to properly parse a MIME message and must deal with transfer-encoded bodies by itself. To make the program task simpler, you can supply the -b switch wich will let mailagent decode the whole body for you, suppressing any Content-Transfer-Encoding header (implying "binary"). This is an invalid message format for sending the message, but it makes processing easier. You still have to parse the MIME parts yourself though.

Using -b does not prevent your program from outputing a valid message back, one that can be possibly sent on the network so you have two options: either you do not supply any Content-Transfer-Encoding in the headers, and mailagent will recode the body for you using the initial transfer encoding present in the message (a relatively safe option if you make only changes in the body at well-defined spots without introducing 8-bit chars), or you can supply the Content-Transfer-Encoding yourself and perform the body encoding manually.

To be completely safe and minimize the work in your program, the -e switch will let mailagent analyse the message body you are returning and select the proper transfer encoding automatically. Since this will cause the whole body to be analysed, and it can be potentially huge, that behaviour must be explicitly asked for. If you need -e then you probably want -b as well (you can supply both by saying -be naturally).

If you do not supply any switch, mailagent will give you the message as-is and will get your message as-is without any additional magic.

FORWARD address(es)

Forward mail to the specified address(es). This acts as if a save had been done, in order to avoid the DELETE. Usually when you forward a mail, you do not wish to keep it. The command adds Resent-like lines in the header. As for BOUNCE, file inclusion is possible (i.e. use an address "forward_list" to forward a mail to all the users listed in the file forward_list). (Fails if mail cannot be resent)

GIVE program

Give the body of the message to the specified program by feeding its standard input. Any output is mailed to the user who runs the mailagent. Note that the message is not tagged as having been saved. (Returns the status of program)

NOTE: If the message had a body that was encoded for transport (using one of the base64 or quoted-printable transfer encoding), mailagent will transparently decode it and supply a version that can be properly handled. In other words, the program does not need to care about the body being encoded in the message, as it will get a plain one. (Since no headers are supplied, this is the only possible option).

Caution though for MIME messages: you should use PIPE for them to give a chance to the program to properly handle the body, but then it needs to be fully MIME-aware.

KEEP header_fields_list

Keeps only the corresponding lines in the header of the mail. For instance, a "KEEP From To Cc Subject" will keep only the principal fields from the mail message. This is suitable for archiving mailing lists messages. You may add a ':' after each header field name if you wish, but that is not strictly necessary. Headers may be specified using shell-style regular expressions, and file inclusion is allowed to get headers from a file. (Does not modify existing status)

LEAVE

Leave incoming mail in the system mailbox. This is the default action if no rule matched or if no saving occurred. (Fails if mail cannot be saved)

MACRO [-rdp] name [= (value, type)]

Lets you specify user-defined macros, of the form %-(name). See the paragraph on user-defined macros for explanation about the available types (SCALAR, EXPR, CONST, FN, PROG, PROGC). A perl interface to the underlying user macros is available for your perl commands. The -r option is used to replace an existing macro (instead of pushing a new instance on the stack), the -d is to delete all the instances of a named macro (in that case it takes only the first argument), and -p pops the last instance of the macro from the stack and reverts to the previous definition, if any (otherwise, it acts as -d). If you wish to define a simple SCALAR macro, you may omit the = (value, type) part and simply continue with the macro value. (Does not modify existing status)

MESSAGE file

Send message file back to the sender of the message (as derived from the header of the message). The text of the message is run through the macro substitution mechanism (described later on). (Fails if message cannot be sent)

NOP [-ft]

No operation. If this seems a bit odd, think of it in terms of a ONCE command. (Does not alter existing status unless -f or -t is used, in which case it forces a false --failure-- or true success status)

NOTIFY file address(es)

Send a notification message file to a given address list. The text of the message is run through the macro substitution mechanism (described later on). As with FORWARD, file inclusion for address specification is possible. (Fails if message cannot be sent)

ON (day list) command

Execute the specified filter command only on the specified day list. That list is a space-separated list of days, specified using the English names. Only the first three characters are taken into account, case-insensitively. Therefore, the shortest valid day specifications are Mon, Tue, Wed, Thu, Fri, Sat and Sun.

This command can be used in conjunction with SELECT to do time-based selective bouncing of messages to, for instance, your home address:

ON (Mon Tue Wed Thu) SELECT (18:30 .. 23:00) BOUNCE me@home.net;
ON (Fri) SELECT (18:30 .. 23:59) BOUNCE me@home.net;
ON (Sat Sun) BOUNCE me@home.net;




    

That would bounce messages only on week-ends and during the week, after 18:30, and until 23:00 (assuming that's bed time, other messages will be seen at work the next day). Note that on Fridays, we go as far as 23:59. (Propagates status from command. If the command is not executed, always return success)

ONCE (name, tag, period) command

Execute the specified filter command once per period. The name and tag fields are used to record timestamps of the last ONCE command. More on this later. (Propagates status from command. If the command is not executed, always return success)

PASS program

Feed the body of the message to the specified program and get a new body back from the output of the program. Note that the message is not tagged as having been saved. (Returns the status of program)

NOTE: If the message had a body that was encoded for transport (using one of the base64 or quoted-printable transfer encoding), mailagent will transparently decode it and supply a version that can be properly handled. The body generated by the program will then be automatically encoded back using the same transfer encoding.

Caution though for MIME messages: you should use FEED for them to give a chance to the program to properly handle the body, but then it needs to be fully MIME-aware.

PERL script [arguments]

Escape to a perl script to perform some actions on the message. This is fully described further in the manpage, and is very different from a RUN perl script command. (Returns failure if the script did not compile or returned a non-zero status).

PIPE [-b] program

Pipe the whole message to the specified program, but do not get anything back. Any output is mailed to the user who runs the mailagent. The message is not tagged as having been saved in any case, so you must explicitly DELETE it if piping was enough and it did not fail: "REJECT -f" is your friend here to avoid unwanted deletion. (Returns the status of program)

WARNING: Your program must be able to properly parse a MIME message and must deal with transfer-encoded bodies by itself. To make the program task simpler, you can supply the -b switch wich will let mailagent decode the whole body for you, suppressing any Content-Transfer-Encoding header (implying "binary"). This is an invalid message format for sending the message, but it makes processing easier. You still have to parse the MIME parts yourself though.

POST [-lb] newsgroup(s)

Post the message to the specified newsgroup(s) after having cleaned-up the header: mail-related fields like Received: or In-Reply-To: are removed, a valid From: line is generated, the original To: and Cc: are renamed with an X- prefix, the References: line is updated/generated if necessary based on existing In-Reply-To, and NNTP-specific fields are stripped so that the server can add its own.

Running POST successfully acts as a saving.

If the first name is -l as in "POST -l comp.mail.mh", then a "Distribution: local" header is added to force a local delivery. Otherwise, the default inews distribution will be used (world, usually).

When the -b switch is given, a successful POST will result in biffing being activated (see section MAIL BIFFING) for the resulting news article.

If more than one newsgroup is specified, they should be space separated. It is possible to get a newsgroup list via file inclusion. (Fails if message cannot be posted)

PROCESS

Run the mailagent processing which looks for @SH commands and executes them. This was described before in the section dealing with default rules. The action associated by default to a mail having [Cc]ommand as its subject is PROCESS. (Always returns success)

PROTECT [-lu] mode

Sets the default protection mode that should be set on created folders (or created files when saving into an MH folder or a directory). By default, permissions are governed by the UMASK command, but this lets you override the default. The specified mode should be preceded by a 0 as in 0644 to give the familiar octal permissions. Otherwise, it is interpreted as a decimal number, so beware!

The -l option may be used to specify a mode locally for one rule. Otherwise, the protection mode is set globally. The -u option unsets the global (or local when combined with -l) mode, reverting to the default behaviour where only the umask is taken into account by the system.

Note that when saving into an MH folder, the PROTECT command takes precedence over the Msg-Protect field from your ~/.mh_profile file. (Does not alter execution status)

PURIFY program

Feed the header into a program and get new header back. RESYNC is done automatically upon return. This may be used to indeed purify the header by removing all the verbose stuff added by so many mail transport agents (X-400 like lines for instance). Obviously, this does not flag the message as having been saved. (Returns the status of program)

If your program removes the Content-Transfer-Encoding header in a MIME message, mailagent will properly transform the message to have a non-encoded body. If you change the value of the Content-Transfer-Encoding header, mailagent will also correctly recode the body for you. The only supported encodings are base64 and quoted-printable.

QUEUE

Queue mail again. A successful queuing counts as if mail has 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 cron, the mail will remain in the queue until another mail arrives. (Fails when mail cannot be queued)

RECORD [-acr] [state] [(tag-list)]

Record message in the history and enters state _SEEN_ if the message was already present there. If the message is recorded for the first time, processing continues normally. Otherwise a REJECT is performed. This behavior may be somewhat modified by using some options. See UNIQUE for a complete description of the options and arguments. Naturally, when a state is specified, that overrides the default _SEEN_. A state name can contain alphanumeric characters and underscores.

When a tag-list (comma-separated list of names) is specified, the message is only recorded and checked against all those tags, but only them. Not specifying any tag list means any occurrence, whether it is tagged or not. See paragraph Using Tags in Record and Unique for more information. (Returns a failure status if mail was already recorded)

REJECT [-tf] [state]

Abort execution of current action, and continue matching. If -t is specified, the reject will occur only if the previous action was successfully completed (return status of true), whilst -f would cause the reject only when a failure occurred. If a state is specified, we enter that state before rejection. REJECT resets the matching flag, which means that if no further match occurs, the default action will apply. A state name can contain alphanumeric characters and underscores. (Does not alter execution status)

REQUIRE file [package]

Behaves like the perl require operator by loading a perl file into memory. By default, the file is read in the newcmd package, but you may specify whatever package you wish to load it in. This command will only perform the loading once per (file, package) tuple. Unlike its perl equivalent, the file "value" is not important, i.e. it does not have to end with a statement returning a true value. (Fails if file cannot be loaded)

RESTART [-tf] [state]

Abort execution of current action and restart the matching process from the beginning. To avoid loops, each rule may be walked through once in a given state. See REJECT for the meaning of the optional parameters. RESTART resets the matching flag, which means that the default action will apply, should no further match occur. (Does not alter execution status)

RESYNC

Re-synchronize header used for matching with the header of the mail. This is probably useful only when a SUBST or ANNOTATE command was run. (Does not alter execution status)

NOTE: At RESYNC time, mailagent will check whether the Content-Transfer-Encoding header was changed and will transparently recode the body if required, so that the whole message remains valid despite header mangling. It will also take care of updating Content-Length if required. Whenever you do change these important headers via SUBST or ANNOTATE, be sure to call RESYNC before disposing of the message or you run the risk of saving a corrupted version that will not be properly understood by your mail user agent.

RUN program

Run the specified program and mail any output to the user who runs mailagent. This action does not flag the message as having been saved. (Returns the status of program)

SAVE folder

Save message in the specified folder. If folder name starts with a '+', it is handled as an MH-style folder and rcvstore is emulated to deliver the message into that folder. If folder is a directory, message is delivered in a single file within that directory. See the FOLDERS section. (Fails if message cannot be saved)

SELECT (start .. end) command

Execute the command only within the time selection period specified. Dates can be specified in a wide range of formats. The output of the date(1) command is an example of a valid specification. If the date, the year or the month is missing, then the current one is substituted in place of it. The following dates are valid specifications: '10:04:25', 'now' ,'April 1 1992', 'Dec 25', 'July 14 1789, 07:40' (err... it's valid according to the grammar, but it's before the Epoch so it does not mean anything). Other fancy dates like 'last month - 5 minutes' or '3 weeks ago' are also enabled. (Isn't that great to have a real parser? The filtering rules could have been more elaborated if only I had known about this Berkeley yacc producing a perl parser...). (Returns the status of command, if run, otherwise returns true).

SERVER [-t] [-d disabled commands]

Activate server processing. The body of the message is interpreted as a list of commands to execute. See section GENERIC MAIL SERVER for more information about the server itself. The -t option turns the server into trusted mode, where powers may be gained. The -d option must be followed by a list of disabled commands, separated by commas with no intervening spaces between them.

SPLIT [-adeiw] folder

Split a mail in digest format into the specified folder (same naming conventions as in SAVE). If no folder is specified, each digest item is queued and will be analyzed as a single mail by itself. The -d option deletes the digest header. The -i option means split is done in-place and the original mail is discarded. All the options may be used simultaneously provided they are stuck together at the beginning (option parsing being really rudimentary).

If the mail is not in digest format and a folder is specified, then it is saved in that folder. Otherwise, the SPLIT action fails and nothing occurs (the filter continues its processing though). The SPLIT command will correctly burst RFC-934 digest messages and will try to do its best otherwise. If the digest was not RFC-934 compliant and there is a chance SPLIT might have produced something incorrect, then the original message is also saved if -i, otherwise it is not tagged as saved (so that the default LEAVE command may apply). The -w (watch) requests special care and will detect every non RFC-934 digest, even when the non-compliance is otherwise harmless; furthermore, any trailing garbage longer that 100 bytes will be saved as a digest item by itself.

The -a option annotates every digest item with an X-Digest-To: header line, which is the concatenation of the To: and Cc: fields of the original digest message. This may be used for instance to burst the digest into the queue and then re-process each of its items according to this added field. Finally, the -e option will discard the digest header only if its body is empty (i.e. the moderator did not include any leading comment). (Returns success if mail was in digest format and correctly split without any error)

STORE folder

Save message in the specified folder and leave a copy in the system mailbox. The folder parameter follows the same naming conventions as in SAVE. (Fails if message cannot be saved either in the folder or in the mailbox)

STRIP header_fields_list

Remove the corresponding lines in the header of the mail. For instance, a "STRIP Newsgroups Apparently-To" will remove the appropriate lines to wipe out any Newsgroups: or Apparently-To: header. You may add a ':' after each header field name if you wish, but that is not strictly necessary. Headers may be specified via shell-style regular expressions or via "file" inclusion. (Does not alter execution status)

SUBST var/header expression

Substitutes the expression on the specified user-defined variable (name starting with a #) or back-reference (digit), or header field (optionally ending with ':'). For instance

SUBST #foo /w/y/g




    

would substitute in user-defined variable foo all the w by y. See also ASSIGN and TR.

For substitutions on header fields, like:

SUBST Subject: /\[foo\]\s+//;




    

matching header lines will be reformatted when the substitution is successful, which likely means original continuations will not be preserved. The target of the substitution is the whole header, with continuations normalized to one space. You are therefore guaranteed to be independent from the actual header formatting in the original.

Do not forget to issue a RESYNC after a header field SUBST, since some routines (like POST) probe into the parsed header hash table to generate the saved message.

(Fails if error in expression)

TR var/header translation

Perform the translation on the specified variable, back-reference or header field. For instance

TR 1 /A-Z/a-z/




    

would canonicalize content of reference 1 into lowercase. Successfully transliterated headers are reformatted, even when their overall size is not changed. See also ASSIGN and SUBST. (Fails if error in translation)

UMASK [-l] mode

Changes the process's umask to the specified mode, which can be decimal, octal (if preceded by '0') or hexadecimal (starting with '0x'). The octal notation is the clearest way to specify the umask anyway. Aren't rumors saying that octal was invented for that purpose only? ;-) Use the -l option to change the umask for the duration of the current action rule only. Note that the default umask specified in your config file is used to reset mailagent's umask at the start of each mail processing. (Does not alter execution status)

UNIQUE [-acr] [state] [(tag-list)]

Record message in the history and tag message as saved if it was already present there. If the message is recorded for the first time, processing continues normally. Otherwise a REJECT is performed. If -r was used, a RESTART is used instead whilst -a would run an ABORT. For instance, to remove duplicate messages from mailing lists, run a UNIQUE -a before saving the mail. The -c option may be used alone to actually prevent the command from disturbing the execution flow, and to later use the return status to see what happened: UNIQUE returns a failure status if the message was already recorded. If an optional state argument is given, then the automaton will enter that state if the mail was previously in the database. See also RECORD, and the paragraph entitled Using Tags in Record and Unique for more information about the tag-list. (Fails if mail was already recorded)

VACATION [-l] on|off|path [period]

Allow or disallow a vacation message. When vacation mode is turned on via the configuration file, a message is sent whenever the user receives a mail meeting some requirements, as explained under the section VACATION MODE. One of the conditions is that the vacation flag modified by this command be true. This makes it easy to disallow vacation messages, ever, to a group of people for instance.

Instead of on or off, you can specify a file name (~ substitution allowed) being the new path to be used for locating the vacation file. Optionally, you may specify a last parameter, which will be taken as the period to apply when sending the vacation message. Changes to the vacation message path are forbidden when the configuration variable vacfixed is set to ON.

If you use the -l option, changes are made locally, for the duration of the rule only. If you REJECT to go to some other rule, your changes will be lost. The global value of the altered parameters is changed on the first local usage and restored when a new rule is entered. (Does not alter execution status)

WRITE folder

Write the message in the specified folder, removing any pre-existing folder with the same name. Hence, successive WRITE commands will overwrite the previous one. This is useful to store output of system commands ran by cron. Don't try to use it with an MH folder or a directory folder or it will behave like SAVE. (Fails if message cannot be written)

Execution Status

Some of the actions however do not modify this last execution status. Typically, those are actions which make decisions based on that status, or simply actions which may never fail. Those special actions are: ABORT, ASSIGN, BEGIN, KEEP, MACRO, NOP, REJECT, RESTART, RESYNC, STRIP and VACATION.

It is unfortunate that ONCE or SELECT commands cannot make the difference between a non-execution and a successful execution of the specified command. There may be a change in the way this scheme works, but it should remain backward compatible.

Perl Escape

Before we go any further, please note that as there is no extra process created, you must not call the perl exit function. Use &exit instead, so that the exit may be trapped. &exit takes one argument, the exit code. If you use 0, this is understood as a success, any other value meaning failure (i.e. the PERL command will return a failure status). Using the perl exit function directly would kill mailagent and would probably incur some mail losses.

The scripts used should remain simple. In particular, you should avoid the use of the package directive or define functions with a package name other than mailhook (i.e. the package where your script is loaded). Failure to do so may raise some name clashes with mailagent's own routines. In particular, avoid the main package. Note that since the compilation environment is set-up to mailhook, not specifying package names in your variables and subroutine is fine (in fact, it's meant to work that way).

Your script is free to do whatever it wants to the mail. Most of the time however, you end up using the mailagent primitives to save the mail or forward it (but you are free to redesign your own and call them instead, of course). The interface is simple: each function takes but one argument, a string, which is the arguments to the command, if any. For instance, in a perl escape script, you would express:

{ SAVE list; FORWARD "users"; FEED ~/bin/newmail -tty; REJECT }

&save('list');
&forward('"users"');
&feed('~/bin/newmail -tty');
&reject;

Each function returns a boolean success status of the command (i.e. 1 means success). For those functions which usually do not modify the filter's last execution status variable, a success is always returned. This makes it possible to (intuitively) write:

&exit(0) if &save('uucp');
&bounce('root') || &save('emergency');

It is important to understand that these commands have exactly the same effect on the filtering process when they are run from a perl escape script or from within the rule file as regular actions. A &reject call will simply abandon the execution of the current perl script and the filter automaton will regain control and attempt a new match. But perl brings you much more power, in particular system calls, control structures like if and for, raw regular expressions, etc...

The special perl @INC array (which controls the search path for require) 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 script:

@ARGV

The arguments of the script, which were given by the PERL command. This array is set up the exact same way you would expect it to be set up if you invoked the command directly from the shell, excepted that @ARGV[0] is the name of the script (since you cannot use perl's $0 to get at it; that would give you mailagent's name).

$address

The address part of the From: line.

$cc

The raw content of the Cc: line.

@cc

The list of addresses on the Cc: line, with comments suppressed.

$envelope

The mail envelope, as computed using the first From line of the message.

$friendly

The comment part of the From: line, if any.

$from

The content of the From: line, with address and comment part.

%header

This table, indexed by field name, returns the raw content on the corresponding header line. See below.

$msgpath

The full path name of the folder (or message within an MH folder) where the last saving operation has occurred. This is intended to be used if you wish to construct your own mail reception notification.

$length

The message length, in bytes.

$lines

The number of lines in the message.

$login

The login name of the address on the From: line.

$precedence

The content of the Precedence: line, if any at all.

@relayed

The list of host names (possibly raw IP addresses if no DNS mapping) listed in the (computed) Relayed: header line.

$reply_to

The e-mail address where a reply should be sent to, with comment suppressed.

$sender

The sender of the message (may have a comment), derived in the same way the Sender: line is computed by mailagent.

$subject

The subject of the message.

$to

The raw content of the To: line.

@to

The list of addresses on the To: line, with comments suppressed.

The associative array %header gives you access to all the fields in the header of the message. For instance, $to is really the value of $header{'To'}. The key is specified using a normalized case, i.e. the first letter of each word is uppercased, the remaining being lowercased. This is independent of the actual physical representation in the message itself.

The pseudo keys Head, Body and All respectively gives you access to the raw header of the message, the body and the whole message. The %header array is really a reference to the mailagent's internal data structure, so modifying the values will influence the filtering process. For instance, the SAVE command writes the Head, the X-Filter: line, the end of header (a single newline) and then the Body (this is an example only, not a documented feature :-). The =Body= key is special: it is a Perl reference to a scalar containing the body with any content transfer encoding removed.

Note that the $msgpath variable holds only a snapshot of the folder path at the time where the PERL escape was called. If you perform your own savings in perl, then you need to look at the $main'folder_saved variable instead to get the up-to-date folder path value.

As a final note, resist the temptation of reading the internals of the mailagent and directly calling the routines you need. If it is not documented in the manual page, it may be changed without notice by any further patch. (And this does not say that documented features may not change also... It's just more unlikely, and patches would clearly state that, of course.)

Program Environment

All the programs are executed from within the home directory. This includes scripts started via the PERL command and mail hooks. The latter will be described in detail further down.

File inclusion

The file should list each parameter (be it an address, a header or a pattern) on a line by itself. Shell-style comments (#) are allowed within that file and leading white spaces are trimmed (but not trailing spaces).

Macros Substitutions

%%

A real percent sign

%A

The internet address extracted out of the From: field (a.b.c in u@a.b.c), converted to lower-case.

%C

CPU name on which mailagent runs. That is a fully qualified hostname with the domain name, e.g. lyon.eiffel.com.

%D

Day of the week (0-6)

%H

Host name (name of the machine on which the mailagent runs), without any domain name. Always in lower-case, regardless of the machine name.

%I

The internet domain name extracted out of the From: field (b.c in u@a.b.c), converted to lower-case.

%L

Length of the body part, in bytes, with content-transfer-encoding removed.

%N

Full name of the sender (login name if none)

%O

The organization name extracted out of the From: field (b in u@a.b.c), converted to lower-case.

%R

Subject of the original message with leading Re: suppressed

%S

Re: subject of original message

%T

Time of the last modification on mailed file (commands MESSAGE and NOTIFY)

%U

Full name of the user

%Y

Full year, with four digits (so-called yyyy format)

%_

A white space (useful to put white spaces in single patterns)

%&

List of selectors which incurred match (among those specified via a regular expression such as 'X-*: /foo/i'. If we find the foo substring in the X-Mailer: header line, then %& will be set to this value). Values in the list are comma separated.

%~

A null character, wiped out from the resulting string.

%digit

Value of the corresponding back reference from the last match.

%#var

Value of user-defined variable var

%=var

Value of the mailagent configuration variable var as specified in the ~/.mailagent file.

%d

Day of the month (01-31)

%e

The user's e-mail address (yours!).

%f

Contents of the "From:" line, something like %N <%r> or %r (%N) depending on how the mailer is configured.

%h

Hour of the day (00-23)

%i

Message ID, if available (otherwise, this is a null string)

%l

Number of lines in the message, once content-transfer-encoding has been removed

%m

Month of the year (01-12)

%n

Lower-case login name of sender

%o

Organization (where mailagent runs)

%r

Return address of message

%s

Subject of original message

%t

Current hour and minute (in HH:MM format)

%u

Login name of the user

%y

Year (last two digits)

%[To]

Value of the header field (here To:)

User-defined Macros

Once defined, a user macro (say foo) can be substituted by using %-(foo). In the case of a single-letter macro, that can be optimized into %-f for instance, i.e. the parenthesis can be omitted.

There are six types of macros:

SCALAR

A scalar value is given, e.g: red. The macro's value is the literal scalar value, no further interpretation is performed on the data.

EXPR

A perl expression will be evaled to get the value, e.g: $red. Note that the evaluation will be performed within the usrmac package, so if you are referring to a variable in another package, it would be wise to specify it, as in $foo'bar.

CONST

It's really the same as EXPR, but the value is known to be a constant. So the first time a substitution is made, the expression will be evaluated, and then its result is cached.

FN

A perl function name (without the leading &), such as main'do_this. The function will be called with a single parameter: the name of the macro itself. That leaves the door open for further user-defined conventions by forcing evaluation through one single perl function.

PROG

A program to run to get the actual value. Only trailing newline is chopped, others are preserved. The program is forked each time. In the argument list given to the program, %n is expanded as the macro name we are trying to evaluate. If you specify that in the filtering rules, don't forget to escape the first %.

PROGC

Same as PROG really, but the program is forked only once and the value is cached for later perusal.

At the perl level, four functions let you manipulate and define your macros (all part of the usrmac package):

new(name, value, type)

Replace or create a %-(name) macro. For instance:

new('foo', "$mailhook'header{'X-Foo'}", 'EXPR');




    

would create a new macro foo that would expand into the value of an hypothetical X-Foo header.

delete(name)

Delete all values recorded for the macro.

push(name, value, type)

Stack a new macro, creating it if necessary.

pop(name)

Remove last macro definition on the stack.

One macro stack is allocated for each macro, so that some kind of crude dynamic scoping may be implemented. Creating a macro via push is like taking a local variable in perl, while creating one by new is simply assigning to a variable. Likely, pop is like exiting a block with a local variable definition and delete frees all the macro bearing that name, i.e. it deletes the whole stack.

At the filter level, the MACRO command has three options. By default, the command defines a new macro by using push, and the other options each let you access one of the other interface functions. Note that macro definitions persist across APPLY commands.

User-defined Logging

Normally, logs are appended into the agentlog file by calling &main'add_log(string) (see subsection General Purpose Routines). For plain mailagent actions, this is fine.

But mailagent lets you define alternate logging files, referred to by name. This generic logging interface is defined in the usrlog package:

new(name, file, flag)

Records a new log file known as name and done in file. If the pathname given for this file is not absolute, it is rooted under the logdir directory. If flag is set to true, any logging done to this file will also be copied to the default system-wide logfile. Nothing is done if a logfile with the same name has already been defined.

delete(name)

Deletes the logfile known as name. Further logging done to that file is redirected to the default logfile.

main'usr_log(name, string)

Adds an entry to the logfile name. The default logfile is known as default and cannot be redefined nor deleted. Note that this function is available from the main package. Calling it with name set to the string 'default' is mostly equivalent to calling directly main'add_log with the notable exception that the -i mailagent option will not be honored in that case. This may or may not be useful to you.

If you call &main'usr_log with a non-existent logfile name, logging is redirected to the default system-wide logfile defined in your ~/.mailagent.

Dynamically Loading New Code

Using the so-called dynload interface buys you some extra features:

• The mailagent public library path is automatically prepended to the @INC array, which lets you define your own system-wide or private perl library files (the private library path is defined by the perlib configuration variable, the public library path was defined at installation time).
• Like perl's require, mailagent keeps track of which files were loaded into which packages and will not reload the same file in the same package twice.
• It is possible to make sure that a specific function be defined in the loaded file, with an error reported if this is not the case.
• You benefit from the default logging done by dynload when some error occurs.

In order to do all this, you call:

&dynload'load(package, file, function)

Using Once Commands

Here is a prototypical usage of a ONCE, which acts like the vacation program, excepted that it sends a reply only once a day for a given address:

{ ONCE (%r, message, 1d) MESSAGE ~/.message };

The timestamps associated with each commands are kept in files under the Hash directory. The name is used as a hashing key to compute the name of the file (the two first letters are used). Inside the file, timestamps are sorted by name, then by tag. Of course, you could say (inverting tag and name):

{ ONCE (message, %r, 1d) MESSAGE ~/.message };

Using Tags in Record and Unique

This is very useful when receiving mail cross-posted to distinct mailing lists and you want to save one instance of the message in each folder, but still guard against duplicates. You may say:

To Cc: unix-wizards	{
	UNIQUE (wizards);
	SAVE wizards;
	REJECT;
};
To Cc: majordomo-users	{
	UNIQUE (majordomo);
	SAVE majordomo;
	REJECT;
};

To Cc: majordomo-users	{
	UNIQUE (majordomo);
	SAVE majordomo;
	REJECT;
};
To Cc: dist-users {
	UNIQUE (dist, agent);
	SAVE dist-users;
	REJECT;
};
To Cc: agent-users {
	UNIQUE (dist, agent);
	SAVE dist-users;
	REJECT;
};

Specifying A Period

m

minute

h

hour (60 minutes)

d

day (24 hours)

w

week (7 days)

M

month (30 days)

y

year (365 days)

All the periods are converted internally in seconds, although you do not really care... Examples of valid periods range from "1m" to "136y" on a 32 bits machine (why ?).

Timeouts

There is also a filter queue timeout. In order to moderate system load, the C filter program waits 60 seconds by default (or whatever queuewait was set to in the config file) before launching mailagent. To avoid conflicts, messages queued by the first filter (which will then sleep for queuewait seconds) are not processed by mailagent's -q option until they are at least queuehold seconds old. Another queue-related parameter is queuelost, the amount of seconds after which mailagent will flag messages as "lost" when listing the queue.

Finally, the locking timeout policy may also be configured. By default, a lock is broken when it is one hour old (configured by the lockhold variable) and mailagent will only make lockmax attempts, spaced by lockdelay seconds to acquire the lock. It will then proceed whether or not it got that lock. If you want a secure locking policy, make sure lockmax times lockdelay is greater than lockhold, that parameter being "large" enough.

Avoiding Loops

The _SEEN_ state makes it easy to deal with mails which loop because of an alias loop you have no control on. If no action is found in the _SEEN_ state, the mail is left in the mailbox, as usual. Moreover, if no saving is done, a LEAVE is executed. This is the normal behavior.

The "X-Filter:" header is only added when the message is saved. Actions such as PIPE or GIVE do not flag the message as being saved and therefore they do not add that header line. You can add one via ANNOTATE if you wish to prevent loops, in case the program to which you are feeding the message might return it to you in some strange way.

Message Files

At the head of the message, you may put header lines. Those lines will overwrite the default supplied lines. That may be useful to change the default subject or add some additional fields like the name of your organization. The end of your header is given by the first blank line encountered. If the top of the message you wish to send looks like a mail header, you may protect it by adding a blank line at the very top of the file. This dummy line will be removed from the message and the whole file will be sent as a body part.

Here is an example of a vacation file. We add a carbon copy as well as the name of our organization in the header:

Cc: ram
Organization: %o
Precedence: bulk
[Last revision made on %T]
Dear %N:
I've received your mail regarding "%R".
It will be read as soon as I come back from vacation.
Sincerely,
--
%U <%u@%C>

Folder Format

When MMDF mode is activated, each folder will be scanned to see if it is a UNIX-style or MMDF-style mailbox and the message will be saved accordingly. When saving to a new folder, the default is to create a UNIX-style mailbox, unless the mmdfbox configuration variable was set to ON, in which case the MMDF format prevails.

Note that the MMDF format is also the standard for MH packed folders, so by enabling the MMDF mode, you can actually deliver directly to those packed folders. The MH command inc is able to incorporate mail from either form anyway, i.e. it does not matter whether the folder is in UNIX format (also called UUCP-style) or in MMDF format.

MH-style folders are also supported. It is mainly a directory in which messages are stored in individual files. To save directly into an MH folder, simply prefix the folder name with '+', just as you would do with MH commands. The unseen sequences specified in your MH profile (the mhprofile parameter in your ~/.mailagent, default is ~/.mh_profile) will be correctly updated, as rcvstore would.

When the target folder is a directory, mailagent attempts the delivery in an individual numbered file. If a prefix file is present (config parameter msgprefix, default is .msg_prefix), its first line is used to specify the base name of the message, then a number is appended to give the name of the message file to use. That is, if there is no such file, the folder will look like an MH one, without any MH sequence file though.

Folder Compression

To achieve folder compression, you have to set up a file, referred to by the compress configuration variable. This file must list folder names, one per line, with blank lines ignored and shell-style (#) comments allowed. You may use shell-style patterns to specify the folders, and the match will be attempted on the full pathname of the folder (~ substitution occurs). If you do not specify a pattern starting with a leading '/' character, then the match will be attempted on the basename of the folder (i.e. the last component of the folder path). If you want to compress all your folders, then simply put a single '*' inside this file.

Mailagent uses the filename extension to determine what compression scheme is used for a particular folder. The file referred to by the compspecs configuration variable (default is $spool/compressors) is used to define the commands that mailagent will use to perform the compress, uncompress, and cat operations for a particular extension.

The compressors file holds lines of the following form:

tag extension compression_prog uncompress_prog cat_prog

tag

is the logical name for the compression scheme. This is typically the same as the name of the program used to provide the compression, but could be different for some unforeseen reason. This must be unique across all records in the file.

extension

is the extension to recognize as belonging to the specified tag. This must be unique across all records in the file.

compression_prog

is the name of the command to run to compress a folder. The program must replace the uncompressed file with the compressed one with the extension appended to the filename (like compress or gzip).

uncompression_prog

is the name of the command to run to uncompress a folder. The program must replace the compressed file with the uncompressed one without the extension (like uncompress or gunzip).

cat_prog

is the name of the command to output the uncompressed contents of a compressed folder to stdout (like zcat or gzcat).

The fields are separated by TABS to allow for the use of space characters in the command fields.

If the file referred to by the compspecs configuration variable cannot be accessed for whatever reason, a default entry is hard-wired into mailagent (knows about both compress and gzip programs):

compress <TAB> .Z <TAB> compress <TAB> uncompress <TAB> zcat
gzip <TAB> .gz <TAB> gzip <TAB> gunzip <TAB> gunzip -c

If you wish to add more compressors, you can copy the default compressors file from mailagent's private library directory and setup a correct entry for your alternate compressor. Keep in mind that the trailing extension needs to be unique amongst all the listed programs, since that extension is used to determine the type of compression performed on the folder.

If the folder is created without any existing compressed form around, a default compressor is selected for you, as defined by the comptag configuration variable. That refers to the tag name of the compspecs file, i.e. the first word on the line (usually the name of the compression program, but not necessarily).

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 (ie. the file has a recognized filename extension) 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.

If for some reason there is a 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.

On newly created folders the comptag configuration variable is referenced to determine the compression type to use for the folder.

Customizing Biffing Output

%-A

Same as writing %-H, new line, %-B

%-B

The body part of the biffing message, with content-transfer-encoding removed. If the message is a MIME multipart one, the text/plain part is shown. If only a text/html part is available, the HTML markup is stripped for biffing.

%-H

The header part of the biffing message. If shows only From:, To: Subject: and Date: headers, or whatever you have set the biffhead configuration variable to. All headers are showed as one line of text, regardless of their actual length. There will be three trailing dots at the end to signal that truncation occurred. For a news article (biffing after a POST -b), the To: and Cc: fields are never shown, even if specified in biffhead.

%-T

Same as %-B, but trimming is activated. The purpose of trimming is to remove any leading quotation in the message, to get only the most meaningful part. This assumes the quoting character is a single non-alphanumeric character. The leading attribution line that may introduce the quotation can be also removed, and a minimum length for the quotation can be set in the configuration file.

%B

The relative path under %d of the message folder, full path (%p) if not saved under that directory. The newsgroup name for news articles.

%D

The directory where the message is stored. If an MH folder, this is the folder full path. The home directory is replaced by a ~. Empty for news articles.

%F

The base name (last path component) of the message. For an MH message, this is the message number. Empty for news articles.

%P

The folder path. It has the correct semantics for MH and directory folders, i.e. it points to the folder directory itself. Otherwise, the same as %p.

%a

Alarm characters (^G). May expand to more than one under the control of the BEEP filtering command. Use %b if you only want a single bell.

%b

A beeping character (^G). As opposed to %a, this only expands to give one bell.

%d

Full path where folders such as the one being saved into are stored if not qualified (i.e. your MH path for MH folders, of something like ~/Mail for other folders). Empty for news articles.

%f

Folder where mail was saved, home replaced by ~ for short. The newsgroup when article was posted for news.

%m

A '+' sign if the folder is an MH one, empty otherwise.

%p

The full path name (same as %f) of the message, but without any ~ shortcut. The newsgroup name for news articles.

%t

The type of message: usually "mail", but set to "article" for biffing after a POST command.

You can get the standard macro expansion by using %:f for instance, since the %f macro is superseded. The %: form lets you obtain the standard macro definition anyway, no matter what, so you don't have to remember whether a given macro is superseded in this context or not. Besides, it is safer since new macros may be added here without notice. Note that macros related to the message content all start with %- and therefore are not conflicting with standard one.

Here is the format you need to use to get the same behaviour as the default hardwired format:

%b
New %t for %u has arrived in %f:
----
%-A
----%b

Trimming Leading Quotation

Quoting John Doe:
> This is quoted material.
> Another line from John's mail.
This is part of the reply to John.

However, when biffing, this may be seen as useless noise, especially nowadays where people freely quote more and more in their replies. Since the biff message only shows the top lines of the message, it may be desirable to automatically trim those quoted lines.

Via the %-T macro in the customized biff format, you may request trimming of the leading quotation material, keeping the attribution line or not, and even replace trimmed material with a notification that so many lines have been removed.

All this customization is done from the ~/.mailagent configuration file, using the bifftrim, bifftrlen and biffquote variables.

You first need to turn trimming on by using a customized biff format using the %-T macro. By setting bifftrlen to 3, you may request that only quotations of at least 3 lines be trimmed. Turning bifftrim off will remove the trimming notification, whilst turning biffquote off will also strip the attribution line, when present.

For instance, assuming the following settings:

bifftrim : ON
bifftrlen: 2
biffquote: OFF

[trimmed 3 lines starting with a leading '>' character & attribution line]
This is part of the reply to John.

The trimming algorithm considers the first line of the body to see if it starts with a non-alphanumeric character. If it does, then all the following lines starting with that same character, or any blank line is removed, up to the first non-blank line starting with another character. Optionally, the first line (and that line only) is skipped if the second one starts with a non-alphanumeric character, and the first line is taken as being the attribution line.

Using Compact MH-style Biffing

Since this compacting is output verbatim on the tty, line breaks will occur randomly and this may make reading difficult. You may request an automatic reformatting of the compacted body by turning biffnice to ON and the biff output will fit nicely within the terminal.

To make biffnice really nice, mailagent probes each tty (those where biffing was turned on) for its size and uses that information to drive formatting of the output. Note that you can set biffnice even when biffmh is OFF. This really helps maximizing the amount of body text displayed.

Overview

• Write a perl subroutine to implement the FOLD action and put that into an external file. Say we write the subroutine fold and we store that in a fold.pl file. This is naturally the difficult part, where you need to know some basic things about mailagent internals.
• Choose where you want to store your fold.pl file. Then check the syntax with perl -c, just to be sure...
• Edit the newcmd file (as given by the configuration file) to record your new command. Then make sure this file is tightly protected. You must own it, and it should not be writable by any other individual but you.
• Additionally, you may want to specify whether FOLD is to modify the existing execution status and whether or not it will be allowed within the special _SEEN_ state.
• Write some rules using the new FOLD command. This is the easy part! Note that your command may also be used within perl hooks as if it were a builtin command (this means there is an interface function built for you within the mailhook package).

In the following sections, we're going to describe the syntax of the newcmd file, and we'll then present some low-level internal variables which may be used when implementing new commands.

New Command File Format

Each line is formed by 3 principal fields and 2 optional ones; fields are separated by spaces or tabs. Here is a skeleton:

<cmd_name> <path> <function> <status_flag> <seen_flag>

The last two fields are optional, and are boolean values which may be specified by true or yes to express truth, and false or no to express falsehood. If status_flag is set to true, then the command will modify the last execution status variable. If seen_flag is true, then the command may be used when the filter is in _SEEN_ state. The default values are respectively true and false.

So in our example, we would have written:

FOLD  ~/mail/cmds/fold.pl  fold  no  yes

Writing An Implementation

(Normally, in PERL hooks, there is no need for this prefixing since the perl script is loaded in the mailhook package. When you are extending your mailagent, you should be extra careful however, and it does not really hurt to use this prefixing. You are free to use the perl package directive within your function, hence switching to the mailhook package in the body of the routine but leaving its name in the newcmd package.)

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.

Each command is called with one argument, namely the full command string as read from the filter rules. Additionally, the special @ARGV array is set by performing a shell-style parsing of the command line (which will fail if quotes are mismatched, but then you can do the parsing by yourself since you get the command line). At the end of your routine, you must return a failure status, i.e. 0 for success and 1 to signal failure.

Those are your only requirements. You are free to do whatever you want inside the routine. To ease your task however, some variables are pre-computed for you, the same ones that are made available within mail hooks, only they are defined within the newcmd package this time. There are also a few special variables which you need to know about, and a set of standard routines you may want to call. Please avoid calling something which is not documented here, since it may change without prior notice. If you would like to use one routine and it is not documented in this manual page, please let me know.

Each command is called from within an eval construct, so you may safely use die or call external library routines that use die. If you use require, be aware that mailagent is setting up a special @INC array by putting its private library path first, so you may place all your mailagent-related library files in this place.

Special Variables

$mfile

The base name of the mail file being processed. This variable is read-only. It is mainly used in log messages, as in [$mfile] to tag each log, since a single mailagent process may deal with multiple messages.

$ever_saved

This is a boolean, which should be set to 1 once a successful saving operation has been completed. If at the end of the filtering, this variable is still 0, then the default LEAVE will be executed.

$folder_saved

The value of that variable governs the $msgpath convenience variable set for PERL escapes. It is updated whenever a message is written to a file, to hold the path of the written file.

$cont

This is the continuation status, a variable of the utmost importance when dealing with the control flow. Four constants from the main package can be used to specify whether we should continue with the current rule ($FT_CONT), abandon current rule ($FT_REJECT), restart filtering from the beginning ($FT_RESTART) or simply abort processing ($FT_ABORT). More on this later.

$lastcmd

The last failure status recorded by the last command (among those which do modify the execution status). You should not have to update this by yourself unless you are implementing some encapsulation for other commands, like BACK or ONCE, since by default $lastcmd will be set to the value you return at the end of the command.

$wmode

This records the current state of the filter automaton (working mode), in a literal string form, typically modified by the BEGIN command or as a side effect, as in REJECT for instance.

All the special variables set-up for PERL escapes are also installed within the newcmd package. Those are $login, %header, etc... You may peruse them at will.

Other variables you might have a need for are configuration parameters, held in the ~/.mailagent configuration file. Well, the rule is simple. The value of each parameter param from the configuration file is held in variable $cf'param. Variable $main'loglvl is the copy of $cf'level, since it's always shorter to type in $'loglvl after each call to the logging routine &add_log.

There is one more variable worth knowing about: $main'FILTER, which is the suitable X-Filter line that should be appended in all 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.

Rule Environment

When we speak about altering the environment, we refer to the one set up via the configuration file, whose values end-up in the cf package. Well, some of those variables are copied in the env package before filtering of a message starts (under the control of the @env'Env array).

All rules should then refer to the version in the env package, and not in the cf package, to see alterations. Global changes are made by affecting directly to the variable in the env package, while local changes are requested by calling the &env'local routine.

For instance, the cf'umask value is copied as env'umask because umask is held in @env'Env. Global changes are made by setting that copy directly, while local changes may be made with:

	&env'local('umask', 0722);

Variables requiring a side effect when their value is changed (such as the umask variable, which requires a system call to let the kernel see the change) may specify it by accessing the %env'Spec array, the key being the name of the variable requiring a side effect, the value being interpreted as a bit of perl code ran once the original value is restored. For instance, we say somewhere (in &env'init):

	package env;
	$Spec{'umask'} = 'umask($umask)';

Internally, the &analyze_mail routine calls &env'setup before starting its processing to initialize the env package, and &env'cleanup at the end before returning. Before running the actions specified on a rule match, &apply_rules calls &env'restore to ensure a coherent view of the environment while running the actions for that particular rule.

Altering Control Flow

You may also want to directly alter the $wmode and $cont variables, but then you'll have to do your own logging if you want some. Or you may call low-level routines &main'do_reject, &main'do_restart and &main'do_abort to perform the corresponding operation (with logging).

Remember that the _SEEN_ state is special and directly handled at the filter level, and the filter begins in the INITIAL state. The default action is to continue with the current rule, which is why there is no routine to perform this task.

The preferred way is to invoke the mailhook interface functions, &mailhook'begin, &mailhook'reject, etc..., and that will work even if you redefine those functions yourself. Besides, that's the only interface which is likely not to be changed by new versions.

General Purpose Routines

&header'format(rfc822-field)

Return a formatted RFC822 field to fit in 78 columns, with proper continuations introduced by eight spaces.

&header'normalize(rfc822-header-name)

Normalize case in RFC822 header and return the new header name with every first letter uppercased.

&header'reset

This is part of an RFC822 header validation, mainly used when splitting a digest. This resets the recognition automaton (see &header'valid).

&header'valid(line)

Returns a boolean status, indicating if all the lines given so far to this function since the last &header'reset are part of a valid RFC822 header. The function understands the first From line which is part of UNIX mails. At any time, the variable $header'maybe may be checked to see if so far we have found at least one essential mail header field.

&main'acs_rqst(file)

Perform a .lock locking on the file, returning 0 on success and -1 on failure. If an old lock was present, it is removed (time limit set to one hour). Use &main'free_file to release the lock.

&main'add_log(string)

Add the string to the logfile. The usual idiom is to postfix that call with the if $'loglvl > value, where value is the logging level you wish to have before emitting that kind of log ($'loglvl is a short form for $main'loglvl).

&main'free_file(file)

Remove a .lock on a file, obtained by &main'acs_rqst. It returns 0 if the lock was successfully removed, -1 if it was a stale lock (obtained by someone else).

&main'header_found(file)

Scan the head of a file and try to determine whether there is a mail header at the beginning or not. Return true if a header was found.

&main'history_record

Record the message ID of the current message and return 0 if the message had not been previously seen, 1 if it is a duplicate.

&main'hostname

Return the value of the hostname, lowercased, with possible domain name appended to it. The hostname is cached, since its value must initially be obtained by forking. (see also &main'myhostname)

&main'internet_info(email-address)

Parse an e-mail internet address and return a three-element array containing the host, the domain and the country part of the internet host. For instance, if the address is user@d.c.b.a, it will return (c, b, a).

&main'login_name(email-address)

Parse the e-mail internet address and return the login name.

&main'macros_subst(*line)

Perform in-place macro substitution (line passed as a type glob) using the information currently held in the %main'Header array. Do not pass *_ as a parameter, since internally macros_subst uses a local variable bearing that name to perform the substitutions and you would end up with an unmodified version. If you really want to pass *_, then you must use the returned value from macros_subst which is the substituted text, but that's less efficient than having it modified in place.

&main'makedir(pathname, mode)

Make directory, creating all the intermediate directories needed to make pathname a valid directory. Has no effect if the directory already exists. The mode parameter is optional, 0700 is used (octal number) if not specified.

&main'myhostname

Returns the hostname of the current machine, without any domain name. The hostname is cached, since its value must initially be obtained by forking.

&main'run_command(filter-command)

Execute the single filter command specified and return the continuation status, which should normally be affected to the $cont variable. You will need this routine when trying to implement commands which encapsulate other commands, like ONCE or SELECT.

&main'seconds_in_period(period)

Return the number of seconds in the period specified. See section Specifying A Period to get valid period strings.

&main'shell_command(program, input, feedback)

Run a shell command and return a failure status (0 for OK). The input parameter may be one of the following constants (defined in the main package): $NO_INPUT to close standard input, $BODY_INPUT to pipe the body of the current message, $MAIL_INPUT to pipe the whole mail as-is, $MAIL_INPUT_BINARY to pipe the whole mail after having removed any content transfer-encoding and $HEADER_INPUT to pipe the message header. The feedback parameter may be one of $FEEDBACK or $NO_FEEDBACK depending whether or not you wish to use the standard output to alter the corresponding part of the message. If no feedback is wanted, the output of the command is mailed back to the user. The $FEEDBACK_ENCODING is handled like $FEEDBACK but will tell mailagent to look at the best suitable body encoding when the input is the whole message.

&main'parse_address(rfc822-address)

Parse an RFC822 e-mail address and return a two-elements array containing the internet address and the comment part of that address.

&main'xeqte(filter-actions)

Execute a series of actions separated by the ';' character, calling run_command to actually perform the job. Return the continuation status. Note that $FT_ABORT will never 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 could say xeqte is the equivalent of the eval function in perl, since it interprets a little filter script and returns control to the caller once finished, and ABORT is perl's die.

You may also use the three functions from the extern package which manipulate persistent variables (already documented in the section dealing with variables) as well as the user-defined macro routines.

Example

Here is a small example. We want to write a command to bounce back a mail message to the original sender, the way sendmail does, with some leading text to explain what happened. The command would have the following syntax:

SENDBACK reason

sub sendback {
	local($cmd_line) = @_;
	local($reason) = join(' ', @ARGV[1..$#ARGV]);
	unless (open(MAILER, "|/usr/lib/sendmail -odq -t")) {
		&'add_log("ERROR cannot run sendmail to send message")
			if $'loglvl;
		return 1;
	}
	print MAILER <<EOF;
From: mailagent
To: $header{'Sender'}
Subject: Returned mail: Mailagent failure
$main'FILTER
  --- Transcript Of Session
$reason
  --- Unsent Message Follows
$header{'All'}
EOF
	close MAILER;
	$ever_saved = 1;	# Don't want it in mailbox
	$? == 0 ? 0 : 1;	# Failure status
}

SENDBACK  ~/mail/cmds/sendback.pl  sendback  yes  no

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

Conclusion

Note that you may also use the information presented here inside the perl escape scripts. Via the require operator, it is easy to get the new command implementation into your script and perform the same task. You will maybe need to set up @ARGV by yourself if you rely on that feature in your command implementation.

Command extension can also be viewed as a way to reuse some other perl code, the mailagent providing a fixed and reliable frame and the external program providing the service. One immediate extension would be mailing list handling, using this mechanism to interface with some mailing list management software written in perl.

Overview

• Think about the command from a security point of view. Here, the command we want to implement is a potentially dangerous one since it can give access to any file on the machine the individual running mailagent has access to. So we want to restrict that command to a limited number of trusted people, who will be granted the power to run this command. More on this later.
• Choose whether you want to implement the command in perl or in another programming language. If you do the latter, your command will be known as a shell command (i.e. a command runnable directly from a shell), while in the former case, you have the choice of making it appear as a shell command, or have it hooked to the mailagent in which case it is known as a perl command. In that last case, your command will be dynamically loaded into mailagent with all the advantages that brings you. Here, we are going to write our command as a shell script.
• Write the command itself. That's the most difficult part in this scheme. Later on, we will see a straightforward implementation of the send command.
• Edit the comserver file (defined in your ~/.mailagent) to record your new command. Then make sure this file is tightly protected. You must own it, and be the only one allowed to modify it.
• Additionally, you may want to hide some of the arguments in the session transcript (more on this later), allow the command to take a flow of data as its standard input, assign a path to the command, etc... All those parameters take place in your comserver file.
• Start using the command... which of course is the nicest part in this scheme!

In the following sections, we'll learn about the syntax of the comserver file, what powers are, how the session transcript is built, what the command environment is, etc...

Builtin Commands Overview

The server maintains the notion of powers. One user may have more than one power at a time, each power granting only a limited access to some sensitive area. A few powers are hardwired in the server, but the user may create new ones when necessary. Those powers are software-enforced, meaning the command must check for itself whether is has the necessary power(s) to perform correctly.

Powers are protected by a password and a clearance file. Having the good password is not enough, you have to be cleared in order to (ab)use it. The clearance file is a list of e-mail address patterns, using the shell metacharacters scheme, someone being cleared if and only if his e-mail address matches at least one of the patterns from the clearance file. The more use you will make of metacharacters, the weaker this clearance scheme will be, so be careful.

Your commands and the output resulting from their execution is normally mailed back to you as a session transcript. For security reasons, passwords are hidden from the command line. Likewise, failure to get a power will not indicate whether you lacked authorization or whether your password was bad.

A user with the system power is allowed to create new powers, delete other powers, change power passwords, and list, remove or change power clearances. This is somehow an important power which should be detained by a small number of users with very strict clearance (no meta-characters in the address, if possible). A good password should also protect that power.

However, a user with the system power is not allowed to directly get another power without specifying its password and being allowed to do so by the associated clearance file. But it would be possible to achieve that indirectly by removing the power and creating a new one bearing the same name. In order to control people with the system power and also for some tricky situation, there is another more god-like power: the root power.

A user with the root power can do virtually anything, since it instantly grants that individual all the powers available on the server (but security). The only limitation is that root cannot remove the root power alone. One needs to specify the security password (another hardwired power) in order to proceed. Needless to say, only one individual should have both root and security clearance, and only one individual should know the security password and be listed in the clearance file. The system power cannot harm any of those two powers. Eventually, more than one user could have the root power, but do not grant that lightly...

Getting the root power is necessary when system has messed with the system configuration in an hopeless way, or when a long atomic sequence of commands has to be issued: root is not subject to the maximum number of command that can be issued in one single message.

In case you think this mailagent feature is dangerous for your account, do not create the root and security powers, and do not write any sensitive commands.

Builtin Commands Definition

addauth power password

Add users to clearance file for power. If the power password is given, no special power is needed, otherwise the system power is required. For root or security powers, the corresponding power is required, or the password must be specified. The command reads the standard input up to the EOF marker to get the new users.

approve password command

Records the password in the command environment, then executes the command. If a power is required and not yet obtained, the command will look for the password in the environment and try to get the relevant power using that password. Hence, approved command (with proper password) will transparently execute without the hassle of requesting the power, issuing the command and then releasing the power. It is up to the command to perform the approve password test by looking at the approve variable in the command environment (see below). Since clearance checks (such as those performed when requesting a power) are not performed, no sensitive command should ever deal with the approve construct.

delpower power password [security]

Delete a power from the system, and its associated clearance list. The system power is required to delete most powers except root and security. The security power may only be deleted by itself and the root power may only be deleted when the security password is also specified.

getauth power password

Get current clearance file for a given power. No special power required if the password is given or the power is already detained. Otherwise, the system power is needed for all powers but root or security where the corresponding power is mandatory.

newpower power password [alias]

Add a new power to the system. The command then reads the standard mail input until the EOF marker to get the power clearance list. The system power is required to create a new power, unless it's root or security: The security power is required to create root and the root power is required to create security.

passwd power old new

Change power password. It does not matter if you already hold the corresponding power, you must give the proper old password. See also the password command.

password power new

Change power password. The corresponding power is required, or you have to get the system power. To change the root or security passwords, you need the corresponding power.

power name password

Ask for a new power. Of course, root does not need to request for any other power but security, less give any password. This command is not honored when the server is not in trusted mode, unbeknownst to the user: the error message in the transcript file is no different from the one obtained with an invalid password.

powers regexp

List all the powers matching the perl regular expression, along with their respective clearance file. The system power is required to get the list. The root or security power are required to get access to the root or security information, respectively. If no arguments are given, all the powers are listed.

release power

Get rid of some power.

remauth power password

Remove users from clearance file, getting the list by reading the standard mail input until the EOF marker. This command does not require any special power if the proper password is given or if the power is already detained. Otherwise, the system power is needed. For root and security clearance, the corresponding power is needed as well.

set variable value

Set the variable to the corresponding value. Useful to alter internal variables like the EOF marker value, or change some command environment. The user may define his own variables for his commands. For flag-type variable, a value of on, yes or true sets the variable to 1, any other string sets it to 0 (false). Used all by itself as set, the list of all the defined variables along with their respective values is returned.

setauth power password

Replace power clearance file with one obtained from standard mail input up to the EOF mark. The system power is needed unless you specify the proper password or the power is already yours. As usual, root or security clearances can only be changed when the power is detained.

user [e-mail [command]]

Execute command by assuming the e-mail identity specified. Powers are lost while executing the command. The e-mail identity may be checked by the command itself, which may impose further restrictions on the execution, like getting user-defined powers. Note that this command only modifies the global environment, and that it's up to the command implementation to make use of that information. If no command is specified, the new identity is assumed until changed by another user command and all the powers currently held by the user are released. If no e-mail address is given, the original user ID is restored.

Command Environment

Whenever mailagent fires a server command, it sets up an environment for that command: if it is a perl-type command, then a set of perl variables are set before loading the command; if it is a shell-type command, some environment variables are initialized and file descriptor #3 is set up to point directly to the mailagent session transcript.

A shell-type command is forked, whilst a perl-type command is loaded directly in mailagent within the cmdenv package. This operates much like the PERL filtering command, only the target package differs and a distinct set of variables is preset.

Some commands collect additional data up to an end-of-file marker (by default the string EOF on a line by itself) and those data are fed to shell commands via stdin and to perl commands via the @buffer variable set up in the environment package named cmdenv (in which the command is loaded and run).

If you define your own variables (types var or flag), you may use the builtin set command to modify their values. Note that no default value can be provided when defining your variable. A suitable default value must be set within commands making use of them, with the advantage that different default values may be used by different commands.

The following environment variables are defined. Most are read-only, unless notified otherwise, in which case the builtin set command may be used on them.

approve

The approve password for approve commands, empty if not within a builtin approve construct.

auth

A flag set to true when a valid envelope was found in the mail message. When this flag is false, the server cannot be put in trusted mode.

cmd

The command line, as written in the message.

collect

Internal flag set to true while collecting input from a here-document. It is normally reset to false before calling the command.

debug

True when debug mode is activated (may be set).

disabled

A comma separated list of disabled commands, with no space between them. This is initialized when the SERVER command is invoked and the -d option is used.

eof

The current end-of-file marker for here-document commands. By default set to 'EOF' (may be changed).

errors

Number of errors so far.

jobnum

The job number assigned to the current mailagent.

log

What was logged in the transcript, with some args possibly concealed.

name

The command name.

pack

Packing mode for file sending (may be set).

path

Destination address for file sending or notification (may be set).

powers

A colon (:) separated list of powers the user currently has successfully requested and got.

requests

Number of requests processed so far.

trace

True when shell commands want to be traced in transcript (may be set).

trusted

True when server is in trust mode, where powers may be gained. This is activated by the -t option of the SERVER command, provided a valid mail envelope was found.

uid

Address of the sender of the message, where transcript is to be sent. By extension, the real user ID for the server, which is the base of the power clearance mechanism.

user

The effective user ID, originally the same as the uid, but may be changed via the user builtin command.

Session Transcript

A perl command may access the transcript via the MAILER file handle, defined in the cmdenv package, whilst a shell command may access it via its file descriptor #3.

Note that the session transcript is mailed to the sender of the message, i.e. whoever the envelope header line says it is. As far as the server is concerned, this e-mail address is used as the user ID, just like a plain login name can be thought of as the user id. For sensitive commands, authentication based on that information is really weak. A more "secure" authentication is provided by the server powers, which is password-based. Unfortunately, the clear password has to be transmitted in the message itself and could be eavesdropped.

Recording New Commands and Variables

Each row has the following fields:

name type hide collect-data path extra

name

is the name of the command or variable as recognized by the server.

type

is one of perl, shell, var, flag, help or end.

hide

indicates which arguments in the command are to be hidden (the command name being argument zero) in the session transcript. Use '-' if no arguments need to be hidden. Typically, this is used to hide clear passwords in commands. If more than one argument has to be hidden, then a list of numbers separated by a ',' (comma) may be specified, with no spaces between them. For instance '2,4' would hide arguments 2 and 4 in the transcript.

collect-data

is a flag (specify as either 'y' or 'n', but you may use complete words 'yes' or 'no') indicating whether the command collects additional data in a here-document until the EOF marker. Alternatively, you may specify '-' in place of 'n'.

path

specifies the path of the command (~name substitution allowed). If not relevant (e.g. when defining a variable) or when you want to leave it blank, use '-'. If a blank path is specified for a perl or shell command, then the implementation of that command is expected to be found in servdir, as defined in ~/.mailagent. If the command name is cmd for instance, then perl command are expected there in a file named cmd of cmd.pl, whereas shell commands are expected to be found in a cmd of cmd.sh file. Note that a command is disabled if it cannot be located at the time the comserver file is parsed.

extra

is any extra parameter needed for the command. Unlike other fields, this should be left blank if not needed. Anything up to the end of the line is grabbed by this field. Perl commands should specify the name of the perl function to call to execute the command; if none is specified, the name of the command itself is called. Shell commands may use that field to supply additional options, which will be inserted right after the command name and before any other user-supplied arguments. Others should leave this alone.

Special Command Types

The simplest is the end type. This is used to specify commands which may end the server processing. By default, processing continues until the end of the file is reached or a signature delimiter '--' is found. For instance, you may wish to define the command quit and give it the end type. As soon as the server reaches that command, it aborts processing and discards the remaining of the message.

The help type is usually attached to an help command and prints help on a command basis, help for each command being stored under the helpdir variable (defined in your ~/.mailagent) in a file bearing the same name as the command itself. For example, assuming a command shoot, its help file would be expected in helpdir/shoot. If no file is found there, mailagent looks in its public library (/usr/local/lib/mailagent) for an help file. Help is provided only when the help file exists and is not zero-sized.

Creating the Root Power

First, you need to pick up a good password for the root power. Someone with the root power can do virtually anything with the server, so be careful. Let's assume you choose root-pass as a password.

Edit passwd (defined in your ~/.mailagent) and add the following line:

root:<root-pass>:

You are almost done. Now simply issue the following command:

mailagent -i -e 'SERVER -t'

From your e-mail address
From: your e-mail address
power root root-pass
password root root-pass
^D

The side effect of re-instantiating your password will be to crypt it in the passwd file, so that anybody looking at that file cannot guess your root password, hopefully.

Once you have a valid root power installed, you may create the system power by using newpower. Further powers may then be created and deleted using the system power only.

You should also create the security power and give it a different password than the root password. This is really needed only if you wish to remotely administrate the server. If you have local access and things get corrupted, it's always possible to change the root password manually by repeating this bootstrapping sequence.

Note that clearance checks are made using the envelope address of the message, which is a little harder to forge than plain header fields like Sender:. The envelope is extracted by looking at the first header line, which on Unix systems looks like:

	From envelope-address send-date

Moreover, since the session transcript is sent to that same envelope address used to authenticate the eligibility for a power, the server feature can hardly be used to retrieve confidential information held at the site where the mailagent is run since the information would be sent to one of the users cleared for that power. It is the responsibility of you, the user, to make sure this cannot happen or you could get into legal troubles.

Finally, sensitive commands should be protected by a proper power, and great care should be taken in writing the command implementation to ensure the security cannot be circumvented. But no, this mailagent feature is not believed to be dangerous for the system or site it is used on, since a determined user could implement one trivially via a five line shell script. If security is really an issue, .forward files using the piping feature should be prohibited and access to cron forbidden in order to avoid automatic mail processing (since it would be possible to have cron invoke a mailagent process -or any other program for that matter- to process the incoming mail in a comparable way).

Example

Here is my implementation of the shell command (available in the mailagent distribution under misc/shell):

#!/bin/sh
# Execute commands from stdin, as transmitted by the mailagent server.
# File descriptor #3 is a channel to the session transcript.
# Make sure we have the shell power.
# Don't even allow the root power to bypass that for security reasons.
case ":$powers:" in
*:shell:*) ;;
*)
	echo "Permission denied." >&3
	exit 1
	;;
esac
# Perhaps a shell was defined... Otherwise, use /bin/sh
case "$shell" in
'') shell='/bin/sh';;
esac
# Normally, a shell command has its output included in the transcript only in
# case of error or when the user requests the trace. Here however, we need to
# see what happened, so everything is redirected to the session transcript.
exec $shell -x >&3 2>&3

Note how we make access to the $powers and $shell environment variable. That last one is user-defined to allow dynamic set-up of a shell.

Assuming we store that command under servdir/shell.sh (don't forget to add the execution bit on the file...), here is how we declare it and its variable in the comserver file.

shell	shell	-	y	-
shell	var	-	-	-

Now, assuming you have already created a system power and protected it with a password (let's assume sys-pass for the purpose of this example), you need to create the shell power. Although you could do it manually (like when you handcrafted the root power), it's better to use the SERVER interface since it ensures consistency.

In order to create the shell power required to use the newly created shell command, you need to add the following rule to your rule file:

Subject: Server		{ SAVE server; SERVER -t };

Subject: Server
power system sys-pass
newpower shell shell-pass
ram@acri.fr
EOF

You will receive a session transcript along these lines:

    ---- Mailagent session transcript for ram@acri.fr ----
----> power system ********
OK.
====> newpower shell ********
OK.
====> --
End of processing (.signature)
    ---- End of mailagent session transcript ----

Now let's use this new command... Send yourself the following mail:

Subject: Server
set shell /bin/ksh
set eof END
shell
ls -l /etc/passwd
END
power shell shell-pass
shell
ls -l /etc/passwd
END

    ---- Mailagent session transcript for ram@acri.fr ----
----> set shell /bin/ksh
OK.
----> set eof END
OK.
----> shell
Permission denied.
Command returned a non-zero status (1).
FAILED.
----> power shell ********
OK.
====> shell
+ ls -l /etc/passwd
-rw-r--r--   1 root     system       691 Oct 01 14:24 /etc/passwd
OK.
====> --
End of processing (.signature)
    ---- End of mailagent session transcript ----

Conclusion

If you implement new simple server commands and feel they are generic enough to be contributed, please send them to me and I will gladly integrate them.