95.1.66. pepsi-config

inspect and edit the effective pepsi configuration

Section du manuel:

1

95.1.66.1.1. Nom

pepsi-config - consulter, développer, imprimer et modifier la configuration Pepsi fusionnée.

95.1.66.1.2. Synopsis

pepsi-config [GLOBAL-OPTIONS] get [-f | –filename] SECTION OPTION

pepsi-config [GLOBAL-OPTIONS] pathsub PATH-EXPR

pepsi-config [GLOBAL-OPTIONS] dump [-d | –diagnostics] [–origin [–scope SCOPE]]

pepsi-config [GLOBAL-OPTIONS] set [–scope SCOPE] SECTION OPTION VALUE

pepsi-config [GLOBAL-OPTIONS] unset [–scope SCOPE] SECTION [OPTION]

pepsi-config [GLOBAL-OPTIONS] list [–scope SCOPE] [–drafts]

pepsi-config [GLOBAL-OPTIONS] export [–from DIR] [–password-file FILE] ARCHIVE

pepsi-config [GLOBAL-OPTIONS] import [–into DIR] [–force] [–password-file FILE] ARCHIVE

95.1.66.1.3. Description

pepsi-config inspecte et modifie la configuration effective que partagent tous les composants Pepsi. Tous les composants lisent le même fichier de configuration de style INI (voir pepsi.conf(5)) et la même surcouche de configuration en base, de sorte que ce seul outil les sert tous.

Les commandes de lecture rapportent la configuration effective : le fichier amendé par la table pepsi.config_override. Pour get, pathsub et dump, une base inaccessible n’est pas une erreur, car un opérateur recourt le plus souvent à cet outil quand quelque chose ne va pas : la commande rapporte la configuration du fichier, et l’exécution réussit tout de même. Un échec de connexion est journalisé comme un avertissement. Lorsque la connexion réussit mais que la surcouche ne peut être lue, la commande journalise une erreur et rapporte quand même la configuration du fichier. dump –origin rapporte la configuration du fichier sans message lorsqu’il ne peut pas se connecter, et avec un avertissement lorsque la surcouche ne peut être lue. list fait exception : elle imprime les redéfinitions stockées, n’a donc rien à rapporter sans la base, et se termine avec un code non nul lorsque la connexion échoue ou que l’appelant ne détient pas le rôle pepsi-config.

Les commandes d’écriture (set, unset) ne modifient que la surcouche en base. Elles ne modifient jamais le fichier de configuration, qui reste celui de l’opérateur, et elles sont refusées à moins que l’appelant ne détienne le rôle PostgreSQL pepsi-config (pepsi-config adopte ce compte lorsqu’il est lancé en tant que root). Ce droit impose la règle suivante : aucun composant Pepsi qui traite du courrier ne peut écrire la configuration qui définit le pipeline dans lequel il s’exécute.

La chaîne de portées, et les sections qui peuvent résider en base, sont décrites dans pepsi.conf(5).

95.1.66.1.4. Commandes

get [-f | –filename] SECTION OPTION

Imprime la valeur effective de OPTION dans SECTION. Avec –filename, la valeur est interprétée comme un chemin et l’expansion $ est appliquée.

pathsub PATH-EXPR

Imprime PATH-EXPR avec les marqueurs ${VAR} et $VAR substitués depuis la section [PATHS] et l’environnement.

dump [-d | –diagnostics] [–origin [–scope SCOPE]]

Imprime la configuration fusionnée. Avec –diagnostics, montre aussi de quel fichier et de quelle ligne provient chaque option. Avec –origin, annote chaque valeur avec la couche qui l’a définie (file, ou la portée en base) et chaque section selon qu’un changement s’y applique à chaud ou exige un redémarrage ; –scope résout la chaîne pour un domaine ou une adresse donnés (global par défaut).

–scope n’a d’effet qu’associée à –origin. Sans celle-ci, la sortie est le fichier amendé par la seule couche de surcouche global, quoi que dise –scope (la valeur est tout de même analysée, de sorte qu’une portée malformée reste une erreur).

