### 3.2 Mailutils Configuration File ¶

Configuration files are the principal means of configuring any GNU Mailutils component. When started, each utility tries to load its configuration from the following locations, in that order:

1. Main site-wide configuration file.

   It is named `sysconfdir/mailutils.conf`, where sysconfdir stands for the system configuration directory set when compiling the package. You can obtain the value of sysconfdir by running

       $ mailutils info sysconfdir

   or

       $ prog --show-config-options | grep SYSCONFDIR

   where prog stands for any GNU Mailutils utility.

   The site-wide configuration file is not read if any of `--no-site-config` or `--no-config` command line options was given.

   Older versions of GNU Mailutils read configuration from file `mailutils.rc`. To facilitate transition, mailutils will look for that file as well. If both the default site-wide configuration file and legacy configuration file are present you will get the following warning:

       legacy configuration file /etc/mailutils.rc ignored

   Otherwise, if `mailutils.conf` does not exist and `mailutils.rc` is present, it will be used instead and the following warning will be issued:

        using legacy configuration file /etc/mailutils.rc:
        please rename it to /etc/mailutils.conf

2. Per-user configuration file.

   Client utilities, such as `frm` or `sieve`, look in the user home directory for a file named ‘`.prog`’, where prog is the name of the utility. If present, this file will be loaded after loading the site-wide configuration file. For example, the per-user configuration file for `sieve` utility is named `.sieve`.

   Loading of per-user configuration file is disabled by `--no-user-config` and `--no-config` options.

Server programs, such as `imap4d` don’t use per-user configuration files.

The `--no-config` option provides a shortcut for disabling loading of the default configuration files. For servers, its effect is the same as of `--no-site-config`. For client utilities, it is equivalent to `--no-site-config --no-user-config` used together.

The `--config-file` command line option instructs the program to read configuration from the file supplied as its argument. In that case, default configuration files are not used at all.

Neither site-wide nor user configuration files are required to exist. If any or both of them are absent, GNU Mailutils won’t complain – the utility will silently fall back to its default settings.

To make configuration processing more verbose, use the `--config-verbose` command line option. Here is an example of what you might get using this option:

    imap4d: parsing file `/etc/mailutils.conf'
    imap4d: finished parsing file `/etc/mailutils.conf'

Specifying this option more than once adds more verbosity to this output. If this option is given two times, GNU Mailutils will print each configuration file statement it parsed, along with the exact location where it occurred (the exact meaning of each statement will be described later in this chapter):

    imap4d: parsing file `/etc/mailutils.conf'
    # 1 "/etc/mailutils.conf"
    mailbox {
    # 2 "/etc/mailutils.conf"
      mailbox-pattern maildir:/var/spool/mail;type=index;param=2;user=${user};
    # 3 "/etc/mailutils.conf"
      mailbox-type maildir;
    };
    # 6 "/etc/mailutils.conf"
    include /etc/mailutils.d;
    imap4d: parsing file `/etc/mailutils.d/imap4d'
    ...

To test configuration file without actually running the utility, use the `--config-lint` command line option. With this option, any Mailutils utility exits after finishing parsing of the configuration files. Any errors occurred during parsing are displayed on the standard error output. This option can be combined with `--config-verbose` to obtain more detailed output.

The `--config-help` command line option produces on the standard output the summary of all configuration statements understood by the utility, with detailed comments and in the form suitable for configuration file. For example, the simplest way to write a configuration file for, say, `imap4d` is to run

    $ imap4d --config-help > imap4d.conf

and to edit the `imap4d.conf` file with your editor of choice.

The order in which configuration files are loaded defines the precedence of their settings. Thus, for client utilities, settings from the per-user configuration file override those from the site-wide configuration.

It is also possible to set or override arbitrary configuration variables in the command line. It can be done via the `--set` option. Its argument is a pathname of the variable to be set, followed by an equals sign and a value. For example, to define the variable ‘`syslog`’ in section ‘`logging`’ to ‘`no`’, do the following:

    $ imap4d --set .logging.syslog=no

Configuration pathnames are discussed in detail in Statement Path. For a detailed description of this option, the --set option.

The `--set` options are processed after loading all configuration files.