uhppoted tunnel
1.0.0
Tunnelt UDP-Pakete zwischen zwei Maschinen, um den Fernzugriff auf den UHPPOTE-Controller zu ermöglichen.
Technisch gesehen ist es nicht wirklich ein Tunnel, außer in dem Sinne, dass man als Paket ein dunkles, abweisendes Loch betritt, mysteriöse und möglicherweise unaussprechliche Dinge passieren und man einige Zeit später blinzelnd im Licht an einem völlig anderen Ort auftaucht. Also wahrscheinlich eher ein Relay oder ein Proxy ... aber wir verwenden trotzdem einen Tunnel .
Die Implementierung umfasst die folgenden Konnektoren:
Für die so lästigen Zeiten, in denen es schön wäre, die UHPPOTE AccessControl- Anwendung auszuführen, sich der Controller jedoch an einem Ort befindet und der Host-Rechner an einem anderen (oder vielleicht auf einem VPS in Norwegen), was bedeutet, dass UDP-Broadcast nicht einfach funktioniert. Und Löcher in die Firewall zu bohren und das NAT zu optimieren oder ein VPN einzurichten, wird entweder nicht passieren oder ist mehr Ärger als es wert ist.
Auch für die Remote-Nutzung nützlich
und ist eine einfachere Alternative zu:
Unterstützte Betriebssysteme:
**v0.8.9 – 06.09.2024
Ausführbare Dateien für alle unterstützten Betriebssysteme sind in den Versionen enthalten:
Die Release-Tarballs enthalten die ausführbaren Dateien für alle Betriebssysteme. Betriebssystemspezifische Tarballs mit allen uhppoted -Komponenten finden Sie in uhppoted-Releases.
Die Installation ist unkompliziert: Laden Sie das Archiv herunter und extrahieren Sie es in ein Verzeichnis Ihrer Wahl. So installieren Sie uhppoted-tunnel als Systemdienst:
cd <uhppoted directory>
sudo uhppoted-tunnel daemonize --in <connector> --out <connector> --label <label>
uhppoted-tunnel help listet die verfügbaren Befehle und zugehörigen Optionen auf (unten dokumentiert).
Benötigte Werkzeuge:
So erstellen Sie mit dem mitgelieferten Makefile:
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
make build
Ohne make zu verwenden:
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
go build -trimpath -o bin/ ./...
Die oben genannten Befehle erstellen die ausführbare Datei uhppoted-tunnel im bin -Verzeichnis.
| Abhängigkeit | Beschreibung |
|---|---|
| uhppote-core | API-Implementierung auf Geräteebene |
| uhppoted-lib | Gemeinsame Bibliotheksfunktionen |
| golang.org/x/sys | (für Windows-Dienstintegration) |
| tailscale.com | tsnet- Bibliothek für Tailscale-Konnektoren |
Verwendung: uhppoted-tunnel <command> --in <connector> --out <connector> <options>
Unterstützte Befehle:
helpversionrundaemonizeundaemonize Wird standardmäßig run , wenn der Befehl nicht bereitgestellt wird, z. B. uhppoted-tunnel --in <connector> --out <connector> <options> entspricht uhppoted-tunnel run --in <connector> --out <connector> <options> .
Für uhppoted-tunnel v0.8.3+ wird die Laufzeitkonfiguration in einer TOML-Datei definiert (hier dokumentiert) und alle zukünftigen Verbesserungen können nur in der TOML-Datei konfiguriert werden.
Die unten beschriebenen Befehlszeilenargumente dienen der Legacy-Unterstützung und dem Überschreiben bestimmter Einstellungen in der TOML-Konfiguration.
run Führt den uhppoted-tunnel Dienst aus. Standardbefehl, der als Systemdienst verwendet werden soll, der im Hintergrund ausgeführt wird.
Befehlszeile:
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
Im Allgemeinen arbeiten Tunnel paarweise – einer auf dem Host , der auf Befehle z. B. von der AccessControl- Anwendung oder uhppote-cli wartet, und der andere auf dem Client lokal beim Controller, der die Befehle an den/die Controller sendet und die Antworten zurückgibt zum Gastgeber . Es ist jedoch möglich, mehrere Tunnel zu verketten, um mehrere Maschinen zu überbrücken.
Die Ereigniskonnektoren sind eine Spezialisierung der UDP -Listen- und Broadcast- Konnektoren, da Ereignisse nur in eine Richtung weitergeleitet werden, ohne dass eine Antwort erwartet wird. Es ist durchaus möglich, die Listen- und Broadcast- Konnektoren zum Weiterleiten von Ereignissen zu verwenden, die speziellen Konnektoren sind jedoch leicht für den Anwendungsfall optimiert und wurden auch eingerichtet, um zukünftige Verbesserungen zu unterstützen, die möglicherweise auf den speziellen Konnektoren basieren.
daemonize Registriert uhppoted-tunnel als Systemdienst, der beim Systemstart gestartet wird. Der Befehl erstellt die erforderlichen systemspezifischen Dienstkonfigurationsdateien und Dienstmanagereinträge.
Unter Linux:
uhppoted:uhppoted – dies kann mit der Option --user geändert werdensudo systemctl enable uhppoted-tunnel-xxx auszuführen, damit der Dienst uhppoted-tunnel beim Booten gestartet wird.network-online.target wartet (vgl. https://systemd.io/NETWORK_ONLINE). Um auf eine bestimmte Schnittstelle zu warten, ändern Sie die Unit-Datei ( /etc/systemd/system/uhpppoted-tunnel-xxx ), um auf systemd-networkd-wait-online.service zu wartenBefehlszeile:
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 Hebt die Registrierung uhppoted-tunnel als Systemdienst auf, löscht jedoch keine erstellten Protokoll- oder Konfigurationsdateien.
Befehlszeile:
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 unterstützt mehrere Konnektoren, die im Allgemeinen gemischt und angepasst werden können, mit einigen Einschränkungen:
IN -Anschlüsse:
OUT- Anschlüsse:
Hört auf eingehende UDP-Pakete an der Bind-Adresse und fungiert so effektiv als direkter Proxy für einen Remote-Controller.
--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
Sendet ein empfangenes Paket als UDP-Nachricht an die Broadcast-Adresse und leitet alle Antworten an den ursprünglichen Anforderer weiter, wodurch es effektiv als Proxy für eine Remoteanwendung fungiert.
--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
Der TCP-Server-Connector akzeptiert Verbindungen von einem oder mehreren TCP-Clients und kann sowohl als IN -Connector als auch als OUT- Connector fungieren. Eingehende Anfragen werden an alle angeschlossenen Clients weitergeleitet.
--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
Der TCP-Client-Connector stellt eine Verbindung zu einem TCP-Server her und kann sowohl als IN -Connector als auch als OUT- Connector fungieren. Eingehende Anfragen/Antworten werden an den Remote-Server weitergeleitet.
--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
Der TLS-Server-Connector ist ein TCP-Server-Connector, der nur TLS-gesicherte Client-Verbindungen akzeptiert.
--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
Der TLS-Client-Connector ist ein TCP-Client-Connector, der nur eine Verbindung zu TLS-gesicherten Servern herstellt.
--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
Der HTTP-POST-Connector akzeptiert JSON-POST-Anfragen und leitet Antworten an den anfragenden Client weiter, hauptsächlich um schnelle und schmutzige browserbasierte Anwendungen zu unterstützen (ein kleines Beispiel ist im Beispielordner enthalten).
--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
POST-Anfrage:
{
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,,...]
}
Antwort:
{
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,...],
]
}
Der HTTPS-POST-Connector ist ein HTTP-POST-Connector, der nur TLS-Client-Verbindungen akzeptiert.
--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
POST-Anfrage:
{
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,,...]
}
Antwort:
{
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,...],
]
}
Der Tailscale -Server-Connector stellt eine lauschende Tailscale-Verbindung her, die Verbindungen von einem oder mehreren Tailscale-Clients akzeptiert. Im Gegensatz zu den TCP-Anschlüssen dient er nur als IN -Anschluss. Eingehende Anfragen werden an alle angeschlossenen Clients weitergeleitet.
Die Tailscale- Serveradresse umfasst:
machine , der für den Server verwendet werden soll (erforderlich)debug um die Tailscale-Verbindungsprotokollierung anzuzeigen. Der Standardwert ist „kein Protokoll“, da die Tailscale-Protokollierung sehr ausführlich ist, aber gelegentlich nützlich oder notwendig für die Fehlerbehebung bei Verbindungsproblemen. Der einzig gültige Wert ist debug – andere Werte (z. B. nolog) können als Platzhalter-Mnemonik verwendet werden. --in tailscale/server:<device>:<port>[,debug]
e.g.
--in tailscale/server:uhppoted:12345,debug
--in tailscale/server:uhppoted:12345,nolog
Bitte beachten Sie, dass Tailscale derzeit keine Bindung an eine bestimmte Schnittstelle unterstützt (Ref. tailscale/tailscale#1552).
Der Tailscale- Client-Connector stellt eine Verbindung zu einem lauschenden Tailscale- Server-Connecton her. Im Gegensatz zu den TCP- und UDP-Client-Konnektoren kann ein Tailscale-Client-Konnektor nur als OUT -Konnektor konfiguriert werden, d. h. er erwartet den Empfang von Befehlen am UDP-IN-Port und leitet die Befehle an den Tailscale-Server weiter, der mit dem Zugangscontroller verbunden ist.
Die Tailscale- Kundenadresse umfasst:
machine , der für den Server verwendet werden soll (optional, aber empfohlen)debug um die Tailscale-Verbindungsprotokollierung anzuzeigen. Der Standardwert ist „kein Protokoll“, da die Tailscale-Protokollierung sehr ausführlich ist, aber gelegentlich nützlich oder notwendig für die Fehlerbehebung bei Verbindungsproblemen. Der einzig gültige Wert ist debug – andere Werte (z. B. nolog) können als Platzhalter-Mnemonik verwendet werden. --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
Bitte beachten Sie, dass Tailscale derzeit keine Bindung an eine bestimmte Schnittstelle unterstützt (Ref. tailscale/tailscale#1552).
Standardmäßig verwenden Verbindungen zu einem Tailscale-Tailnet den Autorisierungsschlüssel in der Umgebungsvariablen TS_AUTHKEY. Wenn die Umgebungsvariable nicht definiert oder leer ist, werden Sie zur Eingabe einer Autorisierungs-URL aufgefordert.
Alternative Autorisierungsmethoden können in der TOML-Konfigurationsdatei konfiguriert werden (angegeben mit der Befehlszeilenoption --config ):
env:<variable name> angegeben werden, z. B [tailscale-server]
...
authorisation = "env:TS_WORKSHOP"
...
Dies ist eine Alternative zur Verwendung eines wiederverwendbaren Autorisierungsschlüssels in der Umgebungsvariablen TS_AUTHKEY, wenn zwei oder mehr Tunnel auf demselben Computer ausgeführt werden.
authkey:<key> angegeben werden, z [tailscale-server]
...
authorisation = "authkey:tskey-auth-xxxxxxxxxxxx-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
...
oauth2:<credentials> verwendet, z [tailscale-server]
...
authorisation = "oauth2:.credentials.workship"
...
Bei den credentials handelt es sich um eine JSON-Datei, die die OAuth2-Anmeldeinformationen für den OAuth2-Client enthält, z. B
{
"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 und client-secret sind die Schlüssel, die beim Erstellen des OAuth2-Clients auf der Tailscale-Administratorkonsole generiert werden.tailnet ist der Benutzer-/Organisationskontoname ( nicht der Tailnet-DNS-Name), kann aber standardmäßig auf „-“ gesetzt werden, da die API-Schlüssel organisations-/clientspezifisch sind.Der IP/Out-Anschluss unterstützt die folgenden Verbindungen zu Controllern:
Die Standardverbindung ist UDP-Broadcast, aber bestimmte Controller in der TOML-Konfigurationsdatei können für UDP-„sendto“- oder TCP-Verbindungen konfiguriert werden, sodass es sich für alle praktischen Zwecke um einen reinen „TOML“-Connector handelt:
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 verfügt über eine interne Ratenbegrenzung, die die Anzahl der Anfragen pro Sekunde begrenzt, die verarbeitet werden können. Die Standardeinstellungen sind einigermaßen konservativ:
Diese Grenzwerte können in der TOML-Konfigurationsdatei geändert werden, z. B.:
...
rate-limit = 5
rate-limit-burst = 300
...
Es werden gebrochene Ratenlimits unterstützt, z. B. rate-limit = 0.1
