85.1.60. pepsi-config¶

inspect and edit the effective pepsi configuration

Section du manuel:: 1

85.1.60.1.1. Nom¶

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

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

85.1.60.1.3. Description¶

pepsi-config inspecte — et modifie — la configuration effective partagée par chaque composant 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 – la configuration du fichier est rapportée et l’exécution réussit tout de même – car un opérateur recourt le plus souvent à cet outil quand quelque chose ne va pas. (Un échec de connexion est journalisé comme un avertissement ; une connexion qui réussit mais dont la surcouche ne peut être lue est journalisée comme une erreur, et la configuration du fichier est quand même rapportée. 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 et n’a donc rien à rapporter sans la base, et elle 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 est ce qui l’impose : aucun composant Pepsi traitant 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).

85.1.60.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 PASSWORD, PASSPHRASE, SECRET, TOKEN, CREDENTIAL, CLIENT_ID ou PEPPER — délibérément pas KEY, 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, de sorte qu’un vidage non masqué lancé en tant que root imprimerait 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 tel vidage dans un rapport de bogue est la manière ordinaire dont un opérateur partage sa configuration. Le prédicat est celui qu’emploient 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 modification est d’abord validée en construisant la configuration qu’elle produirait et en lui appliquant l’analyseur propre à l’étape propriétaire ; une valeur que cette étape rejetterait est refusée, avec l’erreur de cette étape, et rien n’est stocké. Sont refusés de même, et jamais stockés : 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), 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. Indique si le changement est à chaud ou exige un redémarrage, et consigne la modification – qui, quand, quelle portée, mais pas la valeur – dans le journal d’audit.

unset [–scope SCOPE] SECTION [OPTION]

Retire une redéfinition ou — sans OPTION — toutes les redéfinitions que la portée porte 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, qui reste ainsi utilisable. Le fichier d’archive lui-même est créé en 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 — et un fichier isolé de plus de 32 Mio, un mot de passe vide, ou un répertoire ne contenant aucun fichier ordinaire sont refusés. 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ù l’entrée est atteinte : 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 il est demandé sur le terminal sans écho, et export le demande deux fois et refuse une discordance. Lorsqu’aucun fichier de configuration n’a été trouvé, il n’y a aucun répertoire par défaut et –from/–into devient obligatoire.

85.1.60.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 même règle qu’emploie la couche de paramètres par adresse (pepsi-settings(1)).

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

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

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

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

85.1.60.1.10. Voir aussi¶

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

85.1.60.1.11. Bogues¶

Signalez les bogues au gestionnaire de tickets de Pepsi.