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

NAME

6       wg-quick - set up a WireGuard interface simply
7
8

SYNOPSIS

10       wg-quick [ up | down | save | strip ] [ CONFIG_FILE | INTERFACE ]
11
12

DESCRIPTION

14       This  is  an extremely simple script for easily bringing up a WireGuard
15       interface, suitable for a few common use cases.
16
17       Use up to add and set up an interface, and use down to  tear  down  and
18       remove  an  interface. Running up adds a WireGuard interface, brings up
19       the interface with the supplied IP addresses, sets up mtu  and  routes,
20       and  optionally runs pre/post up scripts. Running down optionally saves
21       the current configuration, removes the WireGuard interface, and option‐
22       ally  runs  pre/post down scripts. Running save saves the configuration
23       of an existing interface without bringing the interface down. Use strip
24       to  output  a  configuration file with all wg-quick(8)-specific options
25       removed, suitable for use with wg(8).
26
27       CONFIG_FILE is a configuration file, whose filename  is  the  interface
28       name  followed  by  `.conf'. Otherwise, INTERFACE is an interface name,
29       with configuration found at  `/etc/wireguard/INTERFACE.conf',  searched
30       first, followed by distro-specific search paths.
31
32       Generally  speaking,  this  utility  is just a simple script that wraps
33       invocations to wg(8) and ip(8) in order to set up  a  WireGuard  inter‐
34       face.  It  is designed for users with simple needs, and users with more
35       advanced needs are highly encouraged to use a  more  specific  tool,  a
36       more  complete  network manager, or otherwise just use wg(8) and ip(8),
37       as usual.
38
39

CONFIGURATION

41       The configuration file adds a few extra  configuration  values  to  the
42       format  understood by wg(8) in order to configure additional attributes
43       of an interface. It handles the values that it understands, and then it
44       passes the remaining ones directly to wg(8) for further processing.
45
46       It infers all routes from the list of peers' allowed IPs, and automati‐
47       cally adds them to the system routing table. If one of those routes  is
48       the  default route (0.0.0.0/0 or ::/0), then it uses ip-rule(8) to han‐
49       dle overriding of the default gateway.
50
51       The configuration file will be passed  directly  to  wg(8)'s  `setconf'
52       sub-command,  with  the  exception  of  the  following additions to the
53       Interface section, which are handled by this tool:
54
55
56       ·      Address — a comma-separated list of  IP  (v4  or  v6)  addresses
57              (optionally  with  CIDR  masks) to be assigned to the interface.
58              May be specified multiple times.
59
60       ·      DNS — a comma-separated list of IP (v4 or v6)  addresses  to  be
61              set  as  the  interface's DNS servers, or non-IP hostnames to be
62              set as the interface's DNS search domains. May be specified mul‐
63              tiple  times. Upon bringing the interface up, this runs `resolv‐
64              conf -a tun.INTERFACE -m 0 -x` and upon bringing it  down,  this
65              runs  `resolvconf -d tun.INTERFACE`. If these particular invoca‐
66              tions of resolvconf(8) are undesirable, the PostUp and  PostDown
67              keys below may be used instead.
68
69       ·      MTU — if not specified, the MTU is automatically determined from
70              the endpoint addresses or the system  default  route,  which  is
71              usually  a  sane  choice. However, to manually specify an MTU to
72              override this automatic discovery, this value may  be  specified
73              explicitly.
74
75       ·      Table  —  Controls  the routing table to which routes are added.
76              There are two special values: `off'  disables  the  creation  of
77              routes  altogether,  and `auto' (the default) adds routes to the
78              default table and enables special handling of default routes.
79
80       ·      PreUp, PostUp, PreDown, PostDown — script snippets which will be
81              executed  by  bash(1)  before/after  setting up/tearing down the
82              interface, most commonly used to configure custom DNS options or
83              firewall  rules.  The  special string `%i' is expanded to INTER‐
84              FACE. Each one may be specified multiple times,  in  which  case
85              the commands are executed in order.
86
87       ·      SaveConfig  —  if set to `true', the configuration is saved from
88              the current state of the interface upon  shutdown.  Any  changes
89              made  to  the configuration file before the interface is removed
90              will therefore be overwritten.
91
92
93       Recommended INTERFACE names include `wg0' or `wgvpn0' or even  `wgmgmt‐
94       lan0'.   However, the number at the end is in fact optional, and really
95       any free-form string [a-zA-Z0-9_=+.-]{1,15} will work. So  even  inter‐
96       face names corresponding to geographic locations would suffice, such as
97       `cincinnati', `nyc', or `paris', if that's somehow desirable.
98
99

EXAMPLES

