sbin/iscontrol/iscsi.conf.5

   1 .\" Copyright (c) 2007-2010 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$
  26 .\"
  27 .Dd October 10, 2013
  28 .Dt ISCSI.CONF 5
  29 .Os
  30 .Sh NAME
  31 .Nm iscsi.conf
  32 .Nd iSCSI initiator configuration file
  33 .Sh DESCRIPTION
  34 The file
  35 .Nm ,
  36 is used by the
  37 .Xr iscsictl 8
  38 and
  39 .Xr iscontrol 8
  40 utilities.
  41 It contains declarations and parameter/key-options.
  42 The syntax is very simple,
  43 .D1 Li variable = value;
  44 and they can be grouped via a
  45 .Em block
  46 declaration:
  47 .Bf Li
  48 .Bd -literal
  49         # this is a comment
  50         target_1 { # nickname
  51            variable = value;
  52            ...
  53         } # this must be on a line by itself.
  54 .Ed
  55 .Ef
  56 .Pp
  57 The following are specified in the iSCSI RFC 3720,
  58 for a full description see sections 11/12 of the RFC.
  59 .Bl -tag -width MaxConnections
  60 .It Cm AuthMethod
  61 currently only supported authentication method is CHAP, with
  62 digest either MD5 or SHA.
  63 Default is none.
  64 .It Cm HeaderDigest
  65 a
  66 .Em digest
  67 is calculated on the header of all iSCSI PDUs, and
  68 checked.
  69 Only CRC32C is implemented.
  70 Default is none.
  71 .It Cm DataDigest
  72 same as for HeaderDigest, but on the data part of the iSCSI PDU.
  73 (not yet tested)
  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 TargetAddress
  84 is of the form
  85 .Sy domainname[:port][,portal-group-tag]
  86 to quote the RFC:
  87 .Bd -ragged -compact
  88 The domainname can be specified as either a DNS host name, a
  89 dotted-decimal IPv4 address, or a bracketed IPv6 address as specified
  90 in [RFC2732].
  91 .Ed
  92 Note: portal-group-tag is unused at the moment.
  93 .Em not implemented yet.
  94 .It Cm MaxRecvDataSegmentLength
  95 the maximum data segment length in
  96 bytes it can receive in an iSCSI PDU, default is 8192.
  97 .It Cm MaxOutstandingR2T
  98 is used to calculate/negotiate the
  99 .Em tag opening ,
 100 can be overridden by the
 101 .Sy tag
 102 option.
 103 .It Cm SessionType
 104 either Discovery or Normal, default is Normal, see the
 105 .Fl d
 106 flag of
 107 .Cm iscontrol .
 108 .El
 109 .sp
 110 The following are not specified in the
 111 .Sy RFC 3720
 112 .Bl -tag -width sockbufsize
 113 .It Cm port
 114 The iSCSI port used by the iSCSI protocol, defaults to 3260.
 115 .It Cm tags
 116 Sets the
 117 .Em tag opening
 118 to the value specified.
 119 .It Cm maxluns
 120 overrides the compiled value of
 121 .Sy luns ,
 122 see
 123 .Xr iscsi_initiator 4 .
 124 This value can only be reduced.
 125 .It Cm sockbufsize
 126 sets the receiver and transmitter socket buffer size to
 127 .Em size ,
 128 in kilobytes.
 129 The default is 128.
 130 .El
 131 .sp
 132 If
 133 .Em AuthMethod
 134 is set to
 135 .Cm CHAP ,
 136 then the following must also be set:
 137 .Bl -tag -width chapSecret
 138 .It Cm chapSecret
 139 this
 140 .Em shared-secret .
 141 Can be either an ASCII string (e.g. hello world), a hex string (e.g
 142 0xababcd0987654321...), or base64 string (eg 0b...)
 143 .It Cm chapIName
 144 the chap-name, defaults to
 145 .Em hostname .
 146 .It Cm chapDigest
 147 can be MD5 or SHA1.
 148 .It Cm tgtChapSecret/tgtChapName
 149 same as the none
 150 .Em tgt
 151 counterpart, but to authenticate the target.
 152 .El
 153 .Sh FILES
 154 .Bl -tag -width indent
 155 .It Pa /etc/iscsi.conf
 156 .El
 157 .Sh EXAMPLES
 158 .Bd -literal
 159 #
 160 # Globals
 161 #
 162 port = 3260
 163 #
 164 myiscsi { # nickname
 165    targetaddress        = iscsi1
 166    targetname           = iqn.1900.com.com:sn.123456
 167 }
 168 chaptest {
 169    targetaddress= 10.0.0.1;
 170    targetname   = iqn.1900.com.com:sn.123456
 171    initiatorname= iqn.2005-01.il.ac.huji.cs:nobody
 172    authmethod = CHAP; chapDigest = SHA1;
 173    chapsecret = 0x3713c3336d9a224c2791c873d3d2b174
 174    tags         = 256
 175 }
 176 .Ed
 177 .Sh SEE ALSO
 178 .Xr iscsi_initiator 4 ,
 179 .Xr iscsictl 8 ,
 180 .Xr iscontrol 8
 181 .Sh STANDARDS
 182 ISCSI RFC 3720
 183 .\"Sh HISTORY
 184 .\"Sh AUTHORS
 185 .Sh BUGS
 186 Some options have not been implemented, either they were found
 187 to be unnecessary, or not understood, this can change in the future.
 188 .br
 189 The tags opening value is difficult to calculate, use wisely.