FDM.CONF(5)

NAME
fdm.conf - fdm configuration file

DESCRIPTION
This manual page describes the fdm(1) configuration file. It defines accounts from which to fetch mail, a number of possible actions to take, and rules connecting a regexp with an action. The file is parsed once from top to bottom, so action and account definitions must appear before they are referenced in a rule. Rules are evaluated from first to last and (unless overridden by the continue keyword) evaluation stops at the first match.

The file has the following format:

Empty lines and lines beginning with the ‘#’ character are ignored.

Regexps and strings must be enclosed in double quotes. Special characters in regexps and strings (including passwords) must be escaped. Note that this may mean double-escaping in regexps.

Possible commands are covered in the following sections.

OPTIONS
Options are configured using the set command. It may be followed by the following options, one per command:

maximum-size size
    This is used to set the maximum size of a mail. Mails larger than this limit are dropped and, if applicable, not deleted from the server.

    The size may be specified as a plain number in bytes or with a suffix of ‘K’ for kilobytes, ‘M’ for megabytes or ‘G’ for gigabytes. The default is one gigabyte.

delete-oversized
    If this option is specified, fdm(1) attempts to delete messages which exceed maximum-size, and continue. If it is not specified, oversize messages are a fatal error and cause fdm(1) to abort.

allow-multiple
    If this option is specified, fdm(1) does not attempt to create a lock file and allows multiple instances to run simultaneously.

lock-file path
    This sets an alternative lock file. The default is ~/.fdm.lock for non-root users and /var/db/fdm.lock for root.

default-user user
    This sets the default user to change to before delivering mail, if fdm(1) is running as root and no alternative user is specified as part of the action or rule. This option may be overridden with the -u switch on the command line. A default user must be given if running as root.

lock-types type ...
    This specifies the locks to be used for mbox locking. Possible types are fcntl, flock, and dotlock. The flock and fcntl types are mutually exclusive. The default is flock.

domain domain | domains
    { domain ... } This specifies the domains to be used when looking for users with the from-headers keyword. The default is the computer's hostname.

header header | headers
    { header ... } This allows the headers to be examined when looking for users to be set. The default is to look only at the "From" and "Cc" headers. The headers are case-insensitive.

