p2tunnel – OpenHPSDR protocol P2 UDP proxy
  • C 64%
  • C++ 21%
  • Shell 11.7%
  • CMake 2%
  • Makefile 1.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-24 10:06:49 +02:00
assets Add Windows GUI build target and executable icon 2026-10-21 21:57:23 +02:00
packaging Add the two-interface option into the server cli app 2026-10-22 21:58:48 +02:00
src Add version string 2026-10-24 10:06:49 +02:00
.gitignore Begin p2tunnel solution 2026-10-19 18:47:26 +02:00
build-windows-bundle.sh Add WIN bundling 2026-10-23 09:36:05 +02:00
CMakeLists.txt Add version string 2026-10-24 10:06:49 +02:00
dist-macos-p2tunnel.sh Overhaul some functions (OS depend) 2026-10-22 19:24:09 +02:00
Makefile Add version string 2026-10-24 10:06:49 +02:00
README.md Add the two-interface option into the server cli app 2026-10-22 21:58:48 +02:00

p2tunnel – experimental P2 UDP proxy (v0.1)

Build on macOS or Linux: make.

Server (host on same LAN as SDR):

./p2tunnel-server 192.168.1.10 192.168.1.100 12000

Client (host running deskHPSDR):

./p2tunnel-client 127.0.0.1 192.168.1.10 12000

Configure deskHPSDR to discover the client proxy IP (targeted discovery); loopback may not be an eligible discovery interface in deskHPSDR. Prefer a real local interface IP for initial testing. Only one deskHPSDR instance / SDR supported. The server binds to a real LAN address, and the SDR must reply to the UDP source IP/port of the server.

Important limitations

This is an unvalidated experimental prototype, NOT safe for transmitting. Do not connect a power amplifier or enable MOX/TUNE. RX-only laboratory tests first.

  • API-key authentication and per-packet integrity/replay protection are provided, but no encryption. TX stop delivery and RF shutdown are not guaranteed by UDP sends.
  • Discovery works only when deskHPSDR actually probes the configured client IP. Client's P2 sockets bind 1024–1042, which may conflict with other processes.
  • The single UDP socket at the server assumes SDR sends all streams to the source port of host control datagrams; this needs testing against the target hardware.
  • This prototype does not yet validate the complete P2 start/stop and RX stream behavior, nor handle SDR-specific remote IP restrictions.
  • Does not provide multiple clients, multiple SDRs, Windows, telemetry, loss metrics, or safe reconnection.
  • IPv4 only.

Next verification

Capture traffic at both ends (tcpdump) during discovery and RX-only startup, and confirm the source/destination port mapping and actual stream delivery. Verify discovery response device identity and deskHPSDR's network interface selection before extending to TX.

macOS application bundle

With Qt6, CMake, OpenSSL and macdeployqt installed (for example via Homebrew), build the GUI and package its Qt dependencies:

make app
open build/bin/p2tunnel.app

make app creates build/bin/p2tunnel.app with the GUI in Contents/MacOS/p2tunnel and the client in Contents/MacOS/p2tunnel-client. macdeployqt deploys Qt libraries and plugins and inspects the additional client executable. The client key and GUI settings remain in the OS-specific configuration directory, not in the application bundle.

This target does not sign or notarize the bundle. For redistribution, check all non-system dynamic libraries with otool -L (especially OpenSSL used by the client), then sign and notarize the final bundle as appropriate. The CLI and Windows/Linux builds are unchanged.

Qt6 client GUI (macOS/Linux)

Requires Qt6 Widgets/Network and CMake >= 3.20. Build all three programs:

cmake -S . -B build
cmake --build build
./build/bin/p2tunnel-gui

The GUI launches p2tunnel-client from the same directory as its executable. It controls the client as a subprocess; it does not handle P2/UDP packets. The status Running means the client process is running, not that an SDR connection or heartbeat acknowledgement has been verified. Closing the GUI terminates the client; the server-side TX failsafe remains independent and must be tested before using RF transmission. The client accepts IPv4 addresses and DNS/DynDNS hostnames (resolved at startup). DNS itself does not provide authentication; the shared API key authenticates packets. The original make CLI build remains available unchanged.

API-key authentication (required)

The Qt6 client GUI provides Generate, Import..., and Show/Hide for the API key. Generate a new key or import an existing api.key file while disconnected. An existing key is replaced only after confirmation. The client uses the same 64-character hexadecimal key as the Linux server.

Client configuration paths:

