85.1.33. pepsi-stage-edit-settings

change per-address settings from a control e-mail

Section du manuel:

1

85.1.33.1.1. Nom

pepsi-stage-edit-settings - l’étape des paramètres par e-mail du pipeline Pepsi.

85.1.33.1.2. Synopsis

pepsi-stage-edit-settings [GLOBAL-OPTIONS] worker

85.1.33.1.3. Description

pepsi-stage-edit-settings est un programme d’étape exécuté par pepsi-dispatch(1) comme un worker persistant lisant les identifiants de message sur l’entrée standard. Il charge cette ligne pepsi.workqueue (refusant d’agir sauf si son status est running), lit sa section [stage-<stage>], et décide si le message est un message de contrôle de paramètres qu’un propriétaire de compte a envoyé pour changer ses propres paramètres par adresse (les redéfinitions pepsi.settings décrites dans pepsi-settings(1)).

Un message est un message de contrôle seulement lorsque toutes ces conditions tiennent :

  • il est émis localement (state.local_origin vaut true) et possède un expéditeur d’enveloppe non vide (un message à expéditeur nul n’est jamais un message de contrôle) ;

  • son Subject: est exactement SUBJECT (par défaut Pepsi) ; et

  • l’un de ses destinataires d’enveloppe est <CONTROL_LOCAL_PART>@<domain> (partie locale par défaut pepsi) pour un domain que l’instance accepte ([pepsi-ingress] ACCEPTED_DOMAINS).

Tout autre message est avancé inchangé vers NEXT_STAGE, de sorte que l’étape peut être placée sans risque n’importe où sur le chemin de soumission locale.

Décider si un message est un message de contrôle — d’origine locale, le bon Subject, adressé à la partie locale de contrôle sur un domaine accepté — ne nécessite que les métadonnées du message, jamais le corps. Cette étape participe donc à la fusion d’étapes (voir pepsi-dispatch(1)) avec une barrière dépendante des données : elle a FUSION = yes par défaut et un prédécesseur la fusionne dans son processus pour chaque message qui n’est pas de contrôle (qu’elle ne fait qu’avancer), mais décline la fusion pour un véritable message de contrôle, qui est alors validé puis dispatché comme son propre worker afin que le corps complet soit chargé pour l’analyse. Réglez FUSION = no pour vous en exclure.

L’adresse dont les paramètres sont édités est l”expéditeur d’enveloppe — le propriétaire édite ses propres paramètres, et la réponse lui est renvoyée par e-mail. (L’authentification de soumission de l’opérateur doit donc lier l’expéditeur d’enveloppe ; sinon, un utilisateur authentifié pourrait éditer les paramètres d’une autre adresse.)

85.1.33.1.4. Le corps

