[Libstoragemgmt-devel] [PATCH] Suggested edits to manpages

Tony Asleson

2014-12-02 23:19:28 UTC

Signed-off-by: Tony Asleson <***@redhat.com>
---
doc/man/nstor_lsmplugin.1.in | 34 +++++++++++++++++++---------------
doc/man/ontap_lsmplugin.1.in | 21 ++++++++++-----------
doc/man/sim_lsmplugin.1.in | 39 +++++++++++++++++++++++----------------
doc/man/simc_lsmplugin.1.in | 30 +++++++++++++-----------------
doc/man/targetd_lsmplugin.1.in | 33 +++++++++++++++++++--------------
5 files changed, 84 insertions(+), 73 deletions(-)

diff --git a/doc/man/nstor_lsmplugin.1.in b/doc/man/nstor_lsmplugin.1.in
index 99f484b..9a81a9e 100644
--- a/doc/man/nstor_lsmplugin.1.in
+++ b/doc/man/nstor_lsmplugin.1.in
@@ -1,26 +1,24 @@
-.TH NSTOR_LSMPLUGIN "1" "November 2014" "NSTOR_LSMPLUGIN @VERSION@" "libStorageMgmt"
+.TH nstor_lsmplugin "1" "November 2014" "nstor_lsmplugin @VERSION@" "libStorageMgmt"
.SH NAME
-nstor_lsmplugin -- LibstorageMgmt Targetd Plugin
+nstor_lsmplugin -- LibstorageMgmt nstor plugin

.SH DESCRIPTION
-LibstorageMgmt Nstor Plugin allows LibstorageMgmt user to manage
-NexentaStor 3.x storage array.
-.br
-The 'nstor_lsmplugin' executable file is for LibstorageMgmt daemon to
-execute when client user requests Nstor plugin.
+LibstorageMgmt nstor plugin allows user to manage NexentaStor 3.x
+storage software [1]. The 'nstor_lsmplugin' executable file is for libStorageMgmt
+daemon to execute when client user specifies nstor plugin in the URI.

.SH URI
To use this plugin, users should set their URI to this format:
.nf

# HTTP connection
- nstor://<username>@<nstor_mgm_ip>
+ nstor://<username>@<nstor_server>:<port>

# HTTPS connection
- nstor+ssl://<username>@<nstor_mgm_ip>
+ nstor+ssl://<username>@<nstor_server>:<port>

.fi
-No URI parameter is supported by this plugin.
+No additional URI parameters are supported by this plugin.

.TP
\fBusername\fR
@@ -28,12 +26,18 @@ No URI parameter is supported by this plugin.
The \fBusername\fR is the user account with 'Can_use_restapi' permission.

.TP
-\fBnstor_mgm_ip\fR
+\fBnstor_server\fR

-The \fBnstor_mgm_ip\fR is the management IP address or DNS name of
-NexentaStor.
+The \fBnstor_server\fR is IP address or DNS name of
+NexentaStor server.

-.SH Supported Hardware
+.TP
+\fBport number\fR
+
+The \fBport number\fR is the listening port of the nexenta server REST API.
+The default port of 2000 is used if none is supplied on the URI.
+
+.SH SUPPORTED SOFTWARE
NexentaStor 3.x is supported.
Detailed support status can be queried via:

@@ -42,7 +46,7 @@ Detailed support status can be queried via:
* \fBlsmcli capabilities\fR (lsmcli command line).

.SH SEE ALSO
-\fBlsmcli\fR(1), \fBlsmd\fR(1)
+\fBlsmcli\fR(1), \fBlsmd\fR(1), [1] http://nexentastor.org

.SH BUGS
Please report bugs to
diff --git a/doc/man/ontap_lsmplugin.1.in b/doc/man/ontap_lsmplugin.1.in
index 601124c..c64018e 100644
--- a/doc/man/ontap_lsmplugin.1.in
+++ b/doc/man/ontap_lsmplugin.1.in
@@ -1,19 +1,18 @@
-.TH ONTAP_LSMPLUGIN "1" "November 2014" "ONTAP_LSMPLUGIN @VERSION@" "libStorageMgmt"
+.TH ontap_lsmplugin "1" "November 2014" "ontap_lsmplugin @VERSION@" "libStorageMgmt"
.SH NAME
-ontap_lsmplugin -- LibstorageMgmt ONTAP Plugin
+ontap_lsmplugin -- LibstorageMgmt ontap plugin

