usr.bin/iscsictl/iscsictl.8

   1 .\" Copyright (c) 2012 The FreeBSD Foundation
   2 .\"
   3 .\" This software was developed by Edward Tomasz Napierala under sponsorship
   4 .\" from the FreeBSD Foundation.
   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 AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd December 27, 2018
  30 .Dt ISCSICTL 8
  31 .Os
  32 .Sh NAME
  33 .Nm iscsictl
  34 .Nd iSCSI initiator management utility
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Fl A
  38 .Fl p Ar portal Fl t Ar target
  39 .Op Fl u Ar user Fl s Ar secret
  40 .Op Fl w Ar timeout
  41 .Op Fl r
  42 .Op Fl e Cm on Ns | Ns Cm off
  43 .Nm
  44 .Fl A
  45 .Fl d Ar discovery-host
  46 .Op Fl u Ar user Fl s Ar secret
  47 .Op Fl r
  48 .Op Fl e Cm on Ns | Ns Cm off
  49 .Nm
  50 .Fl A
  51 .Fl a Op Fl c Ar path
  52 .Nm
  53 .Fl A
  54 .Fl n Ar nickname Op Fl c Ar path
  55 .Nm
  56 .Fl M
  57 .Fl i Ar session-id
  58 .Op Fl p Ar portal
  59 .Op Fl t Ar target
  60 .Op Fl u Ar user
  61 .Op Fl s Ar secret
  62 .Op Fl e Cm on Ns | Ns Cm off
  63 .Nm
  64 .Fl M
  65 .Fl i Ar session-id
  66 .Op Fl n Ar nickname Op Fl c Ar path
  67 .Nm
  68 .Fl R
  69 .Op Fl p Ar portal
  70 .Op Fl t Ar target
  71 .Nm
  72 .Fl R
  73 .Fl a
  74 .Nm
  75 .Fl R
  76 .Fl n Ar nickname Op Fl c Ar path
  77 .Nm
  78 .Fl L
  79 .Op Fl v
  80 .Op Fl w Ar timeout
  81 .Sh DESCRIPTION
  82 The
  83 .Nm
  84 utility is used to configure the iSCSI initiator.
  85 .Pp
  86 The following options are available:
  87 .Bl -tag -width "-d discovery-host"
  88 .It Fl -libxo
  89 Generate output via
  90 .Xr libxo 3
  91 in a selection of different human and machine readable formats.
  92 See
  93 .Xr xo_parse_args 3
  94 for details on command line arguments.
  95 .It Fl A
  96 Add session.
  97 .It Fl M
  98 Modify session.
  99 .It Fl R
 100 Remove session.
 101 .It Fl L
 102 List sessions.
 103 .It Fl a
 104 When adding, add all sessions defined in the configuration file.
 105 When removing, remove all currently established sessions.
 106 .It Fl c Ar path
 107 Path to the configuration file.
 108 The default is
 109 .Pa /etc/iscsi.conf .
 110 .It Fl d Ar discovery-host
 111 Target host name or address used for SendTargets discovery.
 112 When used, it will add a temporary discovery session.
 113 After discovery is done, sessions will be added for each discovered target,
 114 and the temporary discovery session will be removed.
 115 .It Fl e Cm on Ns | Ns Cm off
 116 Enable or disable the session.
 117 This is ignored for discovery sessions, but gets passed down to normal
 118 sessions they add.
 119 .It Fl i Ar session-id
 120 Session ID, as displayed by
 121 .Nm
 122 .Fl v .
 123 .It Fl n Ar nickname
 124 The
 125 .Ar nickname
 126 of a session defined in the configuration file.
 127 .It Fl p Ar portal
 128 Target portal \(em host name or address \(em for statically defined targets.
 129 .It Fl r
 130 Use iSER (iSCSI over RDMA) instead of plain iSCSI over TCP/IP.
 131 .It Fl s Ar secret
 132 CHAP secret.
 133 .It Fl t Ar target
 134 Target name.
 135 .It Fl u Ar user
 136 CHAP login.
 137 .It Fl v
 138 Verbose mode.
 139 .It Fl w Ar timeout
 140 Instead of returning immediately, wait up to
 141 .Ar timeout
 142 seconds until all configured sessions are successfully established.
 143 .El
 144 .Pp
 145 Certain parameters are necessary when adding a session.
 146 One can specify these either via command line (using the
 147 .Fl t ,
 148 .Fl p ,
 149 .Fl u ,
 150 and
 151 .Fl s
 152 options), or configuration file (using the
 153 .Fl a
 154 or
 155 .Fl n
 156 options).
 157 Some functionality - for example mutual CHAP - is available only
 158 via configuration file.
 159 .Pp
 160 Since connecting to the target is performed in background, non-zero
 161 exit status does not mean that the session was successfully established.
 162 Use either
 163 .Nm Fl L
 164 to check the connection status, or the
 165 .Fl w
 166 flag to wait for session establishment.
 167 .Pp
 168 Note that in order for the iSCSI initiator to be able to connect to a target,
 169 the
 170 .Xr iscsid 8
 171 daemon must be running.
 172 .Pp
 173 Also note that
 174 .Fx
 175 currently supports two different initiators: the old one,
 176 .Xr iscsi_initiator 4 ,
 177 with its control utility
 178 .Xr iscontrol 8 ,
 179 and the new one,
 180 .Xr iscsi 4 ,
 181 with
 182 .Nm
 183 and
 184 .Xr iscsid 8 .
 185 The only thing the two have in common is the configuration file,
 186 .Xr iscsi.conf 5 .
 187 .Sh FILES
 188 .Bl -tag -width ".Pa /etc/iscsi.conf" -compact
 189 .It Pa /etc/iscsi.conf
 190 iSCSI initiator configuration file.
 191 .El
 192 .Sh EXIT STATUS
 193 The
 194 .Nm
 195 utility exits 0 on success, and >0 if an error occurs.
 196 .Sh EXAMPLES
 197 Attach to target iqn.2012-06.com.example:target0, served by 192.168.1.1:
 198 .Dl Nm Fl A Fl t Ar iqn.2012-06.com.example:target0 Fl p Ar 192.168.1.1
 199 .Pp
 200 Perform discovery on 192.168.1.1, and add disabled sessions for each
 201 discovered target; use
 202 .Nm -M -e on
 203 to connect them:
 204 .Dl Nm Fl A Fl d Ar 192.168.1.1 Fl e Ar off
 205 .Pp
 206 Disconnect all iSCSI sessions:
 207 .Dl Nm Fl Ra
 208 .Sh SEE ALSO
 209 .Xr libxo 3 ,
 210 .Xr xo_parse_args 3 ,
 211 .Xr iscsi 4 ,
 212 .Xr iscsi.conf 5 ,
 213 .Xr iscsid 8
 214 .Sh HISTORY
 215 The
 216 .Nm
 217 command appeared in
 218 .Fx 10.0 .
 219 .Sh AUTHORS
 220 The
 221 .Nm
 222 utility was developed by
 223 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
 224 under sponsorship from the FreeBSD Foundation.