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
19       aspects 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
48              described 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
101              below.
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.
130              Required.
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
152              allowed 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
155              addresses. 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
160              authenticated 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/ker‐
206       nel/debug/dynamic_debug/control
207
208       On  userspace  implementations,  it  is  customary to set the LOG_LEVEL
209       environment variable to verbose.
210
211

ENVIRONMENT VARIABLES

213       WG_COLOR_MODE
214              If set to always, always print ANSI colorized output. If set  to
215              never,  never print ANSI colorized output. If set to auto, some‐
216              thing invalid, or unset, then print ANSI colorized  output  only
217              when writing to a TTY.
218
219       WG_HIDE_KEYS
220              If  set to never, then the pretty-printing show sub-command will
221              show private and preshared keys in the output. If set to always,
222              something  invalid,  or  unset,  then private and preshared keys
223              will be printed as "(hidden)".
224
225       WG_ENDPOINT_RESOLUTION_RETRIES
226              If set to an integer or to infinity,  DNS  resolution  for  each
227              peer's  endpoint  will be retried that many times for non-perma‐
228              nent errors, with an increasing delay between retries. If unset,
229              the default is 15 retries.
230
231

SEE ALSO

233       wg-quick(8), ip(8), ip-link(8), ip-address(8), ip-route(8).
234
235

AUTHOR

237       wg  was  written  by Jason A. Donenfeld ⟨Jason@zx2c4.com⟩.  For updates
238       and more information, a project page is available on the World Wide Web
239https://www.wireguard.com/⟩.
240
241
242
243ZX2C4                           2015 August 13                           WG(8)
Impressum