=============
Configuration
=============

.. highlight:: none

Syntax
======

The configuration consists of key-value pairs and comments, each of which
must comprise a line of its own. Keys and values are separated by whitespace.
Comments start with a hash ("#"). Comments, empty lines, and leading or
trailing whitespace are ignored.


Keys
====

.. confvar:: account [login@]host

    Subsequent statements only apply to accounts matching `login` and `host`.
    If `login` is omitted, all accounts on `host` match.

.. confvar:: alias string

    Use `string` as alias for the current host.

.. confvar:: backups n

    Keep `n` backups of Sieve scripts.

    `n` = 0
        Do not make backups (default).

    `n` = 1
        Back up :file:`file` as :file:`file~`.

    `n` > 1
        Back up :file:`file` as :file:`file.~{m}~`, where *m* starts
        with 1 and increments with each backup. Old backups are
        deleted if there are more than `n` backups.

.. confvar:: cafile file

    Load custom certificate authorities (CAs) from `file`.
    `File` must be in PEM format.

.. confvar:: cadir dir

    Load custom certificate authorities (CAs) from `dir`. `Dir` must
    contain one PEM file per CA, each of which must be named after the
    hash of its subject name.

    .. only:: man

        See :manpage:`c_rehash(1)` for details.

    .. only:: not man

        See the OpenSSL manual (fn. SSL_CTX_load_verify_locations_)
        for details.

.. confvar:: cert file

    Read the client TLS certificate from `file`. `File` must be in PEM
    format and contain the private key, the client certificate, and every
    CA certificate required to establish the certificate's authenticity,
    in that order. Some ManageSieve servers also require that each CA
    certificate is followed by its certificate revocation list.

.. confvar:: confirm command [, ...]

    Comma-separated list of commands that require confirmation
    if they overwrite or remove a file.

    Either a combination of:

    * :sievecmd:`cp`
    * :sievecmd:`get`
    * :sievecmd:`mv`
    * :sievecmd:`put`
    * :sievecmd:`rm`

    Or one of:

    * ``all`` (default)
    * ``none``

.. confvar:: getpassphrase command

    Read the TLS key passphrase from the standard output of :samp:`{command}`.

.. confvar:: getpassword command

    Read the login password from the standard output of :samp:`{command}`.

.. confvar:: host hostname

    Host to connect to (default: :samp:`localhost`).

.. confvar:: key file

    Read the client TLS key from `file`, rather than from the certificate file.
    `File` must be in PEM format.

.. confvar:: login username

    Log in as *username*.

.. confvar:: password string

     Use `string` as password.

     :file:`sieve.cf` must not be group- or world-readable
     if a `password` is set.

     .. danger::
         Passwords should be stored in encrypted form only.
         Use :confvar:`getpassword` instead.

.. confvar:: port port

    Connect to `port` (default: 4190).

.. confvar:: timeout float

    Connection timeout in seconds.

.. confvar:: tls boolean

    Secure connections with Transport Layer Security (TLS)?

    ``yes`` (default) or ``no``.

    .. danger::
        Data sent over an unsecured connection can be
        read and modified by third parties.

.. confvar:: saslmechs mechanism [, ...]

    Comma-separated list of authentication mechanisms, ordered by preference.

    External mechanism:

    * ``external``

    Password-based mechanisms:

    * ``scram-sha3-512-plus``
    * ``scram-sha-512-plus``
    * ``scram-sha-384-plus``
    * ``scram-sha-256-plus``
    * ``scram-sha-224-plus``
    * ``scram-sha-1-plus``
    * ``scram-sha3-512``
    * ``scram-sha-512``
    * ``scram-sha-384``
    * ``scram-sha-256``
    * ``scram-sha-224``
    * ``scram-sha-1``
    * ``plain``
    * ``cram-md5`` (obsolete)
    * ``login`` (obsolete)

    Shell-like patterns are expanded to mechanisms in the above order.
    However, if ``EXTERNAL`` authentication is requested, it is attempted
    before password-based authentication, regardless of the order in
    which authentication mechanisms are given. See :manpage:`sh(1)`
    and :manpage:`fnmatch(3)` for the pattern matching syntax.

    Default: ``scram-*, plain``

.. confvar:: saslprep credentials

    Types of `credentials` that should be normalised.

    One of:

    * ``usernames``
    * ``passwords``
    * ``all`` (default)
    * ``none``

    Adjust if valid credentials are rejected.

