update README and examples

Signed-off-by: Christoph Hellwig <hch@lst.de>

diff --git a/README.md b/README.md
index 75ca072ed82cb12d3c6e22a058ad9542cfd1345a..1af3ed177bb3bb3f2812b72b0088775d29d33727 100644 (file)
--- a/README.md
+++ b/README.md
@@ -25,16 +25,13 @@ configfs is mounted on /sys/kernel/config, using:
 
        mount -t configs none /sys/kernel/config
 
-You can load the default config that exports the first NVMe device and
-the first ramdisk by running "nvmetcli restore nvmet.json".  The default
-config is stored in /etc/nvmet.json.  You can also edit the json file
-directly.
-
 To get started with the interactive mode start nvmetcli without
 arguments.  Then in the nvmetcli prompt type:
 
 # 
-# 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,
+# which is probably the best choice, we we don't do it here as the name
+# would be random
 #
 
 > cd /subsystems
@@ -55,6 +52,20 @@ arguments.  Then in the nvmetcli prompt type:
 ...> cd /subsystems/testnqn/
 ...> set attr allow_any_host=1
 
+#
+# Create a port through which access is allowed, and enable access to
+# a subsystem through it.
+#
+# This creates a trivial loopback port that can be used with nvme-loop on
+# the same machine:
+#
+...> cd /ports/
+...> create 1
+...> cd 1/
+...> set addr trtype=loop
+...> cd subsystems/
+...> create testnqn
+
 #
 # Create a new namespace.  If you do not specify a namespace ID the fist
 # unused one will be used.
@@ -63,9 +74,43 @@ arguments.  Then in the nvmetcli prompt type:
 ...> cd namespaces 
 ...> create 1
 ...> cd 1
-...> set device path=/dev/ram1
+...> set device path=/dev/nvme0n1
 ...> enable
 
+#
+# Or create a RDMA (IB, RoCE, iWarp) port using IPv4 addressing, 4420 is the
+# IANA assigned 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
+
+
+Saving and restoring the configuration
+--------------------------------------
+
+The saveconfig and restoreconfig commands inside nvmetcli save and restore
+the current configuration, but you can also invoke these commands for the
+command line using the load and restore arguments to nvmetcli.  Without
+an additional file name these operate on /etc/nvmet.json.
+
+To load the loop + explicit host version above do the following:
+
+  ./nvmetcli load loop.json
+
+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:
+
+  ./nvmetcli load rdma.json
+
+You can also edit the json files directly.
+
 
 Testing
 -------

diff --git a/loop.json b/loop.json
new file mode 100644 (file)
index 0000000..a2b7ec7
--- /dev/null
+++ b/loop.json
@@ -0,0 +1,44 @@
+{
+  "hosts": [
+    {
+      "nqn": "hostnqn"
+    }
+  ], 
+  "ports": [
+    {
+      "addr": {
+        "adrfam": "", 
+        "traddr": "", 
+        "treq": "not specified", 
+        "trsvcid": "", 
+        "trtype": "loop"
+      }, 
+      "portid": 1, 
+      "referrals": [], 
+      "subsystems": [
+        "testnqn"
+      ]
+    }
+  ], 
+  "subsystems": [
+    {
+      "allowed_hosts": [
+        "hostnqn"
+      ], 
+      "attr": {
+        "allow_any_host": "0"
+      }, 
+      "namespaces": [
+        {
+          "device": {
+            "nguid": "ef90689c-6c46-d44c-89c1-4067801309a8", 
+            "path": "/dev/nvme0n1"
+          }, 
+          "enable": 1, 
+          "nsid": 1
+        }
+      ], 
+      "nqn": "testnqn"
+    }
+  ]
+}

diff --git a/nvmet.json b/nvmet.json
deleted file mode 100644 (file)
index 33c3545..0000000
--- a/nvmet.json
+++ /dev/null
@@ -1,45 +0,0 @@
-{
-  "hosts": [], 
-  "ports": [
-    {
-      "addr": {
-        "adrfam": "ipv4", 
-        "traddr": "192.168.7.68", 
-        "treq": "not specified", 
-        "trsvcid": "1023", 
-        "trtype": "rdma"
-      }, 
-      "portid": 2, 
-      "subsystems": [
-        "nqn.2014-08.org.nvmexpress:NVMf:uuid:77dca664-0d3e-4f67-b8b2-04c70e3f991d"
-      ]
-    }
-  ], 
-  "subsystems": [
-    {
-      "allowed_hosts": [], 
-      "attr": {
-        "allow_any_host": "1"
-      }, 
-      "namespaces": [
-        {
-          "device": {
-            "nguid": "289ae029-c396-3143-87e8-aec0d7a4b1a8", 
-            "path": "/dev/nvme0n1"
-          }, 
-          "enable": 1, 
-          "nsid": 1
-        }, 
-        {
-          "device": {
-            "nguid": "8a6a2e57-1a2d-2b41-8938-bc409c4ebb6c", 
-            "path": "/dev/ram0"
-          }, 
-          "enable": 0, 
-          "nsid": 2
-        }
-      ], 
-      "nqn": "nqn.2014-08.org.nvmexpress:NVMf:uuid:77dca664-0d3e-4f67-b8b2-04c70e3f991d"
-    }
-  ]
-}

diff --git a/rdma.json b/rdma.json
new file mode 100644 (file)
index 0000000..6fc326c
--- /dev/null
+++ b/rdma.json
@@ -0,0 +1,42 @@
+{
+  "hosts": [
+    {
+      "nqn": "hostnqn"
+    }
+  ], 
+  "ports": [
+    {
+      "addr": {
+        "adrfam": "ipv4", 
+        "traddr": "192.168.6.68", 
+        "treq": "not specified", 
+        "trsvcid": "4420", 
+        "trtype": "rdma"
+      }, 
+      "portid": 2, 
+      "referrals": [], 
+      "subsystems": [
+        "testnqn"
+      ]
+    }
+  ], 
+  "subsystems": [
+    {
+      "allowed_hosts": [], 
+      "attr": {
+        "allow_any_host": "1"
+      }, 
+      "namespaces": [
+        {
+          "device": {
+            "nguid": "ef90689c-6c46-d44c-89c1-4067801309a8", 
+            "path": "/dev/nvme0n1"
+          }, 
+          "enable": 1, 
+          "nsid": 1
+        }
+      ], 
+      "nqn": "testnqn"
+    }
+  ]
+}