aad91ae679
Due to concerns with the .io TLD, we are switching to using wireguard.com instead. Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
199 lines
5.9 KiB
Groff
199 lines
5.9 KiB
Groff
.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 tun.%i -m 0 -x\fP
|
|
.br
|
|
\fBPostDown = resolvconf -d tun.%i\fP
|
|
.br
|
|
PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM=
|
|
.br
|
|
|
|
.br
|
|
[Peer]
|
|
.br
|
|
PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU=
|
|
.br
|
|
PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak=
|
|
.br
|
|
AllowedIPs = 0.0.0.0/0
|
|
.br
|
|
Endpoint = demo.wireguard.com: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.com/
|
|
World Wide Web
|
|
.UE .
|