diff options
Diffstat (limited to 'contrib/examples/wg-config/README')
| -rw-r--r-- | contrib/examples/wg-config/README | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/contrib/examples/wg-config/README b/contrib/examples/wg-config/README new file mode 100644 index 0000000..2e594c6 --- /dev/null +++ b/contrib/examples/wg-config/README @@ -0,0 +1,140 @@ +== Installation == + + # make install + +== Usage == + +wg-config is a very simple utility for adding and configuring WireGuard +interfaces using ip(8) and wg(8). + +Usage: wg-config [ add | del ] INTERFACE [arguments...] + + wg-config add INTERFACE --config=CONFIG_FILE [--address=ADDRESS/CIDR...] + [--route=ROUTE/CIDR...] [--no-auto-route-from-allowed-ips] + [--env-file=ENV_FILE] + + The add subcommand adds a new WireGuard interface, INTERFACE, replacing + any existing interfaces of the same name. The --config argument is + required, and its argument is passed to wg(8)'s setconf subcommand. The + --address argument(s) is recommended for this utility to be useful. The + --route argument is purely optional, as by default this utility will + automatically add routes implied by --address and as implied by the + allowed-ip entries inside the --config file. To disable this automatic + route adding, you may use the option entitled --no-auto-route-from-allowed-ips. + + wg-config del INTERFACE [--config=CONFIG_FILE_TO_SAVE] [--env-file=ENV_FILE] + + The del subcommand removes an existing WireGuard interface. If the + optional --config is specified, then the existing configuration is + written out to the file specified, via wg(8)'s showconf subcommand. + +Both `add' and del' take the --env-file=ENV_FILE option. If specified, +the contents of ENV_FILE are imported into wg-config. This can be used to +set variables in a file, instead of needing to pass them on the command +line. The following table shows the relation between the command line +options described above, and variables that may be declared in ENV_FILE: + + --address=A, --address=B, --address=C ADDRESSES=( "A" "B" "C" ) + --route=A, --route=B, --route=C ADDITIONAL_ROUTES=( "A" "B" "C" ) + --config-file=F CONFIG_FILE="F" + echo C > /tmp/F, --config-file=/tmp/F CONFIG_FILE_CONTENTS="C" + --no-auto-route-from-allowed-ips AUTO_ROUTE=0 + +Additionally, ENV_FILE may define the bash functions pre_add, post_add, +pre_del, and post_del, which will be called at their respective times. + + +== Helper Tool == + +tungate is a separate utility, developed originally not explicitly for +WireGuard, which acts as a poor man's way of ensuring 0/1 and 128/1 default +route overrides still work with an endpoint going over the original default +route. It's quite handy, and wg-config makes use of it for dealing with +0.0.0.0/0 routes. At the moment it only supports IPv4, but adding IPv6 +should be pretty easy. + +== Example == + +/etc/wireguard/wg-server.conf: + + [Interface] + PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk= + ListenPort = 41414 + + [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 + +/etc/wireguard/wg-server.env: + + CONFIG_FILE="$(dirname "${BASH_SOURCE[0]}")/wg-server.conf" + ADDRESSES=( 10.192.122.1/34 10.10.0.1/16 ) + +Run at startup: +# wg-config add wgserver0 --env-file=/etc/wireguard/wg-server.env +Run at shutdown: +# wg-config del wgserver0 --env-file=/etc/wireguard/wg-server.env + +== Advanced Example == + +/etc/wireguard/wg-vpn-gateway.conf: + + [Interface] + PrivateKey = 6JiA3fa+NG+x5m6aq7+lxlVaVqVf1mxK6/pDOZdNuXc= + + [Peer] + PublicKey = 6NagfTu+s8+TkEKpxX7pNjJuTf4zYtoJme7iQFYIw0A= + AllowedIPs = 0.0.0.0/0 + Endpoint = demo.wireguard.io:29912 + +/etc/wireguard/wg-vpn-gateway.env: + + [[ $SUBCOMMAND == add ]] && CONFIG_FILE="$(dirname "${BASH_SOURCE[0]}")/demo-vpn.conf" || true + ADDRESSES=( 10.200.100.2/32 ) + post_add() { + printf 'nameserver 10.200.100.1' | cmd resolvconf -a "$INTERFACE" -m 0 + } + post_del() { + cmd resolvconf -d "$INTERFACE" + } + +Run to flip on the VPN: +# wg-config add wgvpn0 --env-file=/etc/wireguard/wg-vpn-gateway.env +The config file is not overwritten on shutdown, due to the conditional in the env file: +# wg-config del wgvpn0 --env-file=/etc/wireguard/wg-vpn-gateway.env + +== Single File Advanced Example == + +/etc/wireguard/wg-vpn-gateway.env: + + CONFIG_FILE_CONTENTS=" + [Interface] + PrivateKey = 6JiA3fa+NG+x5m6aq7+lxlVaVqVf1mxK6/pDOZdNuXc= + + [Peer] + PublicKey = 6NagfTu+s8+TkEKpxX7pNjJuTf4zYtoJme7iQFYIw0A= + AllowedIPs = 0.0.0.0/0 + Endpoint = demo.wireguard.io:29912 + " + + ADDRESSES=( 10.200.100.2/32 ) + + post_add() { + printf 'nameserver 10.200.100.1' | cmd resolvconf -a "$INTERFACE" -m 0 + } + post_del() { + cmd resolvconf -d "$INTERFACE" + } + +Run to flip on the VPN: +# wg-config add wgvpn0 --env-file=/etc/wireguard/wg-vpn-gateway.env +Run to flip off the VPN: +# wg-config del wgvpn0 --env-file=/etc/wireguard/wg-vpn-gateway.env |