[PATCH 0/3] nvmetcli manpage and misc tweaks

[PATCH 0/3] nvmetcli manpage and misc tweaks

[Jay Freyensee]

Adding proper documentation solution to nvmetcli.

Jay Freyensee (3):
  nvmetcli: Adding manpage/html generation
  nvmetcli: add python-six to rpm package building
  nvmetcli: remove README file

 Documentation/Makefile     |  21 ++++
 Documentation/nvmetcli.txt | 237 +++++++++++++++++++++++++++++++++++++++++++++
 Makefile                   |  15 ++-
 README                     | 173 ---------------------------------
 rpm/nvmetcli.spec.tmpl     |   2 +-
 5 files changed, 272 insertions(+), 176 deletions(-)
 create mode 100644 Documentation/Makefile
 create mode 100644 Documentation/nvmetcli.txt
 delete mode 100644 README

-- 
2.7.4

[PATCH 1/3] nvmetcli: Adding manpage/html generation

[Jay Freyensee]

Signed-off-by: Jay Freyensee <james.p.freyensee at intel.com>
---
 Documentation/Makefile     |  21 ++++
 Documentation/nvmetcli.txt | 237 +++++++++++++++++++++++++++++++++++++++++++++
 Makefile                   |  15 ++-
 3 files changed, 271 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/Makefile
 create mode 100644 Documentation/nvmetcli.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
new file mode 100644
index 0000000..432731a
--- /dev/null
+++ b/Documentation/Makefile
@@ -0,0 +1,21 @@
+PKGNAME = nvmetcli
+MANPAGE = ${PKGNAME}.1
+HTMLFILE = ${PKGNAME}.html
+XMLFILE = ${PKGNAME}.xml
+
+ASCIIDOC = asciidoc
+XMLTO = xmlto --skip-validation
+
+DOCDATA = ${XMLFILE} ${HTMLFILE}
+ 
+${MANPAGE}: ${DOCDATA}
+	${XMLTO} man $<
+ 
+%.xml: %.txt
+	${ASCIIDOC} -b docbook -d manpage -o $@ $<
+ 
+%.html: %.txt
+	${ASCIIDOC} -a toc -o $@ $<
+ 
+clean:
+	-rm -f ${MANPAGE} ${HTMLFILE} ${XMLFILE}
diff --git a/Documentation/nvmetcli.txt b/Documentation/nvmetcli.txt
new file mode 100644
index 0000000..8ec66eb
--- /dev/null
+++ b/Documentation/nvmetcli.txt
@@ -0,0 +1,237 @@
+nvmetcli(1)
+===========
+
+NAME
+----
+nvmetcli - Configure NVMe Target for NVMe-over-Fabrics solution.
+
+USAGE
+------
+[verse]
+nvmetcli
+nvmetcli [cmd] [file]
+
+DESCRIPTION
+-----------
+*nvmetcli* is a python-based program used for viewing, editing, saving,
+and starting a Linux kernel NVMe Target, used for an NVMe-over-Fabrics
+network configuration.  It enables an administrator to assign local
+storage resources backed by either local NVMe devices, OS files, or
+system volumes and export them to remote systems via network fabrics
+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
+
+nvmetcli manages only one NVMe Target as there is only one Linux kernel
+NVMe Target per system.
+
+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                    | Same as Linux, allows to move around the tree. 
+| ls                    | Similar as Linux, 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.
+|==================
+
+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
+--------------
+
+* 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.
+
+AUTHORS
+-------
+This was written by mailto:james.p.freyensee at intel.com[Jay Freyensee]
+for mailto:hch at infradead.org[Christoph Hellwig].
+
+REPORTING BUGS & DEVELOPMENT
+-----------------------------
+Please send patches to linux-nvme at 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.
diff --git a/Makefile b/Makefile
index a8dc916..10faa4e 100644
--- a/Makefile
+++ b/Makefile
@@ -2,6 +2,7 @@ PKGNAME = nvmetcli
 NAME = nvmet
 GIT_BRANCH = $$(git branch | grep \* | tr -d \*)
 VERSION = $$(basename $$(git describe --tags | tr - . | sed 's/^v//'))
+DOCDIR = ./Documentation
 
 all:
 	@echo "Usage:"
