⚓️ Add test_vpn.sh and make the fleet sturdier: healthcheck for Gluetun, dependencies for VPN-bound crew

Author: scottgigawatt

.vscode/settings.json

@@ -35,9 +35,12 @@
         "goin",
         "guidin",
         "handlin",
+        "healthcheck",
+        "healthchecks",
         "helpin",
         "holdin",
         "IPAM",
+        "IPINFO",
         "keepin",
         "linebreak",
         "linkify",

Makefile

@@ -46,11 +46,9 @@ COMPOSE_UP_OPTIONS         ?= --force-recreate --pull always --detach
 COMPOSE_LOGS_OPTIONS       ?= --follow
 
 #
-# Testing options
+# Testing commands
 #
-DOCKER_VPN_CONTAINER  ?= $(COMPOSE_GLUETUN_SERVICE)-latest
-DOCKER_VPN_TEST_IMAGE ?= alpine:3.18
-DOCKER_VPN_TEST_CMD   ?= sh -c "apk add wget && wget -qO- https://ipinfo.io"
+DOCKER_VPN_TEST_CMD ?= sh scripts/test_vpn.sh
 
 #
 # Build dependencies
@@ -130,7 +128,7 @@ $(START): $(BUILD_DEPENDS)
 # $(TEST_VPN): Obtains the VPN IP address and ensure the connection is working.
 #
 $(TEST_VPN):
-	docker run --rm --network=container:$(DOCKER_VPN_CONTAINER) $(DOCKER_VPN_TEST_IMAGE) $(DOCKER_VPN_TEST_CMD)
+	$(DOCKER_VPN_TEST_CMD)
 
 #
 # $(CONFIG): Renders the actual data model to be applied on the Docker Engine.

README.md

@@ -119,18 +119,38 @@ To confirm yer VPN sails be catchin' wind:
 
 ```bash
 ❯ make test-vpn
-docker run --rm --network=container:gluetun-latest alpine:3.18 sh -c "apk add wget && wget -qO- https://ipinfo.io"
+sh scripts/test_vpn.sh
+Running VPN container test...
+Step 1: Running Docker container with VPN network:
+docker run --rm --network=container:gluetun-latest alpine:latest sh -c 'apk add --no-cache wget >/dev/null 2>&1 && wget -qO- https://ipinfo.io'
+Step 2: Received container response:
 {
-  "ip": "172.16.0.42",
+  "ip": "172.16.88.88",
   "city": "Tortuga",
-  "region": "Caribbean",
-  "country": "High Seas",
-  "loc": "13.4443,-144.7937",
-  "org": "Black Pearl Privateers",
-  "postal": "ARR123",
-  "timezone": "Rum/Somewhere",
-  "readme": "https://ipinfo.io/blackpearl"
+  "region": "Rum Islands",
+  "country": "XP",
+  "loc": "21.4200,-71.1419",
+  "org": "AS7777 The Jolly Rogers",
+  "postal": "00000",
+  "timezone": "Ocean/HighSeas",
+  "readme": "https://ipinfo.io/missingauth"
 }
+Step 3: Getting host IP info from ipinfo.io...
+Step 4: Received host response:
+{
+  "ip": "10.42.42.42",
+  "hostname": "flagship.plundarr.local",
+  "city": "Port Royal",
+  "region": "Skull Coast",
+  "country": "XP",
+  "loc": "17.9355,-76.8419",
+  "org": "AS1492 Blackbeard’s Backbone Ltd.",
+  "postal": "99999",
+  "timezone": "Ocean/SkullBay",
+  "readme": "https://ipinfo.io/missingauth"
+}
+Step 5: Comparing container and host IPs...
+VPN is active. Container IP: 172.16.88.88 (Tortuga, Rum Islands XP), Host IP: 10.42.42.42 (Port Royal, Skull Coast XP).
 ```
 
 > [!WARNING]

docker-compose.yml

