emissary/doc/tutorials/fr/first-steps.md

# 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 admin -o "$HOME/.config/emissary/admin-token"
    ```

    > **Note** Le jeton sera stocké dans le répertoire `$HOME/.config/emissary`.

6. Créer un nouveau `tenant`:

    ```shell
    sudo emissary --workdir /usr/share/emissary --config /etc/emissary/server.yml client tenant create --tenant-label "My Tenant" -o wide --token-file "$HOME/.config/emissary/admin-token"
    ```

    Noter la valeur de l'UUID (de la forme `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) affiché dans la colonne `ID`. Il sera identifié comme `$EMISSARY_TENANT` dans les étapes suivantes.

7. Créer un jeton d'authentification pour ce nouveau tenant:

    ```shell
    sudo emissary --workdir /usr/share/emissary --config /etc/emissary/server.yml server auth create-token --role writer --tenant $EMISSARY_TENANT
    ```

    > **Note** Le jeton sera stocké dans le fichier `$HOME/.config/emissary/auth-token`. Il sera le jeton utilisé par défaut par le CLI Emissary.

8. Vérifier l'authentification sur l'API:

    ```shell
    emissary client 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"}
    ```

2. Récupérer le `thumbprint` de votre agent:

    ```
    emissary agent show-thumbprint
    ```

    Noter la valeur de la chaîne de caractères affichée. Elle sera identifiée comme `$AGENT_THUMBPRINT` dans les étapes suivantes.

3. Sur le serveur, "réclamer" votre agent:

    ```shell
    emissary client agent claim --agent-thumbprint $AGENT_THUMBPRINT
    ```

    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 la valeur de l'identifiant affiché dans la colonne `ID`. Il sera identifié comme `$AGENT_ID` dans les étapes suivantes.

4. Mettre à jour le statut de l'agent afin qu'il soit en capacité à récupérer ses spécifications:

    ```
    emissary client 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)