La commande tosiam-config

tosiam-config est un jar autonome qui parle à un serveur TOSIAM par son API REST. Il ne demande ni les bibliothèques du serveur, ni un accès au config store : il fonctionne depuis un poste ou une CI, contre un serveur distant.

Où trouver la commande#

Distribution : tosiam/tosiam-config.jar dans le zip TosiAM-<version>.zip de la page de téléchargement. Il demande Java 17 ou plus récent :
bash
```
java -jar tosiam-config.jar --help
```
Image TOSIAM : la commande tosiam-config est dans l’image, voir Import au démarrage.

Utilisez la commande de la version du serveur : une CLI X.Y accepte un serveur X.Y ou X.(Y-1) et refuse les autres.

S’authentifier#

La CLI ouvre une session avec un compte d’administration du royaume racine, amadmin par défaut. Le mot de passe n’est jamais passé en argument :

Faites défiler le tableau

Réglage	Option	Variable d’environnement
Compte	`--username <nom>`	`TOSIAM_CONFIG_USERNAME` (défaut `amadmin`)
Mot de passe	`--password-file <fichier>`	`TOSIAM_CONFIG_PASSWORD`
Autorité de certification du serveur	`--ca-cert <fichier.pem>`	— (défaut : celles de la JVM)

L’URL du serveur comprend son contexte : --server https://am.example.com/tosiam. Le serveur refuse un hôte qui n’est pas un nom complet : localhost et 127.0.0.1 ne conviennent pas.

Exporter#

bash

export TOSIAM_CONFIG_PASSWORD='…'
java -jar tosiam-config.jar export --server https://am.example.com/tosiam \
    --dir ./tosiam-config --realm /clients

texte

DataStore: 1 exported
Script: 3 exported
SubGraph: 0 exported
AuthGraph: 2 exported
...
Export written in tosiam-config/realms/clients
The secrets are written as ${secret:…}: provide them by ${env:…} or ${file:…}.

L’export remplace les fichiers du royaume par ceux du serveur. --kinds Script,AuthGraph limite l’export (et le plan) à certains types. Remplacez ensuite les références ${secret:…} par des références ${env:…} ou ${file:…} : voir Secrets.

Calculer le plan#

bash

java -jar tosiam-config.jar plan --server https://am.example.com/tosiam --dir ./tosiam-config --realm /clients

texte

+ Script decision (6f0c…)
~ AuthGraph login
    steps/password/config/maxAttempts: 3 → 5
~ OAuth2Client app1
    coreOAuth2ClientConfig/userpassword: secret rewritten
! Script legacy-check (91aa…)   (on the server, not in the files)
Plan: 1 to create, 2 to update, 0 to delete, 1 on the server only.

Faites défiler le tableau

Symbole	Signification
`+`	Créé : dans les fichiers, pas sur le serveur
`~`	Modifié, avec les chemins qui diffèrent (`valeur du serveur → valeur des fichiers`)
`-`	Supprimé, avec `--prune=managed` seulement
`!`	Sur le serveur seulement : jamais supprimé hors du périmètre géré

Le plan n’écrit rien. Il se termine par la liste des problèmes qui empêchent d’appliquer, par exemple un secret obligatoire non fourni ou un conflit de nom.

Appliquer#

bash

java -jar tosiam-config.jar apply --server https://am.example.com/tosiam --dir ./tosiam-config --realm /clients

L’application recalcule le plan, refuse s’il a des problèmes, puis applique les créations et les modifications dans l’ordre des dépendances, et les suppressions en dernier. Elle affiche ce qui a été appliqué ; sur une erreur, ce qui a été appliqué avant elle.

Appliquer exactement le plan relu#

En CI, on relit le plan avant de l’appliquer. plan --out l’enregistre avec l’empreinte de l’état du serveur ; apply --plan applique exactement ce plan, et refuse si le serveur ou les fichiers ont changé depuis :

bash

java -jar tosiam-config.jar plan  --server "$URL" --dir ./tosiam-config --realm /clients --out plan.json
# revue du plan…
java -jar tosiam-config.jar apply --server "$URL" --dir ./tosiam-config --realm /clients --plan plan.json

Le fichier plan.json ne contient que les noms des objets et l’empreinte, aucune valeur de la configuration.

Tous les royaumes#

--all-realms calcule le plan ou applique chaque royaume du répertoire realms/, les royaumes parents avant leurs sous-royaumes. L’application s’arrête au premier royaume en erreur. Cette option ne se combine pas avec --realm, --out ni --plan.

Supprimer#

--prune=managed supprime les objets du périmètre déclaré dans tosiam.yaml qui n’ont pas de fichier ; le plan les annonce par -. Sans cette option (--prune=none), rien n’est supprimé.

Options#

Faites défiler le tableau

Option	Commandes	Rôle
`--server <url>`	toutes	URL du serveur, avec son contexte
`--dir <répertoire>`	toutes	Répertoire de la configuration
`--realm <royaume>`	toutes	Royaume, `/` par défaut
`--all-realms`	`plan`, `apply`	Chaque royaume du répertoire `realms/`
`--kinds <k1,k2>`	toutes	Types d’objets, tous par défaut
`--out <fichier>`	`plan`	Enregistre le plan
`--plan <fichier>`	`apply`	Applique le plan enregistré
`--prune <none\|managed>`	`plan`, `apply`	Suppression des objets du périmètre géré absents des fichiers
`--username`, `--password-file`, `--ca-cert`	toutes	Voir S’authentifier

Codes de retour#

Faites défiler le tableau

Code	Signification
`0`	Fait, ou aucun écart
`2`	Le plan a des écarts
`1`	Erreur, ou problème qui empêche d’appliquer
`64`	Mauvais usage de la commande

Le code 2 permet à une CI de détecter une dérive : un plan planifié qui sort en 2 signale une modification faite à la main sur le serveur.

Exemple d’intégration continue#

Les fichiers sont dans git, le mot de passe du compte de service et les secrets dans les variables protégées de la CI :

bash

#!/bin/sh
set -eu
URL=https://recette.example.com/tosiam
CLI="java -jar tosiam-config.jar"
# les références ${env:APP1_SECRET}… des fichiers sont lues dans l'environnement de la CI

# étape « plan » (sur chaque demande de fusion) : le plan est publié pour la revue
status=0
$CLI plan --server "$URL" --dir tosiam-config --realm /clients --out plan.json || status=$?
# 0 : aucun écart, 2 : écarts à relire ; tout autre code est une erreur
[ "$status" -eq 0 ] || [ "$status" -eq 2 ] || exit "$status"

# étape « apply » (après fusion, sur validation) : exactement le plan relu
$CLI apply --server "$URL" --dir tosiam-config --realm /clients --plan plan.json