..
  This file is part of PEPSI.
  Copyright (C) 2026 GNUnet e.V.

  PEPSI is free software; you can redistribute it and/or modify it under the
  terms of the GNU Affero General Public License as published by the Free
  Software Foundation; either version 3, or (at your option) any later version.

==========
pepsi-list
==========

*Create and manage mailing lists, their members and their owners.*

Role
====

``pepsi-list`` is the operator's command-line tool for Pepsi's mailing-list
subsystem. It connects through the shared ``[pepsi-postgres]`` section and
reads its own ``[pepsi-list]`` section for the handful of settings that belong
to the *site* rather than to a list. Started as ``root`` it continues as the
``pepsi`` service account before connecting, so no ``sudo -u pepsi`` is needed.
It is **not** setuid and must not be made so. Reference:
:manpage:`pepsi-list(1)`.

This subsystem is a reimplementation of GNU Mailman 3; see
:doc:`../mailing-lists`, which says so at greater length and names what was
taken from upstream.

What it manages
===============

* **Domains** — the mail domains lists may be created in. Registering one here
  is separate from ``[pepsi-ingress] ACCEPTED_DOMAINS``, and a list in a domain
  ingress does not accept is a list whose mail is refused at ``RCPT``.
* **Lists** — creation from a *style*, and every one of the 99 attributes GNU
  Mailman 3.3.10's REST API exposes. ``list show`` prints them all;
  ``list show --explain`` adds each one's explanation.
* **Members and owners** — the four roles (``member``, ``owner``,
  ``moderator``, ``nonmember``). An owner gets a user account, because they
  sign in to the owner console; an ordinary subscriber does not need one.
* **Bans** — per list or site-wide, as an address or a ``^``-anchored regular
  expression.
* **Pepsi-only per-list settings** — ``list set-ext``. These are deliberately
  invisible to the REST API; :doc:`../mailing-lists` explains why.

Two things it deliberately does not do
======================================

**It does not ask permission.** ``members add`` subscribes an address without
a confirmation. That is what a command-line tool is for — migrating a roster,
fixing a mistake — and it is also why it is dangerous: the confirmation
workflow exists so that an address proves it wants to be there. The workflow is
what the ``-join`` address and the web form drive; this is the bottom of it.

**``owner reset-password`` prints the password rather than mailing it.** The
command-line path has to work when mail is broken, which is exactly when an
operator reaches for it. The ordinary way to change a password is the web reset
flow at ``/lists/reset``, which mails a link.

Checking a site
===============

``pepsi-list check`` validates what is silent in production. A misconfigured
stage target fails loudly the first time a message reaches it; a list with no
owner simply accumulates held messages nobody sees, and a list asking for more
trigram indexing than the site allows simply gets less. Each finding carries a
remedy.

.. code-block:: console

   $ pepsi-list check
   error: announce@lists.example.org: has no owner
       `pepsi-list owner add announce@lists.example.org <address>`, or set
       [pepsi-list] SITE_OWNER so its notices reach somebody
   note: site: archive search: full text and trigram (substring, fuzzy)

Configuration
=============

See :manpage:`pepsi.conf(5)`'s ``[pepsi-list]`` section, and
:doc:`../mailing-lists` for what each option decides.