WG(8)

🎀 WG(8) 🎀

okay bestie, gather round, because this is the manual page for wg(8) — the WireGuard config utility — and it's genuinely iconic.

---

✨ NAME ✨

wg — set and retrieve configuration of WireGuard interfaces 💖

---

🌸 SYNOPSIS 🌸

wg [ COMMAND ] [ OPTIONS ]... [ ARGS ]...

---

🦋 DESCRIPTION 🦋

so like. wg is the configuration utility for getting and setting the configuration of WireGuard tunnel interfaces. that's the whole vibe. 🫶

the interfaces themselves — the actual tunnel devices — get added and removed using ip-link(8), and their IP addresses and routing tables get set using ip-address(8) and ip-route(8). wg doesn't do that part, that's not her job. what wg does is give you a series of sub-commands for changing the WireGuard-specific aspects of WireGuard interfaces. she's a specialist. she's booked and busy. 💅

if no COMMAND is specified, COMMAND defaults to show. no cap. you just type wg and she shows you things.

⚠️ sub-commands that take an INTERFACE must be passed a WireGuard interface. like, an actual WireGuard one. she will not be fooled. 😭

---

👑 COMMANDS 👑

🌈 show

show { <interface> | all | interfaces } [public-key | private-key |
listen-port | fwmark | peers | preshared-keys | endpoints | allowed-ips
| latest-handshakes | persistent-keepalive | transfer | dump]

shows the current WireGuard configuration and runtime information of the specified <interface> ✨

• if no <interface> is specified, <interface> defaults to all. everyone's invited to the group chat.
• if interfaces is specified, it prints a list of all WireGuard interfaces, one per line, and quits. just the names. a little roll call. 🎀
• if no options are given after the interface specification, then it prints a list of all attributes in a visually pleasing way meant for the terminal. for you. because you deserve nice things.
• otherwise, it prints specified information grouped by newlines and tabs, meant to be used in scripts. script-friendly, no decoration, all business.
• for this script-friendly display, if all is specified, then the first field for all categories of information is the interface name. so you always know who's who. 💜
• if dump is specified, then several lines are printed. the first contains, in order separated by tab: private-key, public-key, listen-port, fwmark. subsequent lines are printed for each peer and contain, in order separated by tab: public-key, preshared-key, endpoint, allowed-ips, latest-handshake, transfer-rx, transfer-tx, persistent-keepalive. literally the full tea, tab-separated. 🔥

🌸 showconf <interface>

shows the current configuration of <interface> in the format described by CONFIGURATION FILE FORMAT below. it's giving copy-paste-able. 🎀

💜 set

set <interface> [listen-port <port>] [fwmark <fwmark>] [private-key
<file-path>] [peer <base64-public-key> [remove] [preshared-key <file-
path>] [endpoint <ip>:<port>] [persistent-keepalive <interval seconds>]
[allowed-ips [+|-]<ip1>/<cidr1>[,[+|-]<ip2>/<cidr2>]...] ]...

sets configuration values for the specified <interface>. okay so here's the tea, option by option: 🫖

