nvmetcli(8)
===========
NAME
----
nvmetcli - Configure NVMe-over-Fabrics Target.
USAGE
------
[verse]
nvmetcli
nvmetcli clear
nvmetcli restore [filename.json]
DESCRIPTION
-----------
*nvmetcli* is a program used for viewing, editing, saving,
and starting a Linux kernel NVMe Target, used for an NVMe-over-Fabrics
network configuration. It allows an administrator to export
a storage resource (such as NVMe devices, files, and volumes)
to a local block device and expose them to remote systems
based on the NVMe-over-Fabrics specification from http://www.nvmexpress.org.
*nvmetcli* is run as root and has two modes:
1. An interactive configuration shell
2. Command-line mode which uses an argument
BACKGROUND
----------
The term *NQN* used throughout this man page is the *NVMe Qualified
Name* format which an NVMe endpoint (device, subsystem, etc) must
follow to guarantee a unique name under the NVMe standard. Any
name in a network system setup can be used, but if it does not
follow the NQN format, it may not be unique on an NVMe-over-Fabrics network.
Note that some of the fields set for an NVMe Target port under
interactive mode are defined in the "Discovery Log Page" section of
NVMe-over-Fabrics specification. Each NVMe Target has a
discovery controller mechanism that an NVMe Host can use to determine
the NVM subsystems it can access. *nvmetcli* can be used to add
a new record to the discovery controller upon each new subsystem
entry and port entry that the newly created subsystem entry binds
to (see *OPTIONS* and *EXAMPLES* sections). Each NVMe
Host only gets to see the discovery entries defined in
*/subsystems/[NQN NAME]/allowed_hosts* and the IP port it is connected
to the NVMe Target. An NVMe Host can retrieve these discovery logs via
the nvme-cli tool (https://github.com/linux-nvme/nvme-cli).
OPTIONS
-------
*Interactive Configuration Shell*
To start the interactive configuration shell, type *nvmetcli* on
the command-line. nvmetcli interacts with the Linux kernel
NVMe Target configfs subsystem starting at base
nvmetcli directories **/port**, **/subsystem**, and **/host**.
Configuration changes entered by the administrator are made
immediately to the kernel target configuration. The
following commands can be used while in the interactive configuration
shell mode:
[]
|==================
| cd | Allows to move around the tree.
| ls | Lists contents of current tree node.
| create [NQN name]/[#] | Create a new object using the specified name
or number. If a [NQN name]/[#] is not specified,
a random entry will be used.
| delete [NQN name]/[#] | Delete an object with the specified name or number.
| set attr allow_any_host=[0/1] | Used under */subsystems/[NQN name]* to
specify if any NVMe Host can connect to
the subsystem.
| set device path=[device path] | Used under
*/subsystems/[NQN name]/namespaces*
to set the (storage) device to be used.
| set device nguid=[string] | Used under
*/subsystems/[NQN name]/namespaces*
to set the unique id of the device to
the defined namespace.
| enable/disable | Used under
*/subsystems/[NQN name]/namespaces*
to enable and disable the namespace.
| set addr [discovery log page field]=[string] | Used under */ports/[#]*
to create a port which
access is allowed. See
*EXAMPLES* for more
information.
| saveconfig [filename.json] | Save the NVMe Target configuration in .json
format. Without specifying the
filename this will save as
*/etc/nvmet/config.json*. This file
is in JSON format and can be edited directly
using a prefered file editor.
| exit | Quits interactive configuration shell mode.
|==================
*Command Line Mode*
Typing *nvmetcli [cmd]* on the command-line will execute a command
and not enter the interactive configuration shell.
[]
|==================
| restore [filename.json] | Loads a saved NVMe Target configuration.
Without specifying the filename this will use
*/etc/nvmet/config.json*.
| clear | Clears a current NVMe Target configuration.
| ls | Dumps the current NVMe Target configuration.
|==================
EXAMPLES
--------
Make sure to run nvmetcli as root, the nvmet module is loaded,
your devices and all dependent modules are loaded,
and configfs is mounted on /sys/kernel/config
using:
mount -t configs none /sys/kernel/config
The following section walks through a configuration example.
* To get started with the interactive mode and the nvmetcli command prompt,
type (in root):
--------------
# ./nvmetcli
...>
--------------
* Create a subsystem. If you do not specify a name a NQN will be generated,
which is probably the best choice. We don't do it here as the name
would be random:
--------------
> cd /subsystems
...> create testnqn
--------------
* Add access for a specific NVMe Host by it's NQN:
--------------
...> cd /hosts
...> create hostnqn
...> cd /subsystems/testnqn
...> set attr allow_any_host=0
...> cd /subsystems/testnqn/allowed_hosts/
...> create hostnqn
--------------
* Remove access of a subsystem by deleting the Host NQN:
--------------
...> cd /subsystems/testnqn/allowed_hosts/
...> delete hostnqn
--------------
* Alternatively this allows any Host to connect to the subsystsem. Only
use this in tightly controlled environments:
--------------
...> cd /subsystems/testnqn/
...> set attr allow_any_host=1
--------------
* Create a new namespace. If you do not specify a namespace ID the fist
unused one will be used:
--------------
...> cd /subsystems/testnqn/namespaces
...> create 1
...> cd 1
...> set device path=/dev/nvme0n1
...> enable
--------------
Note that in the above setup the 'device_nguid' attribute
does not have to be set for correct NVMe Target functionality (but
to correctly match a namespace to the exact device upon
clear and restore operations, it is advised to set the
'device_nguid' parameter).
* Create a loopback port that can be used with nvme-loop module
on the same physical machine...
--------------
...> cd /ports/
...> create 1
...> cd 1/
...> set addr trtype=loop
...> cd subsystems/
...> create testnqn
--------------
* or create an RDMA (IB, RoCE, iWarp) port using IPv4 addressing. 4420 is the
IANA assigned default port for NVMe over Fabrics using RDMA:
--------------
...> cd /ports/
...> create 2
...> cd 2/
...> set addr trtype=rdma
...> set addr adrfam=ipv4
...> set addr traddr=192.168.6.68
...> set addr trsvcid=4420
...> cd subsystems/
...> create testnqn
--------------
* or create an FC port. traddr is the WWNN/WWPN of the FC port.
--------------
...> cd /ports/
...> create 3
...> cd 3/
...> set addr trtype=fc
...> set addr adrfam=fc
...> set addr traddr=nn-0x1000000044001123:pn-0x2000000055001123
...> set addr trsvcid=none
...> cd subsystems/
...> create testnqn
--------------
* Saving the NVMe Target configuration:
--------------
./nvmetcli
...> saveconfig test.json
--------------
* Loading an NVMe Target configuration:
--------------
./nvmetcli restore test.json
--------------
* Clearing a current NVMe Target configuration:
--------------
./nvmetcli clear
--------------
ADDITIONAL INFORMATION
----------------------
nvmetcli has the ability to start and stop the NVMe Target configuration
on boot and shutdown through the *systemctl* Linux utility via a .service file.
nvmetcli package comes with *nvmet.service* which when installed, it can
automatically restore the default, saved NVMe Target configuration from
*/etc/nvmet/config.json*. *nvmet.service* can be installed in directories
such as */lib/systemd/system*.
To explicitly enable the service, type:
--------------
systemctl enable nvmet
--------------
To explicitly disable the service, type:
--------------
systemctl disable nvmet
--------------
See also systemctl(1).
AUTHORS
-------
This man page was written by
mailto:james.p.freyensee@intel.com[Jay Freyensee]. nvmetcli was
originally written by mailto:hch@infradead.org[Christoph Hellwig].
REPORTING BUGS & DEVELOPMENT
-----------------------------
Please send patches and bug reports to linux-nvme@lists.infradead.org
for review and acceptance.
LICENSE
-------
nvmetcli is licensed under the *Apache License, Version 2.0*. Software
distributed under this license is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or implied.