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 April 19, 2015
  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 lun Ar name No {
  64 .Dl path Ar path
  65 }
  66
  67 .No target Ar name {
  68 .Dl auth-group Ar name
  69 .Dl portal-group Ar name Op Ar agname
  70 .Dl port Ar name
  71 .Dl lun Ar number Ar name
  72 .Dl lun Ar number No {
  73 .Dl     path Ar path
  74 .Dl }
  75 .Dl ...
  76 }
  77 .Ed
  78 .Ss Global Context
  79 .Bl -tag -width indent
  80 .It Ic auth-group Ar name
  81 Create an
  82 .Sy auth-group
  83 configuration context,
  84 defining a new auth-group,
  85 which can then be assigned to any number of targets.
  86 .It Ic debug Ar level
  87 The debug verbosity level.
  88 The default is 0.
  89 .It Ic maxproc Ar number
  90 The limit for concurrently running child processes handling
  91 incoming connections.
  92 The default is 30.
  93 A setting of 0 disables the limit.
  94 .It Ic pidfile Ar path
  95 The path to the pidfile.
  96 The default is
  97 .Pa /var/run/ctld.pid .
  98 .It Ic portal-group Ar name
  99 Create a
 100 .Sy portal-group
 101 configuration context,
 102 defining a new portal-group,
 103 which can then be assigned to any number of targets.
 104 .It Ic lun Ar name
 105 Create a
 106 .Sy lun
 107 configuration context, defining a LUN to be exported by some target(s).
 108 .It Ic target Ar name
 109 Create a
 110 .Sy target
 111 configuration context, which can contain one or more
 112 .Sy lun
 113 contexts.
 114 .It Ic timeout Ar seconds
 115 The timeout for login sessions, after which the connection
 116 will be forcibly terminated.
 117 The default is 60.
 118 A setting of 0 disables the timeout.
 119 .It Ic isns-server Ar address
 120 An IPv4 or IPv6 address and optionally port of iSNS server to register on.
 121 .It Ic isns-period Ar seconds
 122 iSNS registration period.
 123 Registered Network Entity not updated during this period will be unregistered.
 124 The default is 900.
 125 .It Ic isns-timeout Ar seconds
 126 Timeout for iSNS requests.
 127 The default is 5.
 128 .El
 129 .Ss auth-group Context
 130 .Bl -tag -width indent
 131 .It Ic auth-type Ar type
 132 Sets the authentication type.
 133 Type can be either
 134 .Qq Ar none ,
 135 .Qq Ar deny ,
 136 .Qq Ar chap ,
 137 or
 138 .Qq Ar chap-mutual .
 139 In most cases it is not necessary to set the type using this clause;
 140 it is usually used to disable authentication for a given
 141 .Sy auth-group .
 142 .It Ic chap Ar user Ar secret
 143 A set of CHAP authentication credentials.
 144 Note that for any
 145 .Sy auth-group ,
 146 the configuration may only contain either
 147 .Sy chap
 148 or
 149 .Sy chap-mutual
 150 entries; it is an error to mix them.
 151 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 152 A set of mutual CHAP authentication credentials.
 153 Note that for any
 154 .Sy auth-group ,
 155 the configuration may only contain either
 156 .Sy chap
 157 or
 158 .Sy chap-mutual
 159 entries; it is an error to mix them.
 160 .It Ic initiator-name Ar initiator-name
 161 An iSCSI initiator name.
 162 Only initiators with a name matching one of the defined
 163 names will be allowed to connect.
 164 If not defined, there will be no restrictions based on initiator
 165 name.
 166 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 167 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 168 followed by a literal slash and a prefix length.
 169 Only initiators with an address matching one of the defined
 170 addresses will be allowed to connect.
 171 If not defined, there will be no restrictions based on initiator
 172 address.
 173 .El
 174 .Ss portal-group Context
 175 .Bl -tag -width indent
 176 .It Ic discovery-auth-group Ar name
 177 Assign a previously defined authentication group to the portal group,
 178 to be used for target discovery.
 179 By default, portal groups are assigned predefined
 180 .Sy auth-group
 181 .Qq Ar default ,
 182 which denies discovery.
 183 Another predefined
 184 .Sy auth-group ,
 185 .Qq Ar no-authentication ,
 186 may be used
 187 to permit discovery without authentication.
 188 .It Ic discovery-filter Ar filter
 189 Determines which targets are returned during discovery.
 190 Filter can be either
 191 .Qq Ar none ,
 192 .Qq Ar portal ,
 193 .Qq Ar portal-name ,
 194 or
 195 .Qq Ar portal-name-auth .
 196 When set to
 197 .Qq Ar none ,
 198 discovery will return all targets assigned to that portal group.
 199 When set to
 200 .Qq Ar portal ,
 201 discovery will not return targets that cannot be accessed by the
 202 initiator because of their
 203 .Sy initiator-portal .
 204 When set to
 205 .Qq Ar portal-name ,
 206 the check will include both
 207 .Sy initiator-portal
 208 and
 209 .Sy initiator-name .
 210 When set to
 211 .Qq Ar portal-name-auth ,
 212 the check will include
 213 .Sy initiator-portal ,
 214 .Sy initiator-name ,
 215 and authentication credentials.
 216 The target is returned if it does not require CHAP authentication,
 217 or if the CHAP user and secret used during discovery match those
 218 used by the target.
 219 Note that when using
 220 .Qq Ar portal-name-auth ,
 221 targets that require CHAP authentication will only be returned if
 222 .Sy discovery-auth-group
 223 requires CHAP.
 224 The default is
 225 .Qq Ar none .
 226 .It Ic listen Ar address
 227 An IPv4 or IPv6 address and port to listen on for incoming connections.
 228 .\".It Ic listen-iser Ar address
 229 .\"An IPv4 or IPv6 address and port to listen on for incoming connections
 230 .\"using iSER (iSCSI over RDMA) protocol.
 231 .It Ic offload Ar driver
 232 Define iSCSI hardware offload driver to use for this
 233 .Sy portal-group .
 234 .It Ic redirect Ar address
 235 IPv4 or IPv6 address to redirect initiators to.
 236 When configured, all initiators attempting to connect to portal
 237 belonging to this
 238 .Sy portal-group
 239 will get redirected using "Target moved temporarily" login response.
 240 Redirection happens before authentication and any
 241 .Sy initiator-name
 242 or
 243 .Sy initiator-portal
 244 checks are skipped.
 245 .El
 246 .Ss target Context
 247 .Bl -tag -width indent
 248 .It Ic alias Ar text
 249 Assign a human-readable description to the target.
 250 There is no default.
 251 .It Ic auth-group Ar name
 252 Assign a previously defined authentication group to the target.
 253 By default, targets that do not specify their own auth settings,
 254 using clauses such as
 255 .Sy chap
 256 or
 257 .Sy initiator-name ,
 258 are assigned
 259 predefined
 260 .Sy auth-group
 261 .Qq Ar default ,
 262 which denies all access.
 263 Another predefined
 264 .Sy auth-group ,
 265 .Qq Ar no-authentication ,
 266 may be used to permit access
 267 without authentication.
 268 Note that targets must only use one of
 269 .Sy auth-group , chap , No or Sy chap-mutual ;
 270 it is a configuration error to mix multiple types in one target.
 271 .It Ic auth-type Ar type
 272 Sets the authentication type.
 273 Type can be either
 274 .Qq Ar none ,
 275 .Qq Ar deny ,
 276 .Qq Ar chap ,
 277 or
 278 .Qq Ar chap-mutual .
 279 In most cases it is not necessary to set the type using this clause;
 280 it is usually used to disable authentication for a given
 281 .Sy target .
 282 This clause is mutually exclusive with
 283 .Sy auth-group ;
 284 one cannot use
 285 both in a single target.
 286 .It Ic chap Ar user Ar secret
 287 A set of CHAP authentication credentials.
 288 Note that targets must only use one of
 289 .Sy auth-group , chap , No or Sy chap-mutual ;
 290 it is a configuration error to mix multiple types in one target.
 291 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 292 A set of mutual CHAP authentication credentials.
 293 Note that targets must only use one of
 294 .Sy auth-group , chap , No or Sy chap-mutual ;
 295 it is a configuration error to mix multiple types in one target.
 296 .It Ic initiator-name Ar initiator-name
 297 An iSCSI initiator name.
 298 Only initiators with a name matching one of the defined
 299 names will be allowed to connect.
 300 If not defined, there will be no restrictions based on initiator
 301 name.
 302 This clause is mutually exclusive with
 303 .Sy auth-group ;
 304 one cannot use
 305 both in a single target.
 306 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 307 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 308 followed by a literal slash and a prefix length.
 309 Only initiators with an address matching one of the defined
 310 addresses will be allowed to connect.
 311 If not defined, there will be no restrictions based on initiator
 312 address.
 313 This clause is mutually exclusive with
 314 .Sy auth-group ;
 315 one cannot use
 316 both in a single target.
 317 .It Ic portal-group Ar name Op Ar agname
 318 Assign a previously defined portal group to the target.
 319 The default portal group is
 320 .Qq Ar default ,
 321 which makes the target available
 322 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
 323 Optional second argument specifies auth group name for connections
 324 to this specific portal group.
 325 If second argument is not specified, target auth group is used.
 326 .It Ic port Ar name
 327 Assign specified CTL port (such as "isp0") to the target.
 328 On startup ctld configures LUN mapping and enables all assigned ports.
 329 Each port can be assigned to only one target.
 330 .It Ic redirect Ar address
 331 IPv4 or IPv6 address to redirect initiators to.
 332 When configured, all initiators attempting to connect to this target
 333 will get redirected using "Target moved temporarily" login response.
 334 Redirection happens after successful authentication.
 335 .It Ic lun Ar number Ar name
 336 Export previously defined
 337 .Sy lun
 338 by the parent target.
 339 .It Ic lun Ar number
 340 Create a
 341 .Sy lun
 342 configuration context, defining a LUN exported by the parent target.
 343 .El
 344 .Ss lun Context
 345 .Bl -tag -width indent
 346 .It Ic backend Ar block No | Ar ramdisk
 347 The CTL backend to use for a given LUN.
 348 Valid choices are
 349 .Qq Ar block
 350 and
 351 .Qq Ar ramdisk ;
 352 block is used for LUNs backed
 353 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
 354 testing.
 355 The default backend is block.
 356 .It Ic blocksize Ar size
 357 The blocksize visible to the initiator.
 358 The default blocksize is 512.
 359 .It Ic device-id Ar string
 360 The SCSI Device Identification string presented to the initiator.
 361 .It Ic option Ar name Ar value
 362 The CTL-specific options passed to the kernel.
 363 All CTL-specific options are documented in the
 364 .Sx OPTIONS
 365 section of
 366 .Xr ctladm 8 .
 367 .It Ic path Ar path
 368 The path to the file, device node, or
 369 .Xr zfs 8
 370 volume used to back the LUN.
 371 For optimal performance, create the volume with the
 372 .Qq Ar volmode=dev
 373 property set.
 374 .It Ic serial Ar string
 375 The SCSI serial number presented to the initiator.
 376 .It Ic size Ar size
 377 The LUN size, in bytes.
 378 .El
 379 .Sh FILES
 380 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
 381 .It Pa /etc/ctl.conf
 382 The default location of the
 383 .Xr ctld 8
 384 configuration file.
 385 .El
 386 .Sh EXAMPLES
 387 .Bd -literal
 388 auth-group ag0 {
 389         chap-mutual "user" "secret" "mutualuser" "mutualsecret"
 390         chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
 391         initiator-portal 192.168.1.1/16
 392 }
 393
 394 auth-group ag1 {
 395         auth-type none
 396         initiator-name "iqn.2012-06.com.example:initiatorhost1"
 397         initiator-name "iqn.2012-06.com.example:initiatorhost2"
 398         initiator-portal 192.168.1.1/24
 399         initiator-portal [2001:db8::de:ef]
 400 }
 401
 402 portal-group pg0 {
 403         discovery-auth-group no-authentication
 404         listen 0.0.0.0:3260
 405         listen [::]:3260
 406         listen [fe80::be:ef]:3261
 407 }
 408
 409 target iqn.2012-06.com.example:target0 {
 410         alias "Example target"
 411         auth-group no-authentication
 412         lun 0 {
 413                 path /dev/zvol/tank/example_0
 414                 blocksize 4096
 415                 size 4G
 416         }
 417 }
 418
 419 lun example_1 {
 420         path /dev/zvol/tank/example_1
 421         option naa 0x50015178f369f093
 422 }
 423
 424 target iqn.2012-06.com.example:target1 {
 425         auth-group ag0
 426         portal-group pg0
 427         lun 0 example_1
 428         lun 1 {
 429                 path /dev/zvol/tank/example_2
 430                 option foo bar
 431         }
 432 }
 433
 434 target naa.50015178f369f092 {
 435         port isp0
 436         port isp1
 437         lun 0 example_1
 438 }
 439 .Ed
 440 .Sh SEE ALSO
 441 .Xr ctl 4 ,
 442 .Xr ctladm 8 ,
 443 .Xr ctld 8 ,
 444 .Xr zfs 8
 445 .Sh AUTHORS
 446 The
 447 .Nm
 448 configuration file functionality for
 449 .Xr ctld 8
 450 was developed by
 451 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
 452 under sponsorship from the FreeBSD Foundation.