85.1.47. pepsi-list

manage Pepsi’s mailing lists

Section du manuel:

1

85.1.47.1.1. Nom

pepsi-list – créer et gérer les listes de diffusion, leurs membres et leurs propriétaires.

85.1.47.1.2. Synopsis

pepsi-list [OPTIONS-GLOBALES] domain add|list|remove [ARGS]

pepsi-list [OPTIONS-GLOBALES] list create|show|set|set-ext|remove|find|styles [ARGS]

pepsi-list [OPTIONS-GLOBALES] members list|add|remove [ARGS]

pepsi-list [OPTIONS-GLOBALES] owner add|remove|reset-password [ARGS]

pepsi-list [OPTIONS-GLOBALES] import mailman3|mailman21 [ARGS]

pepsi-list [OPTIONS-GLOBALES] invite send|status [ARGS]

pepsi-list [OPTIONS-GLOBALES] digest send|bump|periodic|status [ARGS]

pepsi-list [OPTIONS-GLOBALES] ban add|list|remove [ARGS]

pepsi-list [OPTIONS-GLOBALES] template list|set|clear [ARGS]

pepsi-list [OPTIONS-GLOBALES] unsub-token LIST EMAIL [–serial N] [–uri]

pepsi-list [OPTIONS-GLOBALES] tasks –once

pepsi-list [OPTIONS-GLOBALES] check [–strict]

85.1.47.1.3. Description

pepsi-list est l’outil en ligne de commande de l’exploitant pour le sous-système de listes de diffusion de Pepsi. Ce n’est pas une étape : il lit et écrit directement les tables de listes du schéma pepsi, à la manière de pepsi-whitelist(1) et de pepsi-settings(1).

Le sous-système de listes de diffusion de Pepsi est une réimplémentation de GNU Mailman 3. Son modèle de données, son architecture rule/chain et handler/pipeline, son API REST, son vocabulaire de commandes par e-mail et les noms de ses modèles de notification sont la conception du projet GNU Mailman, dont la Free Software Foundation détient les droits, et Pepsi existe pour être compatible avec eux. La documentation d’amont, à l’adresse <https://docs.mailman3.org>, décrit des notions qui s’appliquent directement ici et mérite d’être lue en parallèle de cette page. Certains fichiers de Pepsi sont repris de GNU Mailman, Postorius ou HyperKitty et demeurent sous la GNU General Public License ; vendor/PEPSI-VENDORING.md les recense.

La configuration par liste réside dans la base et non dans pepsi.conf(5). Les listes sont créées à l’exécution, potentiellement par milliers, par des personnes qui ne sont pas l’exploitant ; le fichier de configuration ne contient que ce que l”exploitant possède, dans la section [pepsi-list].

85.1.47.1.4. Options globales

Les drapeaux globaux se placent avant la sous-commande, comme partout ailleurs dans Pepsi :

-c, --config FICHIER

Fichier de configuration à lire.

-L, --log NIVEAU

Niveau de journalisation.

-v, --verbose

Affiche les messages de journal de toutes les sources, y compris les bibliothèques tierces.

-V, --version

Affiche la version et quitte.

85.1.47.1.5. Nommer une liste

Chaque verbe qui prend une liste accepte les deux graphies :

name@domain

L’adresse d’envoi, celle que les gens saisissent.

name.domain

Le list_id d’amont, avec un point. C’est l’identifiant que l’API REST emploie, et il n’est pas interchangeable avec l’adresse d’envoi – les deux apparaissent dans l’API, et écrire le mauvais est un bogue de compatibilité.

85.1.47.1.6. Commandes

domain add DOMAIN [–base-url URL] [–description TEXTE]

Enregistre un domaine de courrier dans lequel des listes peuvent être créées. Ce n’est pas la même chose que le ACCEPTED_DOMAINS de pepsi-ingress(1) : un domaine peut accepter du courrier sans héberger de listes. Si un domaine de listes n’est pas accepté par ingress, le courrier destiné à la liste est refusé au RCPT et rien dans les journaux de ce sous-système ne le dit.

domain list

Affiche les domaines de listes et le nombre de listes que chacun contient.

domain remove DOMAIN

Retire un domaine de listes. Refusé tant qu’il contient encore des listes : le supprimer cascaderait à travers la liste des membres, les messages retenus et les archives de chaque liste.

list create ADRESSE [–style STYLE] [–set NOM=VALEUR]…

Crée une liste de diffusion. --style applique un ensemble nommé de valeurs d’attributs par défaut avant tout --set ; voir Styles plus bas. Un nom de style inconnu est une erreur, non une opération vide silencieuse.

list show ADRESSE [–explain]

