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

331 lines
11 KiB
Markdown
Raw Normal View History

feat: initial commit
2023-02-03 16:40:47 +01:00
# 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
```