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