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