@@ -9,13 +10,23 @@ all:
 	@echo "  make deb         - Builds debian packages."
 	@echo "  make rpm         - Builds rpm packages."
 	@echo "  make release     - Generates the release tarball."
+	@echo "  make doc         - Builds manpages & html docs in ${DOCDIR}."
 	@echo
 	@echo "  make clean       - Cleanup the local repository build files."
-	@echo "  make cleanall    - Also remove dist/*"
+	@echo "  make cleandoc    - Cleanup auto-generated docs in ${DOCDIR}."
+	@echo "  make cleanall    - Remove dist/*, build files, auto-gen docs."
 
 test:
 	@nose2 -C --coverage ./nvmet
 
+doc: ${NAME}
+	${MAKE} -C ${DOCDIR}
+
+cleandoc:
+	@rm -f ${DOCDIR}/${PKGNAME}.1
+	@rm -f ${DOCDIR}/${PKGNAME}.html
+	@rm -f ${DOCDIR}/${PKGNAME}.xml
+	
 clean:
 	@rm -fv ${NAME}/*.pyc ${NAME}/*.html
 	@rm -frv doc
@@ -25,7 +36,7 @@ clean:
 	@rm -frv ${PKGNAME}-*
 	@echo "Finished cleanup."
 
-cleanall: clean
+cleanall: clean cleandoc
 	@rm -frv dist
 
 release: build/release-stamp
-- 
2.7.4

[PATCH 2/3] nvmetcli: add python-six to rpm package building

[Jay Freyensee]

>From experience, if python-six isn't installed on a Fedora
system, hard-to-decipher errors can occur trying to use
nvmetcli.

Signed-off-by: Jay Freyensee <james.p.freyensee at intel.com>
---
 rpm/nvmetcli.spec.tmpl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rpm/nvmetcli.spec.tmpl b/rpm/nvmetcli.spec.tmpl
index 03667d7..1ffdbe6 100644
--- a/rpm/nvmetcli.spec.tmpl
+++ b/rpm/nvmetcli.spec.tmpl
@@ -9,7 +9,7 @@ Source:         nvmetcli-%{version}.tar.gz
 BuildRoot:      %{_tmppath}/%{name}-%{version}-%{release}-rpmroot
 BuildArch:      noarch
 BuildRequires:  python-devel python-setuptools systemd-units
-Requires:	python-configshell python-kmod
+Requires:	python-configshell python-kmod python-six
 Requires(post): systemd
 Requires(preun): systemd
 Requires(postun): systemd
-- 
2.7.4

[PATCH 3/3] nvmetcli: remove README file

[Jay Freyensee]

Contents of README have been moved and updated into the
manpage/html solution.

Signed-off-by: Jay Freyensee <james.p.freyensee at intel.com>
---
 README | 173 -----------------------------------------------------------------
 1 file changed, 173 deletions(-)
 delete mode 100644 README

diff --git a/README b/README
deleted file mode 100644
index 4c44b39..0000000
--- a/README
+++ /dev/null
@@ -1,173 +0,0 @@
-nvmetcli
-========
-This contains the NVMe target admin tool "nvmetcli".  It can either be
-used interactively by invoking it without arguments, or it can be used
-to save, restore or clear the current NVMe target configuration.
-
-Installation
-------------
-Please install the configshell-fb package from
-https://github.com/agrover/configshell-fb first.
-
-nvmetcli can be run directly from the source directory or installed
-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).
-
-Walk-Through Example Usage
----------------------------
-Make sure to run nvmetcli as root, the nvmet module is loaded,
-your devices are loaded, and configfs is mounted on /sys/kernel/config
-using:
-
-	mount -t configs none /sys/kernel/config
-
-To get started with the interactive mode and the nvmetcli command prompt,
-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,
-# which is probably the best choice, we 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/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 controller 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.
-
-#
-# 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
-
-#
-# 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
-
-Discovery
-----------
-Each NVMe Target has a discovery controller mechanism that an NVMe
-Host can use to determine the NVM subsystems it has access too.
-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 too (see the '/port/' and
-'/subystem/' nvmetcli walk-through earlier in this README).  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.
-
-A Host can retrieve these discovery logs via the nvme-cli tool
-(https://github.com/linux-nvme/nvme-cli).
-
-Referrals
----------
-TBD
-
-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
-
-(to clear a current NVMe Target configuration):
-  ./nvmetcli clear test.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:
-
-  ./nvmetcli restore 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 restore rdma.json
-
-These files can also be edited directly using your favorite editor.
-
-Testing
--------
-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
-the coverage plugin for it installed and simple run 'make test'.
-
-Development
------------------
-Please send to linux-nvme at lists.infradead.org for review and acceptance.
-- 
2.7.4

[PATCH 1/3] nvmetcli: Adding manpage/html generation

[Christoph Hellwig]

Hi Jay,

thanks a lot for writing this man page!  I have a few comments below,
but otherwise this looks really great.

> +NAME
> +----
> +nvmetcli - Configure NVMe Target for NVMe-over-Fabrics solution.

I'd just say "Configure the NVMe-over-Fabrics Target".

> +[verse]
> +nvmetcli
> +nvmetcli [cmd] [file]

Should we just list the three actual command here?

> +DESCRIPTION
> +-----------
> +*nvmetcli* is a python-based program used for viewing, editing, saving,

I'd drop python here - that's an implementation detail not interesting
to the actual user reading the man page.


> It enables an administrator to assign local
> +storage resources backed by either local NVMe devices, OS files, or
> +system volumes and export them to remote systems via network fabrics
> +based on the NVMe-over-Fabrics specification from http://www.nvmexpress.org.

I'd something like "It allows to export a local block device (including,
but not limited to a NVMe devices).."  We can't really export files
directly but need to turn them into a block device first using the loop
device, and NVMe devices aren't really treated special, although they
are of course worse mentioning.

> +nvmetcli manages only one NVMe Target as there is only one Linux kernel
> +NVMe Target per system.

Can we just remove this sentence?  As per the spec there is no such
thing as a NVMe Target (unfortunately, bit out my teeth on that), but
just a collection of subsystems and ports - with nvmetcli we can create
sets of subsystems and ports that are entirelt disjoint.

> +|==================
> +| cd                    | Same as Linux, allows to move around the tree. 
> +| ls                    | Similar as Linux, lists contents of current tree node.

Can we drop the "Same as" and "Similar as"?  It's really traditional
Unix shells that we are similar too, but that wording seems a bit clumsy.

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

It might be good to mention the actual service, e.g.

nvmetcli ships with a nvmet systemd service file, which automatically
restores the saved config from /etc/nvme/nvmet.json on system startup,
and clears the configuration on shutdown.  You can uses systemctl (and we
probably want a man page reference to systemctl here, no idea how to do
that in asciidoc) to enable and disable this functionality.

> +
> +AUTHORS
> +-------
> +This was written by mailto:james.p.freyensee at intel.com[Jay Freyensee]
> +for mailto:hch at infradead.org[Christoph Hellwig].

If at all I'd word this as

This man page was written by mailto:james.p.freyensee at intel.com[Jay Freyensee].
nvmetcli was originall written by mailto:hch at infradead.org[Christoph Hellwig].

But I'd be personallly fine with just dropping all this from the man page
and instead have an AUTHORS file.  Any suggestions from someone else?

> +
> +REPORTING BUGS & DEVELOPMENT
> +-----------------------------
> +Please send patches to linux-nvme at lists.infradead.org for review and acceptance.

Might be worth to also mention bug reports here.

> +doc: ${NAME}
> +	${MAKE} -C ${DOCDIR}
> +
> +cleandoc:
> +	@rm -f ${DOCDIR}/${PKGNAME}.1
> +	@rm -f ${DOCDIR}/${PKGNAME}.html
> +	@rm -f ${DOCDIR}/${PKGNAME}.xml

Should this be ${MAKE} -C ${DOCDIR} clean?

Also I suspect this should be a .8 page, not .1 given that we install
into sbin.

[PATCH 3/3] nvmetcli: remove README file

[Christoph Hellwig]

On Wed, Nov 23, 2016@10:01:13AM -0800, Jay Freyensee wrote:
> Contents of README have been moved and updated into the
> manpage/html solution.


I still think that a basic README is useful, including pointing people
to the manpage, and for build instruction in case we add any.


> --- a/README
> +++ /dev/null
> @@ -1,173 +0,0 @@
> -nvmetcli
> -========
> -This contains the NVMe target admin tool "nvmetcli".  It can either be
> -used interactively by invoking it without arguments, or it can be used
> -to save, restore or clear the current NVMe target configuration.
> -
> -Installation
> -------------
> -Please install the configshell-fb package from
> -https://github.com/agrover/configshell-fb first.
> -
> -nvmetcli can be run directly from the source directory or installed
> -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).


E.g. keep everything up to here, then add a reference to
nvmetcli.txt after that.

And keep the rest quotes below this text as well,

> -Example NVMe Target .json files
> ---------------------------------------
> -To load the loop + explicit host version above do the following:
> -
> -  ./nvmetcli restore 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 restore rdma.json
> -
> -These files can also be edited directly using your favorite editor.
> -
> -Testing
> --------
> -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
> -the coverage plugin for it installed and simple run 'make test'.
> -
> -Development
> ------------------
> -Please send to linux-nvme at lists.infradead.org for review and acceptance.
> -- 
> 2.7.4
---end quoted text---

[PATCH 1/3] nvmetcli: Adding manpage/html generation

[J Freyensee]

On Fri, 2016-11-25@08:43 +0100, Christoph Hellwig wrote:
> Hi Jay,
> 
> thanks a lot for writing this man page!??I have a few comments below,
> but otherwise this looks really great.

No problem, thanks for the compliment :-).

> 
> > 
> > +NAME
> > +----
> > +nvmetcli - Configure NVMe Target for NVMe-over-Fabrics solution.
> 
> I'd just say "Configure the NVMe-over-Fabrics Target".

Will do.

> 
> > 
> > +[verse]
> > +nvmetcli
> > +nvmetcli [cmd] [file]
> 
> Should we just list the three actual command here?

You mean just list out all the "nvmetcli [cmd] [file]" commands
(nvmetcli restore [file], nvmetcli clear [file])?

> 
> > 
> > +DESCRIPTION
> > +-----------
> > +*nvmetcli* is a python-based program used for viewing, editing,
> > saving,
> 
> I'd drop python here - that's an implementation detail not
> interesting
> to the actual user reading the man page.

No problem.

> 
> 
> > 
> > It enables an administrator to assign local
> > +storage resources backed by either local NVMe devices, OS files,
> > or
> > +system volumes and export them to remote systems via network
> > fabrics
> > +based on the NVMe-over-Fabrics specification from http://www.nvmex
> > press.org.
> 
> I'd something like "It allows to export a local block device
> (including,
> but not limited to a NVMe devices).."??We can't really export files
> directly but need to turn them into a block device first using the
> loop
> device, and NVMe devices aren't really treated special, although they
> are of course worse mentioning.

OK, I'll give it a stab to tweak and add that comment.

> 
> > 
> > +nvmetcli manages only one NVMe Target as there is only one Linux
> > kernel
> > +NVMe Target per system.
> 
> Can we just remove this sentence???

Sure.


> > +|==================
> > +| cd????????????????????| Same as Linux, allows to move around the
> > tree.?
> > +| ls????????????????????| Similar as Linux, lists contents of
> > current tree node.
> 
> Can we drop the "Same as" and "Similar as"???It's really traditional
> Unix shells that we are similar too, but that wording seems a bit
> clumsy.

Sure, no problem.

> 
> > 
> > +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.
> 
> It might be good to mention the actual service, e.g.
> 
> nvmetcli ships with a nvmet systemd service file, which automatically
> restores the saved config from /etc/nvme/nvmet.json on system
> startup,

Yah, I've played with the nvmet systemd service file, I can mention
that.

> and clears the configuration on shutdown.??You can uses systemctl
> (and we
> probably want a man page reference to systemctl here, no idea how to
> do
> that in asciidoc) to enable and disable this functionality.

I can explicitly state the commands:

systemctl enable nvmet
systemctl disable nvmet

into this section...not sure how I'd add a man page reference to
systemctl, I'm not an asciidoc power user.

> 
> > 
> > +
> > +AUTHORS
> > +-------
> > +This was written by mailto:james.p.freyensee at intel.com[Jay
> > Freyensee]
> > +for mailto:hch at infradead.org[Christoph Hellwig].
> 
> If at all I'd word this as
> 
> This man page was written by mailto:james.p.freyensee at intel.com[Jay
> Freyensee].
> nvmetcli was originall written by mailto:hch at infradead.org[Christoph
> Hellwig].
> 

I can just do this. ?I don't mind mentioning I authored the man page,
but I don't want to take credit that is yours.

> > +
> > +REPORTING BUGS & DEVELOPMENT
> > +-----------------------------
> > +Please send patches to linux-nvme at lists.infradead.org for review
> > and acceptance.
> 
> Might be worth to also mention bug reports here.

OK, I can tweak it.

> 
> > 
> > +doc: ${NAME}
> > +	${MAKE} -C ${DOCDIR}
> > +
> > +cleandoc:
> > +	@rm -f ${DOCDIR}/${PKGNAME}.1
> > +	@rm -f ${DOCDIR}/${PKGNAME}.html
> > +	@rm -f ${DOCDIR}/${PKGNAME}.xml
> 
> Should this be ${MAKE} -C ${DOCDIR} clean?
> 

Maybe :-P. ?I'll look into it.

> Also I suspect this should be a .8 page, not .1 given that we install
> into sbin.

Can change, no problem.

[PATCH 3/3] nvmetcli: remove README file

[J Freyensee]

On Fri, 2016-11-25@08:46 +0100, Christoph Hellwig wrote:
> On Wed, Nov 23, 2016@10:01:13AM -0800, Jay Freyensee wrote:
> > 
> > Contents of README have been moved and updated into the
> > manpage/html solution.
> 
> 
> I still think that a basic README is useful, including pointing
> people
> to the manpage, and for build instruction in case we add any.

OK, I can re-send the patch series and not touch the README.

> 
> 
> > 
> > --- a/README
> > +++ /dev/null
> > @@ -1,173 +0,0 @@
> > -nvmetcli
> > -========
> > -This contains the NVMe target admin tool "nvmetcli".??It can
> > either be
> > -used interactively by invoking it without arguments, or it can be
> > used
> > -to save, restore or clear the current NVMe target configuration.
> > -
> > -Installation
> > -------------
> > -Please install the configshell-fb package from
> > -https://github.com/agrover/configshell-fb first.
> > -
> > -nvmetcli can be run directly from the source directory or
> > installed
> > -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).
> 
> 
> E.g. keep everything up to here, then add a reference to
> nvmetcli.txt after that.
> 
> And keep the rest quotes below this text as well,
> 
> > 
> > -Example NVMe Target .json files
> > ---------------------------------------
> > -To load the loop + explicit host version above do the following:
> > -
> > -??./nvmetcli restore 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 restore rdma.json
> > -
> > -These files can also be edited directly using your favorite
> > editor.
> > -
> > -Testing
> > --------
> > -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
> > -the coverage plugin for it installed and simple run 'make test'.
> > -
> > -Development
> > ------------------
> > -Please send to linux-nvme at lists.infradead.org for review and
> > acceptance.
> > --?
> > 2.7.4
> ---end quoted text---
> 
> _______________________________________________
> Linux-nvme mailing list
> Linux-nvme at lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/linux-nvme

[PATCH 1/3] nvmetcli: Adding manpage/html generation

[Andy Grover]

On 11/24/2016 11:43 PM, Christoph Hellwig wrote:
> Hi Jay,
>
> thanks a lot for writing this man page!  I have a few comments below,
> but otherwise this looks really great.

Hi, do you mind tagging this into a release?

Thanks -- Andy

[PATCH 1/3] nvmetcli: Adding manpage/html generation

[J Freyensee]

On Thu, 2017-01-05@13:43 -0800, Andy Grover wrote:
> On 11/24/2016 11:43 PM, Christoph Hellwig wrote:
> > 
> > Hi Jay,
> > 
> > thanks a lot for writing this man page!??I have a few comments below,
> > but otherwise this looks really great.
> 
> Hi, do you mind tagging this into a release?

Love too, but I think Christoph has the only power :-)

> 
> Thanks -- Andy
> 
> 
> _______________________________________________
> Linux-nvme mailing list
> Linux-nvme at lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/linux-nvme

[PATCH 1/3] nvmetcli: Adding manpage/html generation

[Christoph Hellwig]

On Thu, Jan 05, 2017@01:43:18PM -0800, Andy Grover wrote:
> On 11/24/2016 11:43 PM, Christoph Hellwig wrote:
>> Hi Jay,
>>
>> thanks a lot for writing this man page!  I have a few comments below,
>> but otherwise this looks really great.
>
> Hi, do you mind tagging this into a release?

Will do next week, just need to finish my work to automate the release cutting.