Provided by: fdm_1.5-3_i386 bug

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 one gigabyte.

     delete-oversized
             If this option is specified, fdm(1) attempts to delete messages
             which exceed maximum-size, and continue.  If it is not specified,
             oversize messages are a fatal error and cause fdm(1) to abort.

             Note that fdm(1) may have a number of messages queued (up to the
             queue-high setting, doubled for rewrite, per account), so this
             setting and the queue-high option should be set after
             consideration of the space available in the temporary folder and
             the implications should fdm(1) abort due to the space becoming
             full.

     queue-high number
             This sets the maximum number of messages fdm(1) will hold
             simultaneously.  fdm(1) will attempt to process previously queued
             messages as the next is being fetched.  Once this limit is
             reached, no further messages wil be fetched until the number of
             messages held drops to the queue-low value.

     queue-low number
             This is the length to which the message queue must drop before
             fetching continues after the queue-high limit has been reached.

     allow-multiple
             If this option is specified, fdm(1) does not attempt to create a
             lock file and allows multiple instances to run simultaneously.

     lock-file path
             This sets an alternative lock file.  The default is ~/.fdm.lock
             for non-root users and /var/db/fdm.lock for root.

     command-user user
             This specifies the user used to run exec and pipe actions.  By
             default it is the user who invoked fdm.

     default-user user
             This sets the default user to change to before delivering mail,
             if fdm(1) is running as root and no alternative user is specified
             as part of the action or rule.  This option may be overridden
             with the -u switch on the command line.  A default user must be
             given if running as root.

     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.

     domain domain | domains { domain ... }
             This specifies the domains to be used when looking for users with
             the from-headers keyword.  The default is the computer’s
             hostname.

     header header | headers { header ... }
             This allows the headers to be examined when looking for users to
             be set.  The default is to look only at the "From" and "Cc"
             headers.  The headers are case-insensitive.

     proxy url
             This instructs fdm(1) to proxy all connections through url.  HTTP
             and SOCKS5 proxies are supported at present (URLs of the form
             http://host[:port] or socks://[user:pass@]host[:port]).  No
             authentication is supported for HTTP.

     unmatched-mail drop | keep
             This option controls what fdm(1) does with mail that reaches the
             end of the ruleset (mail that matches no rules or matches only
             rules with the continue keyword).  drop will cause such mail to
             be discarded, and keep will attempt to leave the mail on the
             server.  The default is to keep the mail and log a warning that
             it reached the end of the ruleset.

     purge-after count
             The purge-after option makes fdm(1) attempt to purge deleted mail
             from the server (if supported) after count mails have been
             retrieved.  This is useful on unreliable connections to limit the
             potential number of mails refetched if the connetion drops, but
             note that it can incur a considerable speed penalty.

     no-received
             If this option is present, fdm(1) will not insert a ‘Received’
             header into each mail.

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

     file-umask user | umask
             This specifies the umask(2) to use when creating files.  user
             means to use the umask set when fdm(1) is started, or umask may
             be specified as a three-digit octal number.  The default is 077.

     file-group user | group
             This option allows the default group ownership of files and
             directories created by fdm(1) to be specified.  group may be a
             group name string or a numeric gid.  If user is used, or this
             option does not appear in the configuration file, fdm(1) does not
             attempt to set the group of new files and directories.

     timeout time
             This controls the maximum time to wait for a server to send data
             before closing a connection.  The default is 900 seconds.

     verify-certificates
             Instructs fdm(1) to verify SSL certificates for all SSL
             connections.

INCLUDING FILES

     Further configuration files may be including using the include command:

     include path

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

MACROS

     Macros may be defined using the following syntax:

     $name = string

     %name = number

     Macros are prefixed with $ to indicate a string value and % to indicate a
     numeric value.  Once defined, a macro may be used in any place a string
     or number is expected.  Macros may be embedded in strings by surrounding
     their name (after the $ or %) with {}s, like so:

           "abc ${mymacro} %{anothermacro} def"

     The ifdef, ifndef and endif keywords may be used to conditionally parse a
     section of the configuration file depending on whether or not the macro
     given exists or does not exist.  ifdef and ifndef blocks may be nested.

SHELL COMMANDS

     The result of a shell command may be used at any point a string or number
     is expected by wrapping it in $() or %().  If the former is used, the
     command result is used as a string; if the latter, it is converted to an
     integer.  Shell commands are executed when the configuration file is
     parsed.

ACCOUNTS

     The account command is used to instruct fdm(1) to fetch mail from an
     account.  The syntax is:

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

     The name argument is a string specifying a name for the account.  The
     optional users argument has the following form:

     user user | users { user ... } | user from-headers

     The first two options specify a user or list of users as which the mail
     should be delivered when an action is executed.  If user from-headers is
     specified, fdm(1) attempts to find the users from the mail headers, using
     the values of the headers and domains options.  If no headers are
     specified, or fdm(1) fails to find any valid users in the headers, 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]

     pop3s server host [port port] [userpass] [only] [no-apop] [no-verify]
             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.

     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]

     imaps server host [port port] [userpass] [folder name] [only] [no-verify]
             These define an IMAP or IMAPS account.  The parameters are as for
             a POP3 or POP3S account, aside from the additional folder option
             which allows the folder name to be specified (the default is to
             fetch from the inbox).  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.

     imap pipe command [userpass] [folder name] [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 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.

     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.

     nntp server host [port port] group group cache cache

     nntp server host [port port] groups { group ... } cache cache

     nntps server host [port port] group group cache cache

     nntps server host [port port] 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_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 occurances 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 〈nicm@users.sourceforge.net