334 lines
11 KiB
Groff
334 lines
11 KiB
Groff
.\" $NetBSD: iscsictl.8,v 1.7 2014/03/18 18:20:38 riastradh Exp $
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.Dd May 26, 2012
|
|
.Dt ISCSICTL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm iscsictl
|
|
.Nd program to manage iSCSI instances
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl d Ar sockdir
|
|
.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.
|
|
.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 xsxsecretx
|
|
.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 5n
|
|
.It Cm version
|
|
return version information from the
|
|
.Nm
|
|
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
|
|
.Dq OK
|
|
value is printed.
|
|
For more context on the exact usage of this
|
|
command, please see the example below.
|
|
.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
|
|
.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.
|
|
.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.
|
|
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.
|
|
.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 Op Fl c
|
|
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.
|
|
If the
|
|
.Fl c
|
|
flag is used, connection information is displayed as well.
|
|
For more context on the exact usage of this
|
|
command, please see the example below.
|
|
.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
|
|
is intended to be used as follows:
|
|
.Pp
|
|
The initiator itself can be loaded as a kernel module, and works successfully
|
|
on 2.0 (the host called "burner"), running against the
|
|
.Nx
|
|
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
|
|
.\" 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
|
|
.An Alistair Crooks Aq Mt agc@NetBSD.org
|
|
wrote this manual page.
|
|
The
|
|
.Nm
|
|
utility was contributed by Wasabi Systems, Inc.
|