From 0249fac42beff3d5bc6d68850a1ac5bdd30a92f9 Mon Sep 17 00:00:00 2001
From: Nils Cant <nils@vargen.io>
Date: Tue, 23 Jun 2020 14:05:23 +0200
Subject: [PATCH] first commit

---
 README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f814cad
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# Wireguard ansible role
+
+This role configures a host to act as a wireguard (default) gateway, supporting dual stack ipv4/ipv6.
+It is only tested on Debian 10 but also works on a raspberry pi.
+
+The role uses ndppd to proxy IPv6 neighbour requests, so you do not need a routed IPv6 range.
+
+## Prerequisites
+
+* Debian 10 or Raspberry Pi OS 10 for the gateway host
+* Host has dual stack networking configured
+* Host has both A and AAAA dns records
+* Kernel headers installed for your currently running kernel (raspberrypi-kernel-headers, linux-headers-cloud-amd64, ...)
+* If your device is behind a NAT router, have UDP/51820 forwarded on the edge gateway
+
+## Example playbook
+
+(Do not use the example keys)
+
+```
+- host: rpi
+  roles: 
+    - role: wireguard-nftables
+      vars:
+        wireguard_peers:
+          - publickey: Y+UE7yK4qbkssZUITh0LKTeqG6XhaPXmXSWmFfSNlAM=
+            presharedkey: WLJH/t9dNn36mAyyR57ZWGkb4azjxcgX5lVVpjYJimc=
+            allowedips: ["10.0.0.2/32" ,"2a02:XXXX:XXXX:7d00::2/128"]`
+  
+```
+
+## Configuring clients
+
+Install wireguard on your client.
+
+Generate a private key on your client:
+```
+wg genkey > wg.key
+```
+
+Calculate the public key:
+```
+cat wg.key | wg pubkey
+Y+UE7yK4qbkssZUITh0LKTeqG6XhaPXmXSWmFfSNlAM=
+```
+
+Generate a new shared key (Optional)
+```
+wg genkey
+WLJH/t9dNn36mAyyR57ZWGkb4azjxcgX5lVVpjYJimc=
+```
+
+Run the playbook with a new peer configuration:
+```
+- publickey: Y+UE7yK4qbkssZUITh0LKTeqG6XhaPXmXSWmFfSNlAM=
+  presharedkey: WLJH/t9dNn36mAyyR57ZWGkb4azjxcgX5lVVpjYJimc=
+  allowedips: ["10.0.0.2/32" ,"2a02:XXXX:XXXX:7d00::2/128"]`
+```
+
+The role will generate a private key on the server in /etc/wireguard. Calculate the public key from it:
+```
+cat /etc/wireguard/wg0.key | wg pubkey
+6MnDIYj6MhI9Vic6SnbQ0GfObuYceKTADJuAmNoS9UY=
+```
+
+Create a configuration file on the client in /etc/wireguard, using:
+
+* The clients private key
+* The gateways public key
+* The preshared key
+
+```
+[Interface]
+PrivateKey = CEWE+IXpSUZbTSPPrQiQYeYo2E3XBm6xCmjQUzklA2k=
+ListenPort = 51820
+Address = 10.0.0.2/32, 2a02:XXXX:XXXX:7d00::2/128
+
+[Peer]
+PublicKey = 6MnDIYj6MhI9Vic6SnbQ0GfObuYceKTADJuAmNoS9UY=
+PresharedKey = WLJH/t9dNn36mAyyR57ZWGkb4azjxcgX5lVVpjYJimc=
+Endpoint = wg.my-domain.org:51820
+AllowedIPs = 0.0.0.0/0,::0/0
+```
+
+Use wg-quick to bring up the tunnel (Asuming the configurion in /etc/wireguard/wg0.conf)
+
+```
+wg-quick up wg0
+```
+
+Disconnect:
+```
+wg-quick down wg0
+```
+## Choosing Client IP addresses for peers (clients)
+
+### IPv4
+Pick any RFC1918 ipv4 IP that does not cause conflicts for you. (nftables configures IP masquerading)
+
+### IPv6
+Choose any IP that is valid on the same network as your gateway device.
+When on a network using stateless autoconfiguration, you're pretty safe picking something in the beginning of your range. (If your device has IP 2a02:XXXX:XXXX:7d00:ba27:ebff:fe7e:d22a/64, 2a02:XXXX:XXXX:7d00::2/128 is unlikely to cause a conflict)
+
+VPS providers like Digital Ocean may limit the amount of IPv6 addresses you are allowed to use, so be sure to choose addresses that are in the allowed range. 
+