1.\" $NetBSD: iscsictl.8,v 1.9 2015/08/30 10:49:57 jnemeth Exp $ 2.\" 3.\" Copyright (c) 2011 Alistair Crooks <agc@NetBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd August 30, 2015 27.Dt ISCSICTL 8 28.Os 29.Sh NAME 30.Nm iscsictl 31.Nd program to manage iSCSI instances 32.Sh SYNOPSIS 33.Nm 34.Op Fl d Ar sockdir 35.Ar command 36.Op Ar arguments ... 37.Sh DESCRIPTION 38The 39.Nm 40utility manages iSCSI instances on the local computer. 41It talks to the 42.Xr iscsid 8 43program to perform this management. 44.Pp 45iSCSI is a method for transferring SCSI commands across a TCP 46connection. 47The client which issues the SCSI command is called the initiator, 48and the device which receives the command and takes action 49is called the target; this mirrors SCSI devices, although instead 50of being physically attached to a host, the SCSI commands and 51responses take place over a network. 52iSCSI communication is done in sessions. 53The iSCSI initiator logs in to a target across the network, 54possibly authenticating itself; this creates an iSCSI 55.Dv session 56between initiator 57and target. 58The initiator can then issue commands to 59and read responses from the target. 60.Pp 61Firstly, the iSCSI initiator on the local machine must be made 62aware of the network location of the target. 63The 64.Dv add_send_target 65is used in 66.Nm 67to do this. 68The targets can be listed using the 69.Dv list_targets 70command. 71To login from the initiator to the target, the 72.Dv login 73command is used; this creates a session between the initiator and target. 74The sessions can be listed by using the 75.Dv list_sessions 76command. 77.Ss Global Options 78.Bl -tag -width xdxsockdirx 79.It Fl d Ar sockdir 80Specify the directory where the socket for 81.Xr iscsid 8 82lives. 83.El 84.Ss Target Address Specification 85The target address specification for the 86.Ic add_target 87and 88.Ic add_send_target 89commands may include a target name, target address (IP or FQDN), 90TCP port, and group tag. 91Either the target address or target name is required. 92(For add_send_target, a target address is required). 93The address, port, and group tag may optionally be repeated. 94.Bl -tag -width xaxtarget-addressx 95.It Fl a Ar target-address 96Specify the target address by IP or FQDN. 97.It Fl n Ar target-name 98Specify the target by name. 99.It Fl p Ar port-num 100The TCP port to connect to the target on. 101(Default port is 3260) 102.It Fl g Ar group-tag 103The group tag, a 16-bit integer. 104.El 105.Ss Portal Address Specification 106The portal address specification for the 107.Ic add_portal 108command may include an address (IP or FQDN), port, and group tag, plus 109portal options. 110.Bl -tag -width xaxtarget-addressx 111.It Fl a Ar target-address 112Specify the target address by IP or FQDN. 113.It Fl p Ar port-num 114The TCP port to connect to the target on. 115(Default port is 3260) 116.It Fl g Ar group-tag 117The group tag, a 16-bit integer. 118.It Fl h 119Use a CRC32 header digest. 120.It Fl d 121Use a CRC32 data digest. 122.It Fl l Ar segment-length 123Specify the max received data segment length. 124.El 125.Ss Target Options 126Target options are as follows: 127.Bl -tag -width xlxsegment-lengthx 128.It Fl h 129Use a CRC32 header digest. 130.It Fl d 131Use a CRC32 data digest. 132.It Fl w Ar time 133Time to wait. 134.It Fl r Ar time 135Time to retain. 136.It Fl e Ar level 137Error recovery level. 138.It Fl l Ar segment-length 139Specify the max received data segment length. 140.El 141.Ss Authentication Options 142Authentication options are as follows: 143.Bl -tag -width xsxsecretx 144.It Fl t Ar type 145Specify authentication type. 146.Ar n 147indicates no authentication, while 148.Ar c 149indicates CHAP authentication, and 150.Ar C 151indicates Mutual CHAP authentication. 152.It Fl u Ar name 153User name. 154.It Fl s Ar secret 155Initiator secret. 156.It Fl S Ar secret 157Target secret. 158.El 159.Ss Nm Commands 160The 161.Nm 162command argument is taken from one of the following options: 163.Bl -tag -width 5n 164.It Cm version 165return version information from the 166.Nm 167utility and the 168.Xr iscsid 8 169daemon. 170.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 171A 172.Ar target-address-spec 173may include name, address, port, and group tag, with address/port/tag 174possibly repeated. 175.It Cm add_portal Ar portal-address-spec Oo Fl I target-id Oc Oo Fl N symbolic-name Oc 176Add a portal to the list of portals. 177.It Cm remove_target Fl I Ar target-id 178.It Cm remove_target Fl n Ar target-name 179Remove a target by name or ID. 180.It Cm slp_find_targets 181Not implemented. 182.It Cm refresh_targets Op Fl I Ar target-id 183this command causes the iSCSI initiator to refresh its view of the 184iSCSI targets to which it is connected. 185If this command completes successfully, an 186.Dq OK 187value is printed. 188For more context on the exact usage of this 189command, please see the example below. 190.It Cm list_targets 191Display a list of targets the iSCSI initiator knows about. 192.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 193this command allows the iSCSI initiator to connect to an iSCSI 194target. 195The subsequent 196.Fl a 197target provides the address of the target. 198This can be provided as a numerical IP address, 199or as a textual FQDN. 200For more context on the exact usage of this 201command, please see the example below. 202.It Cm remove_send_target Fl I Ar target-id 203.It Cm remove_send_target Fl n Ar target-name 204Remove a send target from the list by name or 205.Ar target-id 206.It Cm list_send_targets 207Display the list of send targets configured. 208.It Cm add_isns_server Ar iSNS-address-spec 209Add an iSNS server using an address specification that may include name, 210address, and port. 211.It Cm remove_isns_server Fl I Ar isns-server-id 212.It Cm remove_isns_server Fl a Ar isns-server-address 213.It Cm find_isns_servers 214Not Implemented. 215.It Cm list_isns_servers 216.It Cm refresh_isns Op Fl I Ar id 217.It Cm login Oo Fl m Oc Oo Ar target-opts Oc Oo Ar auth-opts Oc Oo Fl P Ar portal-id Oc 218To be able to communicate with the iSCSI target, the initiator 219must login. 220This command allows this login to take place. 221The subsequent 222.Fl P Ar session 223argument provides the session which should be used to 224perform the login. 225On successful completion of this command, the 226session which has been created will be displayed, along with the connection 227number. 228For more context on the exact usage of this 229command, please see the example below. 230.It Cm logout Op Fl I Ar session-id 231.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 232.It Cm remove_connection Fl I Ar session-id Fl C Ar connection-id 233.It Cm inquiry Oo Fl l Ar lun Oc Oo Fl d Ar detail Oc Oo Fl p Ar pag Oc 234.It Cm read_capacity Op Fl I Ar session-id Op Fl l Ar lun 235.It Cm report_luns Op Fl I Ar session-id 236.It Cm test_unit_ready Op Fl I Ar session-id 237.It Cm add_initiator Fl a Ar interface-address Op Fl N Ar symbolic-name 238.It Cm remove_initiator Fl I Ar portal-id 239.It Cm list_initiators 240.It Cm list_sessions Op Fl c 241Once login to the target has taken place, a session will have been created. 242To list the session information, this command is used. 243The session number and target information for each of the targets are displayed. 244If the 245.Fl c 246flag is used, connection information is displayed as well. 247For more context on the exact usage of this 248command, please see the example below. 249.It Cm set_node_name Fl n Ar initiator-name Oo Fl A alias Oc Oo Fl i Ar isid Oc 250Set the initiator name. 251The default initiator name is 252iqn.1994-04.org.netbsd:iscsi.<hostname>:<hostid> . 253An 254.Ar alias 255can be specified as well as an 256.Ar isid 257.El 258.Sh EXAMPLES 259.Nm 260is intended to be used as follows: 261.Pp 262The initiator itself can be loaded as a kernel module, and works successfully 263on 5.0 (the host called "burner"), running against the 264.Nx 265target on a 5.99 host. 266.Pp 267.Bd -literal 268burner# modload iscsi 269burner# modstat iscsi 270NAME CLASS SOURCE REFS ADDRESS SIZE REQUIRES 271iscsi driver filesys 0 ffffffff813c6000 44208 - 272burner# iscsid 273iSCSI Daemon loaded 274burner# iscsictl add_send_target -a 172.16.135.133 275Added Send Target 1 276burner# iscsictl refresh_targets 277OK 278burner# iscsictl list_targets 279 1: iqn.1994-04.org.netbsd.iscsi-target:target0 280 2: 172.16.135.133:3260,1 281burner# iscsictl login -P 2 282Created Session 2, Connection 1 283burner# iscsictl list_sessions 284Session 2: Target iqn.1994-04.org.netbsd.iscsi-target:target0 285.\" how do we know that it was assigned sd0? 286burner# newfs /dev/rsd0a 287/dev/rsd0a: 100.0MB (204800 sectors) block size 8192, fragment size 1024 288 using 4 cylinder groups of 25.00MB, 3200 blks, 6144 inodes. 289super-block backups (for fsck -b #) at: 290 32, 51232, 102432, 153632, 291burner# mount /dev/sd0a /mnt 292burner# df 293Filesystem 1K-blocks Used Avail Capacity Mounted on 294/dev/wd0a 4066094 186994 3675795 4% / 295kernfs 1 1 0 100% /kern 296/dev/sd0a 99247 1 94283 0% /mnt 297burner# dmesg | egrep '(scsibus|sd0)' 298scsibus0 at bha2: 16 targets, 8 luns per target 299scsibus0: waiting 2 seconds for devices to settle... 300scsibus1 at iscsi0: 1 target, 16 luns per target 301sd0 at scsibus1 target 0 lun 0: <NetBSD, NetBSD iSCSI, 0> disk fixed 302sd0: fabricating a geometry 303sd0: 100 MB, 100 cyl, 64 head, 32 sec, 512 bytes/sect x 204800 sectors 304sd0: fabricating a geometry 305sd0: fabricating a geometry 306sd0: fabricating a geometry 307burner# 308.Ed 309.Pp 310and, on the target end of the iSCSI session: 311.Bd -literal 312Reading configuration from `/etc/iscsi/targets' 313target0:rw:0.0.0.0/0 314 extent0:/tmp/iscsi-target0:0:104857600 315DISK: 1 logical unit (204800 blocks, 512 bytes/block), type iscsi fs 316DISK: LUN 0: 100 MB disk storage for "target0" 317TARGET: iSCSI Qualified Name (IQN) is iqn.1994-04.org.netbsd.iscsi-target 318> 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 319< 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 320> 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 321.Ed 322.Sh SEE ALSO 323.Xr iscsid 8 324.Sh HISTORY 325The 326.Nm 327utility appeared in 328.Nx 6.0 . 329.Sh AUTHORS 330.An Alistair Crooks Aq Mt agc@NetBSD.org 331wrote this manual page. 332The 333.Nm 334utility was contributed by Wasabi Systems, Inc. 335