Menerobos paket UDP antara sepasang mesin untuk mengaktifkan akses jarak jauh pengontrol UHPPOTE.
Secara teknis, ini bukanlah sebuah terowongan, kecuali dalam arti bahwa sebagai sebuah paket Anda memasuki lubang gelap yang terlarang, hal-hal misterius dan mungkin tak terkatakan terjadi dan Anda muncul beberapa waktu kemudian, berkedip dalam cahaya di tempat yang sama sekali berbeda. Jadi mungkin lebih merupakan relay atau proxy .. tapi kami tetap menggunakan terowongan .
Implementasinya mencakup konektor berikut:
Untuk saat-saat yang sangat menjengkelkan ketika menjalankan aplikasi UHPPOTE AccessControl akan menyenangkan tetapi pengontrolnya ada di satu tempat dan mesin host di tempat lain (atau mungkin di VPS di Norwegia) yang berarti siaran UDP tidak hanya berfungsi. Dan melubangi firewall dan mengubah NAT atau menyiapkan VPN tidak akan terjadi atau lebih merepotkan daripada manfaatnya.
Juga berguna untuk penggunaan jarak jauh
dan merupakan alternatif yang lebih sederhana untuk:
Sistem operasi yang didukung:
**v0.8.9 - 06-09-2024
Executable untuk semua sistem operasi yang didukung dikemas dalam rilis:
Tarbal rilis berisi executable untuk semua sistem operasi - tarbal khusus OS dengan semua komponen yang di-uhppot dapat ditemukan di rilis yang di-uhppot.
Instalasinya mudah - unduh arsip dan ekstrak ke direktori pilihan Anda. Untuk menginstal uhppoted-tunnel
sebagai layanan sistem:
cd <uhppoted directory>
sudo uhppoted-tunnel daemonize --in <connector> --out <connector> --label <label>
uhppoted-tunnel help
akan mencantumkan perintah yang tersedia dan opsi terkait (didokumentasikan di bawah).
Alat yang diperlukan:
Untuk membangun menggunakan Makefile yang disertakan:
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
make build
Tanpa menggunakan make
:
git clone https://github.com/uhppoted/uhppoted-tunnel.git
cd uhppoted-tunnel
go build -trimpath -o bin/ ./...
Perintah di atas membangun uhppoted-tunnel
yang dapat dieksekusi ke direktori bin
.
Ketergantungan | Keterangan |
---|---|
uhppote-inti | Implementasi API tingkat perangkat |
uhpoted-lib | Fungsi perpustakaan umum |
golang.org/x/sys | (untuk integrasi layanan Windows) |
skala ekor.com | perpustakaan tsnet untuk konektor Tailscale |
Penggunaan: uhppoted-tunnel <command> --in <connector> --out <connector> <options>
Perintah yang didukung:
help
version
run
daemonize
undaemonize
Default untuk run
jika perintah tidak diberikan yaitu uhppoted-tunnel --in <connector> --out <connector> <options>
setara dengan uhppoted-tunnel run --in <connector> --out <connector> <options>
.
Untuk uhppoted-tunnel v0.8.3+, konfigurasi runtime ditentukan dalam file TOML (didokumentasikan di sini) dan penyempurnaan apa pun di masa mendatang hanya dapat dikonfigurasi dalam file TOML.
Argumen baris perintah yang dijelaskan di bawah ini adalah untuk dukungan lama dan mengesampingkan pengaturan tertentu dalam konfigurasi TOML.
run
Menjalankan layanan uhppoted-tunnel
. Perintah default, dimaksudkan untuk digunakan sebagai layanan sistem yang berjalan di latar belakang.
Baris perintah:
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
Secara umum, terowongan beroperasi berpasangan - satu di host , mendengarkan perintah misalnya dari aplikasi AccessControl atau uhppote-cli dan yang lainnya di klien lokal ke pengontrol, yang mengirimkan perintah ke pengontrol dan mengembalikan balasan kepada tuan rumah . Namun, dimungkinkan untuk merangkai beberapa terowongan untuk menjembatani beberapa mesin.
Konektor peristiwa adalah spesialisasi dari konektor pendengar dan siaran UDP di mana peristiwa diteruskan dalam satu arah saja, tanpa mengharapkan balasan. Sangat mungkin untuk menggunakan konektor dengar dan siaran untuk menyampaikan peristiwa, tetapi konektor khusus sedikit dioptimalkan untuk kasus penggunaan dan juga telah diterapkan untuk mendukung peningkatan di masa mendatang yang mungkin bergantung pada konektor khusus.
daemonize
Mendaftarkan uhppoted-tunnel
sebagai layanan sistem yang akan dimulai saat boot sistem. Perintah ini membuat file konfigurasi layanan spesifik sistem dan entri manajer layanan yang diperlukan.
Di Linux:
uhppoted:uhppoted
user:group - ini dapat diubah dengan opsi --user
sudo systemctl enable uhppoted-tunnel-xxx
setelah melakukan daemonisasi agar layanan uhppoted-tunnel dapat dimulai saat boot.network-online.target
(lih. https://systemd.io/NETWORK_ONLINE). Untuk menunggu antarmuka tertentu, modifikasi file unit ( /etc/systemd/system/uhpppoted-tunnel-xxx ) untuk menunggu systemd-networkd-wait-online.serviceBaris perintah:
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
Membatalkan pendaftaran uhppoted-tunnel
sebagai layanan sistem, namun tidak menghapus log atau file konfigurasi apa pun yang dibuat.
Baris perintah:
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 menyertakan dukungan untuk beberapa konektor yang secara umum dapat dipadukan dan dicocokkan, dengan beberapa batasan:
Konektor IN :
Konektor KELUAR :
Mendengarkan paket UDP yang masuk pada alamat pengikatan , secara efektif bertindak sebagai proksi langsung untuk pengontrol jarak jauh.
--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
Mengirimkan paket yang diterima sebagai pesan UDP pada alamat siaran dan meneruskan balasan apa pun ke pemohon asli, yang secara efektif bertindak sebagai proksi untuk aplikasi jarak jauh.
--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
Konektor server TCP menerima koneksi dari satu atau lebih klien TCP dan dapat bertindak sebagai konektor IN dan konektor OUT . Permintaan yang masuk akan diteruskan ke semua klien yang terhubung.
--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
Konektor klien TCP terhubung ke server TCP dan dapat bertindak sebagai konektor IN dan konektor OUT . Permintaan/balasan yang masuk akan diteruskan ke server jauh.
--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
Konektor server TLS adalah konektor server TCP yang hanya menerima koneksi klien aman 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
Konektor klien TLS adalah konektor klien TCP yang hanya menyambungkan ke server aman 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
Konektor HTTP POST menerima permintaan JSON POST dan meneruskan balasan ke klien yang meminta, terutama untuk mendukung aplikasi berbasis browser yang cepat dan kotor (contoh kecil disertakan dalam folder contoh ).
--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
Permintaan POSTING:
{
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,,...]
}
Membalas:
{
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,...],
]
}
Konektor HTTPS POST adalah konektor HTTP POST yang hanya menerima koneksi klien 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
Permintaan POSTING:
{
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,,...]
}
Membalas:
{
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,...],
]
}
Konektor server Tailscale membuat koneksi Tailscale mendengarkan yang menerima koneksi dari satu atau lebih klien Tailscale. Berbeda dengan konektor TCP, konektor ini dirancang untuk bertindak hanya sebagai konektor IN . Permintaan yang masuk diteruskan ke semua klien yang terhubung.
Alamat server Tailscale terdiri dari:
machine
tailnet yang akan digunakan untuk server (wajib)debug
opsional untuk menampilkan logging koneksi tailscale. Defaultnya adalah 'tidak ada log' karena logging Tailscale sangat bertele-tele, namun terkadang berguna atau diperlukan untuk men-debug masalah koneksi. Satu-satunya nilai yang valid adalah debug
- nilai lain (misalnya nolog) dapat digunakan sebagai mnemonik placeholder. --in tailscale/server:<device>:<port>[,debug]
e.g.
--in tailscale/server:uhppoted:12345,debug
--in tailscale/server:uhppoted:12345,nolog
Harap dicatat bahwa Tailscale saat ini tidak mendukung pengikatan ke antarmuka tertentu (Ref. tailscale/tailscale#1552).
Konektor klien Tailscale terhubung ke koneksi server Tailscale yang mendengarkan. Berbeda dengan konektor klien TCP dan UDP, konektor klien Tailscale hanya dapat dikonfigurasi sebagai konektor OUT yaitu konektor tersebut mengharapkan untuk menerima perintah pada port UDP IN dan meneruskan perintah ke server Tailscale yang terhubung ke pengontrol akses.
Alamat klien Tailscale terdiri dari:
machine
tailnet yang akan digunakan untuk server (opsional, tetapi disarankan)debug
opsional untuk menampilkan logging koneksi tailscale. Defaultnya adalah 'tidak ada log' karena logging Tailscale sangat bertele-tele, namun terkadang berguna atau diperlukan untuk men-debug masalah koneksi. Satu-satunya nilai yang valid adalah debug
- nilai lain (misalnya nolog) dapat digunakan sebagai mnemonik placeholder. --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
Harap dicatat bahwa Tailscale saat ini tidak mendukung pengikatan ke antarmuka tertentu (Ref. tailscale/tailscale#1552).
Secara default, koneksi ke tailnet Tailscale akan menggunakan kunci otorisasi dalam variabel lingkungan TS_AUTHKEY. Jika variabel lingkungan tidak ditentukan atau kosong maka Anda akan dimintai URL otorisasi.
Metode otorisasi alternatif dapat dikonfigurasi dalam file konfigurasi TOML (ditentukan menggunakan opsi baris perintah --config
):
env:<variable name>
, misalnya [tailscale-server]
...
authorisation = "env:TS_WORKSHOP"
...
Ini merupakan alternatif untuk menggunakan kunci otorisasi yang dapat digunakan kembali dalam variabel lingkungan TS_AUTHKEY saat menjalankan dua terowongan atau lebih pada mesin yang sama.
authkey:<key>
, misalnya [tailscale-server]
...
authorisation = "authkey:tskey-auth-xxxxxxxxxxxx-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
...
oauth2:<credentials>
, misalnya [tailscale-server]
...
authorisation = "oauth2:.credentials.workship"
...
credentials
adalah file JSON yang berisi kredensial OAuth2 untuk klien OAuth2, misalnya
{
"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
dan client-secret
adalah kunci yang dihasilkan saat membuat klien OAuth2 di konsol admin Tailscale.tailnet
adalah nama akun pengguna/organisasi ( bukan nama DNS tailnet) tetapi dapat ditetapkan secara default ke '-' karena kunci API khusus untuk organisasi/klien.Konektor IP/out mendukung koneksi berikut ke pengontrol:
Koneksi default adalah siaran UDP tetapi pengontrol spesifik dalam file konfigurasi TOML dapat dikonfigurasi untuk koneksi UDP 'sendto' atau TCP, menjadikannya konektor 'TOML' saja untuk semua tujuan praktis:
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 memiliki batas kecepatan internal yang membatasi jumlah permintaan per detik yang dapat diproses. Pengaturan defaultnya cukup konservatif:
Batasan ini dapat diubah pada file konfigurasi TOML, misalnya:
...
rate-limit = 5
rate-limit-burst = 300
...
Batas tarif pecahan didukung, misalnya rate-limit = 0.1