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, 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 · 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 · 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 · 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 · 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 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
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 The following might be used for connecting as a client to a VPN gateway
106 for tunneling all traffic:
107 [Interface]
109 Address = 10.200.100.8/24
110 DNS = 10.200.100.1
111 PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM=
112 [Peer]
114 PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU=
115 PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak=
116 AllowedIPs = 0.0.0.0/0
117 Endpoint = demo.wireguard.com:51820
118 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 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 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 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 Or, perhaps it is desirable to store private keys in encrypted form,
146 such as through use of pass(1):
147 PostUp = wg set %i private-key <(pass WireGuard/private-keys/%i)
149 For use on a server, the following is a more complicated example
151 involving multiple peers:
152 [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 [Peer]
161 PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
162 AllowedIPs = 10.192.122.3/32, 10.192.124.1/24
163 [Peer]
165 PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0=
166 AllowedIPs = 10.192.122.4/32, 192.168.0.0/16
167 [Peer]
169 PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA=
170 AllowedIPs = 10.10.10.230/32
171 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 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 [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 [Peer]
189 PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
190 AllowedIPs = 0.0.0.0/0
191 These configuration files may be placed in any directory, putting the
193 desired interface name in the filename:
194 # wg-quick up /path/to/wgnet0.conf
196 For convenience, if only an interface name is supplied, it automati‐
198 cally chooses a path in `/etc/wireguard/':
199 # wg-quick up wgnet0
201 This will load the configuration file `/etc/wireguard/wgnet0.conf'.
203 The strip command is useful for reloading configuration files without
205 disrupting active sessions:
206 # wg syncconf wgnet0 <(wg-quick strip wgnet0)
208
211 wg(8), ip(8), ip-link(8), ip-address(8), ip-route(8), ip-rule(8),
212 resolvconf(8).
213
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/⟩.
219ZX2C4 2016 January 1 WG-QUICK(8)