Contents

  1. Mailman 3
    1. Prerequisites
    2. Install Mailman 3
    3. Configuration
      1. Postfix integration
      2. Setting up Postorius (admin and user web interface)
        1. Manual configuration
        2. Automatic configuration
      3. Setting up HyperKitty (archiver)
        1. Enable the HyperKitty archiver
    4. Creating mailing lists
      1. Create a domain for the mailing list
      2. Create the mailing list
      3. Configuring a mailing list
    5. Migration of Mailman 2.1 lists
      1. Import the list configuration and members
        1. On the old server
        2. On the new server
      2. Import the list archive
    6. Troubleshooting
      1. Avoid DMARC-related problems
      2. Accessing logs

Mailman 3

Mailman logo

This guide helps setting up Mailman 3 on Debian trixie: Postfix integration, mailing list creation, web interface (with nginx integration) for changing list settings, and message archiving.

Other mail transport agents (such as exim, sendmail) can also be used, but this guide does not cover them. Check the Mailman3 documentation and the file /usr/share/doc/mailman3/README.txt in the section "Exim4 as mail transport agent (MTA)" for further information.

This guide uses nginx to make the administrator and user web interface available. The package also has integration with Apache2. Other reverse proxies could be used as well.

This guide uses lists.example.org as the mailing list domain and web interface host name.

Prerequisites

Install Mailman 3

To install Mailman3 (core, Postorius web admin and HyperKitty archiver): 

$ sudo apt install mailman3-full

This installs all the required Mailman packages for delivering emails, Web UI for the list members and administrators of the list and the archiving tooling.

Mailman3 is divided into different independent components, each of them are a separate application that communicates with each other. Relevant for the installation and configuration:

{i} Internally, Mailman 3 is divided into 5 components.

Installing mailman3-full installs all the components in the server.

For the database backend, the Debian packages use by default SQLite 3. The file /usr/share/doc/mailman3/README.Debian notes that for production setups, SQLite 3 is not recommended as database backend and explains how to use PostgreSQL or MariaDB/MySQL. The Mailman 3 upstream documentation also has information about Setting up your database. Mailman 3 documentation does not recommend a specific database.

{i} In Debian, the SQLite 3 database is stored in /var/lib/mailman3/data/mailman.db.

During mailman3-full installation you will be asked two questions. Answer "Yes" to both of them:

After installation, display information about the Mailman installation with: 

$ sudo mailman-wrapper info

{i} Upstream Mailman 3 uses the command mailman, but in Debian trixie the command mailman-wrapper must be used.

{i} There is a bug (to be reported) where mailman-wrapper --help returns an error (raises a Python exception). It does not affect other functionality.

Configuration

This guide uses SQLite 3 as its database and Postfix as its MTA. Mailman Core, Postorius, and HyperKitty all run on the same host.

Postfix integration

The file /usr/share/doc/mailman3/README.Debian in the section "Postfix as mail transport agent (MTA)" has information about how to integrate Postfix with Mailman.

Edit /etc/postfix/main.cf and add: 

# Mailman related settings
owner_request_special = no
transport_maps = hash:/var/lib/mailman3/data/postfix_lmtp
local_recipient_maps = proxy:unix:passwd.byname $alias_maps hash:/var/lib/mailman3/data/postfix_lmtp
relay_domains = ${{$compatibility_level} < {2} ? {$mydestination} : {}} hash:/var/lib/mailman3/data/postfix_domains

Check that these settings do not conflict with your existing Postfix configuration. They are compatible with a default Postfix installation on Debian trixie.

Reload Postfix: 

$ sudo systemctl reload postfix

Edit /etc/mailman3/mailman.cfg and set site_owner to the email address of the global Mailman administrator. The defaults for the other settings are generally suitable.

Restart Mailman Core: 

$ sudo systemctl restart mailman3

Setting up Postorius (admin and user web interface)

Postorius is Mailman’s Django-based web interface. Debian-specific setup instructions are available in /usr/share/doc/mailman3-web/README.Debian.gz. The package supports both Apache2 and nginx; this guide uses nginx.

Manual configuration

Install nginx: 

$ sudo apt install nginx

Edit the provided nginx configuration and set at least server_name: 

$ sudo sensible-editor /etc/mailman3/nginx.conf

Enable the configuration, create its log directory, and reload nginx: 

$ sudo ln -s /etc/mailman3/nginx.conf /etc/nginx/sites-enabled/mailman3.conf
$ sudo mkdir /var/log/nginx/mailman3
$ sudo systemctl reload nginx

