Release v0.3.0: ICMP monitors, dependency topology, dead-man peers

ICMP (ping) monitors via unprivileged datagram sockets (rootless-Docker friendly, IPv4+IPv6). Dependency-aware alerting (depends_on) with root-cause/impact annotations and display groups. Mutual-surveillance dead-man peers ([health]/[[peers]]) with witness quorum, and a JSON /healthz. Status-page annotation moved below the caption and ungrouped sections spaced.

Author: uplg

CHANGELOG.md

@@ -7,8 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-08
+
 ### Added
 
+- **ICMP (ping) monitors** (`kind = "icmp"`): `target` is a host or IP (no port),
+  up = an echo reply within the timeout, latency = the round-trip time
+  (`degraded_over_ms` applies). It uses an **unprivileged datagram socket**, so it
+  works in rootless Docker without `CAP_NET_RAW` (the kernel's
+  `net.ipv4.ping_group_range`, Docker's default, must cover the process); when no
+  ICMP permission is available the monitor reports down with a clear reason rather
+  than crashing. **IPv4 and IPv6** are both supported.
 - **Dependency-aware alerting** (`depends_on`) and **display groups** (`group`)
   on monitors. When a monitor goes down, the alert is annotated with topology
   context: `"caused by X"` if an upstream it depends on is also down (symptom),

Cargo.lock

@@ -8,7 +8,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.2.4"
+version = "0.3.0"
 edition = "2024"
 license = "MIT"
 publish = false

Cargo.toml

@@ -62,6 +62,14 @@ The status page is at `http://localhost:8787/`. Put it behind your reverse proxy
 on whatever domain you like - Hora is self-contained and assumes nothing about who
 consumes it.
 
+**ICMP (`kind = "icmp"`) monitors** use an unprivileged datagram socket, so they
+need no extra capability as long as the container's group id is within the
+kernel's `net.ipv4.ping_group_range` - Docker's default (`0 2147483647`) already
+covers the image's `10001` user, **including rootless Docker**. If your host
+narrows that range, either widen it
+(`--sysctl net.ipv4.ping_group_range="0 2147483647"`) or grant `--cap-add NET_RAW`;
+otherwise `icmp` monitors simply report down with a clear reason.
+
 Secrets are best kept in the environment: any `${VAR}` in the config is replaced
 from the environment at load. So in the file:
 

README.md

@@ -107,9 +107,13 @@ default_retention_days = 90
 # at = "2026-06-07T12:00:00Z"      # optional, RFC 3339
 
 # --- Monitors -------------------------------------------------------------
-# kind = "http" (default), "tcp" or "push".
+# kind = "http" (default), "tcp", "icmp" or "push".
 # For http: target is a URL; up = 2xx (or expected_status if set).
 # For tcp:  target is "host:port"; up = TCP connect succeeds.
+# For icmp: target is a host or IP (no port); up = ICMP echo reply. Uses an
+#           unprivileged datagram socket, so it works in rootless Docker without
+#           CAP_NET_RAW (the kernel net.ipv4.ping_group_range, Docker's default,
+#           must cover the process). IPv4 and IPv6 are both supported.
 # For push: no target; the job calls POST /api/push/{id} (see below).
 # TLS certificate expiry is checked automatically for https:// monitors.
 #
@@ -163,6 +167,17 @@ interval_secs = 60
 timeout_secs = 5
 group = "infra"
 
+# ICMP echo (ping) to a host or IP. No port; up = an echo reply within timeout.
+[[monitors]]
+id = "gateway"
+name = "Gateway"
+kind = "icmp"
+target = "192.0.2.1"             # or a hostname, or an IPv6 address
+interval_secs = 30
+timeout_secs = 5
+group = "infra"
+# degraded_over_ms = 200         # optional; flag slow round-trips as degraded
+
 # Heartbeat / push monitor: down if no ping arrives within `interval_secs`.
 # The job calls: curl -fsS -X POST \
 #   "https://status.example.com/api/push/nightly-backup?token=${BACKUP_TOKEN}"

config.example.toml

@@ -17,7 +17,9 @@ reqwest.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 serde_json_path = "0.7.2"
+socket2 = "0.6.1"
 sqlx.workspace = true
+surge-ping = "0.8.4"
 tokio = { workspace = true, features = ["rt", "time", "net", "sync", "signal"] }
 tokio-rustls.workspace = true
 toml.workspace = true

crates/hora-core/Cargo.toml

@@ -493,6 +493,11 @@ pub enum Kind {
     #[default]
     Http,
     Tcp,
+    /// ICMP echo (ping). Target is a host or IP (no port). Uses an unprivileged
+    /// datagram socket, so it works in rootless Docker without `CAP_NET_RAW`
+    /// (the kernel's `net.ipv4.ping_group_range` must cover the process, which is
+    /// the Docker default). IPv4 and IPv6 are both supported.
+    Icmp,
     /// Passive heartbeat: the monitored job pings `/api/push/{id}`; missing a
     /// heartbeat within the interval marks it down. No active probing.
     Push,
@@ -505,7 +510,8 @@ pub struct Monitor {
     pub name: String,
     #[serde(default)]
     pub kind: Kind,
-    /// Probe target (URL for HTTP, `host:port` for TCP). Unused for push monitors.
+    /// Probe target (URL for HTTP, `host:port` for TCP, host or IP for ICMP).
+    /// Unused for push monitors.
     #[serde(default)]
     pub target: String,
     pub interval_secs: u64,
@@ -1000,6 +1006,23 @@ fn validate_monitor_io(monitor: &Monitor) -> anyhow::Result<()> {
             "monitor {}: tcp target must be host:port",
             monitor.id
         ),
+        Kind::Icmp => {
+            // A stray `:port` is a common mistake; an IPv6 literal parses as an IP
+            // and is exempt, so its colons are fine.
+            let has_port = monitor.target.parse::<std::net::IpAddr>().is_err()
+                && monitor
+                    .target
+                    .rsplit_once(':')
+                    .is_some_and(|(host, port)| !host.is_empty() && port.parse::<u16>().is_ok());
+            anyhow::ensure!(
+                !monitor.target.contains("://")
+                    && !monitor.target.contains('/')
+                    && !monitor.target.chars().any(char::is_whitespace)
+                    && !has_port,
+                "monitor {}: icmp target must be a bare host or IP (no scheme, path, or port)",
+                monitor.id
+            );
+        }
         Kind::Push => {}
     }
     // A negative latency threshold would mark every check degraded/breached.
@@ -1866,4 +1889,44 @@ mod tests {
         let error = validate(&config).unwrap_err().to_string();
         assert!(error.contains("cycle"), "got: {error}");
     }
+
+    #[test]
+    fn parses_icmp_monitor() {
+        let config = parse(
+            r#"
+            [page]
+            [server]
+            [[monitors]]
+            id = "host"
+            name = "Host"
+            kind = "icmp"
+            target = "192.0.2.1"
+            interval_secs = 30
+        "#,
+        );
+        assert_eq!(config.monitors[0].kind, Kind::Icmp);
+        // ICMP is not HTTPS, so no certificate check.
+        assert!(!config.monitors[0].checks_cert());
+        validate(&config).expect("valid icmp monitor");
+    }
+
+    #[test]
+    fn rejects_icmp_target_with_scheme_or_port() {
+        for bad in ["https://example.com", "1.2.3.4:443", "a/b"] {
+            let config = parse(&format!(
+                r#"
+                [page]
+                [server]
+                [[monitors]]
+                id = "host"
+                name = "Host"
+                kind = "icmp"
+                target = "{bad}"
+                interval_secs = 30
+            "#
+            ));
+            let error = validate(&config).unwrap_err().to_string();
+            assert!(error.contains("bare host or IP"), "{bad} -> {error}");
+        }
+    }
 }