linux-nvme · igaw · Jul 2, 2026 · Jul 1, 2026 · Jun 29, 2026 · Jun 30, 2026
diff --git a/Documentation/meson.build b/Documentation/meson.build
@@ -30,6 +30,12 @@ adoc_sources = [
     'nvme-endurance-event-agg-log',
     'nvme-endurance-log',
     'nvme-error-log',
+    'nvme-exclusion-add',
+    'nvme-exclusion-create',
+    'nvme-exclusion-delete',
+    'nvme-exclusion-edit',
+    'nvme-exclusion-list',
+    'nvme-exclusion-remove',
     'nvme-fdp-configs',
     'nvme-fdp-events',
     'nvme-fdp-feature',

diff --git a/Documentation/nvme-disconnect.txt b/Documentation/nvme-disconnect.txt
@@ -10,6 +10,7 @@ SYNOPSIS
 [verse]
 'nvme' [<global-options>] 'disconnect' [--nqn=<subnqn> | -n <subnqn>]
 			[--device=<device> | -d <device>]
+			[--exclude | -x]
 
 DESCRIPTION
 -----------
@@ -18,6 +19,12 @@ If the --nqn option is specified all controllers connecting to the Subsystem
 identified by subnqn will be removed. If the --device option is specified
 the controller specified by the --device option will be removed.
 
+With --exclude, a matching entry is written to the system-wide NVMe-oF
+exclusion list before the controller (or subsystem) is torn down, so that a
+cooperating orchestrator sees the exclusion in place before the removal event
+fires and does not immediately reconnect. See nvme-exclusion-add(1) and the
+exclusion list overview for details.
+
 OPTIONS
 -------
 -n <subnqn>::
@@ -30,6 +37,13 @@ OPTIONS
 	Indicates that the controller with the specified name should be
 	removed.
 
+-x::
+--exclude::
+	Write a matching entry to the 'user' exclusion list before
+	disconnecting, so orchestrators do not auto-reconnect the
+	controller. The entry is built from the controller's transport
+	parameters (or, with --nqn, from the subsystem NQN).
+
 include::global-options.txt[]
 
 EXAMPLES
@@ -47,9 +61,16 @@ nqn.2014-08.com.example:nvme:nvm-subsystem-sn-d78432:
 # nvme disconnect --device=nvme4
 ------------
 
+* Disconnect nvme4 and exclude it so orchestrators do not reconnect it:
++
+------------
+# nvme disconnect --device=nvme4 --exclude
+------------
+
 SEE ALSO
 --------
 nvme-connect(1)
+nvme-exclusion-add(1)
 
 NVME
 ----

diff --git a/Documentation/nvme-exclusion-add.txt b/Documentation/nvme-exclusion-add.txt
@@ -0,0 +1,67 @@
+nvme-exclusion-add(1)
+=====================
+
+NAME
+----
+nvme-exclusion-add - Add an entry to an NVMe-oF exclusion list
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'exclusion add' --name=<NAME> | -N <NAME>
+			--entry=<ENTRY> | -e <ENTRY>
+
+DESCRIPTION
+-----------
+Append an entry to the NVMe-oF exclusion list named <NAME>, creating the
+list if it does not exist.  The entry is a semicolon-separated list of
+key=value fields; a controller is excluded when it matches every field
+present in the entry.
+
+The recognized field keys are the 'nvme connect' option names: transport,
+traddr, trsvcid, nqn, host-traddr, host-iface, hostnqn and hostid.  Only
+the fields given are matched, so a single key excludes broadly and more
+keys narrow the match.  See the exclusion list overview (EXCLUSIONS.md)
+for the full match semantics.
+
+The entry is validated before it is written; an entry with an unknown
+key, or with no recognized field, is rejected.  This command requires
+root.
+
+OPTIONS
+-------
+-N <NAME>::
+--name=<NAME>::
+	Name of the exclusion list to add to.
+
+-e <ENTRY>::
+--entry=<ENTRY>::
+	The entry to add, e.g. "transport=tcp;traddr=192.0.2.10;nqn=...".
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Exclude a single path to a subsystem:
++
+------------
+# nvme exclusion add --name user \
+	--entry "transport=tcp;traddr=192.0.2.10;trsvcid=4420;nqn=nqn.2024-01.com.example:vol1"
+------------
+
+* Exclude a whole subsystem on every transport and address:
++
+------------
+# nvme exclusion add --name user --entry "nqn=nqn.2024-01.com.example:retired"
+------------
+
+SEE ALSO
+--------
+nvme-exclusion-remove(1)
+nvme-exclusion-list(1)
+nvme-exclusion-edit(1)
+nvme-disconnect(1)
+
+NVME
+----
+Part of the nvme-user suite
diff --git a/Documentation/nvme-exclusion-create.txt b/Documentation/nvme-exclusion-create.txt
@@ -0,0 +1,48 @@
+nvme-exclusion-create(1)
+========================
+
+NAME
+----
+nvme-exclusion-create - Create a new NVMe-oF exclusion list
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'exclusion create' --name=<NAME> | -N <NAME>
+
+DESCRIPTION
+-----------
+Create a new, empty NVMe-oF exclusion list named <NAME>, stored as
+/etc/nvme/exclusions.conf.d/<NAME>.conf.  The exclusion list names controllers
+that no orchestrator may auto-connect; see the exclusion list overview
+in the libnvme documentation (EXCLUSIONS.md) for the format, the field
+keys, and the match semantics.
+
+This command requires root.
+
+OPTIONS
+-------
+-N <NAME>::
+--name=<NAME>::
+	Name of the exclusion list to create.
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Create a list for controllers under maintenance:
++
+------------
+# nvme exclusion create --name maintenance
+------------
+
+SEE ALSO
+--------
+nvme-exclusion-add(1)
+nvme-exclusion-list(1)
+nvme-exclusion-delete(1)
+nvme-disconnect(1)
+
+NVME
+----
+Part of the nvme-user suite
diff --git a/Documentation/nvme-exclusion-delete.txt b/Documentation/nvme-exclusion-delete.txt
@@ -0,0 +1,46 @@
+nvme-exclusion-delete(1)
+========================
+
+NAME
+----
+nvme-exclusion-delete - Delete an NVMe-oF exclusion list
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'exclusion delete' --name=<NAME> | -N <NAME>
+
+DESCRIPTION
+-----------
+Delete the NVMe-oF exclusion list named <NAME> in its entirety, removing
+/etc/nvme/exclusions.conf.d/<NAME>.conf and every entry it contains.  To
+drop a single entry instead, use 'nvme exclusion remove'.
+
+This command requires root.
+
+OPTIONS
+-------
+-N <NAME>::
+--name=<NAME>::
+	Name of the exclusion list to delete.
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Remove the maintenance list once the work is done:
++
+------------
+# nvme exclusion delete --name maintenance
+------------
+
+SEE ALSO
+--------
+nvme-exclusion-remove(1)
+nvme-exclusion-list(1)
+nvme-exclusion-create(1)
+nvme-disconnect(1)
+
+NVME
+----
+Part of the nvme-user suite
diff --git a/Documentation/nvme-exclusion-edit.txt b/Documentation/nvme-exclusion-edit.txt
@@ -0,0 +1,60 @@
+nvme-exclusion-edit(1)
+======================
+
+NAME
+----
+nvme-exclusion-edit - Edit an NVMe-oF exclusion list in an editor
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'exclusion edit' --name=<NAME> | -N <NAME>
+
+DESCRIPTION
+-----------
+Open the NVMe-oF exclusion list named <NAME> in the editor named by the
+$EDITOR environment variable, in the same spirit as 'visudo' or
+'crontab -e'.  A missing list is created.
+
+The list is edited through a private scratch copy and installed by name
+only when the editor exits.  On save the result is validated; if it
+contains a bad entry you are offered the chance to re-open the editor and
+fix it.  If the list changed on disk while you were editing, the save is
+refused so a concurrent editor's changes are never silently overwritten.
+Whenever the changes are not saved, the scratch copy is kept and its path
+printed so your edits are recoverable.
+
+This command requires root.
+
+OPTIONS
+-------
+-N <NAME>::
+--name=<NAME>::
+	Name of the exclusion list to edit.
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Edit the 'user' list:
++
+------------
+# nvme exclusion edit --name user
+------------
+
+* Use a specific editor:
++
+------------
+# EDITOR=vi nvme exclusion edit --name user
+------------
+
+SEE ALSO
+--------
+nvme-exclusion-add(1)
+nvme-exclusion-remove(1)
+nvme-exclusion-list(1)
+nvme-disconnect(1)
+
+NVME
+----
+Part of the nvme-user suite
diff --git a/Documentation/nvme-exclusion-list.txt b/Documentation/nvme-exclusion-list.txt
@@ -0,0 +1,53 @@
+nvme-exclusion-list(1)
+======================
+
+NAME
+----
+nvme-exclusion-list - List NVMe-oF exclusion lists or their entries
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'exclusion list' [--name=<NAME> | -N <NAME>]
+
+DESCRIPTION
+-----------
+Without --name, print the name of every named exclusion list under
+/etc/nvme/exclusions.conf.d/.  With --name, print the entries contained
+in that one list.
+
+This command is read-only and does not require root.
+
+OPTIONS
+-------
+-N <NAME>::
+--name=<NAME>::
+	List the entries in the named exclusion list.  Omit to list all
+	exclusion lists instead.
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Show every exclusion list:
++
+------------
+# nvme exclusion list
+------------
+
+* Show the entries in the 'user' list:
++
+------------
+# nvme exclusion list --name user
+------------
+
+SEE ALSO
+--------
+nvme-exclusion-add(1)
+nvme-exclusion-remove(1)
+nvme-exclusion-create(1)
+nvme-disconnect(1)
+
+NVME
+----
+Part of the nvme-user suite
diff --git a/Documentation/nvme-exclusion-remove.txt b/Documentation/nvme-exclusion-remove.txt
@@ -0,0 +1,47 @@
+nvme-exclusion-remove(1)
+========================
+
+NAME
+----
+nvme-exclusion-remove - Remove an entry from an NVMe-oF exclusion list
+
+SYNOPSIS
+--------
+[verse]
+'nvme' [<global-options>] 'exclusion remove' --name=<NAME> | -N <NAME>
+
+DESCRIPTION
+-----------
+Interactively remove a single entry from the NVMe-oF exclusion list named
+<NAME>.  The current entries are shown and one is selected for removal;
+the rest of the list is left untouched.  To delete a whole list at once,
+use 'nvme exclusion delete'.
+
+This command requires root.
+
+OPTIONS
+-------
+-N <NAME>::
+--name=<NAME>::
+	Name of the exclusion list to remove an entry from.
+
+include::global-options.txt[]
+
+EXAMPLES
+--------
+* Remove an entry from the 'user' list:
++
+------------
+# nvme exclusion remove --name user
+------------
+
+SEE ALSO
+--------
+nvme-exclusion-add(1)
+nvme-exclusion-edit(1)
+nvme-exclusion-delete(1)
+nvme-disconnect(1)
+
+NVME
+----
+Part of the nvme-user suite