Configuration Reference

Detailed reference for the wiretastix.yaml configuration file.

Wiretastix is configured using a YAML file, typically named wiretastix.yaml. This file defines various aspects of the daemon’s operation, including database connections, WireGuard interface settings, API server bindings, and more. The default location for this file is /etc/wiretastix/wiretastix.yaml.

Below is a detailed reference of all available configuration options.

Top-Level Sections

webserver: Configuration for the optional web-based GUI.
apiserver: Configuration for the RESTful API server.
wireguard: Core WireGuard interface settings.
nftables: NFTables firewall integration settings.
oidc: OpenID Connect (OIDC) authentication settings.
db: Database connection settings.
resolver: Internal DNS resolver settings.
metrics: Prometheus metrics exposure settings.

`webserver`

Configuration for the optional web-based GUI.

webserver:
    # If there is at least one host, the value will be used to automatically
    # request a TLS certificate from letsencryot
    acme-host:
    #  - wiretastix.local
    binding: :8085
    # The base url of the wiretastix endpoint.
    base: /
    # where the HTML templates and assets are stored
    html-assets: /usr/lib/wiretastix/html
    html-templates: /usr/lib/wiretastix/templates
    # If set to true, wiretastix will generate a self signed certificate and the web ui will be served
    # through those certificates. The certificates will change et every restart so this feature
    # should be used with care, mainly as a secure transport between a frontend proxy and wiretastix itself.
    auto-cert: true
    # Where wiretastix will store the certificates generated through ACME (letsencrypt)
    cert-dir: /etc/wiretastix/certs/

Parameter	Type	Description	Default
`acme-host`	`[]string`	List of hostnames for ACME (Let’s Encrypt) certificate generation. Requires `cert-dir` to also be set – if `acme-host` is set but `cert-dir` is empty, Wiretastix refuses to enable ACME at all (logs a warning and serves without it) rather than picking an implicit certificate directory.	`[]`
`binding`	`string`	The address and port the web server listens on (e.g., `:8085`).	`:8085`
`base`	`string`	The base URL path for the web interface (e.g., `/`).	`/`
`html-assets`	`string`	Path to the directory containing static HTML assets.	`(internal)`
`html-templates`	`string`	Path to the directory containing HTML templates.	`(internal)`
`auto-cert`	`bool`	If true, Wiretastix generates a self-signed certificate for the web UI. Certificates change on restart, suitable for secure transport behind a proxy.	`false`
`cert-dir`	`string`	Directory to store the ACME account key and issued TLS certificates (Let’s Encrypt). Must be set explicitly for ACME to work – there is no implicit fallback path (a fixed, predictable temp directory was removed as a security fix: a shared host’s other users could pre-create it before Wiretastix ever started).	(none – ACME is disabled if unset while `acme-host` is set)

`apiserver`

The apiserver provides the endpoints to interact with the Wiretastix settings and configure all the parameters.

apiserver:
    binding: 127.0.0.1:8095
    base: /wiretastix/api/v1/

Parameter	Type	Description	Default
`binding`	`string`	The address and port the API server listens on (e.g., `127.0.0.1:8095`).	`127.0.0.1:8095`
`base`	`string`	The base URL path for the API (e.g., `/wiretastix/api/v1/`).	`/wiretastix/api/v1/`

`wireguard`

This stanza sets up the WireGuard interface that will be owned by Wiretastix. The interface needs to be configured without any IP address. Wiretastix will set it up appropriately when it starts.

wireguard:
    # The interface name
    ifname: wg0
    # the port for the wireguard packets
    port: 51820
    # The private key for the web interface.
    pvtkey: setAproperKey # wg genkey
    # marking the tunnel packets may be useful for nftables rules and routing
    fwmark: 0xbeef
    # this is the ipv4 address of the wireguard interface and the gateway for vpn peers. Leave empty to disable.
    ipv4: 10.100.200.1/24
    # this is the ipv6 address of the wireguard interface and the gateway for vpn peers. Leave empty to disable.
    ipv6: fd41:34e9:dead:beef::abcd/64

Parameter	Type	Description	Default
`ifname`	`string`	The name of the WireGuard interface (e.g., `wg0`).	`wg0`
`port`	`int`	The UDP listening port for the WireGuard interface.	`51820`
`pvtkey`	`string`	The private key for the WireGuard interface. Generate with `wg genkey`.	`(generated)`
`fwmark`	`int`	Firewall mark for WireGuard traffic. May be useful for `nftables` rules and routing.	`0`
`ipv4`	`string`	The IPv4 address of the WireGuard interface and the gateway for VPN peers. Leave empty to disable.	`(none)`
`ipv6`	`string`	The IPv6 address of the WireGuard interface and the gateway for VPN peers. Leave empty to disable.	`(none)`

`nftables`

Wiretastix automatically creates and updates nftables rules for all the peers. This is the nftables table name where Wiretastix will be able to handle the rules.

