Module Name: othersrc
Committed By: agc
Date: Mon Aug 8 06:53:00 UTC 2011
Added Files:
othersrc/external/bsd/iscsi/sbin/iscsictl: iscsictl.8
Log Message:
Add a first pass at a manual page, iscsictl(8).
To generate a diff of this commit:
cvs rdiff -u -r0 -r1.1 othersrc/external/bsd/iscsi/sbin/iscsictl/iscsictl.8
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Added files:
Index: othersrc/external/bsd/iscsi/sbin/iscsictl/iscsictl.8
diff -u /dev/null othersrc/external/bsd/iscsi/sbin/iscsictl/iscsictl.8:1.1
--- /dev/null Mon Aug 8 06:53:00 2011
+++ othersrc/external/bsd/iscsi/sbin/iscsictl/iscsictl.8 Mon Aug 8 06:52:59 2011
@@ -0,0 +1,219 @@
+.\" $NetBSD: iscsictl.8,v 1.1 2011/08/08 06:52:59 agc Exp $
+.\"
+.\" Copyright (c) 2011 Alistair Crooks <[email protected]>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (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 5, 2011
+.Dt ISCSICTL 8
+.Os
+.Sh NAME
+.Nm iscsictl
+.Nd program to manage iSCSI instances
+.Sh SYNOPSIS
+.Nm
+.Op Fl v
+.Op Fl d Ar directory
+command
+.Op Ar arguments...
+.Sh DESCRIPTION
+The
+.Nm
+utility manages iSCSI instances on the local computer.
+It talks to the
+.Xr iscsid 8
+program to perform this management.
+.Pp
+iSCSI is a method for transferring SCSI commands across a TCP
+connection.
+The client which issues the SCSI command is called the initiator,
+and the device which receives the command and takes action
+is called the target; this mirrors SCSI devices, although instead
+of being physically attached to a host, the SCSI commands and
+responses take place over a TCP connection.
+iSCSI communication is done in sessions.
+The iSCSI initiator logs in to a terget across the network,
+possible authenticating itself; this creates an iSCSI session between initiator
+and target.
+The initiator can then issue commands
+and read responses from the target.
+.Pp
+Firstly, a TCP connection
+the iSCSI initiator on the local machine must be made
+aware of the network location of the target.
+The
+.Dv add_send_target
+is used in
+.Nm
+to do this.
+The targets can be listed using the
+.Dv list_targets
+command.
+To login from the initiator to the target, the
+.Dv login
+command is used; this creates a session between the initiator and target.
+The sessions can be listed by using
+the
+.Dv list_sessions
+command.
+.Pp
+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
+.Nm
+utility
+.It add_target
+.It add_portal
+.It remove_target
+.It slp_find_targets
+.It refresh_targets
+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
+.Dq OK
+value is printed.
+For more context on the exact usage of this
+command, please ee the worked example below.
+.It list_targets
+.It add_send_target
+this coomand allows the iSCSI initiator to connect to an iSCSI
+target. The subsequent
+.Fl a
+target provides the address of the target.
+This can be provided as a numerical IP address,
+or as a textual FQDN.
+For more context on the exact usage of this
+command, please ee the worked 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
+To be able to communicate with the iSCSI target, the initiator
+must login. This command allows this login to take place.
+The subsequent
+.Fl P session
+argument provides the session which should be used to
+perform the login.
+On successful completion of this command, the
+session which has been created will be displayed, along with the connection
+number.
+For more context on the exact usage of this
+command, please ee the worked 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
+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 ee the worked example below.
+.It set_node_name
+.El
+.Pp
+.Nm
+is intended to be used as follows:
+.Sh EXAMPLES
+.Pp
+The initiator itself can be loaded as an lkm, and works successfully
+on 2.0 (the "burner" host), running against the NetBSD target on a 5.99 host.
+.Pp
+.Bd -literal
+burner# modload -v -s -p /usr/lkm/iscsi_post.sh /usr/lkm/iscsidrv.o
+modload: reserving 36864 bytes of memory
+Module loaded as ID 0
+burner# iscsid
+iSCSI Daemon loaded
+burner# iscsictl add_send_target -a 172.16.135.133
+Added Send Target 1
+burner# iscsictl refresh_targets
+OK
+burner# iscsictl list_targets
+ 1: iqn.1994-04.org.netbsd.iscsi-target:target0
+ 2: 172.16.135.133:3260,1
+burner# iscsictl login -P 2
+Created Session 2, Connection 1
+burner# iscsictl list_sessions
+Session 2: Target iqn.1994-04.org.netbsd.iscsi-target:target0
+burner# newfs /dev/rsd0a
+/dev/rsd0a: 100.0MB (204800 sectors) block size 8192, fragment size 1024
+ using 4 cylinder groups of 25.00MB, 3200 blks, 6144 inodes.
+super-block backups (for fsck -b #) at:
+ 32, 51232, 102432, 153632,
+burner# mount /dev/sd0a /mnt
+burner# df
+Filesystem 1K-blocks Used Avail Capacity Mounted on
+/dev/wd0a 4066094 186994 3675795 4% /
+kernfs 1 1 0 100% /kern
+/dev/sd0a 99247 1 94283 0% /mnt
+burner# dmesg | egrep '(scsibus|sd0)'
+scsibus0 at bha2: 16 targets, 8 luns per target
+scsibus0: waiting 2 seconds for devices to settle...
+scsibus1 at iscsi0: 1 target, 16 luns per target
+sd0 at scsibus1 target 0 lun 0: <NetBSD, NetBSD iSCSI, 0> disk fixed
+sd0: fabricating a geometry
+sd0: 100 MB, 100 cyl, 64 head, 32 sec, 512 bytes/sect x 204800 sectors
+sd0: fabricating a geometry
+sd0: fabricating a geometry
+sd0: fabricating a geometry
+burner#
+.Ed
+.Pp
+and, on the target end of the iSCSI session:
+.Bd -literal
+Reading configuration from `/etc/iscsi/targets'
+target0:rw:0.0.0.0/0
+ extent0:/tmp/iscsi-target0:0:104857600
+DISK: 1 logical unit (204800 blocks, 512 bytes/block), type iscsi fs
+DISK: LUN 0: 100 MB disk storage for "target0"
+TARGET: iSCSI Qualified Name (IQN) is iqn.1994-04.org.netbsd.iscsi-target
+> iSCSI Discovery login successful from iqn.1994-04.org.netbsd:iscsi.burner.cupertino.alistaircrooks.com:0 on 172.16.135.137 disk -1, ISID 70368764559360, TSIH 1
+< iSCSI Discovery logout successful from iqn.1994-04.org.netbsd:iscsi.burner.cupertino.alistaircrooks.com:0 on 172.16.135.137 disk -1, ISID 70368764559360, TSIH 1
+> iSCSI Normal login successful from iqn.1994-04.org.netbsd:iscsi.burner.cupertino.alistaircrooks.com:0 on 172.16.135.137 disk 0, ISID 70368764559360, TSIH 2
+.Ed
+.Sh SEE ALSO
+.Xr iscsid 8
+.Sh HISTORY
+The
+.Nm
+utility appeared in
+.Nx 6.0 .
+.Sh AUTHORS
+.An Alistair Crooks Aq [email protected]
+wrote this manual page.
+The
+.Nm
+utility was contributed by Wasabi Systems, Inc.
