85.1.46. pepsi-settings

manage per-address stage option overrides

Section du manuel:

1

85.1.46.1.1. Nom

pepsi-settings - définir, lister et supprimer les redéfinitions de configuration par adresse.

85.1.46.1.2. Synopsis

pepsi-settings [GLOBAL-OPTIONS] set ADDRESS STAGE OPTION VALUE

pepsi-settings [GLOBAL-OPTIONS] unset ADDRESS STAGE [OPTION]

pepsi-settings [GLOBAL-OPTIONS] import ADDRESS SOURCE

pepsi-settings [GLOBAL-OPTIONS] get ADDRESS

pepsi-settings [GLOBAL-OPTIONS] list [–json]

pepsi-settings [GLOBAL-OPTIONS] remove ADDRESS

85.1.46.1.3. Description

pepsi-settings est l’outil de l’opérateur pour la table pepsi.settings, qui permet de redéfinir par adresse e-mail les options d’une étape. Une étape lit normalement ses options depuis sa section [stage-<name>] dans le fichier de configuration ; la table de paramètres fournit des redéfinitions pour les messages vers ou depuis un correspondant particulier, la valeur INI servant de valeur par défaut pour toute option que la redéfinition ne mentionne pas.

Chaque ligne associe une adresse d’enveloppe en minuscules à un objet JSON dont les clés de premier niveau sont des noms de section d’étape (stage-<name>) et dont les valeurs sont des objets de OPTION vers valeur. Pour un message donné, l’adresse pertinente est l”expéditeur d’enveloppe lorsque le message provient localement (state.local_origin), sinon un destinataire d’enveloppe. L’adresse est mise en correspondance exactement (pas de repli par domaine ou sous-adresse).

Lorsque les destinataires d’un message entrant se résolvent en configurations effectives différentes pour l’étape sur le point de s’exécuter — que la différence vienne de cette table ou d’une portée domain:/address: de la surcouche en base —, le pipeline scinde de façon transparente le message en une ligne par configuration distincte, de sorte que chaque destinataire soit traité sous ses propres paramètres ; voir pepsi-dispatch(1).

Cet outil n’est pas une étape. Il se connecte à la même base de données que les autres composants via la section partagée [pepsi-postgres] et n’introduit aucune configuration propre. Démarré en tant que root, il poursuit sous le compte de service pepsi ; voir Exécution en tant que root.

85.1.46.1.3.1. Relation avec la surcouche de configuration en base de données

La table pepsi.settings est la couche supérieure de la chaîne de portées décrite dans pepsi.conf(5)

configuration file  <  global  <  domain:<d>  <  address:<a>  <  pepsi.settings

Les trois couches intermédiaires résident dans une table différente, pepsi.config_override, et se gèrent avec pepsi-config(1). Les deux ne sont délibérément pas fusionnées :

  • cette table est écrite par les titulaires de comptes eux-mêmes, depuis leur propre boîte aux lettres, via pepsi-stage-edit-settings(1), restreinte aux sections d’étape que l’opérateur a autorisées ;

  • config_override définit le pipeline et n’est modifiable qu’à travers le rôle PostgreSQL pepsi-config, que ne détient aucun composant traitant du courrier.

Les garder séparées est une frontière de sécurité et non une duplication : dans une seule table, un bogue dans la vérification de l’espace de noms par adresse cesserait d’être une fuite de redéfinition pour devenir un utilisateur reconfigurant le serveur de messagerie. pepsi-setup(1) vérifie les droits sur la base de données réelle après chaque installation.

Là où les deux mécanismes nomment la même option pour le même message, cette table l’emporte — c’est la couche supérieure, et ce qu’elle peut toucher est déjà borné par la liste d’autorisation EDITABLE_STAGES de l’opérateur.

Les vérifications que pepsi-stage-edit-settings(1) applique aux choix propres d’un propriétaire de compte sont faites là, lorsque le propriétaire écrit, et non lorsqu’une étape lit la ligne – une étape ne peut pas savoir qui l’a écrite. Cet outil est celui de l’opérateur et n’y est pas soumis : par exemple, il peut faire pointer le WHITELIST_NAME de pepsi-stage-auto-whitelist(1) ou de pepsi-stage-secretary(1) pour une adresse vers une whitelist partagée, qu’un propriétaire ne peut pas choisir lui-même. Un propriétaire qui modifie ensuite cette étape par courrier conserve la valeur stockée à moins de la changer.

85.1.46.1.4. Commandes

set ADDRESS STAGE OPTION VALUE

Définir une redéfinition d’option. STAGE est le label d’étape (par exemple check-whitelist ; un stage- initial est accepté et facultatif) et est stocké comme clé de section stage-<name> ; une étape sans section correspondante dans la configuration est refusée. VALUE est stockée comme une chaîne ; l’étape l’analyse exactement comme elle le ferait pour la valeur INI correspondante (donc un booléen utilise YES/NO, un nombre ses chiffres, et ainsi de suite). La ligne et la section d’étape sont créées selon les besoins.

