Index: head/usr.bin/iscsictl/iscsi.conf.5 =================================================================== --- head/usr.bin/iscsictl/iscsi.conf.5 (revision 280981) +++ head/usr.bin/iscsictl/iscsi.conf.5 (revision 280982) @@ -1,190 +1,156 @@ .\" Copyright (c) 2007-2010 Daniel Braniss .\" 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 4, 2015 +.Dd April 2, 2015 .Dt ISCSI.CONF 5 .Os .Sh NAME .Nm iscsi.conf .Nd iSCSI initiator configuration file .Sh DESCRIPTION -The file -.Nm , -is used by the +The +.Nm +configuration file is used by the .Xr iscsictl 8 and .Xr iscontrol 8 utilities. -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: +The general syntax is: .Bf Li .Bd -literal # this is a comment - target_1 { # nickname + nickname_1 { variable = value; ... - } # this must be on a line by itself. + } + nickname_2 { + variable = value; + ... + } + ... .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. +Sets the authentication type. +Type can be either +.Qq Ar None , +or +.Qq Ar CHAP . +Default is +.Qq Ar None . +When set to +.Cm CHAP , +both +.Cm chapIName +and +.Cm chapSecret +must be defined. +.It Cm chapIName +Login for CHAP authentication. +.It Cm chapSecret +Secret for CHAP authentication. +.It Cm tgtChapName +Target login for Mutual CHAP authentication. +.It Cm tgtChapSecret +Target secret for Mutual CHAP authentication. .It Cm HeaderDigest -a -.Em digest -is calculated on the header of all iSCSI PDUs, and -checked. -Only CRC32C is implemented. -Default is none. +Sets the header digest; a checksum calculated over the header of iSCSI +PDUs, and verified on receive. +Digest can be either +.Qq Ar None , +or +.Qq Ar CRC32C . +Default is +.Qq Ar None . .It Cm DataDigest -same as for HeaderDigest, but on the data part of the iSCSI PDU. -(not yet tested) +Sets the data digest; a checksum calculated over the Data Section of iSCSI +PDUs, and verified on receive. +Digest can be either +.Qq Ar None , +or +.Qq Ar CRC32C . +Default is +.Qq Ar None . .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 . +Sets the target name. +Not required for discovery sessions. .It Cm InitiatorName -if not specified, defaults to -.Sy iqn.2005-01.il.ac.huji.cs: -.Aq hostname . +Sets the initiator name. +By default, the name is concatenation of +.Qq Ar iqn.1994-09.org.freebsd: +with the hostname. .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. -.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 MaxOutstandingR2T -is used to calculate/negotiate the -.Em tag opening , -can be overridden by the -.Sy tag -option. +Sets the target address and port, in +.Sy address[:port] +format. +The +.Sy address +can be either an IP address, or hostname. +The optional port defaults to 3260. .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 offload +Sets the session type. +Type can be either +.Qq Ar Discovery , +or +.Qq Ar Normal . +Default is +.Qq Ar Normal . +For normal sessions, the +.Sy TargetName +must be defined. +Discovery sessions result in the initiator connecting to all the targets +returned by SendTargets iSCSI discovery with the defined +.Sy TargetAddress . +.It Cm Offload Name of selected iSCSI hardware offload driver. -.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. +Default is +.Qq Ar None . .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 tgtChapName/tgtChapSecret -name and secret used for mutual CHAP; by default, mutual CHAP -is not used. -.El .Sh FILES .Bl -tag -width indent .It Pa /etc/iscsi.conf .El .Sh EXAMPLES .Bd -literal -# -# Globals -# -port = 3260 -# myiscsi { # nickname - targetaddress = iscsi1 - targetname = iqn.1900.com.com:sn.123456 + 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 + targetaddress = 10.0.0.1; + targetname = iqn.1900.com.com:sn.123456; + initiatorname = iqn.2005-01.il.ac.huji.cs:nobody; + authmethod = CHAP; + chapiname = iqn.2005-01.il.ac.huji.cs:nobody; + chapsecret = "secretsecret"; } .Ed .Sh SEE ALSO -.Xr iscsi_initiator 4 , .Xr iscontrol 8 , .Xr iscsictl 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.