usr.bin/iscsictl/iscsi.conf.5

   1 .\" Copyright (c) 2007-2010 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 February 25, 2022
  28 .Dt ISCSI.CONF 5
  29 .Os
  30 .Sh NAME
  31 .Nm iscsi.conf
  32 .Nd iSCSI initiator configuration file
  33 .Sh DESCRIPTION
  34 The
  35 .Nm
  36 configuration file is used by the
  37 .Xr iscsictl 8
  38 utility.
  39 The general syntax is:
  40 .Bf Li
  41 .Bd -literal
  42         # this is a comment
  43         nickname_1 {
  44            variable = value;
  45            ...
  46         }
  47         nickname_2 {
  48            variable = value;
  49            ...
  50         }
  51         ...
  52 .Ed
  53 .Ef
  54 .Bl -tag -width MaxConnections
  55 .It Cm AuthMethod
  56 Sets the authentication type.
  57 Type can be either
  58 .Qq Ar None ,
  59 or
  60 .Qq Ar CHAP .
  61 Default is
  62 .Qq Ar None .
  63 When set to
  64 .Cm CHAP ,
  65 both
  66 .Cm chapIName
  67 and
  68 .Cm chapSecret
  69 must be defined.
  70 .It Cm chapIName
  71 Login for CHAP authentication.
  72 .It Cm chapSecret
  73 Secret for CHAP authentication.
  74 .It Cm tgtChapName
  75 Target login for Mutual CHAP authentication.
  76 .It Cm tgtChapSecret
  77 Target secret for Mutual CHAP authentication.
  78 .It Cm HeaderDigest
  79 Sets the header digest; a checksum calculated over the header of iSCSI
  80 PDUs, and verified on receive.
  81 Digest can be either
  82 .Qq Ar None ,
  83 or
  84 .Qq Ar CRC32C .
  85 Default is
  86 .Qq Ar None .
  87 .It Cm DataDigest
  88 Sets the data digest; a checksum calculated over the Data Section of iSCSI
  89 PDUs, and verified on receive.
  90 Digest can be either
  91 .Qq Ar None ,
  92 or
  93 .Qq Ar CRC32C .
  94 Default is
  95 .Qq Ar None .
  96 .It Cm InitiatorName
  97 Sets the initiator name.
  98 By default, the name is concatenation of
  99 .Qq Ar iqn.1994-09.org.freebsd:
 100 with the hostname.
 101 .It Cm TargetName
 102 Sets the target name.
 103 Not required for discovery sessions.
 104 .It Cm TargetAddress
 105 Sets the target address and port, in
 106 .Sy address[:port]
 107 format.
 108 The
 109 .Sy address
 110 can be either an IP address, or hostname.
 111 The optional port defaults to 3260.
 112 .It Cm SessionType
 113 Sets the session type.
 114 Type can be either
 115 .Qq Ar Discovery ,
 116 or
 117 .Qq Ar Normal .
 118 Default is
 119 .Qq Ar Normal .
 120 For normal sessions, the
 121 .Sy TargetName
 122 must be defined.
 123 Discovery sessions result in the initiator connecting to all the targets
 124 returned by SendTargets iSCSI discovery with the defined
 125 .Sy TargetAddress .
 126 .It Cm Enable
 127 Enable or disable the session.
 128 State can be either
 129 .Qq Ar On ,
 130 or
 131 .Qq Ar Off .
 132 Default is
 133 .Qq Ar On .
 134 .It Cm Offload
 135 Name of selected iSCSI hardware offload driver.
 136 Default is
 137 .Qq Ar None .
 138 .It Cm Protocol
 139 Name of selected protocol.
 140 It can be either
 141 .Qq Ar iSER ,
 142 for iSCSI over RDMA, or
 143 .Qq Ar iSCSI .
 144 Default is
 145 .Qq Ar iSCSI .
 146 .It Cm dscp
 147 The DiffServ Codepoint used for sending data.
 148 The DSCP can be set to numeric, or hexadecimal values directly,
 149 as well as the well-defined
 150 .Qq Ar cs<n>
 151 and
 152 .Qq Ar af<xx>
 153 codepoints.
 154 Default is no specified dscp codepoint, which means the default
 155 of the outgoing interface is used.
 156 .It Cm pcp
 157 The 802.1Q Priority CodePoint used for sending packets.
 158 The PCP can be set to a value in the range between
 159 .Qq Ar 0
 160 to
 161 .Qq Ar 7 .
 162 When omitted, the default for the outgoing interface is used.
 163 .It Cm PingTimeout
 164 Specify the time in seconds to wait between pings (SCSI NOP), and
 165 for a ping response before declaring the session as dead and
 166 attempting a re-establishment.
 167 If this entry is not present in the conf file, the default value
 168 configured using
 169 .Qq Ar kern.iscsi.ping_timeout
 170 (default at
 171 .Qq Ar 5
 172 seconds) is taken by the driver.
 173 If present, the PingTimeout can be set to any positive value
 174 starting with
 175 .Qq Ar 1 .
 176 .It Cm LoginTimeout
 177 Specify the time in seconds to wait for a login PDU to be sent or
 178 received after trying to establish a new session.
 179 When no login PDU is received within this time, the login on a
 180 particular connection fails and a new reconnection attempt is made.
 181 If this entry is not present in the conf file, the default value of
 182 .Qq Ar 60
 183 seconds is used, as configured by
 184 .Qq Ar kern.iscsi.login_timeout .
 185 The LoginTimeout can be set to any positive value starting with
 186 .Qq Ar 1 .
 187 .El
 188 .Sh FILES
 189 .Bl -tag -width indent
 190 .It Pa /etc/iscsi.conf
 191 .El
 192 .Sh EXAMPLES
 193 .Bd -literal
 194 myiscsi { # nickname
 195    targetaddress = iscsi1
 196    targetname    = iqn.1900.com.com:sn.123456
 197 }
 198
 199 myiscsi6 { # nickname
 200    targetaddress = [2001:db8::de:ef]:3260
 201    targetname    = iqn.1900.com.com:sn.123456
 202 }
 203
 204 chaptest {
 205    targetaddress = 10.0.0.1;
 206    targetname    = iqn.1900.com.com:sn.123456;
 207    initiatorname = iqn.2005-01.il.ac.huji.cs:nobody;
 208    authmethod    = CHAP;
 209    chapiname     = iqn.2005-01.il.ac.huji.cs:nobody;
 210    chapsecret    = "secretsecret";
 211 }
 212 .Ed
 213 .Sh SEE ALSO
 214 .Xr iscsictl 8
 215 .\"Sh HISTORY
 216 .\"Sh AUTHORS