This guide covers configuration options for both Netcheck variants. Configuration approaches differ significantly between the Rust (m1/netcheck) and Shell (TristanBrotherton/netcheck) versions.
Netcheck uses command-line arguments instead of environment variables or config files.
netcheck run --target <name>=<url1>,<url2> [options]
| Option | Description | Default | Required | Example |
|---|---|---|---|---|
--target |
Target group with URLs to monitor | — | Yes | external=https://one.one.one.one |
--timeout |
HTTP request timeout | 5s |
No | --timeout "10s" |
--connect-timeout |
TCP connection timeout | 3s |
No | --connect-timeout "5s" |
--failure-threshold |
Consecutive failures before marking down | 3 |
No | --failure-threshold "5" |
--wait-time |
Interval between checks | 10s |
No | --wait-time "30s" |
--port |
Metrics server port | 8080 |
No | --port 9090 |
--help |
Show help message | — | No | netcheck run --help |
netcheck run --target external=https://one.one.one.one
netcheck run --target external=https://one.one.one.one,https://dns.google,https://api.github.com
netcheck run \
--target external=https://one.one.one.one,https://dns.google \
--target internal=http://kubernetes.default.svc.cluster.local:443 \
--target api=https://api.example.com/health
| Name Pattern | Use Case | Example |
|---|---|---|
external |
Internet-facing services | external=https://one.one.one.one |
internal |
Internal cluster services | internal=http://svc.cluster.local |
api |
API endpoints | api=https://api.example.com/health |
db |
Database connectivity | db=postgres://db:5432 |
| Custom name | Any descriptive label | payment=https://pay.example.com |
services:
netcheck:
image: ghcr.io/m1/netcheck:latest
command:
- run
- --target
- external=https://one.one.one.one,https://dns.google
- --target
- internal=http://kubernetes.default.svc.cluster.local:443
- --timeout
- "5s"
- --connect-timeout
- "3s"
- --failure-threshold
- "3"
- --wait-time
- "10s"
- --port
- "8080"
targets:
external:
- https://one.one.one.one
- https://dns.google
internal:
- http://kubernetes.default.svc.cluster.local:443
timing:
timeout: 5s
connectTimeout: 3s
failureThreshold: 3
waitTime: 10s
metrics:
port: 8080
GET http://localhost:8080/metrics
| Metric | Type | Description | Labels |
|---|---|---|---|
netcheck_target_up |
Gauge | Target availability (1=up, 0=down) | target |
netcheck_response_time_seconds |
Histogram | Response time distribution | target, le |
netcheck_checks_total |
Counter | Total checks performed | target, status |
netcheck_consecutive_failures |
Gauge | Current failure streak | target |
# HELP netcheck_target_up Target availability status
# TYPE netcheck_target_up gauge
netcheck_target_up{target="external"} 1
netcheck_target_up{target="internal"} 1
# HELP netcheck_response_time_seconds Response time histogram
# TYPE netcheck_response_time_seconds histogram
netcheck_response_time_seconds_bucket{target="external",le="0.01"} 150
netcheck_response_time_seconds_bucket{target="external",le="0.05"} 180
netcheck_response_time_seconds_bucket{target="external",le="0.1"} 195
netcheck_response_time_seconds_bucket{target="external",le="+Inf"} 200
netcheck_response_time_seconds_sum{target="external"} 8.5
netcheck_response_time_seconds_count{target="external"} 200
# HELP netcheck_checks_total Total checks performed
# TYPE netcheck_checks_total counter
netcheck_checks_total{target="external",status="success"} 195
netcheck_checks_total{target="external",status="failure"} 5
# Target availability (percentage)
avg_over_time(netcheck_target_up{target="external"}[24h]) * 100
# 95th percentile response time
histogram_quantile(0.95, rate(netcheck_response_time_seconds_bucket[5m]))
# Checks per minute
rate(netcheck_checks_total[1m]) * 60
# Consecutive failures
netcheck_consecutive_failures
./netcheck.sh [options]
| Option | Description | Default | Example |
|---|---|---|---|
-u URL |
URL/host to check | http://www.google.com |
-u https://example.com |
-t SECONDS |
Check interval | 5 |
-t 10 |
-l FILE |
Log file path | /var/log/netcheck.log |
-l /opt/logs/netcheck.log |
-s |
Enable speedtest on reconnect | Disabled | -s |
-d SCRIPT |
Script to run on disconnect | — | -d /path/to/alert.sh |
-r SCRIPT |
Script to run on reconnect | — | -r /path/to/notify.sh |
-e SCRIPT |
Script to run after every check | — | -e /path/to/log.sh |
-i |
Install as systemd service | — | -i |
-w |
Start web interface | — | -w |
-p PORT |
Web interface port | 8080 |
-p 9090 |
-h |
Show help | — | -h |
./netcheck.sh -u https://www.google.com -t 5
./netcheck.sh \
-u https://www.google.com \
-t 10 \
-l /var/log/netcheck.log \
-s
./netcheck.sh \
-u https://www.google.com \
-t 5 \
-d /opt/scripts/slack_alert_down.sh \
-r /opt/scripts/slack_alert_up.sh \
-s
sudo ./netcheck.sh -i
This creates:
/etc/systemd/system/netcheck.service/var/log/netcheck.log[2026-02-16 10:30:00] CONNECTED - Response time: 45ms
[2026-02-16 10:30:05] CONNECTED - Response time: 52ms
[2026-02-16 10:30:10] DISCONNECTED - No response from https://www.google.com
[2026-02-16 10:30:15] DISCONNECTED - No response from https://www.google.com
[2026-02-16 10:30:20] CONNECTED - Response time: 38ms - Downtime: 10 seconds
[2026-02-16 10:30:20] SPEEDTEST - Download: 950 Mbps, Upload: 850 Mbps
/opt/scripts/slack_alert_down.sh)#!/bin/bash
curl -X POST -H 'Content-type: application/json' \
--data "{\"text\":\"⚠️ Internet connection DOWN at $(date)!\"}" \
https://hooks.slack.com/services/YOUR/WEBHOOK/URL
/opt/scripts/notify_up.sh)#!/bin/bash
echo "Internet connection restored at $(date)" | \
mail -s "🟢 Connection Restored" admin@example.com
/opt/scripts/log.sh)#!/bin/bash
echo "$(date) - Status: $1" >> /var/log/custom_netcheck.log
Start the web UI:
./netcheck.sh -w -p 8080
Security Note: The web interface is basic and unauthenticated. Use behind a reverse proxy with authentication.
server {
listen 80;
server_name netcheck.example.com;
auth_basic "Netcheck Logs";
auth_basic_user_file /etc/nginx/.htpasswd;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
Create password file:
sudo htpasswd -c /etc/nginx/.htpasswd admin
command:
- run
- --target
- external=https://one.one.one.one,https://dns.google,https://api.github.com
- --timeout
- "10s"
- --connect-timeout
- "5s"
- --failure-threshold
- "5"
- --wait-time
- "30s"
Rationale:
command:
- run
- --target
- external=https://one.one.one.one
- --target
- internal=http://kubernetes.default.svc.cluster.local:443
- --target
- api=https://api.internal.svc.cluster.local/health
- --timeout
- "5s"
- --connect-timeout
- "3s"
- --failure-threshold
- "3"
- --wait-time
- "15s"
./netcheck.sh \
-u https://www.google.com \
-t 10 \
-l /var/log/isp_monitor.log \
-s \
-d /opt/scripts/isp_down.sh \
-r /opt/scripts/isp_up.sh
#!/bin/bash
# /opt/scripts/multi_target_monitor.sh
targets=(
"https://www.google.com"
"https://www.cloudflare.com"
"https://www.amazon.com"
)
for target in "${targets[@]}"; do
./netcheck.sh -u "$target" -t 30 -l "/var/log/netcheck_$(echo $target | md5sum).log" &
done
--wait-time / -t)| Use Case | Recommended Interval | Rationale |
|---|---|---|
| Critical services | 10-15s | Fast detection, higher resource usage |
| Standard monitoring | 30s | Balance between detection and resources |
| ISP/home monitoring | 60s | Lower overhead, acceptable detection time |
| Non-critical | 5-10 min | Minimal overhead |
| Environment | Recommended Threshold | Rationale |
|---|---|---|
| Stable networks | 3 | Quick detection of real issues |
| Unstable networks | 5-7 | Avoid false positives from transient issues |
| Mobile/cellular | 10 | High tolerance for intermittent connectivity |
| Network Type | Timeout | Connect Timeout |
|---|---|---|
| LAN/Datacenter | 3s | 1s |
| Internet/Cloud | 5-10s | 3-5s |
| High-latency (satellite) | 15-30s | 10s |
Netcheck is stateless — configuration is in Docker Compose or command-line. Backup your Compose file:
cp /opt/netcheck/docker/docker-compose.yml /backup/netcompose-$(date +%Y%m%d).yml
Backup logs and configuration:
tar -czvf netcheck-backup-$(date +%Y%m%d).tar.gz \
/var/log/netcheck.log \
/etc/systemd/system/netcheck.service \
/opt/scripts/*.sh
Any questions?
Feel free to contact us. Find all contact information on our contact page.