NVME-CONNECT(1)

📦
version 3.2 · 14 versions
, in arch rolling

💅 NVME-CONNECT(1) — the nvme-connect glow-up (from the NVMe Manual, bestie)

okay so. nvme-connect is literally the moment your machine makes a Fabrics controller and connects it to a remote system. She's the main character of "my storage is somewhere else and I want in." 🦋

✨ NAME ✨

nvme-connect — connect to a Fabrics controller. periodt.

🎀 SYNOPSIS 🎀

nvme [<global-options>] connect [--config=<filename>]
                        [--devid-file=<filename>]
                        [--discovery]
                        [--idempotent]
                        [--owner=<NAME>]
                        [<fabrics-options>]

💖 DESCRIPTION 💖

So what she actually does: she creates a transport connection to a remote system (and yes, that system is specified by --traddr and --trsvcid, keep up 💅), and then she creates an NVMe over Fabrics controller for the NVMe subsystem that you named with the --nqn option.

That's it. That's the whole vibe. Connect + controller = iconic 💫

🌸 OPTIONS 🌸

  • --config=<filename> — bestie, use this JSON configuration file instead of the default one. simple as that ✨
  • --devid-file=<filename> — write the kernel-assigned device name (like, for example, nvme0) into <filename>. If the controller is already connected, the device name that already exists gets written. Otherwise the device name goes in after the controller is connected. 🫶

When you use it with --idempotent, the existing device name gets written before the command exits successfully. this is so a supervising process — a systemd service, say — can figure out which device to disconnect later. iykyk.

the output file is created before the connection is even attempted. and no cap: if the file can't be created, like because the parent directory doesn't exist, the command fails without attempting the connection at all. 💀

  • --discovery — plot twist: the target is a Discovery Controller. The kernel recognizes the well-known discovery NQN all by itself, but without this option it sees a Discovery Controller with a unique NQN as an I/O controller. and that gives it a keep-alive timeout of 5 seconds when none is given, and creates I/O queues for it. so yeah, use the flag if that's not what you want 🙈
  • --idempotent — if the controller you're asking for is already connected, exit with status 0 instead of reporting an error. she's unbothered, she's thriving 💅
  • --owner=<NAME> — record NAME as the owner of the connected controller in the NVMe ownership registry, so other orchestrators (and nvme-disconnect-all) leave it alone. see nvme-disconnect-all(1). an empty NAME (--owner=) removes the registry entry instead, leaving the controller unowned. and without --owner, a controller that was already connected keeps whatever entry it has. no take-backsies 👑

🦋 FABRICS OPTIONS 🦋

these are the options that all the NVMe over Fabrics commands share, nvme connect included. girlies, this is the good stuff:

  • -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 a reconnect is attempted after a connection loss.
  • -C <secret>, --kxchap-ctrl-secret=<secret> — controller authentication secret for bi-directional authentication. if you don't specify it, bi-directional authentication isn't attempted. that's just how it is ✨
  • -S <secret>, --kxchap-secret=<secret> — host authentication secret (KX-HMAC-CHAP). must be provided in ASCII format as defined in the NVMe specification. rules are rules 📜
  • -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) — she's an elder, show her respect but use the new one 🙈
  • -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) — same deal, legacy queen 💀
  • --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. yes you CAN have two, she's not jealous 💅
  • -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. glow-up your identity ✨
  • -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. this is literally the who-you're-connecting-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. she's persistent, she's loyal 🫶
  • -s <trsvcid>, --trsvcid=<trsvcid> — transport service identifier (e.g. TCP/rdma port). the 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. (pls don't put secrets in your shell history bestie, that's so not the move 😭)
  • --tls-key-identity=<identity> — identity associated with the TLS key.

💜 GLOBAL OPTIONS 💜

these are defined up at the top-level nvme command and they're available to this subcommand too. big main-character energy ✨

  • --dry-run — print the command that would be executed, but do not actually execute it. all the fantasy, zero consequences 💭
  • --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. pick one, queen, you can't have all four 👑
  • --output-format-version=<version> — select the output format version. version 1 uses the original field naming, while version 2 (the default) provides more consistent and script-friendly field names. other versions are rejected. respectfully, no 💀
  • --quiet — suppress informational messages. errors are still reported, and --quiet cancels any --verbose for the library log level. she's a literal "mute notifications" button 🔇
  • --set-options=<key=value>[,<key=value>...] — set libnvme library options for this invocation. supported keys are force-4k, mi-probe-enabled, test-base-dir and test-sysfs-dir.
  • --timeout=<ms> — set the timeout for the command in milliseconds. infinite or -1 waits without a time limit (0xffffffff). she'll wait forever, literally 🌙
  • -v, --verbose — increase the level of detail in the output. may be specified multiple times to further increase verbosity. spam the -v, she loves to over-explain 💬
these options can also be set as machine-wide defaults in nvme-cli.conf(5). a command-line flag always overrides the file. flag > file, every single time. 💅

🌈 EXAMPLES 🌈

  1. connect to a subsystem named nqn.2014-08.com.example:nvme:nvm-subsystem-sn-d78432 on the IP4 address 192.168.1.3. port 4420 is used by default:
# nvme connect --transport=rdma --traddr=192.168.1.3 \
--nqn=nqn.2014-08.com.example:nvme:nvm-subsystem-sn-d78432

look at her go. effortless. 🦋✨

⭐ SEE ALSO ⭐

nvme-discover(1) nvme-connect-all(1) — go read those next, bestie, they're the sequel 🎀

👑 AUTHORS 👑

this was co-written by Jay Freyensee[1] and Christoph Hellwig[2]. two icons, one manpage 💖

🍓 NVME 🍓

part of the nvme-user suite 🫶

📝 NOTES 📝

  1. Jay Freyensee — mailto:james.p.freyensee@intel.com
  2. Christoph Hellwig — mailto:hch@lst.de

okay that's the whole thing, you're officially educated 💅✨ this was the NVMe manual, dated 10/30/2026 — go forth and connect responsibly, bestie 🌸💖🎀

📦 where this page comes from