You should now be able to access http://lists.example.org, which should display the Mailman 3 welcome page.

If you need to create a superuser (if not done during the installation of mailman3-full) you can do it now via (replace ADMIN_USERNAME and ADMIN_EMAIL_ADDRESS with the desired values): 

$ sudo django-admin createsuperuser --pythonpath /usr/share/mailman3-web \
    --settings settings --username ADMIN_USERNAME --email ADMIN_EMAIL_ADDRESS

The command will request the password for the new user.

For security, the web interface should be served over HTTPS. HTTPS configuration for nginx is outside the scope of this guide.

If you deliberately use plain HTTP, edit /etc/mailman3/mailman-web.py and change ACCOUNT_DEFAULT_HTTP_PROTOCOL from https to http. Otherwise, generated links such as email-verification links will use HTTPS and may not work.

To configure the domain used in the From header of messages sent by Postorius, edit /etc/mailman3/mailman-web.py and change EMAILME. Its default value is 'localhost.local'; for this example, use 'lists.example.org'.

After changing any values in /etc/mailman3/mailman-web.py, restart the web server: 

$ sudo systemctl restart mailman3-web

Automatic configuration

Run: 

$ sudo dpkg-reconfigure mailman3-web

/!\ Running this command may overwrite previous changes to /etc/mailman3/mailman-web.py.

Answer the prompts to configure Postorius integration with Apache2 or nginx and, optionally, create a superuser.

Setting up HyperKitty (archiver)

Enable the HyperKitty archiver

Add the following section to the end of /etc/mailman3/mailman.cfg, as documented in /etc/mailman3/mailman-hyperkitty.cfg: 

[archiver.hyperkitty]
class: mailman_hyperkitty.Archiver
enable: yes
configuration: /etc/mailman3/mailman-hyperkitty.cfg

Copy the value of MAILMAN_ARCHIVER_KEY from /etc/mailman3/mailman-web.py to the api_key setting in /etc/mailman3/mailman-hyperkitty.cfg. Omit the surrounding quotation marks.

You could also set up the api_key in mailman-hyperkitty.cfg using: 

$ sudo dpkg-reconfigure python3-mailman-hyperkitty

/!\ This command rewrites the entire /etc/mailman3/mailman-hyperkitty.cfg file.

Still in mailman-hyperkitty.cfg, set base_url to the URL at which ?HyperKitty is accessible. With the nginx configuration done earlier, it would be http://lists.example.org/hyperkitty/. Use curl or a similar command to see that the URL is accessible.

Restart mailman3-web after the changes: 

$ sudo systemctl restart mailman3-web

Summary:

Creating mailing lists

Create a domain for the mailing list

Access http://lists.example.org and then click on the top-right "Sign In". On first login, Postorius sends an email-verification message.

After signing in as an administrator:

  1. Open Domains in the top navigation bar.

  2. Select Add Domain.

The domain must be associated with a web host. Select it from the Web Host drop-down list. If the required host is absent, follow the link in the form to edit the existing example.org entry or add a new web host. Then reload the domain form.

Create the mailing list

  1. Select Lists in the top navigation bar.

  2. Select Create New List.

  3. Enter the list details and select Create list.

After creating it, Postorius displays its administration interface and offers to subscribe you as an administrator. If you subscribe to the list, you will receive an email with a 'Welcome to the "NameMailingList" mailing list'.

You can also list the mailing lists from the server: 

$ sudo mailman-wrapper lists

Or the members: 

$ sudo mailman-wrapper members LIST_NAME

Configuring a mailing list

Postorius provides several administration tabs, including Info, Subscription requests, Held messages, Users, Templates, and Settings. Refer to the Mailman3 upstream documentation for more information if needed.

Migration of Mailman 2.1 lists

Before starting the migration, ensure that the Mailman 3 installation is working and that the domain for the migrated list has been configured.

Import the list configuration and members

On the old server

Locate the list's config.pck file and mbox archive.

In a Debian-packaged Mailman 2.1 installation, they are normally located at:

An installation made directly from upstream sources might instead use:

Create a tar archive containing both files. Adjust the base directory if Mailman is installed under /usr/local/mailman: 

$ sudo tar -C /var/lib/mailman \
    -czf /var/tmp/mailman21-LIST_NAME.tar.gz \
    lists/LIST_NAME/config.pck \
    archives/private/LIST_NAME.mbox/LIST_NAME.mbox