nftables:
    table: wiretastix

Parameter	Type	Description	Default
`table`	`string`	The name of the `nftables` table used by Wiretastix.	`wiretastix`

`oidc`

OpenID Connect (OIDC) authentication settings.

oidc:
    name: Authentik
    client-id: fill-me
    client-secret: fill-me-again
    redirect-url: https://set.it/callback
    config-issuer: https://your-oauth-idp/.well-known/openid-configuration
    # .well-known/openid-configuration
    cookie-secret: set-to-a-random-string
    force-approval: true
    verbose: true
    refresh-min-interval-sec: 300
    scopes:
        - openid
        - email
        - profile
        #- offline_access
    constraints:
        groups:
            - vpn
            - whatever
        email:
            - my@email.address.example.com

Parameter	Type	Description	Default
`name`	`string`	The name of the OIDC provider.	`(none)`
`client-id`	`string`	The OIDC client ID.	`(none)`
`client-secret`	`string`	The OIDC client secret.	`(none)`
`redirect-url`	`string`	The URL where the OIDC provider redirects after authentication.	`(none)`
`config-issuer`	`string`	The OIDC issuer URL.	`(none)`
`verbose`	`bool`	Enable verbose logging for OIDC operations.	`false`
`cookie-secret`	`string`	Secret key for OIDC session cookies.	`(generated)`
`force-approval`	`bool`	Force user approval for OIDC scopes.	`false`
`refresh-min-interval-sec`	`int`	Minimum interval in seconds to refresh OIDC tokens.	`30`
`scopes`	`[]string`	List of OIDC scopes to request.	`[]`
`constraints`	`map[string][]string`	Defines rules based on OIDC claims (e.g., group memberships) to authorize users for Wiretastix access.	`{}`

`db`

The database settings. Wiretastix supports only two different backends: sqlite and postgres.

db:
    type: postgres
    dsn: postgresql://wiretastix:changeme@127.0.0.1:5432/wiretastix?client_encoding=UTF8&application_name=DblEngine&sslmode=require
    #type: sqlite
    #dsn:  file:/var/lib/wiretastix/wiretastix.db?cache=shared

Parameter	Type	Description	Default
`type`	`string`	The type of database to use (`sqlite` or `postgres`).	`sqlite`
`dsn`	`string`	The Data Source Name (DSN) for the database connection.	`(varies)`

`resolver`

Internal DNS resolver settings. See DNS Authoritative Server for how the resolver behaves and DNS Server Configuration for setup and access control.

resolver:
    enabled: false
    binding: 127.0.0.1:5353
    concurrency: 5
    domain: vpn.local
    acls: []

Parameter	Type	Description	Default
`enabled`	`bool`	Turns the resolver on. Off by default – anyone who can reach it can enumerate every peer’s nickname and VPN IP via PTR queries, so it stays disabled unless you actually use the DNS integration.	`false`
`binding`	`string`	The address and port the DNS resolver listens on (e.g., `127.0.0.1:5353`). Only checked when `enabled` is `true`: if `binding` is empty, malformed, or missing a port, Wiretastix logs a warning and forces it to `127.0.0.1:5353` (loopback-only) rather than falling through to Go’s own default of binding all interfaces on a random port.	(forced to `127.0.0.1:5353` if invalid and `enabled` is `true`)
`concurrency`	`uint16`	The maximum number of concurrent DNS queries.	`5`
`domain`	`string`	The internal domain for Wiretastix DNS resolution (e.g., `vpn.local`).	`vpn.`
`acls`	`[]string`	CIDR blocks (IPv4/IPv6) allowed to query the resolver. A source outside all listed blocks gets `REFUSED`. Empty allows any source that can reach the resolver – gates who may query at all, not which peers’ records they can see. A malformed entry fails validation at config load.	`[]` (empty)

`metrics`

Prometheus metrics exposure settings – a separate HTTP server from apiserver, with its own binding. This endpoint has no authentication of its own. It doesn’t leak secrets, but it does reveal internal topology (peer counts, WireGuard public keys, nicknames, traffic), so put it behind a reverse proxy enforcing access control if you bind it to anything beyond a loopback/internal address.

metrics:
    path: /metrics
    binding: 127.0.0.1:9090

Parameter	Type	Description	Default
`path`	`string`	The URL path for the metrics endpoint (e.g., `/metrics`).	`/metrics`
`binding`	`string`	The address and port the metrics server listens on (e.g., `127.0.0.1:9090`).	`127.0.0.1:9100`

There is no messaging section. An earlier version of Wiretastix had unused messaging.slack-url/mattermost-url/mattermost-dst config fields left over from a notification feature that was never wired up to anything – they were read by nothing even while they existed in the example config. Both the dead fields and the unused library behind them have since been removed. If you’re looking to get alerted on Wiretastix events, see Prometheus Metrics and configure your own Alertmanager routes (which do support Slack/Mattermost/PagerDuty/etc.) instead.