unset ADDRESS STAGE [OPTION]

Supprimer une OPTION de la section STAGE de l’adresse. Avec OPTION omis, supprimer toute la section d’étape. Une section vidée, puis une ligne vidée, sont supprimées automatiquement.

import ADDRESS SOURCE

Remplacer l’objet de paramètres entier de l’adresse par le JSON lu depuis le fichier SOURCE, ou depuis l’entrée standard lorsque SOURCE est -. Le JSON doit être un objet dont les clés sont des noms de section stage-<name> et dont les valeurs sont des objets de scalaires JSON (chaîne, nombre ou booléen) ; les clés de section sont mises en minuscules.

get ADDRESS

Afficher l’objet de paramètres de l’adresse en JSON formaté, ou un avis si aucun n’existe.

list [–json]

Lister toutes les lignes. La sortie par défaut est une ligne address<TAB>JSON par ligne de la table ; –json émet à la place un tableau JSON d’objets {address, settings}.

remove ADDRESS

Supprimer entièrement la ligne de paramètres de l’adresse.

85.1.46.1.5. Validation

pepsi-setup(1) valide la table après avoir installé le schéma : chaque clé de premier niveau doit nommer une section [stage-<name>] existante, et chaque valeur d’option doit être un scalaire JSON (chaîne, nombre ou booléen). Une redéfinition indexée sur une section d’étape mal orthographiée est signalée comme une erreur plutôt qu’ignorée silencieusement.

85.1.46.1.6. Exécution en tant que root

Pepsi donne à chaque composant son propre rôle PostgreSQL, authentifié via la socket locale par le compte système sous lequel il s’exécute, et root n’en fait délibérément pas partie. Plutôt que d’échouer à se connecter et de vous obliger à penser à sudo -u pepsi pepsi-settings …, l’outil détecte qu’il a été démarré en tant que root et devient le compte de service non privilégié pepsi — le compte sous lequel l’échafaudage d’étape consulte pepsi.settings — avant de se connecter.

Tout ce qui se passe avant la connexion se passe toujours en tant qu’utilisateur appelant : le fichier de configuration (avec tout fragment @inline-secret@) est lu en premier, de même que le document JSON donné à import, de sorte qu’un chemin source lisible par root seul fonctionne.

Si le compte pepsi n’existe pas — une arborescence source non installée, un banc de test —, l’identité est laissée intacte, un avertissement est journalisé et la connexion est tentée en tant qu’utilisateur appelant, de sorte qu’une installation où root peut atteindre la base de données continue de fonctionner.

85.1.46.1.7. Options globales

Ces options globales précèdent la sous-commande (un indicateur placé à la fin est rejeté).

-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. LOGLEVEL est l’un de error, warn, info, debug ou trace. En l’absence de l’indicateur, l’option globale [pepsi] LOG s’applique, et à défaut info.

-v, –verbose

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

-h, –help

Affiche un résumé d’utilisation et quitte.

-V, –version

Affiche la version et quitte.

85.1.46.1.8. Code de sortie

0

Achèvement réussi.

1

Une erreur s’est produite : un fichier de configuration malformé, un JSON invalide, une connexion ou requête de base de données échouée, ou une étape sans section [stage-<name>]. La raison est écrite dans le journal.

2

La ligne de commande elle-même était erronée (une option inconnue, une option globale écrite après la sous-commande, un argument manquant).

85.1.46.1.9. Fichiers

Lorsque –config n’est pas fourni, le premier fichier existant de la liste suivante est utilisé. Chaque composant Pepsi partage le même fichier de configuration, c’est donc la même liste que chacun parcourt :

  • $XDG_CONFIG_HOME/pepsi.conf

  • $HOME/.config/pepsi.conf

  • /etc/pepsi/pepsi.conf

  • /etc/pepsi.conf

Aucun autre fichier n’est lu ni écrit : toutes les redéfinitions résident dans la table pepsi.settings.

85.1.46.1.10. Exemples

Envoyer le courrier vers vip@example.com via une liste blanche différente

pepsi-settings -c /etc/pepsi/pepsi.conf set vip@example.com check-whitelist WHITELIST_NAME vips

Bloquer un ensemble de langues différent pour un destinataire

pepsi-settings -c /etc/pepsi/pepsi.conf set bob@example.org block-language BLACKLIST 'ru,zh'

Inspecter puis effacer les redéfinitions d’un destinataire

pepsi-settings -c /etc/pepsi/pepsi.conf get bob@example.org
pepsi-settings -c /etc/pepsi/pepsi.conf unset bob@example.org block-language BLACKLIST

Charger un objet entier depuis un fichier

pepsi-settings -c /etc/pepsi/pepsi.conf import vip@example.com /tmp/vip.json

85.1.46.1.11. Voir aussi

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

85.1.46.1.12. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.