Aren
/
NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NetBSD/sbin/iscsictl/iscsictl.8

334 lines
11 KiB
Groff
Raw Normal View History

Merge riastradh-drm2 to HEAD.
2014-03-18 22:20:35 +04:00
.\" $NetBSD: iscsictl.8,v 1.7 2014/03/18 18:20:38 riastradh Exp $
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
.\"
.\" Copyright (c) 2011 Alistair Crooks <agc@NetBSD.org>
.\" 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.
.\"
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.
2012-05-27 00:03:34 +04:00
.Dd May 26, 2012
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
.Dt ISCSICTL 8
.Os
.Sh NAME
.Nm iscsictl
.Nd program to manage iSCSI instances
.Sh SYNOPSIS
.Nm
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.
2012-05-27 00:03:34 +04:00
.Op Fl d Ar sockdir
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
.Ar 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 network.
iSCSI communication is done in sessions.
The iSCSI initiator logs in to a target across the network,
possibly authenticating itself; this creates an iSCSI
.Dv session
between initiator
and target.
The initiator can then issue commands to
and read responses from the target.
.Pp
Firstly, 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.
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.
2012-05-27 00:03:34 +04:00
.Ss Global Options
Fix Bl -tag width arguments.
2012-06-02 15:54:07 +04:00
.Bl -tag -width xdxsockdirx
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.
2012-05-27 00:03:34 +04:00
.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
NetBSD -> Nx; new sentence, new line; remove superfluous Pp.
2012-05-27 15:59:12 +04:00
The TCP port to connect to the target on.
(Default port is 3260)
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.
2012-05-27 00:03:34 +04:00
.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
NetBSD -> Nx; new sentence, new line; remove superfluous Pp.
2012-05-27 15:59:12 +04:00
The TCP port to connect to the target on.
(Default port is 3260)
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.
2012-05-27 00:03:34 +04:00
.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:
Fix Bl -tag width arguments.
2012-06-02 15:54:07 +04:00
.Bl -tag -width xsxsecretx
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.
2012-05-27 00:03:34 +04:00
.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
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
The
.Nm
command argument is taken from one of the following options:
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.
2012-05-27 00:03:34 +04:00
.Bl -tag -width 5n
.It Cm version
return version information from the
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
.Nm
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.
2012-05-27 00:03:34 +04:00
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
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
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 see the example below.
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.
2012-05-27 00:03:34 +04:00
.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
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
this command 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 see the example below.
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.
2012-05-27 00:03:34 +04:00
.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
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
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 Ar 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 see the example below.
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.
2012-05-27 00:03:34 +04:00
.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
The 'list_sessions' command has a -c flag to display connections associated with the sessions.
2012-05-29 04:33:04 +04:00
.It Cm list_sessions Op Fl c
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
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.
The 'list_sessions' command has a -c flag to display connections associated with the sessions.
2012-05-29 04:33:04 +04:00
If the
.Fl c
flag is used, connection information is displayed as well.
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
For more context on the exact usage of this
command, please see the example below.
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.
2012-05-27 00:03:34 +04:00
.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
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
.El
.Sh EXAMPLES
.Nm
is intended to be used as follows:
.Pp
The initiator itself can be loaded as a kernel module, and works successfully
NetBSD -> Nx; new sentence, new line; remove superfluous Pp.
2012-05-27 15:59:12 +04:00
on 2.0 (the host called "burner"), running against the
.Nx
target on a 5.99 host.
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
.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
.\" how do we know that it was assigned sd0?
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
Use Mt for email addresses.
2013-07-21 01:39:55 +04:00
.An Alistair Crooks Aq Mt agc@NetBSD.org
Start to move the in-kernel iSCSI initiator, kindly contributed to the NetBSD Foundation by Wasabi Systems, from othersrc/external/bsd/iscsi/{iscsictl,iscsid} to src/sbin/{iscsictl,iscsid}
2011-10-24 01:11:23 +04:00
wrote this manual page.
The
.Nm
utility was contributed by Wasabi Systems, Inc.