A WireGuard tunnel, built again in Rust.

Bring a tunnel up

Do these in order. The commands are the ones in the repository README and the Homebrew tap.

1. Install both binaries

   Tap dickwu/tap, then install ironguard. The formula puts ironguard and ironguard-tui on your PATH.

   brew tap dickwu/tap Copy

   brew install ironguard Copy

2. Make a key pair

   genkey prints a private key. pubkey reads a private key on stdin and prints the public key. genpsk prints a pre-shared key.

   ironguard genkey > private.key Copy

   ironguard pubkey < private.key Copy

3. Write wg.json

   Point private_key_file at the key, set an address, and add peers. The file has to be JSON. Comments are not allowed. A full example is below. Validate it before you open a device.

   ironguard validate wg.json Copy

4. Bring the interface up

   This is the command from the tap README. utun9 is the interface name in that example, and it has to be a key in your wg.json. On Linux the key is whatever you named the interface, such as wg0 in the TUI setup example. Creating the TUN device needs root. If you are not root, ironguard up re-runs itself with sudo. ironguard down utun9 stops that interface. ironguard status lists what the file configures.

   sudo ironguard up utun9 --config wg.json --foreground Copy

On the wire

Taken from the v0.3.2 sources, the repository README, and the Homebrew formula. The schema tables live in the README.

Frame

16-byte v2 header: type, flags, reserved, receiver id, counter. In the source the type byte starts at 0x04 for data, then 0x05 keepalive, 0x06 control, and 0x07 batch, so the header can share the wire with older handshake messages.

AEAD

AES-256-GCM through ring. The project README reports 2.5 to 3.6 times the speed of ChaCha20-Poly1305 on AES-NI hardware.

Keys

X25519 for key exchange. HKDF-SHA256 derives epoch keys. Private key material is zeroed on drop.

Routing

Crypto-key routing with longest-prefix match tables for IPv4 and IPv6. Anti-replay is an RFC 6479 window of 2048 bits. Each peer has five timers.

QUIC

A Cargo feature, compiled into the release binaries. The README says tunnel packets can ride inside QUIC on networks that block UDP: unreliable datagrams first, length-prefixed streams if datagrams are unavailable. quic.mode is handshake_only (the schema default) or full_transport. The handshake port is quic.port, or the listen port plus one. ironguard gen-quic-cert writes an mTLS certificate.

Pipeline

Tokio workers batch TUN and UDP I/O. A batch flushes on count, size, or timeout. The buffer pool has two tiers: 8192 buffers of 2 KB and 128 of 64 KB. Each peer has a reorder buffer.

Systems

macOS uses utun, sendmsg_x / recvmsg_x, and kernel buffer tuning. Linux uses a TUN device, sendmmsg / recvmmsg, and GSO/GRO. The formula publishes archives for macOS Apple Silicon, macOS Intel, Linux x86_64, and Linux ARM64.

NAT

The README’s connectivity crate does STUN binding requests, coordinated UDP hole punching, a birthday-paradox spray for symmetric NAT, UPnP port mapping, mDNS on the LAN, and a QUIC relay.

Config

wg.json holds interfaces, addresses, peers, DNS names in endpoints, masquerade, and post_up / post_down hooks. A peer can carry allowed IPs, a keepalive, a pre-shared key file, and an ACL of destination CIDRs. ironguard import and ironguard export convert standard WireGuard .conf files.

Post-quantum

The schema has post_quantum set to false, true, or strict, and a per-peer pq_public_key documented as an ML-KEM-768 public key. The Homebrew tap describes that cryptography as optional and feature-gated.

A wg.json file

The example from the repository README. The public key there is a placeholder. Secrets stay in private.key, not in the JSON.

{
  "$schema": "ironguard/v1",
  "interfaces": {
    "utun9": {
      "private_key_file": "./private.key",
      "listen_port": 51820,
      "address": ["10.0.0.1/24"],
      "mtu": 1420,
      "quic": {
        "port": 51821,
        "sni": "vpn.example.com"
      },
      "peers": [
        {
          "public_key": "abc123...",
          "endpoint": "vpn.example.com:51820",
          "allowed_ips": ["10.0.0.2/32"],
          "persistent_keepalive": 25
        }
      ]
    }
  }
}

Keys load from a file or an environment variable, hex or base64. More fields, including DNS, fwmark, and per-peer ACLs, are in the README. Sample files are in configs/.

Without Homebrew

The formula installs the v0.3.2 archives. You can fetch those same files, or build the workspace.

Questions

Something missing belongs in the issue tracker.