@@ -152,6 +152,14 @@ services:
     volumes:
       - ${GLUETUN_CONFIG_PATH}:/gluetun:rw  # Configuration files including WireGuard config at gluetun/wireguard/wg0.conf
 
+    # Define container healthcheck to verify VPN connectivity
+    healthcheck:
+      test: ["CMD-SHELL", "curl -s --max-time 10 https://ipinfo.io | grep -q 'ip'"]  # Check if public IP is reachable
+      interval: ${GLUETUN_HEALTHCHECK_INTERVAL}                                      # Run the check at this interval
+      timeout: ${GLUETUN_HEALTHCHECK_TIMEOUT}                                        # Fail if it exceeds this duration
+      start_period: ${GLUETUN_HEALTHCHECK_START_PERIOD}                              # Grace period before checks start
+      retries: 5                                                                     # Mark as unhealthy after 5 failures
+
     # Specify container service dependencies
     depends_on:
       privateerr:                                  # Depends on privateer to generate the WireGuard config
@@ -194,8 +202,10 @@ services:
 
     # Specify container service dependencies
     depends_on:
-      - gluetun
-      - flaresolverr
+      gluetun:
+        condition: service_healthy  # Wait until Gluetun reports healthy VPN connection
+      flaresolverr:
+        condition: service_started  # Ensure FlareSolverr is started
 
   #
   # Define the 'qbittorrent' service for managing torrents
@@ -212,6 +222,11 @@ services:
       - ${QBITTORRENT_CONFIG_PATH}:/config:rw  # Configuration files
       - ${HOST_DOWNLOADS_PATH}:/downloads:rw   # Location of download managers output directory
 
+    # Specify container service dependencies
+    depends_on:
+      gluetun:
+        condition: service_healthy  # Wait until Gluetun reports healthy VPN connection
+
   #
   # Define the 'radarr' service for managing movies
   #
@@ -230,9 +245,12 @@ services:
 
     # Specify container service dependencies
     depends_on:
-      - gluetun
-      - prowlarr
-      - qbittorrent
+      gluetun:
+        condition: service_healthy  # Wait until Gluetun reports healthy VPN connection
+      prowlarr:
+        condition: service_started  # Ensure Prowlarr is started
+      qbittorrent:
+        condition: service_started  # Ensure qBittorrent is started
 
   #
   # Define the 'sonarr' service for managing tv shows
@@ -252,9 +270,12 @@ services:
 
     # Specify container service dependencies
     depends_on:
-      - gluetun
-      - prowlarr
-      - qbittorrent
+      gluetun:
+        condition: service_healthy  # Wait until Gluetun reports healthy VPN connection
+      prowlarr:
+        condition: service_started  # Ensure Prowlarr is started
+      qbittorrent:
+        condition: service_started  # Ensure qBittorrent is started
 
   #
   # Define the 'bazarr' service for managing subtitles
@@ -274,8 +295,12 @@ services:
 
     # Specify container service dependencies
     depends_on:
-      - sonarr
-      - radarr
+      gluetun:
+        condition: service_healthy  # Wait until Gluetun reports healthy VPN connection
+      sonarr:
+        condition: service_started  # Ensure Sonarr is started
+      radarr:
+        condition: service_started  # Ensure Radarr is started
 
   #
   # Define the 'readarr' service for managing ebooks
@@ -295,9 +320,12 @@ services:
 
     # Specify container service dependencies
     depends_on:
-      - gluetun
-      - prowlarr
-      - qbittorrent
+      gluetun:
+        condition: service_healthy  # Wait until Gluetun reports healthy VPN connection
+      prowlarr:
+        condition: service_started  # Ensure Prowlarr is started
+      qbittorrent:
+        condition: service_started  # Ensure qBittorrent is started
 
   #
   # Define the 'overseerr' service for managing media library requests
@@ -422,10 +450,14 @@ services:
 
     # Specify container service dependencies
     depends_on:
