uhppoted tunnel
1.0.0
在一对机器之间建立 UDP 数据包隧道，以实现 UHPPOTE 控制器远程访问。
从技术上讲，它并不是真正的隧道，但从某种意义上说，作为一个数据包，你进入了一个黑暗而令人生畏的洞，神秘的、可能无法形容的事情发生了，一段时间后，你在一个完全不同的地方在光亮中眨眼。所以可能更多的是中继或代理..但无论如何我们都会使用隧道。
该实现包括以下连接器：
对于那些非常烦人的情况，运行 UHPPOTE AccessControl应用程序会很好，但控制器位于一个位置而主机位于另一个位置（或者可能位于挪威的 VPS 上），这意味着 UDP 广播不起作用。在防火墙上挖洞、调整 NAT 或设置 VPN 要么不会发生，要么带来的麻烦大于其价值。
对于远程使用也很有用
是一个更简单的替代方案：
支持的操作系统：
**v0.8.9 - 2024-09-06
所有支持的操作系统的可执行文件都打包在以下版本中：
发行版 tarball 包含所有操作系统的可执行文件 - 包含所有uhppoted组件的操作系统特定 tarball 可以在 uhppoted 发行版中找到。
安装非常简单 - 下载存档并将其解压到您选择的目录。要将uhppoted-tunnel安装为系统服务：
cd <uhppoted directory>
sudo uhppoted-tunnel daemonize --in <connector> --out <connector> --label <label>
uhppoted-tunnel help将列出可用的命令和相关选项（如下所述）。
所需工具：
使用包含的 Makefile 进行构建：
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
make build
不使用make ：
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
go build -trimpath -o bin/ ./...
上述命令将uhppoted-tunnel可执行文件构建到bin目录中。
| 依赖性 | 描述 |
|---|---|
| uhppote核心 | 设备级API实现 |
| uhppoted 库 | 常用库函数 |
| golang.org/x/sys | （用于Windows服务集成） |
| tailscale.com | Tailscale 连接器的tsnet库 |
用法： uhppoted-tunnel <command> --in <connector> --out <connector> <options>
支持的命令：
helpversionrundaemonizeundaemonize如果未提供命令，则默认run ，即uhppoted-tunnel --in <connector> --out <connector> <options>相当于uhppoted-tunnel run --in <connector> --out <connector> <options> 。
对于uhppoted-tunnel v0.8.3+，运行时配置在 TOML 文件中定义（在此处记录），任何未来的增强功能都只能在 TOML 文件中进行配置。
下面描述的命令行参数用于旧版支持并覆盖 TOML 配置中的特定设置。
run运行uhppoted-tunnel服务。默认命令，旨在用作在后台运行的系统服务。
命令行：
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
一般来说，隧道成对运行 - 一个在主机上，侦听来自AccessControl应用程序或uhppote-cli等命令，另一个在控制器本地客户端上，将命令发送到控制器并返回回复给主机。然而，可以链接多个隧道来桥接多台机器。
事件连接器是 UDP侦听和广播连接器的特化，因为事件仅在单个方向上中继，而不期望回复。很可能使用监听和广播连接器来中继事件，但专用连接器针对用例进行了稍微优化，并且也已到位以支持可能依赖于专用连接器的未来增强功能。
daemonize将uhppoted-tunnel注册为将在系统启动时启动的系统服务。该命令创建必要的系统特定服务配置文件和服务管理器条目。
在 Linux 上：
uhppoted:uhppoted user:group - 这可以使用--user选项进行更改sudo systemctl enable uhppoted-tunnel-xxx以使uhppoted-tunnel服务在引导时启动。network-online.target （参见 https://systemd.io/NETWORK_ONLINE）。要等待特定接口，请修改单元文件 ( /etc/systemd/system/uhpppoted-tunnel-xxx ) 以等待 systemd-networkd-wait-online.service命令行：
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将uhppoted-tunnel取消注册为系统服务，但不删除任何创建的日志或配置文件。
命令行：
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支持多个连接器，这些连接器通常可以混合和匹配，但有一些限制：
输入连接器：
输出连接器：
侦听绑定地址上传入的 UDP 数据包，有效充当远程控制器的直接代理。
--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
将收到的数据包作为 UDP 消息在广播地址上发送出去，并将所有回复转发给原始请求者，有效充当远程应用程序的代理。
--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
TCP 服务器连接器接受来自一个或多个 TCP 客户端的连接，并且可以充当IN连接器和OUT连接器。传入请求将转发到所有连接的客户端。
--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
TCP 客户端连接器连接到 TCP 服务器，并且可以充当IN连接器和OUT连接器。传入的请求/回复将转发到远程服务器。
--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
TLS 服务器连接器是仅接受 TLS 安全客户端连接的 TCP 服务器连接器。
--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
TLS 客户端连接器是仅连接到 TLS 安全服务器的 TCP 客户端连接器。
--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
HTTP POST 连接器接受 JSON POST 请求并将回复转发给请求客户端，主要是为了支持基于浏览器的快速而肮脏的应用程序（示例文件夹中包含一个小示例）。
--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
发布请求：
{
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,,...]
}
回复：
{
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,...],
]
}
HTTPS POST 连接器是仅接受 TLS 客户端连接的 HTTP POST 连接器。
--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
发布请求：
{
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,,...]
}
回复：
{
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,...],
]
}
Tailscale服务器连接器建立一个侦听 Tailscale 连接，该连接接受来自一个或多个 Tailscale 客户端的连接。与 TCP 连接器不同，它被设计为仅充当IN连接器。传入请求将转发到所有连接的客户端。
Tailscale 服务器地址包括：
machine名称（必需）debug以显示 tailscale 连接日志记录。默认为“无日志”，因为 Tailscale 日志记录非常详细，但有时对于调试连接问题很有用或必要。唯一有效的值是debug - 其他值（例如 nolog）可以用作占位符助记符。 --in tailscale/server:<device>:<port>[,debug]
e.g.
--in tailscale/server:uhppoted:12345,debug
--in tailscale/server:uhppoted:12345,nolog
请注意，Tailscale 目前不支持绑定到特定接口（参考 tailscale/tailscale#1552）。
Tailscale客户端连接器连接到侦听Tailscale服务器连接。与 TCP 和 UDP 客户端连接器不同，Tailscale 客户端连接器只能配置为OUT连接器，即它期望在 UDP IN 端口上接收命令，并将命令转发到连接到访问控制器的 Tailscale 服务器。
Tailscale 客户端地址包括：
machine名称（可选，但推荐）debug以显示 tailscale 连接日志记录。默认为“无日志”，因为 Tailscale 日志记录非常详细，但有时对于调试连接问题很有用或必要。唯一有效的值是debug - 其他值（例如 nolog）可以用作占位符助记符。 --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
请注意，Tailscale 目前不支持绑定到特定接口（参考 tailscale/tailscale#1552）。
默认情况下，与 Tailscale tailnet 的连接将使用 TS_AUTHKEY 环境变量中的授权密钥。如果环境变量未定义或为空，则系统将提示您提供授权 URL。
可以在 TOML 配置文件中配置替代授权方法（使用--config命令行选项指定）：
env:<variable name>语法指定不同的环境变量，例如 [tailscale-server]
...
authorisation = "env:TS_WORKSHOP"
...
当在同一台计算机上运行两个或多个隧道时，这是在 TS_AUTHKEY 环境变量中使用可重用授权密钥的替代方法。
authkey:<key>语法指定，例如 [tailscale-server]
...
authorisation = "authkey:tskey-auth-xxxxxxxxxxxx-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
...
oauth2:<credentials>语法，例如 [tailscale-server]
...
authorisation = "oauth2:.credentials.workship"
...
credentials是一个 JSON 文件，其中包含 OAuth2 客户端的 OAuth2 凭据，例如
{
"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和client-secret是在 Tailscale 管理控制台上创建 OAuth2 客户端时生成的密钥。tailnet是用户/组织帐户名称（不是tailnet DNS 名称），但可以默认为“-”，因为 API 密钥是特定于组织/客户端的。IP/输出连接器支持以下与控制器的连接：
默认连接是 UDP 广播，但 TOML 配置文件中的特定控制器可以配置为 UDP“sendto”或 TCP 连接，使其成为适用于所有实际用途的“TOML”连接器：
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有一个内部速率限制，限制每秒可以处理的请求数。默认设置相当保守：
这些限制可以在 TOML 配置文件中更改，例如：
...
rate-limit = 5
rate-limit-burst = 300
...
支持分数速率限制，例如rate-limit = 0.1
