:title: Mailing Lists

.. _lists:

Mailing Lists
#############

`The Mailman Suite <https://www.list.org/>`_ (Mailman Core, Postorius,
Hyperkitty) is installed on lists.opendev.org to run mailing lists for the
OpenDev Collaboratory and projects it hosts, as well as archives of those
lists.

At a Glance
===========

:Hosts:
  * https://lists.opendev.org (and numerous other aliases)
:Ansible:
  * :git_file:`playbooks/service-lists3.yaml`
  * :git_file:`playbooks/roles/mailman3`
:Projects:
  * https://www.list.org/
  * https://gitlab.com/mailman/
:Bugs:
  * https://storyboard.openstack.org/#!/project/748
  * https://gitlab.com/mailman/
:Resources:
  * `Mailman Documentation <https://docs.mailman3.org/>`_

Adding a List
=============

A list may be added by adding it to the ``openstack-infra/system-config``
repository in :git_file:`inventory/service/group_vars/mailman3.yaml`.
For example:

.. code-block:: yaml

        - name: Example list
          description: 'This is an example'
          admin: 'admin@example.com'
          password: "{{ mailman_list_password }}"

Scripted Interaction with Lists
===============================

This may only be performed with root access to the list server.

.. code-block:: bash

  sudo docker-compose -f /etc/mailman-compose/docker-compose.yaml exec -T -u mailman mailman-core mailman help

Use context help for the CLI's many subcommands, or see the Mailman v3
documentation for more details.

Example: Switch a mailing list to default moderation
----------------------------------------------------

For popular lists which allow subscribers to post freely and only
moderate messages from non-subscribers, it's not uncommon to see
spammers bypass this rule by subscribing first (or posting spam through
Hyperkitty, as it auto-subscribes the poster). The recommended
mitigation is to set the list's default action to hold for moderation,
and then have a moderator switch any legitimate new subscriber's action
to default processing after approving their post. For subscribers
imported from Mailman 2.1, those typically already have default
processing set, but anyone subscribing through Mailman 3 will use the
list default (i.e. unset for their account) so we need to bulk update
all of those to default processing or else they're going to be treated
like new subscribers.

Here's how to do that from an SSH session on the mailing list server
(make sure to pass the actual list name in the ``-l`` option instead of
``sample-list@lists.example.org``):

.. code-block:: bash

  $ sudo docker-compose -f /etc/mailman-compose/docker-compose.yaml exec -u mailman mailman-core mailman shell -l sample-list@lists.example.org -i

  Welcome to the GNU Mailman shell
  Use commit() to commit changes.
  Use abort() to discard changes since the last commit.
  Exit with ctrl+D does an implicit commit() but exit() does not.
  The variable 'm' is the sample-list@lists.example.org mailing list
  >>> from mailman.interfaces.action import Action
  >>> for member in m.members.members:
  ...     if not member.moderation_action:
  ...         member.moderation_action = Action.defer
  ...
  >>> commit()
  >>> exit()

Note that we avoid altering ``moderation_action`` if it's already set,
since previously identified spammers may have theirs set to something
like ``Action.discard`` and we don't wish to reenable them. In this case
``Action.defer`` is the explicit default processing path, which means
continue to check the message against other rules like max recipients,
message length, administrivia filtering, and so forth. While there is an
``Action.accept`` it should be avoided, since it directly bypasses these
valuable default processing rules.

Once this action has been performed, switch the list's *Default action
to take when a member posts to the list* from *Default processing* to
*Hold for moderation* in Postorius. Any existing subscribers will have
the same experience as before, but anyone who subscribes to the list
from this point forward will have their posts held for moderation until
a moderator changes the *Moderation* value to *Default processing* under
the *Administration options* at the end of their subscriber page in
Postorius.

Django Admin Interface
======================

There is an admin WebUI at ``/admin/``, but it's only accessible over a
loopback from localhost. If you need to use it, you'll want to connect an
SSH tunnel from your own system and then override DNS resolution for
``lists.opendev.org`` to point to your loopback address.

List Configuration and Moderation Backdoor
==========================================

If you need to step in and assist a list moderator or owner with
configuration and moderation tasks, you can log into the appropriate
Postorius URL for the corresponding list domain with the Django admin
credentials. This is effectively a Mailman "super user" account (as well as
being the account for administering the underlying Django installation).
This same account can be similarly used in Hyperkitty to delete spam
messages and threads in an emergency if the list owner is unavailable.