pi-hole · NittanySeaLion · Dec 3, 2023 · yubiuser · Mar 9, 2024 · rdwebdesign
diff --git a/docs/guides/vpn/wireguard/client.md b/docs/guides/vpn/wireguard/client.md
@@ -93,18 +93,19 @@ wg genpsk > "${name}.psk"
 
 Add the new client by running the command:
 
+<!-- markdownlint-disable code-block-style -->
+!!! info "Client IP address"
+    Make sure to increment the IP address for each additional client! The command below adds the first client with the IP addresses `10.100.0.2` and `fd08:4711::2/128` (`10.100.0.1` and `fd08:4711::1/128` are the server)
+    The next client could use `10.100.0.3` and `fd08:4711::3/128`
+<!-- markdownlint-disable code-block-style -->
+
 ```bash
 echo "[Peer]" >> /etc/wireguard/wg0.conf
 echo "PublicKey = $(cat "${name}.pub")" >> /etc/wireguard/wg0.conf
 echo "PresharedKey = $(cat "${name}.psk")" >> /etc/wireguard/wg0.conf
 echo "AllowedIPs = 10.100.0.2/32, fd08:4711::2/128" >> /etc/wireguard/wg0.conf
 ```
 
-<!-- markdownlint-disable code-block-style -->
-!!! info "Client IP address"
-    Make sure to increment the IP address for any further client! We add the first client with the IP addresses `10.100.0.2` and `fd08:4711::2/128` in this example (`10.100.0.1` and `fd08:4711::1/128` are the server)
-<!-- markdownlint-disable code-block-style -->
-
 Reload your server config to add the new client:
 
 ```bash
@@ -166,19 +167,19 @@ echo "PrivateKey = $(cat "${name}.key")" >> "${name}.conf"
 
 Next, add your server as peer for this client:
 
-```plain
-[Peer]
-AllowedIPs = 10.100.0.1/32, fd08:4711::1/128
-Endpoint = [your public IP or domain]:47111
-PersistentKeepalive = 25
+```bash
+echo "[Peer]" > "${name}.conf"
+echo "AllowedIPs = 10.100.0.1/32, fd08:4711::1/128" >> "${name}.conf"
+echo "Endpoint = [your public IP or domain]:47111" >> "${name}.conf" # Edit to add your Internet facing device
+echo "PersistentKeepalive = 25" >> "${name}.conf"
 ```
 
 Then add the public key of the server as well as the PSK for this connection:
 
 ```bash
 echo "PublicKey = $(cat server.pub)" >> "${name}.conf"
 echo "PresharedKey = $(cat "${name}.psk")" >> "${name}.conf"
-exit
+# exit here if not using qrencode to copy the client config to the client
 ```
 
 That's it.
@@ -201,13 +202,16 @@ That's it.
 You can now copy the configuration file to your client (if you created the config on the server). If the client is a mobile device such as a phone, `qrencode` can be used to generate a scanable QR code:
 
 ```bash
-sudo qrencode -t ansiutf8 < "/etc/wireguard/${name}.conf"
+qrencode -t ansiutf8 < "/etc/wireguard/${name}.conf"
+exit
 ```
 
 (you may need to install `qrencode` using `sudo apt-get install qrencode`)
 
 You can directly scan this QR code with the official WireGuard app after clicking on the blue plus symbol in the lower right corner.
 
+The `exit` command will clear the variable `${name}`. But you can run `sudo qrencode -t ansiutf8 < "/etc/wireguard/[client_name].conf"` at any time to display the QR code for a particular `client_name`.
+
 ## Connect to your WireGuard VPN
 
 After creating/copying the connection information over to your client, you may use the client you prefer to connect to your system. Mind that setting up auto-start of the WireGuard connection may lead to issues if you are doing this too early (when the system cannot resolve DNS). See our [FAQ](faq.md) for further hints.

diff --git a/docs/guides/vpn/wireguard/internal.md b/docs/guides/vpn/wireguard/internal.md
@@ -26,7 +26,25 @@ net.ipv6.conf.all.forwarding = 1
 
 they were enabled successfully.
 
-A properly configured firewall is ***highly*** recommended for any Internet-facing device. Configuring a firewall (`iptables`, `ufw`, etc.) is not part of this guide.
+A properly configured firewall is ***highly*** recommended for any Internet-facing device. A complete configuration of a firewall (`iptables`, `ufw`, etc.) is not part of this guide.
+
+## Open and close a route from the Wireguard server to the client
+
+<!-- markdownlint-disable code-block-style -->
+!!! warning "**Important:** Substitute interface"
+    **Without the correct interface name, this will not work!**
+
+    Substitute `eth0` in the commands below to enable the NAT to match the Internet-facing interface. This may be `enp2s0` or similar on more recent Ubuntu versions. If you are unsure, you can use `ip a` to find the correct interface name. The interface name is the one that is connected to the Internet.
+
+    If you are using the `nftables` method to enable NAT, you do not need to specify the interface name for the `PostUp` and `Post Down` lines.
+<!-- markdownlint-enable code-block-style -->
+
+The following example can open and close a route for the Wireguard interface in a `ufw` firewall of the WireGuard device. On your server, add the following to the `[INTERFACE]` section of your `/etc/wireguard/wg0.conf`:
+
+```bash
+PostUp = ufw route allow in on eth0 out on wg0
+PreDown = ufw route delete allow in on eth0 out on wg0
+```
 
 ## Enable NAT on the server
 
