remail/Documentation/configuration.rst

.. SPDX-License-Identifier: GPL-2.0

.. _remail_configuration:

remail configuration guide
==========================

Introduction
------------

The configuration files are simple yaml files which only use the very basic
yaml components. The yaml file does not have a schema yet, but the
configuration parser is doing extensive verification.

See :ref:`remail_daemon_config_man` for a detailed explanation of the
configuration files and the configuration items.

The examples directory in Documentation contains a full dummy configuration
for two lists including fully documented yaml files.

Work directory
--------------

The work directory structure is fixed and is documented in the man page in
the section :ref:`config_dir_struct`.

A comfortable way to manage the configuration is git. The base
configuration directory and the actual list configuration directories are
in separate git trees so that they can be maintained by different people
with different permissions.


Key considerations
------------------

Private keys
^^^^^^^^^^^^

In order to encrypt incoming mail and to sign outgoing mail the list daemon
needs access to the private GPG and S/MIME keys of each list.

The keys must be stored without password.

This is not a security issue because if the keys would have passwords then
the password needs to be part of the configuration file.

If the list configuration or the list server is compromised all bets are
off. Having a password on the keys would not make any difference.

Public keys
^^^^^^^^^^^

The public GPG keys of the subscribers in the mailing list specific keyring
are always trusted by remail. The list administrator is responsible for
verifying the authenticity of the subscribers key, so extensive trust
management does not make sense and just complicates the handling.

remail does not try to update the keyring at any time. This is in the
responsibility of the list administrator. Automatic updates are not a
really good idea in the light of the recent attacks on the PGP
infrastructure.

The public S/MIME certificates are verified against the CA certificates
which are provided and managed by the remail base administrator as part of
the base configuration.

Key storage format
------------------

GPG
^^^

GPG keys are stored using the storage format of gnugp. Create and manage
the private keys and the subscriber keyrings with the GPG tool of your
choice.

S/MIME
^^^^^^

S/MIME .key and .crt files are stored in pem format and have to follow
the following naming convention.

Private keys (list keys):
  email@address.domain.key

Public certificates (list and subscribers):
  email@address.domain.crt

Using git for configuration management
--------------------------------------

As seen above the base configuration directory contains the private keys
for the lists. So the administrator has to ensure that the git repository
which is used to push the configuration to is properly protected. Also the
machine used for updating the base configuration repository should not be
accessible by unpriviledged users.

The incomplete list of things to avoid under all circumstances:

 - Push the base configuration to a public hosted repository server like
   github, gitlab etc.

 - Keep the base configuration on an easy accessible machine if the data is
   not sufficiently protected by encryption

 - Keep the base configuration unencrypted on a backup medium.

The list configuration does not contain strictly secret information, but
the pure existance of an incident list and the list of involved people
might give a hint in which area the handled issue might be. So in general
it is recommended to hide a list configuration repository from public and
unpriviledged access as well, but in case of an leak the potential damage
is way smaller than the one of leaking the base configuration which
contains the private keys.


Base configuration
------------------

To configure the list daemon the following configuration files need to be
created or modified:

 - remail.yaml

remail.yaml:

   The main configuration file for the remail daemon. See
   :ref:`remail_daemon_config_man` for a detailed information of the file.

List configuration
------------------

For each enabled mailing list the following configuration files need to be
created or modified:

 - list.yaml
 - template_welcome
 - template_admin

list.yaml:

   The list specific configuration file for the mailing list. It contains
   the subscriber list.  See :ref:`remail_daemon_config_man` for a detailed
   information of the file.

template_admin:

   The mail template for mail to the list admin(s).

template_welcome:

   The mail template for mail to welcome new subscribers.


Public mail
-----------

Request or configure a user account for receiving list mail. This mail
account acts as a catch all for the list, the list-owner and list-bounce
addresses. If more than one mailing list is served by the list daemon then
the user mail account can receive all mails for the lists. remail finds the
appropriate mailing list for the various addresses.

remail does not retrieve mail from a public mail server as this is outside
the scope of remail and depends on the particular setup. remail expects the
incoming mails to be delivered into a maildir. Tools like getmail,
fetchmail can handle that as well as SMTP servers.


Local mail transport
--------------------

remail delivers the outgoing mail to the local SMTP server. The
configuration for the SMTP server to relay the mails to the public facing
machines is outside the scope of this documentation and depends on the SMTP
server variant you are using.