pi-hole/docs
1
0
Fork 0
mirror of https://github.com/pi-hole/docs.git synced 2024-12-06 19:27:12 +01:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Improve guide by adding exemplary modified config files in the optional sections and remove the debated highlighting (use plain for all the Wireguard config files)

Browse Source 
Signed-off-by: DL6ER <dl6er@dl6er.de>
This commit is contained in:
DL6ER
2021-01-01 21:53:15 +01:00
parent c1853a9f84
commit 053ee1e72d
5 changed files with 107 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guides/wireguard/client.md
+15 -15
View File
@@ -6,7 +6,7 @@ For each new client, the following steps must be taken. For the sake of simplici
<!-- markdownlint-disable code-block-style -->
??? info "All commands described below at once"
```bash
``` bash
sudo -i
cd /etc/wireguard
umask 077
@@ -40,7 +40,7 @@ For each new client, the following steps must be taken. For the sake of simplici
We generate a key-pair for the client `NAME` (replace accordingly everywhere below):
```bash
``` bash
sudo -i
cd /etc/wireguard
umask 077
@@ -52,7 +52,7 @@ wg genkey | tee "${name}.key" | wg pubkey > "${name}.pub"
We furthermore recommend generating a pre-shared key (PSK) in addition to the keys above. This adds an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography and is mainly for post-quantum resistance. A pre-shared key should be generated for each peer pair and *should not be reused*.
```bash
``` bash
wg genpsk > "${name}.psk"
```
@@ -60,7 +60,7 @@ wg genpsk > "${name}.psk"
Add the new client by running the command:
```bash
``` 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
@@ -74,13 +74,13 @@ echo "AllowedIPs = 10.100.0.2/32, fd08:4711::2/128" >> /etc/wireguard/wg0.conf
Restart your server to load the new client config:
```bash
``` bash
systemctl restart wg-quick@wg0
```
After a restart, the server file should look like:
```bash
``` plain
[Interface]
Address = 10.100.0.1/24, fd08::1/128
ListenPort = 47111
@@ -97,13 +97,13 @@ AllowedIPs = 10.100.0.2/32, fd08:4711::2/128
The command
```bash
``` bash
wg
```
should tell you about your new client:
```plain
``` plain
interface: wg0
public key: XYZ123456ABC= ⬅ Your server's public key will be different
private key: (hidden)
@@ -118,7 +118,7 @@ peer: F+80gbmHVlOrU+es13S18oMEX2g= ⬅ Your peer's public key will be differen
Create a dedicated config file for your new client:
```bash
``` bash
echo "[Interface]" > "${name}.conf"
echo "Address = 10.100.0.2/32, fd08:4711::2/128" >> "${name}.conf" # May need editing
echo "DNS = 10.100.0.1" >> "${name}.conf" # Your Pi-hole's IP
@@ -126,13 +126,13 @@ echo "DNS = 10.100.0.1" >> "${name}.conf" # Your Pi-hol
and add the private key of this client
```bash
``` bash
echo "PrivateKey = $(cat "${name}.key")" >> "${name}.conf"
```
Next, add your server as peer for this client:
```bash
``` plain
[Peer]
AllowedIPs = 10.100.0.0/24, fd08::/64
Endpoint = [your public IP or domain]:47111
@@ -141,7 +141,7 @@ PersistentKeepalive = 25
Then add the public key of the server as well as the PSK for this connection:
```bash
``` bash
echo "PublicKey = $(cat server.pub)" >> "${name}.conf"
echo "PresharedKey = $(cat "${name}.psk")" >> "${name}.conf"
exit
@@ -166,7 +166,7 @@ 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
``` bash
sudo qrencode -t ansiutf8 -r "/etc/wireguard/${name}.conf"
```
@@ -180,13 +180,13 @@ After creating/copying the connection information over to your client, you may u
You can check if your client successfully connected by, once again, running
```plain
``` bash
sudo wg
```
on the server. It should show some traffic for your client if everything works:
```plain
``` plain
interface: wg0
public key: XYZ123456ABC= ⬅ Your server's public key will be different
private key: (hidden)
docs/guides/wireguard/faq.md
+6 -6
View File
@@ -9,13 +9,13 @@ Hostnames cannot be resolved during startup. This may lead to a five minutes del
If the IP changes while the connection is running, resolving the new IP address fails often. Reconnect using
```bash
``` bash
sudo ifdown wg0 && sudo ifup wg0
```
To achieve a permanent solution, one can install a `cron` job which restarts the connection automatically whenever a change is detected. This avoids excessive restarts of the interface. Example script (taken from [Ubuntuusers Wiki](https://wiki.ubuntuusers.de/WireGuard)):
```bash
``` bash
#!/bin/bash
# Check state of wg0 interface
wgstatus=$(wg)
@@ -42,11 +42,11 @@ fi
Store this file as `/home/[user name]/wg-restart.sh` and add it to your `crontab`:
```bash
``` bash
sudo crontab -e
```
```plain
``` plain
*/10 * * * * bash /home/[user name]/wg-restart.sh # Runs the script every 10 minutes
```
@@ -54,7 +54,7 @@ sudo crontab -e
Users of NetworkManager should make sure that it is not managing the WireGuard interface(s). For example, create the configuration file `/etc/NetworkManager/conf.d/unmanaged.conf` with content
```bash
``` bash
[keyfile]
unmanaged-devices=interface-name:wg*
```
@@ -77,7 +77,7 @@ The solution is to use networking software that supports `resolvconf`.
Due to too low MTU (lower than 1280), `wg-quick` may fail to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in the Interface section on the client:
```bash
``` bash
[Interface]
MTU = 1500
```
docs/guides/wireguard/internal.md
+49 -36
View File
@@ -4,7 +4,7 @@
Enable IP forwarding on your server by removing the comments in front of
```bash
``` plain
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1
```
@@ -13,13 +13,13 @@ in the file `/etc/sysctl.d/99-sysctl.conf`
Then apply the new option with the command below.
```bash
``` bash
sudo sysctl -p
```
If you see the options repeated like
```bash
``` plain
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1
```
@@ -30,9 +30,6 @@ A properly configured firewall is ***highly*** recommended for any Internet-faci
## Enable NAT on the server
!!! info "Optional for NAT"
If the server is behind a router and receives traffic via NAT, these iptables rules are not needed.
On your server, add the following to the `[INTERFACE]` section of your `/etc/wireguard/wg0.conf`:
```bash
@@ -40,43 +37,59 @@ 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
```
!!! warning "Substitute interface"
Substitute `eth0` in the preceding lines to match the Internet-facing interface.
!!! warning "**Important:** Substitute interface"
**Without the correct interface name, this will not work!**
??? info "The `PostUp` and `PostDown` options"
`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.
Substitute `eth0` in the preceding lines to match the Internet-facing interface. This may be `ens2p0` or similar on more recent Ubuntu versions (check, e.g., `ip a` for details about your local interfaces).
`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.
??? info "Exemplary server config file with this change"
``` plain
[Interface]
PrivateKey = [your server's private key]
Address = [Wireguard-internal IPs of the server, e.g. 10.100.0.1/24, fd08:4711::1/64]
ListenPort = 47111
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o enp2s0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o enp2s0 -j MASQUERADE
# Android phone
[Peer]
PublicKey = [public key of this client]
PresharedKey = [pre-shared key of this client]
AllowedIPs = [Wireguard-internal IP of this client, e.g., 10.100.0.2/32, fd08:4711::2/128]
# maybe more [Peer] sections for more clients
```
The important change is the extra PostUp` and `PostDown` in the `[Interface]` section.
## Allow clients to access other devices
In our standard configuration, we have configured the clients in such a way that they can only speak to the server. This has to be changed on both the server and the clients.
In our standard configuration, we have configured the clients in such a way that they can only speak to the server. Add the network range of your local network in CIDR notation (e.g., `192.168.2.1 - 192.168.2.254` -> `192.168.2.0/24`) in the `[Peers]` section of all clients you want to have this feature:
### Server side
Change the allowed addresses in your `/etc/wireguard/wg0.conf` from
```bash
[Peer]
AllowedIPs = 10.100.0.1/32, fd08:4711::1/64
```
to
```bash
[Peer]
AllowedIPs = 10.100.0.0/24, fd08:4711::/64, 192.168.2.0/24
```
assuming your internal network is in the IP range `192.168.2.1` - `192.168.2.254`. The change `10.100.0.1/32` to `10.100.0.0/24` also allows your WireGuard peers to see each other.
### Client side
Do the same you did above for the server also in the `[Interface]` section of all clients you want to have this feature:
```bash
``` plain
[Peer]
AllowedIPs = 10.0.0.0/24, fd08:4711::/64, 192.168.2.0/24
```
It is possible to add this only for a few clients, leaving the others isolated to only the Pi-hole server itself.
??? info "Exemplary client config file with this change"
``` plain
[Interface]
PrivateKey = [your client's private key]
Address = [Wireguard-internal IPs of your client, e.g. 10.100.0.2/32, fd08:4711::2/128]
DNS = 10.100.0.1
[Peer]
AllowedIPs = 10.100.0.0/24, fd08::/64, 192.168.2.0/24
Endpoint = [your server's public IP or domain]:47111
PublicKey = [public key of the server]
PresharedKey = [pre-shared key of this client]
PersistentKeepalive = 25
```
The important change is the extra `192.168.2.0/24` at the end of the `[Peer] -> AllowedIPs` entry.
docs/guides/wireguard/route-everything.md
+19 -2
View File
@@ -14,12 +14,29 @@ Rerouting the Internet traffic through your Pi-hole will furthermore cause all o
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 before continuing here.
<!-- 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 your clients's WireGuard config files:
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:
```bash
``` plain
AllowedIPs = 0.0.0.0/0, ::/0
```
??? info "Exemplary client config file with this change"
``` plain
[Interface]
PrivateKey = [your client's private key]
Address = [Wireguard-internal IPs of your client, e.g. 10.100.0.2/32, fd08:4711::2/128]
DNS = 10.100.0.1
[Peer]
AllowedIPs = 0.0.0.0/0, ::/0
Endpoint = [your server's public IP or domain]:47111
PublicKey = [public key of the server]
PresharedKey = [pre-shared key of this client]
PersistentKeepalive = 25
```
The important change is setting the `[Peer] -> AllowedIPs` entry to `0.0.0.0/0, ::/0`
<!-- markdownlint-disable code-block-style -->
!!! warning "Change this setting only on your clients"
Do **not** set this on the server in the `[Interface]` section. WireGuard will automatically take care of setting up [correct routing](https://www.wireguard.com/netns/#routing-all-your-traffic) so that networking still functions on all your clients.
docs/guides/wireguard/server.md
+18 -8
View File
@@ -109,13 +109,13 @@ wg genkey | tee server.key | wg pubkey > server.pub
Create a config file
```bash
``` bash
sudo nano /etc/wireguard/wg0.conf
```
and put the following into it:
```bash
``` plain
[Interface]
Address = 10.100.0.1/24, fd08:4711::1/64
ListenPort = 47111
@@ -123,7 +123,7 @@ ListenPort = 47111
Then run
```bash
``` bash
echo "PrivateKey = $(cat server.key)" >> /etc/wireguard/wg0.conf
exit # Exit the sudo session
```
@@ -138,7 +138,7 @@ If the server is behind NAT, be sure to forward the specified port on which Wire
Register your server `wg0` as:
```bash
``` bash
sudo systemctl enable wg-quick@wg0.service
sudo systemctl daemon-reload
sudo systemctl start wg-quick@wg0
@@ -150,31 +150,41 @@ If successful, you should not see any output.
??? warning "Error: RTNETLINK answers: Operation not supported"
In case you get an error like
```plain
``` plain
RTNETLINK answers: Operation not supported
Unable to access interface: Protocol not supported
```
you should check that the WireGuard kernel module is loaded with the command below:
```bash
``` bash
sudo modprobe wireguard
```
If you get an error saying the module is missing, try reinstalling WireGuard or restart your server and try again. This may happen when the WireGuard server is installed for a more recent kernel than you are currently running. This typically happens when you have neither updated nor restarted your system for a long time.
??? warning "Error: RTNETLINK answers: File exists"
In case you get an error like
``` plain
RTNETLINK answers: File exists
```
you need to check the configured IP addresses (check the CIDR notation). Overlapping IP address ranges cause this error when trying to register a router for an address where a a route already exists. This is meaningful and always an error in your configuration. However, the error message could be more clear about this.
<!-- markdownlint-enable code-block-style -->
## Check everything is running
With the following command, you can check if your `wireguard` server is running:
```bash
``` bash
sudo wg
```
The output should look like the following:
```plain
``` plain
interface: wg0
public key: XYZ123456ABC= ⬅ Your public key will be different
private key: (hidden)