FDM.CONF(5)

💖 NAME 💖

okay so this is fdm.conf(5) — the manual page for the fdm configuration file. That's it, that's the whole name section, but bestie you're gonna want to keep reading because this file is literally where all the magic happens ✨

---

🌸 DESCRIPTION 🌸

So here's the tea: this page describes the fdm(1) configuration file. That file is the blueprint for everything — it defines accounts you fetch mail from, a whole menu of actions you can take on that mail, and rules that glue a regexp to an action. it's giving "matchmaker for mail" fr fr 💅

The file gets parsed once, top to bottom. Which means: action and account definitions have to show up before any rule that references them. no showing up late to the function, bestie 🫶

Rules get evaluated first to last, and — unless the continue keyword overrides it — evaluation stops at the first match. periodt.

The file format is:

• Empty lines? ignored. 💀
• Lines starting with the # character? Also ignored.
• Regexps and strings must be enclosed in double quotes "".
• Special characters in regexps and strings (yes, including passwords 👀) must be escaped.
• Heads up: that can mean you end up double-escaping inside regexps. it's giving stressful but we move 🎀

Possible commands are covered in the following sections. let's gooo 🌈

---

✨ OPTIONS ✨

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

• maximum-size size — sets the max size of a mail. Mails bigger than this limit get dropped, and if applicable they are not deleted from the server. The size can be a plain number in bytes, or you can tack on a suffix: K for kilobytes, M for megabytes, G for gigabytes. Default is 32 megabytes, and the max is one gigabyte. 👑
• delete-oversized — if you set this, fdm(1) tries to delete messages that exceed maximum-size and then continue on its merry way. If you don't set it, oversize messages are a fatal error and fdm(1) will abort. 😭

