NVME-DISCOVER(1)

📦
version 3.2 · 14 versions
, in arch rolling

💅 nvme-discover(1) — NVMe Manual 🌸

okay bestie, this is the nvme-discover page from the NVMe Manual, and it’s literally about sending Get Log Page requests to a Discovery Controller. ✨

💖 NAME 💖

nvme-discover — send a Get Log Page request to a Discovery Controller. 💅

🌈 SYNOPSIS 🌈

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>]

✨ DESCRIPTION ✨

Okay so nvme discover sends one or more Get Log Page requests to an NVMe-over-Fabrics Discovery Controller. 🫶

If you give it no parameters at all, nvme discover will try to find a /usr/local/etc/nvme/discovery.conf file and use that to supply a list of Discovery commands to run. If that /usr/local/etc/nvme/discovery.conf file doesn’t exist, the command will quit with an error. 😭 No file, no party.

Otherwise, you should point it at a specific Discovery Controller with --transport, --traddr, and — if necessary — --trsvcid. Then a Discovery request gets sent to that specified Discovery Controller. ✨

🦋 BACKGROUND 🦋

The NVMe-over-Fabrics spec 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 give the NVMe Host specific information — such as network address and unique subsystem NQN — that 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 spec defines the NQN (NVMe Qualified Name) format that 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 its own NQN defined in the NVMe-over-Fabrics spec: 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 /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 no value of the option but an extra argument, and the command fails. 🚨
    • no — never persist. Use this to opt out of the default.
    • auto (the default, both when the option is omitted entirely and 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.

auto and force ask each discovery controller for a keep-alive timeout of 30 seconds, or the --keep-alive-tmo value when it is given. no asks for none, even when --keep-alive-tmo is given. 💜

  • --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. 👑

🧚 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>, --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:
    • 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 ✨

Okay bestie, these ones live at the top level of the nvme command — like, they're the popular girls of the CLI — but they're all available to this subcommand too. 💅

  • --dry-run — Shows you the command it would run and then... doesn't run it. It's giving look-but-don't-touch. Very safe, very demure. 🎀
  • --no-ioctl-probing — Turns off probing for 64-bit IOCTL support. No probing, no poking, we simply do not ask. 🫶
  • --no-retries — Kills the retry logic on transient errors. One shot, no second chances, main character energy only. 💀
  • -o <fmt>, --output-format=<fmt> — Sets the reporting format to normal, tabular, json, or binary. Only one output format at a time, please — we don't do mixed aesthetics. 🔥
  • --output-format-version=<version> — Picks which version of the output format you want. Version 1 keeps the original field naming, while version 2 (that's the default, iykyk) gives you more consistent and script-friendly field names. Any other version? Rejected. Not even a little bit sorry. 🙈
  • --quiet — Suppresses informational messages. Errors still get reported (we're not hiding the tea), and --quiet cancels any --verbose for the library log level. They literally cannot coexist. 😭
  • --set-options=<key=value>[,<key=value>...] — Sets libnvme library options just for this invocation. The supported keys are force-4k, mi-probe-enabled, test-base-dir and test-sysfs-dir. Slay, custom configuration. 🌸
  • --timeout=<ms> — Sets the timeout for the command in milliseconds. infinite or -1 waits with no time limit at all (0xffffffff) — literally forever, bestie, no cap. ⭐
  • -v, --verbose — Cranks up the detail in the output. You can specify it multiple times to get even more verbosity, which is honestly iconic of it. 👑
Fun fact bestie: all of these can also be set as machine-wide defaults in nvme-cli.conf(5). And a command-line flag always overrides the file — the flag wins, periodt. 💖

🌈 EXAMPLES 🌈

Like, actual examples, because reading about it is one thing and doing it is another:

  • 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". That's it. That's the whole vibe check. ✨

🦋 SEE ALSO 🦋

Go give these icons some love too:

💜 AUTHORS 💜

This was written by Jay Freyensee[1]. Respect the author, bestie. 🫶

🎀 NVME 🎀

Part of the nvme-user suite. One big happy family. 🌸

📝 NOTES 📝

  1. Jay Freyensee mailto:james.p.freyensee@intel.com

And that's the whole page, bestie — go forth and discover. 🧚 This little masterpiece is part of the NVMe suite, dated 10/30/2026, and it's genuinely so iconic of it. Mwah. 💋👑

📦 where this page comes from