Reorganized

FAQ.md

@@ -7,12 +7,93 @@
 
 ## How do I diagnose port forwarding?
 
-### Before you begin
+### Preliminary checks
 
-This guide assumes that the PiVPN installation was successful and you see all [OK] on the `pivpn -d` self check (i.e. the server is working, listening for connections, with firewall rules in place).
+- Confirm that all checks are [OK] using `pivpn -d`.
 
-If your debug log shows some [ERR], you need to solve those first: accept the [Y/n], look through existing issues or open a new issue.
+In our case:
-Instead, if you performed all the following steps and suggestions, again, look through existing issues or open a new issue adding the packet capture (censor client IPs if you want) and the attempted remedies. Remember to follow the ISSUE TEMPLATE.
+
+```
+$ pivpn -d
+[...]
+::::		Self check		 ::::
+:: [OK] IP forwarding is enabled
+:: [OK] Iptables MASQUERADE rule set
+:: [OK] OpenVPN is running
+:: [OK] OpenVPN is enabled (it will automatically start on reboot)
+:: [OK] OpenVPN is listening on port 1194/udp
+=============================================
+[...]
+```
+
+If your debug log shows some [ERR], accept the [Y/n], run `pivpn -u` again and verify that all checks pass. If not, stop here and look up the error (if you get any) among existing issues or open a new issue.
+
+***
+
+- Verify that the server is running.
+  - OpenVPN, restart the server with `sudo systemctl restart openvpn`, run `pivpn -u` and confirm that the snippet of the server log ends with `Initialization Sequence Completed`.
+  - WireGuard, restart the server with `sudo systemctl restart wg-quick@wg0`. Run `lsmod | grep wireguard` and confirm that you get exactly this output (the numbers don't matter).
+
+```
+wireguard             225280  0
+ip6_udp_tunnel         16384  1 wireguard
+udp_tunnel             16384  1 wireguard
+```
+
+***
+
+- Acquire the installation settings using `cat /etc/pivpn/setupVars.conf`.
+
+```
+[...]
+IPv4dev=eth0                  <--- Network interface
+
+IPv4addr=192.168.23.211/24    <--- IP address of the Raspberry Pi at the time of installation
+                                   (only consider the 192.168.23.211 part)
+
+IPv4gw=192.168.23.1           <--- Gateway, you typically go to this IP on a web browser to forward the port
+
+pivpnPROTO=udp                <--- Protocol you need to use in the port forwarding entry
+
+pivpnPORT=1194                <--- Port you need to forward
+
+pivpnHOST=192.0.2.48          <--- Public IP or DNS name your clients will use to connect to the PiVPN
+[...]
+```
+
+***
+
+- Check that the current IP address of the interface `IPv4dev` is the same as `IPv4addr`. You can see the current IP with `ip -f inet address show IPv4dev`.
+
+In our case:
+
+```
+$ ip -f inet address show eth0
+2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
+    `inet 192.168.23.211/24 brd 192.168.23.255 scope global dynamic eth0
+       valid_lft 84694sec preferred_lft 84694sec
+```
+
+Confirmed: `192.168.23.211` is the same as the content of the `IPv4addr` variable.
+
+If it's not the same, go to your router admin webpage and reserve the static IP `IPv4addr` to the MAC address of the `IPv4dev` interface. To show the MAC address: `cat /sys/class/net/IPv4dev/address`. Then reboot the Raspberry Pi.
+
+***
+
+- Check that the current public IP of your connection is the same as `pivpnHOST`. To check the current public IP: `curl -s https://checkip.amazonaws.com`.
+
+In our case:
+
+```
+$ curl -s https://checkip.amazonaws.com
+192.0.2.48
+```
+
+Confirmed: `192.0.2.48` is the same as the content of the `pivpnHOST` variable.
+
+If the IP is different, then update the IP using the [OpenVPN](https://github.com/pivpn/pivpn/wiki/OpenVPN#how-do-i-change-the-public-ipdns-name-of-the-pivpn-after-the-install) or [WireGuard](https://github.com/pivpn/pivpn/wiki/WireGuard#how-do-i-change-the-public-ipdns-name-of-the-pivpn-after-the-install) guide. If your IP changes frequently, the norm on most home connections, consider using a [Dynamic DNS](https://github.com/pivpn/pivpn/wiki#my-isp-doesnt-give-me-a-static-external-ip-address-so-my-servers-ip-address-keeps-changing).
+
+If you are already using a DDNS, and thus `pivpnHOST` contains your domain name, use `dig +short yourdomain.example.com` to check whether the returned IP matches `curl -s https://checkip.amazonaws.com`.
 
 ### Packet capture
 
@@ -25,19 +106,15 @@ Connecting from the same network as the server not only doesn't make sense (you
 From your device, go to https://ipleak.net and check what's your IP address, let's say we have 192.0.2.45.
 
 1. Open a root shell: `sudo -s`
-1. Install tcpdump: `apt install tcpdump -y`
+2. Install tcpdump: `apt install tcpdump -y`
-2. Acquire the installation settings: `cat /etc/pivpn/setupVars.conf`
+3. Run `tcpdump -n -i IPv4dev pivpnPROTO port pivpnPORT` (it will block the terminal but don't worry)
-3. Take note of the values of `IPv4dev`, `pivpnPROTO` and `pivpnPORT`, for example `eth0`, `udp`, `51820`
+4. Try to connect from your device
-3. Run `tcpdump -n -i IPv4dev pivpnPROTO port pivpnPORT`, in our example would be `tcpdump -n -i eth0 udp port 51820` (it will block the terminal but don't worry)
+5. Shortly after you should see some packets being exchanged between your Raspberry Pi and your device
 
-Now you are looking at udp or tcp packets coming to your Raspberry Pi on the port you specified, via the network interface (ethernet or wifi) you chose. The LAN address of the Raspberry Pi is 192.168.23.211.
+In our case:
-
-6. Try to connect from your device.
-7. Shortly after you should see some packets being exchanged between your Raspberry Pi and your device.
-
-Here's a successful conversation:
 
 ```
+# tcpdump -n -i eth0 udp port 1194
 tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
 listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
 10:57:38.952503 IP 192.0.2.45.28050 > 192.168.23.211.51820: UDP, length 32    <--- Your device sent a packet to the Raspberry Pi
@@ -46,6 +123,8 @@ listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
 10:57:59.490185 IP 192.168.23.211.51820 > 192.0.2.45.28050: UDP, length 32
 ```
 
+You are looking at udp or tcp packets coming to your Raspberry Pi on the port you specified, via the network interface (ethernet or wifi) you chose. The example output above is a successful conversation.
+
 Here's an unsuccessful one (no packets reach the Raspberry Pi):
 
 ```
@@ -53,15 +132,14 @@ tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
 listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
 ```
 
-8. Press CTRL-C to stop the capture
+6. Press CTRL-C to stop the capture
-9. Exit the root shell: `exit`
+7. Exit the root shell: `exit`
 
 ### What to do if I see no packets?
 
-- Check your port forwarding, make sure you forwarded the correct PORT, with the correct PROTOCOL, to the correct IP of your Pi. You can see what you chose by looking at `IPv4addr` (without the netmask part, `/24` in most cases), `pivpnPROTO` and `pivpnPORT` inside `/etc/pivpn/setupVars.conf`.
-- Check if the router still assigned the internal IP you chose during the installation. If it changed even though you set up a static IP when installing PiVPN, use DHCP reservation on the router and reserve `IPv4addr`.
 - If you set up PiVPN with ethernet and later switched to wifi, you will have a different IP. Easiest what to fix is to reinstall and pick the new network interface.
-- Check if your ISP uses Carrier-grade NAT. With CGNAT, your router gets a private IP, making port forwarding ineffective. This is mostly the norm if your router connects via 4G/LTE. If that's the case, you need to ask the ISP for a public IP.
+- Check if your ISP uses Carrier-grade NAT (check online). With CGNAT, your router gets a private IP, making port forwarding ineffective. This is mostly the norm if your router connects via 4G/LTE. If that's the case, you need to ask the ISP for a public IP.
-- Check if the IP in your client config matches the public IP of your Pi or that the DDNS is updated. To see the public IP of your Pi, run `curl -s https://checkip.amazonaws.com`.
 - If you see packets coming, but no response from the Pi, it may indicate routing issues, attempts to block the connection (on either side), or poor connectivity. In all cases, try to connect from a different network.
 - You may have misconfigured firewall rules on your Pi, open an issue and add the output of `sudo iptables -S` and `sudo iptables -t nat -S`.
+
+If you performed all the following steps and suggestions, but you still can't connect, open a new issue showing all the steps you followed to troubleshoot. Include the packet capture as well (censor client IPs if you want). Remember to follow the ISSUE TEMPLATE.