Skip to content
Snippets Groups Projects
Commit 4a8ccf52 authored by Jay Freyensee's avatar Jay Freyensee Committed by Christoph Hellwig
Browse files

nvmetcli: Updated README to current functionality


Also added a referrals/discovery placeholder TBD section.

Signed-off-by: default avatarJay Freyensee <james_p_freyensee@linux.intel.com>
Signed-off-by: default avatarChristoph Hellwig <hch@lst.de>
parent 5945e785
Branches
No related tags found
No related merge requests found
nvmetcli nvmetcli
======== ========
This contains the NVMe target admin tool "nvmetcli". It can either be This contains the NVMe target admin tool "nvmetcli". It can either be
used interactively by invoking it without arguments, or it can be used used interactively by invoking it without arguments, or it can be used
to save, restore or clear the current NVMe target configuration. to save, restore or clear the current NVMe target configuration.
Installation Installation
------------ ------------
Please install the configshell-fb package from Please install the configshell-fb package from
https://github.com/agrover/configshell-fb first. https://github.com/agrover/configshell-fb first.
Nvmetcli can be run directly from the source directory or installed nvmetcli can be run directly from the source directory or installed
using setup.py. using setup.py.
Common Package Dependencies and Problems
-----------------------------------------
nvmetcli uses the 'python-six' and 'pyparsing' packages
(running nvmetcli without these packages may produce
hard-to-decipher errors).
Usage Walk-Through Example Usage
----- ---------------------------
Make sure to run nvmetcli as root, the nvmet module is loaded,
Make sure to run nvmetcli as root, the nvmet module is loaded and your devices are loaded, and configfs is mounted on /sys/kernel/config
configfs is mounted on /sys/kernel/config, using: using:
mount -t configs none /sys/kernel/config mount -t configs none /sys/kernel/config
To get started with the interactive mode start nvmetcli without To get started with the interactive mode and the nvmetcli command prompt,
arguments. Then in the nvmetcli prompt type: type (in root):
./nvmetcli
...>
The following walks through an example using interactive mode.
# #
# Create a subsystem. If you do not specify a name a NQN will be generated, # Create a subsystem. If you do not specify a name a NQN will be generated,
...@@ -40,6 +46,7 @@ arguments. Then in the nvmetcli prompt type: ...@@ -40,6 +46,7 @@ arguments. Then in the nvmetcli prompt type:
# #
# Add access for a specific NVMe Host by it's NQN: # Add access for a specific NVMe Host by it's NQN:
# #
...> cd /hosts ...> cd /hosts
...> create hostnqn ...> create hostnqn
...> cd /subsystems/testnqn/allowed_hosts/ ...> cd /subsystems/testnqn/allowed_hosts/
...@@ -49,9 +56,24 @@ arguments. Then in the nvmetcli prompt type: ...@@ -49,9 +56,24 @@ arguments. Then in the nvmetcli prompt type:
# Alternatively this allows any host to connect to the subsystsem. Only # Alternatively this allows any host to connect to the subsystsem. Only
# use this in tightly controller environments: # use this in tightly controller environments:
# #
...> cd /subsystems/testnqn/ ...> cd /subsystems/testnqn/
...> set attr allow_any_host=1 ...> 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 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.
# #
# Create a port through which access is allowed, and enable access to # Create a port through which access is allowed, and enable access to
# a subsystem through it. # a subsystem through it.
...@@ -59,6 +81,7 @@ arguments. Then in the nvmetcli prompt type: ...@@ -59,6 +81,7 @@ arguments. Then in the nvmetcli prompt type:
# This creates a trivial loopback port that can be used with nvme-loop on # This creates a trivial loopback port that can be used with nvme-loop on
# the same machine: # the same machine:
# #
...> cd /ports/ ...> cd /ports/
...> create 1 ...> create 1
...> cd 1/ ...> cd 1/
...@@ -66,21 +89,11 @@ arguments. Then in the nvmetcli prompt type: ...@@ -66,21 +89,11 @@ arguments. Then in the nvmetcli prompt type:
...> cd subsystems/ ...> cd subsystems/
...> create testnqn ...> create testnqn
#
# Create a new namespace. If you do not specify a namespace ID the fist
# unused one will be used.
#
...> cd namespaces
...> create 1
...> cd 1
...> set device path=/dev/nvme0n1
...> enable
# #
# Or create a RDMA (IB, RoCE, iWarp) port using IPv4 addressing, 4420 is the # Or create a RDMA (IB, RoCE, iWarp) port using IPv4 addressing, 4420 is the
# IANA assigned port for NVMe over Fabrics using RDMA: # IANA assigned port for NVMe over Fabrics using RDMA:
# #
...> cd /ports/ ...> cd /ports/
...> create 2 ...> create 2
...> cd 2/ ...> cd 2/
...@@ -91,30 +104,48 @@ arguments. Then in the nvmetcli prompt type: ...@@ -91,30 +104,48 @@ arguments. Then in the nvmetcli prompt type:
...> cd subsystems/ ...> cd subsystems/
...> create testnqn ...> create testnqn
Referrals/Discovery
--------------------
TBD
Saving and restoring the configuration Saving and restoring the configuration
-------------------------------------- --------------------------------------
The saveconfig command in the interactive
nvmetcli mode saves the current configuration. For example,
./nvmetcli
...> saveconfig test.json
You can also invoke a 'save' command, as well as a 'restore'
and 'clear' command on the Linux command line. For example,
(to load an NVMe Target configuration):
./nvmetcli restore test.json
The saveconfig and restoreconfig commands inside nvmetcli save and restore (to clear a current NVMe Target configuration):
the current configuration, but you can also invoke these commands for the ./nvmetcli clear test.json
command line using the load and restore arguments to nvmetcli. Without
an additional file name these operate on /etc/nvmet/config.json.
Without an additional file name these operate on /etc/nvmet/config.json.
Example NVMe Target .json files
--------------------------------------
To load the loop + explicit host version above do the following: To load the loop + explicit host version above do the following:
./nvmetcli load loop.json ./nvmetcli restore loop.json
Or to load the rdma + no host authentication version do the following Or to load the rdma + no host authentication version do the following
after you've ensured that the IP address in rdma.json fits your setup: after you've ensured that the IP address in rdma.json fits your setup:
./nvmetcli load rdma.json ./nvmetcli restore rdma.json
You can also edit the json files directly.
These files can also be edited directly using your favorite editor.
Testing Testing
------- -------
nvmetcli comes with a testsuite that tests itself and the kernel configfs nvmetcli comes with a testsuite that tests itself and the kernel configfs
interface for the NVMe target. To run it make sure you have nose2 and interface for the NVMe target. To run it make sure you have nose2 and
the coverage plugin for it installed and simple run 'make test'. the coverage plugin for it installed and simple run 'make test'.
Development
-----------------
Please send to linux-nvme@lists.infradead.org for review and acceptance.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment