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: src/sbin/iscontrol/iscsi.conf.5,v 1.3 2008/11/25 07:17:11 scottl Exp $ 26.\" 27.Dd August 24, 2009 28.Dt ISCSI.CONF 5 29.Os 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 78.Em discovery session . 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 91dotted-decimal IPv4 address, or a bracketed IPv6 address as specified in 92.Sy RFC 2732 . 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 overridden 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 148.Em size , 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 SEE ALSO 197.Xr iscsi_initiator 4 , 198.Xr iscontrol 8 199.Sh STANDARDS 200ISCSI RFC 3720 201.\"Sh HISTORY 202.\"Sh AUTHORS 203.Sh BUGS 204Some options have not been implemented, either they were found 205to be unnecessary, or not understood, this can change in the future. 206.Pp 207The tags opening value is difficult to calculate, use wisely. 208.Pp 209The parsing is very primitive, so do not expect - at the moment - any 210error messages. 211