Initial commit

2025-10-15 23:48:19 +02:00
commit 5e2d10a2f6
2 changed files with 322 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,211 @@
+# Zabbix Speedtest Template
+
+A Zabbix template for monitoring internet connection speed using the official [Speedtest.net CLI client](https://www.speedtest.net/apps/cli).
+
+## Overview
+
+This template monitors your internet connection performance by periodically running speed tests and tracking key metrics including download speed, upload speed, and latency. It includes configurable triggers to alert you when performance drops below acceptable thresholds.
+
+## Features
+
+- **Download Speed Monitoring** - Track download bandwidth in bits per second
+- **Upload Speed Monitoring** - Track upload bandwidth in bits per second
+- **Latency Monitoring** - Measure ping latency in milliseconds
+- **Automatic Alerting** - Triggers fire when speeds fall below configured thresholds
+- **Configurable Thresholds** - Easy customization via Zabbix macros
+- **Timestamp Tracking** - Records when each test was performed
+
+## Requirements
+
+- Zabbix 7.0 or higher
+- Speedtest CLI client installed on the monitored host
+- Zabbix agent with permission to read `/home/zabbix/speedtest.json`
+
+## Installation
+
+### 1. Install Speedtest CLI
+
+On your monitored host, install the official Speedtest CLI:
+
+**Debian/Ubuntu:**
+```bash
+curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash
+sudo apt-get install speedtest
+```
+
+**RHEL/CentOS:**
+```bash
+curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.rpm.sh | sudo bash
+sudo yum install speedtest
+```
+
+**Other platforms:** See [official installation instructions](https://www.speedtest.net/apps/cli)
+
+### 2. Accept Speedtest License
+
+Run the speedtest command once manually to accept the license:
+```bash
+sudo -u zabbix speedtest --accept-license --accept-gdpr
+```
+
+### 3. Set Up Automated Speed Tests
+
+Create a cron job or systemd timer to run speed tests periodically and save results to JSON:
+
+**Using cron:**
+```bash
+# Create the speedtest script
+sudo tee /usr/local/bin/speedtest-json.sh > /dev/null <<'EOF'
+#!/bin/bash
+speedtest --format=json --accept-license --accept-gdpr > /home/zabbix/speedtest.json
+chown zabbix:zabbix /home/zabbix/speedtest.json
+chmod 644 /home/zabbix/speedtest.json
+EOF
+
+# Make it executable
+sudo chmod +x /usr/local/bin/speedtest-json.sh
+
+# Add to cron (run every 30 minutes)
+sudo crontab -e
+# Add this line:
+*/30 * * * * /usr/local/bin/speedtest-json.sh
+```
+
+**Note:** The template polls the JSON file every 30 minutes by default, so align your cron schedule accordingly.
+
+### 4. Import the Template
+
+1. Log in to your Zabbix frontend
+2. Go to **Configuration** → **Templates**
+3. Click **Import**
+4. Select the `zbx_speedtest_net.yaml` file
+5. Click **Import**
+
+### 5. Link the Template to a Host
+
+1. Go to **Configuration** → **Hosts**
+2. Select your host or create a new one
+3. Go to the **Templates** tab
+4. Link the **Speedtest** template
+5. Click **Update**
+
+## Monitored Metrics
+
+| Item | Key | Units | Description |
+|------|-----|-------|-------------|
+| Download Speed | `speedtest.download.speed` | bps | Download bandwidth in bits per second |
+| Upload Speed | `speedtest.upload.speed` | bps | Upload bandwidth in bits per second |
+| Latency | `speedtest.latency` | ms | Ping latency in milliseconds |
+| Timestamp | `speedtest.timestamp` | - | When the speed test was performed |
+| RAW Data | `vfs.file.contents[/home/zabbix/speedtest.json]` | - | Complete JSON output from speedtest |
+| RAW Data MD5 | `vfs.file.md5sum[/home/zabbix/speedtest.json]` | - | MD5 checksum to detect file changes |
+
+## Triggers
+
+### Download Speed Too Low
+- **Severity:** Average
+- **Condition:** Fires when download speed is below `{$SPEEDTEST.DOWNLOAD.MIN}` for 2 consecutive measurements
+- **Recovery:** Automatically recovers when speed exceeds the threshold
+
+### Upload Speed Too Low
+- **Severity:** Average
+- **Condition:** Fires when upload speed is below `{$SPEEDTEST.UPLOAD.MIN}` for 2 consecutive measurements
+- **Recovery:** Automatically recovers when speed exceeds the threshold
+
+## Configuration
+
+The template uses macros for easy customization. You can adjust these values at the template, host, or host group level.
+
+### Available Macros
+
+| Macro | Default Value | Description |
+|-------|---------------|-------------|
+| `{$SPEEDTEST.DOWNLOAD.MIN}` | 600 Mbit/s | Minimum acceptable download speed before triggering alert |
+| `{$SPEEDTEST.UPLOAD.MIN}` | 600 Mbit/s | Minimum acceptable upload speed before triggering alert |
+| `{$SPEEDTEST.LATENCY.MAX}` | 50 ms | Maximum acceptable latency before triggering alert (not currently used in triggers) |
+
+### Customizing Thresholds
+
+To customize thresholds for a specific host:
+
+1. Go to **Configuration** → **Hosts**
+2. Select your host
+3. Go to the **Macros** tab
+4. Click **Inherited and host macros**
+5. Modify the macro values as needed
+6. Click **Update**
+
+**Example:** For a 100 Mbit/s connection, you might set:
+- `{$SPEEDTEST.DOWNLOAD.MIN}` = `80` (80 Mbit/s, allowing 20% tolerance)
+- `{$SPEEDTEST.UPLOAD.MIN}` = `10` (10 Mbit/s)
+
+## Troubleshooting
+
+### No Data Received
+
+1. **Verify the JSON file exists:**
+   ```bash
+   ls -la /home/zabbix/speedtest.json
+   ```
+
+2. **Check file permissions:**
+   ```bash
+   sudo chmod 644 /home/zabbix/speedtest.json
+   sudo chown zabbix:zabbix /home/zabbix/speedtest.json
+   ```
+
+3. **Test the speedtest command:**
+   ```bash
+   sudo -u zabbix speedtest --format=json
+   ```
+
+4. **Check Zabbix agent can read the file:**
+   ```bash
+   zabbix_get -s 127.0.0.1 -k vfs.file.contents[/home/zabbix/speedtest.json]
+   ```
+
+### Speedtest Command Fails
+
+- Ensure you've accepted the license agreement
+- Check internet connectivity
+- Verify the speedtest binary is in the PATH
+- Check system logs for errors
+
+### High Latency or Bandwidth Usage
+
+Speed tests consume bandwidth and may cause latency spikes during execution. Consider:
+- Running tests less frequently (e.g., every hour instead of every 30 minutes)
+- Scheduling tests during off-peak hours only
+- Using Speedtest's `--server-id` option to test against a specific server
+
+## Technical Details
+
+### How It Works
+
+1. The speedtest CLI runs periodically via cron and outputs JSON to `/home/zabbix/speedtest.json`
+2. Zabbix agent reads the file contents every 30 minutes using the `vfs.file.contents` key
+3. Dependent items extract specific values using JSONPath preprocessing
+4. Bandwidth values are converted from bytes/second to bits/second (multiplied by 8)
+5. Triggers evaluate the metrics and fire alerts when thresholds are breached
+
+### Data Flow
+
+```
+Speedtest CLI → JSON File → Zabbix Agent → Master Item → Dependent Items → Triggers
+```
+
+## License
+
+This template is provided as-is without any warranty. Feel free to modify and distribute as needed.
+
+## Author
+
+David Leutgeb
+
+## Version
+
+1.0 - Initial release for Zabbix 7.0
+
+## Contributing
+
+Issues and pull requests are welcome!
--- a/zbx_speedtest_net.yaml
+++ b/zbx_speedtest_net.yaml
@@ -0,0 +1,111 @@
+zabbix_export:
+  version: '7.0'
+  template_groups:
+    - uuid: 0ebbb8bd230c4105a00a0d6f1a319b15
+      name: David
+  templates:
+    - uuid: ee57ce6d065d4d9690de6601d7dca87a
+      template: Speedtest
+      name: Speedtest
+      vendor:
+        name: David Leutgeb
+        version: "1.0"
+      description: 'Uses the speedtest.net CLI client'
+      groups:
+        - name: David
+      items:
+        - uuid: 92929609f7704e9cbbecffd90ba82132
+          name: 'Speedtest Download speed'
+          type: DEPENDENT
+          key: speedtest.download.speed
+          delay: '0'
+          units: bps
+          preprocessing:
+            - type: JSONPATH
+              parameters:
+                - $.download.bandwidth
+            - type: MULTIPLIER
+              parameters:
+                - '8'
+          master_item:
+            key: 'vfs.file.contents[/home/zabbix/speedtest.json]'
+          triggers:
+            - uuid: 4075e0a3c2a64e6e9d035f99f7bec0ad
+              expression: 'last(/Speedtest/speedtest.download.speed,#1)<{$SPEEDTEST.DOWNLOAD.MIN} and last(/Speedtest/speedtest.download.speed,#2)<{$SPEEDTEST.DOWNLOAD.MIN}'
+              recovery_mode: RECOVERY_EXPRESSION
+              recovery_expression: 'last(/Speedtest/speedtest.download.speed)>{$SPEEDTEST.DOWNLOAD.MIN}'
+              name: 'Download Speedtest too low'
+              priority: AVERAGE
+        - uuid: 7241c7b470fd420e977449265815e401
+          name: 'Speedtest latency'
+          type: DEPENDENT
+          key: speedtest.latency
+          delay: '0'
+          value_type: FLOAT
+          units: ms
+          preprocessing:
+            - type: JSONPATH
+              parameters:
+                - $.ping.latency
+          master_item:
+            key: 'vfs.file.contents[/home/zabbix/speedtest.json]'
+        - uuid: 1376fac46730425e987d77846c7d502e
+          name: 'Speedtest Timestamp'
+          type: DEPENDENT
+          key: speedtest.timestamp
+          delay: '0'
+          history: '0'
+          value_type: TEXT
+          trends: '0'
+          preprocessing:
+            - type: JSONPATH
+              parameters:
+                - $.timestamp
+          master_item:
+            key: 'vfs.file.contents[/home/zabbix/speedtest.json]'
+        - uuid: cb1a50514c1e4deaa95edcdbb8aa2300
+          name: 'Speedtest Upload speed'
+          type: DEPENDENT
+          key: speedtest.upload.speed
+          delay: '0'
+          units: bps
+          preprocessing:
+            - type: JSONPATH
+              parameters:
+                - $.upload.bandwidth
+            - type: MULTIPLIER
+              parameters:
+                - '8'
+          master_item:
+            key: 'vfs.file.contents[/home/zabbix/speedtest.json]'
+          triggers:
+            - uuid: 571991ae4ed34632b3cffb225e6bcf1b
+              expression: 'last(/Speedtest/speedtest.upload.speed,#1)<{$SPEEDTEST.UPLOAD.MIN} and last(/Speedtest/speedtest.upload.speed,#2)<{$SPEEDTEST.UPLOAD.MIN}'
+              recovery_mode: RECOVERY_EXPRESSION
+              recovery_expression: 'last(/Speedtest/speedtest.upload.speed)>{$SPEEDTEST.UPLOAD.MIN}'
+              name: 'Upload Speedtest too low'
+              priority: AVERAGE
+        - uuid: f3e86712c62b49fb87b49131159aae9f
+          name: 'RAW data'
+          key: 'vfs.file.contents[/home/zabbix/speedtest.json]'
+          delay: 30m
+          history: '0'
+          value_type: TEXT
+          trends: '0'
+        - uuid: d452d59eb9c2488da850f0edfdd9f608
+          name: 'RAW data file md5 sum'
+          key: 'vfs.file.md5sum[/home/zabbix/speedtest.json]'
+          delay: 30m
+          history: 5d
+          value_type: CHAR
+          trends: '0'
+      macros:
+        - macro: '{$SPEEDTEST.DOWNLOAD.MIN}'
+          value: '600'
+          description: 'Mbit/s min, before Trigger'
+        - macro: '{$SPEEDTEST.LATENCY.MAX}'
+          value: '50'
+          description: 'ms, max Latency before Trigger'
+        - macro: '{$SPEEDTEST.UPLOAD.MIN}'
+          value: '600'
+          description: 'Mbit/s min, before Trigger'