Affiche chacun des 99 attributs REST avec sa valeur courante. --explain ajoute l’explication d’une ligne de chaque attribut. (Le drapeau est --explain et non --help parce que ce dernier appartient à l’analyseur d’arguments.)

list set ADRESSE NOM VALEUR

Pose un attribut. La valeur passe par le même validateur que l’API REST et la console du propriétaire : les trois ne peuvent donc pas être en désaccord sur ce qu’est une valeur valide. Les attributs à valeurs multiples prennent une entrée par ligne ; la virgule n’est pas un séparateur, car une expression rationnelle peut en contenir une.

list set-ext ADRESSE CLÉ VALEUR

Pose un réglage par liste propre à Pepsi. Ceux-ci sont délibérément invisibles pour l’API REST de Mailman : le PUT d’amont, qui porte sur la ressource entière, exige que chaque attribut modifiable soit présent, si bien qu’un client bâti contre Mailman 3.3.10 omettrait tout ce que Pepsi a inventé et serait rejeté. Une valeur vide restaure le défaut du serveur. Les clés sont search_trigram, archive_show_addresses et archive_retention_days.

list remove ADRESSE –yes

Supprime une liste, sa liste des membres, ses messages retenus et ses archives. --yes est obligatoire.

list find [SOUS-CHAÎNE]

Énumère les listes de diffusion, éventuellement celles qui correspondent à une sous-chaîne.

list styles

Affiche les styles et leurs alias.

members list ADRESSE [–role RÔLE]

Affiche la liste des membres d’une liste. RÔLE vaut member, owner, moderator ou nonmember.

members add ADRESSE EMAIL [–display-name NOM] [–role RÔLE]

Abonne une adresse. Cela contourne entièrement la politique d’abonnement, ce à quoi sert un outil en ligne de commande et ce qui le rend dangereux : tout l’intérêt du flux de confirmation est qu’une adresse prouve qu’elle veut être là. Employez-le pour migrer un effectif ou corriger une erreur, non pour ajouter des gens qui n’ont rien demandé.

members remove ADRESSE EMAIL [–role RÔLE]

Désabonne une adresse d’un rôle.

owner add ADRESSE EMAIL

Fait d’une adresse un propriétaire. Contrairement à un simple abonné, un propriétaire obtient un compte utilisateur, puisqu’il se connectera à la console du propriétaire.

owner remove ADRESSE EMAIL

Retire un propriétaire.

owner reset-password ADRESSE EMAIL [–password MOT-DE-PASSE]

Pose le mot de passe du compte d’un propriétaire et l”affiche. Il affiche au lieu d’envoyer à dessein : ce chemin doit fonctionner quand le courrier est en panne, c’est-à-dire précisément quand un exploitant en a besoin.

La façon ordinaire de changer un mot de passe est le flux de réinitialisation web à /lists/reset, qui envoie un lien et jamais un mot de passe – un mot de passe envoyé est un mot de passe qui reste pour toujours dans une boîte. Cette sous-commande est l’issue de secours pour le cas que ce flux ne peut pas couvrir : l’adresse du compte ne reçoit pas de courrier, ou rien sur la machine n’en remet. Elle pose le même list_user.password_hash que le flux web, avec les mêmes paramètres Argon2, et, comme un changement de mot de passe fait dans le navigateur, elle met fin à toutes les sessions ouvertes de ce compte.

ban add MOTIF [–list ADRESSE]

Interdit une adresse, ou une expression rationnelle commençant par ^. Sans --list, l’interdiction vaut pour tout le serveur.

ban list [–list ADRESSE]

Affiche les interdictions.

ban remove MOTIF [–list ADRESSE]

Lève une interdiction.

tasks –once

Exécute une fois les passes périodiques puis quitte : les passes de rejet qui avertissent puis retirent, l’éviction des événements de rejet traités ([pepsi-list] BOUNCE_EVENT_RETENTION), l’expiration des messages retenus selon max_days_to_hold, les balayages des jetons de confirmation expirés et des pierres tombales de suppression, et le balayage de rétention des archives. C’est ce que l’unité pepsi-list-tasks.timer exécute chaque jour. --once est obligatoire : sans cette option la commande refuse, car la planification appartient au timer et non à une boucle dans ce programme.

Tout ce qui, dans le sous-système, se produit selon un calendrier est ici, et chaque partie en est invisible lorsque la minuterie ne tourne pas : un membre dont le score de bounce a franchi le seuil est désactivé par l’étape de rejet, et les avertissements comme le désabonnement final appartiennent à cette passe – un déploiement qui en est dépourvu désactive des membres puis ne les avertit ni ne les retire jamais.

Note

