nvme-discover(1)

SYNOPSIS

nvme discover [--transport=<trtype> | -t <trtype>]
+                        [--nqn=<subnqn> | -n <subnqn>]
+                        [--traddr=<traddr> | -a <traddr>]
+                        [--trsvcid=<trsvcid> | -s <trsvcid>]
+                        [--host-traddr=<traddr> | -w <traddr>]
+                        [--host-iface=<iface> | -f <iface>]
+                        [--hostnqn=<hostnqn> | -q <hostnqn>]
+                        [--hostid=<hostid> | -I <hostid>]
+                        [--raw=<filename> | -r <filename>]
+                        [--device=<device> | -d <device>]
+                        [--config=<filename> | -J <filename>]
+                        [--keep-alive-tmo=<sec> | -k <sec>]
+                        [--reconnect-delay=<#> | -c <#>]
+                        [--ctrl-loss-tmo=<#> | -l <#>]
+                        [--nr-io-queues=<#> | -i <#>]
+                        [--nr-write-queues=<#> | -W <#>]
+                        [--nr-poll-queues=<#> | -P <#>]
+                        [--queue-size=<#> | -Q <#>] [--keyring=<#>]
+                        [--tls_key=<#>] [--hdr-digest | -g] [--data-digest | -G]
+                        [--persistent | -p] [--quiet | -S] [--tls] [--concat]
+                        [--dump-config | -O] [--output-format=<fmt> | -o <fmt>]
+                        [--force] [--nbft] [--no-nbft] [--nbft-path=<STR>]
+                        [--context=<STR>]
+                        [--output-format=<fmt> | -o <fmt>] [--verbose | -v]

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 /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.

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

+-t <trtype> +

+--transport=<trtype> +

+ This field specifies the network fabric being used for + a NVMe-over-Fabrics network. Current string values include: +

+ +++ + + + + + + + + + + + + + + + + + + + + + +

Value	Definition
rdma	The network fabric is an rdma network (RoCE, iWARP, Infiniband, basic rdma, etc)
fc	WIP The network fabric is a Fibre Channel network.
tcp	The network fabric is a TCP/IP network.
loop	Connect to a NVMe over Fabrics target on the local host

+-n <subnqn> +

+--nqn <subnqn> +

+ This field specifies the name for the NVMe subsystem to connect to. +

+-a <traddr> +

+--traddr=<traddr> +

+ This field specifies the network address of the Discovery Controller. + For transports using IP addressing (e.g. rdma) this should be an + IP-based address (ex. IPv4). +

+-s <trsvcid> +

+--trsvcid=<trsvcid> +

+ This field specifies the transport service id. For transports using IP + addressing (e.g. rdma) this field is the port number. By default, the IP + port number for the RDMA transport is 4420. +

+-w <traddr> +

+--host-traddr=<traddr> +

+ This field specifies the network address used on the host to connect + to the Controller. For TCP, this sets the source address on the socket. +

+-f <iface> +

+--host-iface=<iface> +

+ This field specifies the network interface used on the host to connect + to the Controller (e.g. IP eth1, enp2s0, enx78e7d1ea46da). This forces + the connection to be made on a specific interface instead of letting + the system decide. +

+-q <hostnqn> +

+--hostnqn=<hostnqn> +

+ Overrides the default host NQN that identifies the NVMe Host. + If this option is not specified, the default is read from + /usr/local/etc/nvme/hostnqn first. If that does not exist, the + autogenerated NQN value from the NVMe Host kernel module is used next. +

+-I <hostid> +

+--hostid=<hostid> +

+ UUID(Universally Unique Identifier) to be discovered which should be + formatted. +

+-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/libnvme/blob/master/doc/config-schema.json +

+-k <#> +

+--keep-alive-tmo=<#> +

+ Overrides the default keep alive timeout (in seconds). This + option will be ignored for discovery, and it is only + implemented for completeness. +

+-c <#> +

+--reconnect-delay=<#> +

+ Overrides the default delay (in seconds) before reconnect is attempted + after a connect loss. +

+-l <#> +

+--ctrl-loss-tmo=<#> +

+ Overrides the default controller loss timeout period (in seconds). +

+-i <#> +

+--nr-io-queues=<#> +

+ Overrides the default number of I/O queues create by the driver. + This option will be ignored for the discovery, and it is only + implemented for completeness. +

+-W <#> +

+--nr-write-queues=<#> +

+ Adds additional queues that will be used for write I/O. +

+-P <#> +

+--nr-poll-queues=<#> +

+ Adds additional queues that will be used for polling latency sensitive I/O. +

+-Q <#> +

+--queue-size=<#> +

+ Overrides the default number of elements in the I/O queues created + by the driver which can be found at drivers/nvme/host/fabrics.h. + This option will be ignored for the discovery, and it is only + implemented for completeness. +

+--keyring=<#> +

+ Keyring for TLS key lookup. +

+--tls_key=<#> +

+ TLS key for the connection (TCP). +

+-g +

+--hdr-digest +

+ Generates/verifies header digest (TCP). +

+-G +

+--data-digest +

+ Generates/verifies data digest (TCP). +

+-p +

+--persistent +

+ Don’t remove the discovery controller after retrieving the discovery + log page. +

+--tls +

+ Enable TLS encryption (TCP). +

+--concat +

+ Enable secure concatenation (TCP). +

+-S +

+--quiet +

+ Suppress already connected errors. +

+-O +

+--dump-config +

+ Print out resulting JSON configuration file to stdout. +

+-o <fmt> +

+--output-format=<fmt> +

+ Set the reporting format to normal, json or binary. Only one + output format can be used at a time. +

+--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. +

+-o <fmt> +

+--output-format=<fmt> +

+ Set the reporting format to normal, json or binary. Only one + output format can be used at a time. +

+-v +

+--verbose +

+ Increase the information detail in the output. +

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 /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".

AUTHORS

This was written by Jay Freyensee

NVME

Part of the nvme-user suite

+nvme-discover(1) Manual Page +

NAME