Some small fixes in the iscsi manual pages.
[dragonfly.git] / sbin / iscontrol / iscsi.conf.5
CommitLineData
e25c779e
MD
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.\"
ef8e7823 25.\" $FreeBSD: src/sbin/iscontrol/iscsi.conf.5,v 1.3 2008/11/25 07:17:11 scottl Exp $
e25c779e 26.\"
ef8e7823 27.Dd August 24, 2009
e25c779e
MD
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
34The file
35.Nm ,
36is read by the
37.Xr iscontrol 8
38program.
39It contains declarations and parameter/key-options.
40The syntax is very simple,
41.D1 Li variable = value;
42and they can be grouped via a
43.Em block
44declaration:
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
55The following are specified in the iSCSI RFC 3720,
56for a full description see sections 11/12 of the RFC.
57.Bl -tag -width MaxConnections
58.It Cm AuthMethod
59currently only supported authentication method is CHAP, with
60digest either MD5 or SHA.
61Default is none.
62.It Cm HeaderDigest
63a
64.Em digest
65is calculated on the header of all iSCSI PDUs, and
66checked.
67Only CRC32C is implemented.
68Default is none.
69.It Cm DataDigest
70same as for HeaderDigest, but on the data part of the iSCSI PDU.
71.It Cm MaxConnections
72is the number of simultaneous connections per session,
73currently only 1.
74.It Cm TargetName
75is the name by which the target is known, not to be confused with
76target address, either obtained via the target administrator, or
77from a
ef8e7823 78.Em discovery session .
e25c779e
MD
79.It Cm InitiatorName
80if not specified, defaults to
81.Sy iqn.2005-01.il.ac.huji.cs:
82.Aq hostname .
83.It Cm TargetAlias / InitiatorAlias
84not implemented.
85.It Cm TargetAddress
86is of the form
87.Sy domainname[:port][,portal-group-tag]
88to quote the RFC:
89.Bd -ragged -compact
90The domainname can be specified as either a DNS host name, a
ef8e7823
SW
91dotted-decimal IPv4 address, or a bracketed IPv6 address as specified in
92.Sy RFC 2732 .
e25c779e
MD
93.Ed
94Note: 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
102the maximum data segment length in
103bytes 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
113is used to calculate/negotiate the
114.Em tag opening ,
115can be overriden by the
116.Sy tag
117option.
118.It Cm DataPDUInOrder
119.Em not implemented yet.
120.It Cm DataSequenceInOrder
121.Em not implemented yet.
122.It Cm ErrorRecoveryLevel
123Only level 0 is supported.
124.It Cm SessionType
125either Discovery or Normal, default is Normal, see the
126.Fl d
127flag of
128.Cm iscontrol .
129.El
130.sp
131The following are not specified in the
132.Sy RFC 3720
133.Bl -tag -width sockbufsize
134.It Cm port
135The iSCSI port used by the iSCSI protocol, defaults to 3260.
136.It Cm tags
137Sets the
138.Em tag opening
139to the value specified.
140.It Cm maxluns
141overrides the compiled value of
142.Sy luns ,
143see
144.Xr iscsi_initiator 4 .
145This value can only be reduced.
146.It Cm sockbufsize
147sets the receiver and transmitter socket buffer size to
ef8e7823 148.Em size ,
e25c779e
MD
149in kilobytes.
150The default is 128.
151.El
152.sp
153If
154.Em AuthMethod
155is set to
156.Cm CHAP ,
157then the following must also be set:
158.Bl -tag -width chapSecret
159.It Cm chapSecret
160this
161.Em shared-secret .
162Can be either an ASCII string (e.g. hello world), a hex string (e.g
1630xababcd0987654321...), or base64 string (eg 0b...)
164.It Cm chapIName
165the chap-name, defaults to
166.Em hostname .
167.It Cm chapDigest
168can be MD5 or SHA1.
169.It Cm tgtChapSecret/tgtChapName
170same as the none
171.Em tgt
172counterpart, 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#
181port = 3260
182#
183myiscsi { # nickname
184 targetaddress = iscsi1
185 targetname = iqn.1900.com.com:sn.123456
186}
187chaptest {
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
197The parsing is very primitive, so do not expect - at the moment - any
198error messages.
199.Sh SEE ALSO
200.Xr iscsi_initiator 4 ,
201.Xr iscontrol 8
202.Sh STANDARDS
203ISCSI RFC 3720
204.\"Sh HISTORY
205.\"Sh AUTHORS
206.Sh BUGS
207Some options have not been implemented, either they were found
1de3c21d 208to be unnecessary, or not understood, this can change in the future.
e25c779e
MD
209.br
210The tags opening value is difficult to calculate, use wisely.