wireguard-tools/src/wg-quick.8

.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 mtu and 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
MTU \(em if not specified, the MTU is automatically determined from the endpoint addresses
or the system default route, which is usually a sane choice. However, to manually specify
an MTU to override this automatic discovery, this value may be specified explicitly.
.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 -x\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 = 51820 
.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 .