Skip to content

Commit 4283407

Browse files
author
Martin Belanger
committed
nvme: add man pages for registry commands and update disconnect-all
Add man pages for the four new registry subcommands: nvme-registry-list(1) nvme-registry-retrieve(1) nvme-registry-update(1) nvme-registry-delete(1) Update nvme-disconnect-all(1) to document the new ownership-aware default behavior and the --owner, --force, and --transport options. The --transport option was already implemented but undocumented. Signed-off-by: Martin Belanger <martin.belanger@dell.com> Assisted-by: Claude:claude-sonnet-4-6 [Claude Code]
1 parent 797044b commit 4283407

5 files changed

Lines changed: 255 additions & 2 deletions

File tree

‎Documentation/nvme-disconnect-all.txt‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,30 +9,67 @@ SYNOPSIS
99
--------
1010
[verse]
1111
'nvme' [<global-options>] 'disconnect-all'
12+
[--transport=<STR> | -r <STR>]
13+
[--owner=<NAME> | -O <NAME>]
14+
[--force | -f]
1215

1316
DESCRIPTION
1417
-----------
15-
Disconnects and removes all existing NVMe over Fabrics controllers.
18+
Disconnects and removes NVMe over Fabrics controllers. The default
19+
behavior is ownership-aware: only controllers with no entry in the
20+
ownership registry are disconnected. Controllers registered to an
21+
orchestrator (e.g. nvme-stas, nbft) are left untouched.
22+
23+
Use --owner to target a specific orchestrator's controllers, or --force
24+
to disconnect all controllers regardless of ownership. --force and
25+
--owner are mutually exclusive. When --force is used interactively a
26+
confirmation prompt is shown.
1627

1728
See the documentation for the nvme-disconnect(1) command for further
1829
background.
1930

2031
OPTIONS
2132
-------
33+
-r <STR>::
34+
--transport=<STR>::
35+
Limit disconnection to controllers using the specified transport
36+
(e.g. tcp, rdma, fc).
37+
38+
-O <NAME>::
39+
--owner=<NAME>::
40+
Disconnect only controllers owned by NAME in the registry.
41+
42+
-f::
43+
--force::
44+
Disconnect all controllers regardless of ownership. Requires
45+
interactive confirmation when stdin is a terminal.
2246

2347
include::global-options.txt[]
2448

2549
EXAMPLES
2650
--------
27-
* Disconnect all existing nvme controllers:
51+
* Disconnect all unowned controllers (safe default):
2852
+
2953
------------
3054
# nvme disconnect-all
3155
------------
56+
+
57+
* Disconnect all controllers owned by nvme-stas:
58+
+
59+
------------
60+
# nvme disconnect-all --owner stas
61+
------------
62+
+
63+
* Disconnect all controllers regardless of ownership:
64+
+
65+
------------
66+
# nvme disconnect-all --force
67+
------------
3268

3369
SEE ALSO
3470
--------
3571
nvme-disconnect(1)
72+
nvme-registry-list(1)
3673

3774
NVME
3875
----

‎Documentation/nvme-registry-delete.txt‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
nvme-registry-delete(1)
2+
=======================
3+
4+
NAME
5+
----
6+
nvme-registry-delete - Remove a controller's ownership registry entry
7+
8+
SYNOPSIS
9+
--------
10+
[verse]
11+
'nvme' [<global-options>] 'registry-delete'
12+
--device=<DEV> | -d <DEV>
13+
14+
DESCRIPTION
15+
-----------
16+
Remove the ownership registry entry for an NVMe-oF controller. The
17+
registry entry is stored at /run/nvme/registry/<device>.json.
18+
19+
Under normal operation registry entries are removed automatically: a
20+
udev rule fires on the kernel REMOVE event and deletes the entry. This
21+
command is provided for manual cleanup or for orchestrators that want to
22+
explicitly release ownership before disconnecting.
23+
24+
OPTIONS
25+
-------
26+
-d <DEV>::
27+
--device=<DEV>::
28+
NVMe device name (e.g. nvme3).
29+
30+
include::global-options.txt[]
31+
32+
EXAMPLES
33+
--------
34+
* Remove the registry entry for nvme3:
35+
+
36+
------------
37+
# nvme registry-delete --device nvme3
38+
------------
39+
40+
SEE ALSO
41+
--------
42+
nvme-registry-list(1)
43+
nvme-registry-retrieve(1)
44+
nvme-registry-update(1)
45+
nvme-disconnect-all(1)
46+
47+
NVME
48+
----
49+
Part of the nvme-user suite

