1WG(8) WireGuard WG(8)
2
6 wg - set and retrieve configuration of WireGuard interfaces
7
10 wg [ COMMAND ] [ OPTIONS ]... [ ARGS ]...
11
14 wg is the configuration utility for getting and setting the configura‐
15 tion of WireGuard tunnel interfaces. The interfaces themselves can be
16 added and removed using ip-link(8) and their IP addresses and routing
17 tables can be set using ip-address(8) and ip-route(8). The wg utility
18 provides a series of sub-commands for changing WireGuard-specific as‐
19 pects of WireGuard interfaces.
20 If no COMMAND is specified, COMMAND defaults to show. Sub-commands
22 that take an INTERFACE must be passed a WireGuard interface.
23
26 show { <interface> | all | interfaces } [public-key | private-key |
27 listen-port | fwmark | peers | preshared-keys | endpoints | allowed-ips
28 | latest-handshakes | persistent-keepalive | transfer | dump]
29 Shows current WireGuard configuration and runtime information of
30 specified <interface>. If no <interface> is specified, <inter‐
31 face> defaults to all. If interfaces is specified, prints a
32 list of all WireGuard interfaces, one per line, and quits. If no
33 options are given after the interface specification, then prints
34 a list of all attributes in a visually pleasing way meant for
35 the terminal. Otherwise, prints specified information grouped by
36 newlines and tabs, meant to be used in scripts. For this script-
37 friendly display, if all is specified, then the first field for
38 all categories of information is the interface name. If dump is
39 specified, then several lines are printed; the first contains in
40 order separated by tab: private-key, public-key, listen-port,
41 fwmark. Subsequent lines are printed for each peer and contain
42 in order separated by tab: public-key, preshared-key, endpoint,
43 allowed-ips, latest-handshake, transfer-rx, transfer-tx, persis‐
44 tent-keepalive.
45 showconf <interface>
47 Shows the current configuration of <interface> in the format de‐
48 scribed by CONFIGURATION FILE FORMAT below.
49 set <interface> [listen-port <port>] [fwmark <fwmark>] [private-key
51 <file-path>] [peer <base64-public-key> [remove] [preshared-key <file-
52 path>] [endpoint <ip>:<port>] [persistent-keepalive <interval seconds>]
53 [allowed-ips <ip1>/<cidr1>[,<ip2>/<cidr2>]...] ]...
54 Sets configuration values for the specified <interface>. Multi‐
55 ple peers may be specified, and if the remove argument is given
56 for a peer, that peer is removed, not configured. If listen-port
57 is not specified, or set to 0, the port will be chosen randomly
58 when the interface comes up. Both private-key and preshared-key
59 must be files, because command line arguments are not considered
60 private on most systems but if you are using bash(1), you may
61 safely pass in a string by specifying as private-key or pre‐
62 shared-key the expression: <(echo PRIVATEKEYSTRING). If
63 /dev/null or another empty file is specified as the filename for
64 either private-key or preshared-key, the key is removed from the
65 device. The use of preshared-key is optional, and may be omit‐
66 ted; it adds an additional layer of symmetric-key cryptography
67 to be mixed into the already existing public-key cryptography,
68 for post-quantum resistance. If allowed-ips is specified, but
69 the value is the empty string, all allowed ips are removed from
70 the peer. The use of persistent-keepalive is optional and is by
71 default off; setting it to 0 or "off" disables it. Otherwise it
72 represents, in seconds, between 1 and 65535 inclusive, how often
73 to send an authenticated empty packet to the peer, for the pur‐
74 pose of keeping a stateful firewall or NAT mapping valid persis‐
75 tently. For example, if the interface very rarely sends traffic,
76 but it might at anytime receive traffic from a peer, and it is
77 behind NAT, the interface might benefit from having a persistent
78 keepalive interval of 25 seconds; however, most users will not
79 need this. The use of fwmark is optional and is by default off;
80 setting it to 0 or "off" disables it. Otherwise it is a 32-bit
81 fwmark for outgoing packets and may be specified in hexadecimal
82 by prepending "0x".
83 setconf <interface> <configuration-filename>
85 Sets the current configuration of <interface> to the contents of
86 <configuration-filename>, which must be in the format described
87 by CONFIGURATION FILE FORMAT below.
88 addconf <interface> <configuration-filename>
90 Appends the contents of <configuration-filename>, which must be
91 in the format described by CONFIGURATION FILE FORMAT below, to
92 the current configuration of <interface>.
93 syncconf <interface> <configuration-filename>
95 Like setconf, but reads back the existing configuration first
96 and only makes changes that are explicitly different between the
97 configuration file and the interface. This is much less effi‐
98 cient than setconf, but has the benefit of not disrupting cur‐
99 rent peer sessions. The contents of <configuration-filename>
100 must be in the format described by CONFIGURATION FILE FORMAT be‐
101 low.
102 genkey Generates a random private key in base64 and prints it to stan‐
104 dard output.
105 genpsk Generates a random preshared key in base64 and prints it to
107 standard output.
108 pubkey Calculates a public key and prints it in base64 to standard out‐
110 put from a corresponding private key (generated with genkey)
111 given in base64 on standard input.
112 A private key and a corresponding public key may be generated at
114 once by calling:
115 $ umask 077
116 $ wg genkey | tee private.key | wg pubkey > public.key
117 help Shows usage message.
119
122 The configuration file format is based on INI. There are two top level
123 sections -- Interface and Peer. Multiple Peer sections may be speci‐
124 fied, but only one Interface section may be specified.
125 The Interface section may contain the following fields:
128 • PrivateKey — a base64 private key generated by wg genkey. Re‐
130 quired.
131 • ListenPort — a 16-bit port for listening. Optional; if not spec‐
133 ified, chosen randomly.
134 • FwMark — a 32-bit fwmark for outgoing packets. If set to 0 or
136 "off", this option is disabled. May be specified in hexadecimal
137 by prepending "0x". Optional.
138 The Peer sections may contain the following fields:
140 • PublicKey — a base64 public key calculated by wg pubkey from a
142 private key, and usually transmitted out of band to the author
143 of the configuration file. Required.
144 • PresharedKey — a base64 preshared key generated by wg genpsk.
146 Optional, and may be omitted. This option adds an additional
147 layer of symmetric-key cryptography to be mixed into the already
148 existing public-key cryptography, for post-quantum resistance.
149 • AllowedIPs — a comma-separated list of IP (v4 or v6) addresses
151 with CIDR masks from which incoming traffic for this peer is al‐
152 lowed and to which outgoing traffic for this peer is directed.
153 The catch-all 0.0.0.0/0 may be specified for matching all IPv4
154 addresses, and ::/0 may be specified for matching all IPv6 ad‐
155 dresses. May be specified multiple times.
156 • Endpoint — an endpoint IP or hostname, followed by a colon, and
158 then a port number. This endpoint will be updated automatically
159 to the most recent source IP address and port of correctly au‐
160 thenticated packets from the peer. Optional.
161 • PersistentKeepalive — a seconds interval, between 1 and 65535
163 inclusive, of how often to send an authenticated empty packet to
164 the peer for the purpose of keeping a stateful firewall or NAT
165 mapping valid persistently. For example, if the interface very
166 rarely sends traffic, but it might at anytime receive traffic
167 from a peer, and it is behind NAT, the interface might benefit
168 from having a persistent keepalive interval of 25 seconds. If
169 set to 0 or "off", this option is disabled. By default or when
170 unspecified, this option is off. Most users will not need this.
171 Optional.
172
175 This example may be used as a model for writing configuration files,
176 following an INI-like syntax. Characters after and including a '#' are
177 considered comments and are thus ignored.
178 [Interface]
180 PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
181 ListenPort = 51820
182 [Peer]
184 PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
185 Endpoint = 192.95.5.67:1234
186 AllowedIPs = 10.192.122.3/32, 10.192.124.1/24
187 [Peer]
189 PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0=
190 Endpoint = [2607:5300:60:6b0::c05f:543]:2468
191 AllowedIPs = 10.192.122.4/32, 192.168.0.0/16
192 [Peer]
194 PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA=
195 Endpoint = test.wireguard.com:18981
196 AllowedIPs = 10.10.10.230/32
197
200 Sometimes it is useful to have information on the current runtime state
201 of a tunnel. When using the Linux kernel module on a kernel that sup‐
202 ports dynamic debugging, debugging information can be written into
203 dmesg(1) by running as root:
204 # modprobe wireguard && echo module wireguard +p > /sys/kernel/de‐
206 bug/dynamic_debug/control
207 On OpenBSD and FreeBSD, debugging information can be written into
209 dmesg(1) on a per-interface basis by using ifconfig(1):
210 # ifconfig wg0 debug
212 On userspace implementations, it is customary to set the LOG_LEVEL en‐
214 vironment variable to verbose.
215
218 WG_COLOR_MODE
219 If set to always, always print ANSI colorized output. If set to
220 never, never print ANSI colorized output. If set to auto, some‐
221 thing invalid, or unset, then print ANSI colorized output only
222 when writing to a TTY.
223 WG_HIDE_KEYS
225 If set to never, then the pretty-printing show sub-command will
226 show private and preshared keys in the output. If set to always,
227 something invalid, or unset, then private and preshared keys
228 will be printed as "(hidden)".
229 WG_ENDPOINT_RESOLUTION_RETRIES
231 If set to an integer or to infinity, DNS resolution for each
232 peer's endpoint will be retried that many times for non-perma‐
233 nent errors, with an increasing delay between retries. If unset,
234 the default is 15 retries.
235
238 wg-quick(8), ip(8), ip-link(8), ip-address(8), ip-route(8).
239
242 wg was written by Jason A. Donenfeld ⟨Jason@zx2c4.com⟩. For updates
243 and more information, a project page is available on the World Wide Web
244 ⟨https://www.wireguard.com/⟩.
245ZX2C4 2015 August 13 WG(8)