diff options
Diffstat (limited to 'Documentation/nvme-discover.txt')
| -rw-r--r-- | Documentation/nvme-discover.txt | 301 |
1 files changed, 301 insertions, 0 deletions
diff --git a/Documentation/nvme-discover.txt b/Documentation/nvme-discover.txt new file mode 100644 index 0000000..1069d3c --- /dev/null +++ b/Documentation/nvme-discover.txt @@ -0,0 +1,301 @@ +nvme-discover(1) +================ + +NAME +---- +nvme-discover - Send Get Log Page request to Discovery Controller. + +SYNOPSIS +-------- +[verse] +'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 @SYSCONFDIR@/nvme/discovery.conf file to use to supply a list of +Discovery commands to run. If no @SYSCONFDIR@/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 + @SYSCONFDIR@/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 @SYSCONFDIR@/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 @SYSCONFDIR@/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 mailto:james.p.freyensee@intel.com[Jay Freyensee] + +NVME +---- +Part of the nvme-user suite |