NVME-CONFIG-CREATE(1)

📦 version 3.2, in arch rolling

💅 nvme-config-create — the NVMe Manual, section 1, but make it make sense

Okay bestie, gather round, because this one is the glow-up command for your NVMe-oF config file ✨

🎀 NAME 🎀

nvme-config-create — adds an NVMe-oF connection entry to the INI configuration. That's it. That's the whole job. And it does it immaculately 💅

🌸 SYNOPSIS 🌸

nvme [<global-options>] config create
                        [--discovery]
                        [--persistent[=<no|auto|force>] ]
                        [--host-symname=<name>]
                        [--output=<file>]
                        [<fabrics-options>]

🦋 DESCRIPTION 🦋

So what this does, right: it builds one NVMe-oF connection entry out of your command-line options and drops it into the INI configuration that nvme connect, nvme discover, and nvme connect-all all read from. Like it's the shared group chat and this command is the one adding a member 🫶

The format is documented over at https://github.com/linux-nvme/nvme-cli/blob/master/libnvme/design/CONFIG.md if you wanna read the lore yourself, iykyk.

If the target file already exists, bestie, nothing gets deleted — its connections are kept, and your new entry gets merged in alongside them. And running the exact same command again? A no-op. Literally no drama, it just vibes 💀

Heads up: unlike nvme config convert, this is not a one-shot migration. It's the ongoing, everyday way to build an INI configuration from the command line. <rainbow>main character energy</rainbow> 👑

By default the entry is an I/O controller (subsystem) entry, and --nqn is required. Want a discovery controller entry instead? Use --discovery, and then --nqn becomes optional 👑

One more thing, and this is the detail people always miss 🙈 — a connection with an explicit --hostnqn or --hostid gets written to a drop-in under <file>.d/. One without either of those goes into the main file. That's the rule, no cap.

✨ OPTIONS ✨

  • --discovery — makes a discovery controller entry instead of an I/O controller entry. And without it, --nqn is required. Periodt.
  • --persistent[=<no|auto|force>] — records this discovery controller's persistence mode. Requires --discovery. And listen, because the value is optional, it has to be glued directly to the option, like --persistent=force. If you hand it a separate argument (--persistent force), that's not a value of the option at all — it's an extra argument, and the command fails 😭 so don't do that to yourself.
    • auto (the default for every --discovery entry, whether or not you give --persistent): persist the connection only where the target's own EPCSD (Explicit Persistent Connection Support for Discovery) flag says it supports it.
    • force — persist no matter what EPCSD reports. For when a target's self-reported EPCSD just cannot be trusted 🙈
    • no — explicitly record that this discovery controller is not persistent, overriding any default that would otherwise apply.
  • --host-symname=<name> — names this host persona. It gets its own configuration drop-in, living its best separate life 🦋
  • --output=<file> — write to this file instead of the default /usr/local/etc/nvme/nvme-fabrics.conf.

🧚 FABRICS OPTIONS 🧚

These ones are shared with NVMe over Fabrics commands, aka stuff like nvme connect. Same flags, same energy:

  • -a <traddr>, --traddr=<traddr> — the network address of the controller. For transports that use IP addressing (e.g. rdma, tcp), this should be an IP address.
  • --concat — enable secure concatenation (TCP).
  • -c <#>, --reconnect-delay=<#> — 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 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 — it's giving legacy, we don't stan)
  • -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> — the network interface to use for the connection.
  • -I <hostid>, --hostid=<hostid> — the host UUID.
  • -q <hostnqn>, --hostnqn=<hostnqn> — override the default host NQN.
  • -w <traddr>, --host-traddr=<traddr> — the source address on the host side of the connection.
  • -k <#>, --keep-alive-tmo=<#> — keep-alive timeout in seconds.
  • --keyring=<keyring> — keyring to use for TLS key lookup.
  • -n <subnqn>, --nqn=<subnqn> — 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> — 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 🫶 (yes, that's a real recommendation, not me being dramatic)
  • --tls-key-identity=<identity> — identity associated with the TLS key.

💜 GLOBAL OPTIONS 💜

These live at the top-level nvme command, but they're available to this subcommand too. Big "borrowing my friend's hoodie" energy:

  • --dry-run — print the command that would be executed, but don't 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. Other versions are rejected 🚫
  • --quiet — suppress informational messages. Errors are still reported, and --quiet cancels any --verbose for the library log level.
  • --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). No timer, no stress 🧘
  • -v, --verbose — increase the level of detail in the output. May be specified multiple times to further increase verbosity.
These options can also be set as machine-wide defaults in nvme-cli.conf(5). A command-line flag always overrides the file. Always. 💅

🔥 EXAMPLES 🔥

  • Add a discovery controller entry for an FC discovery controller:
# nvme config create --transport fc \
    --traddr=nn-0x58ccf090c92006da:pn-0x58ccf091492806da \
    --host-traddr=nn-0x20000024ff7fa448:pn-0x21000024ff7fa448 \
    --hostnqn=nqn.2014-08.org.nvmexpress:uuid:62a4ab74-1e18-11f1-8bb7-6c1ff71ba506 \
    --discovery
  • Add an I/O controller entry to a test configuration file:
# nvme config create --transport tcp --traddr=192.168.1.20 --trsvcid=4420 \
    --nqn=nqn.2024-01.com.example:data.vol1 \
    --output=/tmp/nvme-fabrics.conf

🍓 SEE ALSO 🍓

nvme-config-convert(1) nvme-config-validate(1) nvme-config-show(1) nvme-connect-all(1) nvme-discover(1)

👑 NVME 👑

Part of the nvme-user suite. Iconic behaviour, honestly.

Alright bestie, that's the whole page — from the NVMe manual, page NVME-CONFIG-CREATE(1), dated 10/30/2026, brought to you by the NVMe gang. Go forth and configure 🌈✨

📦 where this page comes from