From f97210d2ade370bd27a9020cde0c4d4ed7d6aa65 Mon Sep 17 00:00:00 2001 From: Robert Wimmer <2039811+githubixx@users.noreply.github.com> Date: Mon, 20 Jan 2020 21:28:58 +0100 Subject: [PATCH] Update readme (#37) * update README/CHANGELOG * update CHANGELOG --- CHANGELOG.md | 4 ++++ README.md | 36 ++++++++++++++++++++++++++---------- 2 files changed, 30 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a11dd67..d2adaa0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,10 @@ Changelog --------- +**5.0.0** + +- `wireguard_(preup|postdown|preup|predown)` settings are now a list. If more `iptables` commands needs to be specified e.g. then this changes makes it more readable. The commands are executed in order as described in [wg-quick.8](https://git.zx2c4.com/wireguard-tools/about/src/man/wg-quick.8). Also see README for more examples. (contribution by @Madic-) + **4.2.0** - Add support for Fedora (contribution by @ties) diff --git a/README.md b/README.md index acb26ac..fab04eb 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ I used [PeerVPN](https://peervpn.net/) before but that wasn't updated for a whil In general WireGuard is a network tunnel (VPN) for IPv4 and IPv6 that uses UDP. If you need more information about [WireGuard](https://www.wireguard.io/) you can find a good introduction here: [Installing WireGuard, the Modern VPN](https://research.kudelskisecurity.com/2017/06/07/installing-wireguard-the-modern-vpn/). -This role was tested with Ubuntu 18.04 (Bionic Beaver), Debian 9 (Stretch) and Archlinux. It might also work with Ubuntu 16.04 (Xenial Xerus) but haven't tested it. If someone tested it let me please know if it works ;-) +This role was tested with Ubuntu 18.04 (Bionic Beaver), Debian 9 (Stretch), Archlinux, Fedora 31 and CentOS. It might also work with Ubuntu 16.04 (Xenial Xerus) and Debian 10 (Buster) but haven't tested it. If someone tested it let me please know if it works ;-) Versions -------- @@ -17,7 +17,7 @@ I tag every release and try to stay with [semantic versioning](http://semver.org Requirements ------------ -By default port `51820` (protocol UDP) should be accessable from the outside. But you can adjust the port by changing the variable `wireguard_port`. Also IP forwarding needs to be enabled e.g. via `echo 1 > /proc/sys/net/ipv4/ip_forward `. I decided not to implement this task in this Ansible role. IMHO that should be handled elsewhere. You can use my [ansible-role-harden-linux](https://github.com/githubixx/ansible-role-harden-linux) e.g. Besides changing sysctl entries (which you need to enable IP forwarding) it also manages firewall settings among other things. +By default port `51820` (protocol UDP) should be accessable from the outside. But you can adjust the port by changing the variable `wireguard_port`. Also IP forwarding needs to be enabled e.g. via `echo 1 > /proc/sys/net/ipv4/ip_forward `. I decided not to implement this task in this Ansible role. IMHO that should be handled elsewhere. You can use my [ansible-role-harden-linux](https://github.com/githubixx/ansible-role-harden-linux) e.g. Besides changing sysctl entries (which you need to enable IP forwarding) it also manages firewall settings among other things. Nevertheless the `PreUp`, `PreDown`, `PostUp` and `PostDown` hooks may be a good place to do some network related stuff before a WireGuard interface comes up or goes down. Changelog --------- @@ -86,13 +86,28 @@ wireguard_dns: "1.1.1.1" wireguard_fwmark: "1234" wireguard_mtu: "1492" wireguard_table: "5000" -wireguard_preup: "..." -wireguard_predown: "..." -wireguard_postup: "..." -wireguard_postdown: "..." +wireguard_preup: + - ... +wireguard_predown: + - ... +wireguard_postup: + - ... +wireguard_postdown: + - ... wireguard_save_config: "true" ``` +`wireguard_(preup|predown|postup|postdown)` are specified as lists e.g.: + +``` +wireguard_postup: + - iptables -t nat -A POSTROUTING -o ens12 -j MASQUERADE + - iptables -A FORWARD -i %i -j ACCEPT + - iptables -A FORWARD -o %i -j ACCEPT +``` + +If more `iptables` commands needs to be specified e.g. then a list makes it more readable. The commands are executed in order as described in [wg-quick.8](https://git.zx2c4.com/wireguard-tools/about/src/man/wg-quick.8). + `wireguard_address` is required as already mentioned. It's the IP of the interface name defined with `wireguard_interface` variable (`wg0` by default). Every host needs a unique VPN IP of course. If you don't set `wireguard_endpoint` the playbook will use the hostname defined in the `vpn` hosts group (the Ansible inventory hostname). If you set `wireguard_endpoint` to `""` (empty string) that peer won't have a endpoint. That means that this host can only access hosts that have a `wireguard_endpoint`. That's useful for clients that don't expose any services to the VPN and only want to access services on other hosts. So if you only define one host with `wireguard_endpoint` set and all other hosts have `wireguard_endpoint` set to `""` (empty string) that basically means you've only clients besides one which in that case is the WireGuard server. The third possibility is to set `wireguard_endpoint` to some hostname. E.g. if you have different hostnames for the private and public DNS of that host and need different DNS entries for that case setting `wireguard_endpoint` becomes handy. Take for example the IP above: `wireguard_address: "10.8.0.101"`. That's a private IP and I've created a DNS entry for that private IP like `host01.i.domain.tld` (`i` for internal in that case). For the public IP I've created a DNS entry like `host01.p.domain.tld` (`p` for public). The `wireguard_endpoint` needs to be a interface that the other members in the `vpn` group can connect to. So in that case I would set `wireguard_endpoint` to `host01.p.domain.tld` because WireGuard normally needs to be able to connect to the public IP of the other host(s). Here is a litte example for what I use the playbook: I use WireGuard to setup a fully meshed VPN (every host can directly connect to every other host) and run my Kubernetes (K8s) cluster at Hetzner Cloud (but you should be able to use any hoster you want). So the important components like the K8s controller and worker nodes (which includes the pods) only communicate via encrypted WireGuard VPN. Also (as already) mentioned I've two clients. Both have `kubectl` installed and are able to talk to the internal Kubernetes API server by using WireGuard VPN. One of the two clients also exposes a WireGuard endpoint because the Postfix mailserver in the cloud and my internal Postfix needs to be able to talk to each other. I guess that's maybe a not so common use case for WireGuard :D But it shows what's possible. So let me explain the setup which might help you to use this Ansible role. @@ -245,10 +260,10 @@ Example Playbook - wireguard ``` -Example Inventory using 2 different WireGuard interfaces on host multi ----------------------------------------------------------------------- +Example Inventory using two different WireGuard interfaces on host "multi" +-------------------------------------------------------------------------- -This is a complex example using yaml inventory format +This is a complex example using yaml inventory format: ``` vpn1: @@ -273,7 +288,8 @@ vpn1: vpn2: hosts: - multi-wg1: # use a different name, and define ansible_host, to avoid mixing of vars without needing to prefix vars with interface name + # use a different name, and define ansible_host, to avoid mixing of vars without needing to prefix vars with interface name + multi-wg1: ansible_host: multi wireguard_interface: wg1 wireguard_port: 51821 # when using several interface on one host, we must use different ports