OS GUI settings Shared API key
Windows %LOCALAPPDATA%\p2tunnel\client.ini %LOCALAPPDATA%\p2tunnel\api.key
macOS ~/Library/Application Support/p2tunnel/client.ini ~/Library/Application Support/p2tunnel/api.key
Linux ~/.config/p2tunnel/client.ini ~/.config/p2tunnel/api.key

The Qt6 GUI stores settings in client.ini using INI-format QSettings. The standalone C client reads api.key from the same OS-specific directory. Existing configurations are not migrated automatically.

On the Linux server, install the same key in /etc/p2tunnel/api.key (one line containing 64 hexadecimal characters). The server reads it at startup. For the systemd service, use root:p2tunnel ownership and mode 0640 so the service account can read the key.

Packets remain unencrypted. Each UDP tunnel frame carries an 8-byte monotonic counter and a 16-byte truncated HMAC-SHA256 tag covering the header, payload and counter. A 64-packet receive window rejects duplicate and stale packets while tolerating normal UDP reordering. Unauthenticated traffic cannot start or refresh a server session. Both endpoints must run this version; the previous unauthenticated protocol is incompatible.

Operational limitations: The key is shared by both endpoints and is not transmitted. Anyone who obtains the key can control the tunnel. The protocol does not conceal SDR activity, and the server remains susceptible to network-level denial of service. An attacker able to capture and delay valid authenticated traffic can replay it only inside the receive window; this is not a substitute for a full secure transport. Keep the key private.

For a public deployment, independently verify that the server TX failsafe actually stops RF output on the SDR and test reconnect after a timeout.

Raspberry Pi OS systemd service

Build on the Pi using make, then install with sudo packaging/install-server.sh 192.168.253.53. The installer creates a non-login p2tunnel service account and /etc/p2tunnel/server.conf on first installation. Edit that file to change the SDR address, bind interface, or port.

On servers with two separate network interfaces, optionally set P2T_SDR_BIND=eth1 in /etc/p2tunnel/server.conf (or export the variable when launching manually). The existing P2T_BIND continues to select the tunnel-facing interface; P2T_SDR_BIND selects the local IPv4 address used by the SDR-facing socket for discovery, P2 traffic and TX failsafe. It accepts an interface name or local IPv4 address. On Linux, an interface name also enables SO_BINDTODEVICE, restricting the SDR socket to that interface; a numeric IPv4 address only binds the local address. A valid route to the SDR is still required. Example:

P2T_BIND=eth0
P2T_SDR_BIND=eth1
P2T_SDR=192.168.10.100
P2T_PORT=12000

Default unchanged: If P2T_SDR_BIND is unset or empty, both sockets use the original P2T_BIND address. For P2T_BIND=all, the SDR socket continues to bind to 0.0.0.0 unless explicitly overridden.

Place the same 64-character hexadecimal key as the client in /etc/p2tunnel/api.key; use sudo chown root:p2tunnel and sudo chmod 0640 on the file. The systemd unit packaging/p2tunnel-server.service sets P2T_SERVER_KEY_FILE=/etc/p2tunnel/api.key directly, so the service reads this path automatically; manual CLI use also defaults to /etc/p2tunnel/api.key.

sudo systemctl enable --now p2tunnel-server starts the service after the key has been installed. Check with systemctl status p2tunnel-server or journalctl -u p2tunnel-server -f. SIGTERM/SIGINT triggers the existing three-datagram TX failsafe before process exit when a session is active. A hard crash or power failure cannot guarantee RF shutdown.

Windows (MSYS2 UCRT64 / Qt 6)

Install the MSYS2 UCRT64 packages mingw-w64-ucrt-x86_64-toolchain, mingw-w64-ucrt-x86_64-cmake, mingw-w64-ucrt-x86_64-ninja, mingw-w64-ucrt-x86_64-qt6-base, and mingw-w64-ucrt-x86_64-openssl. From the UCRT64 shell:

cmake -S . -B build-win -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build-win
./build-win/bin/p2tunnel-gui.exe

Keep p2tunnel-client.exe alongside p2tunnel-gui.exe. The Windows GUI stores the API key under %LOCALAPPDATA%\p2tunnel\api.key, matching the standalone client. GUI settings are in client.ini alongside it. The same 64-character key must be installed on the Raspberry Pi server. Select 127.0.0.1 as the local P2 address for deskHPSDR. The server is built and installed on Linux, not Windows.

macOS standalone distribution

Run bash ./dist-macos-p2tunnel.sh for a clean Release build, deployment, Developer ID signing and a ZIP in dist/. Run PUBLISH=1 bash ./dist-macos-p2tunnel.sh to notarize and staple. Configure IDENTITY and PROFILE through environment variables if needed. make app remains a local build only.