Déploiement de Geoprobe
Ce guide couvre le déploiement et la configuration des agents geoProbe — les serveurs qui effectuent les mesures de latence pour le service de Géolocalisation DoubleZero.
Un geoProbe se situe entre les DZD et les appareils cibles dans la chaîne de mesure à trois niveaux. Il reçoit des LocationOffsets signés des DZD parents et mesure le RTT vers les cibles enregistrées via TWAMP, TWAMP signé ou écho ICMP. Chaque geoProbe est enregistré onchain et lié à un ou plusieurs DZD parents.
Pour un aperçu de l'architecture de géolocalisation et des flux de mesure, consultez le guide utilisateur de Géolocalisation.
Prérequis
Version de l'agent de télémétrie DZD
Les DZD parents doivent exécuter la version 0.17.0 ou plus récente de l'agent de télémétrie de l'appareil pour prendre en charge le service de géolocalisation. Les versions antérieures n'incluent pas les extensions de découverte de sonde, de ping TWAMP et de publication d'offsets nécessaires à la géolocalisation. Vérifiez les versions des agents avant de déployer une sonde — une sonde associée à un DZD plus ancien ne recevra pas d'offsets.
Avant de déployer un geoProbe, assurez-vous de disposer de :
- Serveur Linux bare metal — Un VPS peut fonctionner, mais est moins idéal.
- Proximité réseau avec un DZD — moins de 1 ms de RTT entre la sonde et son DZD parent. Idéalement 0,1 ms ou moins.
- Capacité
CAP_NET_RAWpour le processus de l'agent (nécessaire pour le sondage par écho ICMP avec des sockets bruts) - Paire de clés Ed25519 pour l'identité de signature de la sonde
- Autorisation de la Fondation — l'enregistrement des sondes est actuellement contrôlé par la fondation ; coordonnez-vous avec la DZF avant de procéder
- DZD parent(s) exécutant l'agent de télémétrie v0.17.0+
Installation
Installez à la fois le démon de l'agent et le CLI doublezero :
curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash
sudo apt install doublezero-geoprobe-agent doublezero
| Paquet | Objectif |
|---|---|
doublezero-geoprobe-agent |
Démon de l'agent qui s'exécute sur le serveur de la sonde, effectuant les mesures de latence et générant des offsets signés |
doublezero |
Outil CLI utilisé pour l'enregistrement des sondes et les commandes de gestion |
Enregistrement Onchain
L'enregistrement des sondes nécessite une autorisation de la fondation. Coordonnez-vous avec la DZF avant de procéder.
Étape 1 : Enregistrer la sonde
doublezero geolocation probe create \
--code <probe-code> \
--exchange <exchange-pubkey> \
--public-ip <probe-ip> \
--signing-pubkey <signing-key-pubkey>
| Paramètre | Description |
|---|---|
--code |
Identifiant unique pour la sonde (par ex., ams-tn-gp1) — 32 caractères maximum |
--exchange |
Clé publique du compte Serviceability Exchange auquel cette sonde est associée |
--public-ip |
Adresse IPv4 publique sur laquelle la sonde écoute |
--signing-pubkey |
Clé publique utilisée pour signer les offsets et la télémétrie |
Étape 2 : Lier les DZD parents
doublezero geolocation probe add-parent \
--probe <probe-code> \
--device <dzd-code>
Chaque DZD parent doit être un appareil activé dans le Serviceability Program. Les DZD découvrent automatiquement les sondes enfants toutes les 60 secondes — une fois liés, le DZD commence automatiquement les mesures TWAMP et la génération d'offsets.
Exécution de l'Agent
doublezero-geoprobe-agent \
--env mainnet-beta \
--keypair /etc/geoprobe/keypair.json \
--geoprobe-pubkey <probe-onchain-pubkey>
Options Requises
| Option | Description |
|---|---|
--keypair |
Chemin vers le fichier de paire de clés Ed25519 pour la signature des offsets |
--geoprobe-pubkey |
La clé publique onchain de la sonde (issue de probe create) |
--env |
Environnement réseau : testnet, devnet, ou mainnet-beta (définit l'URL RPC du registre) |
Alternativement, utilisez --ledger-rpc-url au lieu de --env pour spécifier un point de terminaison RPC Solana personnalisé.
Options Facultatives
| Option | Défaut | Description |
|---|---|---|
--twamp-listen-port |
8925 | Port pour les mesures TWAMP des DZD parents |
--signed-twamp-port |
8924 | Port pour les sondes TWAMP signées des cibles entrantes |
--udp-listen-port |
8923 | Port pour la réception des datagrammes LocationOffset des DZD |
--probe-interval |
30s | Fréquence de mesure de chaque cible |
--max-offset-age |
1h | Âge maximum d'un offset DZD en cache avant qu'il ne soit supprimé |
--verify-interval |
29s | Fréquence de re-vérification des assignations de cibles depuis le registre |
--verbose |
false | Activer la journalisation détaillée |
--metrics-enable |
false | Activer le point de terminaison de métriques Prometheus |
--metrics-addr |
— | Adresse pour le point de terminaison de métriques Prometheus (par ex., 0.0.0.0:9090) |
Ports et Pare-feu
L'agent geoprobe nécessite l'ouverture de plusieurs ports :
| Port | Protocole | Direction | Objectif |
|---|---|---|---|
| 8923/udp | UDP | Entrant depuis les DZD | Réception des datagrammes LocationOffset signés |
| 8924/udp | UDP | Entrant depuis les cibles | Réflecteur TWAMP signé (flux de sondage entrant) |
| 8925/udp | UDP | Entrant depuis les DZD | Mesures TWAMP des DZD parents |
| ICMP | ICMP | Sortant vers les cibles | Requêtes d'écho ICMP pour les cibles OutboundIcmp |
Note
L'agent a également besoin d'UDP sortant vers les cibles pour le sondage TWAMP (flux sortant) et pour la livraison des résultats LocationOffset signés aux cibles.
Surveillance
Activez le point de terminaison de métriques Prometheus pour une visibilité opérationnelle :
doublezero-geoprobe-agent \
--keypair /etc/geoprobe/keypair.json \
--geoprobe-pubkey <probe-onchain-pubkey> \
--env testnet \
--metrics-enable \
--metrics-addr 0.0.0.0:9090
Métriques clés à surveiller :
- Disponibilité de la sonde — temps de fonctionnement du processus de l'agent
- Latence DZD vers sonde — doit être inférieure à 1 ms ; des valeurs plus élevées indiquent un problème de placement
- Cibles actives — nombre de cibles que la sonde mesure actuellement
- Échecs de vérification de signature — des valeurs non nulles peuvent indiquer une mauvaise configuration des clés ou des paquets altérés
- Taux de succès du cache d'offsets — un taux faible signifie que la sonde attend fréquemment de nouveaux offsets DZD
Consultez le guide des opérations pour des conseils généraux sur les modèles de scraping et d'alerting Prometheus utilisés dans l'ensemble des agents DoubleZero.
Commandes de Gestion des Sondes
Le CLI doublezero geolocation fournit les sous-commandes suivantes pour la gestion des sondes :
| Sous-commande | Description |
|---|---|
probe create |
Enregistrer un nouveau geoProbe onchain |
probe get |
Obtenir les détails d'une sonde spécifique par code |
probe list |
Lister toutes les sondes enregistrées |
probe update |
Mettre à jour la configuration de la sonde (IP, port, clé de signature) |
probe delete |
Supprimer une sonde (nécessite l'absence de références de cibles actives) |
probe add-parent |
Lier un DZD parent à la sonde |
probe remove-parent |
Retirer un DZD parent de la sonde |
Toutes les sous-commandes acceptent --env ou --rpc-url pour sélectionner le réseau. Les opérations d'écriture (create, update, delete, add-parent, remove-parent) nécessitent --keypair.
Exemple : lister les sondes
doublezero geolocation probe list
Retourne toutes les sondes enregistrées avec leurs codes, IPs publiques, DZD parents et statut actuel.