-      - gluetun
-      - sonarr
-      - radarr
-      - qbittorrent
+      gluetun:
+        condition: service_healthy  # Wait until Gluetun reports healthy VPN connection
+      sonarr:
+        condition: service_started  # Ensure Sonarr is started
+      radarr:
+        condition: service_started  # Ensure Radarr is started
+      qbittorrent:
+        condition: service_started  # Ensure qBittorrent is started
 
   #
   # Define the 'speedtest-tracker' service for tracking internet speeds

example.env

@@ -71,6 +71,9 @@ GLUETUN_TAG="${GLUETUN_TAG:-latest}"
 GLUETUN_VPN_SERVICE_PROVIDER="${GLUETUN_VPN_SERVICE_PROVIDER:-custom}"
 GLUETUN_VPN_TYPE="${GLUETUN_VPN_TYPE:-wireguard}"
 GLUETUN_CONFIG_PATH="${GLUETUN_CONFIG_PATH:-./config/gluetun}"
+GLUETUN_HEALTHCHECK_INTERVAL="${GLUETUN_HEALTHCHECK_INTERVAL:-10s}"
+GLUETUN_HEALTHCHECK_TIMEOUT="${GLUETUN_HEALTHCHECK_TIMEOUT:-10s}"
+GLUETUN_HEALTHCHECK_START_PERIOD="${GLUETUN_HEALTHCHECK_START_PERIOD:-10s}"
 
 #
 # Flaresolverr environment variables

scripts/README.md

@@ -49,6 +49,8 @@ To ensure ye script be running on boot, follow these steps, ye salty dogs:
 
     - Click **OK** to save the task 💾.
 
+---
+
 ### ⚙️ `entware.sh` – Summon the Tools o' the Deep
 
 > [!NOTE]
@@ -147,6 +149,28 @@ To ensure the Docker fleet sets sail in the right order after every reboot, set
 
 ---
 
+### 🕵️‍☠️ `test_vpn.sh` – Spyglass into the VPN Abyss
+
+This script helps ye confirm whether yer VPN tunnel be secure and active by comparin' the public IP and location from inside a container with that o' the host.
+
+**Features:**
+
+- Runs a container hooked into yer VPN network (like Gluetun).
+- Fetches the container's public IP and location via `ipinfo.io`.
+- Compares it against the host's own info to spot any leaks.
+- Uses `jq` to pretty-print responses if installed, or falls back to a plaintext method.
+
+🦜 [Unfurl the test_vpn.sh Chart](./test_vpn.sh)
+
+> [!TIP]
+> 🔍 Useful fer confirm'n that yer containers be masked and the host be hidin' in the fog! Call it straight from the Makefile with:
+>
+> ```sh
+> make test-vpn
+> ```
+
+---
+
 May yer setup be swift and yer configurations flawless! 🌊🏴‍☠️
 
 May this scroll guide all yer Docker fleets to set sail true and in order! ⚓🏴‍☠️

scripts/test_vpn.sh

