GHOSTWIRE/README.md

GHOSTWIRE

A small WireGuard server manager: one Go binary with a web interface and a JSON API (also meant for a future iOS app). It configures the WireGuard server, manages peers (add, change, disable, remove) and records traffic per peer.

• State: everything lives in config.json. The kernel is reconciled to it, so there is no /etc/wireguard, no wg-quick and no wireguard-tools.
• Kernel access: netlink creates wg0 and sets its addresses and MTU; wgctrl sets keys and peers; nftables holds the rules in its own inet GHOSTWIRE table.
• Live peer changes: only peers that changed are touched, the same effect as wg syncconf, so connected peers stay connected.
• Logs: written to GHOSTWIRE.jsonl, rotated at 10 MB with 5 old files kept by default (Settings → Data retention).
• Traffic history: kept in stats.json: hourly for 48 h and daily for 400 days by default (Settings → Data retention).
• Client private keys are never stored. A config is shown once, as a download or QR code. "Issue new config" makes new keys.

Requirements

• Linux with kernel 5.6 or newer (WireGuard built in), nftables and systemd
• Ports: UDP 51820 (WireGuard), TCP 443 (web), TCP 80 (optional, Let's Encrypt http-01 and redirect)

Build

make linux-amd64      # dist/amd64/GHOSTWIRE
make linux-arm64      # dist/arm64/GHOSTWIRE (Raspberry Pi 64-bit, ARM servers)
make linux-arm        # dist/armv7/GHOSTWIRE (Raspberry Pi OS 32-bit)
make test

Install

The binary installs itself. Copy it to the server and run it as root:

scp dist/amd64/GHOSTWIRE server:/tmp/
ssh server
sudo /tmp/GHOSTWIRE install -domain vpn.example.net -email you@example.net

-domain turns on Let's Encrypt and is also used as the WireGuard endpoint. Without it, the web interface uses a self-signed certificate; set the endpoint later in the web interface or with -endpoint.

install:

1. creates the system user ghostwire and /opt/ghostwire
2. copies itself to /opt/ghostwire/GHOSTWIRE
3. creates config.json with defaults, if missing
4. writes /etc/sysctl.d/99-ghostwire.conf (IP forwarding) and /etc/modules-load.d/ghostwire.conf, and loads the kernel module
5. writes /etc/systemd/system/ghostwire.service
6. asks for the admin password (first install only)
7. enables and starts the service, and checks that it stays up

Running it again is safe: steps that are already done are skipped.

The service runs as user ghostwire with only CAP_NET_ADMIN and CAP_NET_BIND_SERVICE, and can write only to /opt/ghostwire. Root is needed only for the commands below, never for the running service.

Commands (as root)

Command	What it does
GHOSTWIRE install [-domain d] [-email e] [-endpoint h]	Sets up and starts the service, as above.
GHOSTWIRE update [-force]	Run from the new binary, e.g. sudo /tmp/GHOSTWIRE update. Checks that it can read the current config.json (nothing changes if not), backs up the config to config.json.bak-<old version>, replaces the binary, updates the unit if needed and restarts. If the new version does not stay up, the old binary is put back and restarted. It refuses older versions without -force.
GHOSTWIRE uninstall [-purge] [-y]	Stops and removes the service, wg0 and the firewall table. -purge also deletes /opt/ghostwire and the user.
GHOSTWIRE passwd	Sets the admin password and reloads the running service.
GHOSTWIRE version	Prints the version.

Updating restarts only the management service. VPN connections stay up, because wg0 lives in the kernel.

config.json

A minimal file is enough. Missing values are filled with defaults on first start: server key, a random free /24 subnet, port 51820, MTU 1420, Quad9 DNS, full tunnel.

{
  "web": {
    "listen": ":443",
    "httpListen": ":80",
    "tls": { "mode": "acme", "domain": "vpn.example.net", "email": "admin@example.net" }
  },
  "server": { "endpoint": "vpn.example.net" }
}

web.tls.mode can be:

Mode	What it does
acme	Let's Encrypt, automatic. Uses tls-alpn-01 on :443, or http-01 when httpListen is set. Certificates are cached in /opt/ghostwire/acme. "staging": true uses the test CA.
selfsigned	Generates a certificate in /opt/ghostwire/tls. The iOS app pins its fingerprint.
files	Uses certFile and keyFile, and reloads them when they change.
off	Plain HTTP, for running behind a reverse proxy on localhost.

After editing config.json by hand, run sudo systemctl reload ghostwire.

Files in /opt/ghostwire

File	Content
GHOSTWIRE	the program
config.json	all settings, server key, peers, token hashes (0600)
stats.json	traffic history per peer
GHOSTWIRE.jsonl	log, one JSON object per line. Changes carry "audit":true
acme/, tls/	certificates

API

Base path /api/v1. The web interface signs in with a session cookie. Apps and scripts use Authorization: Bearer <token>; create the token under Settings → Pair iOS app. A read-only token may only use GET. Full-access tokens can do everything the web interface does except the admin-only endpoints: password, API tokens, backup and restore, and changing the admin username.

POST   /auth/login · /auth/logout        GET /auth/me        POST /auth/password (admin)
GET    /status                           GET /stats?range=24h|7d|30d|90d
GET    /server         PATCH /server     POST /server/rotate-key     GET /server/detect-ip
GET    /peers          POST /peers       (returns the config and QR once)
GET    /peers/{id}     PATCH /peers/{id} DELETE /peers/{id}
POST   /peers/{id}/enable | /disable | /issue-config
GET    /peers/{id}/stats?range=…
GET    /settings       PATCH /settings   POST /restart
GET    /logs?level=&limit=&audit=1       GET /logs/download
admin: GET|POST /tokens · DELETE /tokens/{id} · GET /backup · POST /restore

Traffic is reported from the peer's point of view: down is what the peer downloaded, up is what it uploaded.

Firewall note

GHOSTWIRE's rules sit in their own nftables table. An accept there cannot override a drop in another table, so if ufw or firewalld is active, allow UDP 51820 (and TCP 443/80) in that firewall too.

iOS app

ios/ holds the native iPhone app (SwiftUI, iOS 17+). It does everything the web interface does except password, API tokens and backups. Pair it in the web interface under Settings → Pair iOS app: scan the QR code, or tap "Copy pairing code" and paste it into the app's "Enter manually". Self-signed certificates are pinned during pairing.

• Open ios/GHOSTWIRE.xcodeproj in Xcode to build and run.
• TEAM_ID=<your team> ios/release.sh archives and uploads a build to App Store Connect.
• ios/AppStore/ has the store listing text, privacy details, review notes and 6.9-inch screenshots.

Development

On macOS (or any non-Linux system), make dev starts the app on http://127.0.0.1:8080 with a traffic simulator in place of the kernel. Set a password first:

make build && mkdir -p dev && ./GHOSTWIRE -config dev/config.json -passwd