Merge pull request #38 from PlexSheep/devel

make outages work for now
PlexSheep · Jan 7, 2025 · f592925 · f592925
2 parents 5002a96 + 4cf97e3
commit f592925
Show file tree

Hide file tree

Showing 5 changed files with 336 additions and 78 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 default-run = "netpulse"
 name = "netpulse"
-version = "0.6.1"
+version = "0.7.0-rc0"
 edition = "2021"
 publish = true
 authors = ["Christoph J. Scherr <[email protected]>"]

diff --git a/README.md b/README.md
@@ -6,17 +6,67 @@
 ![GitHub language count](https://img.shields.io/github/languages/count/PlexSheep/netpulse)
 [![Rust CI](https://github.com/PlexSheep/netpulse/actions/workflows/cargo.yaml/badge.svg)](https://github.com/PlexSheep/hedu/actions/workflows/cargo.yaml)
 
-Keep track of your internet connection with a daemon
+Keep track of your internet connection with a daemon. Licensed under MIT.
 
-* [GitHub](https://github.com/PlexSheep/netpulse)
-* [crates.io](https://crates.io/crates/netpulse)
-* [docs.rs](https://docs.rs/crate/netpulse/)
+- [GitHub](https://github.com/PlexSheep/netpulse)
+- [crates.io](https://crates.io/crates/netpulse)
+- [docs.rs](https://docs.rs/crate/netpulse/)
 
 ## Why?
 
 My ISP has trouble pretty much every year some month delivering constant uptime,
 Netpulse helps keep track of when your internet connectivity goes down.
 
+## Platform Support
+
+- Primary support: GNU/Linux x86_64
+- Other architectures: May work but untested
+- Windows: Not supported
+- macOS: Unknown/untested
+
+I have it running on my homeserver and laptop with Debian based modern Operating
+Systems.
+
+## How it Works
+
+Netpulse performs comprehensive connectivity checks using multiple methods:
+
+1. HTTP Checks: Makes HTTP requests to test application-layer connectivity
+2. ICMP Checks: Sends ping requests to test basic network reachability
+3. Dual-Stack: Each check is performed over both IPv4 and IPv6 to monitor both network stacks
+
+The daemon performs these checks every 60 seconds against reliable targets
+(currently Cloudflare's DNS servers). This multi-protocol approach helps
+distinguish between different types of connectivity issues.
+
+## Installation
+
+### Via Cargo
+
+The simplest way to install Netpulse is through Cargo:
+
+```bash
+cargo install netpulse
+```
+
+This will install both the `netpulse` and `netpulsed` executables.
+
+### System Setup
+
+After installing the binaries, you'll need to set up the daemon environment:
+
+```bash
+sudo netpulsed --setup
+```
+
+This will:
+
+- Create the netpulse user and group
+- Copy the `netpulsed` executable to `/usr/local/bin/`
+- Create necessary directories and set permissions
+- Install a systemd unit file
+- Configure logging
+
 ## Usage
 
 Netpulse has two parts:
@@ -34,47 +84,151 @@ seconds.
 
 ### The Daemon
 
-The daemon of Netpulse can be started, ended and so on with the `netpulsed`
-executable.
+The `netpulsed` daemon can be run either through systemd (recommended) or as a standalone process.
 
-A simple `sudo netpulsed --start` will let the daemon run until you stop it or
-your system shuts down. Root privileges are required for starting and setup,
-but privileges will be dropped to the user `netpulse` with the group
-`netpulse`.
+#### Using Systemd (Recommended)
 
-Therefore, you need to create a user `netpulse` on your system to use the
-daemon:
+After running the setup (`sudo netpulsed --setup`), you can manage the daemon using standard systemd commands:
 
 ```bash
-useradd -r -s /usr/sbin/nologin netpulse
+sudo systemctl start netpulsed.service   # Start the daemon
+sudo systemctl stop netpulsed.service    # Stop the daemon
+sudo systemctl status netpulsed.service  # Check daemon status
 ```
 
-To set everything up, including a systemd unit file and copying the `netpulsed`
-executable to `/usr/local/bin/`, do the following:
+#### Running Standalone
 
-```bash
-netpulsed --setup
-```
+You can also run `netpulsed` directly as a regular program. Note that root privileges are required for setup, but the daemon will drop privileges to the `netpulse` user and group during operation.
 
-#### Updating
+#### Logging
 
-Just run `netpulsed --setup` again, and restart the systemd service with
-`systemctl restart netpulsed.service` if you use that.
+The daemon's log level can be controlled using the `NETPULSE_LOG_LEVEL` environment variable. Valid values are:
+
+- `error`
+- `warn`
+- `info` (default)
+- `debug`
+- `trace`
+
+For example:
+
+```bash
+NETPULSE_LOG_LEVEL=debug netpulsed --start
+```
 
 ### The Reader
 
 You can use `netpulse --test` to run the checks the daemon would run and see the
 status. Just using `netpulse` without arguments will result in it trying to load
 and analyze the store.
 
+#### Example Output
+
+The processed output of `netpulse` currently looks somewhat like this:
+
+```txt
+========== General =======================================
+checks                  : 00303548
+checks ok               : 00302817
+checks bad              : 00000731
+success ratio           : 99.76%
+first check at          : 2024-11-09 00:38:00 +01:00
+last check at           : 2025-01-07 03:13:00 +01:00
+
+========== HTTP ==========================================
+checks                  : 00150420
+checks ok               : 00150120
+checks bad              : 00000300
+success ratio           : 99.80%
+first check at          : 2024-11-09 00:38:00 +01:00
+last check at           : 2025-01-07 03:13:00 +01:00
+
+========== ICMP ==========================================
+checks                  : 00153128
+checks ok               : 00152697
+checks bad              : 00000431
+success ratio           : 99.72%
+first check at          : 2024-11-09 03:19:00 +01:00
+last check at           : 2025-01-07 03:13:00 +01:00
+
+========== IPv4 ==========================================
+checks                  : 00151774
+checks ok               : 00151601
+checks bad              : 00000173
+success ratio           : 99.89%
+first check at          : 2024-11-09 00:38:00 +01:00
+last check at           : 2025-01-07 03:13:00 +01:00
+
+========== IPv6 ==========================================
+checks                  : 00151774
+checks ok               : 00151216
+checks bad              : 00000558
+success ratio           : 99.63%
+first check at          : 2024-11-09 00:38:00 +01:00
+last check at           : 2025-01-07 03:13:00 +01:00
+
+========== Outages =======================================
+0:	From 2025-01-06 14:35:00 +01:00 To (None), Total 1
+1:	From 2025-01-06 14:35:00 +01:00 To (None), Total 1
+2:	From 2025-01-06 11:14:00 +01:00 To (None), Total 1
+3:	From 2025-01-06 11:14:00 +01:00 To (None), Total 1
+4:	From 2025-01-05 09:45:00 +01:00 To (None), Total 1
+5:	From 2025-01-05 09:45:00 +01:00 To (None), Total 1
+6:	From 2025-01-05 09:42:00 +01:00 To 2025-01-05 09:42:00 +01:00, Total 2
+7:	From 2025-01-05 01:13:00 +01:00 To (None), Total 1
+8:	From 2025-01-05 01:13:00 +01:00 To (None), Total 1
+9:	From 2025-01-04 14:42:00 +01:00 To (None), Total 1
+10:	From 2025-01-04 14:42:00 +01:00 To (None), Total 1
+
+showing only the 10 latest outages...
+
+========== Store Metadata ================================
+Hash mem blake3         : 8eacb2853d44d141d82d3b8232c27edb530df6add5a40b4370facb0b634ade3d
+Hash file sha256        : 67c30c020f176615fb9956126ad9b27c69d556870f17fa6cadd37962be33258d
+Store Version (mem)     : 2
+Store Version (file)    : 2
+Store Size (mem)        : 16777248
+Store Size (file)       : 1113762
+File to Mem Ratio       : 0.06638526175449036
+```
+
+### Updating
+
+There are two steps to updating Netpulse:
+
+1. Update the binaries:
+
+```bash
+cargo install netpulse
+```
+
+2. Update the system configuration:
+
+```bash
+sudo netpulsed --setup
+```
+
+3. If using systemd, restart the service:
+
+```bash
+sudo systemctl restart netpulsed.service
+```
+
 ### Files and Directories
 
 `netpulsed` will try to create a few directories / files:
 
-* `/run/netpulse/netpulse.pid` – lockfile with the PID of the daemon to make sure it doesn't run multiple times
-* `/var/lib/netpulse/netpuse.store` – the database where your checks are stored
-* `/var/log/netpulse.log` – contains the stdout of the daemon
-* `/var/log/netpulse.err` – contains the stderr of the daemon
+- `/run/netpulse/netpulse.pid` – lockfile with the PID of the daemon to make sure it doesn't run multiple times
+- `/var/lib/netpulse/netpuse.store` – the database where your checks are stored
+- `/var/log/netpulse.log` – contains the stdout of the daemon
+- `/var/log/netpulse.err` – contains the stderr of the daemon
+
+**Storage Requirement of the Store**
+
+Netpulse has been running for almost three months on my homeserver now. The
+server shuts down over night usually for about 6 hours. Other than that, it
+performs the six default checks every 60 seconds. My store file has in that time
+grown to 1.1 MB. ZSTD compression and encoding does a lot here.
 
 ### Targets