1WG(8)                              WireGuard                             WG(8)
2
3
4

NAME

6       wg - set and retrieve configuration of WireGuard interfaces
7
8

SYNOPSIS

10       wg [ COMMAND ] [ OPTIONS ]... [ ARGS ]...
11
12

DESCRIPTION

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
21       If no COMMAND is specified, COMMAND  defaults  to  show.   Sub-commands
22       that take an INTERFACE must be passed a WireGuard interface.
23
24

COMMANDS

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
46       showconf <interface>
47              Shows the current configuration of <interface> in the format de‐
48              scribed by CONFIGURATION FILE FORMAT below.
49
50       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
84       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
89       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
94       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
103       genkey Generates a random private key in base64 and prints it to  stan‐
104              dard output.
105
106       genpsk Generates  a  random  preshared  key  in base64 and prints it to
107              standard output.
108
109       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
113              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
118       help   Shows usage message.
119
120

CONFIGURATION FILE FORMAT

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
126
127       The Interface section may contain the following fields:
128
129       •      PrivateKey  —  a  base64 private key generated by wg genkey. Re‐
130              quired.
131
132       •      ListenPort — a 16-bit port for listening. Optional; if not spec‐
133              ified, chosen randomly.
134
135       •      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
139       The Peer sections may contain the following fields:
140
141       •      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
145       •      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
150       •      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
157       •      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
162       •      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
173

CONFIGURATION FILE FORMAT EXAMPLE

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
179           [Interface]
180           PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
181           ListenPort = 51820
182
183           [Peer]
184           PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
185           Endpoint = 192.95.5.67:1234
186           AllowedIPs = 10.192.122.3/32, 10.192.124.1/24
187
188           [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
193           [Peer]
194           PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA=
195           Endpoint = test.wireguard.com:18981
196           AllowedIPs = 10.10.10.230/32
197
198

DEBUGGING INFORMATION

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
205           # modprobe wireguard && echo module wireguard +p >  /sys/kernel/de‐
206       bug/dynamic_debug/control
207
208       On  OpenBSD  and  FreeBSD,  debugging  information  can be written into
209       dmesg(1) on a per-interface basis by using ifconfig(1):
210
211           # ifconfig wg0 debug
212
213       On userspace implementations, it is customary to set the LOG_LEVEL  en‐
214       vironment variable to verbose.
215
216

ENVIRONMENT VARIABLES

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
224       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
230       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
236

SEE ALSO

238       wg-quick(8), ip(8), ip-link(8), ip-address(8), ip-route(8).
239
240

AUTHOR

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
244https://www.wireguard.com/⟩.
245
246
247
248ZX2C4                           2015 August 13                           WG(8)
Impressum