4.0 KiB
Managed metadata in the WireGuard configuration
WireGuard Admin stores a client's display alias and optional creation time in a
versioned comment block immediately before that client's [Peer] header. The
server configuration remains the source of truth. The block contains no public
key copy, private key, preshared key, password, or other connection secret.
Version 1 grammar
The canonical LF form is:
# wg-admin:begin
# wg-admin:version=1
# wg-admin:alias=<base64url-utf8-without-padding>
# wg-admin:created-utc=2026-10-18T19:00:00Z
# wg-admin:end
[Peer]
created-utc is optional. If it is unknown, it is omitted; an existing peer's
unknown creation date is never inferred from import time, file time, or edit time.
The timestamp grammar is exactly YYYY-MM-DDTHH:MM:SSZ, with a real Gregorian
calendar date, a four-digit nonzero year, and seconds from 00 through 59.
Leap seconds and fractional seconds are not represented.
The alias line contains the canonical URL-safe Base64 encoding of the alias's
UTF-8 bytes, with no = padding. This representation is a single comment line
and makes characters such as #, =, quotes, non-ASCII text, and strings that
look like block markers unambiguous. An alias must pass the application's shared
alias validation: it cannot be empty or contain Unicode control characters.
The encoded representation is decoded and re-encoded canonically when read.
The v1 block has exactly one begin marker, one version field, one alias field, optional single creation field, and one end marker, in the displayed order. No other lines or fields are permitted. Unknown fields, duplicate fields, malformed encoding, or invalid timestamps make the block invalid. A version other than 1 is reported as unsupported and is not interpreted or rewritten.
Ownership and attachment
The exact reserved marker lines are # wg-admin:begin and # wg-admin:end.
Marker lines with trailing whitespace or extra text are treated as malformed
reserved markers. Other administrator comments, including comments that merely
mention wg-admin, do not become managed blocks.
A valid block owns only its own comment lines and line endings. It is attached to
one peer only when its end marker line, including its line ending, ends at the
first byte of that peer's [Peer] header. No blank line, administrator comment,
or other text may intervene. A block elsewhere is reported as misattached. A
missing block is the legacy state: no alias or creation date is inferred, and no
block span is available to edit. Multiple adjacent blocks before one peer are a
duplicate and block metadata edits. Malformed, misattached, duplicate, and
unsupported-version blocks are retained as supplied and block unsafe metadata
edits; they are not treated as absent metadata.
The parser exposes the decoded alias only for a valid, uniquely attached v1 block. It exposes an owned byte span only for that valid block. Issues contain line numbers and categories but never raw source text. Parsing and rendering are caller-buffer operations and do not read or write configuration files.
Examples
An alias containing syntax characters and Unicode is encoded, not escaped in
WireGuard syntax. For example, the alias # café = "laptop" is represented as:
# wg-admin:begin
# wg-admin:version=1
# wg-admin:alias=IyBjYWbDqSA9ICJsYXB0b3Ai
# wg-admin:end
[Peer]
A marker-looking alias is handled the same way. Applications should use the canonical renderer rather than hand-constructing the encoded value.
An existing client with unknown creation time has no created-utc field:
# wg-admin:begin
# wg-admin:version=1
# wg-admin:alias=V29ya2xhcGU
# wg-admin:end
[Peer]
PublicKey = AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
AllowedIPs = 10.0.0.2/32
An unrelated administrator comment is preserved and does not describe managed metadata:
# Added during the 2024 network migration; wg-admin is not the owner of this note.
[Peer]
PublicKey = AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE=
AllowedIPs = 10.0.0.3/32