mirror of
https://kernel.googlesource.com/pub/scm/linux/kernel/git/tglx/remail.git
synced 2024-11-09 22:12:37 +01:00
18a16b08fb
According to RFC2919, List-Id header should be in the form of a hostname value enclosed inside angle brackets. This change does two things: 1. Fixes the default to be the list address with "@" replaced by a "." 2. Allows setting custom list-id values inside remail.yaml 3. Documents the "listid" optional setting in the manpage Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Signed-off-by: Thomas Gleixner <tglx@linutronix.de> Link: https://tools.ietf.org/html/rfc2919
442 lines
12 KiB
ReStructuredText
442 lines
12 KiB
ReStructuredText
.. 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
|
|
gpgbinary: gpg
|
|
|
|
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.
|
|
|
|
gpgbinary:
|
|
|
|
Path to the GnuPG binary to use, defaults to "gpg".
|
|
|
|
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
|
|
listid: ...
|
|
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
|
|
|
|
listid:
|
|
|
|
Optional item to override the default list-id with a custom value.
|
|
Default: list address with the "@" replaced by a period.
|
|
|
|
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 <list@mail.domain>
|
|
|
|
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 <list_admin_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)`
|
|
|