Merge pull request linux-nvme#471 from martin-belanger/doc-updates

docs: updating docs with nvme-stas vs nvme-cli comparison

Author: martin-belanger

NVME-STAS-CLI_COMPARISON.md

@@ -0,0 +1,15 @@
+# Feature Comparison: nvme-stas vs. nvme-cli
+
+| Feature | nvme-stas | nvme-cli |
+| --- | --- | --- |
+| IP address family filter | **Yes** – configured via `ip-family=[ipv4, ipv6, ipv4+ipv6]` in `/etc/stas/*.conf` | **No** |
+| Automatic DIM registration with a Central Discovery Controller (CDC) per TP8010 | **Yes** | **No** – manual only via `nvme dim` |
+| Automatic (zeroconf) discovery of Direct/Central Discovery Controllers (DDC/CDC) | **Yes** – registers with the Avahi daemon to receive mDNS notifications when CDCs or DDCs are detected, and connects to them automatically | **No** |
+| Manual Discovery Controller (DC) configuration with explicit include/exclude | **Yes** – use `controller=` and `exclude=` in `/etc/stas/stafd.conf`; exclusions are useful for filtering out unwanted mDNS-discovered DCs | **Partial** – no way to exclude DCs (moot since mDNS is not supported); use `/etc/nvme/discovery.conf` to include controllers |
+| Manual I/O Controller (IOC) configuration with explicit include/exclude | **Yes** – use `controller=` and `exclude=` in `/etc/stas/stacd.conf`; exclusions filter out unwanted IOCs from log pages (ideally handled via proper zone definitions at the DC) | **Partial** – JSON config files are supported, but excluding IOCs is not possible |
+| AEN monitoring + automatic connection/disconnection for Fabric Zoning | **Yes** – responds to Fabric Zoning changes with connect and disconnect operations with retries (configurable via `/etc/stas/stacd.conf`) | **Partial** – responds to Fabric Zoning changes with connect-only, no retries (one-shot udev rule) |
+| Use PLEO bit to retrieve only Port Local Entries from log pages | **Yes** | **No** |
+| Automatic Layer 3 connectivity without static routes | **Yes** – configurable via `ignore-iface=` in `/etc/stas/*.conf` | **No** – manual only via `--host-iface` |
+| Explicit exclusion of specific discovery interfaces | **Yes** – use `exclude = host-iface=<interface>` in `/etc/stas/*.conf` | **No** – not applicable without mDNS support |
+| AVE client support | **Planned** (implementation TBD) | **No** |
+| Human-friendly `nvme list` output | **No** – `stafctl` and `stacctl` output JSON only; not a significant gap since `nvme list -v` covers this well | **Yes** – via `nvme list -v` |

README.md

@@ -19,6 +19,14 @@
 - **Error handling and reporting**
 - Support for both **automatic (zeroconf)** and **manual configuration**
 
+## Why nvme-stas Instead of nvme-cli?
+
+*nvme-stas* was designed specifically to support the NVMe-oF Technical Proposals **TP8009** (Automated Discovery of NVMe-oF Discovery Controllers for IP Networks) and **TP8010** (NVMe-oF Centralized Discovery Controller), which cannot be implemented in [nvme-cli](https://github.com/linux-nvme/nvme-cli) / libnvme.
+
+The fundamental reason is that **nvme-cli is stateless**: it issues one-off commands and exits. TP8009 and TP8010 require a host to *maintain persistent state* — registering with a Central Discovery Controller (CDC), tracking Asynchronous Event Notifications (AENs), reacting to Fabric Zoning changes with automatic connect and disconnect operations, and retrying failed connections. These are inherently long-running, event-driven behaviors that a stateless CLI tool cannot provide.
+
+*nvme-stas* fills that gap by implementing two cooperating systemd daemons (*stafd* and *stacd*) that continuously monitor the NVMe-oF fabric and manage controller connections on behalf of the host. For a detailed feature-by-feature comparison, see [NVME-STAS-CLI_COMPARISON.md](./NVME-STAS-CLI_COMPARISON.md).
+
 ## High-Level Overview
 
 *nvme-stas* is composed of two cooperating services:

etc/stas/stacd.conf

@@ -97,7 +97,7 @@
 #
 #               Type:    boolean
 #               Range:   [false, true]
-#               Default: true
+#               Default: false
 #ignore-iface=false
 
 # ip-family: With this you can specify whether stacd will support IPv4, IPv6,

etc/stas/stafd.conf

@@ -77,7 +77,7 @@
 #
 #               Type:    boolean
 #               Range:   [false, true]
-#               Default: true
+#               Default: false
 #ignore-iface=false
 
 # ip-family: With this you can specify whether stafd will support IPv4, IPv6,