A modular, multi-transport network tunnel with QUIC, HTTP/3, and MASQUE support.
QTunnel is a network tunneling engine designed with a clear separation between session logic and transport carriers. It supports multiple transport protocols:
| Transport | Status | Use Case |
|---|---|---|
| Native QUIC | β v0.1 (MVP) | TCP proxy, simple deployment |
| HTTP/3 + MASQUE | π‘ v0.2 | UDP proxy (CONNECT-UDP), VPN (CONNECT-IP) |
| HTTP/2 Fallback | π Planned | Restricted networks (custom protocol) |
- π TLS 1.3 only - No downgrade, no weak ciphers
- π Token authentication - 256-bit entropy, constant-time compare, hot reload
- π¦ TCP Proxy - Bidirectional streaming over QUIC streams
- β‘ Connection migration - Native QUIC mobility support
- π‘οΈ Resource limits - Connections, streams, buffers, timeouts
- π Observability - Prometheus metrics, structured logging, health checks
- π§ͺ Well-tested - Unit, integration, fuzz, race detector
- π CONNECT-UDP (RFC 9298) - Standards-based UDP proxying
- π CONNECT-IP (RFC 9484) - Full IP-layer VPN
- π₯οΈ TUN Integration - Linux, Windows (Wintun), macOS
- π Split tunneling - Route selection, DNS handling
- π Kill switch - Leak prevention
- Go 1.23+ (for building)
- TLS certificate (Let's Encrypt recommended for production)
git clone https://github.com/iliyahaddad/qtunnel
cd qtunnel
make build
make certs # Generates test certificatesServer (configs/server.yaml):
role: "server"
listen:
addr: ":4433"
tls:
cert_file: "server.crt"
key_file: "server.key"
auth:
tokens: ["base64-encoded-32-byte-token"]
proxy:
mode: "tcp"
allowlist: ["*"]
denylist: ["10.0.0.0/8", "127.0.0.0/8", "::1"]
limits:
max_connections: 1000
max_streams_per_conn: 100Client (configs/client.yaml):
role: "client"
server:
addr: "your-server.example.com:4433"
sni: "your-server.example.com"
auth:
token: "base64-encoded-32-byte-token"
proxy:
mode: "tcp"
listen: "127.0.0.1:8080"# Terminal 1: Server
./bin/qtunnel-server -c configs/server.yaml
# Terminal 2: Client
./bin/qtunnel-client -c configs/client.yaml
# Terminal 3: Test
curl -v http://httpbin.org/get --proxy http://127.0.0.1:8080./bin/qtunnel-diagnose secret
# Output: base64-encoded 32-byte tokenβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Application Layer β
β TCP Proxy β SOCKS5 (planned) β VPN/TUN (planned) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Session Layer β
β Auth β Stream Mux β Flow Control β Lifecycle β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Frame Layer β
β CONNECT β DATA β CLOSE β PING β AUTH β WINDOW_UPDATE β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Carrier Layer β
β Native QUIC β HTTP/3 (MASQUE) β HTTP/2 (planned) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Document | Description |
|---|---|
| THREAT-MODEL.md | Comprehensive threat model |
| PROTOCOL.md | Wire protocol specification |
| SECURITY.md | Security policy |
| TESTING.md | Testing guide |
| TROUBLESHOOTING.md | Common issues |
| ROADMAP.md | Future plans |
- No custom crypto - Uses Go stdlib TLS 1.3 and quic-go
- Certificate verification mandatory - Cannot be disabled in production config
- Token authentication - 256-bit entropy, constant-time comparison
- Resource limits - Prevents DoS via connection/stream/buffer bounds
- Fuzzing - All parsers fuzzed in CI
- Race detector - All tests run with
-racein CI
See SECURITY.md for vulnerability reporting and secure configuration guidelines.
# Unit tests
make test
# With race detector
make test-race
# With coverage
make test-cover
# Fuzzing (30s per target)
make test-fuzz
# Benchmarks
make test-bench
# Integration tests
make test-integration# Cross-compile
GOOS=linux GOARCH=amd64 make build
GOOS=windows GOARCH=amd64 make build
GOOS=darwin GOARCH=arm64 make build
# With version info
make build VERSION=v1.0.0FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN make build
FROM alpine:3.20
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/bin/qtunnel-server /usr/local/bin/
COPY --from=builder /app/bin/qtunnel-client /usr/local/bin/
ENTRYPOINT ["qtunnel-server"][Unit]
Description=QTunnel Server
After=network.target
[Service]
Type=simple
User=qtunnel
ExecStart=/usr/local/bin/qtunnel-server -c /etc/qtunnel/server.yaml
Restart=on-failure
RestartSec=5
LimitNOFILE=65536
[Install]
WantedBy=multi-user.targetSee configs/client.example.yaml and configs/server.example.yaml for complete examples.
| Option | Description | Default |
|---|---|---|
transport.type |
Carrier: quic, http3 |
quic |
transport.quic.max_idle_timeout |
Idle timeout | 30s |
transport.quic.keep_alive |
Keep-alive interval | 10s |
limits.max_connections |
Max concurrent connections | 1000 |
limits.max_streams_per_conn |
Max streams per connection | 100 |
limits.stream_buffer_size |
Per-stream receive buffer | 1MB |
proxy.allowlist |
Destination allowlist | ["*"] |
proxy.denylist |
Destination denylist | RFC1918, localhost |
See CONTRIBUTING.md for development workflow, coding standards, and PR process.
see LICENSE for details.
- quic-go - QUIC/HTTP/3 implementation
- masque-go - CONNECT-UDP reference
- connect-ip-go - CONNECT-IP reference
- IETF MASQUE WG - Standards development
Current: v0.1.0-alpha (Milestone 2 - Foundation)
See ROADMAP.md for release timeline.