Le corps du message est lu comme un extrait INI indulgent : des en-têtes de section [stage-<name>] et des affectations OPTION = value. Les lignes vides, les commentaires (#/%/;), une salutation en tête et une signature finale (une ligne --) sont ignorés, de sorte qu’un e-mail ordinaire contenant la configuration fonctionne. Chaque affectation ajoute ou remplace la redéfinition stockée pour l’option de cette étape ; une affectation dont la valeur est vide (OPTION =) supprime la redéfinition, ramenant l’option à sa valeur INI par défaut.

Seules les sections dont le nom d’étape apparaît dans EDITABLE_STAGES peuvent être modifiées ; un corps adressant toute autre section est rejeté.

Par sécurité, une affectation qui règle le PROGRAM d’une étape n’est acceptée que lorsque sa valeur est une commande pepsi-stage-* (sans composant de chemin), de sorte qu’un propriétaire de compte ne peut pas rediriger une étape vers un exécutable arbitraire ; et une affectation qui règle SIGNING_DOMAIN est refusée d’emblée, si permissif que soit EDITABLE_STAGES. Cette option redéfinit le domaine sous lequel un message est signé en DKIM : l’autoriser permettrait à n’importe quel propriétaire de compte de faire signer son courrier sous n’importe quel domaine dont cet hôte détient une clé. Régler UNRESTRICTED_UNSAFE_STAGES = YES dans la configuration de l’étape lève les deux restrictions (non sûr ; la valeur par défaut est NO).

Pour la même raison, pepsi-setup --wizard ne met jamais une étape de signature dans EDITABLE_STAGES : il n’y liste que les barrières entrantes et le répondeur d’absence, et lorsque aucune d’elles n’est activée, il ne configure pas du tout cette étape.

Les paramètres combinés qui en résultent — les valeurs par défaut INI, plus les surcharges existantes de l’adresse, plus les nouvelles affectations — sont validés en exécutant l’analyseur de configuration propre à chaque étape concernée, plus les vérifications qui ne s’appliquent qu’au choix propre d’un propriétaire de compte : le WHITELIST_NAME d’une étape qui écrit une whitelist pour le compte du propriétaire – pepsi-stage-auto-whitelist(1), qui enregistre les destinataires de son courrier sortant, et pepsi-stage-secretary(1), qui enregistre les expéditeurs qui répondent à un défi – doit nommer une whitelist dans l’espace de noms <login>/... propre à l’expéditeur, ou celle que la configuration de l’opérateur nomme déjà pour lui ; une whitelist partagée ou celle d’un autre utilisateur est refusée. Le login est résolu avec les options de localité (LOCAL_DOMAINS, RECIPIENT_DELIMITER, TARGETS) de la section d’étape de l’opérateur, et non avec une quelconque surcharge propre au propriétaire. La règle ne s’applique que lorsque le message change la whitelist qu’alimente le courrier de l’expéditeur, de sorte qu’une valeur déjà stockée dans la ligne – que l’opérateur a pu définir avec pepsi-settings(1) – n’empêche pas le propriétaire de modifier d’autres options. Cette étape est le seul moyen pour un propriétaire de compte d’écrire dans pepsi.settings ; c’est donc là que la règle est appliquée ; les propres couches de l’opérateur (le fichier INI, pepsi.config_override à n’importe quelle portée, et les lignes écrites avec pepsi-settings(1)) peuvent nommer n’importe quelle whitelist. Les paramètres sont jugés par-dessus la configuration de l’opérateur pour l’expéditeur, surcharges domain: et address: de pepsi.config_override comprises, et la réponse cite cette même configuration effective. Si quoi que ce soit est invalide, aucune modification n’est faite et une réponse lisible explique chaque problème. Si tout est valide, les surcharges fusionnées sont stockées et une réponse cite l’ensemble complet des options effectives (valeurs par défaut plus surcharges) de chaque étape modifiable, en syntaxe INI.

Une étape listée dans EDITABLE_STAGES voit toute sa configuration effective citée en retour à tout propriétaire de compte qui envoie un message de contrôle, pas seulement les options qu’il a modifiées. Les valeurs d’options dont le nom semble porteur d’identifiants (PASSWORD, PASSPHRASE, SECRET, TOKEN, CREDENTIAL, CLIENT_ID, PEPPER) sont remplacées par ***, le même masquage qu’applique GET /api/v1/config — mais le reste de la section, y compris les noms d’hôtes et les chemins de fichiers, est divulgué verbatim. Ne listez pas une étape dont la section porte quoi que ce soit que vous ne montreriez pas à un utilisateur local.

L’une ou l’autre réponse porte Subject: SUBJECT, l’expéditeur d’enveloppe nul <> (RFC 3834, de sorte qu’elle n’est jamais elle-même soumise à une barrière et ne rebondit jamais), et est injectée à RESPONSE_STAGE (où elle est signée en DKIM et relayée comme tout courrier sortant). Le message de contrôle lui-même est ensuite supprimé.

La prose d’encadrement des deux réponses est localisée : elle est rendue depuis le modèle Mustache edit-settings.<lang>.body personnalisable par l’opérateur sous [pepsi] TEMPLATE_DIR, choisissant <lang> parmi la ou les langues détectées de l’expéditeur (la chaîne Accept-Language state.language posée par pepsi-stage-detect-language) et retombant toujours sur l’anglais (edit-settings.en.body). Les branches {{#success}} / {{^success}} du modèle encadrent, respectivement, l’écho des paramètres effectifs et la liste des problèmes.

Cette étape charge le corps du message mais ne le modifie pas.

85.1.33.1.5. Configuration

Les options résident dans la propre section [stage-<name>] de l’étape (PROGRAM = pepsi-stage-edit-settings) : la liste d’autorisation EDITABLE_STAGES obligatoire (qui doit nommer au moins une étape existante), le RESPONSE_STAGE obligatoire auquel la réponse est injectée, et un NEXT_STAGE pour le courrier ordinaire — obligatoire lui aussi, puisque pepsi-setup(1) refuse une section qui en est dépourvue : tout message autre qu’un message de contrôle y est avancé. Les paramètres de contrôle facultatifs SUBJECT/CONTROL_LOCAL_PART/RESPONSE_FROM et l’interrupteur de sécurité UNRESTRICTED_UNSAFE_STAGES complètent la section. Ils sont documentés dans pepsi.conf(5).

L’étape lit sa propre section depuis la configuration de base, jamais à travers la couche de surcharge par adresse, de sorte qu’aucune ligne pepsi.settings d’un titulaire de compte ne peut changer ce que cette étape considère comme un message de contrôle ni ce qu’elle autorise.

85.1.33.1.6. État

Entrées : state.local_origin (conditionne si le message est un message de contrôle), state.language (choisit la langue de la réponse), et l’expéditeur/les destinataires d’enveloppe et l’en-tête Subject:.

Sorties : l’étape réécrit la ligne pepsi.settings de l’expéditeur d’enveloppe et injecte une réponse ; elle ne modifie pas le state du message original (qu’elle supprime). La disposition de l’état est décrite dans pepsi.state(7).

Transitions :

  • un message ordinaire (pas d’origine locale, ou ne correspondant pas à SUBJECT / CONTROL_LOCAL_PART) → avancer vers NEXT_STAGE inchangé ;

  • un message de contrôle → injecter la réponse (l’écho INI en cas de succès, ou l’erreur sur une édition rejetée/invalide) à RESPONSE_STAGE et terminer (la ligne d’origine est supprimée).

L’étape ne met jamais en pause, n’échoue ni ne réachemine.

La confirmation est rendue avant que les nouveaux paramètres ne soient stockés, de sorte qu’un modèle de réponse manquant est réessayé sans que rien n’ait changé. Une fois ceux-ci stockés, une réponse qui ne peut pas être mise en file est journalisée et la requête supprimée : le changement est fait, et ne doit pas être refait.

85.1.33.1.7. Commandes

worker

Exécuté comme un worker persistant de pepsi-dispatch(1), lisant les identifiants de message sur l’entrée standard.

85.1.33.1.8. Options globales

-c FILE, –config FILE

Lit la configuration depuis FILE au lieu de parcourir les emplacements par défaut.

-L LOGLEVEL, –log LOGLEVEL

Règle la verbosité de journalisation (par défaut info).

-v, –verbose

Affiche les messages de journal de toutes les sources.

-h, –help ; -V, –version

Affiche un résumé d’utilisation / la version et quitte.

85.1.33.1.9. Code de sortie

0

Le message a été traité (laissé passer, ou appliqué/rejeté avec une réponse).

1

Une erreur s’est produite (message introuvable ou non running). La raison est écrite dans le journal.

Une défaillance de l’hôte (la base de données, un modèle ou un helper inutilisable) n’est pas signalée comme un échec : le message est mis en pause et réessayé, comme le décrit Erreurs d’étape dans pepsi-dispatch(1). Une section qui ne s’analyse pas fait refuser au worker de démarrer (statut 78) au lieu de faire échouer chaque message tour à tour.

85.1.33.1.10. Exemples

Une section de pipeline qui permet aux propriétaires d’éditer leur liste blanche et leur politique de langue, avec réponse via le chemin sortant

[stage-edit-settings]
PROGRAM = pepsi-stage-edit-settings
EDITABLE_STAGES = check-whitelist, block-language
RESPONSE_STAGE = dkim-sign
NEXT_STAGE = srs

Un corps d’e-mail de contrôle (Subject: Pepsi, To: pepsi@example.org) qui définit une liste blanche et efface une liste noire de langues

[stage-check-whitelist]
WHITELIST_NAME = my-contacts

[stage-block-language]
BLACKLIST =

85.1.33.1.11. Voir aussi

pepsi-settings(1), pepsi-config(1), pepsi-dispatch(1), pepsi-stage-check-whitelist(1), pepsi-stage-block-language(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)

85.1.33.1.12. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.