Provided by: fdm_1.9+git20181219-1.1build2_amd64 
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 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 will 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.
ignore-errors
If set, fdm.conf will continue to process mail if a delivery fails rather than
aborting.
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.
lock-timeout time
Sets how long fdm.conf will try a lock file before giving up.
lock-wait
If present, fdm.conf will wait for lock-file for lock-timeout rather than exiting
immediately with an error.
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 connection
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]
The name argument is a string specifying a name for the account. The optional users
argument has the following form:
user user | users { user ... }
The first two options specify a user or list of users as which the mail should be delivered
when an action is executed. If no users are specified, 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] [only] [no-apop] [no-uidl] [starttls]
[insecure]
pop3s server host [port port] [userpass] [only] [no-apop] [no-verify] [no-uidl] [insecure]
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.
starttls attempts to use STARTTLS after connection.
insecure allows the use of insecure protocols, which currently includes SSLv2, SSLv3
and TLS1.0.
pop3 pipe command [userpass] [only] [no-apop]
This account type uses the POP3 protocol piped through command, such as ssh(1). If
the command produces any output to stderr, it is logged. For POP3 over a pipe,
providing a user and password is not optional and it may not be read from ~/.netrc.
imap server host [port port] [userpass] [folder name] [only] [no-cram-md5] [no-login]
[starttls] [insecure]
imap server host [port port] [userpass] [folders] { name ... } [only]
imaps server host [port port] [userpass] [folders] [only] [no-verify] [no-cram-md5]
[no-login] [insecure]
These define an IMAP or IMAPS account. The parameters are as for a POP3 or POP3S
account, aside from the additional folders option which sets the name of the folder
or folders to use (the default is to fetch from the inbox). This has the form:
folder name | folders { name ... }
The default ports used are 143 for IMAP and 993 for IMAPS. For IMAP, the only item
consists only of one of the keywords new-only or old-only - a cache file is not
required.
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.
starttls attempts to use STARTTLS after connection.
insecure allows the use of insecure protocols, which currently includes SSLv2, SSLv3
and TLS1.0.
imap pipe command [userpass] [folders] [only]
As with pop3 pipe, this account type uses the IMAP protocol piped through command.
If the optional IMAP user and pass are supplied, they will be used if necessary, but
if one is provided, both must be – using ~/.netrc is not permitted.
Mail fetched using the IMAP protocol is tagged with a folder tag containing the
source folder name.
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.
Mail fetched from a maildir is tagged with a maildir tag containing the basename of
the mail file.
mbox path
mboxes { path ... }
These are similar to maildir and maildirs, but cause fdm(1) to fetch mail from an
mbox or set of mboxes.
Mail fetched from a mbox is tagged with a mbox tag containing the basename of the
mbox file.
nntp server host [port port] [userpass] group group cache cache
nntp server host [port port] [userpass] groups { group ... } cache cache
nntps server host [port port] [userpass] group group cache cache
nntps server host [port port] [userpass] 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. Note that the keep option is completely ignored for NNTP accounts –
all mail is kept, and the cache is always updated.
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]
The path is the location of the cache file. If the expire keyword is specified, items in the
cache are removed after they reach the age specified. age may be given unadorned in
seconds, or followed by one of the modifiers: seconds, hours, minutes, days, months or
years.
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 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. 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.
maildir path
Save the mail to the maildir specified by path. If the maildir or any part of its
path does not exist, it is created, unless the no-create option is set.
Mail delivered to a maildir is tagged with a mail_file tag containing the full path
of the mail file.
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. If the mbox or
any part of its path does not exist, it is created, unless the no-create option is
set.
Mail delivered to an mbox is tagged with a mbox_file tag containing the path of the
mbox.
exec command
Execute command.
pipe command
Pipe the mail to command. exec and pipe commands are run as the command user.
write path
Write the mail to path.
append path
Append the mail to path.
smtp server host [port port] [from from] [to to]
Connect to an SMTP server and attempt to deliver the mail to it. If from or to is
specified, they are passed to the server in the MAIL FROM or RCPT TO commands. 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"
add-header name value value
Add a header name with contents value.
remove-header name
remove-headers { name ... }
Remove all occurrences of headers matching the fnmatch(3) pattern name.
stdout Write the mail to stdout.
add-to-cache path key key
This action adds the string key to the cache specified by path. If key already
exists in the cache, it is replaced.
remove-from-cache path key key
Remove the string key from the cache path, if a matching key is present.
action name
This invokes another named action. A maximum of five actions may be called in a
sequence.
RULES
Rules are specified using the match keyword. It has the following basic form:
match condition [and | or condition ...] [users] actions [continue]
The condition argument may be one of:
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.
tagged string
Matches mails tagged with string.
[case] regexp [in headers | in body]
Specifies a regexp 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.
exec command [user user] returns (return code, stdout regexp)
pipe command [user user] returns (return code, [case] 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.
size < number
size > number
Compare the mail size with number.
string string to [case] regexp
Match string against regexp.
age < time
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.
in-cache path key key
This condition evaluates to true if the string key is in the cache at path.
attachment count < number
attachment count > number
attachment count == number
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.
attachment total-size < size
attachment total-size > size
Matches if the total size of all attachments is smaller or larger than size.
attachment any-size < size
attachment any-size > size
Compare each individual attachment on a mail to size and match if any of them are
smaller or larger.
attachment any-type string
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.
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 ... }
Or may specify a number of actions inline (lambda actions):
action action
action { action ... }
In the latter case, action follows the same form as described in the ACTIONS section. The
actions are performed from first to last 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 <nicholas.marriott@gmail.com>