Zabbix-Speedtest-Template/README.md

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