nvme: rework the registry command-line interface

Documentation/nvme-registry-delete.txt

@@ -3,30 +3,42 @@ nvme-registry-delete(1)
 
 NAME
 ----
-nvme-registry-delete - Remove a controller's ownership registry entry
+nvme-registry-delete - Remove a controller's registry entry or attribute
 
 SYNOPSIS
 --------
 [verse]
-'nvme' [<global-options>] 'registry delete'
-			--device=<DEV> | -d <DEV>
+'nvme' [<global-options>] 'registry delete' <device>
+			[--attr=<ATTR> | -a <ATTR>]
 
 DESCRIPTION
 -----------
-Remove the ownership registry entry for an NVMe-oF controller.  The
-registry entry is the directory /run/nvme/registry/<device>/ and all
-attribute files it contains.
+Remove the ownership registry entry for an NVMe-oF controller, or a single
+attribute from it.  The registry entry is the directory
+/run/nvme/registry/<device>/ and all attribute files it contains.
+
+The <device> is the NVMe controller name (e.g. nvme3), given as a
+positional argument; the /dev/ prefix is optional.
+
+Without --attr the whole entry is removed.  With --attr only that one
+attribute file is removed, leaving the rest of the entry in place.
 
 Under normal operation registry entries are removed automatically: a
 udev rule fires on the kernel REMOVE event and deletes the entry.  This
 command is provided for manual cleanup or for orchestrators that want to
 explicitly release ownership before disconnecting.
 
+Removing the whole entry, or the 'owner' attribute specifically, drops
+ownership and can stop an orchestrator from protecting the controller, so
+it prompts for confirmation when run interactively; non-interactive callers
+(scripts) proceed without prompting.  Removing any other attribute does not
+affect ownership and proceeds silently.
+
 OPTIONS
 -------
--d <DEV>::
---device=<DEV>::
-	NVMe device name (e.g. nvme3).  The /dev/ prefix is optional.
+-a <ATTR>::
+--attr=<ATTR>::
+	Attribute to remove.  If omitted, the whole entry is removed.
 
 include::global-options.txt[]
 
@@ -35,7 +47,13 @@ EXAMPLES
 * Remove the registry entry for nvme3:
 +
 ------------
-# nvme registry delete --device nvme3
+# nvme registry delete nvme3
+------------
+
+* Remove a single attribute, leaving the rest of the entry:
++
+------------
+# nvme registry delete nvme3 --attr note
 ------------
 
 SEE ALSO

Documentation/nvme-registry-retrieve.txt

@@ -8,9 +8,8 @@ nvme-registry-retrieve - Read an attribute from a controller's registry entry
 SYNOPSIS
 --------
 [verse]
-'nvme' [<global-options>] 'registry retrieve'
-			--device=<DEV> | -d <DEV>
-			[--attr=<ATTR> | -a <ATTR>]
+'nvme' [<global-options>] 'registry retrieve' <device>
+			--attr=<ATTR> | -a <ATTR>
 
 DESCRIPTION
 -----------
@@ -19,33 +18,23 @@ controller.  The registry is stored under /run/nvme/registry/ as one
 directory per live controller, with one plain-text file per attribute
 (e.g. /run/nvme/registry/nvme3/owner).
 
-If --attr is omitted the 'owner' attribute is retrieved.
+The <device> is the NVMe controller name (e.g. nvme3), given as a
+positional argument; the /dev/ prefix is optional.
 
 OPTIONS
 -------
--d <DEV>::
---device=<DEV>::
-	NVMe device name (e.g. nvme3).  The /dev/ prefix is optional.
-
 -a <ATTR>::
 --attr=<ATTR>::
-	Attribute name to retrieve.  Defaults to 'owner'.
+	Attribute name to retrieve (e.g. owner, note).  Required.
 
 include::global-options.txt[]
 
 EXAMPLES
 --------
-* Retrieve the owner of nvme3 (default attribute):
-+
-------------
-# nvme registry retrieve --device nvme3
-stas
-------------
-
-* Retrieve a specific attribute:
+* Retrieve the owner of nvme3:
 +
 ------------
-# nvme registry retrieve --device nvme3 --attr owner
+# nvme registry retrieve nvme3 --attr owner
 stas
 ------------
 

Documentation/nvme-registry-update.txt

@@ -8,36 +8,36 @@ nvme-registry-update - Write an attribute to a controller's registry entry
 SYNOPSIS
 --------
 [verse]
-'nvme' [<global-options>] 'registry update'
-			--device=<DEV> | -d <DEV>
+'nvme' [<global-options>] 'registry update' <device>
 			--attr=<ATTR> | -a <ATTR>
 			--value=<VAL> | -V <VAL>
 
 DESCRIPTION
 -----------
-Write a non-owner attribute to the ownership registry entry for an
-NVMe-oF controller.  The registry is stored under /run/nvme/registry/ as
-one directory per live controller, with one plain-text file per
-attribute.  The entry directory is created if it does not already exist.
+Write an attribute to the ownership registry entry for an NVMe-oF
+controller.  The registry is stored under /run/nvme/registry/ as one
+directory per live controller, with one plain-text file per attribute.
+The entry directory is created if it does not already exist.
 
-The 'owner' attribute is immutable: it is recorded when the connection is
-created (e.g. by 'nvme connect --owner') and cannot be changed by this
-command.  Attempting to update 'owner' is rejected.  Use this command for
-auxiliary attributes such as a free-form 'note'.
+The <device> is the NVMe controller name (e.g. nvme3), given as a
+positional argument; the /dev/ prefix is optional.
+
+The 'owner' attribute is normally recorded when the connection is created
+(e.g. by 'nvme connect --owner').  Changing it by hand can stop an
+orchestrator from protecting the controller, so updating 'owner' prompts
+for confirmation when run interactively; non-interactive callers (scripts)
+proceed without prompting.  This is a guard against accidental mistakes,
+not access control -- a user with root can edit the files under
+/run/nvme/registry/ directly.
 
 Writes are atomic: a temporary file is written and synced, then renamed
 into place, preventing corruption under concurrent access.
 
 OPTIONS
 -------
--d <DEV>::
---device=<DEV>::
-	NVMe device name (e.g. nvme3).  The /dev/ prefix is optional.
-
 -a <ATTR>::
 --attr=<ATTR>::
-	Attribute name to write (e.g. note).  The reserved 'owner'
-	attribute is immutable and cannot be written with this command.
+	Attribute name to write (e.g. note, owner).
 
 -V <VAL>::
 --value=<VAL>::
@@ -50,13 +50,13 @@ EXAMPLES
 * Attach a free-form note to nvme3:
 +
 ------------
-# nvme registry update --device nvme3 --attr note --value "maintenance 2026-07"
+# nvme registry update nvme3 --attr note --value "maintenance 2026-07"
 ------------
 
 * Update a previously written note:
 +
 ------------
-# nvme registry update --device nvme3 --attr note --value "released"
+# nvme registry update nvme3 --attr note --value "released"
 ------------
 
 SEE ALSO