proxy url
    This instructs fdm(1) to proxy all connections through url. HTTP and SOCKS5 proxies are supported at present (URLs of the form http://host[:port] or socks://[user:pass@]host[:port]). No authentication is supported for HTTP.

unmatched-mail drop | keep
    This option controls what fdm(1) does with mail that reaches the end of the ruleset (mail that matches no rules or matches only rules with the continue keyword). drop will cause such mail to be discarded, and keep will attempt to leave the mail on the server. The default is to keep the mail and log a warning that it reached the end of the ruleset.

purge-after count
    The purge-after option makes fdm(1) attempt to purge deleted mail from the server (if supported) after count mails have been retrieved. This is useful on unreliable connections to limit the potential number of mails refetched if the connetion drops, but note that it can incur a considerable speed penalty.

INCLUDING FILES
Further configuration files may be including using the include command:

include path

The file to include is searched for first as an absolute path and then relative to the directory containing the main configuration file.

MACROS
Macros may be defined using the following syntax:

$name = string

%name = number

Macros are prefixed with $ to indicate a string value and % to indicate a numeric value. Once defined, a macro may be used in any place a string or number is expected. Macros may be embedded in strings by surrounding their name (after the $ or %) with {}s, like so:

"abc ${mymacro} %{anothermacro} def"

ACCOUNTS
The account command is used to instruct fdm(1) to fetch mail from an account. The syntax is:

account name
    [users] [disabled] type [args] [keep]

The name argument is a string specifying a name for the account. The optional users argument has the following form:

user user | users
    { user ... } | user from-headers

The first two options specify a user or list of users as which the mail should be delivered when an action is executed. If user from-headers is specified, fdm(1) attempts to find the users from the mail headers, using the values of the headers and domains options. If no headers are specified, or fdm(1) fails to find any valid users in the headers, the default user (set with set default-user) is used. Users specified as part of the account definition may be overridden by similar arguments to action definitions or on match rules. If fdm(1) is run as non-root, it will still execute any actions once for each user, but will be unable to change to that user so the action will be executed multiple times as the current user.

The disabled keyword instructs fdm(1) to ignore this account unless it is explicitly enabled with a -a option on the command line. If the keep keyword is specified, all mail collected from this account is kept (not deleted) even if it matches a drop action.

Supported account types and arguments are:

stdin
    This account type reads mail from stdin, if it is connected to a pipe. This may be used to deliver mail from sendmail(8), see fdm(1) for details.

pop3 server host
    [port port] user user pass pass

pop3s server host
    [port port] user user pass pass These statements define a POP3 or POP3S account. The host, user and pass arguments must be strings. The port option may be either a string which will be looked up in the services(5) database, or a number. If it is omitted, the default port (143 for POP3, 993 for POP3S) is used.

imap server host
    [port port] user user pass pass [folder name]

imaps server host
    [port port] user user pass pass [folder name] These define an IMAP or IMAPS account. The parameters are as for a POP3 or POP3 account, aside from the additional folder option which allows the folder name to be specified (the default is to fetch from the inbox).

imap pipe command
    [user user pass pass] This account type uses the IMAP protocol piped through a command, such as ssh(1). If the optional IMAP user and pass are supplied, they will be used if necessary. If the command produces any output to stderr, it is logged.

maildir path

maildirs
    { path ... } These account types instruct fdm(1) to fetch mail from the maildir or maildirs specified. This allows fdm(1) to be used to filter mail, fetching from a maildir and deleting (dropping) unwanted mail, or delivering mail to another maildir or to an mbox.

nntp server host
    [port port] group group cache cache

nntp server host
    [port port] groups { group ... } cache cache An NNTP account. Articles are fetched from the specified group or groups and delivered. The index and message-id of the last article fetched in each group is saved in the specified cache file. When fdm(1) is run again, fetching begins at the cached article.

ACTIONS
The action command is used to define actions. These may be specified by name in rules (see below) to perform some action on a mail. The syntax is:

action name [users]
    action

The name is a string defining a name for the action. The users argument has the same form as for an account definition. An action's user setting may be overridden in the matching rule.

The possible values for action are listed below. In actions for which a command or path is specified, the following substitutions are made before it is used: %a is replaced by the account name, %h by the current user's home directory, %t by the name of the current action, %u by the current user's login name, %n by the UID and %H by the current hour (00-23), %M minute (00-59), %S second (00-59), %d day of the month (00-31), %m month (01-12), %y year, %W day of the week (0-6, Sunday is 0), %Y day of the year (000-365), %Q quarter (1-4) and %% with a literal %. In addition, %s is replaced by a string specific to the type of account and %0 to %9 with the contents of any subexpressions from the regexp executed as part of the last regexp condition. When fetching from a maildir, this is the basename of the maildir path. With pop3 or imap, it is the hostname of the server, as specified in the account definition.

drop
    Discard the mail.

keep
    Keep the mail, do not remove it from the account.

maildir path
    Save the mail to the maildir specified by path.

mbox path [compress]
    Append the mail to the mbox at path. If compress is specified, fdm(1) will add ‘.gz’ to path and attempt to write mail using gzip(1) compression.

pipe command
    Pipe the entire mail to command.

write path
    Write the mail to path.

append path
    Append the mail to path.

smtp server host
    [port port] [to to] Connect to an SMTP server and attempt to deliver the mail to it. If to is specified, it is passed to the server in the RCPT TO command. If not, the current user and host names are used.

rewrite command
    Pipe the entire mail through command to generate a new mail and use that mail for any following actions or rules. An example of the rewrite action is:

        action "cat" pipe "cat"
        action "rewrite" rewrite "sed 's/bob/fred/g'"
        # this rule will rewrite the message
        match all action "rewrite" continue
        # this rule will cat the rewritten message
        match all action "cat"

RULES
Rules are specified using the match keyword. It has one of the following basic forms:

match
    condition [and | or condition ...] [accounts] [users] actions [continue]

match
    condition [and | or condition ...] [accounts] tag string

The condition argument may be one of:

all Matches all mail.

[not]
    matched Matches only mail that has matched a previous rule and been passed on with continue.

[not]
    unmatched The opposite of matched: matches only mails which have matched no previous rules.

[not]
    tagged string Matches mails tagged with string.

[not]
    [case] regexp [in headers | in body] Specifies a list of regexps against which each mail should be matched. The regexp matches may be restricted to either the headers or body of the message by specifying either in headers or in body. The case keyword forces the regexp to be matched case-sensitively: the default is case-insensitive matching.

[not]
    exec command [user user] returns ( return code, stdout regexp)

[not]
    pipe command [user user] returns ( return code, stdout regexp) These two conditions execute a command and test its return value and output. The return code argument is the numeric return code expected and stdout regexp is a regexp to be tested against the output of the command to stdout. Either of these two arguments may be omitted: if both are specified, both must match for the condition to be true. The pipe version will pipe the mail to the command's stdin when executing it. If a user is specified, fdm(1) will change to that user before executing the command, otherwise the current user (or root if started as root) is used.

[not]
    size < number

[not]
    size > number Compare the mail size with number.

[not]
    string string to regexp Match string against regexp. If any of %0 to %9 appear in the string, they will be replaced with the contents of any subexpressions from the regexp executed as part of the last regexp condition. If no regexp condition has yet been seen, or the mail contents has been modified by a rewrite action since the last one, this condition will log a warning and evaluate to false.

[not]
    age < time

[not]
    age > time The age condition examines the mail's date header to determine its age, and matches if the mail is older (<) or newer (>) than the time specified. The time may be given as a simple number in seconds, or followed by the word seconds, hours, minutes, days, months or years to specify a time in different units.

[not]
    attachment count < number

[not]
    attachment count > number

[not]
    attachment count == number

[not]
    attachment count!= number These conditions match if the mail possesses a number of attachments less than, greater than, equal to or not equal to number.

[not]
    attachment total-size < size

[not]
    attachment total-size > size Matches if the total size of all attachments is smaller or larger than size.

[not]
    attachment any-size < size

[not]
    attachment any-size > size Compare each individual attachment on a mail to size and match if any of them are smaller or larger.

[not]
    attachment any-type string

[not]
    attachment any-name string Match true if any of a mail's attachments possesses a MIME type or filename that matches string. fnmatch(3) wildcards may be used.

Aside from the all condition, multiple conditions may be chained together using the and or or keywords. The conditions are tested from left to right. The not keyword may be specified to invert the sense of a condition.

The first form of the command specifies a number of actions to take when a mail matches the rule. The second form tags the mail with string, which may be matched using the tagged condition in later rules. A mail may be tagged with any number of different strings by different rules. Rules which apply a tag do not count as a match for the purposes of the matched or unmatched conditions.

The optional users argument to the first form has the same syntax as for an action definition. A rule's user list overrides any users given as part of the actions.

Both the accounts and actions parts consist either of a single name or a list of names enclosed in braces:

account name | accounts
    { name ... }

action name | actions
    { name ... }

The accounts list is used to limit rules to matching mail within a set of accounts, and the actions list specifies the actions to perform when the rule matches a mail. The account names may include shell glob wildcards to match multiple accounts, as with the -a and -x command line options. The actions are performed from left to right in the order they are specified in the rule definition.

If the continue keyword is present, evaluation will not stop if this rule is matched. Instead, fdm(1) will continue to match further rules after performing any actions for this rule.

NESTED RULES
Rules may be nested by specifying further rules in braces:

match
    condition [and | or condition ...] {

match ...

}

The inner rules will not be evaluated unless the outer one matches. Rules may be multiply nested. Note that the outer rule does not count as a match for the purposes of the matched and unmatched conditions.

FILES
~/.fdm.conf
    default fdm.conf configuration file
/etc/fdm.conf
    default system-wide configuration file
~/.fdm.lock
    default lock file
/var/db/fdm.lock
    lock file for root user

SEE ALSO
fdm(1), re_format(7)

AUTHORS
Nicholas Marriott <nicm@users.sourceforge.net>