uhppoted tunnel
1.0.0
Faz o túnel de pacotes UDP entre um par de máquinas para permitir o acesso remoto do controlador UHPPOTE.
Tecnicamente não é realmente um túnel, exceto no sentido de que, como um pacote, você entra em um buraco escuro e proibitivo, coisas misteriosas e possivelmente indescritíveis ocorrem e você emerge algum tempo depois, piscando na luz, em um lugar totalmente diferente. Provavelmente é mais um relé ou proxy .. mas vamos usar o túnel de qualquer maneira.
A implementação inclui os seguintes conectores:
Para aqueles momentos tão irritantes em que seria bom executar o aplicativo UHPPOTE AccessControl , mas o controlador está em um lugar e a máquina host está em outro (ou talvez em um VPS na Noruega), o que significa que a transmissão UDP não funciona apenas. E abrir buracos no firewall e ajustar o NAT ou configurar uma VPN não vai acontecer ou é mais problemático do que vale a pena.
Também útil para usar remotamente
e é uma alternativa mais simples para:
Sistemas operacionais suportados:
**v0.8.9 - 06/09/2024
Os executáveis para todos os sistemas operacionais suportados estão empacotados nas versões:
Os tarballs de lançamento contêm os executáveis para todos os sistemas operacionais - tarballs específicos do sistema operacional com todos os componentes uhppoted podem ser encontrados em versões uhpppoted.
A instalação é simples: baixe o arquivo e extraia-o para um diretório de sua escolha. Para instalar uhppoted-tunnel como um serviço do sistema:
cd <uhppoted directory>
sudo uhppoted-tunnel daemonize --in <connector> --out <connector> --label <label>
uhppoted-tunnel help listará os comandos disponíveis e as opções associadas (documentadas abaixo).
Ferramentas necessárias:
Para construir usando o Makefile incluído:
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
make build
Sem usar make :
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
go build -trimpath -o bin/ ./...
Os comandos acima criam o executável uhppoted-tunnel no diretório bin .
| Dependência | Descrição |
|---|---|
| uhppote-core | Implementação de API em nível de dispositivo |
| uhppoted-lib | Funções comuns da biblioteca |
| golang.org/x/sys | (para integração de serviços do Windows) |
| tailscale. com | biblioteca tsnet para conectores Tailscale |
Uso: uhppoted-tunnel <command> --in <connector> --out <connector> <options>
Comandos suportados:
helpversionrundaemonizeundaemonize O padrão é ser run se o comando não for fornecido, ou seja, uhppoted-tunnel --in <connector> --out <connector> <options> é equivalente a uhppoted-tunnel run --in <connector> --out <connector> <options> .
Para o uhppoted-tunnel v0.8.3+, a configuração do tempo de execução é definida em um arquivo TOML (documentado aqui) e quaisquer melhorias futuras serão configuráveis apenas no arquivo TOML.
Os argumentos de linha de comando descritos abaixo são para suporte legado e substituição de configurações específicas na configuração TOML.
run Executa o serviço uhppoted-tunnel . Comando padrão, destinado ao uso como um serviço do sistema executado em segundo plano.
Linha 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
Em geral, os túneis operam em pares - um no host , ouvindo comandos, por exemplo, do aplicativo AccessControl ou uhppote-cli e o outro no cliente local para o controlador, que envia os comandos para o(s) controlador(es) e retorna as respostas para o anfitrião . No entanto, é possível encadear vários túneis para fazer a ponte entre várias máquinas.
Os conectores de eventos são uma especialização dos conectores de escuta e transmissão UDP, pois os eventos são retransmitidos apenas em uma única direção, sem expectativa de resposta. É bem possível usar os conectores de escuta e transmissão para retransmitir eventos, mas os conectores especializados são ligeiramente otimizados para o caso de uso e também foram implementados para suportar melhorias futuras que podem depender dos conectores especializados.
daemonize Registra uhppoted-tunnel como um serviço do sistema que será iniciado na inicialização do sistema. O comando cria os arquivos de configuração de serviço e entradas do gerenciador de serviços específicos do sistema necessários.
No Linux:
uhppoted:uhppoted user:group - isso pode ser alterado com a opção --usersudo systemctl enable uhppoted-tunnel-xxx após a daemonização para que o serviço uhppoted-tunnel seja iniciado na inicialização.network-online.target (cf. https://systemd.io/NETWORK_ONLINE). Para aguardar uma interface específica, modifique o arquivo da unidade ( /etc/systemd/system/uhpppoted-tunnel-xxx ) para aguardar systemd-networkd-wait-online.serviceLinha 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 Cancela o registro uhppoted-tunnel como um serviço do sistema, mas não exclui nenhum log criado ou arquivos de configuração.
Linha 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 inclui suporte para vários conectores que em geral podem ser misturados e combinados, com algumas restrições:
Conectores IN :
Conectores de SAÍDA :
Escuta pacotes UDP recebidos no endereço de ligação , agindo efetivamente como um proxy direto para um 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
Envia um pacote recebido como uma mensagem UDP no endereço de broadcast e encaminha quaisquer respostas ao solicitante original, agindo efetivamente como um proxy para um aplicativo remoto.
--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
O conector do servidor TCP aceita conexões de um ou mais clientes TCP e pode atuar como um conector IN e um conector OUT . As solicitações recebidas serão encaminhadas para todos os 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
O conector do cliente TCP se conecta a um servidor TCP e pode atuar como um conector IN e um conector OUT . As solicitações/respostas recebidas serão encaminhadas para o 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
O conector do servidor TLS é um conector de servidor TCP que aceita apenas conexões de cliente protegidas por 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
O conector de cliente TLS é um conector de cliente TCP que se conecta apenas a servidores protegidos por 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
O conector HTTP POST aceita solicitações JSON POST e encaminha respostas ao cliente solicitante, principalmente para oferecer suporte a aplicativos rápidos e sujos baseados em navegador (um pequeno exemplo está incluído na pasta de exemplos ).
--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
Solicitação 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,,...]
}
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,...],
]
}
O conector HTTPS POST é um conector HTTP POST que aceita apenas conexões 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
Solicitação 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,,...]
}
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,...],
]
}
O conector do servidor Tailscale estabelece uma conexão Tailscale de escuta que aceita conexões de um ou mais clientes Tailscale. Ao contrário dos conectores TCP, ele foi projetado para atuar apenas como um conector IN . As solicitações recebidas são encaminhadas para todos os clientes conectados.
O endereço do servidor Tailscale compreende:
machine tailnet a ser usada para o servidor (obrigatório)debug opcional para exibir o log de conexão tailscale. O padrão é 'no log' porque o log do Tailscale é muito detalhado, mas ocasionalmente útil ou necessário para depurar problemas de conexão. O único valor válido é debug - outros valores (por exemplo, nolog) podem ser usados como mnemônicos de espaço reservado. --in tailscale/server:<device>:<port>[,debug]
e.g.
--in tailscale/server:uhppoted:12345,debug
--in tailscale/server:uhppoted:12345,nolog
Observe que Tailscale atualmente não suporta ligação a uma interface específica (Ref. tailscale/tailscale#1552).
O conector do cliente Tailscale se conecta a uma conexão de servidor Tailscale de escuta. Ao contrário dos conectores de cliente TCP e UDP, um conector de cliente Tailscale só pode ser configurado como um conector OUT , ou seja, espera receber comandos na porta UDP IN e encaminha os comandos para o servidor Tailscale que está conectado ao controlador de acesso.
O endereço do cliente Tailscale compreende:
machine tailnet a ser usada para o servidor (opcional, mas recomendado)debug opcional para exibir o log de conexão tailscale. O padrão é 'no log' porque o log do Tailscale é muito detalhado, mas ocasionalmente útil ou necessário para depurar problemas de conexão. O único valor válido é debug - outros valores (por exemplo, nolog) podem ser usados como mnemônicos de espaço reservado. --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
Observe que Tailscale atualmente não suporta ligação a uma interface específica (Ref. tailscale/tailscale#1552).
Por padrão, as conexões com uma tailnet Tailscale usarão a chave de autorização na variável de ambiente TS_AUTHKEY. Se a variável de ambiente não estiver definida ou estiver em branco, você será solicitado a fornecer um URL de autorização.
Métodos de autorização alternativos podem ser configurados no arquivo de configuração TOML (especificado usando a opção de linha de comando --config ):
env:<variable name> , por exemplo [tailscale-server]
...
authorisation = "env:TS_WORKSHOP"
...
Esta é uma alternativa ao uso de uma chave de autorização reutilizável na variável de ambiente TS_AUTHKEY ao executar dois ou mais túneis na mesma máquina.
authkey:<key> , por exemplo [tailscale-server]
...
authorisation = "authkey:tskey-auth-xxxxxxxxxxxx-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
...
oauth2:<credentials> , por exemplo [tailscale-server]
...
authorisation = "oauth2:.credentials.workship"
...
As credentials são um arquivo JSON que contém as credenciais OAuth2 para o cliente OAuth2, por exemplo
{
"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 e client-secret são as chaves geradas ao criar o cliente OAuth2 no console de administração do Tailscale.tailnet é o nome da conta do usuário/organização ( não o nome DNS da tailnet), mas pode ser padronizada como '-', uma vez que as chaves de API são específicas da organização/cliente.O conector IP/out suporta as seguintes conexões com controladores:
A conexão padrão é a transmissão UDP, mas controladores específicos no arquivo de configuração TOML podem ser configurados para conexões UDP 'sendto' ou TCP, tornando-o um conector apenas 'TOML' para todos os fins práticos:
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 possui um limite de taxa interna que limita o número de solicitações por segundo que podem ser processadas. As configurações padrão são razoavelmente conservadoras:
Esses limites podem ser alterados no arquivo de configuração TOML, por exemplo:
...
rate-limit = 5
rate-limit-burst = 300
...
Limites de taxa fracionária são suportados, por exemplo rate-limit = 0.1
