Adding upstream version 0.8.upstream/0.8upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 267 insertions, 0 deletions

diff --git a/Documentation/nvmetcli.txt b/Documentation/nvmetcli.txt
new file mode 100644
index 0000000..43e9f97
--- /dev/null
+++ b/Documentation/nvmetcli.txt
@@ -0,0 +1,267 @@
+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 preferred 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 configfs 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.