NVME-CONNECT(1)

NAME
nvme-connect - Connect to a Fabrics controller.

SYNOPSIS

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

DESCRIPTION

Create a transport connection to a remote system (specified by --traddr and --trsvcid) and create a NVMe over Fabrics controller for the NVMe subsystem specified by the --nqn option.

OPTIONS

--config=<filename>
    Use the specified JSON configuration file instead of the default.

--devid-file=<filename>
    Write the kernel-assigned device name (for example, nvme0) to <filename>. If the controller is already connected, the existing device name is written. Otherwise, the device name is written after the controller is connected.

        When used with --idempotent, the existing device name is written
        before the command exits successfully. This allows a supervising
        process, such as a systemd service, to identify the device for a
        later disconnect operation.

        The output file is created before attempting the connection. If
        the file cannot be created, for example because the parent
        directory does not exist, the command fails without attempting
        the connection.

--idempotent
    Exit with status 0 if the requested controller is already connected instead of reporting an error.

--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. Without --owner, a controller that was already connected keeps the entry it has.

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:

+
Value | Description
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

The following options are defined at the top-level nvme command and are available to this subcommand:

--dry-run
    Print the command that would be executed, but do not 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.

--timeout=<ms>
    Set the timeout for the command in milliseconds.

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

EXAMPLES

    • 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

SEE ALSO

nvme-discover(1) nvme-connect-all(1)

AUTHORS

This was co-written by Jay Freyensee[1] and Christoph Hellwig[2]

NVME

Part of the nvme-user suite

NOTES

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

2.  Christoph Hellwig
    mailto:hch@lst.de