‎Documentation/nvme-registry-list.txt‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
nvme-registry-list(1)
2+
=====================
3+
4+
NAME
5+
----
6+
nvme-registry-list - List NVMe-oF controller ownership registry entries
7+
8+
SYNOPSIS
9+
--------
10+
[verse]
11+
'nvme' [<global-options>] 'registry-list'
12+
13+
DESCRIPTION
14+
-----------
15+
List all live entries in the NVMe-oF controller ownership registry. The
16+
registry records which orchestrator (e.g. nvme-stas, nbft) owns each
17+
connected NVMe-oF controller. It is stored under /run/nvme/registry/ as
18+
one JSON file per live controller.
19+
20+
One line is printed per live registered controller. Controllers with no
21+
registry entry (unowned) and PCIe/apple-nvme controllers (which are never
22+
registered) are not shown.
23+
24+
OPTIONS
25+
-------
26+
27+
include::global-options.txt[]
28+
29+
EXAMPLES
30+
--------
31+
* List all owned controllers:
32+
+
33+
------------
34+
# nvme registry-list
35+
DEVICE OWNER
36+
nvme1 stas
37+
nvme3 nbft
38+
------------
39+
40+
SEE ALSO
41+
--------
42+
nvme-registry-retrieve(1)
43+
nvme-registry-update(1)
44+
nvme-registry-delete(1)
45+
nvme-disconnect-all(1)
46+
47+
NVME
48+
----
49+
Part of the nvme-user suite

‎Documentation/nvme-registry-retrieve.txt‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
nvme-registry-retrieve(1)
2+
=========================
3+
4+
NAME
5+
----
6+
nvme-registry-retrieve - Retrieve a field from a controller's registry entry
7+
8+
SYNOPSIS
9+
--------
10+
[verse]
11+
'nvme' [<global-options>] 'registry-retrieve'
12+
[--device=<DEV> | -d <DEV>]
13+
[--key=<KEY> | -k <KEY>]
14+
15+
DESCRIPTION
16+
-----------
17+
Read a single field from the ownership registry entry for an NVMe-oF
18+
controller. The registry is stored under /run/nvme/registry/ as one JSON
19+
file per live controller (e.g. nvme3.json).
20+
21+
If --key is omitted the 'owner' field is retrieved.
22+
23+
OPTIONS
24+
-------
25+
-d <DEV>::
26+
--device=<DEV>::
27+
NVMe device name (e.g. nvme3).
28+
29+
-k <KEY>::
30+
--key=<KEY>::
31+
Registry field name to retrieve. Defaults to 'owner'.
32+
33+
include::global-options.txt[]
34+
35+
EXAMPLES
36+
--------
37+
* Retrieve the owner of nvme3 (default key):
38+
+
39+
------------
40+
# nvme registry-retrieve --device nvme3
41+
stas
42+
------------
43+
+
44+
* Retrieve a specific field by key:
45+
+
46+
------------
47+
# nvme registry-retrieve --device nvme3 --key device
48+
nvme3
49+
------------
50+
51+
SEE ALSO
52+
--------
53+
nvme-registry-list(1)
54+
nvme-registry-update(1)
55+
nvme-registry-delete(1)
56+
57+
NVME
58+
----
59+
Part of the nvme-user suite

‎Documentation/nvme-registry-update.txt‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
nvme-registry-update(1)
2+
=======================
3+
4+
NAME
5+
----
6+
nvme-registry-update - Update a field in a controller's registry entry
7+
8+
SYNOPSIS
9+
--------
10+
[verse]
11+
'nvme' [<global-options>] 'registry-update'
12+
--device=<DEV> | -d <DEV>
13+
--key=<KEY> | -k <KEY>
14+
--value=<VAL> | -V <VAL>
15+
16+
DESCRIPTION
17+
-----------
18+
Write a key/value pair to the ownership registry entry for an NVMe-oF
19+
controller. If the entry does not exist it is created. The write is
20+
atomic: a temporary file is created, synced, and renamed over the
21+
destination.
22+
23+
This command is the primary mechanism for an orchestrator to claim or
24+
steal ownership of an existing connection. All orchestrators are
25+
assumed to be cooperative; there is no OS-level enforcement of ownership.
26+
27+
OPTIONS
28+
-------
29+
-d <DEV>::
30+
--device=<DEV>::
31+
NVMe device name (e.g. nvme3).
32+
33+
-k <KEY>::
34+
--key=<KEY>::
35+
Registry field name to update (e.g. owner).
36+
37+
-V <VAL>::
38+
--value=<VAL>::
39+
New value for the field.
40+
41+
include::global-options.txt[]
42+
43+
EXAMPLES
44+
--------
45+
* Claim ownership of nvme3:
46+
+
47+
------------
48+
# nvme registry-update --device nvme3 --key owner --value stas
49+
------------
50+
51+
SEE ALSO
52+
--------
53+
nvme-registry-list(1)
54+
nvme-registry-retrieve(1)
55+
nvme-registry-delete(1)
56+
57+
NVME
58+
----
59+
Part of the nvme-user suite

0 commit comments

Comments
 (0)