ipmg 3.1.4__tar.gz → 3.2.0__tar.gz

{ipmg-3.1.4/src/ipmg.egg-info → ipmg-3.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: ipmg
-Version: 3.1.4
-Summary: IP Management & Ping Monitoring CLI Tool
+Version: 3.2.0
+Summary: Network discovery and change detection: ping sweeps, scan history, and reports for what changed on your network
 Author: Sameer Alam
 Maintainer-email: Sameer Alam <sameeralam3127@gmail.com>
 License-Expression: MIT
@@ -48,6 +48,7 @@ Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: pre-commit>=3.5.0; extra == "dev"
 Requires-Dist: python-semantic-release>=10.5.3; extra == "dev"
 Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: httpx2>=2.0; python_version >= "3.10" and extra == "dev"
 Dynamic: license-file
 
 # IPMG — IP Management & Ping Monitoring Tool
@@ -68,10 +69,10 @@ CIDR blocks, and ranges (IPv4 and IPv6), IPMG Web, a local dashboard that
 works offline, and reports in Excel, CSV, JSON, and Markdown.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-compare.gif" alt="ipmg scans 13 hosts, a new address is added to the target file, and a second scan with --compare reports a new host (warning) and a latency change (info) against the first" width="820">
+  <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-compare.gif" alt="ipmg scans 13 hosts with --stream, printing each one as it answers; a new address is added to the target file; a second scan with --compare reports it as a new host (warning) against the first" width="820">
 </p>
 
-[How it compares](#how-it-compares) to `nmap -sn`, `fping`, and Angry IP Scanner.
+[How it compares](#how-it-compares) to nmap, fping, and Uptime Kuma.
 
 **Website:** [sameeralam3127.github.io/ipmg](https://sameeralam3127.github.io/ipmg/) ·
 **Live demo:** [IPMG Web with sample data](https://sameeralam3127.github.io/ipmg/demo/) ·
@@ -98,6 +99,7 @@ ipmg --discover --compare   # later: scan again and see what changed
 [IPMG Web](#ipmg-web) ·
 [What you can scan](#what-you-can-scan) ·
 [Reports](#reports) ·
+[In GitHub Actions](#in-github-actions) ·
 [All options](#all-options) ·
 [Security](#security) ·
 [More help](#more-help) ·
@@ -107,21 +109,26 @@ ipmg --discover --compare   # later: scan again and see what changed
 
 ## How it compares
 
-| | IPMG | `nmap -sn` | `fping` | Angry IP Scanner |
+| | IPMG | nmap | fping | Uptime Kuma |
 | --- | --- | --- | --- | --- |
-| Parallel ping sweep | Yes, one system `ping` per host | Yes | Yes, fastest of the four | Yes |
-| Scan history and "what changed" | Built in | Save XML, compare with `ndiff` | No | No |
-| Change severities and alerts | critical / warning / info; Slack, Teams, webhook, email | No | No | No |
-| Exit codes for cron and CI | `3` with `--fail-on-down`, `2` with `diff --fail-on-change` | No | Non-zero if any host is unreachable | No (GUI first) |
-| Reports | Excel, CSV, JSON, Markdown | XML, grepable text | Plain text | CSV, TXT, XML |
-| Browser UI | IPMG Web, local, works offline | No (Zenmap is a desktop app) | No | Desktop app (Java) |
-| Port checks | Common TCP ports (connect only) | Full port, service, and OS scanner | No | Via fetchers |
+| Primary purpose | Network discovery, scan history, and what changed | Network discovery and security auditing ([nmap.org](https://nmap.org/)) | Fast ICMP reachability for many hosts at once ([man page](https://fping.org/fping.8.html)) | Self-hosted uptime monitoring of individual services ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| Ping sweeps of CIDR blocks and ranges | Yes, one system `ping` per host, `--threads` at a time | Yes, `-sn` host discovery ([docs](https://nmap.org/book/man-host-discovery.html)) | Yes, round-robin from one process with `-g`; the fastest here ([man page](https://fping.org/fping.8.html)) | No: one Ping monitor per host ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| TCP checks | Connect checks on chosen ports, and `--probe tcp` for hosts that block ping | A full port scanner ([docs](https://nmap.org/book/man-port-scanning-techniques.html)) | No ([man page](https://fping.org/fping.8.html)) | A TCP monitor per host and port ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| HTTP checks | `--http-check`: status, time, redirects, TLS, certificate expiry | Through NSE scripts such as `http-title` ([NSE](https://nmap.org/nsedoc/scripts/http-title.html)) | No ([man page](https://fping.org/fping.8.html)) | HTTP(s), keyword, and JSON query monitors ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| History and "what changed" | Built in: every scan stored, changes with severities | Save XML, compare two scans with `ndiff` ([ndiff](https://nmap.org/ndiff/)) | No ([man page](https://fping.org/fping.8.html)) | Up/down state and ping charts per monitor ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| Alerts | Slack, Teams, webhook, email, filtered by severity | No; it writes output files for other tools ([output](https://nmap.org/book/man-output.html)) | No ([man page](https://fping.org/fping.8.html)) | 90+ notification services ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| Exit codes for cron and CI | `3` with `--fail-on-down`, `2` with `diff --fail-on-change` | No; parse its XML output instead ([output](https://nmap.org/book/man-output.html)) | `1` if any host is unreachable ([man page](https://fping.org/fping.8.html)) | Not a command-line tool ([install](https://github.com/louislam/uptime-kuma#-how-to-install)) |
+| Reports | Excel, CSV, JSON, JSON Lines, Markdown | Normal, XML, grepable ([output](https://nmap.org/book/man-output.html)) | Plain text, with summaries (`-s`, `-C`) ([man page](https://fping.org/fping.8.html)) | Status pages ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| Browser UI | IPMG Web: local, offline, with scheduled scans | No; Zenmap is a desktop app ([Zenmap](https://nmap.org/zenmap/)) | No ([man page](https://fping.org/fping.8.html)) | It is a web app ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| Install | `pip`, `uv`, one-line installers, Homebrew, Docker | Packages and installers ([download](https://nmap.org/download.html)) | From source, or Docker ([README](https://github.com/schweikert/fping#installation)) | Docker, or Node.js ([install](https://github.com/louislam/uptime-kuma#-how-to-install)) |
 
 Where the others are better: **nmap** is a real port, service, and OS
 scanner, and IPMG does not try to be one. **fping** sends every probe from a
 single process, so on large ranges it is much faster than IPMG, which starts
-one `ping` per host (`--threads` at a time). Angry IP Scanner is a
-point-and-click desktop app with a plugin system.
+one `ping` per host. **Uptime Kuma** is built for watching a fixed set of
+services around the clock, with status pages to share. [Angry IP
+Scanner](https://angryip.org/) is a point-and-click desktop scanner with a
+plugin system.
 
 Reach for IPMG when you look after a network and need to know what moved since
 yesterday, with a report you can hand to someone.
@@ -151,7 +158,9 @@ That means:
 | Linux (iputils or busybox `ping`) | `ping -c COUNT -W SECONDS` | Supported. CI runs the tests and a scan on Ubuntu; see [verified environments](#verified-environments) |
 | macOS | `ping -c COUNT -W MILLISECONDS`; `ping6` for IPv6 | Supported. CI runs the tests and a scan on macOS |
 | Windows | `ping -n COUNT -w MILLISECONDS` | Supported. CI runs the tests and a scan of `127.0.0.1` on `windows-latest`; not yet verified against a real LAN |
-| FreeBSD, OpenBSD, NetBSD | the macOS flags | Untested. The code treats them like macOS, and their `ping` options may differ |
+| FreeBSD | `ping -c COUNT -W MILLISECONDS`; `ping6` for IPv6 | Probed in a FreeBSD VM in CI when the ping code changes |
+| OpenBSD | `ping -c COUNT -w SECONDS`; `ping6` for IPv6 | Probed in an OpenBSD VM in CI when the ping code changes |
+| NetBSD | `ping -c COUNT -w DEADLINE`; `ping6 -x MILLISECONDS` for IPv6 | Probed in a NetBSD VM in CI when the ping code changes |
 
 `--discover ipv6` reads the neighbour table with `ip -6 neigh` on Linux (the
 `iproute2` package), `ndp -an` on macOS, and `netsh` on Windows.
@@ -196,10 +205,12 @@ irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1 | iex
 
 It works in Windows PowerShell 5.1 and PowerShell 7 and needs no
 administrator rights: it installs uv if it is missing, installs IPMG, adds it
-to your user `PATH`, and checks that `ipmg --version` runs. To pin a release:
+to your user `PATH`, and checks that `ipmg --version` runs. To pin a release,
+replace `X.Y.Z` with any version listed on
+[PyPI](https://pypi.org/project/ipmg/#history):
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1))) -Version 2.3.0
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1))) -Version X.Y.Z
 ```
 
 **Docker (amd64 and arm64):**
@@ -243,7 +254,7 @@ docker compose run --rm scan --input 10.0.0.0/24          # CLI scans land in th
 
 Publishing the port more widely (`8080:8080`) exposes IPMG Web on your
 network over plain HTTP; put a reverse proxy with TLS in front first. Images
-are tagged with the release version (`2.4.0`), the minor line (`2.4`), and
+are tagged with the release version (`X.Y.Z`), the minor line (`X.Y`), and
 `latest`.
 
 ### Installing with pip
@@ -291,6 +302,19 @@ The one-line installers, Homebrew, and the Docker image install it with the
 `web` extra already. Run `ipmg web` without it and IPMG tells you the command
 that adds it.
 
+### Tab completion
+
+`ipmg completion SHELL` prints a completion script for commands, flags, their
+choices, and file names. It is generated from IPMG's own flag definitions, so
+it never falls behind; run it again after an upgrade.
+
+| Shell | Add this |
+| --- | --- |
+| bash | `eval "$(ipmg completion bash)"` in `~/.bashrc` (bash 3.2 and later; no bash-completion package needed) |
+| zsh | `eval "$(ipmg completion zsh)"` in `~/.zshrc`, after `compinit`; or save it as `_ipmg` in a directory on your `$fpath` |
+| fish | `ipmg completion fish > ~/.config/fish/completions/ipmg.fish` |
+| PowerShell | `ipmg completion powershell \| Out-String \| Invoke-Expression` in your `$PROFILE` |
+
 ### The one thing IPMG needs from your system
 
 IPMG probes hosts with your operating system's `ping` command, and minimal
@@ -311,13 +335,17 @@ IPMG runs the same `ping` you would run by hand.
 
 ### Verified environments
 
-Each of these was installed from scratch and run against a live target:
+The installer is tested in each of these whenever `install.sh` changes, and
+weekly: a fresh install as root with `--with-deps`, then a scan
+([workflow](https://github.com/sameeralam3127/ipmg/actions/workflows/install-sh.yml)).
+macOS and Ubuntu are also tested as a normal user, as are a pinned
+`--version` and an upgrade over an existing install.
 
 | Environment | Notes |
 | --- | --- |
 | Ubuntu 22.04 / 24.04 | 24.04 blocks `pip install`; the installer is unaffected |
 | Debian 12 | same PEP 668 situation as Ubuntu |
-| RHEL 8 / RHEL 9 (UBI), Rocky 9 | RHEL 8's system Python is 3.6 — uv supplies its own |
+| RHEL 8 / RHEL 9 (UBI), Rocky 9 | RHEL 8's system Python is 3.6; uv supplies its own |
 | Fedora 41 | |
 | openSUSE Leap 15.6 | image has no Python at all; installer supplies everything |
 | Alpine 3.20 | run the installer with `bash`, not `sh` |
@@ -339,10 +367,11 @@ one of them.
 uv tool install ipmg
 ```
 
-**Pin a specific version:**
+**Pin a specific version** (any release listed on
+[PyPI](https://pypi.org/project/ipmg/#history)):
 
 ```bash
-curl -sSL https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.sh | bash -s -- --version 1.13.0
+curl -sSL https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.sh | bash -s -- --version X.Y.Z
 ```
 
 **From source (development):**
@@ -385,7 +414,7 @@ ipmg --input targets.txt              # a file of hosts
 Here is what a finished scan looks like:
 
 ```text
-  ipmg 1.13.0  ·  scan
+  ipmg X.Y.Z  ·  scan
   ICMP probes only — scan only networks you are authorized to scan.
 
   Source   targets.txt
@@ -516,6 +545,7 @@ Or pick a ready-made command:
 | See what changed since last time | `ipmg --input targets.txt --compare` |
 | Check which services are listening | `ipmg --input targets.txt --scan-ports` |
 | Keep scanning every 5 minutes | `ipmg --input targets.txt --interval 5` |
+| Keep it running after logout and reboots | the systemd and launchd templates in [docs/SERVICES.md](https://github.com/sameeralam3127/ipmg/blob/main/docs/SERVICES.md) |
 | Look back at earlier scans | `ipmg history` |
 | Compare two specific scans | `ipmg diff 12 14` |
 | Use IPMG Web in your browser instead | `ipmg web` |
@@ -816,6 +846,66 @@ them — so piping IPMG into a file or a log gives you clean text.
 
 ---
 
+## In GitHub Actions
+
+This repository is also a GitHub Action: a pipeline step that checks your
+infrastructure is reachable and fails the job when it is not. It installs IPMG
+with uv, scans, writes a summary of the hosts that are down to the job page,
+and uploads the reports as an artifact, even when the step fails.
+
+Before a deploy:
+
+```yaml
+- name: Check the database and cache hosts are up
+  uses: sameeralam3127/ipmg@vX.Y.Z      # any IPMG release tag
+  with:
+    targets: 10.0.4.10 10.0.4.11 10.0.5.0/28
+    fail-on-down: true
+    args: --probe icmp,tcp --ports 5432,6379
+```
+
+On a schedule, with the reports kept and a Slack alert for changes (the
+history lives in the cached database):
+
+```yaml
+on:
+  schedule: [{ cron: "*/30 * * * *" }]
+jobs:
+  reachability:
+    runs-on: [self-hosted, office-lan]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/cache@v6
+        with: { path: ipmg-history, key: "ipmg-${{ github.run_id }}", restore-keys: ipmg- }
+      - uses: sameeralam3127/ipmg@vX.Y.Z
+        with:
+          targets: targets.txt
+          args: --db ipmg-history/history.db --compare --notify-slack
+          formats: csv md
+        env:
+          IPMG_NOTIFY_SLACK: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `targets` | (required) | IPs, CIDR blocks, ranges, or target files, separated by spaces or newlines |
+| `args` | | Extra IPMG flags, split on whitespace |
+| `version` | `latest` | The IPMG release to install, such as `3.2.0` |
+| `fail-on-down` | `false` | Fail the step when any target is not Active |
+| `formats` | `csv json md` | Report formats to write |
+| `upload-artifact` | `true` | Upload the reports as an artifact |
+| `artifact-name` | `ipmg-reports` | The artifact's name |
+
+Outputs: `active` and `total` host counts, `report-path`, and `exit-code`.
+
+GitHub-hosted runners generally cannot ping hosts outside GitHub's network,
+and cannot reach your private networks at all. For a LAN or a VPC, use a
+[self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners)
+inside it; for public hosts that drop ICMP, add `--probe tcp` or `--probe
+icmp,tcp` to `args`, or check the service itself with `--http-check`.
+
+---
+
 ## Default options in a file
 
 If every run repeats the same flags, put them in **`ipmg.toml`** next to your
@@ -991,7 +1081,9 @@ Contributions are welcome.
 [CONTRIBUTING.md](https://github.com/sameeralam3127/ipmg/blob/main/.github/CONTRIBUTING.md)
 covers setting up a development environment, running the tests, the commit
 message format that drives automated releases, and how the project website and
-IPMG Web demo are built. Everyone taking part is expected to follow the
+IPMG Web demo are built.
+[docs/ARCHITECTURE.md](https://github.com/sameeralam3127/ipmg/blob/main/docs/ARCHITECTURE.md)
+explains how the code fits together. Everyone taking part is expected to follow the
 [Code of Conduct](https://github.com/sameeralam3127/ipmg/blob/main/.github/CODE_OF_CONDUCT.md).
 
 ---

{ipmg-3.1.4 → ipmg-3.2.0}/README.md

@@ -16,10 +16,10 @@ CIDR blocks, and ranges (IPv4 and IPv6), IPMG Web, a local dashboard that
 works offline, and reports in Excel, CSV, JSON, and Markdown.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-compare.gif" alt="ipmg scans 13 hosts, a new address is added to the target file, and a second scan with --compare reports a new host (warning) and a latency change (info) against the first" width="820">
+  <img src="https://raw.githubusercontent.com/sameeralam3127/ipmg/main/docs/assets/ipmg-compare.gif" alt="ipmg scans 13 hosts with --stream, printing each one as it answers; a new address is added to the target file; a second scan with --compare reports it as a new host (warning) against the first" width="820">
 </p>
 
-[How it compares](#how-it-compares) to `nmap -sn`, `fping`, and Angry IP Scanner.
+[How it compares](#how-it-compares) to nmap, fping, and Uptime Kuma.
 
 **Website:** [sameeralam3127.github.io/ipmg](https://sameeralam3127.github.io/ipmg/) ·
 **Live demo:** [IPMG Web with sample data](https://sameeralam3127.github.io/ipmg/demo/) ·
@@ -46,6 +46,7 @@ ipmg --discover --compare   # later: scan again and see what changed
 [IPMG Web](#ipmg-web) ·
 [What you can scan](#what-you-can-scan) ·
 [Reports](#reports) ·
+[In GitHub Actions](#in-github-actions) ·
 [All options](#all-options) ·
 [Security](#security) ·
 [More help](#more-help) ·
@@ -55,21 +56,26 @@ ipmg --discover --compare   # later: scan again and see what changed
 
 ## How it compares
 
-| | IPMG | `nmap -sn` | `fping` | Angry IP Scanner |
+| | IPMG | nmap | fping | Uptime Kuma |
 | --- | --- | --- | --- | --- |
-| Parallel ping sweep | Yes, one system `ping` per host | Yes | Yes, fastest of the four | Yes |
-| Scan history and "what changed" | Built in | Save XML, compare with `ndiff` | No | No |
-| Change severities and alerts | critical / warning / info; Slack, Teams, webhook, email | No | No | No |
-| Exit codes for cron and CI | `3` with `--fail-on-down`, `2` with `diff --fail-on-change` | No | Non-zero if any host is unreachable | No (GUI first) |
-| Reports | Excel, CSV, JSON, Markdown | XML, grepable text | Plain text | CSV, TXT, XML |
-| Browser UI | IPMG Web, local, works offline | No (Zenmap is a desktop app) | No | Desktop app (Java) |
-| Port checks | Common TCP ports (connect only) | Full port, service, and OS scanner | No | Via fetchers |
+| Primary purpose | Network discovery, scan history, and what changed | Network discovery and security auditing ([nmap.org](https://nmap.org/)) | Fast ICMP reachability for many hosts at once ([man page](https://fping.org/fping.8.html)) | Self-hosted uptime monitoring of individual services ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| Ping sweeps of CIDR blocks and ranges | Yes, one system `ping` per host, `--threads` at a time | Yes, `-sn` host discovery ([docs](https://nmap.org/book/man-host-discovery.html)) | Yes, round-robin from one process with `-g`; the fastest here ([man page](https://fping.org/fping.8.html)) | No: one Ping monitor per host ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| TCP checks | Connect checks on chosen ports, and `--probe tcp` for hosts that block ping | A full port scanner ([docs](https://nmap.org/book/man-port-scanning-techniques.html)) | No ([man page](https://fping.org/fping.8.html)) | A TCP monitor per host and port ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| HTTP checks | `--http-check`: status, time, redirects, TLS, certificate expiry | Through NSE scripts such as `http-title` ([NSE](https://nmap.org/nsedoc/scripts/http-title.html)) | No ([man page](https://fping.org/fping.8.html)) | HTTP(s), keyword, and JSON query monitors ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| History and "what changed" | Built in: every scan stored, changes with severities | Save XML, compare two scans with `ndiff` ([ndiff](https://nmap.org/ndiff/)) | No ([man page](https://fping.org/fping.8.html)) | Up/down state and ping charts per monitor ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| Alerts | Slack, Teams, webhook, email, filtered by severity | No; it writes output files for other tools ([output](https://nmap.org/book/man-output.html)) | No ([man page](https://fping.org/fping.8.html)) | 90+ notification services ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| Exit codes for cron and CI | `3` with `--fail-on-down`, `2` with `diff --fail-on-change` | No; parse its XML output instead ([output](https://nmap.org/book/man-output.html)) | `1` if any host is unreachable ([man page](https://fping.org/fping.8.html)) | Not a command-line tool ([install](https://github.com/louislam/uptime-kuma#-how-to-install)) |
+| Reports | Excel, CSV, JSON, JSON Lines, Markdown | Normal, XML, grepable ([output](https://nmap.org/book/man-output.html)) | Plain text, with summaries (`-s`, `-C`) ([man page](https://fping.org/fping.8.html)) | Status pages ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| Browser UI | IPMG Web: local, offline, with scheduled scans | No; Zenmap is a desktop app ([Zenmap](https://nmap.org/zenmap/)) | No ([man page](https://fping.org/fping.8.html)) | It is a web app ([features](https://github.com/louislam/uptime-kuma#-features)) |
+| Install | `pip`, `uv`, one-line installers, Homebrew, Docker | Packages and installers ([download](https://nmap.org/download.html)) | From source, or Docker ([README](https://github.com/schweikert/fping#installation)) | Docker, or Node.js ([install](https://github.com/louislam/uptime-kuma#-how-to-install)) |
 
 Where the others are better: **nmap** is a real port, service, and OS
 scanner, and IPMG does not try to be one. **fping** sends every probe from a
 single process, so on large ranges it is much faster than IPMG, which starts
-one `ping` per host (`--threads` at a time). Angry IP Scanner is a
-point-and-click desktop app with a plugin system.
+one `ping` per host. **Uptime Kuma** is built for watching a fixed set of
+services around the clock, with status pages to share. [Angry IP
+Scanner](https://angryip.org/) is a point-and-click desktop scanner with a
+plugin system.
 
 Reach for IPMG when you look after a network and need to know what moved since
 yesterday, with a report you can hand to someone.
@@ -99,7 +105,9 @@ That means:
 | Linux (iputils or busybox `ping`) | `ping -c COUNT -W SECONDS` | Supported. CI runs the tests and a scan on Ubuntu; see [verified environments](#verified-environments) |
 | macOS | `ping -c COUNT -W MILLISECONDS`; `ping6` for IPv6 | Supported. CI runs the tests and a scan on macOS |
 | Windows | `ping -n COUNT -w MILLISECONDS` | Supported. CI runs the tests and a scan of `127.0.0.1` on `windows-latest`; not yet verified against a real LAN |
-| FreeBSD, OpenBSD, NetBSD | the macOS flags | Untested. The code treats them like macOS, and their `ping` options may differ |
+| FreeBSD | `ping -c COUNT -W MILLISECONDS`; `ping6` for IPv6 | Probed in a FreeBSD VM in CI when the ping code changes |
+| OpenBSD | `ping -c COUNT -w SECONDS`; `ping6` for IPv6 | Probed in an OpenBSD VM in CI when the ping code changes |
+| NetBSD | `ping -c COUNT -w DEADLINE`; `ping6 -x MILLISECONDS` for IPv6 | Probed in a NetBSD VM in CI when the ping code changes |
 
 `--discover ipv6` reads the neighbour table with `ip -6 neigh` on Linux (the
 `iproute2` package), `ndp -an` on macOS, and `netsh` on Windows.
@@ -144,10 +152,12 @@ irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1 | iex
 
 It works in Windows PowerShell 5.1 and PowerShell 7 and needs no
 administrator rights: it installs uv if it is missing, installs IPMG, adds it
-to your user `PATH`, and checks that `ipmg --version` runs. To pin a release:
+to your user `PATH`, and checks that `ipmg --version` runs. To pin a release,
+replace `X.Y.Z` with any version listed on
+[PyPI](https://pypi.org/project/ipmg/#history):
 
 ```powershell
-& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1))) -Version 2.3.0
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.ps1))) -Version X.Y.Z
 ```
 
 **Docker (amd64 and arm64):**
@@ -191,7 +201,7 @@ docker compose run --rm scan --input 10.0.0.0/24          # CLI scans land in th
 
 Publishing the port more widely (`8080:8080`) exposes IPMG Web on your
 network over plain HTTP; put a reverse proxy with TLS in front first. Images
-are tagged with the release version (`2.4.0`), the minor line (`2.4`), and
+are tagged with the release version (`X.Y.Z`), the minor line (`X.Y`), and
 `latest`.
 
 ### Installing with pip
@@ -239,6 +249,19 @@ The one-line installers, Homebrew, and the Docker image install it with the
 `web` extra already. Run `ipmg web` without it and IPMG tells you the command
 that adds it.
 
+### Tab completion
+
+`ipmg completion SHELL` prints a completion script for commands, flags, their
+choices, and file names. It is generated from IPMG's own flag definitions, so
+it never falls behind; run it again after an upgrade.
+
+| Shell | Add this |
+| --- | --- |
+| bash | `eval "$(ipmg completion bash)"` in `~/.bashrc` (bash 3.2 and later; no bash-completion package needed) |
+| zsh | `eval "$(ipmg completion zsh)"` in `~/.zshrc`, after `compinit`; or save it as `_ipmg` in a directory on your `$fpath` |
+| fish | `ipmg completion fish > ~/.config/fish/completions/ipmg.fish` |
+| PowerShell | `ipmg completion powershell \| Out-String \| Invoke-Expression` in your `$PROFILE` |
+
 ### The one thing IPMG needs from your system
 
 IPMG probes hosts with your operating system's `ping` command, and minimal
@@ -259,13 +282,17 @@ IPMG runs the same `ping` you would run by hand.
 
 ### Verified environments
 
-Each of these was installed from scratch and run against a live target:
+The installer is tested in each of these whenever `install.sh` changes, and
+weekly: a fresh install as root with `--with-deps`, then a scan
+([workflow](https://github.com/sameeralam3127/ipmg/actions/workflows/install-sh.yml)).
+macOS and Ubuntu are also tested as a normal user, as are a pinned
+`--version` and an upgrade over an existing install.
 
 | Environment | Notes |
 | --- | --- |
 | Ubuntu 22.04 / 24.04 | 24.04 blocks `pip install`; the installer is unaffected |
 | Debian 12 | same PEP 668 situation as Ubuntu |
-| RHEL 8 / RHEL 9 (UBI), Rocky 9 | RHEL 8's system Python is 3.6 — uv supplies its own |
+| RHEL 8 / RHEL 9 (UBI), Rocky 9 | RHEL 8's system Python is 3.6; uv supplies its own |
 | Fedora 41 | |
 | openSUSE Leap 15.6 | image has no Python at all; installer supplies everything |
 | Alpine 3.20 | run the installer with `bash`, not `sh` |
@@ -287,10 +314,11 @@ one of them.
 uv tool install ipmg
 ```
 
-**Pin a specific version:**
+**Pin a specific version** (any release listed on
+[PyPI](https://pypi.org/project/ipmg/#history)):
 
 ```bash
-curl -sSL https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.sh | bash -s -- --version 1.13.0
+curl -sSL https://raw.githubusercontent.com/sameeralam3127/ipmg/main/install.sh | bash -s -- --version X.Y.Z
 ```
 
 **From source (development):**
@@ -333,7 +361,7 @@ ipmg --input targets.txt              # a file of hosts
 Here is what a finished scan looks like:
 
 ```text
-  ipmg 1.13.0  ·  scan
+  ipmg X.Y.Z  ·  scan
   ICMP probes only — scan only networks you are authorized to scan.
 
   Source   targets.txt
@@ -464,6 +492,7 @@ Or pick a ready-made command:
 | See what changed since last time | `ipmg --input targets.txt --compare` |
 | Check which services are listening | `ipmg --input targets.txt --scan-ports` |
 | Keep scanning every 5 minutes | `ipmg --input targets.txt --interval 5` |
+| Keep it running after logout and reboots | the systemd and launchd templates in [docs/SERVICES.md](https://github.com/sameeralam3127/ipmg/blob/main/docs/SERVICES.md) |
 | Look back at earlier scans | `ipmg history` |
 | Compare two specific scans | `ipmg diff 12 14` |
 | Use IPMG Web in your browser instead | `ipmg web` |
@@ -764,6 +793,66 @@ them — so piping IPMG into a file or a log gives you clean text.
 
 ---
 
+## In GitHub Actions
+
+This repository is also a GitHub Action: a pipeline step that checks your
+infrastructure is reachable and fails the job when it is not. It installs IPMG
+with uv, scans, writes a summary of the hosts that are down to the job page,
+and uploads the reports as an artifact, even when the step fails.
+
+Before a deploy:
+
+```yaml
+- name: Check the database and cache hosts are up
+  uses: sameeralam3127/ipmg@vX.Y.Z      # any IPMG release tag
+  with:
+    targets: 10.0.4.10 10.0.4.11 10.0.5.0/28
+    fail-on-down: true
+    args: --probe icmp,tcp --ports 5432,6379
+```
+
+On a schedule, with the reports kept and a Slack alert for changes (the
+history lives in the cached database):
+
+```yaml
+on:
+  schedule: [{ cron: "*/30 * * * *" }]
+jobs:
+  reachability:
+    runs-on: [self-hosted, office-lan]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/cache@v6
+        with: { path: ipmg-history, key: "ipmg-${{ github.run_id }}", restore-keys: ipmg- }
+      - uses: sameeralam3127/ipmg@vX.Y.Z
+        with:
+          targets: targets.txt
+          args: --db ipmg-history/history.db --compare --notify-slack
+          formats: csv md
+        env:
+          IPMG_NOTIFY_SLACK: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `targets` | (required) | IPs, CIDR blocks, ranges, or target files, separated by spaces or newlines |
+| `args` | | Extra IPMG flags, split on whitespace |
+| `version` | `latest` | The IPMG release to install, such as `3.2.0` |
+| `fail-on-down` | `false` | Fail the step when any target is not Active |
+| `formats` | `csv json md` | Report formats to write |
+| `upload-artifact` | `true` | Upload the reports as an artifact |
+| `artifact-name` | `ipmg-reports` | The artifact's name |
+
+Outputs: `active` and `total` host counts, `report-path`, and `exit-code`.
+
+GitHub-hosted runners generally cannot ping hosts outside GitHub's network,
+and cannot reach your private networks at all. For a LAN or a VPC, use a
+[self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners)
+inside it; for public hosts that drop ICMP, add `--probe tcp` or `--probe
+icmp,tcp` to `args`, or check the service itself with `--http-check`.
+
+---
+
 ## Default options in a file
 
 If every run repeats the same flags, put them in **`ipmg.toml`** next to your
@@ -939,7 +1028,9 @@ Contributions are welcome.
 [CONTRIBUTING.md](https://github.com/sameeralam3127/ipmg/blob/main/.github/CONTRIBUTING.md)
 covers setting up a development environment, running the tests, the commit
 message format that drives automated releases, and how the project website and
-IPMG Web demo are built. Everyone taking part is expected to follow the
+IPMG Web demo are built.
+[docs/ARCHITECTURE.md](https://github.com/sameeralam3127/ipmg/blob/main/docs/ARCHITECTURE.md)
+explains how the code fits together. Everyone taking part is expected to follow the
 [Code of Conduct](https://github.com/sameeralam3127/ipmg/blob/main/.github/CODE_OF_CONDUCT.md).
 
 ---

{ipmg-3.1.4 → ipmg-3.2.0}/pyproject.toml

@@ -13,8 +13,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ipmg"
-version = "3.1.4"  # Managed automatically by semantic-release
-description = "IP Management & Ping Monitoring CLI Tool"
+version = "3.2.0"  # Managed automatically by semantic-release
+description = "Network discovery and change detection: ping sweeps, scan history, and reports for what changed on your network"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"
@@ -83,7 +83,11 @@ dev = [
     "ruff>=0.4",
     "pre-commit>=3.5.0",
     "python-semantic-release>=10.5.3",
+    # The TestClient's HTTP client. Starlette 1.x wants httpx2 and warns
+    # about httpx; the Starlette releases Python 3.9 and the lowest-deps job
+    # resolve to predate httpx2 and need httpx.
     "httpx>=0.27",
+    "httpx2>=2.0; python_version >= '3.10'",
 ]
 
 [project.scripts]
@@ -102,7 +106,11 @@ dev = [
     "ruff>=0.4",
     "pre-commit>=3.5.0",
     "python-semantic-release>=10.5.3",
+    # The TestClient's HTTP client. Starlette 1.x wants httpx2 and warns
+    # about httpx; the Starlette releases Python 3.9 and the lowest-deps job
+    # resolve to predate httpx2 and need httpx.
     "httpx>=0.27",
+    "httpx2>=2.0; python_version >= '3.10'",
 ]
 
 
@@ -136,6 +144,7 @@ package-dir = { "" = "src" }
 where = ["src"]
 
 [tool.setuptools.package-data]
+"ipmg" = ["data/*.tsv.gz"]
 "ipmg.web" = ["static/*.html", "static/css/*.css", "static/js/*.js"]
 
 
@@ -146,6 +155,13 @@ where = ["src"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]
+# A deprecated call in IPMG's own code or tests fails the run, so the next
+# one is fixed when it appears instead of scrolling past in the output.
+filterwarnings = [
+    "error::DeprecationWarning:ipmg",
+    "error::DeprecationWarning:test_",
+    "error::PendingDeprecationWarning:ipmg",
+]
 
 [tool.coverage.run]
 source = ["ipmg"]

{ipmg-3.1.4 → ipmg-3.2.0}/src/ipmg/__init__.py

@@ -2,4 +2,4 @@
 ipmg - IP Management & Ping Monitoring Tool
 """
 
-__version__ = "3.1.4"
+__version__ = "3.2.0"