# Premiers pas

## Récupérer et lancer un serveur Emissary sur sa machine

1. Aller sur [la page "Releases"](https://forge.cadoles.com/arcad/emissary/releases) du projet `arcad/emissary` et télécharger la dernière archive disponible `emissary-server_<version>_linux_<arch>.tar.gz` (où `<arch>` correspond à l'architecture de votre machine).

2. Extraire l'archive sur votre poste de travail

3. Dans un terminal, se positionner dans le dossier extrait puis faire:

    ```bash
    ./emissary --config '' server config dump > config.yml  # Générer un fichier de configuration pour votre instance
    ./emissary -c config.yml server database migrate        # Appliquer les migrations à la base de données SQLite
    ./emissary -c config.yml server run                     # Lancer le serveur Emissary
    ```

    Vous devriez avoir une sortie du type:

    ```
    2023-02-22 20:54:26.876 [INFO]	<server.go:100>	http server listening
    2023-02-22 20:54:26.876 [INFO]	<run.go:42>	listening	{"url": "http://127.0.0.1:3000"}
    ```

## Récupérer et lancer une VM OpenWRT avec l'agent Emissary dans Qemu

1. Aller sur [la page "Releases"](https://forge.cadoles.com/arcad/emissary-firmware/releases) du projet `arcad/emissary-firmware` et télécharger la dernière archive d'image disque `openwrt-22.03.2-emissary-<gitref>-x86-generic-generic-squashfs-combined.img.gz`.

2. Décompresser l'image disque téléchargée

    ```bash
    gunzip openwrt-22.03.2-emissary-*-x86-generic-generic-squashfs-combined.img.gz
    ```

3. Lancer une machine virtuelle avec Qemu en utilisant l'image disque

    ```bash
    qemu-system-x86_64 \
		-enable-kvm \
		-nographic \
		-drive file=$(ls openwrt-22.03.2-emissary-*-x86-generic-generic-squashfs-combined.img),id=d0,if=none \
		-device ide-hd,drive=d0,bus=ide.0 \
        -netdev bridge,br=virbr0,id=hn0 \
		-device e1000,netdev=hn0,id=nic1 \
		-netdev user,id=hn1 \
		-device e1000,netdev=hn1,id=nic2
    ```

    La machine virtuelle devrait démarrer. La console s'arrêtera sur une sortie proche de:

    ```
    [   10.095596] e1000: eth1 NIC Link is Up 1000 Mbps Full Duplex, Flow Control: RX
    [   10.098872] IPv6: ADDRCONF(NETDEV_CHANGE): eth1: link becomes ready
    [   11.034720] IPv6: ADDRCONF(NETDEV_CHANGE): br-lan: link becomes ready
    ```

    Appuyer sur la touche `Entrée`.

    Vous devriez arriver sur le shell OpenWRT avec une sortie équivalente à:

    ```
    BusyBox v1.35.0 (2023-02-18 18:31:16 UTC) built-in shell (ash)

     _______                     ________        __
    |       |.-----.-----.-----.|  |  |  |.----.|  |_
    |   -   ||  _  |  -__|     ||  |  |  ||   _||   _|
    |_______||   __|_____|__|__||________||__|  |____|
            |__| W I R E L E S S   F R E E D O M
    -----------------------------------------------------
    OpenWrt 22.03.2, r19803-9a599fee93
    -----------------------------------------------------
    === WARNING! =====================================
    There is no root password defined on this device!
    Use the "passwd" command to set up a new password
    in order to prevent unauthorized SSH logins.
    --------------------------------------------------
    root@OpenWrt:/#
    ```

4. Dans la console OpenWRT et via la commande `uci`, modifier l'URL de base du serveur Emissary associé à votre agent:

    ```bash
    uci set emissary.agent.server_url='http://10.0.2.2:3000'
    ```

    > L'adresse `10.0.2.2` correspond à l'IP de la passerelle de la VM et donc à votre machine sur laquelle est lancé le serveur Emissary.

5. Diminuer l'intervalle de réconciliation de l'agent Emissary pour accélerer le temps de convergence de la configuration pour cette démonstration:

    ```bash
    uci set emissary.agent.reconciliation_interval='10'
    ```

6. Enregistrer la configuration et relancer le service `emissary-agent`

    ```bash
    uci commit                          # Enregistrer les modifications de configuration
    /etc/init.d/emissary-agent restart  # Redémarrer le service emissary-agent
    logread -f                          # Surveiller les logs de la machine
    ```

## Autoriser l'agent à communiquer avec le serveur

1. Sur votre machine, dans un nouveau terminal, interroger l'API avec la commande `curl`

    ```bash
    curl -v http://127.0.0.1:3000/api/v1/agents
    ```

    La sortie devrait ressembler à:

    ```json
    {
        "data": {
            "agents": [
                {
                    "id": 1,
                    "remoteId": "24uS35UciKh95pDtMiMXfYUPsfrCXJBvq9uhjvx6mJyx3XVo6qfXk2isHg3oTHw4qyDbPwc57oRkMWRhuBzRgSvd",
                    "status": 0,
                    "createdAt": "2023-02-22T21:18:47.14565137Z",
                    "updatedAt": "2023-02-22T21:18:47.14565137Z"
                }
            ],
            "total": 1
        }
    }
    ```

    > L'attribut `status` ici égal à `0` indique que l'agent n'est pas encore autorisé à se synchroniser avec les spécifications fournies par le serveur.

2. Autoriser l'agent à se synchroniser avec les spécifications du serveur

    ```bash
    curl -XPUT -H 'Content-Type:application/json' -d '{"status":1}' "http://127.0.0.1:3000/api/v1/agents/${AGENT_ID}"
    ```

    Où `${AGENT_ID}` est à remplacer par l'identifiant associé à votre agent dans la sortie de l'étape précédente (attribut `id` de l'objet correspondant à votre agent).

    La sortie de la commande devrait ressembler à:

    ```json
    {
        "data": {
            "agent": {
                "id": 1,
                "remoteId": "24uS35UciKh95pDtMiMXfYUPsfrCXJBvq9uhjvx6mJyx3XVo6qfXk2isHg3oTHw4qyDbPwc57oRkMWRhuBzRgSvd",
                "status": 1,
                "createdAt": "2023-02-22T21:28:57.174187323Z",
                "updatedAt": "2023-02-22T21:18:47.14565137Z"
            }
        }
    }
    ```

    Votre agent peut désormais commencer à récupérer les spécifications qui lui sont associées sur le serveur.

## Exemple: modifier le `hostname` de la machine

> On va utiliser ici la spécification `uci.emissary.cadoles.com` pour modifier la configuration [UCI](https://openwrt.org/docs/guide-user/base-system/uci) de la machine hôte de l'agent Emissary.

1. Sur votre machine, créer une spécification pour votre agent:

    ```bash
    cat > my-uci-spec.json <<EOF
    {
        "Name": "uci.emissary.cadoles.com",
        "Revision": 0,
        "Data": {
            "config": {
                "packages": [
                    {
                        "name": "system",
                        "configs": [
                            {
                                "name": "system",
                                "options": [
                                    {
                                        "type": "option",
                                        "name": "hostname",
                                        "value": "MyEmissaryAgent"
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        }
    }
    EOF
    ```

2. Avec la commande `curl`, charger la spécification pour votre agent:

    ```bash
    curl -XPOST -d @my-uci-spec.json -H 'Content-Type:application/json' "http://127.0.0.1:3000/api/v1/agents/${AGENT_ID}/specs"
    ```

    Le réponse devrait ressembler à:

    ```json
    {
        "data": {
            "spec": {
                "id": 2,
                "name": "uci.emissary.cadoles.com",
                "data": {
                    "config": {
                        "packages": [
                            {
                                "configs": [
                                    {
                                        "name": "system",
                                        "options": [
                                            {
                                                "name": "hostname",
                                                "type": "option",
                                                "value": "MyEmissaryAgent"
                                            }
                                        ]
                                    }
                                ],
                                "name": "system"
                            }
                        ]
                    }
                },
                "revision": 0,
                "createdAt": "2023-02-22T22:46:12.769547646Z",
                "updatedAt": "2023-02-22T22:46:12.769547646Z"
            }
        }
    }
    ```

3. Dans la console de la VM, après un cycle de réconciliation, vérifier que la configuration a bien été mise à jour:

    ```bash
    uci export system
    ```

    La sortie devrait ressembler à:

    ```
    package system

    config system
        option hostname 'MyEmissaryAgent'
    ```

4. Rédémarrer la VM via sa console:

    ```shell
    reboot
    ```

    Après redémarrage, la console devrait être:

    ```
    root@MyEmissaryAgent:/#
    ```


> **Astuce** Dans la console de la VM, vous pouvez utiliser la commande `uci export | /usr/local/bin/emissary agent openwrt uci transform` pour obtenir la représentation JSON d'une configuration UCI existante.

## Exemple: créer une passerelle vers un site arbitraire

> On va utiliser ici la spécification `gateway.emissary.cadoles.com` pour créer une passerelle inverse sur la machine vers un site web distant.

1. Sur votre machine, créer une spécification pour votre agent:

    ```bash
    cat > my-gateway-spec.json <<EOF
    {
        "Name": "gateway.emissary.cadoles.com",
        "Revision": 0,
        "Data": {
            "gateways": {
                "cadoles.com":{
                    "address":":8080",
                    "target":"http://example.com/"
                }
            }
        }
    }
    EOF
    ```

    > Cette spécification déclare une "gateway" pointant vers le site `http://example.com/` et qui écoutera sur le port 8080 (sur toutes les interfaces) sur la machine hébergeant l'agent.

2. Avec la commande `curl`, charger la spécification pour votre agent:

    ```bash
    curl -XPOST -d @my-gateway-spec.json -H 'Content-Type:application/json' "http://127.0.0.1:3000/api/v1/agents/${AGENT_ID}/specs"
    ```

    Le réponse devrait ressembler à:

    ```json
    {
        "data": {
            "spec": {
                "id": 1,
                "name": "gateway.emissary.cadoles.com",
                "data": {
                    "gateways": {
                        "cadoles.com": {
                            "address": ":8080",
                            "target": "http://example.com/"
                        }
                    }
                },
                "revision": 0,
                "createdAt": "2023-02-22T21:48:37.542822727Z",
                "updatedAt": "2023-02-22T21:48:37.542822727Z"
            }
        }
    }
    ```

3. Dans la console de la VM, après un cycle de réconciliation, vérifier que la passerelle est bien créée:

    ```bash
    netstat -tlnup
    ```

    La réponse devrait contenir une ligne équivalente à:

    ```bash
    tcp        0      0 :::8080                 :::*                    LISTEN      2100/emissary
    ```