Zabbix-Speedtest-Template/README.md

Zabbix Speedtest Template

A Zabbix template for monitoring internet connection speed using the official Speedtest.net CLI client.

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:

curl -s https://packagecloud.io/install/repositories/ookla/speedtest-cli/script.deb.sh | sudo bash
sudo apt-get install speedtest

RHEL/CentOS:

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

2. Accept Speedtest License

Run the speedtest command once manually to accept the license:

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:

# 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:

   ls -la /home/zabbix/speedtest.json
   

2. Check file permissions:

   sudo chmod 644 /home/zabbix/speedtest.json
   sudo chown zabbix:zabbix /home/zabbix/speedtest.json
   

3. Test the speedtest command:

   sudo -u zabbix speedtest --format=json
   

4. Check Zabbix agent can read the file:

   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!