doc: add emissary introduction

README.md

@@ -1,6 +1,4 @@
-<p align="center">
+# Emissary
-    <img width="400" src="./misc/resources/logo.svg" />
-</p>
 
 Control plane for "edge" (and OpenWRT-based) devices.
 
@@ -16,8 +14,6 @@ Download the pre-compiled binaries from the [releases page](https://forge.cadole
 
 See [`doc`](./doc/README.md)
 
-## Licence & mentions
+## Licence
 
-[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.html#license-text)
+AGPL-3.0
-
-Logo by [@aardouin](https://forge.cadoles.com/aardouin)

doc/README.md

@@ -5,18 +5,18 @@
 ## Tutorials
 
 - (FR) - [Premiers pas](./tutorials/fr/first-steps.md)
-- (FR) - [Déployer un serveur mandataire inverse sur un agent](./tutorials/fr/deploy-reverse-proxy.md)
-- (FR) - [Déployer une configuration UCI personnalisée sur un agent](./tutorials/fr/deploy-uci-configuration.md)
 
 ## References
 
-### Specifications
+### API
 
-- [Schéma `app.emissary.cadoles.com`](../internal/agent/controller/app/spec/schema.json)
+[See `misc/rest/server.rest`](../misc/rest/server.rest)
-- [Schéma `proxy.emissary.cadoles.com`](../internal/spec/proxy/schema.json)
+
-- [Schéma `mdns.emissary.cadoles.com`](../internal/agent/controller/mdns/spec/schema.json)
+### Spécifications
+
+- [Schéma `app.emissary.cadoles.com`](../internal/spec/app/schema.json)
 - [Schéma `uci.emissary.cadoles.com`](../internal/spec/uci/schema.json)
-- [Schéma `sysupgrade.openwrt.emissary.cadoles.com`](../internal/agent/controller/openwrt/spec/sysupgrade/schema.json)
+- [Schéma `gateway.emissary.cadoles.com`](../internal/spec/gateway/schema.json)
 
 ### Configuration
 

doc/tutorials/fr/deploy-reverse-proxy.md

@@ -1,3 +0,0 @@
-# Déployer un serveur mandataire inverse sur un agent
-
-> TODO

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

@@ -1,130 +0,0 @@
-# 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.

doc/tutorials/fr/first-steps.md

@@ -1,158 +1 @@
-# Premiers pas
+# Premiers pas
-
-## Prérequis
-
-- Pour le serveur, une machine [Ubuntu 22.04](https://ubuntu.com/download/server)
-- Pour l'agent, un [RaspberryPi version 3](https://openwrt.org/toh/raspberry_pi_foundation/raspberry_pi)
-
-## Étapes
-
-### Préparer votre RaspberryPi
-
-1. Sur la page des ["versions"](https://forge.cadoles.com/arcad/emissary-firmware/releases) des firmwares du projet Emissary, télécharger la dernière version disponibles correspondant à votre système cible, dans le cas présent `openwrt-<openwrt_version>-emissary-<emissary_firmware_version>-bcm27xx-bcm2710-rpi-3-ext4-factory.img.gz`
-
-2. Brancher votre carte SD dans le lecteur, flasher celle ci avec le firmware:
-
-    ```bash
-    # Chemin vers le fichier de firmware précédemment téléchargé
-    FIRMWARE_FILE="openwrt-<openwrt_version>-emissary-<emissary_firmware_version>-bcm27xx-bcm2710-rpi-3-ext4-factory.img.gz"
-
-    SDCARD_DEVICE=/dev/sdX  # Chemin vers le "device" correspondant à votre carte SD
-
-    # Décompresser le firmware
-    gzip -d "${FIRMWARE_FILE}"
-
-    # Flash la carte SD
-    sudo dd if="${FIRMWARE_FILE%.gz}" of="${SDCARD_DEVICE}" bs=2M conv=fsync
-
-    # Attendre la fin des écritures
-    sudo sync
-    ```
-
-3. Placer votre carte SD dans votre RaspberryPi, le connecter à votre réseau en Ethernet puis l'allumer.
-
-4. Scanner votre réseau pour trouver l'adresse IP de votre Raspberry Pi. Par exemple, avec l'outil `nmap`:
-
-    ```bash
-    sudo nmap -sP 192.168.0.*   # À modifier par le préfixe correspondant à votre réseau local
-    ```
-    
-    Une entrée équivalente à la suivante devrait être affichée:
-
-    ```bash
-    Starting Nmap 7.93 ( https://nmap.org ) at 2023-05-25 19:29 CEST
-    Nmap scan report for 192.168.0.24
-    Host is up (0.0034s latency).
-    MAC Address: B8:27:EB:E5:7B:55 (Raspberry Pi Foundation)
-    [...]
-    ```
-
-5. Se connecter en SSH sur votre RaspberryPi et définir un mot de passe pour le compte administrateur:
-
-    ```bash
-    ssh root@<ip>
-
-    passwd
-    ```
-
-### Installer le serveur Emissary
-
-1. Sur la machine Ubuntu 22.04, télécharger les paquets Emissary sur la page ["Versions"](https://forge.cadoles.com/arcad/emissary/releases) du projet. Dans le cas présent, choisir le paquet Debian `emissary-server_<emissary_version>_linux_<arch>.deb` où `<arch>` correspond à l'architecture CPU de votre machine.
-
-2. Installer le paquet télécharger via `dpkg`:
-
-    ```
-    sudo dpkg -i emissary-server_<emissary_version>_linux_<arch>.deb
-    ```
-
-3. Appliquer les migrations sur la base de données:
-
-    ```shell
-    sudo emissary --workdir /usr/share/emissary --config /etc/emissary/server.yml server database migrate
-    ```
-
-4. Redémarrer le service:
-
-    ```shell
-    sudo systemctl restart emissary-server
-    ```
-
-5. Créer un jeton d'administration:
-
-    ```shell
-    sudo emissary --workdir /usr/share/emissary --config /etc/emissary/server.yml server auth create-token --role writer --subject $(whoami) > .emissary-token
-    ```
-
-6. Vérifier l'authentification sur l'API:
-
-    ```shell
-    emissary api agent query
-    ```
-
-    Une réponse équivalente à la suivante devrait s'afficher:
-
-    ```shell
-    +----+-------+------------+--------+-------------+-----------+
-    | ID | LABEL | THUMBPRINT | STATUS | CONTACTEDAT | UPDATEDAT |
-    +----+-------+------------+--------+-------------+-----------+
-    +----+-------+------------+--------+-------------+-----------+
-    ```
-
-### Appairer l'agent avec votre serveur
-
-1. Sur le RaspberryPi, exécuter la commande suivante:
-
-    ```shell
-    uci set emissary.agent.server_url='http://<server_ip>:3000'
-    uci commit emissary
-    reload_config
-    ```
-
-2. Via la commande `logread`, vérifier que l'agent arrive à se connecter avec le serveur:
-
-    ```shell
-    logread -f
-    ```
-
-    Un message de ce type devrait s'afficher:
-
-    ```
-    Thu May 25 18:48:51 2023 daemon.info emissary[2202]: 2023-05-25 18:48:51.611 [INFO]	<./internal/agent/controller/persistence/controller.go:58>	(*Controller).Reconcile	no changes detected, doing nothing	{"controller": "persistence-controller"}
-    Thu May 25 18:48:51 2023 daemon.info emissary[2202]: 2023-05-25 18:48:51.675 [ERROR]	<./internal/agent/controller/spec/controller.go:43>(*Controller).reconcileAgent	unexpected agent status	{"controller": "spec-controller", "agentID": 1, "status": 0}
-    Thu May 25 18:48:51 2023 daemon.info emissary[2202]: 2023-05-25 18:48:51.676 [INFO]	<./internal/agent/controller/openwrt/uci_controller.go:32>	(*UCIController).Reconcile	could not find uci spec, doing nothing	{"controller": "uci-controller"}
-    Thu May 25 18:48:51 2023 daemon.info emissary[2202]: 2023-05-25 18:48:51.677 [INFO]	<./internal/agent/controller/app/controller.go:43>	(*Controller).Reconcile	could not find app spec	{"controller": "app-controller"}
-    Thu May 25 18:48:51 2023 daemon.info emissary[2202]: 2023-05-25 18:48:51.678 [INFO]	<./internal/agent/controller/proxy/controller.go:35>(*Controller).Reconcile	could not find proxy spec	{"controller": "proxy-controller"}
-    Thu May 25 18:48:51 2023 daemon.info emissary[2202]: 2023-05-25 18:48:51.680 [INFO]	<./internal/agent/controller/mdns/controller.go:38>(*Controller).Reconcile	could not find mdns spec	{"controller": "mdns-controller"}
-    Thu May 25 18:48:51 2023 daemon.info emissary[2202]: 2023-05-25 18:48:51.680 [INFO]	<./internal/agent/controller/openwrt/sysupgrade_controller.go:36>	(*SysUpgradeController).Reconcile	could not find sysupgrade spec, doing nothing	{"controller": "sysupgrade-controller"}
-    ```
-
-3. Sur le serveur, vérifier que l'agent a pu s'enregistrer:
-
-    ```shell
-    emissary api agent query
-    ```
-
-    Un message de ce type devrait s'afficher:
-
-    ```
-    +----+-------+-----------------------------------+--------+-----------------------------------+-----------------------------------+
-    | ID | LABEL | THUMBPRINT                        | STATUS | CONTACTEDAT                       | UPDATEDAT                         |
-    +----+-------+-----------------------------------+--------+-----------------------------------+-----------------------------------+
-    | 1  |       | 21CnUATcboKCaheb2uczWCuoxTZtnp... | 0      | 2023-05-25 18:49:51.652680196 ... | "2023-05-25T18:49:51.589225817... |
-    +----+-------+-----------------------------------+--------+-----------------------------------+-----------------------------------+
-    ```
-
-    Noter l'identifiant associé à l'agent.
-
-4. Mettre à jour le statut de l'agent afin qu'il soit en capacité à récupérer ses spécifications:
-
-    ```
-    emissary api agent update --agent-id <agent_id> --status 1
-    ```
-
-**Bravo, vous avez appairé votre premier agent et son serveur Emissary !**
-
-## Aller plus loin
-
-- [Déployer une configuration UCI personnalisée sur un agent](./deploy-uci-configuration.md)
-- [Déployer un serveur mandataire inverse sur votre agent](./deploy-reverse-proxy.md)

misc/packaging/systemd/emissary-agent.systemd.service

@@ -6,7 +6,7 @@ After=network.target
 Type=simple
 Restart=always
 WorkingDirectory=/usr/share/emissary
-ExecStart=/usr/bin/emissary --config /etc/emissary/agent.yml agent run
+ExecStart=/usr/bin/emissary --config /etc/emissary/config.yml agent run
 
 [Install]
 WantedBy=multi-user.target

misc/packaging/systemd/emissary-server.systemd.service

@@ -4,9 +4,9 @@ After=network.target
 
 [Service]
 Type=simple
-Restart=on-failure
+Restart=always
 WorkingDirectory=/usr/share/emissary
-ExecStart=/usr/bin/emissary --config /etc/emissary/server.yml server run
+ExecStart=/usr/bin/emissary --config /etc/emissary/config.yml server run
 
 [Install]
 WantedBy=multi-user.target