table of contents
FDM.CONF(5) | File Formats Manual | 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 thecontinue
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 theset
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 thequeue-high
setting, doubled for rewrite, per account), so this setting and thequeue-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
andpipe
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 theinclude
command:
include
path
MACROS¶
Macros may be defined using the following syntax:- $name
=
string - %name
=
number
"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¶
Theaccount
command is used to instruct
fdm(1) to fetch mail from an account. The syntax
is:
account
name [users] [] type [disabled
args] []keep
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
passonly] [] [no-apop
]no-uidl
pop3s
server
host [] [port
portuserpass] [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
- []
new-only
|old-only
cache
path
new-only
fetches only mail not previously fetched, andold-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. Theno-apop
flag forces fdm(1) not to use the POP3 APOP command for authentication, and theno-verify
keyword instructs fdm(1) to skip SSL certificate validation for this account. Theno-uidl
keyword makes fdm(1) not use the UIDL command to retrieve mails. This is mainly useful for broken POP3 servers. Theno-tls1
keyword instructs fdm(1) not to use the TLSv1 protocol with SSL connections. Some broken servers will fail in the handshake phase if thetls1
flag is not unset. - [
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
portuserpass] [] [folder
nameonly] [] [no-cram-md5
]no-login
imap
server
host [] [port
portuserpass] []folders
{
name ...}
[only]imaps
server
host [] [port
portuserpass] [folders] [only] [] [no-verify
] [no-tls1
] [no-cram-md5
]no-login
- 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:
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
orold-only
- a cache file is not required. Optionsno-cram-md5
andno-login
disable the given authentication method. The default is to use CRAM-MD5 if it is available, or LOGIN otherwise. 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. maildir
pathmaildirs
{
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
pathmboxes
{
path ...}
- These are similar to
maildir
andmaildirs
, 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
portuserpass]group
groupcache
cachenntp
server
host [] [port
portuserpass]groups
{
group ...}
cache
cachenntps
server
host [] [port
portuserpass]group
groupcache
cache []no-tls1
nntps
server
host [] [port
portuserpass]groups
{
group ...}
cache
cache []no-tls1
- 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 thetag
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]
- 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.
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 thecache
keyword:
cache
path []expire
age
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¶
Theaction
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:
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
orstring
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 theno-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
andpipe
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
namevalue
value- Add a header name with contents value.
remove-header
nameremove-headers
{
name ...}
- Remove all occurances of headers matching the fnmatch(3) pattern name.
stdout
- Write the mail to stdout.
add-to-cache
pathkey
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
pathkey
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 thematch
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. tagged
string- Matches mails tagged with string.
- [] regexp [
case
]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
orin body
. Thecase
keyword forces the regexp to be matched case-sensitively: the default is case-insensitive matching. exec
command []user
userreturns
( return code, stdout regexp)pipe
command []user
userreturns
( return code, [] stdout regexp)case
- 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
<
numbersize
>
number- Compare the mail size with number.
string
stringto
[] regexpcase
- Match string against regexp.
age
<
timeage
>
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
pathkey
key- This condition evaluates to true if the string key is in the cache at path.
attachment
count
<
numberattachment
count
>
numberattachment
count
==
numberattachment
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
<
sizeattachment
total-size
>
size- Matches if the total size of all attachments is smaller or larger than size.
attachment
any-size
<
sizeattachment
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
stringattachment
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.
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:
Or may specify a number of actions inline (lambda actions):
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: 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 thematched
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⟩August 21, 2006 | Debian |