.. confvar:: verbosity level

    One of:

    * ``error``
    * ``warning``
    * ``info`` (default)
    * ``debug``
    * ``auth`` (show authentication exchange)

    The higher the level, the fewer messages are printed,
    where ``error`` is highest and ``auth`` lowest.

    .. danger::
        The authentication exchange likely contains your password,
        even though this is not apparent. Do *not* share it.

.. confvar:: x509strict boolean

    Reject TLS certificates that do not conform to :rfc:`5280`?

    ``yes`` (default) or ``no``.


Filenames
=========

:samp:`~` and :samp:`~{user}` are expanded to the home directory of
the logged in and the given `user` respectively, but only if they
occur at the start of a filename.

Relative filenames are interpreted as being relative to the directory of the
configuration file in which a filename variable is set or, if the variable
is set with :option:`-o`, the current working directory.


Commands
========

:samp:`~` and :samp:`~{user}` are expanded in the same way as
they are expanded in filenames. 

:samp:`${var}` and :samp:`$\\{{var}\\}` are expanded to the configuration
variable `var`. '\$' can be escaped by prefixing it with another '\$'
(e.g., :samp:`$$var` is expanded to :samp:`$var`).

Commands are split into words before :samp:`~` and variables are expanded.
Otherwise, they are split in the same way as they would be split by a system
shell. See :manpage:`sh(1)` and :manpage:`wordexp(3)` for details.


Passwords
=========

Passwords and passphrases can be read from the standard output of system
commands with :confvar:`getpassword` and :confvar:`getpassphrase`.

GnuPG
-----

GnuPG_ can be used as password manager.

First, create a directory to hold the encrypted files::

    $ mkdir -m 0700 ~/secret

Next, encrypt the password for each account with GnuPG and put the encrypted
file in that directory. For example, to encrypt the password for :samp:`user`
on :samp:`imap.host.example` for the key :samp:`0123abcd`::

    $ gpg -er 0123abcd <<EOF >~/secret/user@imap.host.example.gpg
    > <password> 
    > EOF

Finally, add

.. code:: none

    getpassword gpg -d ~/secret/$login@$host.gpg

to your :file:`sieve.cf` to read passwords from such files.


KeePassXC
---------

First, add the password for :samp:`user` on :samp:`imap.host.example` to the
directory :samp:`mail` in :file:`database.kdbx`::

    $ keepassxc-cli add database.kdbx mail/user@imap.host.example -p 

Then add

.. code:: none

    getpassword keepassxc-cli show -a password database.kdbx dir/$login@$host

to your :file:`sieve.cf` to look up passwords in the folder :file:`mail` of
the KeyPass database file :file:`database.kdbx` using KeePassXC_.


MacOS Keychain
--------------

Add

.. code:: none

    getpassword security find-internet-password -s $host -a $login -w

to your :file:`sieve.cf` to look up passwords stored by Apple Mail or
MailMate_ in the macOS' Keychain.

Passwords can be added to the Keychain with::

    $ security add-internet-password -s host.imap.example -a user -w

.. warning::
   Granting :command:`security` access to a password, effectively,
   grants *every* application access to that password.


Pass
----

First, add the password for :samp:`user` on :samp:`imap.host.example`::

    $ pass insert mail/user@imap.host.example

Then add

.. code:: none

    getpassword pass mail/$login@$host

to your :file:`sieve.cf` to look up passwords in the folder
:file:`mail` of a pass_ password store.


Files
=====

:file:`/etc/sieve/config`, :file:`/etc/sieve.cf`, :file:`{$XDG_CONFIG_HOME}/sieve/config`, :file:`{$HOME}/.sieve/config`, :file:`{$HOME}/.sieve.cf`
    Default configuration files.


Security
========

TLS should *not* be disabled.

Passwords can be queried from password managers to automate logins. However,
any command that can be run by :command:`sievemgr` can, at the very least,
also be run by any application that can run :command:`python`.


Examples
========

Recommended configuration::

    # Keep a single backup
    backups 1

    # Only require confirmation for removing scripts
    confirm rm

    # Be less verbose
    verbosity warning

Accounts::

    account imap.foo.example
        alias foo
        login user

    account imap.bar.example
        alias bar
        login user@bar.example


Use TLS client authentication to log in as :samp:`user`
on :samp:`imap.foo.example`::

    account imap.foo.example
        login user
        cert client.crt
        key client.key
        saslmechs external


.. only:: man

    See Also
    ========

    :manpage:`sievemgr(1)`