MAN page from openSUSE Tumbleweed wireguard-tools-0.0.20190123-3.1.x86_64.rpm

WG-QUICK

Section: WireGuard (8)
Updated: 2016 January 1
Index

NAME

wg-quick - set up a WireGuard interface simply

SYNOPSIS

wg-quick[up|down|save] [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 removean interface. Running up adds a WireGuard interface, brings up the interface with thesupplied IP addresses, sets up mtu and routes, and optionally runs pre/post up scripts. Running downoptionally saves the current configuration, removes the WireGuard interface, and optionallyruns pre/post down scripts. Running save saves the configuration of an existinginterface without bringing the interface down.

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

Generally speaking, this utility is just a simple script that wraps invocations towg(8)andip(8)in order to set up a WireGuard interface. It is designed for users with simpleneeds, and users with more advanced needs are highly encouraged to use a morespecific tool, a more complete network manager, or otherwise just usewg(8)andip(8),as usual.

CONFIGURATION

The configuration file adds a few extra configuration values to the format understood bywg(8)in order to configure additional attribute of an interface. It handles thevalues that it understands, and then it passes the remaining ones directly towg(8)for further processing.

It infers all routes from the list of peers' allowed IPs, and automatically addsthem to the system routing table. If one of those routes is the default route(0.0.0.0/0 or ::/0), then it usesip-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'sDNS servers. 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 ofresolvconf(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 addressesor the system default route, which is usually a sane choice. However, to manually specifyan MTU to override this automatic discovery, this value may be specified explicitly.

*

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

*

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

*

SaveConfig --- if set to `true', the configuration is saved from the current state of theinterface upon shutdown.

Recommended INTERFACE names include `wg0' or `wgvpn0' or even `wgmgmtlan0'.However, the number at the end is in fact optional, and reallyany free-form string [a-zA-Z0-9_=+.-]{1,15} will work. So even interface names correspondingto geographic locations would suffice, such as `cincinnati', `nyc', or `paris', if that'ssomehow desirable.

EXAMPLES

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

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

    [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` fieldindicates that a DNS server for the interface should be configured viaresolvconf(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 orderto prevent the flow of unencrypted packets through the non-WireGuard interfaces, by adding the followingtwo 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 aniptables(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 thatare either not coming out of the tunnel encrypted or not going through the tunnel itself. (Notethat this continues to allow most DHCP traffic through, since most DHCP clients make use of PF_PACKETsockets, which bypass Netfilter.) When IPv6 is in use, additional similar lines could be added usingip6tables(8).

Or, perhaps it is desirable to store private keys in encrypted form, such as through use ofpass(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', indicatingthat the configuration file should be saved on shutdown using the current status of theinterface.

A combination of the `Table', `PostUp', and `PreDown' fields may be used for policy routingas well. For example, the following may be used to send SSH traffic (TCP port 22) trafficthrough 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 namein 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'.

AUTHOR

wg-quickwas written byJason A. DonenfeldFor updates and more information, a project page is available on theWorld Wide Web

This document was created byman2html,using the manual pages.

WG-QUICK

NAME

SYNOPSIS

DESCRIPTION

CONFIGURATION

EXAMPLES

SEE ALSO

AUTHOR

Index