Ubuntu Manpage: wg-quick - set up a WireGuard interface simply

Provided by: wireguard-tools_1.0.20200513-1~20.04.2_amd64

NAME

       wg-quick - set up a WireGuard interface simply

SYNOPSIS

       wg-quick [ up | down | save | strip ] [ CONFIG_FILE | INTERFACE ]

DESCRIPTION

       This  is an extremely simple script for easily bringing up a WireGuard interface, suitable
       for a few common use cases.

       Use up to add and set up an interface, and use down to tear down and remove an  interface.
       Running  up  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  down
       optionally   saves  the  current  configuration,  removes  the  WireGuard  interface,  and
       optionally runs pre/post down scripts. Running save saves the configuration of an existing
       interface  without  bringing  the interface down. Use strip to output a configuration file
       with all wg-quick(8)-specific options removed, suitable for use with wg(8).

       CONFIG_FILE is a configuration file, whose filename is  the  interface  name  followed  by
       `.conf'.   Otherwise,  INTERFACE  is  an  interface  name,  with  configuration  found  at
       `/etc/wireguard/INTERFACE.conf', searched first, followed by distro-specific search paths.

       Generally speaking, this utility is just a simple script that wraps invocations  to  wg(8)
       and  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 wg(8) and ip(8), as usual.

CONFIGURATION

The configuration file adds a few extra configuration values to the format understood by
wg(8) in order to configure additional attributes of an interface. It handles the values
that it understands, and then it passes the remaining ones directly to 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 ip-rule(8) to handle overriding of the default gateway.

The configuration file will be passed directly to wg(8)'s `setconf' sub-command, with the
exception of the following additions to the Interface section, which are handled by this
tool:

• Address — 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.

• DNS — a comma-separated list of IP (v4 or v6) addresses to be set as the
interface's DNS servers, or non-IP hostnames to be set as the interface's DNS
search domains. May be specified multiple times. Upon bringing the interface up,
this runs `resolvconf -a tun.INTERFACE -m 0 -x` and upon bringing it down, this
runs `resolvconf -d tun.INTERFACE`. If these particular invocations of
resolvconf(8) are undesirable, the PostUp and PostDown keys below may be used
instead.

• MTU — 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.

• Table — Controls the routing table to which routes are added. There are two special
values: `off' disables the creation of routes altogether, and `auto' (the default)
adds routes to the default table and enables special handling of default routes.

• PreUp, PostUp, PreDown, PostDown — script snippets which will be executed by
bash(1) before/after setting up/tearing down the interface, most commonly used to
configure custom DNS options or firewall rules. The special string `%i' is expanded
to INTERFACE. Each one may be specified multiple times, in which case the commands
are executed in order.

• SaveConfig — if set to `true', the configuration is saved from the current state of
the interface upon shutdown. Any changes made to the configuration file before the
interface is removed will therefore be overwritten.

Recommended INTERFACE 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,15} will work. So even interface names corresponding to geographic locations
would suffice, such as `cincinnati', `nyc', or `paris', if that's somehow desirable.

EXAMPLES

       These  examples  draw  on the same syntax found for wg(8), and a more complete description
       may be found there. Bold lines below are for options that extend wg(8).

       The following might be used for connecting as a client to a VPN gateway for tunneling  all
       traffic:

           [Interface]
           Address = 10.200.100.8/24
           DNS = 10.200.100.1
           PrivateKey = oK56DE9Ue9zK76rAc8pBl6opph+1v36lm7cXXsQKrQM=

           [Peer]
           PublicKey = GtL7fZc/bLnqZldpVofMCD6hDjrK28SsdLxevJ+qtKU=
           PresharedKey = /UwcSPg38hW/D9Y3tcS1FOV0K1wuURMbS0sesJEP5ak=
           AllowedIPs = 0.0.0.0/0
           Endpoint = demo.wireguard.com:51820

       The  `Address`  field  is added here in order to set up the address for the interface. The
       `DNS` field indicates that a DNS  server  for  the  interface  should  be  configured  via
       resolvconf(8).   The  peer's  allowed  IPs  entry  implies  that  this interface should be
       configured as the default gateway, which this script does.

       Building on the last example, one might attempt the so-called ``kill-switch'', in order to
       prevent  the  flow  of unencrypted packets through the non-WireGuard interfaces, by adding
       the following two lines `PostUp` and `PreDown` lines to the `[Interface]` section:

           PostUp = iptables -I OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m  addrtype
       ! --dst-type LOCAL -j REJECT
           PreDown = iptables -D OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype
       ! --dst-type LOCAL -j REJECT

       The `PostUp' and `PreDown' fields have been added to specify an iptables(8) command which,
       when  used  with  interfaces  that  have  a  peer  that specifies 0.0.0.0/0 as part of the
       `AllowedIPs', works together with wg-quick's fwmark usage in order  to  drop  all  packets
       that  are  either  not  coming out of the tunnel encrypted or not going through the tunnel
       itself. (Note that this continues to allow most DHCP  traffic  through,  since  most  DHCP
       clients  make  use  of  PF_PACKET  sockets,  which bypass Netfilter.) When IPv6 is in use,
       additional similar lines could be added using ip6tables(8).

       Or, perhaps it is desirable to store private keys in encrypted form, such as  through  use
       of pass(1):

           PostUp = wg set %i private-key <(pass WireGuard/private-keys/%i)

       For use on a server, the following is a more complicated example involving multiple peers:

           [Interface]
           Address = 10.192.122.1/24
           Address = 10.10.0.1/16
           SaveConfig = true
           PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
           ListenPort = 51820

           [Peer]
           PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
           AllowedIPs = 10.192.122.3/32, 10.192.124.1/24

           [Peer]
           PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0=
           AllowedIPs = 10.192.122.4/32, 192.168.0.0/16

           [Peer]
           PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA=
           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.

       A  combination  of  the  `Table',  `PostUp',  and  `PreDown' fields may be used for policy
       routing as well. For example, the following may be used to send SSH traffic (TCP port  22)
       traffic through the tunnel:

           [Interface]
           Address = 10.192.122.1/24
           PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
           ListenPort = 51820
           Table = 1234
           PostUp = ip rule add ipproto tcp dport 22 table 1234
           PreDown = ip rule delete ipproto tcp dport 22 table 1234

           [Peer]
           PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
           AllowedIPs = 0.0.0.0/0

       These  configuration  files  may be placed in any directory, putting the desired interface
       name in the filename:

           # wg-quick up /path/to/wgnet0.conf

       For convenience, if only an interface name is supplied, it automatically chooses a path in
       `/etc/wireguard/':

           # wg-quick up wgnet0

       This will load the configuration file `/etc/wireguard/wgnet0.conf'.

       The  strip  command  is useful for reloading configuration files without disrupting active
       sessions:

           # wg addconf wgnet0 <(wg-quick strip wgnet0)

       (Note that the above command will add and update peers but will not remove peers.)

AUTHOR