101       These examples draw on the same syntax found for wg(8), and a more com‐
102       plete  description may be found there. Bold lines below are for options
103       that extend wg(8).
104
105       The following might be used for connecting as a client to a VPN gateway
106       for tunneling all traffic:
107
108           [Interface]
109           Address = 10.200.100.8/24
110           DNS = 10.200.100.1
111           PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM=
112
113           [Peer]
114           PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU=
115           PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak=
116           AllowedIPs = 0.0.0.0/0
117           Endpoint = demo.wireguard.com:51820
118
119       The  `Address`  field  is added here in order to set up the address for
120       the interface. The `DNS` field indicates that  a  DNS  server  for  the
121       interface  should  be configured via resolvconf(8).  The peer's allowed
122       IPs entry implies that this  interface  should  be  configured  as  the
123       default gateway, which this script does.
124
125       Building  on  the last example, one might attempt the so-called ``kill-
126       switch'', in order to prevent the flow of unencrypted  packets  through
127       the  non-WireGuard  interfaces,  by  adding  the  following  two  lines
128       `PostUp` and `PreDown` lines to the `[Interface]` section:
129
130           PostUp = iptables -I OUTPUT ! -o %i -m mark ! --mark $(wg  show  %i
131       fwmark) -m addrtype ! --dst-type LOCAL -j REJECT
132           PreDown  = iptables -D OUTPUT ! -o %i -m mark ! --mark $(wg show %i
133       fwmark) -m addrtype ! --dst-type LOCAL -j REJECT
134
135       The `PostUp' and `PreDown' fields have been added to specify  an  ipta‐
136       bles(8)  command which, when used with interfaces that have a peer that
137       specifies 0.0.0.0/0 as part of the `AllowedIPs',  works  together  with
138       wg-quick's  fwmark  usage  in order to drop all packets that are either
139       not coming out of the tunnel encrypted or not going through the  tunnel
140       itself.  (Note  that this continues to allow most DHCP traffic through,
141       since most DHCP clients make use of  PF_PACKET  sockets,  which  bypass
142       Netfilter.)  When  IPv6  is  in  use, additional similar lines could be
143       added using ip6tables(8).
144
145       Or, perhaps it is desirable to store private keys  in  encrypted  form,
146       such as through use of pass(1):
147
148           PostUp = wg set %i private-key <(pass WireGuard/private-keys/%i)
149
150       For  use  on  a  server,  the  following  is a more complicated example
151       involving multiple peers:
152
153           [Interface]
154           Address = 10.192.122.1/24
155           Address = 10.10.0.1/16
156           SaveConfig = true
157           PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
158           ListenPort = 51820
159
160           [Peer]
161           PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
162           AllowedIPs = 10.192.122.3/32, 10.192.124.1/24
163
164           [Peer]
165           PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0=
166           AllowedIPs = 10.192.122.4/32, 192.168.0.0/16
167
168           [Peer]
169           PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA=
170           AllowedIPs = 10.10.10.230/32
171
172       Notice the two `Address' lines at the top, and that `SaveConfig' is set
173       to  `true',  indicating  that the configuration file should be saved on
174       shutdown using the current status of the interface.
175
176       A combination of the `Table', `PostUp', and  `PreDown'  fields  may  be
177       used for policy routing as well. For example, the following may be used
178       to send SSH traffic (TCP port 22) traffic through the tunnel:
179
180           [Interface]
181           Address = 10.192.122.1/24
182           PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
183           ListenPort = 51820
184           Table = 1234
185           PostUp = ip rule add ipproto tcp dport 22 table 1234
186           PreDown = ip rule delete ipproto tcp dport 22 table 1234
187
188           [Peer]
189           PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
190           AllowedIPs = 0.0.0.0/0
191
192       These configuration files may be placed in any directory,  putting  the
193       desired interface name in the filename:
194
195           # wg-quick up /path/to/wgnet0.conf
196
197       For  convenience,  if  only an interface name is supplied, it automati‐
198       cally chooses a path in `/etc/wireguard/':
199
200           # wg-quick up wgnet0
201
202       This will load the configuration file `/etc/wireguard/wgnet0.conf'.
203
204       The strip command is useful for reloading configuration  files  without
205       disrupting active sessions:
206
207           # wg syncconf wgnet0 <(wg-quick strip wgnet0)
208
209

SEE ALSO

211       wg(8),   ip(8),  ip-link(8),  ip-address(8),  ip-route(8),  ip-rule(8),
212       resolvconf(8).
213
214

AUTHOR

216       wg-quick was written by  Jason  A.  Donenfeld  ⟨Jason@zx2c4.com⟩.   For
217       updates  and more information, a project page is available on the World
218       Wide Web ⟨https://www.wireguard.com/⟩.
219
220
221
222ZX2C4                           2016 January 1                     WG-QUICK(8)
Impressum