usr.sbin/ctld/ctl.conf.5

   1 .\" Copyright (c) 2012 The FreeBSD Foundation
   2 .\" All rights reserved.
   3 .\"
   4 .\" This software was developed by Edward Tomasz Napierala under sponsorship
   5 .\" from the FreeBSD Foundation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd October 22, 2014
  31 .Dt CTL.CONF 5
  32 .Os
  33 .Sh NAME
  34 .Nm ctl.conf
  35 .Nd CAM Target Layer / iSCSI target daemon configuration file
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 configuration file is used by the
  40 .Xr ctld 8
  41 daemon.
  42 Lines starting with
  43 .Ql #
  44 are interpreted as comments.
  45 The general syntax of the
  46 .Nm
  47 file is:
  48 .Bd -literal -offset indent
  49 .No pidfile Ar path
  50
  51 .No auth-group Ar name No {
  52 .Dl chap Ar user Ar secret
  53 .Dl ...
  54 }
  55
  56 .No portal-group Ar name No {
  57 .Dl listen Ar address
  58 .\".Dl listen-iser Ar address
  59 .Dl discovery-auth-group Ar name
  60 .Dl ...
  61 }
  62
  63 .No target Ar name {
  64 .Dl auth-group Ar name
  65 .Dl portal-group Ar name
  66 .Dl lun Ar number No {
  67 .Dl     path Ar path
  68 .Dl }
  69 .Dl ...
  70 }
  71 .Ed
  72 .Ss Global Context
  73 .Bl -tag -width indent
  74 .It Ic auth-group Ar name
  75 Create an
  76 .Sy auth-group
  77 configuration context,
  78 defining a new auth-group,
  79 which can then be assigned to any number of targets.
  80 .It Ic debug Ar level
  81 The debug verbosity level.
  82 The default is 0.
  83 .It Ic maxproc Ar number
  84 The limit for concurrently running child processes handling
  85 incoming connections.
  86 The default is 30.
  87 A setting of 0 disables the limit.
  88 .It Ic pidfile Ar path
  89 The path to the pidfile.
  90 The default is
  91 .Pa /var/run/ctld.pid .
  92 .It Ic portal-group Ar name
  93 Create a
  94 .Sy portal-group
  95 configuration context,
  96 defining a new portal-group,
  97 which can then be assigned to any number of targets.
  98 .It Ic target Ar name
  99 Create a
 100 .Sy target
 101 configuration context, which can contain one or more
 102 .Sy lun
 103 contexts.
 104 .It Ic timeout Ar seconds
 105 The timeout for login sessions, after which the connection
 106 will be forcibly terminated.
 107 The default is 60.
 108 A setting of 0 disables the timeout.
 109 .El
 110 .Ss auth-group Context
 111 .Bl -tag -width indent
 112 .It Ic auth-type Ar type
 113 Sets the authentication type.
 114 Type can be either
 115 .Qq Ar none ,
 116 .Qq Ar deny ,
 117 .Qq Ar chap ,
 118 or
 119 .Qq Ar chap-mutual .
 120 In most cases it is not necessary to set the type using this clause;
 121 it is usually used to disable authentication for a given
 122 .Sy auth-group .
 123 .It Ic chap Ar user Ar secret
 124 A set of CHAP authentication credentials.
 125 Note that for any
 126 .Sy auth-group ,
 127 the configuration may only contain either
 128 .Sy chap
 129 or
 130 .Sy chap-mutual
 131 entries; it is an error to mix them.
 132 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 133 A set of mutual CHAP authentication credentials.
 134 Note that for any
 135 .Sy auth-group ,
 136 the configuration may only contain either
 137 .Sy chap
 138 or
 139 .Sy chap-mutual
 140 entries; it is an error to mix them.
 141 .It Ic initiator-name Ar initiator-name
 142 An iSCSI initiator name.
 143 Only initiators with a name matching one of the defined
 144 names will be allowed to connect.
 145 If not defined, there will be no restrictions based on initiator
 146 name.
 147 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 148 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 149 followed by a literal slash and a prefix length.
 150 Only initiators with an address matching one of the defined
 151 addresses will be allowed to connect.
 152 If not defined, there will be no restrictions based on initiator
 153 address.
 154 .El
 155 .Ss portal-group Context
 156 .Bl -tag -width indent
 157 .It Ic discovery-auth-group Ar name
 158 Assign a previously defined authentication group to the portal group,
 159 to be used for target discovery.
 160 By default, portal groups are assigned predefined
 161 .Sy auth-group
 162 .Qq Ar default ,
 163 which denies discovery.
 164 Another predefined
 165 .Sy auth-group ,
 166 .Qq Ar no-authentication ,
 167 may be used
 168 to permit discovery without authentication.
 169 .It Ic listen Ar address
 170 An IPv4 or IPv6 address and port to listen on for incoming connections.
 171 .\".It Ic listen-iser Ar address
 172 .\"An IPv4 or IPv6 address and port to listen on for incoming connections
 173 .\"using iSER (iSCSI over RDMA) protocol.
 174 .El
 175 .Ss target Context
 176 .Bl -tag -width indent
 177 .It Ic alias Ar text
 178 Assign a human-readable description to the target.
 179 There is no default.
 180 .It Ic auth-group Ar name
 181 Assign a previously defined authentication group to the target.
 182 By default, targets that do not specify their own auth settings,
 183 using clauses such as
 184 .Sy chap
 185 or
 186 .Sy initiator-name ,
 187 are assigned
 188 predefined
 189 .Sy auth-group
 190 .Qq Ar default ,
 191 which denies all access.
 192 Another predefined
 193 .Sy auth-group ,
 194 .Qq Ar no-authentication ,
 195 may be used to permit access
 196 without authentication.
 197 Note that targets must only use one of
 198 .Sy auth-group , chap , No or Sy chap-mutual ;
 199 it is a configuration error to mix multiple types in one target.
 200 .It Ic auth-type Ar type
 201 Sets the authentication type.
 202 Type can be either
 203 .Qq Ar none ,
 204 .Qq Ar deny ,
 205 .Qq Ar chap ,
 206 or
 207 .Qq Ar chap-mutual .
 208 In most cases it is not necessary to set the type using this clause;
 209 it is usually used to disable authentication for a given
 210 .Sy target .
 211 This clause is mutually exclusive with
 212 .Sy auth-group ;
 213 one cannot use
 214 both in a single target.
 215 .It Ic chap Ar user Ar secret
 216 A set of CHAP authentication credentials.
 217 Note that targets must only use one of
 218 .Sy auth-group , chap , No or Sy chap-mutual ;
 219 it is a configuration error to mix multiple types in one target.
 220 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 221 A set of mutual CHAP authentication credentials.
 222 Note that targets must only use one of
 223 .Sy auth-group , chap , No or Sy chap-mutual ;
 224 it is a configuration error to mix multiple types in one target.
 225 .It Ic initiator-name Ar initiator-name
 226 An iSCSI initiator name.
 227 Only initiators with a name matching one of the defined
 228 names will be allowed to connect.
 229 If not defined, there will be no restrictions based on initiator
 230 name.
 231 This clause is mutually exclusive with
 232 .Sy auth-group ;
 233 one cannot use
 234 both in a single target.
 235 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 236 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 237 followed by a literal slash and a prefix length.
 238 Only initiators with an address matching one of the defined
 239 addresses will be allowed to connect.
 240 If not defined, there will be no restrictions based on initiator
 241 address.
 242 This clause is mutually exclusive with
 243 .Sy auth-group ;
 244 one cannot use
 245 both in a single target.
 246 .It Ic portal-group Ar name
 247 Assign a previously defined portal group to the target.
 248 The default portal group is
 249 .Qq Ar default ,
 250 which makes the target available
 251 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
 252 .It Ic lun Ar number
 253 Create a
 254 .Sy lun
 255 configuration context, defining a LUN exported by the parent target.
 256 .El
 257 .Ss lun Context
 258 .Bl -tag -width indent
 259 .It Ic backend Ar block No | Ar ramdisk
 260 The CTL backend to use for a given LUN.
 261 Valid choices are
 262 .Qq Ar block
 263 and
 264 .Qq Ar ramdisk ;
 265 block is used for LUNs backed
 266 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
 267 testing.
 268 The default backend is block.
 269 .It Ic blocksize Ar size
 270 The blocksize visible to the initiator.
 271 The default blocksize is 512.
 272 .It Ic device-id Ar string
 273 The SCSI Device Identification string presented to the initiator.
 274 .It Ic option Ar name Ar value
 275 The CTL-specific options passed to the kernel.
 276 All CTL-specific options are documented in the
 277 .Sx OPTIONS
 278 section of
 279 .Xr ctladm 8 .
 280 .It Ic path Ar path
 281 The path to the file or device node used to back the LUN.
 282 .It Ic serial Ar string
 283 The SCSI serial number presented to the initiator.
 284 .It Ic size Ar size
 285 The LUN size, in bytes.
 286 .El
 287 .Sh FILES
 288 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
 289 .It Pa /etc/ctl.conf
 290 The default location of the
 291 .Xr ctld 8
 292 configuration file.
 293 .El
 294 .Sh EXAMPLES
 295 .Bd -literal
 296 pidfile /var/run/ctld.pid
 297
 298 auth-group ag0 {
 299         chap-mutual "user" "secret" "mutualuser" "mutualsecret"
 300         chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
 301         initiator-portal 192.168.1.1/16
 302 }
 303
 304 auth-group ag1 {
 305         auth-type none
 306         initiator-name "iqn.2012-06.com.example:initiatorhost1"
 307         initiator-name "iqn.2012-06.com.example:initiatorhost2"
 308         initiator-portal 192.168.1.1/24
 309         initiator-portal [2001:db8::de:ef]
 310 }
 311
 312 portal-group pg0 {
 313         discovery-auth-group no-authentication
 314         listen 0.0.0.0:3260
 315         listen [::]:3260
 316         listen [fe80::be:ef]:3261
 317 }
 318
 319 target iqn.2012-06.com.example:target0 {
 320         alias "Example target"
 321         auth-group no-authentication
 322         lun 0 {
 323                 path /dev/zvol/tank/example_0
 324                 blocksize 4096
 325                 size 4G
 326         }
 327 }
 328
 329 target iqn.2012-06.com.example:target1 {
 330         chap chapuser chapsecret
 331         lun 0 {
 332                 path /dev/zvol/tank/example_1
 333         }
 334 }
 335
 336 target iqn.2012-06.com.example:target2 {
 337         auth-group ag0
 338         portal-group pg0
 339         lun 0 {
 340                 path /dev/zvol/tank/example2_0
 341         }
 342         lun 1 {
 343                 path /dev/zvol/tank/example2_1
 344                 option foo bar
 345         }
 346 }
 347 .Ed
 348 .Sh SEE ALSO
 349 .Xr ctl 4 ,
 350 .Xr ctladm 8 ,
 351 .Xr ctld 8
 352 .Sh AUTHORS
 353 The
 354 .Nm
 355 configuration file functionality for
 356 .Xr ctld 8
 357 was developed by
 358 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
 359 under sponsorship from the FreeBSD Foundation.