docs(public): remove stealth-mode content, add SOCKS5 modes and connection tuning docs
This commit is contained in:
E. Kaparulin
@@ -35,7 +35,7 @@ Most VPNs treat TCP as a fallback. Konduit is designed for TCP from the ground u
|
||||
- **QR code provisioning** — scan once, connect instantly
|
||||
- **Cross-platform** — Linux, Windows, Android (macOS and iOS coming soon)
|
||||
- **Modern cryptography** — X25519 key exchange, ChaCha20-Poly1305 data channel
|
||||
- **Stealth mode** — port 443 deployment with decoy proxy for hostile network environments
|
||||
- **SOCKS5 chaining** — egress-dial (`use_proxy`) to reach the server through your own proxy, or a post-tunnel listener (`listen_socks`) for per-app routing — see [SOCKS Modes](docs/socks-modes.md)
|
||||
- **Memory safe** — written entirely in Rust
|
||||
|
||||
## Download
|
||||
@@ -95,7 +95,8 @@ Coming soon.
|
||||
**CLI & server**
|
||||
- [Client Quickstart](docs/client-quickstart.md) — download, configure, connect, run as a systemd service
|
||||
- [Server Quickstart](docs/server-quickstart.md) — install, provision, NAT setup for iptables and firewalld
|
||||
- [Stealth Mode Setup](docs/stealth-setup.md) — HAProxy TCP passthrough + camouflage configuration
|
||||
- [SOCKS5 Modes](docs/socks-modes.md) — reach the server through a proxy, or expose a local SOCKS5 listener
|
||||
- [Connection Tuning](docs/connection-tuning.md) — opt-in connection pooling for unstable links
|
||||
- [systemd units](docs/systemd/) — service files for konduit-server, konduit (client), and konduit-admin-ui
|
||||
|
||||
## Architecture
|
||||
@@ -124,7 +125,7 @@ Konduit engine (Rust)
|
||||
|
||||
The [`konduit-platform`](./konduit-platform) crate is published here for transparency and security audit. It contains the cryptographic primitives, connection statistics, and platform networking layer (TUN device, DNS, routes) — everything an auditor needs to verify what runs on your machine. It is licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE) — free to read, study, and use for noncommercial purposes.
|
||||
|
||||
The VPN server, management UI, and stealth-mode protocol are proprietary. Keeping stealth mechanisms private makes automated DPI fingerprinting significantly harder. Source review under NDA is available for enterprise partners.
|
||||
The VPN server and management UI are proprietary. Source review under NDA is available for enterprise partners.
|
||||
|
||||
## Security
|
||||
|
||||
@@ -132,8 +133,6 @@ The VPN server, management UI, and stealth-mode protocol are proprietary. Keepin
|
||||
|
||||
**Key storage:** Private keys are stored in the OS secure enclave on every platform (iOS Keychain, macOS Keychain, Android Keystore). They are never written to disk in plaintext.
|
||||
|
||||
**Stealth mode:** On port 443, failed or unrecognized handshakes are proxied transparently to a configurable decoy service. From the outside, the server is indistinguishable from a standard HTTPS endpoint.
|
||||
|
||||
## Support
|
||||
|
||||
**Bug reports:** Use the in-app reporting feature or open an issue in this repository.
|
||||
|
||||
@@ -18,8 +18,6 @@ sudo cp client.toml /opt/konduit/client.toml
|
||||
sudo chmod 600 /opt/konduit/client.toml
|
||||
```
|
||||
|
||||
If your server runs in stealth mode, the config already points to port 443. No additional client-side configuration is needed.
|
||||
|
||||
## 3. Connect
|
||||
|
||||
```bash
|
||||
|
||||
20
docs/connection-tuning.md
Normal file
20
docs/connection-tuning.md
Normal file
@@ -0,0 +1,20 @@
|
||||
# Connection Tuning
|
||||
|
||||
Konduit is a TCP-native VPN. On stable networks, a single TCP connection works fine. On unstable links (spotty Wi-Fi, mobile data, satellite), you can opt into a small pool of pre-warmed connections so a failing connection can be replaced without a full reconnect cascade.
|
||||
|
||||
## Config
|
||||
|
||||
```toml
|
||||
[connection]
|
||||
pool_enabled = false # default off; opt in for unstable links
|
||||
pool_size = 3 # pre-warmed idle connections when enabled
|
||||
carry_duration = 1.0 # seconds an active connection carries traffic before handoff
|
||||
```
|
||||
|
||||
- `pool_enabled` — when `true`, the client keeps `pool_size` extra pre-authenticated connections warm, so an in-use connection can fail over instantly instead of paying a fresh TCP-plus-handshake cost.
|
||||
- `pool_size` — number of pre-warmed idle connections to keep, in addition to the active one. Only used when `pool_enabled = true`.
|
||||
- `carry_duration` — how long (in seconds) an active connection carries traffic before handoff to a pre-warmed one. Only used when `pool_enabled = true`.
|
||||
|
||||
This is a resilience feature, not a stealth feature — it exists purely to make konduit more tolerant of flaky links, and has no effect on how konduit's traffic looks to a network observer.
|
||||
|
||||
Server-side, sticky DL-target routing keeps your active connection selected until it actually fails (detected via a write timeout), rather than rotating on a fixed timer. This needs no client-side configuration.
|
||||
@@ -51,7 +51,6 @@ Server-side connection logs are retained for a limited period for operational pu
|
||||
|
||||
- All traffic between client and server is encrypted using **X25519** key exchange and **ChaCha20-Poly1305** AEAD.
|
||||
- The pre-shared key (PSK) is stored in the local config file with permissions restricted to the current user.
|
||||
- Stealth mode wraps the tunnel in a protocol that is indistinguishable from HTTPS, preventing deep-packet inspection from identifying Konduit traffic.
|
||||
|
||||
## Children
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@ echo "your secret mantra phrase here" | ./konduit-ctl bootstrap -l vpn.example.c
|
||||
echo "your secret mantra phrase here" | ./konduit-ctl bootstrap -l vpn.example.com:8443 --public-port 443 -p -
|
||||
```
|
||||
|
||||
`--public-port` sets the port written into client configs, so they connect to 443 even though konduit listens on 8443. See [stealth-setup.md](stealth-setup.md) for the full HAProxy configuration.
|
||||
`--public-port` sets the port written into client configs, so they connect to 443 even though konduit listens on 8443 — useful when running behind any TCP-passthrough reverse proxy (e.g. HAProxy, nginx `stream` module).
|
||||
|
||||
## 3. Add a Client
|
||||
|
||||
@@ -102,8 +102,8 @@ sudo apt install iptables-persistent && sudo netfilter-persistent save
|
||||
## 7. Verify
|
||||
|
||||
```bash
|
||||
# Should return your website (camouflage) not an error
|
||||
curl -sk https://your-server/
|
||||
# Connect a client and confirm the tunnel comes up
|
||||
./konduit --config client.toml
|
||||
|
||||
# Check konduit logs
|
||||
journalctl -u konduit-server -f
|
||||
|
||||
50
docs/socks-modes.md
Normal file
50
docs/socks-modes.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# SOCKS5 Modes
|
||||
|
||||
Konduit is a VPN for reaching your own resources over the public internet — it is not a censorship-circumvention tool, and it doesn't try to disguise its traffic. If you need to get through a network that's actively blocking or fingerprinting VPN traffic, that's a job for a dedicated, purpose-built tool — an SSH SOCKS proxy (`ssh -D`), Xray, sing-box, or similar — not something konduit reimplements.
|
||||
|
||||
What konduit does provide is standard SOCKS5 support on both sides of the connection, so you can chain it with whichever of those tools you already trust.
|
||||
|
||||
## Egress-dial: reaching the server through a proxy (`use_proxy`)
|
||||
|
||||
If you already have a SOCKS5 proxy that gets you out of a restrictive network (for example `ssh -D 1080 jumphost`), point konduit at it instead of dialing the server directly:
|
||||
|
||||
```toml
|
||||
[client]
|
||||
server_endpoint = "vpn.example.com:443"
|
||||
use_proxy = "socks5://127.0.0.1:1080"
|
||||
```
|
||||
|
||||
Or via the CLI:
|
||||
|
||||
```bash
|
||||
./konduit connect --config client.toml --use-proxy socks5://127.0.0.1:1080
|
||||
```
|
||||
|
||||
Konduit dials the SOCKS5 proxy, asks it to `CONNECT` to your server, and then runs its normal protocol over that connection — the proxy is otherwise transparent to it. If the proxy is unreachable, or requires authentication konduit doesn't support, the connection attempt fails immediately; there is no silent fallback to a direct connection.
|
||||
|
||||
## Listener: exposing a SOCKS5 proxy after the tunnel is up (`listen_socks`)
|
||||
|
||||
Once connected, konduit can also expose a local SOCKS5 listener so other tools (browsers, curl, Xray outbounds) can route traffic through the tunnel without needing their own TUN-level integration:
|
||||
|
||||
```toml
|
||||
[client]
|
||||
listen_socks = "127.0.0.1:1080"
|
||||
```
|
||||
|
||||
Or via the CLI:
|
||||
|
||||
```bash
|
||||
./konduit connect --config client.toml --listen-socks 127.0.0.1:1080
|
||||
```
|
||||
|
||||
Connections accepted by the listener are plain outbound TCP connections, routed through the tunnel by the kernel's routing table — the same routes any other tunnelled traffic uses. The SOCKS code itself has no VPN-specific logic.
|
||||
|
||||
Notes:
|
||||
|
||||
- SOCKS5 only, `CONNECT` command only — no `BIND`, no `UDP ASSOCIATE`.
|
||||
- No authentication — bind it to localhost (the default) unless you understand the exposure of doing otherwise.
|
||||
- If no address is given, konduit falls back to `127.0.0.1:1080`. Override the fallback itself with the `KONDUIT_SOCKS_LISTEN_ADDR` environment variable.
|
||||
|
||||
## Using both together
|
||||
|
||||
`use_proxy` and `listen_socks` are independent and can be combined — for example, dial out through an SSH SOCKS proxy to reach your server, and also expose a local SOCKS5 listener once connected for other apps to use.
|
||||
@@ -1,102 +0,0 @@
|
||||
# Stealth Mode Setup
|
||||
|
||||
Stealth mode makes VPN traffic look like normal HTTPS to deep packet inspection systems.
|
||||
The client opens a real TLS 1.3 connection, performs a WebSocket upgrade, and then carries
|
||||
the konduit protocol inside WebSocket binary frames — identical in appearance to any
|
||||
browser-based web app.
|
||||
|
||||
```
|
||||
Client ──TLS 1.3──▶ HAProxy :443 (TCP passthrough) ──▶ Konduit :8443
|
||||
HTTP/1.1 GET /ws → 101 Switching Protocols
|
||||
WebSocket binary frames (konduit protocol inside)
|
||||
```
|
||||
|
||||
## Server Requirements
|
||||
|
||||
- A domain with a valid TLS certificate (Let's Encrypt / certbot)
|
||||
- HAProxy 2.4+
|
||||
- Konduit server on a non-public port (e.g. `8443`)
|
||||
|
||||
## HAProxy Configuration
|
||||
|
||||
HAProxy acts as a pure TCP proxy — it passes TLS through to the konduit server unchanged.
|
||||
|
||||
```haproxy
|
||||
frontend https-ingress
|
||||
bind *:443
|
||||
mode tcp
|
||||
default_backend konduit-vpn
|
||||
|
||||
backend konduit-vpn
|
||||
mode tcp
|
||||
timeout tunnel 0
|
||||
server konduit 127.0.0.1:8443
|
||||
```
|
||||
|
||||
`timeout tunnel 0` prevents HAProxy from dropping idle connections.
|
||||
|
||||
Reload after changes:
|
||||
|
||||
```bash
|
||||
haproxy -c -f /etc/haproxy/haproxy.cfg # validate first
|
||||
systemctl reload haproxy
|
||||
```
|
||||
|
||||
## Konduit Server (`server.toml`)
|
||||
|
||||
```toml
|
||||
[server]
|
||||
listen_addr = "0.0.0.0"
|
||||
listen_port = 8443
|
||||
public_addr = "your-domain.com"
|
||||
public_port = 443
|
||||
tls_cert = "/etc/letsencrypt/live/your-domain.com/fullchain.pem"
|
||||
tls_key = "/etc/letsencrypt/live/your-domain.com/privkey.pem"
|
||||
websocket = true
|
||||
```
|
||||
|
||||
## Client Configuration (`client.toml`)
|
||||
|
||||
```toml
|
||||
[client]
|
||||
server_endpoint = "your-domain.com:443"
|
||||
peer_id = "..."
|
||||
identity_key = "..."
|
||||
server_public_key = "..."
|
||||
|
||||
[stealth]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
That's it — `stealth = true` activates TLS and WebSocket camouflage automatically.
|
||||
|
||||
## Flutter / Mobile App
|
||||
|
||||
Enable **Stealth Mode** in the app settings. The toggle maps to `[stealth] enabled = true`
|
||||
in the connection config and activates TLS + WebSocket camouflage on all platforms
|
||||
(Linux, Android, Windows).
|
||||
|
||||
For QR-code-based provisioning, the `t: true` field in the QR payload enables stealth.
|
||||
|
||||
## Verify
|
||||
|
||||
```bash
|
||||
# TLS cert must be valid — browser must reach your site
|
||||
curl -s https://your-domain.com/ | head -5
|
||||
|
||||
# Connect the VPN client
|
||||
sudo ./konduit --config client.toml
|
||||
|
||||
# Watch HAProxy — you should see the tunnel established
|
||||
journalctl -u haproxy -f
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
| Mistake | Effect | Fix |
|
||||
|---------|--------|-----|
|
||||
| HAProxy terminating TLS (`bind *:443 ssl crt ...`) | konduit receives plain TCP, WebSocket handshake fails | Use `bind *:443` (no `ssl`) — TCP passthrough |
|
||||
| Missing `timeout tunnel 0` | Connection drops after 30 s of silence | Add `timeout tunnel 0` to backend |
|
||||
| Port 8443 exposed to internet | Bypass HAProxy entirely | Firewall port 8443 to localhost only |
|
||||
| Expired/self-signed cert | TLS error on client | Use Let's Encrypt; renew via certbot |
|
||||
| `stealth = false` on client | Plain TCP connection, DPI detects VPN | Set `[stealth] enabled = true` |
|
||||
Reference in New Issue
Block a user