@@ -50,17 +68,7 @@ PostUp = iptables -w -t nat -A POSTROUTING -o eth0 -j MASQUERADE; ip6tables -w -
 PostDown = iptables -w -t nat -D POSTROUTING -o eth0 -j MASQUERADE; ip6tables -w -t nat -D POSTROUTING -o eth0 -j MASQUERADE
 ```
 
-<!-- markdownlint-disable code-block-style -->
-!!! warning "**Important:** Substitute interface"
-    **Without the correct interface name, this will not work!**
-
-    Substitute `eth0` in the preceding lines to match the Internet-facing interface. This may be `enp2s0` or similar on more recent Ubuntu versions. If you are unsure, you can use `ip a` to find the correct interface name. The interface name is the one that is connected to the Internet.
-
-    If you are using the `nftables` method, you do not need to specify the interface name in the `PostUp` and `PostDown` lines.
-<!-- markdownlint-enable code-block-style -->
-
-`PostUp` and `PostDown` defines steps to be run after the interface is turned on or off, respectively. In this case, iptables is used to set Linux IP masquerade rules to allow all the clients to share the server’s IPv4 and IPv6 address.
-The rules will then be cleared once the tunnel is down.
+`PostUp`, `PreDown`  and `PostDown` defines steps to be run after the interface is turned on or off, respectively. In this case, the rules are used to set Linux IP masquerade rules to allow all the clients to share the server’s IPv4 and IPv6 address. The rules will then be cleared once the tunnel is down.
 
 <!-- markdownlint-disable code-block-style -->
 ??? info "Exemplary server config file with this change"
@@ -70,7 +78,9 @@ The rules will then be cleared once the tunnel is down.
     Address = [Wireguard-internal IPs of the server, e.g. 10.100.0.1/24, fd08:4711::1/64]
     ListenPort = 47111
 
+    PostUp = ufw route allow in on eth0 out on wg0
     PostUp = nft add table ip wireguard; nft add chain ip wireguard wireguard_chain {type nat hook postrouting priority srcnat\; policy accept\;}; nft add rule ip wireguard wireguard_chain counter packets 0 bytes 0 masquerade; nft add table ip6 wireguard; nft add chain ip6 wireguard wireguard_chain {type nat hook postrouting priority srcnat\; policy accept\;}; nft add rule ip6 wireguard wireguard_chain counter packets 0 bytes 0 masquerade
+    PreDown = ufw route delete allow in on eth0 out on wg0
     PostDown = nft delete table ip wireguard; nft delete table ip6 wireguard
 
     # Android phone
@@ -82,7 +92,7 @@ The rules will then be cleared once the tunnel is down.
     # maybe more [Peer] sections for more clients
     ```
 
-    The important change is the extra `PostUp` and `PostDown` in the `[Interface]` section.
+    The important change is the extra `PostUp`, `PreDown` and `PostDown` portions in the `[Interface]` section.
 <!-- markdownlint-enable code-block-style -->
 ## Allow clients to access other devices
 

diff --git a/docs/guides/vpn/wireguard/route-everything.md b/docs/guides/vpn/wireguard/route-everything.md
@@ -1,5 +1,12 @@
 # Route the entire Internet traffic through the WireGuard tunnel
 
