331 lines
11 KiB
Markdown
331 lines
11 KiB
Markdown
|
# 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
|
||
|
|
```
|