wiretastix

WireGuard Integration

How Wiretastix operates as a WireGuard VPN concentrator, managing interfaces and peers.

Wiretastix is built around the WireGuard VPN protocol, providing a management layer that simplifies its deployment and operation. This section explains the core concepts of how Wiretastix interacts with WireGuard.

Crucially, Wiretastix integrates deeply with OpenID Connect (OIDC) Identity Providers. This integration allows for dynamic management of WireGuard peers, where user authentication, self-provisioning of tunnels, and access rule enforcement are all driven by your OIDC IdP. This means that the lifecycle of a WireGuard peer, from creation to deletion, can be automatically tied to a user’s identity and group memberships within your OIDC system.

WireGuard Interface Management

Architecturally, Wiretastix is a WireGuard VPN concentrator: a single server that every peer connects to, rather than a mesh where peers connect directly to each other. Wiretastix manages one WireGuard network interface (e.g., wg0) on the daemon host, configured with a private key, a public key, and an IP address (both IPv4 and IPv6, if configured). If you’re coming from a traditional OpenVPN concentrator setup, this hub-and-spoke model will be familiar – Wiretastix brings that same operational shape to WireGuard, with a web-based admin panel and OIDC/SSO-driven self-service on top. See Migrating from OpenVPN to WireGuard for how the pieces map over.

When the Wiretastix daemon starts, it initializes this WireGuard interface based on the settings in its wiretastix.yaml configuration file. It handles the creation and deletion of the interface, as well as assigning its IP addresses.

Peer Management

The primary function of Wiretastix is to manage WireGuard peers. Each peer represents a client device that connects to the Wiretastix VPN server. Wiretastix automates several aspects of peer management:

  • Key Generation: Automatically generates public and private keys for each new peer, along with an optional preshared key for enhanced security.
  • IP Address Assignment: Assigns unique IPv4 and IPv6 addresses to each peer from the configured WireGuard subnets, ensuring no IP conflicts.
  • Configuration Generation: Provides a ready-to-use WireGuard client configuration file for each peer, simplifying client setup.
  • Dynamic Updates: Adds or removes peers from the WireGuard interface dynamically as they are created, updated, or deleted in the Wiretastix database.
  • Status Monitoring: Collects real-time statistics (e.g., latest handshake, data transfer) for active peers.

Peer Synchronization

Wiretastix maintains a synchronized state between its internal database and the active WireGuard interface. When a peer is created, updated, or deleted through the Wiretastix API or CLI, the daemon ensures that the corresponding changes are applied to the WireGuard interface. This synchronization process ensures that the WireGuard VPN operates according to the configurations defined in Wiretastix.

Keepalive Mechanism

Wiretastix configures a PersistentKeepalive interval for each peer. This setting ensures that NAT mappings are kept alive on the client side, allowing traffic to flow even if the client is behind a restrictive NAT. The default keepalive interval can be configured globally or overridden for specific groups or peers.

Security by Design

Wiretastix’s WireGuard integration follows the same defense-in-depth philosophy used throughout the rest of the system:

  • Native kernel integration, no shell-outs: The daemon manages the WireGuard interface directly via wgctrl and netlink – the same underlying mechanisms wg/wg-quick themselves use. It never constructs and executes wg/wg-quick shell commands, removing an entire class of command-injection risk from interface and peer management.
  • Least privilege at runtime: The daemon runs as an unprivileged system account with exactly one Linux capability – CAP_NET_ADMIN – granted via ambient capabilities rather than running as root or relying on setuid binaries. Combined with NoNewPrivileges and systemd sandboxing (ProtectSystem=strict, restricted namespaces, and more), a compromise of the daemon process doesn’t hand over the host.
  • Private keys are never persisted server-side: When Wiretastix generates a peer’s keypair, only the public key (and optional preshared key) are stored in the database – there is no private-key column at all. The private key is delivered to the user once, via the QR code or config download, and isn’t retained; a compromised database does not expose peer private keys.
  • Identity-bound peer lifecycle: Because peer provisioning is driven by your OIDC Identity Provider, network access is tied directly to identity and group membership rather than to standing credentials that can outlive a user’s authorization.
  • Optional preshared keys: Each peer can carry a preshared key layered on top of WireGuard’s own Noise-protocol handshake, adding a symmetric-key layer that must also be compromised to break confidentiality.

This mirrors the authentication, network, and data-security layers described in Security Best Practices, applied specifically to how the daemon manages WireGuard itself.