.. SPDX-License-Identifier: GPL-2.0 .. _remail_daemon_config_man: remail_daemon.config manual page ================================ Synopsis -------- remail.yaml list.yaml Description ----------- This manual describes the configuration file format for the remail daemon. The configuration files are using yaml syntax. There are two types of configuration files: 1) Base configuration file The default configuration file is located in the base configuration directory which is also the base work directory. 2) List configuration file Per mailing list configuration file. Non-mandatory options are set to the builtin defaults if they are not available in the configuration files. .. _config_dir_struct: Configuration directory structure --------------------------------- The configuration directory structure is fixed and looks like this:: ├── .certs │   ├── cacert.pem │   ├── list1@your.domain.key │   ├── list2@your.domain.key │   ├── admin1@some.domain.crt │   ├── admin2@other.domain.crt ├── .git ├── .gnupg │   ├── private-keys-v1.d │   │   ├── XYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYX1.key │   │   ├── YXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXYXY2.key │   ├── pubring.kbx ├── lists │   ├── list1 │   │   ├── .certs │   │   │   ├── list1@your.domain.crt │   │   │   ├── subscr1-1@subscr1.domain.crt │   │   │   ├── subscr1-2@subscr2.domain.crt │   │   │   ├── admin1@some.domain.crt │   │   ├── .git │   │   ├── .gnupg │   │   │   └── pubring.kbx │   │   ├── list.yaml │   │   ├── template_admin │   │   └── template_welcome │   ├── list2 │   │   ├── .certs │   │   │   ├── list2@your.domain.crt │   │   │   ├── subscr2-1@subscr1.domain.crt │   │   │   ├── subscr2-2@subscr2.domain.crt │   │   │   ├── admin2@other.domain.crt │   │   ├── .git │   │   ├── .gnupg │   │   │   └── pubring.kbx │   │   ├── list.yaml │   │   ├── template_admin │   │   └── template_welcome ├── lock ├── maildir │   ├── cur │   ├── new │   └── tmp ├── maildir.frozen │   ├── cur │   ├── new │   └── tmp └── remail.yaml The base directory contains: - The main configuration file (remail.yaml). - The S/MIME directory (.certs). .. warning:: It contains the private S/MIME keys of the lists. - The GPG directory (.gnupg). .. warning:: It contains the private GPG keys of the lists. - The maildir directory to which the incoming mail gets delivered by a MTA or MRA. - The maildir.frozen directory to which unprocessed or failed mail gets moved to. - A lock file which can be used to protect a reload against a concurrent configuration update. - The lists directory under which the list specific configuration directories are located. The list directories contain: - The list configuration file (list.yaml) - The S/MIME directory (.certs). It contains the public S/MIME keys of the list subscribers and of the list itself. - The GPG directory (.gnupg). It contains the public GPG keys of the list subscribers and of the list itself. Base configuration items ------------------------ The structure of the base configuration file is:: .. code-block:: yaml enabled: False use_smtp: False smime: ... gpg: ... lists: list1: enabled: True moderated: True archive: ... listaccount: ... admins: ad1@min.domain: ... adN@min.domain: ... listN: ... Base items: ^^^^^^^^^^^ .. code-block:: yaml enabled: False use_smtp: False enabled: Optional item to enable or disable the daemon. If the item is set to False then no other options are evaluated and the daemon sleeps waiting for termination or reconfiguration. If True, the rest or the options is evaluated. Optional item which defaults to False use_smtp: Set to True to enable mail delivery via SMTP to the SMTP server on localhost. The SMTP server is responsible for relaying the mails to a public mail server. remail does not implement any other transport for outgoing mail and the target server is therefore not configurable. If False the encrypted mails are delivered to stdout. That's mainly a development option which is not meant for production use. Optional time which defaults to False S/MIME options: ^^^^^^^^^^^^^^^ .. code-block:: yaml smime: verify: True sign: True verify: When handling S/MIME encrypted mail then the validity of the senders key is by default verified against the CA certs. If set to False this verification is disabled. Disable this only in extreme situations and consider the consequences. sign: Sign the mails sent to S/MIME recipients with the lists key. Enabled by default as this is the recommended way to send S/MIME mail. If disabled then the public certificate of the list is not part of the welcome message which is sent to new recipients. GPG options: ^^^^^^^^^^^^ .. code-block:: yaml gpg: always_trust: True sign: True always_trust: The public keyring of a list is managed by the list administrator. To avoid having to manually tweak the trust DB, it's possible to force trust mode on the keyring with this option. Defaults to True as the trust establishment is the responsibility of the list administrator anyway and setting this to True avoids a lot of pointless manual operations. sign: Sign the mails sent to GPG recipients with the lists key. Enabled by default as this is the recommended way to send GPG mail. If disabled then the public key of the list is not part of the welcome message which is sent to new recipients. The mailing lists collection: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: yaml lists: listname: ... listname: lists: The opening of the lists map. The list base configuration: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The list base configuration for each list consists of the following items: .. code-block:: yaml listname: enabled: True moderated: True archive: ... listaccount: ... admins: ... The list base items: """""""""""""""""""" .. code-block:: yaml listname: enabled: True moderated: True enabled: If False, the list configuration is disabled. No mail is delivered to this list. If True, the list is enabled. moderated: Optional item to set the list to moderated. It True only subscribers are allowed to post to the list either from their subscription address or from one of the optional alias mail addresses which are associated with a subscriber. Mails from non-subscribers are not delivered to the list, they are delivered to the list administrator The archive section: """""""""""""""""""" .. code-block:: yaml archive: use_maildir: True archive_incoming: True archive_plain: False use_maildir: If True, maildir is the storage format for enabled archives. If False, mbox is used. archive_incoming: If True archive the incoming encrypted mails in the selected storage format. The maildir folder name is archive_incoming/. The mbox name is archive_incoming.mbox. These files/directories are located in the per mailing list configuration/work directory. archive_plain: If True archive the decrypted mails in the selected storage format. The mails are archived in two stores: - archive_admin[.mbox] for mails which are directed to the list admins either directly or through bounce catching, moderation etc. - archive_list[.mbox] for mails which are delivered to the list The list account section: """"""""""""""""""""""""" .. code-block:: yaml listaccount: list@mail.domain: name: Clear text name fingerprint: 40CHARACTERFINGERPRINT The list account's e-mail address is the key item for the name and fingerprint options. name: A clear text name for the list, e.g. incident-17 or whatever sensible name is selected. This name is used in From mangling when a list post is sent to the subscribers: incident-17 for Joe Poster From rewriting is used to ensure that replies go only to the list and not to some other place. The Reply-To field could be used as well but that is not correctly handled by mail clients and users can force reply to all nevertheless. fingerprint: The full 40 character PGP fingerprint of the list key. .. _list_admin_section: The list administrators section: """""""""""""""""""""""""""""""" .. code-block:: yaml admins: admin1@some.domain: name: Clear text name fingerprint: 40CHARACTERFINGERPRINT enabled: True use_smime: False gpg_plain: False admin2@other.domain: name: The real user name. Mandatory field fingerprint: The full 40 character PGP fingerprint of the administrators key. Mandatory if the use_smime option is not set. enabled: Switch to enable/disable the account. Mandatory item. use_smime: Send S/MIME encrypted mail to the admin if True. Otherwise use PGP. Optional, defaults to False. gpg_plain: If False send mail in the application/pgp-encrypted format. If True use the plain/text embedded PGP variant if possible. The latter does not work for mails with attachments but for normal plain/text conversation this can be requested by a recipient because that's better supported in some mail clients. Optional, defaults to False. List configuration items ------------------------ The structure of a list specific configuration file is:: .. code-block:: yaml subscribers: subscriber1@some.domain: ... subscriberN@other.domain: ... The configuration of the subscribers is identical to the configuration of :ref:`the list administrators section ` above, but it allows one additional field: .. code-block:: yaml subscribers: subscriber1@some.domain: ... aliases: - subscr1@some.domain - subscriber1@other.domain aliases: The optional aliases item is a list of alias email addresses for a subscriber. List mail is always delivered to the subscriber e-mail address, but people have often several e-mail addresses covered by the same PGP key and post from various addresses. If the list is moderated, then the aliases allow posting for subscribers from their registered alias addresses. If moderation is disabled the alias list is not used at all. See also -------- :manpage:`remail_daemon(1)` :manpage:`remail_chkcfg(1)` :manpage:`remail_pipe(1)`