@@ -0,0 +1,94 @@
+#!/bin/sh
+#
+# test_vpn.sh
+#
+# Purpose:
+#   This script verifies whether a Docker container using a VPN network
+#   (such as with Gluetun) is routing traffic properly. It compares the
+#   public IP and location of the container with that of the host system.
+#
+#   The script:
+#     - Runs a temporary Alpine container using the VPN network
+#     - Installs wget inside the container
+#     - Retrieves the container's public IP and location via ipinfo.io
+#     - Retrieves the host's public IP and location via ipinfo.io
+#     - Compares the two IP addresses to determine if the VPN is active
+#     - Pretty-prints all JSON responses, using jq if available
+
+# Constants
+CONTAINER_NAME="gluetun-latest"
+DOCKER_IMAGE="alpine:latest"
+IPINFO_URL="https://ipinfo.io"
+
+# ANSI colors
+COLOR_RED='\033[31m'
+COLOR_GREEN='\033[32m'
+COLOR_YELLOW='\033[33m'
+COLOR_BLUE='\033[34m'
+COLOR_RESET='\033[0m'
+
+# Check for jq availability
+if command -v jq >/dev/null 2>&1; then
+    HAS_JQ=1
+else
+    HAS_JQ=0
+fi
+
+# Show starting message
+printf '%b\n' "${COLOR_BLUE}Running VPN container test...${COLOR_RESET}"
+
+# Define and print the Docker command
+docker_cmd="docker run --rm --network=container:$CONTAINER_NAME $DOCKER_IMAGE sh -c 'apk add --no-cache wget >/dev/null 2>&1 && wget -qO- $IPINFO_URL'"
+printf '%b\n' "${COLOR_BLUE}Step 1: Running Docker container with VPN network:${COLOR_RESET}"
+printf '%b\n' "$docker_cmd"
+
+# Execute the Docker command
+container_output=$(eval "$docker_cmd")
+
+# Print container JSON output
+printf '%b\n' "${COLOR_BLUE}Step 2: Received container response:${COLOR_RESET}"
+if [ "$HAS_JQ" -eq 1 ]; then
+    printf "%s\n" "$container_output" | jq .
+else
+    printf "%s\n" "$container_output" | sed 's/[,{]/\n&/g'
+fi
+
+# Extract container info
+container_ip=$(printf "%s\n" "$container_output" | grep -oE '"ip":\s*"[^"]+"' | cut -d'"' -f4)
+container_city=$(printf "%s\n" "$container_output" | grep -oE '"city":\s*"[^"]+"' | cut -d'"' -f4)
+container_region=$(printf "%s\n" "$container_output" | grep -oE '"region":\s*"[^"]+"' | cut -d'"' -f4)
+container_country=$(printf "%s\n" "$container_output" | grep -oE '"country":\s*"[^"]+"' | cut -d'"' -f4)
+container_location="$container_city, $container_region $container_country"
+
+# Validate container IP
+if [ -z "$container_ip" ]; then
+    printf '%b\n' "${COLOR_RED}Error: could not determine VPN container IP address.${COLOR_RESET}"
+    exit 1
+fi
+
+# Run and display host request
+printf '%b\n' "${COLOR_BLUE}Step 3: Getting host IP info from ipinfo.io...${COLOR_RESET}"
+host_output=$(wget -qO- "$IPINFO_URL")
+
+# Print host JSON output
+printf '%b\n' "${COLOR_BLUE}Step 4: Received host response:${COLOR_RESET}"
+if [ "$HAS_JQ" -eq 1 ]; then
+    printf "%s\n" "$host_output" | jq .
+else
+    printf "%s\n" "$host_output" | sed 's/[,{]/\n&/g'
+fi
+
+# Extract host info
+host_ip=$(printf "%s\n" "$host_output" | grep -oE '"ip":\s*"[^"]+"' | cut -d'"' -f4)
+host_city=$(printf "%s\n" "$host_output" | grep -oE '"city":\s*"[^"]+"' | cut -d'"' -f4)
+host_region=$(printf "%s\n" "$host_output" | grep -oE '"region":\s*"[^"]+"' | cut -d'"' -f4)
+host_country=$(printf "%s\n" "$host_output" | grep -oE '"country":\s*"[^"]+"' | cut -d'"' -f4)
+host_location="$host_city, $host_region $host_country"
+
+# Compare IPs and report result
+printf '%b\n' "${COLOR_BLUE}Step 5: Comparing container and host IPs...${COLOR_RESET}"
+if [ "$container_ip" != "$host_ip" ]; then
+    printf '%b\n' "${COLOR_GREEN}VPN is active. Container IP: $container_ip ($container_location), Host IP: $host_ip ($host_location).${COLOR_RESET}"
+else
+    printf '%b\n' "${COLOR_YELLOW}Warning: container IP $container_ip matches host IP $host_ip. VPN may not be active.${COLOR_RESET}"
+fi