+<!-- markdownlint-disable code-block-style -->
+!!! warning "Ensure you're already forwarding traffic"
+    The following assumes you have already prepared your Pi-hole for [IP forwarding](internal.md#enable-ip-forwarding-on-the-server) and [enabled NAT](internal.md#enable-nat-on-the-server). If this is not the case, follow the steps [over there](internal.md) before continuing here.
+
+    **If you haven't done this, your clients will apparently have no Internet connection whilst local connections may still work.** This is a hard to debug situation so please ensure you have everything set up to avoid hours of troubleshooting.
+<!-- markdownlint-enable code-block-style -->
+
 Routing your entire Internet traffic is **optional**, however, it can be advantageous in cases where you are expecting eavesdropping on the network. This may not only happen in insecure open Wi-Fi networks (airports, hotels, trains, etc.) but also in encrypted Wi-Fi networks where the creator of the network can monitor client activity.
 
 Rerouting the Internet traffic through your Pi-hole will furthermore cause all of your Internet traffic to reach the Internet from the place where your WireGuard server is located. This can be used to obfuscate your real location as well as to be allowed to access geo-blocked content, e.g., when your Pi-hole is located in Germany but you are traveling in the United States. If you want to access a page only accessible from within Germany (like the live-broadcast of Tagesschau, etc.), this will typically not work. However, if you route your entire Internet through your Pi-hole, your network traffic will originate from Germany, allowing you to watch the content.
@@ -9,12 +16,6 @@ Rerouting the Internet traffic through your Pi-hole will furthermore cause all o
     Instead of editing your existing configuration, you can easily add a new one with the modified `AllowedIPs` line as above. This will give you two tunnel variants and you decide - at any time from mobile - which variant you want. The one with only the DNS traffic being safely forwarded to your Pi-hole or the variant where your entire Internet traffic is encrypted and sent through your Pi-hole. You can choose at any time which is the best solution in your current situation (e.g., trusted network, unencrypted airport Wi-Fi, etc.).
 <!-- markdownlint-enable code-block-style -->
 
-<!-- markdownlint-disable code-block-style -->
-!!! warning "Ensure you're already forwarding traffic"
-    The following assumes you have already prepared your Pi-hole for [IP forwarding](internal.md#enable-ip-forwarding-on-the-server) and [enabled NAT](internal.md#enable-nat-on-the-server). If this is not the case, follow the steps [over there](internal.md) before continuing here.
-
-    **If you haven't done this, your clients will apparently have no Internet connection whilst local connections may still work.** This is a hard to debug situation so please ensure you have everything set up to avoid hours of troubleshooting.
-<!-- markdownlint-enable code-block-style -->
 
 To route all traffic through the tunnel to a specific peer, add the default route (`0.0.0.0/0` for IPv4 and `::/0`for IPv6) to `AllowedIPs` in the `[Peer]` section of your clients's WireGuard config files:
 

diff --git a/docs/guides/vpn/wireguard/server.md b/docs/guides/vpn/wireguard/server.md
@@ -134,11 +134,10 @@ to copy the server's private key into your config file.
 
 ## Forward port on your router
 
-If the server is behind a device, e.g., a router that is doing NAT, be sure to forward the specified port on which WireGuard will be running (for this example, `47111/UDP`) from the router to the WireGuard server.
+If the server is behind a device, e.g., a router with a firewall that is doing NAT, be sure to forward the specified port on which WireGuard will be running (for this example, `47111/UDP`) from the router to the WireGuard server. A proper port forwarding rule would act on UDP packets destined for the device's public IP address on the WireGuard port and forward them to the IP address of the WireGuard server, such as the Pi-hole's IP address when WireGuard is running on the Pi-hole device.
 
 ??? info "NAT: Network address translation"
-    Network address translation modifies network packages. Incoming connection requests have their destination address rewritten to a different one.
-    NAT involves more than just changing the IP addresses. For instance, when mapping address `1.2.3.4` to `5.6.7.8`, there is no need to add a rule to do the reverse translation. A `netfilter` system called `conntrack` recognizes packets that are replies to an existing connection. Each connection has its own NAT state attached to it. The reverse translation is done automatically.
+    Network address translation modifies network packages. Incoming connection requests have their destination address rewritten to a different one. NAT involves more than just changing the IP addresses. For instance, when mapping address `1.2.3.4` to `5.6.7.8`, there is no need to add a rule to do the reverse translation. A `netfilter` system called `conntrack` recognizes packets that are replies to an existing connection. Each connection has its own NAT state attached to it. The reverse translation is done automatically.
 
 ## Set up a domain name for your router
 
@@ -173,6 +172,19 @@ There are many excellent guides and a lot of services offer this for free (with
 
 You can either use the methods the corresponding providers recommend or use existing DynDNS solutions inbuilt in your router (if available). Most providers are compatible with, e.g., the popular Fritz!Box routers ([EN](https://en.avm.de/service/fritzbox/fritzbox-4040/knowledge-base/publication/show/30_Setting-up-dynamic-DNS-in-the-FRITZ-Box/) / [DE](https://avm.de/service/fritzbox/fritzbox-7590/wissensdatenbank/publication/show/30_Dynamic-DNS-in-FRITZ-Box-einrichten/)).
 
+## Update `unbound`
+
+If your Pi-hole setup uses a public upstream DNS server, such as OpenDNS, Cloudfare, or Google DNS, no modifications are needed and you may skip to starting the server.
+
+But if you are using `unbound` to provide a recursive DNS server solution based on the Pi-hole's DNS guide, it may be necessary to modify the `unbound` configuration file to allow `unbound` to respond to local DNS requests. To do so, add a line `access-control: [local network subnet] allow` into `unbound`'s pi-hole.conf file and restarting unbound. For example, if your local network subnet hosting the Pi-hole device is 192.168.1.0/24:
+
+```bash
+sudo -i
+echo "access-control: 192.168.1.0/24 allow" >> /etc/unbound/unbound.conf.d/pi-hole.conf
+systemctl restart unbound
+exit
+```
+
 ## Start the server
 
 Register your server `wg0` as: