# Konduit Server Quickstart

## 1. Prerequisites

### IP Forwarding

```bash
sudo sysctl -w net.ipv4.ip_forward=1
# Persist: add 'net.ipv4.ip_forward=1' to /etc/sysctl.conf
```

### Capabilities

Konduit needs permission to create TUN devices and bind privileged ports without running as root.

```bash
sudo setcap cap_net_admin,cap_net_bind_service=+ep ./konduit-server
sudo setcap cap_net_admin=+ep ./konduit
```

## 2. Bootstrap

Konduit derives its identity key from a **mantra** (secret phrase) using Argon2id. Keep the mantra safe — it lets you recover the same identity if the config file is lost.

**Standard (konduit binds on 443):**

```bash
echo "your secret mantra phrase here" | ./konduit-ctl bootstrap -l vpn.example.com:443 -p -
```

**Behind a reverse proxy (HAProxy on 443, konduit on 8443):**

```bash
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.

## 3. Add a Client

```bash
./konduit-ctl add-client my-laptop
```

Creates `my-laptop.client.toml` and appends the peer to `server.toml`. Transfer the `.client.toml` to the client device, or scan the QR payload with the mobile app.

## 4. TUN Interface Name

Set a fixed TUN interface name so firewall rules are stable:

```toml
# server.toml
[network]
tun_name = "konduit0"
```

Without this, konduit picks the first available `tunN`, which shifts if other VPN interfaces exist.

## 5. Run

```bash
./konduit-server --config server.toml
```

For persistent operation, use the provided systemd units in [docs/systemd/](systemd/). Copy `konduit-server.service` to `/etc/systemd/system/`, then:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now konduit-server
```

## 6. NAT / Masquerade

VPN clients send packets with source IP `10.10.0.x`. Masquerade rewrites this to the server's public IP so internet hosts can reply.

### firewalld (RHEL, Fedora, recent Ubuntu)

```bash
# Trust the VPN interface
sudo firewall-cmd --zone=trusted --add-interface=konduit0 --permanent

# Enable masquerade on the public zone
sudo firewall-cmd --zone=public --add-masquerade --permanent

sudo firewall-cmd --reload
```

> **Important:** `iptables` commands are silently ignored on firewalld systems. Always use `firewall-cmd`.

### iptables (Debian/Ubuntu without firewalld)

```bash
IFACE=$(ip route get 1.1.1.1 | awk '{print $5; exit}')
sudo iptables -t nat -I POSTROUTING 1 -s 10.10.0.0/24 -o $IFACE -j MASQUERADE
sudo iptables -I FORWARD 1 -i konduit0 -o $IFACE -j ACCEPT
sudo iptables -I FORWARD 2 -i $IFACE -o konduit0 -m state --state RELATED,ESTABLISHED -j ACCEPT

# Persist
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/

# Check konduit logs
journalctl -u konduit-server -f
```