uhppoted tunnel
1.0.0
UHPPOTE 컨트롤러 원격 액세스를 활성화하기 위해 한 쌍의 시스템 간에 UDP 패킷을 터널링합니다.
엄밀히 말하면 그것은 실제로 터널이 아닙니다. 단, 패킷이 어둡고 금지된 구멍에 들어가면 신비스럽고 아마도 말할 수 없는 일이 일어나고 얼마 후 완전히 다른 곳에서 빛을 깜박이며 나타난다는 점을 제외하면 그것은 실제로 터널이 아닙니다. 그래서 아마도 릴레이나 프록시가 더 많을 것입니다. 하지만 어쨌든 우리는 터널을 사용할 것입니다.
구현에는 다음 커넥터가 포함됩니다.
UHPPOTE AccessControl 애플리케이션을 실행하는 것이 좋을 것 같지만 컨트롤러가 한 곳에 있고 호스트 시스템이 다른 곳에(또는 노르웨이의 VPS에 있을 수도 있음) 있어서 UDP 브로드캐스트가 제대로 작동하지 않는 매우 짜증나는 경우를 위한 것입니다. 그리고 방화벽에 구멍을 뚫고 NAT를 조정하거나 VPN을 설정하는 일은 일어나지 않거나 그만한 가치보다 더 큰 문제입니다.
원격으로 사용할 때도 유용합니다.
다음과 같은 간단한 대안이 있습니다.
지원되는 운영 체제:
**v0.8.9 - 2024-09-06
지원되는 모든 운영 체제에 대한 실행 파일은 릴리스에 패키지되어 있습니다.
릴리스 타르볼에는 모든 운영 체제에 대한 실행 파일이 포함되어 있습니다. 모든 uhppoted 구성 요소가 포함된 OS 특정 타르볼은 uhpppoted 릴리스에서 찾을 수 있습니다.
설치는 간단합니다. 아카이브를 다운로드하고 원하는 디렉터리에 추출합니다. 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 구현 |
| uhpoted-lib | 공통 라이브러리 함수 |
| golang.org/x/sys | (Windows 서비스 통합용) |
| tailscale.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 . .
uhpoted-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 시스템 부팅 시 시작되는 시스템 서비스로 등록합니다. 이 명령은 필요한 시스템별 서비스 구성 파일과 서비스 관리자 항목을 만듭니다.
리눅스의 경우:
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.
uhpoted-tunnel에는 일반적으로 혼합 및 일치할 수 있는 여러 커넥터에 대한 지원이 포함되어 있지만 몇 가지 제한 사항이 있습니다.
IN 커넥터:
출력 커넥터:
바인드 주소 에서 들어오는 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
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 서버 커넥터는 하나 이상의 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은 현재 특정 인터페이스에 대한 바인딩을 지원하지 않습니다(참조 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은 현재 특정 인터페이스에 대한 바인딩을 지원하지 않습니다(참조 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> 구문을 사용하는 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 은 사용자/조직 계정 이름(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
uhpoted-tunnel 에는 처리할 수 있는 초당 요청 수를 제한하는 내부 속도 제한이 있습니다. 기본 설정은 합리적으로 보수적입니다.
이러한 제한은 TOML 구성 파일에서 변경할 수 있습니다. 예:
...
rate-limit = 5
rate-limit-burst = 300
...
부분 비율 제한이 지원됩니다(예: rate-limit = 0.1
