sbin/iscontrol/iscsi.conf.5

   1 .\" Copyright (c) 2007-2008 Daniel Braniss <danny@cs.huji.ac.il>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/sbin/iscontrol/iscsi.conf.5,v 1.3 2008/11/25 07:17:11 scottl Exp $
  26 .\"
  27 .Dd August 24, 2009
  28 .Os
  29 .Dt ISCSI.CONF 5
  30 .Sh NAME
  31 .Nm iscsi.conf
  32 .Nd key options to be negotiated in an iSCSI session
  33 .Sh DESCRIPTION
  34 The file
  35 .Nm ,
  36 is read by the
  37 .Xr iscontrol 8
  38 program.
  39 It contains declarations and parameter/key-options.
  40 The syntax is very simple,
  41 .D1 Li variable = value;
  42 and they can be grouped via a
  43 .Em block
  44 declaration:
  45 .Bf Li
  46 .Bd -literal
  47         # this is a comment
  48         target_1 { # nickname
  49            variable = value;
  50            ...
  51         } # this must be on a line by itself.
  52 .Ed
  53 .Ef
  54 .Pp
  55 The following are specified in the iSCSI RFC 3720,
  56 for a full description see sections 11/12 of the RFC.
  57 .Bl -tag -width MaxConnections
  58 .It Cm AuthMethod
  59 currently only supported authentication method is CHAP, with
  60 digest either MD5 or SHA.
  61 Default is none.
  62 .It Cm HeaderDigest
  63 a
  64 .Em digest
  65 is calculated on the header of all iSCSI PDUs, and
  66 checked.
  67 Only CRC32C is implemented.
  68 Default is none.
  69 .It Cm DataDigest
  70 same as for HeaderDigest, but on the data part of the iSCSI PDU.
  71 .It Cm MaxConnections
  72 is the number of simultaneous connections per session,
  73 currently only 1.
  74 .It Cm TargetName
  75 is the name by which the target is known, not to be confused with
  76 target address, either obtained via the target administrator, or
  77 from a
  78 .Em discovery session .
  79 .It Cm InitiatorName
  80 if not specified, defaults to
  81 .Sy iqn.2005-01.il.ac.huji.cs:
  82 .Aq hostname .
  83 .It Cm TargetAlias / InitiatorAlias
  84 not implemented.
  85 .It Cm TargetAddress
  86 is of the form
  87 .Sy domainname[:port][,portal-group-tag]
  88 to quote the RFC:
  89 .Bd -ragged -compact
  90 The domainname can be specified as either a DNS host name, a
  91 dotted-decimal IPv4 address, or a bracketed IPv6 address as specified in
  92 .Sy RFC 2732 .
  93 .Ed
  94 Note: portal-group-tag is unused at the moment.
  95 .It Cm TargetPortalGroupTag
  96 .Em not implemented yet.
  97 .It Cm InitialR2T
  98 .Em not implemented yet.
  99 .It Cm ImmediateData
 100 .Em not implemented yet.
 101 .It Cm MaxRecvDataSegmentLength
 102 the maximum data segment length in
 103 bytes it can receive in an iSCSI PDU, default is 8192.
 104 .It Cm MaxBurstLength
 105 .Em not implemented yet.
 106 .It Cm FirstBurstLength
 107 .Em not implemented yet.
 108 .It Cm DefaultTime2Wait
 109 .Em not implemented yet.
 110 .It Cm DefaultTime2Retain
 111 .Em not implemented yet.
 112 .It Cm MaxOutstandingR2T
 113 is used to calculate/negotiate the
 114 .Em tag opening ,
 115 can be overriden by the
 116 .Sy tag
 117 option.
 118 .It Cm DataPDUInOrder
 119 .Em not implemented yet.
 120 .It Cm DataSequenceInOrder
 121 .Em not implemented yet.
 122 .It Cm ErrorRecoveryLevel
 123 Only level 0 is supported.
 124 .It Cm SessionType
 125 either Discovery or Normal, default is Normal, see the
 126 .Fl d
 127 flag of
 128 .Cm iscontrol .
 129 .El
 130 .sp
 131 The following are not specified in the
 132 .Sy RFC 3720
 133 .Bl -tag -width sockbufsize
 134 .It Cm port
 135 The iSCSI port used by the iSCSI protocol, defaults to 3260.
 136 .It Cm tags
 137 Sets the
 138 .Em tag opening
 139 to the value specified.
 140 .It Cm maxluns
 141 overrides the compiled value of
 142 .Sy luns ,
 143 see
 144 .Xr iscsi_initiator 4 .
 145 This value can only be reduced.
 146 .It Cm sockbufsize
 147 sets the receiver and transmitter socket buffer size to
 148 .Em size ,
 149 in kilobytes.
 150 The default is 128.
 151 .El
 152 .sp
 153 If
 154 .Em AuthMethod
 155 is set to
 156 .Cm CHAP ,
 157 then the following must also be set:
 158 .Bl -tag -width chapSecret
 159 .It Cm chapSecret
 160 this
 161 .Em shared-secret .
 162 Can be either an ASCII string (e.g. hello world), a hex string (e.g
 163 0xababcd0987654321...), or base64 string (eg 0b...)
 164 .It Cm chapIName
 165 the chap-name, defaults to
 166 .Em hostname .
 167 .It Cm chapDigest
 168 can be MD5 or SHA1.
 169 .It Cm tgtChapSecret/tgtChapName
 170 same as the none
 171 .Em tgt
 172 counterpart, but to authenticate the target.
 173 .El
 174 .Sh FILES
 175 .Pa /etc/iscsi.conf
 176 .Sh EXAMPLES
 177 .Bd -literal
 178 #
 179 # Globals
 180 #
 181 port = 3260
 182 #
 183 myiscsi { # nickname
 184    targetaddress        = iscsi1
 185    targetname           = iqn.1900.com.com:sn.123456
 186 }
 187 chaptest {
 188    targetaddress= 10.0.0.1;
 189    targetname   = iqn.1900.com.com:sn.123456
 190    initiatorname= iqn.2005-01.il.ac.huji.cs:nobody
 191    authmethod = CHAP; chapDigest = SHA1;
 192    chapsecret = 0x3713c3336d9a224c2791c873d3d2b174
 193    tags         = 256
 194 }
 195 .Ed
 196 .Sh ERRORS
 197 The parsing is very primitive, so do not expect - at the moment - any
 198 error messages.
 199 .Sh SEE ALSO
 200 .Xr iscsi_initiator 4 ,
 201 .Xr iscontrol 8
 202 .Sh STANDARDS
 203 ISCSI RFC 3720
 204 .\"Sh HISTORY
 205 .\"Sh AUTHORS
 206 .Sh BUGS
 207 Some options have not been implemented, either they were found
 208 to be unnecessary, or not understood, this can change in the future.
 209 .br
 210 The tags opening value is difficult to calculate, use wisely.