From 0e664bce44dfd8477cbcf913a726c984a0e39923 Mon Sep 17 00:00:00 2001 From: William Petit Date: Thu, 25 May 2023 21:22:56 +0200 Subject: [PATCH] doc: add first steps tutorial (fr) --- doc/README.md | 2 + doc/tutorials/fr/deploy-reverse-proxy.md | 3 + doc/tutorials/fr/deploy-uci-configuration.md | 3 + doc/tutorials/fr/first-steps.md | 157 ++++++++++++++++++- 4 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 doc/tutorials/fr/deploy-reverse-proxy.md create mode 100644 doc/tutorials/fr/deploy-uci-configuration.md diff --git a/doc/README.md b/doc/README.md index bde729d..be3174f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -5,6 +5,8 @@ ## 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 diff --git a/doc/tutorials/fr/deploy-reverse-proxy.md b/doc/tutorials/fr/deploy-reverse-proxy.md new file mode 100644 index 0000000..7da0ea7 --- /dev/null +++ b/doc/tutorials/fr/deploy-reverse-proxy.md @@ -0,0 +1,3 @@ +# Déployer un serveur mandataire inverse sur un agent + +> TODO \ No newline at end of file diff --git a/doc/tutorials/fr/deploy-uci-configuration.md b/doc/tutorials/fr/deploy-uci-configuration.md new file mode 100644 index 0000000..4ba16c3 --- /dev/null +++ b/doc/tutorials/fr/deploy-uci-configuration.md @@ -0,0 +1,3 @@ +# Déployer une configuration UCI personnalisée sur un agent + +> TODO \ No newline at end of file diff --git a/doc/tutorials/fr/first-steps.md b/doc/tutorials/fr/first-steps.md index cda60db..c11b32b 100644 --- a/doc/tutorials/fr/first-steps.md +++ b/doc/tutorials/fr/first-steps.md @@ -1,3 +1,158 @@ # Premiers pas -> TODO \ No newline at end of file +## 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--emissary--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--emissary--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@ + + 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__linux_.deb` où `` correspond à l'architecture CPU de votre machine. + +2. Installer le paquet télécharger via `dpkg`: + + ``` + sudo dpkg -i emissary-server__linux_.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://: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 --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) \ No newline at end of file