[src/trunk]: src/sbin/iscsictl Begin the tedious process of documenting iscsi...

[riz <riz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a49ea4b134ed
branches:  trunk
changeset: 779407:a49ea4b134ed
user:      riz <riz%NetBSD.org@localhost>
date:      Sat May 26 20:03:34 2012 +0000

description:
Begin the tedious process of documenting iscsictl(8) commands,
options, and flags.  I gathered this information by tediously
slogging through the source code, so it's likely to be incomplete
and occasionally flat wrong.

At a minimum, specify which options the various commands take, and
clarify the address specifications.  There is still much to do,
but this increases the usefulness of this man page for me, at least.

diffstat:

 sbin/iscsictl/iscsictl.8 |  176 +++++++++++++++++++++++++++++++++++++---------
 1 files changed, 141 insertions(+), 35 deletions(-)

diffs (234 lines):

diff -r 359b8641a0c9 -r a49ea4b134ed sbin/iscsictl/iscsictl.8
--- a/sbin/iscsictl/iscsictl.8  Sat May 26 19:34:16 2012 +0000
+++ b/sbin/iscsictl/iscsictl.8  Sat May 26 20:03:34 2012 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: iscsictl.8,v 1.1 2011/10/23 21:11:23 agc Exp $
+.\" $NetBSD: iscsictl.8,v 1.2 2012/05/26 20:03:34 riz Exp $
 .\"
 .\" Copyright (c) 2011 Alistair Crooks <agc%NetBSD.org@localhost>
 .\" All rights reserved.
@@ -23,7 +23,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd August 8, 2011
+.Dd May 26, 2012
 .Dt ISCSICTL 8
 .Os
 .Sh NAME
@@ -31,8 +31,7 @@
 .Nd program to manage iSCSI instances
 .Sh SYNOPSIS
 .Nm
-.Op Fl v
-.Op Fl d Ar directory
+.Op Fl d Ar sockdir
 .Ar command
 .Op Ar arguments ...
 .Sh DESCRIPTION
@@ -76,19 +75,110 @@
 .Dv list_sessions
 command.
 .Pp
+.Ss Global Options
+.Bl -tag width xdxsockdirx
+.It Fl d Ar sockdir
+Specify the directory where the socket for
+.Xr iscsid 8
+lives.
+.El
+.Ss Target Address Specification
+The target address specification for the
+.Ic add_target
+and
+.Ic add_send_target
+commands may include a target name, target address (IP or FQDN),
+TCP port, and group tag.
+Either the target address or target name is required.
+(For add_send_target, a target address is required).
+The address, port, and group tag may optionally be repeated.
+.Bl -tag -width xaxtarget-addressx
+.It Fl a Ar target-address
+Specify the target address by IP or FQDN.
+.It Fl n Ar target-name
+Specify the target by name.
+.It Fl p Ar port-num
+The TCP port to connect to the target on.  (Default port is 3260)
+.It Fl g Ar group-tag
+The group tag, a 16-bit integer.
+.El
+.Ss Portal Address Specification
+The portal address specification for the
+.Ic add_portal
+command may include an address (IP or FQDN), port, and group tag, plus
+portal options.
+.Bl -tag -width xaxtarget-addressx
+.It Fl a Ar target-address
+Specify the target address by IP or FQDN.
+.It Fl p Ar port-num
+The TCP port to connect to the target on.  (Default port is 3260)
+.It Fl g Ar group-tag
+The group tag, a 16-bit integer.
+.It Fl h
+Use a CRC32 header digest.
+.It Fl d
+Use a CRC32 data digest.
+.It Fl l Ar segment-length
+Specify the max received data segment length.
+.El
+.Ss Target Options
+Target options are as follows:
+.Bl -tag -width xlxsegment-lengthx
+.It Fl h
+Use a CRC32 header digest.
+.It Fl d
+Use a CRC32 data digest.
+.It Fl w Ar time
+Time to wait.
+.It Fl r Ar time
+Time to retain.
+.It Fl e Ar level
+Error recovery level.
+.It Fl l Ar segment-length
+Specify the max received data segment length.
+.El
+.Ss Authentication Options
+Authentication options are as follows:
+.Bl -tag width 5n
+.It Fl t Ar type
+Specify authentication type.
+.Ar n
+indicates no authentication, while
+.Ar c
+indicates CHAP authentication, and
+.Ar C
+indicates Mutual CHAP authentication.
+.It Fl u Ar name
+User name.
+.It Fl s Ar secret
+Initiator secret.
+.It Fl S Ar secret
+Target secret.
+.El
+.Ss Nm Commands
 The
 .Nm
 command argument is taken from one of the following options:
-.Bl -tag -width XCXremove_send_targetXX
-.It version
-return the version number of the
+.Bl -tag -width 5n
+.It Cm version
+return version information from the
 .Nm
-utility
-.It add_target
-.It add_portal
-.It remove_target
-.It slp_find_targets
-.It refresh_targets
+utility and the
+.Xr iscsid 8
+daemon.
+.It Cm add_target Ar target-address-spec Oo Ar target-opts Oc Oo Ar auth-opts Oc Oo Fl N Ar symbolic-name Oc
+A
+.Ar target-address-spec
+may include name, address, port, and group tag, with address/port/tag
+possibly repeated.
+.It Cm add_portal Ar portal-address-spec Oo Fl I target-id Oc Oo Fl N symbolic-name Oc
+Add a portal to the list of portals.
+.It Cm remove_target Fl I Ar target-id
+.It Cm remove_target Fl n Ar target-name
+Remove a target by name or ID.
+.It Cm slp_find_targets
+Not implemented.
+.It Cm refresh_targets Op Fl I Ar target-id
 this command causes the iSCSI initiator to refresh its view of the
 iSCSI targets to which it is connected.
 If this command completes successfully, an
@@ -96,8 +186,9 @@
 value is printed.
 For more context on the exact usage of this
 command, please see the example below.
-.It list_targets
-.It add_send_target
+.It Cm list_targets
+Display a list of targets the iSCSI initiator knows about.
+.It Cm add_send_target Fl a Ar target-address Oo Ar target-address-spec Oc Oo Ar target-opts Oc Oo Ar auth-opts Oc Oo Fl N Ar symbolic-name Oc
 this command allows the iSCSI initiator to connect to an iSCSI
 target.
 The subsequent
@@ -107,14 +198,22 @@
 or as a textual FQDN.
 For more context on the exact usage of this
 command, please see the example below.
-.It remove_send_target
-.It list_send_targets
-.It add_isns_server
-.It remove_isns_server
-.It find_isns_servers
-.It list_isns_servers
-.It refresh_isns
-.It login
+.It Cm remove_send_target Fl I Ar target-id
+.It Cm remove_send_target Fl n Ar target-name
+Remove a send target from the list by name or
+.Ar target-id
+.It Cm list_send_targets
+Display the list of send targets configured.
+.It Cm add_isns_server Ar iSNS-address-spec
+Add an iSNS server using an address specification that may include name,
+address, and port.
+.It Cm remove_isns_server Fl I Ar isns-server-id
+.It Cm remove_isns_server Fl a Ar isns-server-address
+.It Cm find_isns_servers
+Not Implemented.
+.It Cm list_isns_servers
+.It Cm refresh_isns Op Fl I Ar id
+.It Cm login Oo Fl m Oc Oo Ar target-opts Oc Oo Ar auth-opts Oc Oo Fl P Ar portal-id Oc
 To be able to communicate with the iSCSI target, the initiator
 must login.
 This command allows this login to take place.
@@ -127,23 +226,30 @@
 number.
 For more context on the exact usage of this
 command, please see the example below.
-.It logout
-.It add_connection
-.It remove_connection
-.It inquiry
-.It read_capacity
-.It report_luns
-.It test_unit_ready
-.It add_initiator
-.It remove_initiator
-.It list_initiators
-.It list_sessions
+.It Cm logout Op Fl I Ar session-id
+.It Cm add_connection Oo Fl m Oc Oo Ar target-opts Oc Oo Ar auth-opts Oc Oo Fl P Ar portal-id Oc
+.It Cm remove_connection Fl I Ar session-id Fl C Ar connection-id
+.It Cm inquiry Oo Fl l Ar lun Oc Oo Fl d Ar detail Oc Oo Fl p Ar pag Oc
+.It Cm read_capacity Op Fl I Ar session-id Op Fl l Ar lun
+.It Cm report_luns Op Fl I Ar session-id
+.It Cm test_unit_ready Op Fl I Ar session-id
+.It Cm add_initiator Fl a Ar interface-address Op Fl N Ar symbolic-name
+.It Cm remove_initiator Fl I Ar portal-id
+.It Cm list_initiators
+.It Cm list_sessions
 Once login to the target has taken place, a session will have been created.
 To list the session information, this command is used.
 The session number and target information for each of the targets are displayed.
 For more context on the exact usage of this
 command, please see the example below.
-.It set_node_name
+.It Cm set_node_name Fl n Ar initiator-name Oo Fl A alias Oc Oo Fl i Ar isid Oc
+Set the initiator name.
+The default initiator name is
+iqn.1994-04.org.netbsd:iscsi.<hostname>:<hostid> .
+An
+.Ar alias
+can be specified as well as an
+.Ar isid
 .El
 .Sh EXAMPLES
 .Nm