b9998625f7e53e9e83d02ede973cb8671af2dc79
[dragonfly.git] / 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$
26 .\"
27 .Dd June 5, 2007
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
92 in [RFC2732].
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.