From 3b1b853b147082e5f4a35be2329f983fbf8b035f Mon Sep 17 00:00:00 2001 From: Amir Date: Mon, 29 Dec 2025 12:02:36 -0300 Subject: [PATCH 1/3] feat: implement hybrid native/python speedtest engine - Introduce native Ookla Speedtest binary support for Gigabit connections - Add intelligent engine detection with automatic fallback to python-cli version - Map full JSON payload to Watched_Value3 for n8n integration - Add Spanish (es_es) localizations and update README instructions --- front/plugins/internet_speedtest/README.md | 28 ++++++++-- front/plugins/internet_speedtest/config.json | 16 +++--- front/plugins/internet_speedtest/script.py | 56 +++++++++++++++++--- server/api_server/nettools_endpoint.py | 56 +++++++++++++++++++- server/const.py | 2 + 5 files changed, 140 insertions(+), 18 deletions(-) diff --git a/front/plugins/internet_speedtest/README.md b/front/plugins/internet_speedtest/README.md index 4aa78555..9fab1136 100755 --- a/front/plugins/internet_speedtest/README.md +++ b/front/plugins/internet_speedtest/README.md @@ -1,11 +1,33 @@ ## Overview -A simple plugin allowing for executing regular internet speed tests. +A plugin allowing for executing regular internet speed tests. ### Usage -- N/A +This plugin supports two engines: +1. **Baseline Engine**: Uses the Python `speedtest-cli` library (default). +2. **Native Engine (Optimized)**: Uses the native Ookla Speedtest binary. + +#### Opt-in for Native Engine +To use the native engine: +- Provide the native `speedtest` binary in your environment: [Speedtest CLI Homepage](https://www.speedtest.net/apps/cli) +- Map the binary to `/usr/bin/speedtest` in the container. +- **Ensure the native speedtest binary is installed on the host at the source path.** + +```yaml +volumes: + - /usr/bin/speedtest:/usr/bin/speedtest:ro +``` +- The plugin will automatically detect and use it for subsequent tests. + + +### Data Mapping + +- **Watched_Value1** — Download Speed (Mbps). +- **Watched_Value2** — Upload Speed (Mbps). +- **Watched_Value3** — Full JSON payload (useful for n8n or detailed webhooks). ### Notes -- N/A \ No newline at end of file +- The native binary is recommended for connections > 100 Mbps. +- If the native binary is not detected, the plugin seamlessly falls back to the baseline library. \ No newline at end of file diff --git a/front/plugins/internet_speedtest/config.json b/front/plugins/internet_speedtest/config.json index 75a1c3b1..0d8a97f1 100755 --- a/front/plugins/internet_speedtest/config.json +++ b/front/plugins/internet_speedtest/config.json @@ -240,18 +240,18 @@ "default_value": "", "options": [], "localized": ["name"], - "name": [ + "name": [ { "language_code": "en_us", - "string": "N/A" + "string": "Full JSON" }, { "language_code": "es_es", - "string": "N/A" + "string": "JSON completo" }, { "language_code": "de_de", - "string": "N/A" + "string": "Vollständiges JSON" } ] }, @@ -591,11 +591,15 @@ "description": [ { "language_code": "en_us", - "string": "Send a notification if selected values change. Use CTRL + Click to select/deselect. " + "string": "Send a notification if selected values change. Use CTRL + Click to select/deselect. " + }, + { + "language_code": "es_es", + "string": "Envíe una notificación si los valores seleccionados cambian. Use CTRL + Clic para seleccionar/deseleccionar. " }, { "language_code": "de_de", - "string": "Sende eine Benachrichtigung, wenn ein ausgwählter Wert sich ändert. STRG + klicken zum aus-/abwählen. " + "string": "Sende eine Benachrichtigung, wenn ein ausgwählter Wert sich ändert. STRG + klicken zum aus-/abwählen. " } ] }, diff --git a/front/plugins/internet_speedtest/script.py b/front/plugins/internet_speedtest/script.py index feca2887..0385246b 100755 --- a/front/plugins/internet_speedtest/script.py +++ b/front/plugins/internet_speedtest/script.py @@ -3,6 +3,8 @@ import os import sys import speedtest +import subprocess +import json # Register NetAlertX directories INSTALL_PATH = os.getenv('NETALERTX_APP', '/app') @@ -14,8 +16,7 @@ from logger import mylog, Logger # noqa: E402 [flake8 lint suppression] from helper import get_setting_value # noqa: E402 [flake8 lint suppression] import conf # noqa: E402 [flake8 lint suppression] from pytz import timezone # noqa: E402 [flake8 lint suppression] -from const import logPath # noqa: E402 [flake8 lint suppression] - +from const import logPath, NATIVE_SPEEDTEST_PATH # Make sure the TIMEZONE for logging is correct conf.tz = timezone(get_setting_value('TIMEZONE')) @@ -39,7 +40,7 @@ def main(): secondaryId = timeNowDB(), watched1 = speedtest_result['download_speed'], watched2 = speedtest_result['upload_speed'], - watched3 = 'null', + watched3 = speedtest_result['full_json'], watched4 = 'null', extra = 'null', foreignKey = 'null' @@ -48,23 +49,62 @@ def main(): def run_speedtest(): + native_path = NATIVE_SPEEDTEST_PATH + if os.path.exists(native_path): + mylog('verbose', ["[INTRSPD] Native speedtest binary detected, using it."]) + try: + # Safe parsing of timeout setting + try: + raw_timeout = get_setting_value('INTRSPD_RUN_TIMEOUT') + timeout = int(raw_timeout) if raw_timeout else 60 + except (ValueError, TypeError): + timeout = 60 + + if timeout < 60: + timeout = 60 + + cmd = [native_path, "--format=json", "--accept-license", "--accept-gdpr"] + result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout) + + if result.returncode == 0: + try: + data = json.loads(result.stdout) + download_speed = round(data['download']['bandwidth'] * 8 / 10**6, 2) + upload_speed = round(data['upload']['bandwidth'] * 8 / 10**6, 2) + except (json.JSONDecodeError, KeyError, TypeError) as parse_error: + mylog('none', [f"[INTRSPD] Failed to parse native JSON: {parse_error}"]) + # Fall through to baseline fallback + else: + mylog('verbose', [f"[INTRSPD] Native Result (down|up): {download_speed} Mbps|{upload_speed} Mbps"]) + return { + 'download_speed': download_speed, + 'upload_speed': upload_speed, + 'full_json': result.stdout.strip() + } + + except subprocess.TimeoutExpired: + mylog('none', ["[INTRSPD] Native speedtest timed out, falling back to baseline."]) + except Exception as e: + mylog('none', [f"[INTRSPD] Error running native speedtest: {e!s}, falling back to baseline."]) + + # Baseline fallback try: st = speedtest.Speedtest(secure=True) st.get_best_server() - download_speed = round(st.download() / 10**6, 2) # Convert to Mbps - upload_speed = round(st.upload() / 10**6, 2) # Convert to Mbps - - mylog('verbose', [f"[INTRSPD] Result (down|up): {str(download_speed)} Mbps|{upload_speed} Mbps"]) - + download_speed = round(st.download() / 10**6, 2) + upload_speed = round(st.upload() / 10**6, 2) + mylog('verbose', [f"[INTRSPD] Baseline Result (down|up): {download_speed} Mbps|{upload_speed} Mbps"]) return { 'download_speed': download_speed, 'upload_speed': upload_speed, + 'full_json': json.dumps(st.results.dict()) } except Exception as e: mylog('verbose', [f"[INTRSPD] Error running speedtest: {str(e)}"]) return { 'download_speed': -1, 'upload_speed': -1, + 'full_json': json.dumps({"error": str(e)}) } diff --git a/server/api_server/nettools_endpoint.py b/server/api_server/nettools_endpoint.py index 6a15ba41..456d83bc 100755 --- a/server/api_server/nettools_endpoint.py +++ b/server/api_server/nettools_endpoint.py @@ -6,6 +6,7 @@ import ipaddress import shutil import os from flask import jsonify +from const import NATIVE_SPEEDTEST_PATH # Resolve speedtest-cli path once at module load and validate it. # We do this once to avoid repeated PATH lookups and to fail fast when @@ -13,6 +14,7 @@ from flask import jsonify SPEEDTEST_CLI_PATH = None + def _get_speedtest_cli_path(): """Resolve and validate the speedtest-cli executable path.""" path = shutil.which("speedtest-cli") @@ -113,9 +115,52 @@ def traceroute(ip): def speedtest(): """ - API endpoint to run a speedtest using speedtest-cli. + API endpoint to run a speedtest using native binary or speedtest-cli. Returns JSON with the test output or error. """ + # Prefer native speedtest binary + if os.path.exists(NATIVE_SPEEDTEST_PATH): + try: + result = subprocess.run( + [NATIVE_SPEEDTEST_PATH, "--format=json", "--accept-license", "--accept-gdpr"], + capture_output=True, + text=True, + timeout=60 + ) + if result.returncode == 0: + try: + data = json.loads(result.stdout) + download = round(data['download']['bandwidth'] * 8 / 10**6, 2) + upload = round(data['upload']['bandwidth'] * 8 / 10**6, 2) + ping = data['ping']['latency'] + isp = data['isp'] + server = f"{data['server']['name']} - {data['server']['location']} ({data['server']['id']})" + + output_lines = [ + f"Server: {server}", + f"ISP: {isp}", + f"Latency: {ping} ms", + f"Download: {download} Mbps", + f"Upload: {upload} Mbps" + ] + + if 'packetLoss' in data: + output_lines.append(f"Packet Loss: {data['packetLoss']}%") + + return jsonify({"success": True, "output": output_lines}) + + except (json.JSONDecodeError, KeyError, TypeError) as parse_error: + print(f"Failed to parse native speedtest output: {parse_error}", file=sys.stderr) + # Fall through to CLI fallback + else: + print(f"Native speedtest exited with code {result.returncode}: {result.stderr}", file=sys.stderr) + + except subprocess.TimeoutExpired: + print("Native speedtest timed out after 60s, falling back to CLI", file=sys.stderr) + except Exception as e: + # Fall back to speedtest-cli if native fails + print(f"Native speedtest failed: {e}, falling back to CLI", file=sys.stderr) + # If the CLI wasn't found at module load, return a 503 so the caller # knows the service is unavailable rather than failing unpredictably. if SPEEDTEST_CLI_PATH is None: @@ -133,12 +178,21 @@ def speedtest(): capture_output=True, text=True, check=True, + timeout=60, ) # Return each line as a list output_lines = result.stdout.strip().split("\n") return jsonify({"success": True, "output": output_lines}) + except subprocess.TimeoutExpired: + return jsonify( + { + "success": False, + "error": "Speedtest timed out after 60 seconds", + } + ), 504 + except subprocess.CalledProcessError as e: return jsonify( { diff --git a/server/const.py b/server/const.py index fe2c2317..920b1f15 100755 --- a/server/const.py +++ b/server/const.py @@ -45,6 +45,8 @@ vendorsPathNewest = os.getenv( "VENDORSPATH_NEWEST", "/usr/share/arp-scan/ieee-oui_all_filtered.txt" ) +NATIVE_SPEEDTEST_PATH = os.getenv("NATIVE_SPEEDTEST_PATH", "/usr/bin/speedtest") + default_tz = "Europe/Berlin" From 7edf85718b2f8cff69b373cb19324f22c771df0d Mon Sep 17 00:00:00 2001 From: Amir Date: Mon, 29 Dec 2025 14:52:46 -0300 Subject: [PATCH 2/3] docs: update speedtest setup instructions for native engine --- front/plugins/internet_speedtest/README.md | 28 +++++++++++++++------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/front/plugins/internet_speedtest/README.md b/front/plugins/internet_speedtest/README.md index 9fab1136..933d2f07 100755 --- a/front/plugins/internet_speedtest/README.md +++ b/front/plugins/internet_speedtest/README.md @@ -6,20 +6,30 @@ A plugin allowing for executing regular internet speed tests. This plugin supports two engines: 1. **Baseline Engine**: Uses the Python `speedtest-cli` library (default). -2. **Native Engine (Optimized)**: Uses the native Ookla Speedtest binary. +2. **Native Engine (Optimized)**: Uses the official native Ookla Speedtest binary. #### Opt-in for Native Engine -To use the native engine: -- Provide the native `speedtest` binary in your environment: [Speedtest CLI Homepage](https://www.speedtest.net/apps/cli) -- Map the binary to `/usr/bin/speedtest` in the container. -- **Ensure the native speedtest binary is installed on the host at the source path.** +To use the native engine, you must provide the official binary to the container. The native binary is **strongly recommended** for internet connections > 100 Mbps to ensure CPU bottlenecks don't affect your results. + +**Setup Instructions:** +1. **Download:** Get the official binary for your architecture from the [Speedtest CLI Homepage](https://www.speedtest.net/apps/cli). +2. **Place & Prepare:** Place the binary on your host machine (e.g., in `/opt/netalertx/`) and ensure it has executable permissions: + +```bash + chmod +x /opt/netalertx/speedtest +``` + +3. Docker Mapping: Map the host file to exactly `/usr/bin/speedtest` inside the container via your `docker-compose.yml`: ```yaml -volumes: - - /usr/bin/speedtest:/usr/bin/speedtest:ro +services: + netalertx: + volumes: + - /opt/netalertx/speedtest:/usr/bin/speedtest:ro ``` -- The plugin will automatically detect and use it for subsequent tests. +### Why this mapping? +Inside the container, a Python version of speedtest often exists in the virtual environment (`/opt/venv/bin/speedtest`). Mapping your native binary specifically to `/usr/bin/speedtest` allows the plugin to prioritize the high-performance native engine over the baseline library. ### Data Mapping @@ -30,4 +40,4 @@ volumes: ### Notes - The native binary is recommended for connections > 100 Mbps. -- If the native binary is not detected, the plugin seamlessly falls back to the baseline library. \ No newline at end of file +- If the native binary is not detected at /usr/bin/speedtest, or if it fails to execute, the plugin will seamlessly fall back to the baseline Python library. \ No newline at end of file From 218c427552efd6686a886b99f30a90759cc616a8 Mon Sep 17 00:00:00 2001 From: Amir Date: Mon, 29 Dec 2025 19:23:31 -0300 Subject: [PATCH 3/3] docs: document NATIVE_SPEEDTEST_PATH config option - Added details for NATIVE_SPEEDTEST_PATH to the README under 'Usage'. - Explained default behavior and included examples for overriding the binary location. - Added a verbose log to print the binary path when the plugin starts up. --- front/plugins/internet_speedtest/README.md | 10 ++++++++++ front/plugins/internet_speedtest/script.py | 1 + 2 files changed, 11 insertions(+) diff --git a/front/plugins/internet_speedtest/README.md b/front/plugins/internet_speedtest/README.md index 933d2f07..898b2c67 100755 --- a/front/plugins/internet_speedtest/README.md +++ b/front/plugins/internet_speedtest/README.md @@ -8,6 +8,16 @@ This plugin supports two engines: 1. **Baseline Engine**: Uses the Python `speedtest-cli` library (default). 2. **Native Engine (Optimized)**: Uses the official native Ookla Speedtest binary. +#### Native Speedtest Path +The plugin looks for the Speedtest binary at `/usr/bin/speedtest` by default. If the binary is located elsewhere, you can configure the path using the `NATIVE_SPEEDTEST_PATH` environment variable: + +Example: +```env +NATIVE_SPEEDTEST_PATH=/custom/path/to/speedtest +``` + +If this variable is left unset, the plugin assumes `/usr/bin/speedtest`. + #### Opt-in for Native Engine To use the native engine, you must provide the official binary to the container. The native binary is **strongly recommended** for internet connections > 100 Mbps to ensure CPU bottlenecks don't affect your results. diff --git a/front/plugins/internet_speedtest/script.py b/front/plugins/internet_speedtest/script.py index 0385246b..a324a805 100755 --- a/front/plugins/internet_speedtest/script.py +++ b/front/plugins/internet_speedtest/script.py @@ -50,6 +50,7 @@ def main(): def run_speedtest(): native_path = NATIVE_SPEEDTEST_PATH + mylog('verbose', [f"[INTRSPD] Using native binary path: {native_path}"]) if os.path.exists(native_path): mylog('verbose', ["[INTRSPD] Native speedtest binary detected, using it."]) try: