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$VARsubstitué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 (globalpar 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 contientPASS(doncPASSWORD,PASSPHRASEet[pepsi-list] API_PASS),SECRET,TOKEN,CREDENTIAL,CLIENT_ID,PEPPERouSYSTEM_ID.KEYne figure délibérément pas dans cette liste, afin qu’un cheminTLS_KEYreste affiché. La directive@inline-secret@fusionne chaque fragmentsecrets.d/*.secretdans 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 lePROGRAMd’une étape sauf s’il s’agit d’une simple commandepepsi-stage-*) ; et une SCOPEdomain:/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 mode0600. 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, quepg_dumpsauvegarde 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 normalementroot; 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 queroot. 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à unpepsi.confdemande 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 :
globalTout le déploiement. La valeur par défaut pour set et unset.
domain:DOMAINLes messages dont l’adresse pertinente est à DOMAIN.
address:ADDRESSLes 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,debugoutrace. En l’absence du drapeau, l’option globale[pepsi] LOGs’applique, et à défautinfo.- -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.