Les options porteuses d’identifiants sont masquées par *** : toute option des sections [pepsi-postgres] et [pepsi-admin], et toute option dont le nom contient PASS (donc PASSWORD, PASSPHRASE et [pepsi-list] API_PASS), SECRET, TOKEN, CREDENTIAL, CLIENT_ID, PEPPER ou SYSTEM_ID. KEY ne figure délibérément pas dans cette liste, afin qu’un chemin TLS_KEY reste affiché. La directive @inline-secret@ fusionne chaque fragment secrets.d/*.secret dans la configuration que cette commande rend. Un vidage non masqué lancé en tant que root imprimerait donc le secret SRS, le secret d’enveloppement de clés, le poivre du lien sécurisé et tout mot de passe de smarthost, et rediriger un vidage dans un rapport de bogue est la manière ordinaire dont un opérateur partage sa configuration. La commande emploie le même prédicat que l’API d’administration et l’écho des paramètres (pepsi_common::secrets::is_secret), de sorte que les trois s’accordent par construction. Lisez le fragment lui-même si vous avez besoin d’une valeur.

set [–scope SCOPE] SECTION OPTION VALUE

Stocke une redéfinition en base. SECTION est mise en minuscules et OPTION en majuscules avant toute autre chose, de sorte que l’orthographe employée sur la ligne de commande est sans importance. La commande valide d’abord la modification : elle construit la configuration que la modification produirait et lui applique l’analyseur de l’étape à laquelle appartient la section. Une valeur que cette étape rejetterait est refusée avec l’erreur de l’étape, et rien n’est stocké. La commande refuse de même, et ne stocke jamais, une section qui ne peut résider que dans le fichier de configuration ; une option porteuse d’identifiants dans n’importe quelle section (les identifiants ne sont jamais stockés en base) ; une option qui nomme un programme qu’exécute Pepsi (HELPER, SCAN_HELPER, MAILBOX_HELPER, PIN_COMMAND, et le PROGRAM d’une étape sauf s’il s’agit d’une simple commande pepsi-stage-*) ; et une SCOPE domain:/address: pour une section qui n’est pas [stage-*], puisque rien ne lit les autres sections par domaine ou par adresse (voir pepsi.conf(5)). L’API d’administration applique la même règle, et une ligne qui l’enfreint est ignorée à la lecture de la surcouche. set indique si le changement est à chaud ou exige un redémarrage, et consigne la modification dans le journal d’audit : qui l’a faite, quand et dans quelle portée, mais pas la valeur.

unset [–scope SCOPE] SECTION [OPTION]

Retire une redéfinition ou, sans OPTION, toutes les redéfinitions que la portée contient pour SECTION. Les options concernées reviennent à la couche inférieure suivante, en dernier ressort au fichier de configuration. Retirer quelque chose qui n’a jamais été positionné est signalé et n’est pas une erreur.

list [–scope SCOPE] [–drafts]

Imprime les redéfinitions stockées avec leurs horodatages et leurs auteurs. Contrairement à set et unset, –scope n’a ici pas de valeur par défaut : si aucune n’est donnée, toutes les portées sont listées. –drafts montre en plus les lignes en préparation, qu’aucun composant en fonctionnement ne lit.

export [–from DIR] [–password-file FILE] ARCHIVE

Écrit une archive chiffrée par mot de passe du répertoire de configuration (par défaut le répertoire contenant le fichier de configuration chargé) : le fichier de configuration, les éventuels fragments à côté de lui, et les fragments secrets de secrets.d. Les bits de permission de chaque fichier sont consignés numériquement, et son propriétaire et son groupe par nom (en retombant sur l’identifiant numérique lorsque le compte ne se résout plus). ARCHIVE peut être - pour la sortie standard ; les lignes de progression et de résumé vont sur la sortie d’erreur standard, de sorte que la sortie standard reste utilisable. Le fichier d’archive lui-même est créé avec le mode 0600. Seuls les fichiers ordinaires sont archivés : les liens symboliques ne sont pas suivis, et tout le reste est ignoré avec un avertissement. La commande refuse un fichier isolé de plus de 32 Mio, un mot de passe de moins de 12 caractères et un répertoire qui ne contient aucun fichier ordinaire. Ceci ne couvre délibérément pas la surcouche en base, que pg_dump sauvegarde déjà correctement.

import [–into DIR] [–force] [–password-file FILE] ARCHIVE

Restaure une archive écrite par export. ARCHIVE peut être - pour lire l’entrée standard. La propriété est restaurée, ce qui exige normalement root ; un fichier dont le propriétaire consigné n’existe pas sur cette machine est refusé, non deviné, et de même pour un fichier appartenant à un autre compte lorsque la commande n’est pas lancée en tant que root. Ces contrôles de propriété portent sur l’archive entière avant qu’un seul fichier ne soit écrit, de sorte qu’une restauration qui échoue sur eux n’écrit rien. Une entrée dont la cible existe déjà est refusée elle aussi, mais ce contrôle a lieu au moment où la restauration atteint l’entrée : il arrête la restauration au lieu de sauter le fichier. Les entrées qui la précèdent sont déjà écrites, et celles qui la suivent ne le sont pas. Passez –force pour écraser à la place. Restaurer dans un répertoire qui contient déjà un pepsi.conf demande donc soit –force, soit un répertoire –into vide. Les entrées d’archive nommant un chemin absolu ou un composant .. sont rejetées d’emblée.

export comme import ont besoin du mot de passe de l’archive. Avec –password-file, il est lu depuis FILE, qui ne doit pas être lisible par les autres (chmod 600) ni être vide ; sinon la commande le demande sur le terminal sans écho, et export le demande deux fois et refuse une discordance. export exige un mot de passe d’au moins 12 caractères (comptés en caractères, non en octets) et refuse un mot de passe qui figure sur la liste des mots de passe courants ou qui contient le nom de l’hôte : l’archive porte chaque fragment secret, clé de chiffrement des clés comprise, et quiconque en obtient une copie peut tester des hypothèses hors ligne à loisir, Argon2id ou non. import accepte le mot de passe, quel qu’il soit, avec lequel l’archive a été écrite. Lorsqu’aucun fichier de configuration n’a été trouvé, il n’y a aucun répertoire par défaut, et –from/–into devient obligatoire.

95.1.66.1.5. Portées

SCOPE vaut l’un de :

global

Tout le déploiement. La valeur par défaut pour set et unset.

domain:DOMAIN

Les messages dont l’adresse pertinente est à DOMAIN.

address:ADDRESS

Les messages dont l’adresse pertinente est exactement ADDRESS.

L’adresse pertinente est l’expéditeur d’enveloppe pour un message d’origine locale, sinon chaque destinataire d’enveloppe. La couche de paramètres par adresse emploie la même règle (pepsi-settings(1)).

95.1.66.1.6. 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 du drapeau, 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.

95.1.66.1.7. Code de sortie

0

Achèvement réussi.

1

Une erreur s’est produite, par exemple un fichier de configuration malformé, une SECTION/OPTION manquante, une valeur de redéfinition rejetée, une section qui ne peut résider que dans le fichier de configuration, un mot de passe d’archive erroné, ou des privilèges de base insuffisants pour une écriture. La raison est écrite dans le journal.

2

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

78

set, unset ou list a trouvé un schéma de base de données d’une autre version de Pepsi ; exécutez pepsi-setup schema (voir pepsi-setup(1)). Les commandes de lecture rapportent à la place la configuration du fichier, comme pour une base de données injoignable.

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

95.1.66.1.9. Exemples

Vérifier pour quels domaines le courrier est accepté

pepsi-config -c /etc/pepsi/pepsi.conf get pepsi-ingress ACCEPTED_DOMAINS

Imprimer la configuration fusionnée avec les annotations de source

pepsi-config -c /etc/pepsi/pepsi.conf dump --diagnostics

Montrer d’où vient chaque valeur effective

pepsi-config dump --origin

Augmenter la durée de vie en file d’une étape sans éditer de fichier ni redémarrer quoi que ce soit

pepsi-config set stage-relay MAX_LIFETIME '48 h'

Donner à un domaine un paramètre différent, puis le retirer

pepsi-config set --scope domain:example.org stage-relay DELAY_DSN_AFTER '4 h'
pepsi-config unset --scope domain:example.org stage-relay DELAY_DSN_AFTER

Sauvegarder tout ce qui n’est pas en base

pepsi-config export /root/pepsi-config-backup.pca

95.1.66.1.10. Voir aussi

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

95.1.66.1.11. Bogues

Signalez les bogues au gestionnaire de tickets de Pepsi.