uhppoted tunnel
1.0.0
Túneles paquetes UDP entre un par de máquinas para permitir el acceso remoto al controlador UHPPOTE.
Técnicamente no es realmente un túnel, excepto en el sentido de que, como paquete, entras en un agujero oscuro e intimidante, suceden cosas misteriosas y posiblemente indescriptibles y, un tiempo después, emerges parpadeando ante la luz en un lugar completamente diferente. Probablemente sea más un relé o un proxy... pero de todos modos vamos a utilizar el túnel .
La implementación incluye los siguientes conectores:
Para esos momentos tan molestos en los que sería bueno ejecutar la aplicación UHPPOTE AccessControl pero el controlador está en un lugar y la máquina host en otro (o tal vez en un VPS en Noruega), lo que significa que la transmisión UDP no solo funciona. Y hacer agujeros en el firewall y modificar la NAT o configurar una VPN no va a suceder o es más problemático de lo que vale.
También es útil para usar de forma remota
y es una alternativa más sencilla a:
Sistemas operativos compatibles:
**v0.8.9 - 2024-09-06
Los ejecutables para todos los sistemas operativos compatibles están empaquetados en las versiones:
Los archivos tar de lanzamiento contienen los archivos ejecutables para todos los sistemas operativos; los archivos tar específicos del sistema operativo con todos los componentes uhpppoted se pueden encontrar en los lanzamientos uhpppoted.
La instalación es sencilla: descargue el archivo y extráigalo al directorio que elija. Para instalar uhppoted-tunnel como servicio del sistema:
cd <uhppoted directory>
sudo uhppoted-tunnel daemonize --in <connector> --out <connector> --label <label>
uhppoted-tunnel help enumerará los comandos disponibles y las opciones asociadas (documentadas a continuación).
Herramientas necesarias:
Para construir usando el Makefile incluido:
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
make build
Sin usar make :
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
go build -trimpath -o bin/ ./...
Los comandos anteriores crean el ejecutable uhppoted-tunnel en el directorio bin .
| Dependencia | Descripción |
|---|---|
| uhppote-núcleo | Implementación de API a nivel de dispositivo |
| uhppoted-lib | Funciones de biblioteca comunes |
| golang.org/x/sys | (para integración de servicios de Windows) |
| tailscale.com | Biblioteca tsnet para conectores Tailscale |
Uso: uhppoted-tunnel <command> --in <connector> --out <connector> <options>
Comandos admitidos:
helpversionrundaemonizeundaemonize El valor predeterminado es run si el comando que no proporcionó, es decir, uhppoted-tunnel --in <connector> --out <connector> <options> es equivalente a uhppoted-tunnel run --in <connector> --out <connector> <options> .
Para uhppoted-tunnel v0.8.3+, la configuración del tiempo de ejecución se define en un archivo TOML (documentado aquí) y cualquier mejora futura se podrá configurar solo en el archivo TOML.
Los argumentos de la línea de comando que se describen a continuación son para soporte heredado y para anular configuraciones específicas en la configuración TOML.
run Ejecuta el servicio uhppoted-tunnel . Comando predeterminado, diseñado para usarse como un servicio del sistema que se ejecuta en segundo plano.
Línea de comando:
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 general, los túneles funcionan en pares: uno en el host , escuchando comandos de, por ejemplo, la aplicación AccessControl o uhppote-cli y el otro en el cliente local del controlador, que envía los comandos a los controladores y devuelve las respuestas. al anfitrión . Sin embargo, es posible encadenar múltiples túneles para unir varias máquinas.
Los conectores de eventos son una especialización de los conectores de escucha y transmisión UDP en el sentido de que los eventos se retransmiten en una sola dirección, sin esperar una respuesta. Es muy posible utilizar los conectores de escucha y transmisión para transmitir eventos, pero los conectores especializados están ligeramente optimizados para el caso de uso y también se han implementado para admitir mejoras futuras que puedan depender de los conectores especializados.
daemonize Registra uhppoted-tunnel como un servicio del sistema que se iniciará al iniciar el sistema. El comando crea los archivos de configuración de servicios necesarios y las entradas del administrador de servicios específicos del sistema.
En Linux:
uhppoted:uhppoted user:group; esto se puede cambiar con la opción --usersudo systemctl enable uhppoted-tunnel-xxx después de realizar el demonio para que el servicio uhppoted-tunnel se inicie al arrancar.network-online.target (cf. https://systemd.io/NETWORK_ONLINE). Para esperar una interfaz específica, modifique el archivo de la unidad ( /etc/systemd/system/uhpppoted-tunnel-xxx ) para esperar systemd-networkd-wait-online.serviceLínea de comando:
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 Anula el registro de uhppoted-tunnel como servicio del sistema, pero no elimina ningún registro ni archivo de configuración creado.
Línea de comando:
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 incluye soporte para múltiples conectores que, en general, se pueden mezclar y combinar, con algunas restricciones:
Conectores EN :
Conectores de salida :
Escucha los paquetes UDP entrantes en la dirección de enlace , actuando efectivamente como un proxy directo para un controlador remoto.
--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
Envía un paquete recibido como un mensaje UDP en la dirección de transmisión y reenvía cualquier respuesta al solicitante original, actuando efectivamente como un proxy para una aplicación remota.
--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
El conector del servidor TCP acepta conexiones de uno o más clientes TCP y puede actuar como conector de entrada y de salida . Las solicitudes entrantes se reenviarán a todos los clientes conectados.
--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
El conector del cliente TCP se conecta a un servidor TCP y puede actuar como conector de entrada y de salida . Las solicitudes/respuestas entrantes se reenviarán al servidor remoto.
--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
El conector del servidor TLS es un conector de servidor TCP que solo acepta conexiones de cliente seguras 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
El conector de cliente TLS es un conector de cliente TCP que solo se conecta a servidores seguros 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
El conector HTTP POST acepta solicitudes JSON POST y reenvía respuestas al cliente solicitante, principalmente para admitir aplicaciones rápidas y sucias basadas en navegador (se incluye un pequeño ejemplo en la carpeta de ejemplos ).
--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
Solicitud de publicación:
{
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,,...]
}
Responder:
{
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,...],
]
}
El conector HTTPS POST es un conector HTTP POST que solo acepta conexiones de cliente 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
Solicitud de publicación:
{
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,,...]
}
Responder:
{
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,...],
]
}
El conector del servidor Tailscale establece una conexión de escucha de Tailscale que acepta conexiones de uno o más clientes de Tailscale. A diferencia de los conectores TCP, está diseñado para actuar únicamente como conector IN . Las solicitudes entrantes se reenvían a todos los clientes conectados.
La dirección del servidor Tailscale comprende:
machine tailnet que se utilizará para el servidor (obligatorio)debug opcional para mostrar el registro de conexión de escala final. El valor predeterminado es "sin registro" porque el registro de Tailscale es muy detallado, pero en ocasiones es útil o necesario para depurar problemas de conexión. El único valor válido es debug ; se pueden utilizar otros valores (por ejemplo, nolog) como mnemotécnicos de marcador de posición. --in tailscale/server:<device>:<port>[,debug]
e.g.
--in tailscale/server:uhppoted:12345,debug
--in tailscale/server:uhppoted:12345,nolog
Tenga en cuenta que Tailscale actualmente no admite la vinculación a una interfaz específica (Ref. tailscale/tailscale#1552).
El conector del cliente Tailscale se conecta a una conexión del servidor Tailscale de escucha. A diferencia de los conectores de cliente TCP y UDP, un conector de cliente Tailscale solo se puede configurar como conector de SALIDA , es decir, espera recibir comandos en el puerto UDP IN y reenvía los comandos al servidor Tailscale que está conectado al controlador de acceso.
La dirección del cliente de Tailscale comprende:
machine tailnet que se utilizará para el servidor (opcional, pero recomendado)debug opcional para mostrar el registro de conexión de escala final. El valor predeterminado es "sin registro" porque el registro de Tailscale es muy detallado, pero en ocasiones es útil o necesario para depurar problemas de conexión. El único valor válido es debug ; se pueden utilizar otros valores (por ejemplo, nolog) como mnemotécnicos de marcador de posición. --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
Tenga en cuenta que Tailscale actualmente no admite la vinculación a una interfaz específica (Ref. tailscale/tailscale#1552).
De forma predeterminada, las conexiones a una tailnet de Tailscale utilizarán la clave de autorización en la variable de entorno TS_AUTHKEY. Si la variable de entorno no está definida o está en blanco, se le solicitará una URL de autorización.
Se pueden configurar métodos de autorización alternativos en el archivo de configuración TOML (especificado mediante la opción de línea de comando --config ):
env:<variable name> , por ejemplo [tailscale-server]
...
authorisation = "env:TS_WORKSHOP"
...
Esta es una alternativa al uso de una clave de autorización reutilizable en la variable de entorno TS_AUTHKEY cuando se ejecutan dos o más túneles en la misma máquina.
authkey:<key> , por ejemplo [tailscale-server]
...
authorisation = "authkey:tskey-auth-xxxxxxxxxxxx-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
...
oauth2:<credentials> , por ejemplo [tailscale-server]
...
authorisation = "oauth2:.credentials.workship"
...
Las credentials son un archivo JSON que contiene las credenciales de OAuth2 para el cliente OAuth2, por ejemplo
{
"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 y client-secret son las claves generadas al crear el cliente OAuth2 en la consola de administración de Tailscale.tailnet es el nombre de la cuenta del usuario/organización ( no el nombre DNS de la tailnet), pero puede tener un valor predeterminado '-' ya que las claves API son específicas de la organización/cliente.El conector IP/salida admite las siguientes conexiones a controladores:
La conexión predeterminada es de transmisión UDP, pero se pueden configurar controladores específicos en el archivo de configuración TOML para conexiones UDP 'sendto' o TCP, lo que lo convierte en un conector exclusivo 'TOML' para todos los propósitos prácticos:
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 tiene un límite de velocidad interna que limita la cantidad de solicitudes por segundo que se pueden procesar. La configuración predeterminada es razonablemente conservadora:
Estos límites se pueden cambiar en el archivo de configuración TOML, por ejemplo:
...
rate-limit = 5
rate-limit-burst = 300
...
Se admiten límites de tasa fraccionarios, por ejemplo rate-limit = 0.1
