uhppoted tunnel
1.0.0
Туннелирует UDP-пакеты между парой компьютеров, чтобы обеспечить удаленный доступ к контроллеру UHPPOTE.
Технически это не совсем туннель, за исключением того, что вы, будучи пакетом, входите в темную, неприступную дыру, происходят загадочные и, возможно, невыразимые вещи, и через некоторое время вы выходите, моргая на свету, в совершенно другом месте. Так что, вероятно, это скорее реле или прокси ... но мы все равно собираемся использовать туннель .
Реализация включает в себя следующие разъемы:
Для тех неприятных моментов, когда было бы неплохо запустить приложение UHPPOTE AccessControl , но контроллер находится в одном месте, а хост-машина — в другом (или, возможно, на VPS в Норвегии), что означает, что широковещательная передача UDP не просто работает. А проделать дыры в брандмауэре и настроить NAT или настроить VPN либо не получится, либо это больше проблем, чем того стоит.
Также полезно для удаленного использования
и является более простой альтернативой:
Поддерживаемые операционные системы:
**v0.8.9 - 06.09.2024
Исполняемые файлы для всех поддерживаемых операционных систем упакованы в выпуски:
Архив-архивы релизов содержат исполняемые файлы для всех операционных систем. Архив-архивы для конкретных ОС со всеми компонентами uhpppoted можно найти в релизах 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 .
| Зависимость | Описание |
|---|---|
| uhppot-ядро | Реализация API на уровне устройства |
| uhppoted-lib | Общие библиотечные функции |
| golang.org/x/sys | (для интеграции служб Windows) |
| Tailscale.com | библиотека tsnet для соединителей Tailscale |
Использование: 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 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 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 — это соединитель сервера TCP, который принимает только защищенные клиентские подключения 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
Клиентский соединитель TLS — это клиентский соединитель TCP, который подключается только к серверам, защищенным 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
Коннектор 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 — это соединитель HTTP POST, который принимает только клиентские соединения 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
ПОСТ-запрос:
{
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 Tailnet, которое будет использоваться на сервере (обязательно)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 и перенаправляет команды на сервер Tailscale, подключенный к контроллеру доступа.
Адрес клиента Tailscale включает в себя:
machine Tailnet, которое будет использоваться для сервера (необязательно, но рекомендуется)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 будут использовать ключ авторизации в переменной среды 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 — это ключи, генерируемые при создании клиента OAuth2 в консоли администратора Tailscale.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
uhppoted-tunnel имеет внутренний лимит скорости, который ограничивает количество запросов в секунду, которые могут быть обработаны. Настройки по умолчанию достаточно консервативны:
Эти ограничения можно изменить в файле конфигурации TOML, например:
...
rate-limit = 5
rate-limit-burst = 300
...
Поддерживаются дробные ограничения скорости, например rate-limit = 0.1
