212 lines
5.6 KiB
Groff
212 lines
5.6 KiB
Groff
.\" Copyright (c) 2007-2010 Daniel Braniss <danny@cs.huji.ac.il>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 25, 2012
|
|
.Dt ISCSI.CONF 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm iscsi.conf
|
|
.Nd key options to be negotiated in an iSCSI session
|
|
.Sh DESCRIPTION
|
|
The file
|
|
.Nm ,
|
|
is read by the
|
|
.Xr iscontrol 8
|
|
program.
|
|
It contains declarations and parameter/key-options.
|
|
The syntax is very simple,
|
|
.D1 Li variable = value;
|
|
and they can be grouped via a
|
|
.Em block
|
|
declaration:
|
|
.Bf Li
|
|
.Bd -literal
|
|
# this is a comment
|
|
target_1 { # nickname
|
|
variable = value;
|
|
...
|
|
} # this must be on a line by itself.
|
|
.Ed
|
|
.Ef
|
|
.Pp
|
|
The following are specified in the iSCSI RFC 3720,
|
|
for a full description see sections 11/12 of the RFC.
|
|
.Bl -tag -width MaxConnections
|
|
.It Cm AuthMethod
|
|
currently only supported authentication method is CHAP, with
|
|
digest either MD5 or SHA.
|
|
Default is none.
|
|
.It Cm HeaderDigest
|
|
a
|
|
.Em digest
|
|
is calculated on the header of all iSCSI PDUs, and
|
|
checked.
|
|
Only CRC32C is implemented.
|
|
Default is none.
|
|
.It Cm DataDigest
|
|
same as for HeaderDigest, but on the data part of the iSCSI PDU.
|
|
(not yet tested)
|
|
.It Cm MaxConnections
|
|
is the number of simultaneous connections per session,
|
|
currently only 1.
|
|
.It Cm TargetName
|
|
is the name by which the target is known, not to be confused with
|
|
target address, either obtained via the target administrator, or
|
|
from a
|
|
.Em discovery session.
|
|
.It Cm InitiatorName
|
|
if not specified, defaults to
|
|
.Sy iqn.2005-01.il.ac.huji.cs:
|
|
.Aq hostname .
|
|
.It Cm TargetAlias / InitiatorAlias
|
|
not implemented.
|
|
.It Cm TargetAddress
|
|
is of the form
|
|
.Sy domainname[:port][,portal-group-tag]
|
|
to quote the RFC:
|
|
.Bd -ragged -compact
|
|
The domainname can be specified as either a DNS host name, a
|
|
dotted-decimal IPv4 address, or a bracketed IPv6 address as specified
|
|
in [RFC2732].
|
|
.Ed
|
|
Note: portal-group-tag is unused at the moment.
|
|
.It Cm TargetPortalGroupTag
|
|
.Em not implemented yet.
|
|
.It Cm InitialR2T
|
|
.Em not implemented yet.
|
|
.It Cm ImmediateData
|
|
.Em not implemented yet.
|
|
.It Cm MaxRecvDataSegmentLength
|
|
the maximum data segment length in
|
|
bytes it can receive in an iSCSI PDU, default is 8192.
|
|
.It Cm MaxBurstLength
|
|
.Em not implemented yet.
|
|
.It Cm FirstBurstLength
|
|
.Em not implemented yet.
|
|
.It Cm DefaultTime2Wait
|
|
.Em not implemented yet.
|
|
.It Cm DefaultTime2Retain
|
|
.Em not implemented yet.
|
|
.It Cm MaxOutstandingR2T
|
|
is used to calculate/negotiate the
|
|
.Em tag opening ,
|
|
can be overridden by the
|
|
.Sy tag
|
|
option.
|
|
.It Cm DataPDUInOrder
|
|
.Em not implemented yet.
|
|
.It Cm DataSequenceInOrder
|
|
.Em not implemented yet.
|
|
.It Cm ErrorRecoveryLevel
|
|
Only level 0 is supported.
|
|
.It Cm SessionType
|
|
either Discovery or Normal, default is Normal, see the
|
|
.Fl d
|
|
flag of
|
|
.Cm iscontrol .
|
|
.El
|
|
.sp
|
|
The following are not specified in the
|
|
.Sy RFC 3720
|
|
.Bl -tag -width sockbufsize
|
|
.It Cm port
|
|
The iSCSI port used by the iSCSI protocol, defaults to 3260.
|
|
.It Cm tags
|
|
Sets the
|
|
.Em tag opening
|
|
to the value specified.
|
|
.It Cm maxluns
|
|
overrides the compiled value of
|
|
.Sy luns ,
|
|
see
|
|
.Xr iscsi_initiator 4 .
|
|
This value can only be reduced.
|
|
.It Cm sockbufsize
|
|
sets the receiver and transmitter socket buffer size to
|
|
.Em size,
|
|
in kilobytes.
|
|
The default is 128.
|
|
.El
|
|
.sp
|
|
If
|
|
.Em AuthMethod
|
|
is set to
|
|
.Cm CHAP ,
|
|
then the following must also be set:
|
|
.Bl -tag -width chapSecret
|
|
.It Cm chapSecret
|
|
this
|
|
.Em shared-secret .
|
|
Can be either an ASCII string (e.g. hello world), a hex string (e.g
|
|
0xababcd0987654321...), or base64 string (eg 0b...)
|
|
.It Cm chapIName
|
|
the chap-name, defaults to
|
|
.Em hostname .
|
|
.It Cm chapDigest
|
|
can be MD5 or SHA1.
|
|
.It Cm tgtChapSecret/tgtChapName
|
|
same as the none
|
|
.Em tgt
|
|
counterpart, but to authenticate the target.
|
|
.El
|
|
.Sh FILES
|
|
.Pa /etc/iscsi.conf
|
|
.Sh EXAMPLES
|
|
.Bd -literal
|
|
#
|
|
# Globals
|
|
#
|
|
port = 3260
|
|
#
|
|
myiscsi { # nickname
|
|
targetaddress = iscsi1
|
|
targetname = iqn.1900.com.com:sn.123456
|
|
}
|
|
chaptest {
|
|
targetaddress= 10.0.0.1;
|
|
targetname = iqn.1900.com.com:sn.123456
|
|
initiatorname= iqn.2005-01.il.ac.huji.cs:nobody
|
|
authmethod = CHAP; chapDigest = SHA1;
|
|
chapsecret = 0x3713c3336d9a224c2791c873d3d2b174
|
|
tags = 256
|
|
}
|
|
.Ed
|
|
.Sh ERRORS
|
|
The parsing is very primitive, so do not expect - at the moment - any
|
|
error messages.
|
|
.Sh SEE ALSO
|
|
.Xr iscsi_initiator 4 ,
|
|
.Xr iscontrol 8
|
|
.Sh STANDARDS
|
|
ISCSI RFC 3720
|
|
.\"Sh HISTORY
|
|
.\"Sh AUTHORS
|
|
.Sh BUGS
|
|
Some options have not been implemented, either they were found
|
|
to be unnecessary, or not understood, this can change in the future.
|
|
.br
|
|
The tags opening value is difficult to calculate, use wisely.
|