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 October 13, 2020
  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 target Ar name {
  65 .Dl auth-group Ar name
  66 .Dl portal-group Ar name
  67 .Dl lun Ar number No {
  68 .Dl     path Ar path
  69 .Dl }
  70 .Dl ...
  71 }
  72 .Ed
  73 .Ss Global Context
  74 .Bl -tag -width indent
  75 .It Ic auth-group Ar name
  76 Create an
  77 .Sy auth-group
  78 configuration context,
  79 defining a new auth-group,
  80 which can then be assigned to any number of targets.
  81 .It Ic debug Ar level
  82 The debug verbosity level.
  83 The default is 0.
  84 .It Ic maxproc Ar number
  85 The limit for concurrently running child processes handling
  86 incoming connections.
  87 The default is 30.
  88 A setting of 0 disables the limit.
  89 .It Ic pidfile Ar path
  90 The path to the pidfile.
  91 The default is
  92 .Pa /var/run/ctld.pid .
  93 .It Ic portal-group Ar name
  94 Create a
  95 .Sy portal-group
  96 configuration context,
  97 defining a new portal-group,
  98 which can then be assigned to any number of targets.
  99 .It Ic lun Ar name
 100 Create a
 101 .Sy lun
 102 configuration context, defining a LUN to be exported by any number of targets.
 103 .It Ic target Ar name
 104 Create a
 105 .Sy target
 106 configuration context, which can optionally contain one or more
 107 .Sy lun
 108 contexts.
 109 .It Ic timeout Ar seconds
 110 The timeout for login sessions, after which the connection
 111 will be forcibly terminated.
 112 The default is 60.
 113 A setting of 0 disables the timeout.
 114 .It Ic isns-server Ar address
 115 An IPv4 or IPv6 address and optionally port of iSNS server to register on.
 116 .It Ic isns-period Ar seconds
 117 iSNS registration period.
 118 Registered Network Entity not updated during this period will be unregistered.
 119 The default is 900.
 120 .It Ic isns-timeout Ar seconds
 121 Timeout for iSNS requests.
 122 The default is 5.
 123 .El
 124 .Ss auth-group Context
 125 .Bl -tag -width indent
 126 .It Ic auth-type Ar type
 127 Sets the authentication type.
 128 Type can be either
 129 .Qq Ar none ,
 130 .Qq Ar deny ,
 131 .Qq Ar chap ,
 132 or
 133 .Qq Ar chap-mutual .
 134 In most cases it is not necessary to set the type using this clause;
 135 it is usually used to disable authentication for a given
 136 .Sy auth-group .
 137 .It Ic chap Ar user Ar secret
 138 A set of CHAP authentication credentials.
 139 Note that for any
 140 .Sy auth-group ,
 141 the configuration may only contain either
 142 .Sy chap
 143 or
 144 .Sy chap-mutual
 145 entries; it is an error to mix them.
 146 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 147 A set of mutual CHAP authentication credentials.
 148 Note that for any
 149 .Sy auth-group ,
 150 the configuration may only contain either
 151 .Sy chap
 152 or
 153 .Sy chap-mutual
 154 entries; it is an error to mix them.
 155 .It Ic initiator-name Ar initiator-name
 156 An iSCSI initiator name.
 157 Only initiators with a name matching one of the defined
 158 names will be allowed to connect.
 159 If not defined, there will be no restrictions based on initiator
 160 name.
 161 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 162 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 163 followed by a literal slash and a prefix length.
 164 Only initiators with an address matching one of the defined
 165 addresses will be allowed to connect.
 166 If not defined, there will be no restrictions based on initiator
 167 address.
 168 .El
 169 .Ss portal-group Context
 170 .Bl -tag -width indent
 171 .It Ic discovery-auth-group Ar name
 172 Assign a previously defined authentication group to the portal group,
 173 to be used for target discovery.
 174 By default, portal groups are assigned predefined
 175 .Sy auth-group
 176 .Qq Ar default ,
 177 which denies discovery.
 178 Another predefined
 179 .Sy auth-group ,
 180 .Qq Ar no-authentication ,
 181 may be used
 182 to permit discovery without authentication.
 183 .It Ic discovery-filter Ar filter
 184 Determines which targets are returned during discovery.
 185 Filter can be either
 186 .Qq Ar none ,
 187 .Qq Ar portal ,
 188 .Qq Ar portal-name ,
 189 or
 190 .Qq Ar portal-name-auth .
 191 When set to
 192 .Qq Ar none ,
 193 discovery will return all targets assigned to that portal group.
 194 When set to
 195 .Qq Ar portal ,
 196 discovery will not return targets that cannot be accessed by the
 197 initiator because of their
 198 .Sy initiator-portal .
 199 When set to
 200 .Qq Ar portal-name ,
 201 the check will include both
 202 .Sy initiator-portal
 203 and
 204 .Sy initiator-name .
 205 When set to
 206 .Qq Ar portal-name-auth ,
 207 the check will include
 208 .Sy initiator-portal ,
 209 .Sy initiator-name ,
 210 and authentication credentials.
 211 The target is returned if it does not require CHAP authentication,
 212 or if the CHAP user and secret used during discovery match those
 213 used by the target.
 214 Note that when using
 215 .Qq Ar portal-name-auth ,
 216 targets that require CHAP authentication will only be returned if
 217 .Sy discovery-auth-group
 218 requires CHAP.
 219 The default is
 220 .Qq Ar none .
 221 .It Ic listen Ar address
 222 An IPv4 or IPv6 address and port to listen on for incoming connections.
 223 .\".It Ic listen-iser Ar address
 224 .\"An IPv4 or IPv6 address and port to listen on for incoming connections
 225 .\"using iSER (iSCSI over RDMA) protocol.
 226 .It Ic offload Ar driver
 227 Define iSCSI hardware offload driver to use for this
 228 .Sy portal-group .
 229 The default is
 230 .Qq Ar none .
 231 .It Ic option Ar name Ar value
 232 The CTL-specific port options passed to the kernel.
 233 .It Ic redirect Ar address
 234 IPv4 or IPv6 address to redirect initiators to.
 235 When configured, all initiators attempting to connect to portal
 236 belonging to this
 237 .Sy portal-group
 238 will get redirected using "Target moved temporarily" login response.
 239 Redirection happens before authentication and any
 240 .Sy initiator-name
 241 or
 242 .Sy initiator-portal
 243 checks are skipped.
 244 .It Ic tag Ar value
 245 Unique 16-bit tag value of this
 246 .Sy portal-group .
 247 If not specified, the value is generated automatically.
 248 .It Ic foreign
 249 Specifies that this
 250 .Sy portal-group
 251 is listened by some other host.
 252 This host will announce it on discovery stage, but won't listen.
 253 .It Ic dscp Ar value
 254 The DiffServ Codepoint used for sending data. The DSCP can be
 255 set to numeric, or hexadecimal values directly, as well as the
 256 well-defined
 257 .Qq Ar CSx
 258 and
 259 .Qq Ar AFxx
 260 codepoints.
 261 .It Ic pcp Ar value
 262 The 802.1Q Priority CodePoint used for sending packets.
 263 The PCP can be set to a value in the range between
 264 .Qq Ar 0
 265 to
 266 .Qq Ar 7 .
 267 When omitted, the default for the outgoing interface is used.
 268 .El
 269 .Ss target Context
 270 .Bl -tag -width indent
 271 .It Ic alias Ar text
 272 Assign a human-readable description to the target.
 273 There is no default.
 274 .It Ic auth-group Ar name
 275 Assign a previously defined authentication group to the target.
 276 By default, targets that do not specify their own auth settings,
 277 using clauses such as
 278 .Sy chap
 279 or
 280 .Sy initiator-name ,
 281 are assigned
 282 predefined
 283 .Sy auth-group
 284 .Qq Ar default ,
 285 which denies all access.
 286 Another predefined
 287 .Sy auth-group ,
 288 .Qq Ar no-authentication ,
 289 may be used to permit access
 290 without authentication.
 291 Note that this clause can be overridden using the second argument
 292 to a
 293 .Sy portal-group
 294 clause.
 295 .It Ic auth-type Ar type
 296 Sets the authentication type.
 297 Type can be either
 298 .Qq Ar none ,
 299 .Qq Ar deny ,
 300 .Qq Ar chap ,
 301 or
 302 .Qq Ar chap-mutual .
 303 In most cases it is not necessary to set the type using this clause;
 304 it is usually used to disable authentication for a given
 305 .Sy target .
 306 This clause is mutually exclusive with
 307 .Sy auth-group ;
 308 one cannot use
 309 both in a single target.
 310 .It Ic chap Ar user Ar secret
 311 A set of CHAP authentication credentials.
 312 Note that targets must only use one of
 313 .Sy auth-group , chap , No or Sy chap-mutual ;
 314 it is a configuration error to mix multiple types in one target.
 315 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 316 A set of mutual CHAP authentication credentials.
 317 Note that targets must only use one of
 318 .Sy auth-group , chap , No or Sy chap-mutual ;
 319 it is a configuration error to mix multiple types in one target.
 320 .It Ic initiator-name Ar initiator-name
 321 An iSCSI initiator name.
 322 Only initiators with a name matching one of the defined
 323 names will be allowed to connect.
 324 If not defined, there will be no restrictions based on initiator
 325 name.
 326 This clause is mutually exclusive with
 327 .Sy auth-group ;
 328 one cannot use
 329 both in a single target.
 330 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 331 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 332 followed by a literal slash and a prefix length.
 333 Only initiators with an address matching one of the defined
 334 addresses will be allowed to connect.
 335 If not defined, there will be no restrictions based on initiator
 336 address.
 337 This clause is mutually exclusive with
 338 .Sy auth-group ;
 339 one cannot use
 340 both in a single target.
 341 .Pp
 342 The
 343 .Sy auth-type ,
 344 .Sy chap ,
 345 .Sy chap-mutual ,
 346 .Sy initiator-name ,
 347 and
 348 .Sy initiator-portal
 349 clauses in the target context provide an alternative to assigning an
 350 .Sy auth-group
 351 defined separately, useful in the common case of authentication settings
 352 specific to a single target.
 353 .It Ic portal-group Ar name Op Ar ag-name
 354 Assign a previously defined portal group to the target.
 355 The default portal group is
 356 .Qq Ar default ,
 357 which makes the target available
 358 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
 359 Optional second argument specifies
 360 .Sy auth-group
 361 for connections to this specific portal group.
 362 If second argument is not specified, target
 363 .Sy auth-group
 364 is used.
 365 .It Ic port Ar name
 366 .It Ic port Ar name/pp
 367 .It Ic port Ar name/pp/vp
 368 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
 369 This is used to export the target through a specific physical - eg Fibre
 370 Channel - port, in addition to portal-groups configured for the target.
 371 Use
 372 .Cm "ctladm portlist"
 373 command to retrieve the list of available ports.
 374 On startup
 375 .Xr ctld 8
 376 configures LUN mapping and enables all assigned ports.
 377 Each port can be assigned to only one target.
 378 .It Ic redirect Ar address
 379 IPv4 or IPv6 address to redirect initiators to.
 380 When configured, all initiators attempting to connect to this target
 381 will get redirected using "Target moved temporarily" login response.
 382 Redirection happens after successful authentication.
 383 .It Ic lun Ar number Ar name
 384 Export previously defined
 385 .Sy lun
 386 by the parent target.
 387 .It Ic lun Ar number
 388 Create a
 389 .Sy lun
 390 configuration context, defining a LUN exported by the parent target.
 391 .Pp
 392 This is an alternative to defining the LUN separately, useful in the common
 393 case of a LUN being exported by a single target.
 394 .El
 395 .Ss lun Context
 396 .Bl -tag -width indent
 397 .It Ic backend Ar block No | Ar ramdisk
 398 The CTL backend to use for a given LUN.
 399 Valid choices are
 400 .Qq Ar block
 401 and
 402 .Qq Ar ramdisk ;
 403 block is used for LUNs backed
 404 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
 405 testing.
 406 The default backend is block.
 407 .It Ic blocksize Ar size
 408 The blocksize visible to the initiator.
 409 The default blocksize is 512 for disks, and 2048 for CD/DVDs.
 410 .It Ic ctl-lun Ar lun_id
 411 Global numeric identifier to use for a given LUN inside CTL.
 412 By default CTL allocates those IDs dynamically, but explicit specification
 413 may be needed for consistency in HA configurations.
 414 .It Ic device-id Ar string
 415 The SCSI Device Identification string presented to the initiator.
 416 .It Ic device-type Ar type
 417 Specify the SCSI device type to use when creating the LUN.
 418 Currently CTL supports Direct Access (type 0), Processor (type 3)
 419 and CD/DVD (type 5) LUNs.
 420 .It Ic option Ar name Ar value
 421 The CTL-specific options passed to the kernel.
 422 All CTL-specific options are documented in the
 423 .Sx OPTIONS
 424 section of
 425 .Xr ctladm 8 .
 426 .It Ic path Ar path
 427 The path to the file, device node, or
 428 .Xr zfs 8
 429 volume used to back the LUN.
 430 For optimal performance, create the volume with the
 431 .Qq Ar volmode=dev
 432 property set.
 433 .It Ic serial Ar string
 434 The SCSI serial number presented to the initiator.
 435 .It Ic size Ar size
 436 The LUN size, in bytes or by number with a suffix of
 437 .Sy K , M , G , T
 438 (for kilobytes, megabytes, gigabytes, or terabytes).
 439 When the configuration is in UCL format, use the suffix format
 440 .Sy kKmMgG Ns | Ns Sy bB ,
 441 (i.e., 4GB, 4gb, and 4Gb are all equivalent).
 442 .El
 443 .Sh FILES
 444 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
 445 .It Pa /etc/ctl.conf
 446 The default location of the
 447 .Xr ctld 8
 448 configuration file.
 449 .El
 450 .Sh EXAMPLES
 451 .Bd -literal
 452 auth-group ag0 {
 453         chap-mutual "user" "secret" "mutualuser" "mutualsecret"
 454         chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
 455         initiator-portal 192.168.1.1/16
 456 }
 457
 458 auth-group ag1 {
 459         auth-type none
 460         initiator-name "iqn.2012-06.com.example:initiatorhost1"
 461         initiator-name "iqn.2012-06.com.example:initiatorhost2"
 462         initiator-portal 192.168.1.1/24
 463         initiator-portal [2001:db8::de:ef]
 464 }
 465
 466 portal-group pg0 {
 467         discovery-auth-group no-authentication
 468         listen 0.0.0.0:3260
 469         listen [::]:3260
 470         listen [fe80::be:ef]:3261
 471 }
 472
 473 target iqn.2012-06.com.example:target0 {
 474         alias "Example target"
 475         auth-group no-authentication
 476         lun 0 {
 477                 path /dev/zvol/tank/example_0
 478                 blocksize 4096
 479                 size 4G
 480         }
 481 }
 482
 483 lun example_1 {
 484         path /dev/zvol/tank/example_1
 485         option naa 0x50015178f369f093
 486 }
 487
 488 target iqn.2012-06.com.example:target1 {
 489         auth-group ag0
 490         portal-group pg0
 491         lun 0 example_1
 492         lun 1 {
 493                 path /dev/zvol/tank/example_2
 494                 option vendor "FreeBSD"
 495         }
 496 }
 497
 498 target naa.50015178f369f092 {
 499         port isp0
 500         port isp1
 501         lun 0 example_1
 502 }
 503 .Ed
 504 .Pp
 505 An equivalent configuration in UCL format, for use with
 506 .Fl u :
 507 .Bd -literal
 508 auth-group {
 509         ag0 {
 510                 chap-mutual = [
 511                         {
 512                                 user = "user"
 513                                 secret = "secretsecret"
 514                                 mutual-user = "mutualuser"
 515                                 mutual-secret = "mutualsecret"
 516                         },
 517                         {
 518                                 user = "user2"
 519                                 secret = "secret2secret2"
 520                                 mutual-user = "mutualuser"
 521                                 mutual-secret = "mutualsecret"
 522                         }
 523                 ]
 524         }
 525
 526         ag1 {
 527                 auth-type = none
 528                 initiator-name = [
 529                         "iqn.2012-06.com.example:initiatorhost1",
 530                         "iqn.2012-06.com.example:initiatorhost2"
 531                 ]
 532                 initiator-portal = [192.168.1.1/24, "[2001:db8::de:ef]"]
 533         }
 534 }
 535
 536 portal-group {
 537         pg0 {
 538                 discovery-auth-group = no-authentication
 539                 listen = [
 540                         0.0.0.0:3260,
 541                         "[::]:3260",
 542                         "[fe80::be:ef]:3261"
 543                 ]
 544         }
 545 }
 546
 547 lun {
 548         example_0 {
 549                 path = /dev/zvol/tank/example_0
 550                 blocksize = 4096
 551                 size = 4GB
 552         }
 553
 554         example_1 {
 555                 path = /dev/zvol/tank/example_1
 556                 options {
 557                         naa = "0x50015178f369f093"
 558                 }
 559         }
 560
 561         example_2 {
 562                 path = /dev/zvol/tank/example_2
 563                 options {
 564                         vendor = "FreeBSD"
 565                 }
 566         }
 567 }
 568
 569 target {
 570         "iqn.2012-06.com.example:target0" {
 571                 alias = "Example target"
 572                 auth-group = no-authentication
 573                 lun = [
 574                         { number = 0, name = example_0 },
 575                 ]
 576         }
 577
 578         "iqn.2012-06.com.example:target1" {
 579                 auth-group = ag0
 580                 portal-group { name = pg0 }
 581                 lun = [
 582                         { number = 0, name = example_1 },
 583                         { number = 1, name = example_2 }
 584                 ]
 585         }
 586
 587         naa.50015178f369f092 {
 588                 port = isp0
 589                 lun = [
 590                         { number = 0, name = example_1 }
 591                 ]
 592         }
 593 }
 594 .Ed
 595 .Sh SEE ALSO
 596 .Xr ctl 4 ,
 597 .Xr ctladm 8 ,
 598 .Xr ctld 8 ,
 599 .Xr zfs 8
 600 .Sh AUTHORS
 601 The
 602 .Nm
 603 configuration file functionality for
 604 .Xr ctld 8
 605 was developed by
 606 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
 607 under sponsorship from the FreeBSD Foundation.