SYNOPSIS
nvme [<global-options>] discover
[--raw=<filename> | -r <filename>]
[--device=<device> | -d <device>]
[--config=<filename> | -J <filename>]
[--persistent | -p]
[--quiet]
[--dump-config | -O]
[--force]
[--nbft]
[--no-nbft]
[--nbft-path=<STR>]
[--context=<STR>]
[<fabrics-options>]
DESCRIPTION
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 /tmp/usr/etc/nvme/discovery.conf file to use to supply a list of Discovery commands to run. If no /tmp/usr/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.
BACKGROUND
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.
OPTIONS
- -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 /tmp/usr/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
-
Don’t remove the discovery controller after retrieving the discovery log page.
- --quiet
-
Suppress already connected errors.
- -O
- --dump-config
-
Print out resulting JSON configuration file to stdout.
- --force
-
Disable the built-in persistent discover connection rules. Combined with --persistent flag, always create new persistent discovery connection.
- --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
- --context <STR>
-
Set the execution context to <STR>. This allows to coordinate the management of the global resources.
FABRICS OPTIONS
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>
- --dhchap-ctrl-secret=<secret>
-
Controller authentication secret for bi-directional authentication. If not specified, bi-directional authentication is not attempted.
- -S <secret>
- --dhchap-secret=<secret>
-
Host authentication secret (DH-HMAC-CHAP). Must be provided in ASCII format as defined in the NVMe specification.
- --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.
GLOBAL OPTIONS
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.
EXAMPLES
-
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:
# nvme discover --nbft -
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 /tmp/usr/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".
SEE ALSO
nvme-connect(1) nvme-connect-all(1)
AUTHORS
This was written by Jay Freyensee
NVME
Part of the nvme-user suite