nvme-discover - Send Get Log Page request to Discovery
Controller.
nvme [<global-options>] discover
[--raw=<filename> | -r <filename>]
[--device=<device> | -d <device>]
[--config=<filename> | -J <filename>]
[--persistent[=<no|auto|force>] | -p]
[--quiet]
[--no-reuse]
[--force]
[--nbft]
[--no-nbft]
[--nbft-path=<STR>]
[--owner=<NAME>]
[<fabrics-options>]
Send one or more Get Log Page requests to a NVMe-over-Fabrics
Discovery Controller.
If no parameters are given, then nvme discover will attempt
to find a /usr/local/etc/nvme/discovery.conf file to use to supply a list of
Discovery commands to run. If no /usr/local/etc/nvme/discovery.conf file
exists, the command will quit with an error.
Otherwise, a specific Discovery Controller should be specified
using the --transport, --traddr, and if necessary the --trsvcid flags. A
Discovery request will then be sent to the specified Discovery
Controller.
The NVMe-over-Fabrics specification defines the concept of a
Discovery Controller that an NVMe Host can query on a fabric network to
discover NVMe subsystems contained in NVMe Targets which it can connect to
on the network. The Discovery Controller will return Discovery Log Pages
that provide the NVMe Host with specific information (such as network
address and unique subsystem NQN) the NVMe Host can use to issue an NVMe
connect command to connect itself to a storage resource contained in that
NVMe subsystem on the NVMe Target.
Note that the base NVMe specification defines the NQN (NVMe
Qualified Name) format which an NVMe endpoint (device, subsystem, etc) must
follow to guarantee a unique name under the NVMe standard. In particular,
the Host NQN uniquely identifies the NVMe Host, and may be used by the
Discovery Controller to control what NVMe Target resources are allocated to
the NVMe Host for a connection.
A Discovery Controller has it’s own NQN defined in the
NVMe-over-Fabrics specification,
nqn.2014-08.org.nvmexpress.discovery. All Discovery Controllers must
use this NQN name. This NQN is used by default by nvme-cli for the
discover command.
-r <filename>, --raw=<filename>
This field will take the output of the nvme
discover command and dump it to a raw binary file. By default nvme
discover will dump the output to stdout.
-d <device>, --device=<device>
This field takes a device as input. It must be a
persistent device associated with a Discovery Controller previously created by
the command "connect-all" or "discover". <device>
follows the format nvme*, eg. nvme0, nvme1.
-J <filename>, --config=<filename>
Use the specified JSON configuration file instead of the
default /usr/local/etc/nvme/config.json file or none to not read in an
existing configuration file. The JSON configuration file format is documented
in
https://github.com/linux-nvme/nvme-cli/blob/master/libnvme/doc/config-schema.json
-p, --persistent[=<no|auto|force>]
Keep the discovery controller connected after retrieving
the discovery log page, instead of disconnecting once it’s done.
Because the value is optional, it must be attached directly to the option:
--persistent=force for the long form, -pforce for the short form. A value
given as a separate argument (--persistent force, -p force) is silently NOT
applied — it’s dropped, and --persistent/-p is treated as if
given bare (mode "auto"), with no error.
•no (the default when the option is omitted
entirely): never persist.
•auto (the default when --persistent is
given with no value): persist a Discovery Log Page entry’s connection
only where that entry’s own EPCSD (Explicit Persistent Connection
Support for Discovery) flag reports support for it; degrade to non-persistent,
with a log message, for entries that don’t.
•force: persist regardless of what EPCSD
reports, for a target whose self-reported EPCSD cannot be trusted.
--quiet
Suppress already connected errors.
--no-reuse
Always create a new connection, never reuse an existing
one.
--force
(deprecated, see --no-reuse)
--nbft
Only look at NBFT tables
--no-nbft
Do not look at NBFT tables
--nbft-path=<STR>
Use a user-defined path to the NBFT tables
--owner=<NAME>
Record NAME as the owner of connected controllers in the
NVMe ownership registry, so other orchestrators (and nvme-disconnect-all)
leave them alone. See
nvme-disconnect-all(1). When --nbft is also given,
--owner takes precedence over its default owner of
nbft.
The following options are common to NVMe over Fabrics commands
such as nvme connect:
-a <traddr>, --traddr=<traddr>
Specify the network address of the controller. For
transports using IP addressing (e.g. rdma, tcp), this should be an IP
address.
--concat
Enable secure concatenation (TCP).
-c <#>, --reconnect-delay=<#>
Set the delay in seconds before reconnect is attempted
after a connection loss.
-C <secret>, --kxchap-ctrl-secret=<secret>
Controller authentication secret for bi-directional
authentication. If not specified, bi-directional authentication is not
attempted.
-S <secret>, --kxchap-secret=<secret>
Host authentication secret (KX-HMAC-CHAP). Must be
provided in ASCII format as defined in the NVMe specification.
-C <secret>, --dhchap-ctrl-secret=<secret>
Controller authentication secret for bi-directional
authentication. If not specified, bi-directional authentication is not
attempted. (deprecated, see --kxchap-ctrl-secret)
-S <secret>, --dhchap-secret=<secret>
Host authentication secret (DH-HMAC-CHAP). Must be
provided in ASCII format as defined in the NVMe specification. (deprecated,
see --kxchap-secret)
--disable-sqflow
Disable submission queue flow control.
-G, --data-digest
Enable data digest generation/verification (TCP).
-D, --duplicate-connect
Allow duplicate connections to the same subsystem.
-g, --hdr-digest
Enable header digest generation/verification (TCP).
-f <iface>, --host-iface=<iface>
Specify the network interface to use for the
connection.
-I <hostid>, --hostid=<hostid>
Specify the host UUID.
-q <hostnqn>, --hostnqn=<hostnqn>
Override the default host NQN.
-w <traddr>, --host-traddr=<traddr>
Specify the source address on the host side of the
connection.
-k <#>, --keep-alive-tmo=<#>
Set the keep-alive timeout in seconds.
--keyring=<keyring>
Keyring to use for TLS key lookup.
-n <subnqn>, --nqn=<subnqn>
Specify the NVMe subsystem NQN to connect to.
-i <#>, --nr-io-queues=<#>
Number of I/O queues to create.
-P <#>, --nr-poll-queues=<#>
Number of polling queues to create.
-W <#>, --nr-write-queues=<#>
Number of write queues to create.
-Q <#>, --queue-size=<#>
Queue depth for I/O queues.
-l <#>, --ctrl-loss-tmo=<#>
Maximum time in seconds to retry reconnect attempts after
controller loss.
-s <trsvcid>, --trsvcid=<trsvcid>
Transport service identifier (e.g. TCP/rdma port).
Default is 4420 for RDMA.
-T <#>, --tos=<#>
Type of service value for the connection (TCP).
-t <trtype>, --transport=<trtype>
Specify the transport type. Supported values
include:
+
| Value |
Description |
| rdma |
RDMA (RoCE, iWARP, InfiniBand) |
| tcp |
TCP/IP |
| fc |
Fibre Channel (experimental) |
| loop |
Local loopback transport |
--tls
Enable TLS encryption (TCP).
--tls-key=<tls-key>
TLS key for the connection. It is recommended to preload
keys into the system keyring instead of passing them via the command
line.
--tls-key-identity=<identity>
Identity associated with the TLS key.
The following options are defined at the top-level nvme command
and are available to this subcommand:
--dry-run
Print the command that would be executed, but do not
actually execute it.
--no-ioctl-probing
Disable probing for 64-bit IOCTL support.
--no-retries
Disable retry logic on transient errors.
-o <fmt>, --output-format=<fmt>
Set the reporting format to normal, tabular,
'json, or binary. Only one output format may be used at a
time.
--output-format-version=<version>
Select the output format version. Version 1 uses
the original field naming, while version 2 (default) provides more
consistent and script-friendly field names.
--timeout=<ms>
Set the timeout for the command in milliseconds.
-v, --verbose
Increase the level of detail in the output. May be
specified multiple times to further increase verbosity.
These options can also be set as machine-wide defaults in
nvme-cli.conf(5). A command-line flag always overrides the file.
•Query the Discover Controller with IP4 address
192.168.1.3 for all resources allocated for NVMe Host name host1-rogue-nqn on
the RDMA network. Port 4420 is used by default:
# nvme discover --transport=rdma --traddr=192.168.1.3 \
--hostnqn=host1-rogue-nqn
•Issue a
nvme discover command using the
default system defined NBFT tables:
•Issue a
nvme discover command with a
user-defined path for the NBFT table:
# nvme discover --nbft-path=/sys/firmware/acpi/tables/NBFT1
•Issue a
nvme discover command using a
/usr/local/etc/nvme/discovery.conf file:
# Machine default 'nvme discover' commands. Query the
# Discovery Controller's two ports (some resources may only
# be accessible on a single port). Note an official
# nqn (Host) name defined in the NVMe specification is being used
# in this example.
-t rdma -a 192.168.69.33 -s 4420 -q nqn.2014-08.com.example:nvme:nvm-subsystem-sn-d78432
-t rdma -a 192.168.1.4 -s 4420 -q nqn.2014-08.com.example:nvme:nvm-subsystem-sn-d78432
At the prompt type "nvme discover".
This was written by Jay Freyensee[1]
Part of the nvme-user suite
- 1.
- Jay Freyensee
mailto:james.p.freyensee@intel.com