tasks --once rejette aussi les messages retenus plus anciens que le max_days_to_hold de leur liste. Cet attribut est inerte dans GNU Mailman 3 – un grep de tout son arbre hors tests trouve la colonne, la valeur par défaut du style et le validateur REST, et aucune tâche qui le lise – et il est actif ici. C’est un sur-ensemble strict : le défaut 0 signifie « n’expire jamais », ce qui est ce qui se produit en amont, rien ne change donc pour une liste qui n’y touche pas. Chaque rejet est écrit au journal d’audit, et les modérateurs sont informés une fois par passe avec un décompte, et non une fois par message.

Note

Le balayage de rétention des archives supprime les messages archivés de chaque liste plus anciens que sa rétention, exactement comme le ferait pepsi-archive expire (les fils et les compteurs sont réparés ensuite). La rétention est résolue par liste : le propre archive_retention_days d’une liste (réglé avec list set-ext) l’emporte, 0 compris ; une liste qui n’en a pas utilise [pepsi-list] ARCHIVE_RETENTION, dont la propre valeur par défaut est 0 ; et 0 conserve tout. Une valeur stockée qui n’est pas un nombre de jours est ignorée avec un avertissement plutôt que devinée.

check [–strict]

Valide la configuration de chaque liste et celle de l’installation. Chaque constat est une error, un warning ou une note, avec un remède lorsqu’il y en a un évident. Sort avec un état non nul sur une erreur, et aussi sur un avertissement avec --strict.

import mailman3 –rest URL [–user NOM] [–password-file FICHIER] [–dry-run] [–report FICHIER]

Importe un site GNU Mailman 3 en fonctionnement via sa propre API REST : domaines, listes attribut par attribut, utilisateurs, adresses (en conservant leur verified_on), membres, interdictions, règles d’en-tête et URI de modèles.

REST est le chemin par défaut et non le recours, parce qu’il fonctionne contre un site en marche, n’exige aucune connaissance du schéma d’amont, et est à l’abri des migrations d’amont. C’est aussi ce qui rend l’import vérifiable : les deux extrémités répondent à /3.1/lists/<id>/config, une comparaison attribut par attribut est donc possible.

Préférez --password-file à --password : un argument est visible par tout autre processus de la machine.

import mailman21 –listdir RÉP [–list NOM] [–domain HÔTE] [–dry-run] [–report FICHIER]

Importe un site Mailman 2.1 depuis son répertoire lists/, en lisant chaque config.pck. La correspondance des attributs est celle de GNU Mailman lui-même – les dix-huit renommages, les tables entier-vers-énumération, les deux fusions de booléens, la règle de préséance DMARC et le champ de bits user_options sont transcrits depuis le utilities/importer.py d’amont.

--domain fournit l’hôte de courrier pour un pickle qui n’en nomme aucun.

Note

pepsi-list démarre en root et passe immédiatement à l’utilisateur de service ``pepsi`` : un chemin --report doit donc être un chemin que cet utilisateur peut écrire. --report /root/import.txt échoue sur une erreur de permission et ne produit aucun rapport ; /tmp ou un répertoire possédé par pepsi fonctionne. Sans --report, le rapport complet va sur la sortie standard, il n’est donc jamais perdu.

import mailman21 –json FICHIER [–list NOM]

L’issue de secours. Ce lecteur ne construit rien – aucun module n’est cherché et aucun appelable n’est appelé, car une config.pck vient du serveur de quelqu’un d’autre. Le prix en est la rigueur : lorsqu’il refuse un fichier, lancez contrib/mm21-export.py sur l’ancien serveur avec le Python de ce serveur et donnez le JSON ici. Les deux voies passent par la même correspondance.

invite send [–list ADRESSE] [–rate N] [–limit N] [–dry-run]

Invite tous ceux qui n’ont pas de mot de passe à en choisir un. import n’envoie délibérément rien : c’est donc ce verbe qui décide du moment où le plus gros envoi que le serveur fera jamais a réellement lieu.

--rate vaut par défaut [pepsi-list] INVITE_RATE (300 par heure). --dry-run affiche l”histogramme par domaine, qui est un outil de délivrabilité et non une barre de progression : un fournisseur détenant la moitié d’un site migré est ce qui décide du rythme. La campagne reprend là où elle s’est arrêtée – une adresse ayant une invitation valide est sautée – et les invitations durent quatre semaines, car une invitation rivalise avec des vacances et non avec une soirée.

invite status [–list ADRESSE]

Combien de comptes ont un mot de passe, combien ont une invitation en cours, et combien restent à inviter. Personne n’est jamais désabonné pour n’avoir pas répondu.

digest send ADRESSE

Envoie maintenant le résumé accumulé d’une liste, quoi que dise digest_size_threshold. Un exploitant qui demande une livraison a déjà décidé.

digest bump ADRESSE

Fait avancer le volume et remet le numéro à 1 sans envoyer, ce qui est le --bump d’amont. Ce qu’un propriétaire fait en début d’année, ou après une livraison partie de travers.

