This guide covers installation of both Netcheck variants for different use cases. Choose the variant that matches your requirements.
| Variant | Best For | Deployment | Complexity |
|---|---|---|---|
| m1/netcheck | Kubernetes, Prometheus stacks, cloud-native | Docker, Helm, Binary | ⭐⭐ Medium |
| TristanBrotherton/netcheck | Home networks, ISP monitoring, simple logging | Shell script, Systemd | ⭐ Easy |
For Docker installation, see Docker.
Install Git to clone the project repository.
sudo apt-get update && sudo apt-get install -y git
Download the source code to access configuration examples and Helm charts.
git clone https://github.com/m1/netcheck netcheck
cd netcheck
Choose one of the following deployment methods:
Create a docker-compose.yml file:
services:
netcheck:
image: ghcr.io/m1/netcheck:latest
container_name: netcheck
restart: unless-stopped
ports:
- "8080:8080"
command:
- run
- --target
- external=https://one.one.one.one,https://dns.google
- --target
- internal=http://hellosvc.test.svc.cluster.local:9111
- --timeout
- "5s"
- --connect-timeout
- "3s"
- --failure-threshold
- "3"
- --wait-time
- "10s"
networks:
- monitoring
networks:
monitoring:
driver: bridge
Start the service:
docker compose up -d
Download the latest release binary:
curl -LO https://github.com/m1/netcheck/releases/latest/download/netcheck-linux-amd64
chmod +x netcheck-linux-amd64
sudo mv netcheck-linux-amd64 /usr/local/bin/netcheck
Run netcheck:
netcheck run --target external=https://one.one.one.one
helm repo add netcheck https://m1.github.io/netcheck/charts
helm repo update
helm install netcheck netcheck/netcheck \
--set targets.external[0]=https://one.one.one.one \
--set targets.external[1]=https://dns.google
Check if the metrics endpoint is accessible:
curl http://localhost:8080/metrics
Expected output includes Prometheus metrics:
# HELP netcheck_target_up Target availability status
# TYPE netcheck_target_up gauge
netcheck_target_up{target="external"} 1
Add netcheck to your prometheus.yml:
scrape_configs:
- job_name: 'netcheck'
static_configs:
- targets: ['netcheck:8080']
metrics_path: /metrics
scrape_interval: 30s
Ensure basic tools are available:
sudo apt-get update && sudo apt-get install -y curl git systemd
git clone https://github.com/TristanBrotherton/netcheck
cd netcheck
Edit the script or use command-line options:
# View available options
./netcheck.sh -h
# Run with custom settings
./netcheck.sh \
-u https://www.google.com \ # URL to check
-t 5 \ # Check interval (seconds)
-l /var/log/netcheck.log \ # Log file location
-s # Enable speedtest on reconnect
Install and enable the service:
sudo ./netcheck.sh -i
This creates a systemd service that starts on boot.
Check service status:
systemctl status netcheck
journalctl -u netcheck -f
View logs:
cat /var/log/netcheck.log
Start the optional web UI for remote log viewing:
./netcheck.sh -w
Note: The web interface is basic and unauthenticated. Use behind a reverse proxy with authentication or expose via secure tunnel (e.g., NGROK).
netcheck_target_up — Target availability (1=up, 0=down)netcheck_response_time_seconds — Response time histogramUse event hooks for notifications:
# Disconnect hook
./netcheck.sh -d /path/to/alert_script.sh
# Reconnect hook
./netcheck.sh -r /path/to/notify_script.sh
Example alert script:
#!/bin/bash
# /path/to/alert_script.sh
curl -X POST -H 'Content-type: application/json' \
--data '{"text":"⚠️ Internet connection DOWN!"}' \
https://hooks.slack.com/services/YOUR/WEBHOOK/URL
Configure log rotation for TristanBrotherton/netcheck:
sudo tee /etc/logrotate.d/netcheck << 'EOF'
/var/log/netcheck.log {
daily
rotate 30
compress
delaycompress
missingok
notifempty
create 0640 root root
}
EOF
| Issue | Solution |
|---|---|
| Container won’t start | Check Docker logs: docker logs netcheck |
| No metrics visible | Verify port 8080 is exposed and not blocked by firewall |
| Targets show as down | Check network connectivity and target URLs |
| Issue | Solution |
|---|---|
| Service fails to start | Check journal: journalctl -u netcheck |
| No logs appearing | Verify log file permissions and path |
| Speedtest fails | Install speedtest-cli: sudo apt install speedtest-cli |
Any questions?
Feel free to contact us. Find all contact information on our contact page.