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
