95.1.34. pepsi-stage-edit-settings

change per-address settings from a control e-mail

Section du manuel:

1

95.1.34.1.1. Nom

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

95.1.34.1.2. Synopsis

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

95.1.34.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 la ligne pepsi.workqueue du message (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. Un message de contrôle qui a aussi des destinataires ordinaires est d’abord scindé : l’adresse de contrôle passe sur une ligne qui lui est propre, et les autres continuent comme du courrier ordinaire.

Les métadonnées du message suffisent pour décider s’il s’agit d’un message de contrôle (d’origine locale, avec le bon Subject, adressé à la partie locale de contrôle sur un domaine accepté) ; le corps n’est pas nécessaire. 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. Pour un véritable message de contrôle, l’étape décline la fusion : le message est validé puis confié à un worker de cette étape, 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. pepsi-ingress(1) le lie pour les logins SASL et par socket locale via USERNAME_MAP ; un réseau MYNETWORKS ou un certificat client épinglé n’est lié que lorsque SENDER_MAP le nomme.)

95.1.34.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é, trois sortes d’affectation sont restreintes :

  • 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), afin qu’un propriétaire de compte ne puisse pas rediriger une étape vers un exécutable arbitraire ;

  • une affectation qui règle une option nommant un programme qu’exécute l’étape ou un outil setuid est refusée sauf si sa valeur est vide, ce qui ne fait que rétablir le réglage de l’opérateur. Ces options sont HELPER (ce qu’une étape de remise exécute avec son privilège setgid), SCAN_HELPER, MAILBOX_HELPER et PIN_COMMAND ;

  • une affectation qui règle une option d’identité (SIGNING_DOMAIN, WALLET_MODE, WALLET_SCOPE ou WALLET_USER) ou une limite de dépense (MAX_TOTAL ou MAX_TOTAL_PER_DAY) est refusée d’emblée, si permissif que soit EDITABLE_STAGES.

SIGNING_DOMAIN 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 pour lequel cet hôte détient une clé. Les options de wallet choisissent le wallet depuis lequel paie pepsi-stage-auto-pay(1) ; les autoriser permettrait à un propriétaire de compte de dépenser depuis un wallet partagé avec d’autres. Les limites de dépense sont ce qui borne un mot de passe de soumission volé. Ce mot de passe authentifie aussi le message de contrôle ; autoriser la modification des limites permettrait donc au voleur de lever la borne. Régler UNRESTRICTED_UNSAFE_STAGES = YES dans la configuration de l’étape lève toutes ces 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, le répondeur d’absence et l’interrupteur de contenu distant (pepsi-stage-defang(1)), et lorsque aucun d’eux n’est activé, il ne configure pas du tout cette étape.

L’étape combine les valeurs par défaut INI, les surcharges existantes de l’adresse et les nouvelles affectations, puis valide le résultat en exécutant l’analyseur de configuration propre à chaque étape concernée. S’y ajoutent les vérifications qui ne s’appliquent qu’au choix propre d’un propriétaire de compte. Deux étapes écrivent 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. Le WHITELIST_NAME d’une telle étape 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. Une valeur déjà stockée dans la ligne, que l’opérateur a pu définir avec pepsi-settings(1), n’empêche donc 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 (contenant PASS, SECRET, TOKEN, CREDENTIAL, CLIENT_ID, PEPPER ou SYSTEM_ID, donc aussi PASSWORD et PASSPHRASE) sont remplacées par ***, le même masquage qu’applique GET /api/v1/config. Le reste de la section, en revanche, 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. Les étapes qu’il est sûr de lister sont exposées sous la frontière des paramètres dans le chapitre Modèle de menace du manuel (tm-settings) et dans son chapitre Sécurité.

L’une ou l’autre réponse porte Subject: SUBJECT et l’expéditeur d’enveloppe nul <> (RFC 3834, afin qu’elle ne soit jamais elle-même soumise à une barrière ni ne rebondisse). Elle 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). Dans le modèle, la branche {{#success}} encadre les paramètres effectifs cités et la branche {{^success}} encadre la liste des problèmes.

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

95.1.34.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. NEXT_STAGE est lui aussi obligatoire, 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.

95.1.34.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 ayant d’autres destinataires → scinder les adresses de contrôle sur une ligne qui leur est propre, et les deux lignes reviennent à cette étape ;

  • 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.

95.1.34.1.7. Commandes

worker

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

95.1.34.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 [pepsi] LOG, sinon 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.

95.1.34.1.9. Code de sortie

Le résultat de chaque message est rapporté à pepsi-dispatch(1) sur la ligne de statut du worker, et non par le code de sortie.

0

Le worker s’est exécuté jusqu’à la fermeture de son entrée standard.

1

Une erreur fatale s’est produite (configuration illisible, la base de données n’a pas pu être ouverte, ou l’entrée/sortie standard a échoué). La raison est écrite dans le journal.

78

Le worker a refusé de démarrer : une section [stage-*] qu’il sert ne s’analyse pas (par exemple un EDITABLE_STAGES ou un RESPONSE_STAGE manquant). Le dispatcher remet en file ce qu’il lui avait confié et réessaie l’étape plus tard.

Une défaillance de l’hôte (la base de données, un modèle de réponse 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).

95.1.34.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 =

95.1.34.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)

95.1.34.1.12. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.