uhppoted tunnel
1.0.0
マシンのペア間で UDP パケットをトンネリングし、UHPPOTE コントローラーのリモート アクセスを可能にします。
技術的には、それは実際にはトンネルではありませんが、パケットとして暗い禁断の穴に入ると、神秘的でおそらく言葉では言い表せないことが起こり、しばらくしてまったく別の場所で光の中で点滅しながら現れます。したがって、おそらくリレーかプロキシが必要ですが、とにかくトンネルを使用します。
実装には次のコネクタが含まれます。
UHPPOTE AccessControlアプリケーションを実行できればいいのに、コントローラーが 1 つの場所にあり、ホスト マシンが別の場所 (またはノルウェーの VPS 上) にあるため、UDP ブロードキャストが正常に動作しないという非常に面倒な場合に備えてです。そして、ファイアウォールに穴を開けて NAT を調整したり、VPN を設定したりすることは、実現しないか、価値以上に面倒な作業です。
遠隔地からの利用にも便利
これは次のより簡単な代替手段です。
サポートされているオペレーティング システム:
**v0.8.9 - 2024-09-06
サポートされているすべてのオペレーティング システムの実行可能ファイルがリリースにパッケージ化されています。
リリースの tarball には、すべてのオペレーティング システムの実行可能ファイルが含まれています。すべてのuppotedコンポーネントを含む OS 固有の 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ディレクトリに構築します。
| 依存 | 説明 |
|---|---|
| ウッポテコア | デバイスレベルのAPI実装 |
| ウッポテッド・ライブラリ | 共通ライブラリ関数 |
| golang.org/x/sys | (Windowsサービス統合用) |
| テールスケール.com | Tailscale コネクタ用のtsnetライブラリ |
使用法: uhppoted-tunnel <command> --in <connector> --out <connector> <options>
サポートされているコマンド:
helpversionrundaemonizeundaemonize提供されていないコマンド、つまり、 uhppoted-tunnel --in <connector> --out <connector> <options>がuhppoted-tunnel run --in <connector> --out <connector> <options>と同等の場合にデフォルトでrunます。 。
uppoted-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
一般に、トンネルはペアで動作します。1 つはホスト上で、 AccessControlアプリケーションやuppote-cliなどからのコマンドを待機し、もう 1 つはコントローラに対してローカルなクライアント上で、コマンドをコントローラに送信して応答を返します。ホストに。ただし、複数のトンネルをチェーンして、複数のマシン間をブリッジすることは可能です。
イベントコネクタは、イベントが応答を期待せずに一方向にのみ中継されるという点で、UDPリッスンコネクタとブロードキャストコネクタを特殊化したものです。イベントを中継するためにリッスンコネクタとブロードキャストコネクタを使用することは十分に可能ですが、特殊なコネクタはユースケースに合わせてわずかに最適化されており、特殊なコネクタに依存する可能性のある将来の機能拡張をサポートするためにも導入されています。
daemonize uhppoted-tunnelシステム起動時に開始されるシステム サービスとして登録します。このコマンドは、必要なシステム固有のサービス構成ファイルとサービス マネージャー エントリを作成します。
Linux の場合:
uhppoted:uhppoted user:group を使用します - これは--userオプションで変更できますsudo systemctl enable uhppoted-tunnel-xxxを実行する必要がある場合があります。network-online.targetを待機するように構成されています (https://systemd.io/NETWORK_ONLINE を参照)。特定のインターフェイスを待機するには、systemd-networkd-wait-online.service を待機するようにユニット ファイル ( /etc/systemd/system/uhpppoted-tunnel-xxx ) を変更します。コマンドライン:
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.
uppoted-tunnel には、いくつかの制限はありますが、一般に組み合わせて使用できる複数のコネクタのサポートが含まれています。
INコネクタ：
OUTコネクタ:
バインド アドレスで受信 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 サーバー コネクタは 1 つ以上の 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
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,,...]
}
返事：
{
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
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,,...]
}
返事：
{
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サーバー コネクタは、1 つ以上の Tailscale クライアントからの接続を受け入れるリスニング Tailscale 接続を確立します。 TCP コネクタとは異なり、 INコネクタとしてのみ機能するように設計されています。受信リクエストは、接続されているすべてのクライアントに転送されます。
Tailscale サーバーのアドレスは以下で構成されます。
machine名 (必須)debug 。 Tailscale のログは非常に詳細であるため、デフォルトは「ログなし」ですが、接続の問題のデバッグに役立つ場合や必要な場合があります。唯一の有効な値はdebugです。他の値 (nolog など) をプレースホルダー ニーモニックとして使用できます。 --in tailscale/server:<device>:<port>[,debug]
e.g.
--in tailscale/server:uhppoted:12345,debug
--in tailscale/server:uhppoted:12345,nolog
Tailscale は現在、特定のインターフェイスへのバインディングをサポートしていないことに注意してください (ref. tailscale/tailscale#1552)。
Tailscaleクライアント コネクタは、リッスンするTailscaleサーバー接続に接続します。 TCP および UDP クライアント コネクタとは異なり、Tailscale クライアント コネクタはOUTコネクタとしてのみ構成できます。つまり、UDP IN ポートでコマンドを受信し、アクセス コントローラーに接続されている Tailscale サーバーにコマンドを転送することを想定しています。
Tailscale クライアントアドレスは以下で構成されます。
machine名 (オプションですが推奨)debug 。 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 は現在、特定のインターフェイスへのバインディングをサポートしていないことに注意してください (ref. tailscale/tailscale#1552)。
デフォルトでは、Tailscale テールネットへの接続では、TS_AUTHKEY 環境変数の認証キーが使用されます。環境変数が定義されていない場合、または空白の場合は、認証 URL の入力を求めるプロンプトが表示されます。
代替の認証方法は、TOML 構成ファイル ( --configコマンド ライン オプションを使用して指定) で構成できます。
env:<variable name>構文を使用して、別の環境変数を指定できます。例: [tailscale-server]
...
authorisation = "env:TS_WORKSHOP"
...
これは、同じマシン上で 2 つ以上のトンネルを実行するときに TS_AUTHKEY 環境変数で再利用可能な認証キーを使用する代わりの方法です。
authkey:<key>構文を使用して直接指定できます。たとえば、 [tailscale-server]
...
authorisation = "authkey:tskey-auth-xxxxxxxxxxxx-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
...
oauth2:<credentials>構文を使用する OAuth2 クライアント。例: [tailscale-server]
...
authorisation = "oauth2:.credentials.workship"
...
credentialsは、OAuth2 クライアントの OAuth2 認証情報を含む JSON ファイルです。
{
"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はユーザー/組織のアカウント名 (テールネット DNS 名ではありません) ですが、API キーは組織/クライアント固有であるため、デフォルトで「-」に設定できます。IP/out コネクタは、コントローラへの次の接続をサポートします。
デフォルトの接続は 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
uppoted-tunnel には、処理できる 1 秒あたりのリクエスト数を制限する内部レート制限があります。デフォルト設定はかなり保守的です。
これらの制限は、TOML 設定ファイルで変更できます。例:
...
rate-limit = 5
rate-limit-burst = 300
...
端数のレート制限がサポートされています (例: rate-limit = 0.1