digest periodic

Envoie chaque liste dont le résumé est dû : au-delà de digest_size_threshold, ou dès qu’il y a accumulation lorsque digest_send_periodic est actif. C’est le verbe de la minuterie. Amont n’a aucun exécutant périodique pour les résumés – maybe_send_digest_now se déclenche de façon synchrone sur un message dès le franchissement du seuil, et mailman digests --send est censé être mis dans le cron par l’exploitant. Pepsi conserve les deux moitiés et place la seconde sur une minuterie systemd, le même agencement que tasks --once.

digest status [ADRESSE]

Ce que chaque liste a accumulé, et si elle est due.

template list

Affiche les 28 noms de modèles d’avis, et toute redéfinition d’URI réglée pour eux au niveau du site, du domaine ou de la liste.

template set NAME URI [–list ADDRESS | –domain DOMAIN] [–user USER] [–password PASSWORD]

Fait pointer un modèle vers une URI : mailman: (le texte intégré) ou une URL http(s):, éventuellement avec des identifiants HTTP Basic. Sans --list ni --domain, la redéfinition s’applique à tout le site. Une URI http(s): est récupérée par le serveur, dans les limites de [pepsi-list] TEMPLATE_FETCH_TIMEOUT, TEMPLATE_FETCH_MAX_BYTES et TEMPLATE_FETCH_ALLOW_INTERNAL. Une URI file: est refusée, ici comme sur tout autre chemin d’écriture (l’API REST et les importateurs), car elle ferait lire au serveur son propre disque ; une ligne file: déjà présente dans la table n’est jamais lue, et l’avis est rendu comme si elle était absente.

template clear NAME [–list ADDRESS | –domain DOMAIN]

Retire une redéfinition, de sorte que le texte intégré soit de nouveau utilisé.

unsub-token LIST EMAIL [–serial N] [–uri]

Affiche le jeton de désabonnement en un clic RFC 8058 que porterait une remise à EMAIL, calculé par le même code qui le frappe ; --uri affiche à la place l’URI https: complète. --serial signe un numéro de série d’abonnement donné plutôt que celui actuel du membre. Nécessite [pepsi-list] UNSUBSCRIBE_SECRET. Il ne divulgue rien que le membre n’ait déjà dans sa boîte aux lettres.

85.1.47.1.7. Verbes réservés

Trois verbes sont listés par --help et répondent en indiquant où la capacité se trouve réellement, plutôt que par « sous-commande inconnue » :

held, requests

Modérer les messages retenus et les demandes d’abonnement n’est pas implémenté en ligne de commande. Cela se trouve dans la console du propriétaire à /lists/<list-id>/admin (pepsi-httpd(1)), via l’API REST, et par courrier à list-request.

inject

Non implémenté, et inutile : écrivez à l’adresse propre de la liste avec pepsi-sendmail(1) ou n’importe quel client SMTP. Un message injecté par un verbe ici et un message envoyé normalement passeraient de toute façon par la même étape.

Ces verbes répondent avant toute tentative de connexion à la base : la réponse est donc la même sur une machine dépourvue de schéma de listes.

85.1.47.1.8. Styles

Un style est un ensemble nommé de valeurs d’attributs par défaut, appliqué à la création d’une liste. GET /3.0/lists/styles en rapporte trois, qui sont ceux d’amont, avec les noms et descriptions d’amont :

legacy-default

Style de liste de discussion ordinaire. Le style par défaut. Également accepté comme discussion ou default.

legacy-announce

Style de liste d’annonces seulement – les membres ne peuvent pas écrire. Également accepté comme announce-only ou announce.

private-default

Style de liste de discussion à archives privées ; non annoncée, et les abonnements exigent à la fois une confirmation et un modérateur. Également accepté comme private.

Un style de plus est propre à Pepsi ; il est accepté ici mais pas listé par REST, pour la même raison que les réglages par liste propres à Pepsi ne le sont pas :

moderated

Une liste de discussion sur laquelle chaque message de membre est retenu pour un modérateur.

85.1.47.1.9. État de sortie

0 en cas de succès, non nul en cas d’échec. check sort avec un état non nul lorsqu’il a trouvé une erreur (ou, avec --strict, un avertissement). import sort avec un état non nul lorsque quoi que ce soit n’a pas été repris, même si tout le reste a été écrit.

85.1.47.1.10. Fichiers

/etc/pepsi/pepsi.conf

Configuration ; voir pepsi.conf(5), section [pepsi-list].

85.1.47.1.11. Voir aussi

pepsi.conf(5), pepsi-setup(1), pepsi-settings(1), pepsi-whitelist(1).

La documentation de GNU Mailman 3 à <https://docs.mailman3.org>.