---
name: "fdm.conf"
section: "5"
platform: "linux"
package: "fdm"
version: "2.2-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/fdm.conf"
---

# fdm.conf(5)

fdm configuration file

## NAME

**fdm.conf** – fdm configuration file

## DESCRIPTION

This manual page describes the [fdm(1)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md) to abort.

  Note that [fdm(1)](/fdm/1.md) 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)](/fdm/1.md) abort due to the space becoming full.

- **queue-high** *number*

  This sets the maximum number of messages [fdm(1)](/fdm/1.md) will hold simultaneously. [fdm(1)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md) 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)](/passwd/5.md) 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)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md) will not insert a ‘Received’ header into each mail.

- **no-create**

  If this option is set, [fdm(1)](/fdm/1.md) will not attempt to create maildirs and mboxes or missing elements of their paths.

- **file-umask** **user** \| *umask*

  This specifies the [umask(2)](/umask/2.md) to use when creating files. **user** means to use the umask set when [fdm(1)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md) 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)](/sendmail/8.md), see [fdm(1)](/fdm/1.md) 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)](/fdm/1.md) attempts to look it up in the *~/.netrc* file (see [ftp(1)](/ftp/1.md) for details of the file format). The port option may be either a string which will be looked up in the [services(5)](/services/5.md) 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)](/fdm/1.md) not to use the POP3 APOP command for authentication, and the **no-verify** keyword instructs [fdm(1)](/fdm/1.md) to skip SSL certificate validation for this account. The **no-uidl** keyword makes [fdm(1)](/fdm/1.md) 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)](/ssh/1.md). 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-plain**\] \[**no-login**\] \[**starttls**\] \[**insecure**\] \[**oauthbearer**\] \[**xoauth2**\]

- **imap** **server** *host*

  \[**port** *port*\] \[*userpass*\] \[**folders**\] { *name* *...* } \[*only*\]

- **imaps** **server** *host*

  \[**port** *port*\] \[*userpass*\] \[*folders*\] \[*only*\] \[**no-verify**\] \[**no-cram-md5**\] \[**no-plain**\] \[**no-login**\] \[**insecure**\] \[**oauthbearer**\] \[**xoauth2**\] 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**, **no-plain** and **no-login** disable the given authentication method. The default is to use CRAM-MD5 if it is available, then PLAIN, and LOGIN otherwise.

    **starttls** attempts to use *STARTTLS* after connection.

    **insecure** allows the use of insecure protocols, which currently includes SSLv2, SSLv3 and TLS1.0.

    **oauthbearer** attempts to use OAuth 2.0 bearer token as authentication method.

- **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)](/fdm/1.md) to fetch mail from the maildir or maildirs specified. This allows [fdm(1)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md) 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)](/fdm/1.md), 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.

- lines

  The total number of lines in the message.

- body\_lines

  The number of lines in the body.

- header\_lines

  The number of lines in the header.

- message\_id

  The message id from the mail's header (if present).

- 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)](/fdm/1.md) can maintain a cache file with a set of user-defined strings. In order to use caches, [fdm(1)](/fdm/1.md) 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)](/fdm/1.md) will add ‘.gz’ to *path* and attempt to write mail using [gzip(1)](/gzip/1.md) 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.

- **lmtp** **server** *path* \| *host*

  \[**port** *port*\] \[**from** *from*\] \[**to** *to*\] Connect to an LMTP server and attempt to store the mail there. If a UNIX socket is to be used, *path* must be the absolute pathname.

  *port* defaults to 24. 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)](/fnmatch/3.md) 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)](/fdm/1.md) 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)](/fnmatch/3.md) 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)](/fdm/1.md) 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)](/fdm/1.md), [re\_format(7)](/re_format/7.md)

## AUTHORS

Nicholas Marriott ⟨*nicholas.marriott@gmail.com*⟩