.SH DESCRIPTION
-LibstorageMgmt ONTAP Plugin allows LibstorageMgmt user to manage NetApp ONTAP
-storage arrays.
-The 'ontap_lsmplugin' executable file is for LibstorageMgmt daemon to execute
-when client user requests ONTAP plugin.
+LibstorageMgmt ontap plugin allows user to manage NetApp ONTAP storage arrays.
+The 'ontap_lsmplugin' executable file is for libStorageMgmt daemon to execute
+when client specifies ontap plugin in the URI.

-This plugin require NetApp ONTAP storage array enable these options:
+This plugin requires NetApp ONTAP storage array to enable these options:

options httpd.enable on
options httpd.admin.enable on

-This options is require for HTTPS connection:
+This options is required for HTTPS connection:

options httpd.admin.ssl.enable on

@@ -22,13 +21,13 @@ To use this plugin, users should set their URI to this format:
.nf

# HTTP connection
- ontap://<username>@<ontap_filer_ip>
+ ontap://<username>@<ontap_filer>

# HTTPS connection
- ontap+ssl://<username>@<ontap_filer_ip>
+ ontap+ssl://<username>@<ontap_filer>

.fi
-No URI parameter is supported by this plugin.
+No additional URI parameters are supported by this plugin.

.TP
\fBusername\fR
diff --git a/doc/man/sim_lsmplugin.1.in b/doc/man/sim_lsmplugin.1.in
index 57530b4..aab3326 100644
--- a/doc/man/sim_lsmplugin.1.in
+++ b/doc/man/sim_lsmplugin.1.in
@@ -1,38 +1,45 @@
-.TH SIM_LSMPLUGIN "1" "November 2014" "SIM_LSMPLUGIN @VERSION@" "libStorageMgmt"
+.TH sim_lsmplugin "1" "November 2014" "sim_lsmplugin @VERSION@" "libStorageMgmt"
.SH NAME
-sim_lsmplugin -- LibstorageMgmt Simulator Plugin
+sim_lsmplugin -- LibStorageMgmt simulator python plugin

.SH DESCRIPTION
-LibstorageMgmt Simulator Plugin is for develop or test only which simulator
-a full featured storage array based on a state file(
-by default storing state data into '/tmp/lsm_sim_data').
+LibstorageMgmt simulator plugin is for development or test use only. The plugin
+simulates an array which supports most features of the library. State is stored
+in a file, default is '/tmp/lsm_sim_data'. The 'sim_lsmplugin' executable file is
+for libStorageMgmt daemon to execute when client user specifies sim plugin in
+the URI.

-This plugin is written in pure Python which is also a LibstorageMgmt Python
-plugin demonstration.
+This plugin is written in pure Python and is intended to be an example of a
+python plugin for the library.

.SH URI
To use this plugin, users should set their URI to this format:
.nf

- sim://?<uri_parameters>
+ # All that is required
+ sim://
+
+ # Optional statefile
+ sim://?statefile=<file path and name>

.fi
No password is required for this plugin.

-.TP
-\fBuri_parameters\fR
-This URI parameter is supported by this plugin:

-.RS 7
.TP
-\fBstatefile=<state_file_path>\fR
-Define a file to store simulator array state data. Example URI:
+\fBstatefile\fR
+
+Use specified file to store simulator state data. Example URI:
.nf
\fBsim://?statefile=/tmp/other_lsm_sim_data\fR
.fi

-.SH Supported Hardware
-N/A
+The statefile is stored via python
+pickle module. From the python docs:
+
+"The pickle module is not intended to be secure against
+erroneous or maliciously constructed data. Never unpickle data received
+from an untrusted or unauthenticated source."

.SH SEE ALSO
\fBlsmcli\fR(1), \fBlsmd\fR(1)
diff --git a/doc/man/simc_lsmplugin.1.in b/doc/man/simc_lsmplugin.1.in
index 3aff84b..74fcc5e 100644
--- a/doc/man/simc_lsmplugin.1.in
+++ b/doc/man/simc_lsmplugin.1.in
@@ -1,21 +1,20 @@
-.TH SIMC_LSMPLUGIN "1" "November 2014" "SIMC_LSMPLUGIN @VERSION@" "libStorageMgmt"
+.TH simc_lsmplugin "1" "November 2014" "simc_lsmplugin @VERSION@" "libStorageMgmt"
.SH NAME
-simc_lsmplugin -- LibstorageMgmt Simulator C Plugin
+simc_lsmplugin -- LibstorageMgmt simulator C plugin

