uhppoted tunnel
1.0.0
Tunnelise les paquets UDP entre une paire de machines pour permettre l’accès à distance au contrôleur UHPPOTE.
Techniquement, ce n'est pas vraiment un tunnel, sauf dans le sens où, en tant que paquet, vous entrez dans un trou sombre et inhospitalier, des choses mystérieuses et peut-être indescriptibles se produisent et vous ressortez quelque temps plus tard en clignant des yeux dans la lumière dans un endroit complètement différent. Donc probablement plus un relais ou un proxy .. mais nous optons quand même pour le tunnel .
L'implémentation comprend les connecteurs suivants :
Pour ces moments si ennuyeux où il serait bien d'exécuter l'application UHPPOTE AccessControl mais que le contrôleur est à un endroit et la machine hôte est à un autre (ou peut-être sur un VPS en Norvège), ce qui signifie que la diffusion UDP ne fonctionne pas seulement. Et percer des trous dans le pare-feu et peaufiner le NAT ou configurer un VPN ne se produira pas ou posera plus de problèmes que cela n'en vaut la peine.
Également utile pour utiliser à distance
et constitue une alternative plus simple à :
Systèmes d'exploitation pris en charge :
**v0.8.9 - 2024-09-06
Les exécutables pour tous les systèmes d'exploitation pris en charge sont regroupés dans les versions :
Les archives tar de la version contiennent les exécutables pour tous les systèmes d'exploitation - des archives tar spécifiques au système d'exploitation avec tous les composants uhppoted peuvent être trouvées dans les versions uhpppoted.
L'installation est simple : téléchargez l'archive et extrayez-la dans un répertoire de votre choix. Pour installer uhppoted-tunnel en tant que service système :
cd <uhppoted directory>
sudo uhppoted-tunnel daemonize --in <connector> --out <connector> --label <label>
uhppoted-tunnel help répertoriera les commandes disponibles et les options associées (documentées ci-dessous).
Outils requis :
Pour construire à l'aide du Makefile inclus :
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
make build
Sans utiliser make :
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
go build -trimpath -o bin/ ./...
Les commandes ci-dessus créent l'exécutable uhppoted-tunnel dans le répertoire bin .
| Dépendance | Description |
|---|---|
| uhppote-core | Implémentation de l'API au niveau de l'appareil |
| uhppoted-lib | Fonctions communes de la bibliothèque |
| golang.org/x/sys | (pour l'intégration des services Windows) |
| tailscale.com | bibliothèque tsnet pour les connecteurs Tailscale |
Utilisation : uhppoted-tunnel <command> --in <connector> --out <connector> <options>
Commandes prises en charge :
helpversionrundaemonizeundaemonize run par défaut si la commande n'est pas fournie, c'est-à-dire uhppoted-tunnel --in <connector> --out <connector> <options> est équivalent à uhppoted-tunnel run --in <connector> --out <connector> <options> .
Pour uhppoted-tunnel v0.8.3+, la configuration d'exécution est définie dans un fichier TOML (documenté ici) et toutes les améliorations futures seront configurables uniquement dans le fichier TOML.
Les arguments de ligne de commande décrits ci-dessous concernent la prise en charge héritée et le remplacement de paramètres spécifiques dans la configuration TOML.
run Exécute le service uhppoted-tunnel . Commande par défaut, destinée à être utilisée comme service système exécuté en arrière-plan.
Ligne de commande :
uhppoted-tunnel [--debug] [--console] --config <configuration> --in <connector> --out <connector> [options]
--config <configuration> Sets the TOML file and section to use for runtime configuration settings. The
configuration may be:
- fully specified, e.g. "--config /etc/uhppoted/uhppoted-tunnel.toml#client"
- file only e.g. "--config /etc/uhppoted/uhppoted-tunnel.toml" (uses the [defaults] section)
- section only e.g. "--config #client" (uses the default TOML file and [client] section)
If the --config argument not supplied, the default TOML file will be used if it exists.
--in <connector> Defines the connector that accepts incoming commands. Overrides the 'IN' connector in the TOML
configuration if it exists. Valid 'in' connectors include:
- udp/listen:<bind address> (e.g. udp/listen:0.0.0.0:60000)
- udp/event:<bind address> (e.g. udp/listen:0.0.0.0:60000)
- tcp/server:<bind address> (e.g. tcp/server:0.0.0.0:12345)
- tcp/client:<host address> (e.g. tcp/client:192.168.1.100:12345)
- tls/server:<bind address> (e.g. tls/server:0.0.0.0:12345)
- tls/client:<host address> (e.g. tls/client:192.168.1.100:12345)
- tailscale/server:<server address> (e.g.uhppoted:12345,nolog)
- http/<bind address> (e.g. http/0.0.0.0:8080)
- https/<bind address> (e.g. https/0.0.0.0:8443)
Under Linux and MacOS TCP and UDP _in_ connectors can be bound to a specific interface by prefixing
the address with ::<interface> e.g. tcp/client::en3:192.168.1.100:12345. The _Tailscale_ connector
syntax is described below.
--out <connector> Defines the connector that forwards received commands. Overrides the 'OUT' connector in the TOML
configuration if it exists. Valid 'out' connectors include:
- udp/broadcast:<broadcast address> (e.g. udp/broadcast:255.255.255.255:60000)
- udp/event:<broadcast address> (e.g. udp/broadcast:255.255.255.255:60000)
- tcp/server:<bind address> (e.g. tcp/server:0.0.0.0:12345)
- tcp/client:<host address> (e.g. tcp/client:192.168.1.100:12345)
- tls/server:<bind address> (e.g. tls/server:0.0.0.0:12345)
- tls/client:<host address> (e.g. tls/client:192.168.1.100:12345)
- tailscale/client:<client address> (e.g. tailscale/client::makerspace:uhppoted:12345,nolog)
Under Linux and MacOS TCP and UDP _out_ connectors can be bound to a specific interface by prefixing
the address with ::<interface> e.g. udp/broadcast::lo0:127.0.0.01:12345. The _Tailscale_ connector
syntax is described below.
--console Runs the UDP tunnel as a console application, logging events to the console.
--debug Displays verbose debugging information, in particular the communications with the
UHPPOTE controllers
Options:
--max-retries <retries> Maximum number of failed bind/connect attempts before failing with a fatal error.
Defaults to 32, set to -1 for infinite retry.
--max-retry-delay <delay> Retries use an exponential backoff (starting at 5 seconds) up to the delay (in
human readable time format e.g. 60s or 5m). Defaults to 5 minutes.
--lockfile <file> Overrides the default lockfile name for use in e.g. bash scripts. The default lockfile
name is generated from the hash of the 'in' and 'out' connectors.
--log-level <level> Lowest level log messages to include in logging output ('debug', 'info', 'warn' or 'error').
Defaults to 'info'
--ca-cert <file> (TLS only) File path for CA certificate PEM file. Defaults to ./ca.cert
--cert <file> (TLS only) File path for client/server certificate PEM file. Defaults to./client.cert ('IN'
connectors) or ./server.cert (OUT connectors)
--key <file> (TLS only) File path for client/server key PEM file. Defaults to ./client.key ('IN' connectors)
or ./server.key ('OUT' connectors)
--client-auth (TLS only) Mandates client authentication. Defaults to false
--html (HTTP only) Folder with HTML, CSS, images, etc. Defaults to./html
En général, les tunnels fonctionnent par paires : l'un sur l' hôte , écoutant les commandes provenant par exemple de l'application AccessControl ou de uhppote-cli et l'autre sur le client local du contrôleur, qui envoie les commandes au(x) contrôleur(s) et renvoie les réponses. à l' hôte . Il est cependant possible de chaîner plusieurs tunnels pour relier plusieurs machines.
Les connecteurs d'événements sont une spécialisation des connecteurs d'écoute et de diffusion UDP dans la mesure où les événements sont relayés dans une seule direction uniquement, sans attente de réponse. Il est tout à fait possible d'utiliser les connecteurs d'écoute et de diffusion pour relayer des événements mais les connecteurs spécialisés sont légèrement optimisés pour le cas d'utilisation et ont également été mis en place pour prendre en charge les améliorations futures pouvant s'appuyer sur les connecteurs spécialisés.
daemonize Enregistre uhppoted-tunnel en tant que service système qui sera démarré au démarrage du système. La commande crée les fichiers de configuration de service spécifiques au système et les entrées du gestionnaire de services nécessaires.
Sous Linux :
uhppoted:uhppoted user:group - cela peut être modifié avec l'option --usersudo systemctl enable uhppoted-tunnel-xxx après la démonisation pour que le service uhppoted-tunnel démarre au démarrage.network-online.target (cf. https://systemd.io/NETWORK_ONLINE). Pour attendre une interface spécifique, modifiez le fichier d'unité ( /etc/systemd/system/uhpppoted-tunnel-xxx ) pour attendre systemd-networkd-wait-online.serviceLigne de commande :
uhppoted-tunnel daemonize --config <configuration> --in <connector> --out <connector> [--label <label>] [--user <user>]
--config <configuration> Sets the TOML file and section to use for runtime configuration settings. The
configuration may be:
- fully specified, e.g. "--config /etc/uhppoted/uhppoted-tunnel.toml#client"
- file only e.g. "--config /etc/uhppoted/uhppoted-tunnel.toml" (uses the [defaults] section)
- section only e.g. "--config #client" (uses the default TOML file and [client] section)
If the --config argument not supplied, the default TOML file will be used if it exists.
--in <connector> Defines the connector that accepts incoming commands. Overrides the 'in' connector in the TOML
configuration. Valid 'in' connectors include:
- udp/listen:<bind address> (e.g. udp/listen:0.0.0.0:60000)
- tcp/server:<bind address> (e.g. tcp/server:0.0.0.0:12345)
- tcp/client:<host address> (e.g. tcp/client:192.168.1.100:12345)
- tls/server:<bind address> (e.g. tls/server:0.0.0.0:12345)
- tls/client:<host address> (e.g. tls/client:192.168.1.100:12345)
- http/<bind address> (e.g. http/0.0.0.0:8080)
- https/<bind address> (e.g. https/0.0.0.0:8443)
--out <connector> Defines the connector that forwards received commands. Overrides the 'out' connector in the TOML
configuration. Valid 'out' connectors include:
- udp/broadcast:<broadcast address> (e.g. udp/broadcast:255.255.255.255:60000)
- tcp/server:<bind address> (e.g. tcp/server:0.0.0.0:12345)
- tcp/client:<host address> (e.g. tcp/client:192.168.1.100:12345)
- tls/server:<bind address> (e.g. tls/server:0.0.0.0:12345)
- tls/client:<host address> (e.g. tls/client:192.168.1.100:12345)
--label <label> Identifying label for the tunnel daemon/service, used to identify the tunnel in logs and when
uninstalling the daemon/service. Imperative if running multiple tunnel daemons on the same machine,
optional but recommended otherwise. Defaults to uhppoted-tunnel if not provided.
--user <uid:group> (Linux only) uid:group pair to use for service. Defaults to uhppoted:uhppoted.
undaemonize Désenregistre uhppoted-tunnel en tant que service système, mais ne supprime aucun journal ou fichier de configuration créé.
Ligne de commande :
uhppoted-tunnel undaemonize [--label <label>]
--label <label> Identifying label for the tunnel daemon/service to be uninstalled. Defaults to uhppoted-tunnel if
not provided.
uhppoted-tunnel inclut la prise en charge de plusieurs connecteurs qui peuvent en général être mélangés et assortis, avec quelques restrictions :
Connecteurs IN :
Connecteurs SORTIE :
Écoute les paquets UDP entrants sur l' adresse de liaison , agissant efficacement comme un proxy direct pour un contrôleur distant.
--in udp/listen[::<interface>]:<bind address>
e.g.
--in udp/listen:0.0.0.0:60000
--in udp/listen::en3:0.0.0.0:60000
Envoie un paquet reçu sous forme de message UDP sur l' adresse de diffusion et transmet toutes les réponses au demandeur d'origine, agissant ainsi comme un proxy pour une application distante.
--out udp/broadcast[::<interface>]:<broadcast address> [--udp-timeout <timeout>]
The broadcast address is typically (but not necessarily) the UDP broadcast for the network adapter for the controllers'
network segment. However it can be any valid IPv4 address:port combination to accomodate the requirements of the
installation.
--udp-timeout <timeout> Sets the maximum time to wait for replies to a broadcast message, in human readable format
e.g. 15s, 1250ms, etc. Defaults to 5 seconds if not provided.
e.g.
--out udp/broadcast:255.255.255.255:60000 --udp-timeout 5s
--out udp/broadcast::en3:255.255.255.255:60000 --udp-timeout 5s
Le connecteur du serveur TCP accepte les connexions d'un ou plusieurs clients TCP et peut agir à la fois comme connecteur IN et comme connecteur OUT . Les demandes entrantes seront transmises à tous les clients connectés.
--in tcp/server[::<interface>]:<bind address>
e.g.
--in tcp/server:0.0.0.0:12345
--in tcp/server::en3:0.0.0.0:12345
Le connecteur client TCP se connecte à un serveur TCP et peut agir à la fois comme connecteur IN et comme connecteur OUT . Les demandes/réponses entrantes seront transmises au serveur distant.
--in tcp/client[::<interface>]:<host address>
e.g.
--in tcp/host:192.168.1.100:12345
--in tcp/host::lo0:127.0.0.1:12345
Le connecteur de serveur TLS est un connecteur de serveur TCP qui accepte uniquement les connexions client sécurisées TLS.
--in tls/server[::<interface>]:<bind address> [--ca-cert <file>] [--cert <file>] [--key <file>] [--client-auth]
--ca-cert CA certificate used to verify client certificates (defaults to ca.cert)
--cert server TLS certificate in PEM format (defaults to server.cert)
--key server TLS key in PEM format (defaults to server.key)
--client-auth requires client mutual authentication if supplied
e.g.
--in tls/server:0.0.0.0:12345 --ca-cert tunnel.ca --cert tunnel.cert --key tunnel.key --client-auth
--in tls/server::en3:0.0.0.0:12345 --ca-cert tunnel.ca --cert tunnel.cert --key tunnel.key --client-auth
Le connecteur client TLS est un connecteur client TCP qui se connecte uniquement aux serveurs sécurisés TLS.
--in tls/client[::<interface>]:<host address> [--ca-cert <file>] [--cert <file>] [--key <file>] [--client-auth]
--ca-cert CA certificate used to verify server certificates (defaults to ca.cert)
--cert client TLS certificate in PEM format. Optional, only required if the TLS server
has mutual authentication enabled.
--key client TLS key in PEM format. Optional, only required if the TLS server
has mutual authentication enabled.
e.g.
--in tls/client:192.168.1.100:12345 --ca-cert tunnel.ca --cert client.cert --key client.key
--in tls/client::en3:192.168.1.100:12345 --ca-cert tunnel.ca --cert client.cert --key client.key
Le connecteur HTTP POST accepte les requêtes JSON POST et transmet les réponses au client demandeur, principalement pour prendre en charge les applications rapides et sales basées sur un navigateur (un petit exemple est inclus dans le dossier des exemples ).
--in http/<bind address> [--html <folder>]
--html <folder> Folder containing the HTML served to the browser on the bind address.
e.g.
--in http:/0.0.0.0:8080 --html examples/html
Requête POST :
{
ID: <request ID>,
wait: <UDP timeout>,
request: <UDP request byte array>
}
e.g.
{
ID: 19,
wait: "5s",
request: [0x17,0x94,0x00,0x00,0x90,0x53,0xfb,0x0b,0x00,,...]
}
Répondre:
{
ID: <request ID>,
replies: <array of UDP byte array>
}
e.g.
{
ID: 19,
replies: [
[0x17,0x94,0x00,0x00,0x90,0x53,0xfb,0x0b,0xc0,0xa8,...],
[0x17,0x94,0x00,0x00,0x41,0x78,0x1e,0x12,0xc0,0xa8,...],
]
}
Le connecteur HTTPS POST est un connecteur HTTP POST qui accepte uniquement les connexions client TLS.
--in https/<bind address> [--html <folder>] [--ca-cert <file>] [--cert <file>] [--key <file>] [--client-auth]
--html <folder> Folder containing the HTML served to the browser on the bind address.
--ca-cert CA certificate used to verify client certificates (defaults to ca.cert)
--cert server TLS certificate in PEM format (defaults to server.cert)
--key server TLS key in PEM format (defaults to server.key)
--client-auth requires client mutual authentication if supplied
e.g.
--in https:/0.0.0.0:8080 --html examples/html
Requête POST :
{
ID: <request ID>,
wait: <UDP timeout>,
request: <UDP request byte array>
}
e.g.
{
ID: 19,
wait: "5s",
request: [0x17,0x94,0x00,0x00,0x90,0x53,0xfb,0x0b,0x00,,...]
}
Répondre:
{
ID: <request ID>,
replies: <array of UDP byte array>
}
e.g.
{
ID: 19,
replies: [
[0x17,0x94,0x00,0x00,0x90,0x53,0xfb,0x0b,0xc0,0xa8,...],
[0x17,0x94,0x00,0x00,0x41,0x78,0x1e,0x12,0xc0,0xa8,...],
]
}
Le connecteur du serveur Tailscale établit une connexion Tailscale d'écoute qui accepte les connexions d'un ou plusieurs clients Tailscale. Contrairement aux connecteurs TCP, il est conçu pour agir uniquement comme connecteur IN . Les demandes entrantes sont transmises à tous les clients connectés.
L' adresse du serveur Tailscale comprend :
machine tailnet à utiliser pour le serveur (obligatoire)debug facultatif pour afficher la journalisation des connexions tailscale. La valeur par défaut est « pas de journal » car la journalisation Tailscale est très détaillée, mais parfois utile ou nécessaire pour déboguer les problèmes de connexion. La seule valeur valide est debug - d'autres valeurs (par exemple nolog) peuvent être utilisées comme mnémoniques d'espace réservé. --in tailscale/server:<device>:<port>[,debug]
e.g.
--in tailscale/server:uhppoted:12345,debug
--in tailscale/server:uhppoted:12345,nolog
Veuillez noter que Tailscale ne prend actuellement pas en charge la liaison à une interface spécifique (Réf. tailscale/tailscale#1552).
Le connecteur client Tailscale se connecte à une connexion serveur Tailscale en écoute. Contrairement aux connecteurs client TCP et UDP, un connecteur client Tailscale ne peut être configuré que comme connecteur OUT , c'est-à-dire qu'il s'attend à recevoir des commandes sur le port UDP IN et transmet les commandes au serveur Tailscale connecté au contrôleur d'accès.
L' adresse du client Tailscale comprend :
machine tailnet à utiliser pour le serveur (facultatif, mais recommandé)debug facultatif pour afficher la journalisation des connexions tailscale. La valeur par défaut est « pas de journal » car la journalisation Tailscale est très détaillée, mais parfois utile ou nécessaire pour déboguer les problèmes de connexion. La seule valeur valide est debug - d'autres valeurs (par exemple nolog) peuvent être utilisées comme mnémoniques d'espace réservé. --in tailscale/client[::<machine>]:<server address>[,debug]
e.g.
--out tailscale/client:uhppoted:12345
--out tailscale/client::qwerty:uhppoted:12345,debug
--out tailscale/client::qwerty:uhppoted:12345,nolog
Veuillez noter que Tailscale ne prend actuellement pas en charge la liaison à une interface spécifique (Réf. tailscale/tailscale#1552).
Par défaut, les connexions à un tailnet Tailscale utiliseront la clé d'autorisation dans la variable d'environnement TS_AUTHKEY. Si la variable d'environnement n'est pas définie ou est vide, une URL d'autorisation vous sera demandée.
Des méthodes d'autorisation alternatives peuvent être configurées dans le fichier de configuration TOML (spécifié à l'aide de l'option de ligne de commande --config ) :
env:<variable name> , par exemple [tailscale-server]
...
authorisation = "env:TS_WORKSHOP"
...
Il s'agit d'une alternative à l'utilisation d'une clé d'autorisation réutilisable dans la variable d'environnement TS_AUTHKEY lors de l'exécution de deux tunnels ou plus sur la même machine.
authkey:<key> , par exemple [tailscale-server]
...
authorisation = "authkey:tskey-auth-xxxxxxxxxxxx-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
...
oauth2:<credentials> , par exemple [tailscale-server]
...
authorisation = "oauth2:.credentials.workship"
...
Les credentials sont un fichier JSON qui contient les informations d'identification OAuth2 pour le client OAuth2, par exemple
{
"tailscale": {
"oauth2": {
"client-id": "xxxxxxxxxxxx",
"client-secret": "tskey-client-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"auth-url": "https://api.tailscale.com/api/v2/oauth/token",
"tailnet": "[email protected]",
"tag": "development",
"key-expiry": 300
}
}
}
client-id et client-secret sont les clés générées lors de la création du client OAuth2 sur la console d'administration Tailscale.tailnet est le nom du compte utilisateur/organisation ( et non le nom DNS du tailnet), mais peut être défini par défaut sur « - » puisque les clés API sont spécifiques à l'organisation/au client.Le connecteur IP/sortie prend en charge les connexions suivantes aux contrôleurs :
La connexion par défaut est la diffusion UDP, mais des contrôleurs spécifiques dans le fichier de configuration TOML peuvent être configurés pour les connexions UDP « sendto » ou TCP, ce qui en fait un connecteur « TOML » uniquement à toutes fins pratiques :
uhppoted-tunnel --config "uhppoted-tunnel.toml#ip"
where the TOML 'ip' section comprises:
...
[ip]
in = "udp/listen:0.0.0.0:60000"
out = "ip/out:192.168.1.255:60005"
console=true
debug = true
[ip.controllers]
405419896 = "udp::192.168.1.100:60005"
303986753 = "tcp::192.168.1.100:60005"
...
- the 'in' connection is any supported IN connection
- the 'out' connection defines the default UDP broadcast connection
- the [controllers] subsection lists the controllers with transport protocol and IPv4 address
uhppoted-tunnel a une limite de débit interne qui limite le nombre de requêtes par seconde pouvant être traitées. Les paramètres par défaut sont raisonnablement conservateurs :
Ces limites peuvent être modifiées dans le fichier de configuration TOML, par exemple :
...
rate-limit = 5
rate-limit-burst = 300
...
Les limites de débit fractionnaires sont prises en charge, par exemple rate-limit = 0.1
