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 32 megabytes and the maximum 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.
Note that fdm(1) may have a number of messages queued (up to the queue-high setting, doubled for rewrite, per account), so this setting and the queue-high option should be set after consideration of the space available in the temporary folder and the implications should fdm(1) abort due to the space becoming full.
- queue-high number
- This sets the maximum number of messages fdm(1) will hold simultaneously. fdm(1) will attempt to process previously queued messages as the next is being fetched. Once this limit is reached, no further messages wil be fetched until the number of messages held drops to the queue-low value.
- queue-low number
- This is the length to which the message queue must drop before fetching continues after the queue-high limit has been reached.
- 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.
- command-user user
- This specifies the user used to run exec and pipe actions. By default it is the user who invoked fdm.
- 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.
- lookup-order location ...
- This specifies the order in which to do user lookup from left to right. Possible types are passwd to use the passwd(5) file, or courier to use Courier authlib (if support is compiled).
- 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
- 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.
- no-received
- If this option is present, fdm(1) will not insert a `Received' header into each mail.
- no-create
- If this option is set, fdm(1) will not attempt to create maildirs and mboxes or missing elements of their paths.
- file-umask user | umask
- This specifies the umask(2) to use when creating files. user means to use the umask set when fdm(1) is started, or umask may be specified as a three-digit octal number. The default is 077.
- file-group user | group
- This option allows the default group ownership of files and directories created by fdm(1) to be specified. group may be a group name string or a numeric gid. If user is used, or this option does not appear in the configuration file, fdm(1) does not attempt to set the group of new files and directories.
- timeout time
- This controls the maximum time to wait for a server to send data before closing a connection. The default is 900 seconds.
- verify-certificates
- Instructs fdm(1) to verify SSL certificates for all SSL connections.
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"
The ifdef ifndef and endif keywords may be used to conditionally parse a section of the configuration file depending on whether or not the macro given exists or does not exist. ifdef and ifndef blocks may be nested.
SHELL COMMANDS
The result of a shell command may be used at any point a string or number is expected by wrapping it in $() or %(). If the former is used, the command result is used as a string; if the latter, it is converted to an integer. Shell commands are executed when the configuration file is parsed.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 ]
- user user | users { 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 ] [only ] [no-apop ] [no-uidl ]
- pop3s server host [port port ] [userpass ] [only ] [no-apop ] [no-uidl ] [no-verify ] [no-tls1 ]
- These statements define a POP3 or POP3S account.
The
userpass
element has the following form:
- [user user ] [pass pass ]
- The
host
user
and
pass
arguments must be strings.
If the user or pass is not provided,
fdm(1)
attempts to look it up in the
~/.netrc
file (see
ftp(1)
for details of the file format).
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 (110 for POP3, 995 for POP3S) is used.
The only option takes the form:
- [new-only | old-only ] cache path
new-only
- fetches only mail not previously fetched, and
old-only
is the inverse: it fetches only mail that has been fetched before.
The cache file is used to save the state of the POP3 mailbox.
The
no-apop
flag forces
fdm(1)
not to use the POP3 APOP command for authentication, and the
no-verify
keyword instructs
fdm(1)
to skip SSL certificate validation for this account.
The
no-uidl
keyword makes
fdm(1)
not use the UIDL command to retrieve mails.
This is mainly useful for broken POP3 servers.
The no-tls1 keyword instructs fdm(1) not to use the TLSv1 protocol with SSL connections. Some broken servers will fail in the handshake phase if the tls1 flag is not unset.
- folder name | folders { name ... }
Options no-cram-md5 and no-login disable the given authentication method. The default is to use CRAM-MD5 if it is available, or LOGIN otherwise.
Mail fetched from a maildir is tagged with a maildir tag containing the basename of the mail file.
Mail fetched from a mbox is tagged with a mbox tag containing the basename of the mbox file.
TAGGING
As mail is processed by fdm(1), it is tagged with a number of name/value pairs. Some tags are added automatically, and mail may also be tagged explicitly by the user using the tag action. Tags may be inserted in most strings in a similar manner to macros, except tags are processed at runtime rather than as the configuration file is parsed. A tag's value is inserted by wrapping its name in %[], for example:- "abc%[account]def"
- "%[hour]:%[minute]:%[second]"
The default tags also have a single-letter shorthand. Including a nonexistent tag in a string is equivalent to including a tag with an empty value, so "abc%[nonexistent]def" will be translated to "abcdef".
The automatically added tags are:
- account (%a)
- The name of the account from which the mail was fetched.
- home (%h)
- The delivery user's home directory.
- uid (%n)
-
The delivery user's uid.
- action (%t)
- The name of the last action executed for this mail.
- user (%u)
- The delivery user's username.
- hour (%H)
- The current hour (00-23).
- minute (%M)
- The current minute (00-59).
- second (%S)
- The current second (00-59).
- day (%d)
-
The current day of the month (01-31).
- month (%m)
- The current month (01-12).
- year (%y)
- The current year.
- year2
- The current year as two digits.
- dayofweek (%W)
- The current day of the week (0-6, Sunday is 0).
- dayofyear (%Y)
- The current day of the year (001-366).
- quarter (%Q)
- The current quarter (1-4).
- rfc822date
- The current date in RFC822 format.
- mail_hour
- The hour from the mail's date header, if it exists and is valid, otherwise the current time.
- mail_minute
- The minute from the mail's date header.
- mail_second
- The second from the mail's date header.
- mail_day
- The day from the mail's date header.
- mail_month
- The month from the mail's date header.
- mail_year
- The year from the mail's date header.
- mail_year2
- The same as two digits.
- mail_dayofweek
- The day of the week from the mail's date header.
- mail_dayofyear
- The day of the year from the mail's date header.
- mail_quarter
- The quarter (1-4) from the mail's date header.
- mail_rfc822date
- The mail's date in RFC822 format.
- hostname
- The local hostname.
In addition, the shorthand %% is replaced with a literal %, and %0 to %9 are replaced with the result of any bracket expressions in the last regexp.
CACHES
fdm(1) can maintain a cache file with a set of user-defined strings. In order to use caches, fdm(1) must have been compiled with them enabled. Caches are declared with the cache keyword:- cache path [expire age ]
Caches must be declared before they are used. Items are added to caches using the add-to-cache action, removed using the remove-from-cache action, and searched for using the in-cache condition; see below for information on these.
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
- action name [users ] { action ... }
The possible values for action are listed below. If multiple actions are specified they are executed once in the order specified, for each user.
- drop
- Discard the mail.
- keep
- Keep the mail, do not remove it from the account.
- tag string [value value ]
- This tags mail with string and optionally value which may be matched using the tagged or string conditions.
Mail delivered to a maildir is tagged with a mail_file tag containing the full path of the mail file.
Mail delivered to an mbox is tagged with a mbox_file tag containing the path of the mbox.
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 the following basic form:- match condition [and | or condition ... ] [users ] actions [continue ]
- all
- Matches all mail.
- matched
- Matches only mail that has matched a previous rule and been passed on with continue
- unmatched
- The opposite of matched matches only mails which have matched no previous rules.
- account name | accounts { name ... }
- Matches only mail fetched from the named account or accounts. The account names may include shell glob wildcards to match multiple accounts, as with the -a and -x command line options.
Multiple conditions may be chained together using the and or or keywords. The conditions are tested from left to right. Any condition may be prefixed by the not keyword to invert it.
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.
The actions list specifies the actions to perform when the rule matches a mail. It is either of a similar form:
- action name | actions { name ... }
- action action
- action { action ... }
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 ...
- }
FILES
- ~/.fdm.conf
- default configuration file
- /etc/fdm.conf
- default system-wide configuration file
- ~/.fdm.lock
- default lock file
- /var/db/fdm.lock
- lock file for root user
AUTHORS
An Nicholas Marriott Aq nicm@users.sourceforge.net