William Petit
d73e027ee3
All checks were successful
arcad/emissary/pipeline/head This commit looks good
130 lines
5.0 KiB
Markdown
130 lines
5.0 KiB
Markdown
# Déployer une configuration UCI personnalisée sur un agent
|
|
|
|
Via la spécification [`uci.emissary.cadoles.com`](../../../internal/spec/uci/schema.json) 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](https://openwrt.org/fr/doc/howto/luci.essentials) 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`](https://stedolan.github.io/jq/)
|
|
- [`sponge`](https://linux.die.net/man/1/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`](../../../internal/spec/uci/schema.json):
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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. |