ngl this one needs a moment of reflection: fdm(1) may have a bunch of messages queued (up to the queue-high setting, and that's doubled for rewrite, per account). So set this and queue-high only after you've thought about how much space is in your temporary folder — and about what happens if fdm(1) aborts because that space fills up. 🫠

• queue-high number — this sets the max number of messages fdm(1) will hold at once. fdm(1) will try to process previously queued messages while the next one is being fetched. Once you hit this limit, no further messages get fetched until the number of held messages drops down to the queue-low value.
• queue-low number — the length the message queue has to drop to before fetching resumes, after the queue-high limit has been reached.
• ignore-errors — if set, fdm.conf keeps processing mail even when a delivery fails, instead of aborting. resilience era 💪
• allow-multiple — if specified, fdm(1) doesn't try to create a lock file, and allows multiple instances to run simultaneously. chaos permitted 🦋
• lock-file path — sets an alternative lock file. Default is ~/.fdm.lock for non-root users and /var/db/fdm.lock for root.
• lock-timeout time — how long fdm.conf will try for a lock file before giving up.
• lock-wait — if present, fdm.conf will wait for lock-file for lock-timeout, instead of exiting immediately with an error. patience is a virtue bestie 🧚
• command-user user — specifies the user used to run exec and pipe actions. By default it's the user who invoked fdm.
• default-user user — sets the default user to change to before delivering mail, if fdm(1) is running as root and no alternative user was specified as part of the action or rule. This can be overridden with the -u switch on the command line. A default user must be given if you're running as root. no skipping this one 🚨
• lookup-order location ... — specifies the order to do user lookup in, left to right. Possible types are passwd (use the passwd(5) file) or courier (use Courier authlib, if support is compiled).
• lock-types type ... — specifies the locks used for mbox locking. Possible types are fcntl, flock, and dotlock. flock and fcntl are mutually exclusive. Default is flock. pick a lane 💅
• proxy url — tells 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 — controls what fdm(1) does with mail that reaches the end of the ruleset (i.e. mail matching no rules, or matching only rules with the continue keyword). drop discards such mail; keep attempts 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 — makes fdm(1) attempt to purge deleted mail from the server (if supported) after count mails have been retrieved. Useful on unreliable connections to limit the potential number of mails refetched if the connection drops — but note it can incur a considerable speed penalty. ⚠️
• no-received — if present, fdm(1) will not insert a Received header into each mail.
• no-create — if set, fdm(1) will not attempt to create maildirs and mboxes, or missing elements of their paths.
• file-umask user | umask — specifies the umask(2) to use when creating files. user means use the umask set when fdm(1) was started, or you can specify umask as a three-digit octal number. Default is 077.
• file-group user | group — lets you set the default group ownership of files and directories created by fdm(1). group can be a group name string or a numeric gid. If user is used, or this option doesn't appear in the config file, fdm(1) doesn't attempt to set the group of new files and directories.
• timeout time — controls the max time to wait for a server to send data before closing a connection. Default is 900 seconds.
• verify-certificates — tells fdm(1) to verify SSL certificates for all SSL connections. 🔐

---

🎀 INCLUDING FILES 🎀

You can pull in more config files with the include command:

include path

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

---

🦋 MACROS 🦋

Macros are your bestie for not repeating yourself. Define them like this:

$name = string

%name = number

Macros are prefixed with $ to mean a string value, and % to mean a numeric value. Once defined, a macro can be used any place a string or number is expected. You can also embed macros inside strings by wrapping their name (after the $ or %) in {}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 the given macro exists or doesn't exist. ifdef and ifndef blocks may be nested. 🪆

---

💀 SHELL COMMANDS 💀

The result of a shell command can be used at any point a string or number is expected, by wrapping it in $() or %(). Use $() and the command result is used as a string; use %() and it gets converted to an integer. Shell commands are executed when the configuration file is parsed. 🌈

---

🎀 ACCOUNTS 🎀

okay so bestie, the account command is literally how you tell fdm(1) where to go scoop up your mail from. the syntax is giving:

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

the name argument is a string, and it's just a name for the account, okay? and then there's this optional users argument that looks like:

user user | users { user ... }

those first two options say which user (or list of users) the mail should be delivered as when an action runs. if you don't say anything about users, the default user gets used — that's the one you set with set default-user. and listen: users you set inside the account definition can get overridden by similar arguments in action definitions or on match rules, so watch out 👀. also if fdm(1) is running as non-root, it'll still execute any actions once for each user, but it cannot change to that user, so the action ends up running multiple times as the current user. noted 💅

the disabled keyword tells fdm(1) to straight-up ignore this account unless you explicitly enable it with a -a option on the command line. and if you use keep, all mail collected from this account is kept (not deleted) even if it matches a drop action. slay.

supported account types and their args are:

💌 stdin

this one reads mail from stdin, if stdin is connected to a pipe. you'd use it to deliver mail from sendmail(8) — see fdm(1) for the deets.

🍓 pop3 server / pop3s server

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 define a POP3 or POP3S account. the userpass element is shaped like:

[user user] [pass pass]

host, user and pass all have to be strings. if you don't hand over the user or the pass, fdm(1) goes looking for it in the ~/.netrc file (see ftp(1) for what that file format even is). the port option can be either a string — which gets looked up in the services(5) database — or a number. leave it out and you get the default port: 110 for POP3, 995 for POP3S.

the only option takes this form:

[new-only | old-only] cache path

new-only fetches only mail that hasn't been fetched before, and old-only is the opposite vibe: it fetches only mail that has been fetched before. the cache file saves the state of the POP3 mailbox. the no-apop flag forces fdm(1) to not use the POP3 APOP command for authentication, and no-verify tells fdm(1) to skip SSL certificate validation for this account (yes, for real 🙈). no-uidl makes fdm(1) not use the UIDL command to retrieve mails — mainly useful for broken POP3 servers. starttls attempts to use STARTTLS after connection. and insecure allows the use of insecure protocols, which currently includes SSLv2, SSLv3 and TLS1.0. ⚠️

🦋 pop3 pipe

pop3 pipe command [userpass] [only] [no-apop]

this account type runs the POP3 protocol piped through command, like ssh(1). if the command produces any output to stderr, it gets logged. for POP3 over a pipe, providing a user and password is not optional, and it may not be read from ~/.netrc. no shortcuts bestie.

🌸 imap server / imaps server

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 work like a POP3 or POP3S account, except there's this extra folders option that sets the name of the folder (or folders) to use — default is to fetch from the inbox. it looks like:

folder name | folders { name ... }

default ports are 143 for IMAP and 993 for IMAPS. for IMAP, the only item is just one of the keywords new-only or old-only — no cache file needed, periodt.

the options no-cram-md5, no-plain and no-login disable the given authentication method. default is: use CRAM-MD5 if it's 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. again, be careful 💀

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

🧚 imap pipe

imap pipe command [userpass] [folders] [only]

same energy as pop3 pipe: this account type runs the IMAP protocol piped through command. if you supply the optional IMAP user and pass, they'll be used if necessary — but if one is provided, both must be, and using ~/.netrc is not permitted.

mail fetched using the IMAP protocol is tagged with a folder tag containing the source folder name. cute.

👑 maildir / maildirs

maildir path

maildirs { path ... }

these account types tell fdm(1) to fetch mail from the maildir or maildirs you specified. this is how you get fdm(1) 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 gets tagged with a maildir tag containing the basename of the mail file.

🌈 mbox / mboxes

mbox path

mboxes { path ... }

basically the same as maildir and maildirs, but they make fdm(1) fetch mail from an mbox or a whole set of mboxes instead.

mail fetched from a mbox gets tagged with a mbox tag containing the basename of the mbox file.

⭐ nntp / nntps

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 get fetched from the group (or groups) you name and then delivered. the index and message-id of the last article fetched in each group is saved in the specified cache file. when fdm(1) runs again, fetching begins at the cached article. and note: the keep option is completely ignored for NNTP accounts — all mail is kept, and the cache is always updated. like, don't even bother.

---

✨ TAGGING ✨

as mail gets processed by fdm(1), it's tagged with a bunch of name/value pairs. some tags get added automatically, and you can also tag mail explicitly using the tag action. tags can be inserted in most strings kind of like macros — except tags are processed at runtime, not while the configuration file is being parsed. big difference bestie.

a tag's value gets inserted by wrapping its name in %[], like:

abc%[account]def

%[hour]:%[minute]:%[second]

the default tags also have a single-letter shorthand. and including a tag that doesn't exist is the same as including a tag with an empty value, so "abc%[nonexistent]def" becomes "abcdef". the void, basically.

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.

on top of all that, the shorthand %% gets replaced with a literal %, and %0 to %9 get replaced with the result of any bracket expressions in the last regexp. iykyk 😌

---

💜 CACHES 💜

fdm(1) can maintain a cache file holding a set of user-defined strings. but lowkey important: to use caches, fdm(1) must have been compiled with them enabled. caches are declared with the cache keyword:

cache path [expire age]

path is the location of the cache file. if you use the expire keyword, items in the cache get removed once they reach the age you specified. age can be given unadorned in seconds, or followed by one of these modifiers: seconds, hours, minutes, days, months or years.

caches must be declared before they're used. items get 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 the info on those. 🫶

🎬 ACTIONS 🎬

okay bestie, this is the part where we tell fdm what to actually do with the mail once it's been matched. iconic behavior. the action command defines an action, and then you can call it by name in rules (scroll down for rules, they're right there) to do a thing to a mail. the syntax is:

