emissary/doc/tutorials/fr/deploy-uci-configuration.md

Déployer une configuration UCI personnalisée sur un agent

Via la spécification uci.emissary.cadoles.com il est possible de configurer un agent avec un système OpenWRT. Dans ce tutoriel nous verrons:

• Comment exporter une configuration UCI existante au format attendu par Emissary;
• Comment modifier la spécification d'un agent Emissary pour mettre à jour sa configuration via le serveur de pilotage.

Étapes

Identifier l'empreinte de votre agent

1. Sur la machine agent, utiliser la commande intégrée pour récupérer l'empreinte ("thumbprint") identifiant l'agent:

   emissary agent show-thumbprint
   

   Noter la valeur retournée. Elle sera utilisée dans les étapes suivantes.

Exporter la configuration UCI de votre agent au format Emissary

1. Se connecter en SSH sur votre agent Emissary:

   ssh root@<agent_ip>
   

2. Sur la machine agent, utiliser la commande intégrée pour exporter la configuration UCI de votre agent au format Emissary:

   uci export | emissary agent openwrt uci transform > my-agent-config.json
   

   Astuce

   Par défaut, l'outil LuCi est disponible sur votre agent. Vous pouvez y accéder via l'URL http://<agent_ip>/.

   Vous pouvez utiliser LuCi pour modifier la configuration de l'agent (par exemple, configurer le WiFi, créer des règles réseaux, etc) avant d'exporter la configuration.

   De cette manière, il est possible de répliquer celle ci sur plusieurs agents via Emissary !

3. Transférer le fichier my-agent-config.json sur la machine hébergeant votre serveur de pilotage Emissary.

Transformer la configuration en spécification

Prérequis

• jq
• sponge (paquet moreutils sur Ubuntu)

Étapes

1. Sur la machine hébergeant le serveur de pilotage Emissary, utiliser l'outil jq pour créer un objet JSON correspondant au schéma attendu par la spécification uci.emissary.cadoles.com:

   # Créer la structure de base de la spécification UCI
   cat >> my-uci-spec.json <<EOF
   {
       "config": null,
       "postImportCommands": [
           { "command": "uci", "args": ["commit"] },
           { "command": "reload_config", "args": [] }
       ]
   }
   EOF
   
   # Injecter la configuration récupérée de notre agent dans la spécification
   cat my-uci-spec.json | jq --slurpfile config my-agent-config.json '.config = $config[0]' | sponge my-uci-spec.json
   

   Notre spécification est prête à être assignée à notre agent !

Assigner la spécification à l'agent

1. Sur la machine hébergeant le serveur de pilotage Emissary, retrouver l'identifiant associé à l'agent:

   # Déclarer une variable contenant l'empreinte de l'agent précédemment trouvée
   AGENT_THUMBPRINT="<empreinte agent>"
   
   # Récupérer l'identifiant de l'agent
   AGENT_ID=$(emissary api agent query -f json | jq -r --arg thumbprint "$AGENT_THUMBPRINT" '.[] | select(.thumbprint == $thumbprint) | .id')
   

2. Assigner la spécification à l'agent UCI:

   cat my-uci-spec.json | emissary api agent spec update -a ${AGENT_ID} --no-patch --spec-data - --spec-name uci.emissary.cadoles.com
   

   Bravo, vous avez déployé des spécifications UCI sur votre agent !

Exemple: modifier le hostname de votre agent

En intervenant directement sur notre spécification, il est possible de modifier la configuration et appliquer ces changements à notre agent.

1. Sur la machine hébergeant le serveur de pilotage, faire:

   # On créait une variable avec le nouveau hostname de notre agent
   MY_NEW_AGENT_HOSTNAME="MyEmissaryAgent"
   
   # On utilise jq afin de modifier la valeur de configuration dans notre spécification UCI
   cat my-uci-spec.json | jq --arg hostname "$MY_NEW_AGENT_HOSTNAME" '( .config.packages[] | select(.name == "system") | .configs[].options[] | select(.name == "hostname").value ) |= $hostname' | sponge my-uci-spec.json
   

   Astuce

   En utilisant la commande grep -C 10 hostname my-uci-spec.json, on peut voir que la valeur de configuration hostname a bien été mise à jour dans notre spécification.

2. Mettre à jour la configuration de l'agent:

   cat my-uci-spec.json | emissary api agent spec update -a ${AGENT_ID} --no-patch --spec-data - --spec-name uci.emissary.cadoles.com
   

3. Sur l'agent, après quelques secondes (par défaut, la fréquence de mise à jour est de 1 fois par minute) l'agent devrait avoir son hostname mis à jour:

   uci show system.@system[].hostname
   

   Un message de ce type devrait s'afficher:

   system.cfg01e48a.hostname='MyEmissaryAgent'
   

   La modification devrait être également visible dans le prompt du shell de l'agent.