1WG-QUICK(8) WireGuard WG-QUICK(8)
2
6 wg-quick - set up a WireGuard interface simply
7
10 wg-quick [ up | down | save | strip ] [ CONFIG_FILE | INTERFACE ]
11
14 This is an extremely simple script for easily bringing up a WireGuard
15 interface, suitable for a few common use cases.
16 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 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 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
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 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 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 · 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 · DNS — a comma-separated list of IP (v4 or v6) addresses to be
61 set as the interface's DNS servers. May be specified multiple
62 times. Upon bringing the interface up, this runs `resolvconf -a
63 tun.INTERFACE -m 0 -x` and upon bringing it down, this runs
64 `resolvconf -d tun.INTERFACE`. If these particular invocations
65 of resolvconf(8) are undesirable, the PostUp and PostDown keys
66 below may be used instead.
67 · MTU — if not specified, the MTU is automatically determined from
69 the endpoint addresses or the system default route, which is
70 usually a sane choice. However, to manually specify an MTU to
71 override this automatic discovery, this value may be specified
72 explicitly.
73 · Table — Controls the routing table to which routes are added.
75 There are two special values: `off' disables the creation of
76 routes altogether, and `auto' (the default) adds routes to the
77 default table and enables special handling of default routes.
78 · PreUp, PostUp, PreDown, PostDown — script snippets which will be
80 executed by bash(1) before/after setting up/tearing down the
81 interface, most commonly used to configure custom DNS options or
82 firewall rules. The special string `%i' is expanded to INTER‐
83 FACE. Each one may be specified multiple times, in which case
84 the commands are executed in order.
85 · SaveConfig — if set to `true', the configuration is saved from
87 the current state of the interface upon shutdown. Any changes
88 made to the configuration file before the interface is removed
89 will therefore be overwritten.
90 Recommended INTERFACE names include `wg0' or `wgvpn0' or even `wgmgmt‐
93 lan0'. However, the number at the end is in fact optional, and really
94 any free-form string [a-zA-Z0-9_=+.-]{1,15} will work. So even inter‐
95 face names corresponding to geographic locations would suffice, such as
96 `cincinnati', `nyc', or `paris', if that's somehow desirable.
97
100 These examples draw on the same syntax found for wg(8), and a more com‐
101 plete description may be found there. Bold lines below are for options
102 that extend wg(8).
103 The following might be used for connecting as a client to a VPN gateway
105 for tunneling all traffic:
106 [Interface]
108 Address = 10.200.100.8/24
109 DNS = 10.200.100.1
110 PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM=
111 [Peer]
113 PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU=
114 PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak=
115 AllowedIPs = 0.0.0.0/0
116 Endpoint = demo.wireguard.com:51820
117 The `Address` field is added here in order to set up the address for
119 the interface. The `DNS` field indicates that a DNS server for the
120 interface should be configured via resolvconf(8). The peer's allowed
121 IPs entry implies that this interface should be configured as the
122 default gateway, which this script does.
123 Building on the last example, one might attempt the so-called ``kill-
125 switch'', in order to prevent the flow of unencrypted packets through
126 the non-WireGuard interfaces, by adding the following two lines
127 `PostUp` and `PreDown` lines to the `[Interface]` section:
128 PostUp = iptables -I OUTPUT ! -o %i -m mark ! --mark $(wg show %i
130 fwmark) -m addrtype ! --dst-type LOCAL -j REJECT
131 PreDown = iptables -D OUTPUT ! -o %i -m mark ! --mark $(wg show %i
132 fwmark) -m addrtype ! --dst-type LOCAL -j REJECT
133 The `PostUp' and `PreDown' fields have been added to specify an ipta‐
135 bles(8) command which, when used with interfaces that have a peer that
136 specifies 0.0.0.0/0 as part of the `AllowedIPs', works together with
137 wg-quick's fwmark usage in order to drop all packets that are either
138 not coming out of the tunnel encrypted or not going through the tunnel
139 itself. (Note that this continues to allow most DHCP traffic through,
140 since most DHCP clients make use of PF_PACKET sockets, which bypass
141 Netfilter.) When IPv6 is in use, additional similar lines could be
142 added using ip6tables(8).
143 Or, perhaps it is desirable to store private keys in encrypted form,
145 such as through use of pass(1):
146 PostUp = wg set %i private-key <(pass WireGuard/private-keys/%i)
148 For use on a server, the following is a more complicated example
150 involving multiple peers:
151 [Interface]
153 Address = 10.192.122.1/24
154 Address = 10.10.0.1/16
155 SaveConfig = true
156 PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
157 ListenPort = 51820
158 [Peer]
160 PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
161 AllowedIPs = 10.192.122.3/32, 10.192.124.1/24
162 [Peer]
164 PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0=
165 AllowedIPs = 10.192.122.4/32, 192.168.0.0/16
166 [Peer]
168 PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA=
169 AllowedIPs = 10.10.10.230/32
170 Notice the two `Address' lines at the top, and that `SaveConfig' is set
172 to `true', indicating that the configuration file should be saved on
173 shutdown using the current status of the interface.
174 A combination of the `Table', `PostUp', and `PreDown' fields may be
176 used for policy routing as well. For example, the following may be used
177 to send SSH traffic (TCP port 22) traffic through the tunnel:
178 [Interface]
180 Address = 10.192.122.1/24
181 PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
182 ListenPort = 51820
183 Table = 1234
184 PostUp = ip rule add ipproto tcp dport 22 table 1234
185 PreDown = ip rule delete ipproto tcp dport 22 table 1234
186 [Peer]
188 PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
189 AllowedIPs = 0.0.0.0/0
190 These configuration files may be placed in any directory, putting the
192 desired interface name in the filename:
193 # wg-quick up /path/to/wgnet0.conf
195 For convenience, if only an interface name is supplied, it automati‐
197 cally chooses a path in `/etc/wireguard/':
198 # wg-quick up wgnet0
200 This will load the configuration file `/etc/wireguard/wgnet0.conf'.
202 The strip command is useful for reloading configuration files without
204 disrupting active sessions:
205 # wg addconf wgnet0 <(wg-quick strip wgnet0)
207 (Note that the above command will add and update peers but will not
209 remove peers.)
210
213 wg(8), ip(8), ip-link(8), ip-address(8), ip-route(8), ip-rule(8),
214 resolvconf(8).
215
218 wg-quick was written by Jason A. Donenfeld ⟨Jason@zx2c4.com⟩. For
219 updates and more information, a project page is available on the World
220 Wide Web ⟨https://www.wireguard.com/⟩.
221ZX2C4 2016 January 1 WG-QUICK(8)