wireguard-tools/contrib/wg-config
Jason A. Donenfeld 87abf354f1 wg-config: use ip rules instead of tungate
Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
2016-12-30 17:50:19 +01:00
..
Makefile wg-config: use ip rules instead of tungate 2016-12-30 17:50:19 +01:00
README wg-config: use ip rules instead of tungate 2016-12-30 17:50:19 +01:00
wg-config wg-config: use ip rules instead of tungate 2016-12-30 17:50:19 +01:00

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.

== Basic Example ==

This basic example might be used by a server.

/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

== Single File Advanced Example ==

This type of configuration might be desirable for a personal access gateway
VPN, connecting to a server like in the example above.

/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

== Advanced Example ==

This achieves the same as the above, but with an external file. It only sets the
configuration file when the subcommand is add, to prevent it from being overwritten.
The above is much simpler and probably preferred, but this example shows how powerful
the tool can be.

/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