Configuration

The server reads wpg.toml from the working directory, or the file given with --config / WPG_CONFIG. Precedence, lowest first: built-in defaults, the file, environment variables WPG_<SECTION>__<KEY> (__ separates nesting levels, for example WPG_SERVER__BIND=0.0.0.0:8080 or WPG_TX__ALLOWED_IFACES='["eth1"]'), then command line options such as wpg serve --bind. Unknown keys are errors. wpg config init writes the commented example below, wpg config show prints the effective configuration, wpg config validate checks it and wpg config set-password stores the admin password hash. The admin password itself is not a key: wpg serve --password, --password-file and WPG_PASSWORD take precedence over auth.password_hash and auth.password_file. This page is generated from the configuration types.

Keys

Top level

[auth]

Authentication.

[dhcp]

DHCP server tool (DHCPv4 / DHCPv6 on one interface; pools and options are edited on the DHCP screen).

[log]

Logging.

[protocols]

User-defined protocols.

[server]

HTTP listener.

[server.tls]

TLS certificate chain and private key (PEM) to serve HTTPS with; takes precedence over self_signed_tls.

[snmp]

SNMP manager tool (Get / Walk / Set / traps, MIB upload).

[templates]

Template library.

[terminal]

Web terminal: SSH / Telnet sessions the server opens for logged-in users (see the web terminal guide).

[tx]

Transmit policy and defaults.

Example (wpg config init)

Every active line equals the built-in default, so the file changes nothing until edited; the commented lines show the optional keys.

# wpg.toml — Web Packet Generator configuration.
#
# Precedence (lowest first): built-in defaults < this file < environment variables
# (WPG_<SECTION>__<KEY>, e.g. WPG_SERVER__BIND=0.0.0.0:8080 or
# WPG_TX__ALLOWED_IFACES='["eth1"]') < command line options (wpg serve --bind ...).
# Unknown keys are rejected. Check a file with `wpg config validate`, print the
# effective configuration with `wpg config show`.

# Server state: user templates, favourites, job history, dry-run captures.
# Default: the OS data directory (Linux: ~/.local/share/wpg).
# data_dir = "/var/lib/wpg"

[server]
# Listen address. Without a password keep it on localhost.
bind = "127.0.0.1:8080"
# Public URL when running behind a reverse proxy.
# base_url = "https://wpg.example.net"
# Serve HTTPS with a self-signed certificate generated into <data_dir>/tls/
# (same as `wpg serve --tls`). Ignored when [server.tls] is set.
self_signed_tls = false
# Most packets one preview request may render (1-100000).
preview_max = 256
# Finished jobs listed on the Jobs screen (kept in memory, 1-100000) and kept in
# the database (1-10000000; older ones are deleted).
job_history = 100
job_history_db = 1000

# TLS certificate chain and private key (PEM) to serve HTTPS with.
# [server.tls]
# cert = "/etc/wpg/cert.pem"
# key = "/etc/wpg/key.pem"

[auth]
# Admin password. Without one (and without a user created on the first-run
# setup screen) the server only listens on localhost. Sources, highest first:
# `wpg serve --password`, `--password-file`, $WPG_PASSWORD, password_hash,
# password_file, the setup screen.
# argon2id hash of the admin password (`wpg config set-password` writes it):
# password_hash = "$argon2id$v=19$m=19456,t=2,p=1$..."
# Or a file holding the hash or the plain-text password:
# password_file = "/etc/wpg/password"
# Session lifetime in seconds (extended by every request).
session_ttl_secs = 86400

[templates]
# Read-only template libraries (Git checkouts etc.), scanned recursively for
# *.wpg.yaml / *.wpg.json and reloaded when files change.
library_paths = ["./templates"]
# Writable directory for templates created or imported in the GUI.
# Default: <data_dir>/templates
# user_dir = "/var/lib/wpg/templates"

[protocols]
# Directories of user-defined protocol files (*.yaml), loaded at startup.
# Changes need a restart.
# dirs = ["/etc/wpg/protocols.d"]

[tx]
# Interfaces jobs may send on; empty = all. The null backend and dry runs are
# not restricted.
allowed_ifaces = []
# Highest rate a job may request, e.g. "100kpps" or "1Gbps". Jobs without a rate
# are sent at this rate.
# max_rate = "100kpps"
# Backend when a job names none: null, pcapfile, afpacket, pcap, afxdp, dpdk.
# Default: afpacket on Linux, else pcap, else null.
# default_backend = "afpacket"
# DPDK EAL arguments for the dpdk backend (wpg adds "-l <first CPU>" and
# "--in-memory" unless given). EAL starts with the first dpdk job; changing them
# needs a restart.
# dpdk_eal_args = ["-a", "0000:00:04.0"]
# Streams are pre-rendered (every frame built before sending) when they have at
# most prerender_max_packets packets and packets * frame length is at most
# prerender_max_bytes (default 256 MiB, up to 1 TiB); larger ones are built on
# the fly. `wpg send --prerender-max-bytes / --prerender-max-packets` override.
prerender_max_bytes = 268435456
prerender_max_packets = 100000000
# Memory of one afpacket TX ring / afxdp UMEM per worker in bytes (1 MiB-1 GiB,
# default 16 MiB); --ring-depth is reduced to fit. Locked memory: raise
# `ulimit -l` / LimitMEMLOCK for large values.
ring_bytes = 16777216

[snmp]
# SNMP tool screen and API (Get / Walk / Set / traps, MIB upload).
enabled = true
# Trap / inform receiver started at boot, e.g. "0.0.0.0:162" (ports below 1024
# need root or CAP_NET_BIND_SERVICE). Empty: not started at boot (it can be
# started from the UI).
trap_listen = ""
# Directory of uploaded MIB files. Empty: <data_dir>/mibs
mib_dir = ""

[dhcp]
# DHCP screen and API (DHCPv4 / DHCPv6 server, Linux only). Pools and options
# are edited on the screen and kept in <data_dir>/dhcp.json.
enabled = true
# Interface the server answers on, e.g. "eth1". Empty: chosen on the screen
# among tx.allowed_ifaces. Ports 67 / 547 need root or CAP_NET_BIND_SERVICE.
iface = ""

[log]
# Filter directives (RUST_LOG overrides this), e.g. "info" or "wpg_tx=debug,info".
level = "info"
# "pretty" or "json".
format = "pretty"
# Also write to this file (its directory is created).
# file = "/var/log/wpg/wpg.log"
# Rotation of the file: "never", "hourly" or "daily".
rotation = "never"
# Keep at most this many rotated files.
# max_files = 7
# Colour the console output when it is a terminal.
ansi = true

[terminal]
enabled = false          # Web terminal (SSH / Telnet)
allowed_targets = []     # "host", "host:port" or CIDR; empty = any target
record_sessions = true   # keep session logs under <data_dir>/terminal-logs
idle_timeout_secs = 1800
max_sessions = 8