usr.bin/iscsictl/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 February 4, 2015
  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 offload
 114 Name of selected iSCSI hardware offload driver.
 115 .It Cm port
 116 The iSCSI port used by the iSCSI protocol, defaults to 3260.
 117 .It Cm tags
 118 Sets the
 119 .Em tag opening
 120 to the value specified.
 121 .It Cm maxluns
 122 overrides the compiled value of
 123 .Sy luns ,
 124 see
 125 .Xr iscsi_initiator 4 .
 126 This value can only be reduced.
 127 .It Cm sockbufsize
 128 sets the receiver and transmitter socket buffer size to
 129 .Em size ,
 130 in kilobytes.
 131 The default is 128.
 132 .El
 133 .sp
 134 If
 135 .Em AuthMethod
 136 is set to
 137 .Cm CHAP ,
 138 then the following must also be set:
 139 .Bl -tag -width chapSecret
 140 .It Cm chapSecret
 141 this
 142 .Em shared-secret .
 143 Can be either an ASCII string (e.g. hello world), a hex string (e.g
 144 0xababcd0987654321...), or base64 string (eg 0b...)
 145 .It Cm chapIName
 146 the chap-name, defaults to
 147 .Em hostname .
 148 .It Cm chapDigest
 149 can be MD5 or SHA1.
 150 .It Cm tgtChapName/tgtChapSecret
 151 name and secret used for mutual CHAP; by default, mutual CHAP
 152 is not used.
 153 .El
 154 .Sh FILES
 155 .Bl -tag -width indent
 156 .It Pa /etc/iscsi.conf
 157 .El
 158 .Sh EXAMPLES
 159 .Bd -literal
 160 #
 161 # Globals
 162 #
 163 port = 3260
 164 #
 165 myiscsi { # nickname
 166    targetaddress        = iscsi1
 167    targetname           = iqn.1900.com.com:sn.123456
 168 }
 169 chaptest {
 170    targetaddress= 10.0.0.1;
 171    targetname   = iqn.1900.com.com:sn.123456
 172    initiatorname= iqn.2005-01.il.ac.huji.cs:nobody
 173    authmethod = CHAP; chapDigest = SHA1;
 174    chapsecret = 0x3713c3336d9a224c2791c873d3d2b174
 175    tags         = 256
 176 }
 177 .Ed
 178 .Sh SEE ALSO
 179 .Xr iscsi_initiator 4 ,
 180 .Xr iscontrol 8 ,
 181 .Xr iscsictl 8
 182 .Sh STANDARDS
 183 ISCSI RFC 3720
 184 .\"Sh HISTORY
 185 .\"Sh AUTHORS
 186 .Sh BUGS
 187 Some options have not been implemented, either they were found
 188 to be unnecessary, or not understood, this can change in the future.
 189 .br
 190 The tags opening value is difficult to calculate, use wisely.