action name [users] action

action name [users] { action ... }

so name is just a string — that's the label for your action. the users argument works exactly the same way it does in an account definition. and lowkey important: an action's user setting may be overridden in the matching rule. so the rule can boss the action around. 💅

here are all the possible values for action. if you specify multiple actions, they get executed once, in the order specified, for each user. no cap.

• drop — Discard the mail. bye bye 🗑️
• 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. so organized ✨
• 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.
• 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. glow-up for your email fr. 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. main character energy, just saying it out loud.
• 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. five. that's the limit bestie, don't get greedy 🙈

---

📏 RULES 📏

rules are specified using the match keyword. basic form goes like this:

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

the condition argument may be one of:

• all — Matches all mail. literally everything, no filtering, we love a broad audience.
• 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. the way the default is lowercase-c-chill... 🧚
• 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. and any condition may be prefixed by the not keyword to invert it. (yes, not is giving iconic chaotic energy and i'm obsessed 😌)

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's either of a similar form:

action name | actions { name ... }

or you can specify a number of actions inline (lambda actions, so fancy ✨):

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. it's like saying "okay and ALSO—" 💅

---

🪆 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 — it's giving matryoshka, it's giving structure, we love to see it 🎀. 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>

---

and that's a wrap bestie!! this page is from the Debian fam, dated August 21, 2006, and it lives at FDM.CONF(5). go forth and filter your mail like the main character you are 💖✨🦋🌸💅🫶