99 lines
4.0 KiB
Markdown
99 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```ini
|
|
# 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:
|
|
|
|
```ini
|
|
# 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:
|
|
|
|
```ini
|
|
# 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:
|
|
|
|
```ini
|
|
# Added during the 2024 network migration; wg-admin is not the owner of this note.
|
|
[Peer]
|
|
PublicKey = AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE=
|
|
AllowedIPs = 10.0.0.3/32
|
|
```
|