diff options
Diffstat (limited to 'src/tools/wg-quick.8')
| -rw-r--r-- | src/tools/wg-quick.8 | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/src/tools/wg-quick.8 b/src/tools/wg-quick.8 new file mode 100644 index 0000000..2425926 --- /dev/null +++ b/src/tools/wg-quick.8 @@ -0,0 +1,194 @@ +.TH WG-QUICK 8 "2016 January 1" ZX2C4 "WireGuard" + +.SH NAME +wg-quick - set up a WireGuard interface simply + +.SH SYNOPSIS +.B wg-quick +[ +.I up +| +.I down +] [ +.I CONFIG_FILE +| +.I INTERFACE +] + +.SH DESCRIPTION + +This is an extremely simple script for easily bringing up a WireGuard interface, +suitable for a few common use cases. + +Use \fIup\fP to add and set up an interface, and use \fIdown\fP to tear down and remove +an interface. Running \fIup\fP adds a WireGuard interface, brings up the interface with the +supplied IP addresses, sets up routes, and optionally runs pre/post up scripts. Running \fIdown\fP +optionally saves the current configuration, removes the WireGuard interface, and optionally +runs pre/post down scripts. + +\fICONFIG_FILE\fP is a configuration file, whose filename is the interface name +followed by `.conf'. Otherwise, \fIINTERFACE\fP is an interface name, with configuration +found at `/etc/wireguard/\fIINTERFACE\fP.conf'. + +Generally speaking, this utility is just a simple script that wraps invocations to +.BR wg (8) +and +.BR ip (8) +in order to set up a WireGuard interface. It is designed for users with simple +needs, and users with more advanced needs are highly encouraged to use a more +specific tool, a more complete network manager, or otherwise just use +.BR wg (8) +and +.BR ip (8), +as usual. + +.SH CONFIGURATION + +The configuration file adds a few extra configuration values to the format understood by +.BR wg (8) +in order to configure additional attribute of an interface. It handles the +values that it understands, and then it passes the remaining ones directly to +.BR wg (8) +for further processing. + +It infers all routes from the list of peers' allowed IPs, and automatically adds +them to the system routing table. If one of those routes is the default route +(0.0.0.0/0 or ::/0), then it uses +.BR ip-rule (8) +to handle overriding of the default gateway. + +The configuration file will be passed directly to \fBwg\fP(8)'s `setconf' +sub-command, with the exception of the following additions to the \fIInterface\fP section, +which are handled by this tool: + +.IP \(bu +Address \(em a comma-separated list of ip (v4 or v6) addresses (optionally with CIDR masks) +to be assigned to the interface. May be specified multiple times. +.IP \(bu +PreUp, PostUp, PreDown, PostDown \(em script snippets which will be executed by +.BR bash (1) +before/after setting up/tearing down the interface, most commonly used +to configure DNS. The special string `%i' is expanded to \fIINTERFACE\fP. +.IP \(bu +SaveConfig \(em if set to `true', the configuration is saved from the current state of the +interface upon shutdown. + +.P +Recommended \fIINTERFACE\fP names include `wg0' or `wgvpn0' or even `wgmgmtlan0'. +However, the number at the end is in fact optional, and really +any free-form string [a-zA-Z0-9_=+.-]{1,16} will work. So even interface names corresponding +to geographic locations would suffice, such as `cincinnati', `nyc', or `paris', if that's +somehow desirable. + +.SH EXAMPLES + +These examples draw on the same syntax found for +.BR wg (8), +and a more complete description may be found there. Bold lines below are for options that extend +.BR wg (8). + +The following might be used for connecting as a client to a VPN gateway for tunneling all +traffic: + + [Interface] +.br + \fBAddress = 10.200.100.8/24\fP +.br + \fBPostUp = echo nameserver 10.200.100.1 | resolvconf -a %i -m 0\fP +.br + \fBPostDown = resolvconf -d %i\fP +.br + PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM= +.br + PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak= +.br + +.br + [Peer] +.br + PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU= +.br + AllowedIPs = 0.0.0.0/0 +.br + Endpoint = demo.wireguard.io:51820 +.br + +Notice that the `PostUp` and `PostDown` commands are used here to configure DNS using +.BR resolvconf (8), +which is one of the many options for DNS configuration. The `Address` field is added +here in order to set up the address for the interface. The peer's allowed IPs entry +implies that this interface should be configured as the default gateway, which this +script does. + +Here is a more complicated example, fit for usage on a server: + + [Interface] +.br + \fBAddress = 10.192.122.1/24\fP +.br + \fBAddress = 10.10.0.1/16\fP +.br + \fBSaveConfig = true\fP +.br + PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk= +.br + ListenPort = 41414 +.br + +.br + [Peer] +.br + PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg= +.br + AllowedIPs = 10.192.122.3/32, 10.192.124.1/24 +.br + +.br + [Peer] +.br + PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0= +.br + AllowedIPs = 10.192.122.4/32, 192.168.0.0/16 +.br + +.br + [Peer] +.br + PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA= +.br + AllowedIPs = 10.10.10.230/32 + +Notice the two `Address' lines at the top, and that `SaveConfig' is set to `true', indicating +that the configuration file should be saved on shutdown using the current status of the +interface. + +These configuration files may be placed in any directory, putting the desired interface name +in the filename: + +\fB # wg-quick up /path/to/wgnet0.conf\fP + +For convienence, if only an interface name is supplied, it automatically chooses a path in +`/etc/wireguard/': + +\fB # wg-quick up wgnet0\fP + +This will load the configuration file `/etc/wireguard/wgnet0.conf'. + +.SH SEE ALSO +.BR wg (8), +.BR ip (8), +.BR ip-link (8), +.BR ip-address (8), +.BR ip-route (8), +.BR ip-rule (8). + +.SH AUTHOR +.B wg-quick +was written by +.MT Jason@zx2c4.com +Jason A. Donenfeld +.ME . +For updates and more information, a project page is available on the +.UR https://\:www.wireguard.io/ +World Wide Web +.UE . |