NAME
iscsictl —
program to manage iSCSI
instances
SYNOPSIS
iscsictl |
[-d
sockdir] command
[arguments ...] |
DESCRIPTION
The
iscsictl utility manages iSCSI instances on the local
computer. It talks to the
iscsid(8) program to perform
this management.
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
session
between initiator and target. The initiator
can then issue commands to and read responses from the target.
Firstly, the iSCSI initiator on the local machine must be made aware of the
network location of the target. The
add_send_target
is
used in
iscsictl to do this. The targets can be listed using
the
list_targets
command. To login from the initiator
to the target, the
login
command is used; this creates
a session between the initiator and target. The sessions can be listed by
using the
list_sessions
command.
Global Options
-
-
- -d
sockdir
- Specify the directory where the socket for
iscsid(8) lives.
Target Address
Specification
The target address specification for the
add_target and
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.
-
-
- -a
target-address
- Specify the target address by IP or FQDN.
-
-
- -n
target-name
- Specify the target by name.
-
-
- -p
port-num
- The TCP port to connect to the target on. (Default port is
3260)
-
-
- -g
group-tag
- The group tag, a 16-bit integer.
Portal Address
Specification
The portal address specification for the
add_portal command
may include an address (IP or FQDN), port, and group tag, plus portal options.
-
-
- -a
target-address
- Specify the target address by IP or FQDN.
-
-
- -p
port-num
- The TCP port to connect to the target on. (Default port is
3260)
-
-
- -g
group-tag
- The group tag, a 16-bit integer.
-
-
- -h
- Use a CRC32 header digest.
-
-
- -d
- Use a CRC32 data digest.
-
-
- -l
segment-length
- Specify the max received data segment length.
Target Options
Target options are as follows:
-
-
- -h
- Use a CRC32 header digest.
-
-
- -d
- Use a CRC32 data digest.
-
-
- -w
time
- Time to wait.
-
-
- -r
time
- Time to retain.
-
-
- -e
level
- Error recovery level.
-
-
- -l
segment-length
- Specify the max received data segment length.
Authentication Options
Authentication options are as follows:
-
-
- -t
type
- Specify authentication type. n
indicates no authentication, while c indicates CHAP
authentication, and C indicates Mutual CHAP
authentication.
-
-
- -u
name
- User name.
-
-
- -s
secret
- Initiator secret.
-
-
- -S
secret
- Target secret.
Commands
The
iscsictl command argument is taken from one of the
following options:
-
-
- version
- return version information from the
iscsictl utility and the
iscsid(8) daemon.
-
-
- add_target
target-address-spec
[target-opts]
[auth-opts]
[-N
symbolic-name]
- A target-address-spec may include
name, address, port, and group tag, with address/port/tag possibly
repeated.
-
-
- add_portal
portal-address-spec
[-I -target-id]
[-N
-symbolic-name]
- Add a portal to the list of portals.
-
-
- remove_target
-I target-id
-
- remove_target
-n target-name
- Remove a target by name or ID.
-
-
- slp_find_targets
- Not implemented.
-
-
- refresh_targets
[-I
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 “OK” value is printed. For more context on
the exact usage of this command, please see the example below.
-
-
- list_targets
- Display a list of targets the iSCSI initiator knows
about.
-
-
- add_send_target
-a target-address
[target-address-spec]
[target-opts]
[auth-opts]
[-N
symbolic-name]
- this command allows the iSCSI initiator to connect to an
iSCSI target. The subsequent -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.
-
-
- remove_send_target
-I target-id
-
- remove_send_target
-n target-name
- Remove a send target from the list by name or
target-id
-
-
- list_send_targets
- Display the list of send targets configured.
-
-
- add_isns_server
iSNS-address-spec
- Add an iSNS server using an address specification that may
include name, address, and port.
-
-
- remove_isns_server
-I isns-server-id
-
- remove_isns_server
-a isns-server-address
-
- find_isns_servers
- Not Implemented.
-
-
- list_isns_servers
-
- refresh_isns
[-I id]
-
- login
[-m]
[target-opts]
[auth-opts]
[-P
portal-id]
- To be able to communicate with the iSCSI target, the
initiator must login. This command allows this login to take place. The
subsequent -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 see the example below.
-
-
- logout
[-I
session-id]
-
- add_connection
[-m]
[target-opts]
[auth-opts]
[-P
portal-id]
-
- remove_connection
-I session-id -C
connection-id
-
- inquiry
[-l lun]
[-d detail]
[-p
pag]
-
- read_capacity
[-I session-id
[-l
lun]]
-
- report_luns
[-I
session-id]
-
- test_unit_ready
[-I
session-id]
-
- add_initiator
-a interface-address
[-N
symbolic-name]
-
- remove_initiator
-I portal-id
-
- list_initiators
-
- list_sessions
[-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 -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.
-
-
- set_node_name
-n initiator-name
[-A -alias]
[-i
isid]
- Set the initiator name. The default initiator name is
iqn.1994-04.org.netbsd:iscsi.<hostname>:<hostid> . An
alias can be specified as well as an
isid
EXAMPLES
iscsictl is intended to be used as follows:
The initiator itself can be loaded as a kernel module, and works successfully on
5.0 (the host called "burner"), running against the
NetBSD target on a 5.99 host.
burner# modload iscsi
burner# modstat iscsi
NAME CLASS SOURCE REFS ADDRESS SIZE REQUIRES
iscsi driver filesys 0 ffffffff813c6000 44208 -
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#
and, on the target end of the iSCSI session:
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
SEE ALSO
iscsid(8)
HISTORY
The
iscsictl utility appeared in
NetBSD
6.0.
AUTHORS
Alistair Crooks
<
agc@NetBSD.org> wrote
this manual page. The
iscsictl utility was contributed by
Wasabi Systems, Inc.