usr.sbin/ctld/ctl.conf.5

   1 .\" Copyright (c) 2012 The FreeBSD Foundation
   2 .\" Copyright (c) 2015 Alexander Motin <mav@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed by Edward Tomasz Napierala under sponsorship
   6 .\" from the FreeBSD Foundation.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd November 9, 2015
  32 .Dt CTL.CONF 5
  33 .Os
  34 .Sh NAME
  35 .Nm ctl.conf
  36 .Nd CAM Target Layer / iSCSI target daemon configuration file
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 configuration file is used by the
  41 .Xr ctld 8
  42 daemon.
  43 Lines starting with
  44 .Ql #
  45 are interpreted as comments.
  46 The general syntax of the
  47 .Nm
  48 file is:
  49 .Bd -literal -offset indent
  50 .No pidfile Ar path
  51
  52 .No auth-group Ar name No {
  53 .Dl chap Ar user Ar secret
  54 .Dl ...
  55 }
  56
  57 .No portal-group Ar name No {
  58 .Dl listen Ar address
  59 .\".Dl listen-iser Ar address
  60 .Dl discovery-auth-group Ar name
  61 .Dl ...
  62 }
  63
  64 .No lun Ar name No {
  65 .Dl path Ar path
  66 }
  67
  68 .No target Ar name {
  69 .Dl auth-group Ar name
  70 .Dl portal-group Ar name Op Ar agname
  71 .Dl port Ar name
  72 .Dl lun Ar number Ar name
  73 .Dl lun Ar number No {
  74 .Dl     path Ar path
  75 .Dl }
  76 .Dl ...
  77 }
  78 .Ed
  79 .Ss Global Context
  80 .Bl -tag -width indent
  81 .It Ic auth-group Ar name
  82 Create an
  83 .Sy auth-group
  84 configuration context,
  85 defining a new auth-group,
  86 which can then be assigned to any number of targets.
  87 .It Ic debug Ar level
  88 The debug verbosity level.
  89 The default is 0.
  90 .It Ic maxproc Ar number
  91 The limit for concurrently running child processes handling
  92 incoming connections.
  93 The default is 30.
  94 A setting of 0 disables the limit.
  95 .It Ic pidfile Ar path
  96 The path to the pidfile.
  97 The default is
  98 .Pa /var/run/ctld.pid .
  99 .It Ic portal-group Ar name
 100 Create a
 101 .Sy portal-group
 102 configuration context,
 103 defining a new portal-group,
 104 which can then be assigned to any number of targets.
 105 .It Ic lun Ar name
 106 Create a
 107 .Sy lun
 108 configuration context, defining a LUN to be exported by some target(s).
 109 .It Ic target Ar name
 110 Create a
 111 .Sy target
 112 configuration context, which can contain one or more
 113 .Sy lun
 114 contexts.
 115 .It Ic timeout Ar seconds
 116 The timeout for login sessions, after which the connection
 117 will be forcibly terminated.
 118 The default is 60.
 119 A setting of 0 disables the timeout.
 120 .It Ic isns-server Ar address
 121 An IPv4 or IPv6 address and optionally port of iSNS server to register on.
 122 .It Ic isns-period Ar seconds
 123 iSNS registration period.
 124 Registered Network Entity not updated during this period will be unregistered.
 125 The default is 900.
 126 .It Ic isns-timeout Ar seconds
 127 Timeout for iSNS requests.
 128 The default is 5.
 129 .El
 130 .Ss auth-group Context
 131 .Bl -tag -width indent
 132 .It Ic auth-type Ar type
 133 Sets the authentication type.
 134 Type can be either
 135 .Qq Ar none ,
 136 .Qq Ar deny ,
 137 .Qq Ar chap ,
 138 or
 139 .Qq Ar chap-mutual .
 140 In most cases it is not necessary to set the type using this clause;
 141 it is usually used to disable authentication for a given
 142 .Sy auth-group .
 143 .It Ic chap Ar user Ar secret
 144 A set of CHAP authentication credentials.
 145 Note that for any
 146 .Sy auth-group ,
 147 the configuration may only contain either
 148 .Sy chap
 149 or
 150 .Sy chap-mutual
 151 entries; it is an error to mix them.
 152 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 153 A set of mutual CHAP authentication credentials.
 154 Note that for any
 155 .Sy auth-group ,
 156 the configuration may only contain either
 157 .Sy chap
 158 or
 159 .Sy chap-mutual
 160 entries; it is an error to mix them.
 161 .It Ic initiator-name Ar initiator-name
 162 An iSCSI initiator name.
 163 Only initiators with a name matching one of the defined
 164 names will be allowed to connect.
 165 If not defined, there will be no restrictions based on initiator
 166 name.
 167 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 168 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 169 followed by a literal slash and a prefix length.
 170 Only initiators with an address matching one of the defined
 171 addresses will be allowed to connect.
 172 If not defined, there will be no restrictions based on initiator
 173 address.
 174 .El
 175 .Ss portal-group Context
 176 .Bl -tag -width indent
 177 .It Ic discovery-auth-group Ar name
 178 Assign a previously defined authentication group to the portal group,
 179 to be used for target discovery.
 180 By default, portal groups are assigned predefined
 181 .Sy auth-group
 182 .Qq Ar default ,
 183 which denies discovery.
 184 Another predefined
 185 .Sy auth-group ,
 186 .Qq Ar no-authentication ,
 187 may be used
 188 to permit discovery without authentication.
 189 .It Ic discovery-filter Ar filter
 190 Determines which targets are returned during discovery.
 191 Filter can be either
 192 .Qq Ar none ,
 193 .Qq Ar portal ,
 194 .Qq Ar portal-name ,
 195 or
 196 .Qq Ar portal-name-auth .
 197 When set to
 198 .Qq Ar none ,
 199 discovery will return all targets assigned to that portal group.
 200 When set to
 201 .Qq Ar portal ,
 202 discovery will not return targets that cannot be accessed by the
 203 initiator because of their
 204 .Sy initiator-portal .
 205 When set to
 206 .Qq Ar portal-name ,
 207 the check will include both
 208 .Sy initiator-portal
 209 and
 210 .Sy initiator-name .
 211 When set to
 212 .Qq Ar portal-name-auth ,
 213 the check will include
 214 .Sy initiator-portal ,
 215 .Sy initiator-name ,
 216 and authentication credentials.
 217 The target is returned if it does not require CHAP authentication,
 218 or if the CHAP user and secret used during discovery match those
 219 used by the target.
 220 Note that when using
 221 .Qq Ar portal-name-auth ,
 222 targets that require CHAP authentication will only be returned if
 223 .Sy discovery-auth-group
 224 requires CHAP.
 225 The default is
 226 .Qq Ar none .
 227 .It Ic listen Ar address
 228 An IPv4 or IPv6 address and port to listen on for incoming connections.
 229 .\".It Ic listen-iser Ar address
 230 .\"An IPv4 or IPv6 address and port to listen on for incoming connections
 231 .\"using iSER (iSCSI over RDMA) protocol.
 232 .It Ic option Ar name Ar value
 233 The CTL-specific port options passed to the kernel.
 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 .It Ic tag Ar value
 246 Unique 16-bit tag value of this
 247 .Sy portal-group .
 248 If not specified, the value is generated automatically.
 249 .It Ic foreign
 250 Specifies that this
 251 .Sy portal-group
 252 is listened by some other host.
 253 This host will announce it on discovery stage, but won't listen.
 254 .El
 255 .Ss target Context
 256 .Bl -tag -width indent
 257 .It Ic alias Ar text
 258 Assign a human-readable description to the target.
 259 There is no default.
 260 .It Ic auth-group Ar name
 261 Assign a previously defined authentication group to the target.
 262 By default, targets that do not specify their own auth settings,
 263 using clauses such as
 264 .Sy chap
 265 or
 266 .Sy initiator-name ,
 267 are assigned
 268 predefined
 269 .Sy auth-group
 270 .Qq Ar default ,
 271 which denies all access.
 272 Another predefined
 273 .Sy auth-group ,
 274 .Qq Ar no-authentication ,
 275 may be used to permit access
 276 without authentication.
 277 Note that targets must only use one of
 278 .Sy auth-group , chap , No or Sy chap-mutual ;
 279 it is a configuration error to mix multiple types in one target.
 280 .It Ic auth-type Ar type
 281 Sets the authentication type.
 282 Type can be either
 283 .Qq Ar none ,
 284 .Qq Ar deny ,
 285 .Qq Ar chap ,
 286 or
 287 .Qq Ar chap-mutual .
 288 In most cases it is not necessary to set the type using this clause;
 289 it is usually used to disable authentication for a given
 290 .Sy target .
 291 This clause is mutually exclusive with
 292 .Sy auth-group ;
 293 one cannot use
 294 both in a single target.
 295 .It Ic chap Ar user Ar secret
 296 A set of CHAP authentication credentials.
 297 Note that targets must only use one of
 298 .Sy auth-group , chap , No or Sy chap-mutual ;
 299 it is a configuration error to mix multiple types in one target.
 300 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 301 A set of mutual CHAP authentication credentials.
 302 Note that targets must only use one of
 303 .Sy auth-group , chap , No or Sy chap-mutual ;
 304 it is a configuration error to mix multiple types in one target.
 305 .It Ic initiator-name Ar initiator-name
 306 An iSCSI initiator name.
 307 Only initiators with a name matching one of the defined
 308 names will be allowed to connect.
 309 If not defined, there will be no restrictions based on initiator
 310 name.
 311 This clause is mutually exclusive with
 312 .Sy auth-group ;
 313 one cannot use
 314 both in a single target.
 315 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 316 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 317 followed by a literal slash and a prefix length.
 318 Only initiators with an address matching one of the defined
 319 addresses will be allowed to connect.
 320 If not defined, there will be no restrictions based on initiator
 321 address.
 322 This clause is mutually exclusive with
 323 .Sy auth-group ;
 324 one cannot use
 325 both in a single target.
 326 .It Ic portal-group Ar name Op Ar agname
 327 Assign a previously defined portal group to the target.
 328 The default portal group is
 329 .Qq Ar default ,
 330 which makes the target available
 331 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
 332 Optional second argument specifies auth group name for connections
 333 to this specific portal group.
 334 If second argument is not specified, target auth group is used.
 335 .It Ic port Ar name
 336 .It Ic port Ar name/pp
 337 .It Ic port Ar name/pp/vp
 338 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
 339 On startup ctld configures LUN mapping and enables all assigned ports.
 340 Each port can be assigned to only one target.
 341 .It Ic redirect Aq Ar address
 342 IPv4 or IPv6 address to redirect initiators to.
 343 When configured, all initiators attempting to connect to this target
 344 will get redirected using "Target moved temporarily" login response.
 345 Redirection happens after successful authentication.
 346 .It Ic lun Ar number Ar name
 347 Export previously defined
 348 .Sy lun
 349 by the parent target.
 350 .It Ic lun Ar number
 351 Create a
 352 .Sy lun
 353 configuration context, defining a LUN exported by the parent target.
 354 .El
 355 .Ss lun Context
 356 .Bl -tag -width indent
 357 .It Ic backend Ar block No | Ar ramdisk
 358 The CTL backend to use for a given LUN.
 359 Valid choices are
 360 .Qq Ar block
 361 and
 362 .Qq Ar ramdisk ;
 363 block is used for LUNs backed
 364 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
 365 testing.
 366 The default backend is block.
 367 .It Ic blocksize Ar size
 368 The blocksize visible to the initiator.
 369 The default blocksize is 512 for disks, and 2048 for CD/DVDs.
 370 .It Ic ctl-lun Ar lun_id
 371 Global numeric identifier to use for a given LUN inside CTL.
 372 By default CTL allocates those IDs dynamically, but explicit specification
 373 may be needed for consistency in HA configurations.
 374 .It Ic device-id Ar string
 375 The SCSI Device Identification string presented to the initiator.
 376 .It Ic device-type Ar type
 377 Specify the SCSI device type to use when creating the LUN.
 378 Currently CTL supports Direct Access (type 0), Processor (type 3)
 379 and CD/DVD (type 5) LUNs.
 380 .It Ic option Ar name Ar value
 381 The CTL-specific options passed to the kernel.
 382 All CTL-specific options are documented in the
 383 .Sx OPTIONS
 384 section of
 385 .Xr ctladm 8 .
 386 .It Ic path Ar path
 387 The path to the file, device node, or
 388 .Xr zfs 8
 389 volume used to back the LUN.
 390 For optimal performance, create the volume with the
 391 .Qq Ar volmode=dev
 392 property set.
 393 .It Ic serial Ar string
 394 The SCSI serial number presented to the initiator.
 395 .It Ic size Ar size
 396 The LUN size, in bytes.
 397 .El
 398 .Sh FILES
 399 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
 400 .It Pa /etc/ctl.conf
 401 The default location of the
 402 .Xr ctld 8
 403 configuration file.
 404 .El
 405 .Sh EXAMPLES
 406 .Bd -literal
 407 auth-group ag0 {
 408         chap-mutual "user" "secret" "mutualuser" "mutualsecret"
 409         chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
 410 }
 411
 412 auth-group ag1 {
 413         auth-type none
 414         initiator-name "iqn.2012-06.com.example:initiatorhost1"
 415         initiator-name "iqn.2012-06.com.example:initiatorhost2"
 416         initiator-portal 192.168.1.1/24
 417         initiator-portal [2001:db8::de:ef]
 418 }
 419
 420 portal-group pg0 {
 421         discovery-auth-group no-authentication
 422         listen 0.0.0.0:3260
 423         listen [::]:3260
 424         listen [fe80::be:ef]:3261
 425 }
 426
 427 target iqn.2012-06.com.example:target0 {
 428         alias "Example target"
 429         auth-group no-authentication
 430         lun 0 {
 431                 path /dev/zvol/tank/example_0
 432                 blocksize 4096
 433                 size 4G
 434         }
 435 }
 436
 437 lun example_1 {
 438         path /dev/zvol/tank/example_1
 439         option naa 0x50015178f369f093
 440 }
 441
 442 target iqn.2012-06.com.example:target1 {
 443         auth-group ag0
 444         portal-group pg0
 445         lun 0 example_1
 446         lun 1 {
 447                 path /dev/zvol/tank/example_2
 448                 option foo bar
 449         }
 450 }
 451
 452 target naa.50015178f369f092 {
 453         port isp0
 454         port isp1
 455         lun 0 example_1
 456 }
 457 .Ed
 458 .Sh SEE ALSO
 459 .Xr ctl 4 ,
 460 .Xr ctladm 8 ,
 461 .Xr ctld 8 ,
 462 .Xr zfs 8
 463 .Sh AUTHORS
 464 The
 465 .Nm
 466 configuration file functionality for
 467 .Xr ctld 8
 468 was developed by
 469 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org
 470 under sponsorship from the FreeBSD Foundation.