arcad
/
emissary-firmware
17
0
Fork 0
Code Issues 1 Pull Requests Projects Releases 3 Wiki Activity
emissary-firmware/doc/tutorials/first-steps.md

11 KiB
Raw Blame History

Premiers pas

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

  1. Aller sur la page "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:

    ./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" 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

    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

    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:

    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:

    uci set emissary.agent.reconciliation_interval='10'

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

    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

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

    La sortie devrait ressembler à:

    {
    "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

    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 à:

    {
    "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 de la machine hôte de l'agent Emissary.

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

    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:

    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 à:

    {
    "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:

    uci export system

    La sortie devrait ressembler à:

    package system

config system
    option hostname 'MyEmissaryAgent'

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

    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:

    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:

    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 à:

    {
    "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:

    netstat -tlnup

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

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