AWG-QUICK(8) AmneziaWG AWG-QUICK(8) NAME awg-quick - set up a WireGuard interface simply SYNOPSIS awg-quick [ up | down | save | strip | reload ] [ CONFIG_FILE | INTERFACE ] DESCRIPTION This is an extremely simple script for easily bringing up a WireGuard in- terface, 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 inter- face with the supplied IP addresses, sets up mtu and routes, and optionally runs pre/post up scripts. Running down optionally saves the current config- uration, 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 awg-quick(8)-specific options removed, suitable for use with awg(8). CONFIG_FILE is a configuration file, whose filename is the interface name followed by `.conf'. Otherwise, INTERFACE is an interface name, with con- figuration found at `/etc/wireguard/INTERFACE.conf', searched first, fol- lowed by distro-specific search paths. Generally speaking, this utility is just a simple script that wraps invoca- tions to awg(8) and ifconfig(8) in order to set up a AmneziaWG 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 awg(8) and route(8), as usual. CONFIGURATION The configuration file adds a few extra configuration values to the format understood by awg(8) in order to configure additional attributes of an in- terface. It handles the values that it understands, and then it passes the remaining ones directly to awg(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 de- fault route (0.0.0.0/0 or ::/0), then it uses ip-rule(8) to handle overrid- ing of the default gateway. The configuration file will be passed directly to awg(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 (op- tionally 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.INTER- FACE -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 alto- gether, 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 inter- face, 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 exe- cuted 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 there- fore be overwritten. * Description -- will setup interface description visible in ifconfig and SNMP. * UserLand -- enforce to use amnezia-go instead of kernel driver, you can use amnezia-wireguard-go to install it. * Routes -- list of routes for the peer to be installed into FIB - that option provides a way to have AllowedIPs list wider then routes installed. Empty list is allowed. That is useful if routing proto- col will work over the link. But remember that internal wireguard routing will happen according to AllowedIPs anyway. Suggested use in case dynamic route - one interface -> one link. * Monitor default route change -- do not run `route monitor` when there is no need to do anything on default change. That will help to avoid keeping two bashes and one route binaries per interface al- ways. Default value is true. * Track DNS Changes -- if peer endpoint defined as a hostname - peri- odically (timeout in seconds) check if hostname was changed, and if changed update peer endpoint according to new hostname. Quite useful in case of DDNS configurations. Default values is 0, disabled. Recommended INTERFACE names include `amn0' or `awg0'. 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 geo- graphic locations would suffice, such as `cincinnati', `nyc', or `paris', if that's somehow desirable. EXAMPLES These examples draw on the same syntax found for awg(8), and a more com- plete description may be found there. Bold lines below are for options that extend awg(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 im- plies 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 $(awg show %i fw- mark) -m addrtype ! --dst-type LOCAL -j REJECT PreDown = iptables -D OUTPUT ! -o %i -m mark ! --mark $(awg show %i fw- mark) -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 awg-quick's fw- mark 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): PreUp = awg 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 de- sired interface name in the filename: # awg-quick up amn0 or # awg-quick up /path/to/amn0.conf For convenience, if only an interface name is supplied, it automatically chooses a path in `/etc/wireguard/': # awg-quick up amn0 This will load the configuration file `/etc/wireguard/wgnet0.conf'. The strip command is useful for reloading configuration files without dis- rupting active sessions: # awg syncconf amn0 <(awg-quick strip amn) or # awg-quick reload amn0 SEE ALSO awg(8), ifconfig(8), route(8), AUTHOR awg-quick based on wg-quick was written by Jason A. Donenfeld. For updates and more information, a project page is available on the World Wide Web. AWG 2025 August 8 AWG-QUICK(8)
NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION | EXAMPLES | SEE ALSO | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=awg-quick&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>