Copy /var/tmp/mailman21-LIST_NAME.tar.gz to the new server.

On the new server

Create a temporary directory and extract the archive into it: 

$ sudo mkdir /var/tmp/mailman21-LIST_NAME
$ sudo tar -C /var/tmp/mailman21-LIST_NAME \
    -xzf /var/tmp/mailman21-LIST_NAME.tar.gz

On Debian, mailman-wrapper drops privileges and runs Mailman commands as the list user. Make that user the owner of the configuration file: 

$ sudo chown list:list \
    /var/tmp/mailman21-LIST_NAME/lists/LIST_NAME/config.pck

Without the appropriate ownership or permissions, mailman-wrapper import21 might report the following error, even when invoked using sudo: 

Error: Invalid value for 'PICKLE_FILE': 'lists/LIST_NAME/config.pck': Permission denied

Create the list in Mailman 3: 

$ sudo mailman-wrapper create LIST_NAME@lists.example.org
Created mailing list: LIST_NAME@lists.example.org

Import the Mailman 2.1 configuration and membership information into the newly created list: 

$ sudo mailman-wrapper import21 LIST_NAME@lists.example.org \
    /var/tmp/mailman21-LIST_NAME/lists/LIST_NAME/config.pck
Importing members     [####################################]  100%
Importing owners      [####################################]  100%
Importing moderators  [####################################]  100%
Importing defers      [####################################]  100%
Importing holds       [####################################]  100%
Importing rejects     [####################################]  100%
Importing discards    [####################################]  100%

{i} No email messages are sent during this import.

The imported list and its members should now appear in Postorius. They can also be verified from the command line: 

$ sudo mailman-wrapper lists
$ sudo mailman-wrapper members LIST_NAME@lists.example.org

Import the list archive

Ensure that the www-data user can read the mbox file: 

$ cd /var/tmp/mailman21-LIST_NAME
$ sudo chown www-data:www-data archives/private/LIST_NAME.mbox/LIST_NAME.mbox

Import the archive into HyperKitty: 

$ sudo -u www-data /usr/share/mailman3-web/manage.py \
    hyperkitty_import \
    -l LIST_NAME@lists.example.org \
    /var/tmp/mailman21-LIST_NAME/archives/private/LIST_NAME.mbox/LIST_NAME.mbox
Importing from mbox file ... to LIST_NAME@lists.example.org
Importing from mbox file archives/private/LIST_NAME.mbox/LIST_NAME.mbox to LIST_NAME@lists.example.org
Computing thread structure
Synchronizing properties with Mailman
XX emails left to refresh, checked 0
Warming up cache
The full-text search index is not updated for this list. It will not be updated by the 'minutely' incremental update job. To update the index for this list, run the Django admin command with arguments 'update_index_one_list folreimanilles@mailman.pinux.info'.

The import does not update the full-text search index. Update it separately: 

$ sudo -u www-data /usr/share/mailman3-web/manage.py \
    update_index_one_list LIST_NAME@lists.example.org
Indexing XXX emails

Finally, open the list in HyperKitty and verify that the imported messages, dates and threads are displayed correctly.

Troubleshooting

Some email providers publish restrictive DMARC policies that instruct receiving mail servers to reject or modify messages when the sender's domain does not match the server that sent the message. As a result, messages sent through a mailing list may be rejected by some recipients or delivered with warnings.

Mailman3 provides several ways to mitigate these problems. One simple approach is to always rewrite the From: header so that messages appear to come from the mailing list address instead of the original sender. Although this changes the visible sender address, it avoids many DMARC-related delivery issues.

To enable this behaviour, in the mailing list administration interface go to Settings → DMARC Mitigations and configure:

This is not necessarily the best configuration for every mailing list, but it is likely the easiest one to mitigate DMARC-delivery problems.

Refer to Mailman3 DMARC Mitigations for more information.

Accessing logs

In a default Debian trixie installation, the Postfix logs can be displayed using: 

$ sudo journalctl -u postfix -f

For the Mailman3 core logs: 

$ sudo tail -f /var/log/mailman3/*

For the Mailman3 Postorius logs: 

$ sudo tail -f /var/log/mailman3/web/*

For the nginx logs: 

$ sudo tail -f /var/log/nginx/*

Or the nginx logs for the Mailman3 virtual host: 

$ sudo tail -f /var/log/nginx/mailman3/*

CategoryNetwork CategorySoftware