.SH DESCRIPTION
-LibstorageMgmt Simulator C Plugin is for develop or test only which simulator
-a memory based full featured storage array.
+LibStorageMgmt simulator C plugin is for development use. The plugin
+simulates an array which supports most features of the library. The simulator
+is memory based, state will be discarded once the plugin exits. The 'simc_lsmplugin'
+executable file is for the libStorageMgmt daemon to execute when client user specifies
+simc plugin in the URI.

-Storage state of this plugin is memory based and will be eliminated once
-the LibstorageMgmt session is closed.
+Since every command of lsmcli is a standalone libStorageMgmt session, this
+plugin is essentially useless for this purpose. In this use case, the
+libStorageMgmt simulator plugin \fBsim_lsmplugin(1)\fR is suggested.

-Since every command of lsmcli is a standalone LibstorageMgmt session, when
-using this plugin via lsmcli, user will not be able to query out newlly
-created resources(volume, access group). In that case, the
-LibstorageMgmt Simulator Plugin \fBsim_lsmplugin(1)\fR is suggested.
-
-This plugin is written in pure C code which is also a LibstorageMgmt C
-plugin demonstration.
+This plugin is written in pure C and is intended to be an example of a
+C plugin for the library.

.SH URI
To use this plugin, users should set their URI to this format:
@@ -25,10 +24,7 @@ To use this plugin, users should set their URI to this format:

.fi
No password is required for this plugin.
-No URI parameter is supported by this plugin.
-
-.SH Supported Hardware
-N/A
+No URI parameters are supported by this plugin.

.SH SEE ALSO
\fBlsmcli\fR(1), \fBlsmd\fR(1), \fBsim_lsmplugin\fR(1)
diff --git a/doc/man/targetd_lsmplugin.1.in b/doc/man/targetd_lsmplugin.1.in
index bcdd2e5..978d71e 100644
--- a/doc/man/targetd_lsmplugin.1.in
+++ b/doc/man/targetd_lsmplugin.1.in
@@ -1,26 +1,25 @@
-.TH TARGETD_LSMPLUGIN "1" "November 2014" "TARGETD_LSMPLUGIN @VERSION@" "libStorageMgmt"
+.TH targetd_lsmplugin "1" "November 2014" "targetd_lsmplugin @VERSION@" "libStorageMgmt"
.SH NAME
-targetd_lsmplugin -- LibstorageMgmt Targetd Plugin
+targetd_lsmplugin -- libStorageMgmt targetd plugin

.SH DESCRIPTION
-LibstorageMgmt Targetd Plugin allows LibstorageMgmt user to manage
-Linux targetd iSCSI target.
-.br
-The 'targetd_lsmplugin' executable file is for LibstorageMgmt daemon to
-execute when client user requests targetd plugin.
+LibStorageMgmt targetd plugin allows user to manage storage using
+the targetd storage API [1]. The 'targetd_lsmplugin' executable file is for
+libStorageMgmt daemon to execute when client user specifies targetd plugin in
+the URI.

.SH URI
To use this plugin, users should set their URI to this format:
.nf

# HTTP connection
- targetd://<username>@<targetd_server_ip>
+ targetd://<username>@<targetd_server>:<port number>

# HTTPS connection
- targetd+ssl://<username>@<targetd_server_ip>
+ targetd+ssl://<username>@<targetd_server>:<port number>

.fi
-No URI parameter is supported by this plugin.
+No additional URI parameters are supported by this plugin.

.TP
\fBusername\fR
@@ -29,12 +28,18 @@ The \fBusername\fR is the user account configured in targetd configuration
file.

.TP
-\fBtargetd_server_ip\fR
+\fBtargetd_server\fR

-The \fBtargetd_server_ip\fR is the IP address or DNS name of server running
+The \fBtargetd_server\fR is the IP address or DNS name of server running
targetd daemon.

-.SH Supported Hardware
+.TP
+\fBport number\fR
+
+The \fBport number\fR is the listening port of the targetd daemon. The default
+port of 18700 is used if none is supplied on the URI.
+
+.SH SUPPORTED SOFTWARE
Linux targetd 0.7.1 or later version.
Detailed support status can be queried via:

@@ -43,7 +48,7 @@ Detailed support status can be queried via:
* \fBlsmcli capabilities\fR (lsmcli command line).

.SH SEE ALSO
-\fBlsmcli\fR(1), \fBlsmd\fR(1)
+\fBlsmcli\fR(1), \fBlsmd\fR(1), [1] https://github.com/agrover/targetd

.SH BUGS
Please report bugs to

--
1.8.2.1

Tony Asleson

2014-12-02 23:20:59 UTC

Permalink

--
1.8.2.1