c61664ca70
Audit of the public repo against the actual server and konduit-ctl source. The happy path was documented; the failure modes were not. - server.toml had no reference at all. Add docs/server-config.md covering every key, [tls], the control API, and key handling. - The mantra could not recover the identity key on its own: derive_from_passphrase needs the [kdf] salt, which is 32 random bytes generated once at bootstrap. bootstrap says so in the file it generates (core/src/config.rs:403); the quickstart claimed the opposite. Fixed, with a backup step added before it is needed rather than after. - konduit-server never appeared in a download step, yet konduit-server.service expects /opt/konduit/konduit-server - a path no instruction created. Added the install section and moved setcap after the copy, since capabilities do not survive every cross-filesystem copy and a binary that silently lost cap_net_bind_service fails at bind time. - Hot config reload was a headline feature with no documented mechanism. It is a control API on 127.0.0.1:3001, and add-client only edits the file on disk, so a new peer is not live until something reloads it. Documented, including that /reload does not disconnect revoked peers but /sync does. - [tls] native termination was entirely undocumented; the key must be PKCS#8. - Dropped a README claim about a konduit-admin-ui unit that does not exist, and fixed a systemd copy path that only resolved if this repo had been cloned to /opt/konduit. #k-ops/#1/#211
175 lines
7.2 KiB
Markdown
175 lines
7.2 KiB
Markdown
<div align="center">
|
|
|
|
<img src="logo-horizontal.svg" alt="Konduit" height="52"/>
|
|
|
|
<br/><br/>
|
|
|
|
**TCP-Native VPN. Works Where UDP Doesn't.**
|
|
|
|
[](LICENSE)
|
|
[]()
|
|
[]()
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
Konduit is a modern VPN built around a single principle: **TCP transport that works when UDP is blocked.**
|
|
|
|
WireGuard is excellent — until your ISP throttles or blocks UDP. Konduit solves that without the complexity of OpenVPN or the fragility of UDP-wrapping hacks. It runs fully in userspace, requires no elevated privileges, and gets out of your way.
|
|
|
|
## Why Konduit?
|
|
|
|
Most VPNs treat TCP as a fallback. Konduit is designed for TCP from the ground up, which means:
|
|
|
|
- No HEAD-OF-LINE blocking from tunneling UDP into TCP
|
|
- Reliable behaviour on restrictive corporate and mobile networks
|
|
- WireGuard-level simplicity without the UDP dependency
|
|
|
|
## Features
|
|
|
|
- **TCP-native protocol** — designed for TCP, not retrofitted
|
|
- **Server-controlled routing** — administrators enforce routing policy; clients cannot bypass it
|
|
- **Userspace implementation** — no kernel modules, no root required
|
|
- **Hot config reload** — update server configuration without dropping connections
|
|
- **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
|
|
- **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
|
|
|
|
Releases are published on the [Releases](../../releases) page. Each release includes:
|
|
|
|
| Artifact | Platform | Purpose |
|
|
|---|---|---|
|
|
| `konduit-server-*-linux-x86_64` | Linux | VPN server |
|
|
| `konduit-*-linux-x86_64` | Linux | CLI client |
|
|
| `konduit-ctl-*-linux-x86_64` | Linux | Server provisioning tool |
|
|
| `Konduit-*-x86_64.AppImage` | Linux | GUI client (AppImage) |
|
|
| `konduit-gui-*-windows-x86_64-portable.zip` | Windows | GUI client |
|
|
| `konduit-cli-*-windows-x86_64.zip` | Windows | CLI client + wintun.dll — **not in every release** |
|
|
| `konduit-*-android.aab` | Android | Android app for bundletool sideload — **not in every release** |
|
|
|
|
Which Windows and Android assets are attached varies between releases: v0.1.0-beta.9
|
|
and v0.1.0-beta.10 carried both, v0.1.0-beta.11 shipped the Windows GUI zip only (as
|
|
`-portable.zip`). **The [Releases](../../releases) page is authoritative** — check it
|
|
rather than assuming a row is present. Android is on Google Play either way.
|
|
|
|
### Linux (CLI)
|
|
|
|
```bash
|
|
# Download konduit-server, konduit-ctl and konduit from the Releases page, then:
|
|
chmod +x konduit-server konduit-ctl konduit
|
|
|
|
# Bootstrap a server (run from the directory that will hold server.toml)
|
|
echo "your secret mantra" | ./konduit-ctl bootstrap -l vpn.example.com:443 -p -
|
|
|
|
# Add a client, and reload the server so it picks the peer up
|
|
./konduit-ctl add-client my-laptop --reload
|
|
|
|
# Connect a client
|
|
./konduit --config my-laptop.client.toml
|
|
```
|
|
|
|
Running a server end to end — install, capabilities, NAT, systemd — is covered
|
|
in the [Server Quickstart](docs/server-quickstart.md).
|
|
|
|
`--config`/`-c` is a top-level flag, not a `connect` flag. The `connect`
|
|
subcommand takes the peer details individually instead:
|
|
|
|
```bash
|
|
./konduit connect --server vpn.example.com:443 \
|
|
--peer-id <peer-id> --identity <key-hex> --server-pub <server-pub-hex>
|
|
```
|
|
|
|
### Linux (GUI)
|
|
|
|
Download the `.AppImage`, make it executable, and run it:
|
|
|
|
```bash
|
|
chmod +x Konduit-*-x86_64.AppImage
|
|
./Konduit-*-x86_64.AppImage
|
|
```
|
|
|
|
### Windows
|
|
|
|
Extract the zip and run `konduit.exe` (CLI) or `Konduit.exe` (GUI). `wintun.dll` must remain alongside the executable.
|
|
|
|
### Android
|
|
|
|
Download from [Google Play](https://play.google.com/store/apps/details?id=eu.k_ops.konduit) or sideload the `.aab` using [bundletool](https://github.com/google/bundletool).
|
|
|
|
### macOS · iOS
|
|
|
|
Coming soon.
|
|
|
|
## Setup
|
|
|
|
**GUI clients**
|
|
- [Linux GUI Quickstart](docs/gui-quickstart-linux.md) — AppImage, privileges, autostart
|
|
- [Windows GUI Quickstart](docs/gui-quickstart-windows.md) — extract, UAC, WinTun, autostart
|
|
|
|
**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
|
|
- [Server Configuration](docs/server-config.md) — every `server.toml` key, the control API, and how the server identity key is protected
|
|
- [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 and konduit (client)
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Flutter UI (Dart)
|
|
│
|
|
flutter_rust_bridge (FFI)
|
|
│
|
|
Konduit engine (Rust)
|
|
├── TUN device (userspace)
|
|
├── TCP tunnel protocol
|
|
├── Key exchange (X25519)
|
|
└── Route manager
|
|
```
|
|
|
|
| Layer | Technology |
|
|
|---|---|
|
|
| UI | Flutter / Dart |
|
|
| Core engine | Rust (Tokio async) |
|
|
| FFI bridge | flutter_rust_bridge |
|
|
| Cryptography | ring / rustls |
|
|
| TUN device | tun crate (userspace) |
|
|
|
|
## Openness Model
|
|
|
|
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 and management UI are proprietary. Source review under NDA is available for enterprise partners.
|
|
|
|
## Security
|
|
|
|
**No UDP dependency:** Konduit does not require UDP at any layer.
|
|
|
|
**Key handling:** Your private identity key is generated locally by `konduit-ctl` and written into the client configuration file you pass with `--config` — it is never transmitted to K-Ops, and K-Ops operates no server. **That file is the secret.** Treat it like a private key file: readable only by its owner, and the only thing standing between an attacker and a tunnel into your VPN is its permissions. Do not commit it or paste it into a bug report.
|
|
|
|
## Support
|
|
|
|
**Bug reports:** file an issue on [Gitea Issues](https://git.k-ops.eu/konduit/konduit-public/issues).
|
|
|
|
**Vulnerabilities:** report directly to konduit@k-ops.eu.
|
|
|
|
**Contributing:** Core development is handled internally. We do not currently accept external pull requests.
|
|
|
|
---
|
|
|
|
## About
|
|
|
|
Created by **Eugen Kaparulin**.
|
|
Official binaries distributed by **[K-Ops Oy](https://k-ops.eu)**.
|
|
|
|
© Eugen Kaparulin. All rights reserved.
|
|
[`konduit-platform`](./konduit-platform) is published under the [PolyForm Noncommercial License 1.0.0](LICENSE).
|
|
All other parts of Konduit are proprietary.
|
|
[Privacy Policy](docs/privacy-policy.md)
|