Tunneling & IPC
Relevant source files
The following files were used as context for generating this wiki page:
The Hoop Tunnel daemon (hsh-tunneld) is a privileged client-side service that enables developers to access remote infrastructure through local networking abstractions. By leveraging a userspace network stack and a TUN device, it allows standard tools (e.g., psql, mysql) to reach hoop connections via deterministic names (e.g., pg-prod.hoop) as if they were on the local network.
The system operates without a custom gateway protocol. Instead, for every TCP flow accepted by the local netstack, the daemon opens a fresh gRPC bidirectional stream (Transport.Connect) to the existing hoop gateway. This architecture ensures that all gateway-level features—such as authentication, audit logging, DLP, and access controls—are applied to tunneled traffic automatically.
Sources: tunnel/README.md:3-17, tunnel/cmd/hsh-tunneld/main.go:5-13
System Architecture
The tunneling system consists of several integrated modules that manage networking, DNS resolution, and local communication.
High-Level Components
- Netstack (
gVisor): A userspace network stack that handles TCP flows and wires the TUN device (/dev/net/tunon Linux,utunon macOS). - Resolver: An in-stack DNS resolver that answers
AandAAAAqueries for the.hoopTLD. - Tunnel Manager (
tunnelmgr): The lifecycle owner responsible for bringing the netstack online, managing the gRPC gateway connection, and configuring host routes. - IPC Server: A local control plane providing an HTTP/JSON API over a Unix domain socket for unprivileged client interactions.
Sources: tunnel/README.md:27-36, tunnel/cmd/hsh-tunneld/main.go:193-207
Data Flow Overview
The following diagram illustrates the path of a request from a local application to the remote upstream resource:
The architecture ensures that the gateway sees each flow as an ordinary client session.
Sources: tunnel/README.md:19-25
Addressing and Connectivity
Every connection is allocated stable virtual IPs from a deterministic, session-seeded map to avoid collisions with local networks.
Dual-Stack Addressing
To ensure compatibility across different operating systems (particularly macOS getaddrinfo limitations), the tunnel implements a dual-stack approach:
- IPv6 ULA: Allocated inside a per-session
fd00::/8/48prefix. - IPv4 CGNAT: Allocated inside a per-session
100.64.0.0/10/16(RFC 6598) space.
| Protocol Family | Address Space | Rationale |
|---|---|---|
| IPv6 (ULA) | fd00::/8 | Native addressing for the userspace stack. |
| IPv4 (CGNAT) | 100.64.0.0/10 | Overcomes macOS AAAA resolution gating when no global IPv6 is present. |
| Sources: tunnel/README.md:126-140 |
Connection Filtering
Only TCP-style protocols are supported for tunneling. Interactive or protocol-specific connections (e.g., SSH, HTTP-proxy, Kubernetes) are filtered out of the resolver and require the standard hoop connect CLI.
- Supported Subtypes:
postgres,mysql,mssql,mongodb,oracledb,tcp.
Sources: tunnel/README.md:118-124, tunnel/ipc/openapi.yaml:61-68
Local IPC Control Plane
The daemon exposes a local-only HTTP/JSON API to allow unprivileged UIs (CLI, tray, dashboard) to drive its operations.
IPC Transport & Security
The IPC layer never binds to a TCP port. It uses platform-specific local transports:
- Linux/macOS: Unix domain socket at
/var/run/hsh/hsh.sock. - Windows: Named pipe at
\\.\pipe\hsh.
Authentication is handled via a rotating bearer token written to /var/run/hsh/control-token with restricted permissions (mode 0640, group hsh).
Sources: tunnel/ipc/openapi.yaml:12-23
API Endpoints (V1)
The IPC server facilitates daemon lifecycle management and status monitoring.
| Endpoint | Method | Purpose |
|---|---|---|
/v1/status | GET | Snapshot of the daemon state (running, logged in, version). |
/v1/connections | GET | List of tunnelable connections exposed as *.hoop. |
/v1/tunnel/up | POST | Synchronously brings the tunnel netstack online. |
/v1/tunnel/down | POST | Tears the netstack down while keeping the token intact. |
/v1/login/local | POST | Sync email/password login for local-auth gateways. |
/v1/reconnect | POST | Asynchronously re-establishes gateway gRPC pipes. |
| Sources: tunnel/ipc/openapi.yaml:153-270 |
Service Management (Linux systemd)
For production environments, the daemon runs as a systemd service. The unit configuration emphasizes security hardening and reliability.
Hardening Clauses
The systemd unit uses a strict security profile to limit the daemon's blast radius while maintaining the CAP_NET_ADMIN capability required for TUN device management.
- ProtectSystem=strict: Renders the system read-only except for explicitly declared directories.
- RuntimeDirectory=hsh: Creates
/run/hsh/(mode 0750) for the IPC socket and token. - DeviceAllow=/dev/net/tun: Restricts hardware access specifically to the TUN device.
- CapabilityBoundingSet=CAP_NET_ADMIN: Limits the root process to networking administration tasks only.
Sources: tunnel/service/unit_linux.go:21-49, tunnel/service/unit_linux.go:138-164
Startup Flow
The service ensures configuration validity before attempting to start the network stack.
Implementation Details
Configuration Persistence
The daemon manages its own configuration in a TOML file (defaulting to platform-specific paths like /etc/hsh/config.toml). Environment variables (prefixed with HOOP_) overlay these values at runtime but are not persisted back to disk.
Sources: tunnel/cmd/hsh-tunneld/main.go:174-184, tunnel/cmd/hsh-tunneld/main.go:273-286
Limitations (V1)
- UDP Support: The tunnel is currently limited to TCP traffic only.
- ICMP (Ping): Works over IPv6 (answered by gVisor) but not IPv4 due to the promiscuous/spoofing mode of the userspace stack.
- Reconnection: Each flow is independent; if a gRPC stream dies, the application must re-initiate the connection.
Sources: tunnel/README.md:154-173
Conclusion
The Tunneling & IPC system provides a seamless local networking experience for accessing remote infrastructure. By isolating networking logic into a privileged daemon and providing a secure local IPC for user interaction, it balances developer productivity with strict organizational security requirements.