wireguard-tools/contrib/wg-config/README

== 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