• multiple peers may be specified, and if the remove argument is given for a peer, that peer is removed, not configured. bye bestie 👋
• if listen-port is not specified, or set to 0, the port will be chosen randomly when the interface comes up. surprise port! 🎁
• both private-key and preshared-key must be files, because command line arguments are not considered private on most systems. ngl that's just facts. but if you are using bash(1), you may safely pass in a string by specifying as private-key or preshared-key the expression: <(echo PRIVATEKEYSTRING) — process substitution, we love her 💅
• if /dev/null or another empty file is specified as the filename for either private-key or preshared-key, the key is removed from the device.
• the use of preshared-key is optional, and may be omitted; it adds an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. extra armour, extra slay. 🔥
• if allowed-ips is specified, but the value is the empty string, all allowed ips are removed from the peer. clean slate, fresh start. 🧚
• by default, allowed-ips replaces a peer's allowed ips. if + or - is prepended to any of the ips then the update is incremental; ips prefixed with '+' or '' are added to the peer's allowed ips if not present, while ips prefixed with '-' are removed if present. patch notes energy. 📝
• the use of persistent-keepalive is optional and is by default off; setting it to 0 or "off" disables it. otherwise it represents, in seconds, between 1 and 65535 inclusive, how often to send an authenticated empty packet to the peer, for the purpose of keeping a stateful firewall or NAT mapping valid persistently. for example, if the interface very rarely sends traffic, but it might at anytime receive traffic from a peer, and it is behind NAT, the interface might benefit from having a persistent keepalive interval of 25 seconds; however, most users will not need this. (most users will not need this. she said it once. she'll say it again.) 🙈
• the use of fwmark is optional and is by default off; setting it to 0 or "off" disables it. otherwise it is a 32-bit fwmark for outgoing packets and may be specified in hexadecimal by prepending "0x". hex girlies rise 🎀

💖 setconf <interface> <configuration-filename>

sets the current configuration of <interface> to the contents of <configuration-filename>, which must be in the format described by CONFIGURATION FILE FORMAT below. full replace, no mercy, periodt. 💅

🌟 addconf <interface> <configuration-filename>

appends the contents of <configuration-filename>, which must be in the format described by CONFIGURATION FILE FORMAT below, to the current configuration of <interface>. additive. gentle. she's just adding to the collection. 🫶

🦋 syncconf <interface> <configuration-filename>

like setconf, but reads back the existing configuration first and only makes changes that are explicitly different between the configuration file and the interface. this is much less efficient than setconf, but has the benefit of not disrupting current peer sessions. the contents of <configuration-filename> must be in the format described by CONFIGURATION FILE FORMAT below. slow and steady keeps the call connected. 📞

🔑 genkey

generates a random private key in base64 and prints it to standard output. boom. secret acquired. 🤫

🎀 genpsk

generates a random preshared key in base64 and prints it to standard output. more secrets. more slay.

✨ pubkey

calculates a public key and prints it in base64 to standard output from a corresponding private key (generated with genkey) given in base64 on standard input. it's a glow-up pipeline: private in, public out. 💖

a private key and a corresponding public key may be generated at once by calling:

$ umask 077
$ wg genkey | tee private.key | wg pubkey > public.key

👑 help

shows usage message. when in doubt, ask for help. iconic behaviour. 🫶

---

🧚 CONFIGURATION FILE FORMAT 🧚

the configuration file format is based on INI. there are two top level sections — Interface and Peer. multiple Peer sections may be specified, but only one Interface section may be specified. one interface, many peers. main character energy. 💅

the Interface section may contain the following fields:

• PrivateKey — a base64 private key generated by wg genkey. Required.
• ListenPort — a 16-bit port for listening. Optional; if not specified, chosen randomly.
• FwMark — a 32-bit fwmark for outgoing packets. If set to 0 or "off", this option is disabled. May be specified in hexadecimal by prepending "0x". Optional.

the Peer sections may contain the following fields:

• PublicKey — a base64 public key calculated by wg pubkey from a private key, and usually transmitted out of band to the author of the configuration file. Required.
• PresharedKey — a base64 preshared key generated by wg genpsk. Optional, and may be omitted. This option adds an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance.
• AllowedIPs — a comma-separated list of IP (v4 or v6) addresses with CIDR masks from which incoming traffic for this peer is allowed and to which outgoing traffic for this peer is directed. The catch-all 0.0.0.0/0 may be specified for matching all IPv4 addresses, and ::/0 may be specified for matching all IPv6 addresses. May be specified multiple times.
• Endpoint — an endpoint IP or hostname, followed by a colon, and then a port number. This endpoint will be updated automatically to the most recent source IP address and port of correctly authenticated packets from the peer. Optional.
• PersistentKeepalive — a seconds interval, between 1 and 65535 inclusive, of how often to send an authenticated empty packet to the peer for the purpose of keeping a stateful firewall or NAT mapping valid persistently. For example, if the interface very rarely sends traffic, but it might at anytime receive traffic from a peer, and it is behind NAT, the interface might benefit from having a persistent keepalive interval of 25 seconds. If set to 0 or "off", this option is disabled. By default or when unspecified, this option is off. Most users will not need this. Optional.

---

🌈 CONFIGURATION FILE FORMAT EXAMPLE 🌈

this example may be used as a model for writing configuration files, following an INI-like syntax. characters after and including a # are considered comments and are thus ignored. so go ahead, annotate your heart out. ✍️

[Interface]
PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
ListenPort = 51820

[Peer]
PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
Endpoint = 192.95.5.67:1234
AllowedIPs = 10.192.122.3/32, 10.192.124.1/24

[Peer]
PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0=
Endpoint = [2607:5300:60:6b0::c05f:543]:2468
AllowedIPs = 10.192.122.4/32, 192.168.0.0/16

[Peer]
PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA=
Endpoint = test.wireguard.com:18981
AllowedIPs = 10.10.10.230/32

---

🔥 DEBUGGING INFORMATION 🔥

sometimes it is useful to have information on the current runtime state of a tunnel. she's mysterious. let's make her talk. 🕵️‍♀️

when using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into dmesg(1) by running as root:

# modprobe wireguard && echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control

on OpenBSD and FreeBSD, debugging information can be written into dmesg(1) on a per-interface basis by using ifconfig(1):

# ifconfig wg0 debug

on userspace implementations, it is customary to set the LOG_LEVEL environment variable to verbose. 🎀

🌈 ENVIRONMENT VARIABLES 🌈

okay so these are the little environment gremlins that change how wg acts, and they are literally so important. no cap. 💅

• WG_COLOR_MODE — bestie, this controls the ANSI colorized output. If you set it to always, then it will always print ANSI colorized output. If you set it to never, then it will never print ANSI colorized output. If you set it to auto, or to something invalid, or if it's just unset, then it will print ANSI colorized output only when writing to a TTY. periodt. ✨
• WG_HIDE_KEYS — okay so if you set this to never, then the pretty-printing show sub-command will show private and preshared keys in the output. 👀 If you set it to always, or to something invalid, or if it's unset, then private and preshared keys will be printed as "(hidden)". so if you're screen-sharing, maybe don't set it to never, iykyk. 🙈
• WG_ENDPOINT_RESOLUTION_RETRIES — if you set this to an integer or to infinity, then DNS resolution for each peer's endpoint will be retried that many times for non-permanent errors, with an increasing delay between retries. 🔁 If it's unset, the default is 15 retries. so yes, it will keep trying, and the delay gets bigger each time. no cap. 💫

---

👀 SEE ALSO 👀

• wg-quick(8)
• ip(8)
• ip-link(8)
• ip-address(8)
• ip-route(8)

---

👑 AUTHOR 👑

wg was written by Jason A. Donenfeld. For updates and more information, a project page is available on the World Wide Web. 🌐 like, go look, bestie, it's giving iconic.

---

this page is serving major main character energy, brought to you by ZX2C4 and dated 2015 August 13, for the WG(8) manual. mwah 💖