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.El 254.Ss target Context 255.Bl -tag -width indent 256.It Ic alias Ar text 257Assign a human-readable description to the target. 258There is no default. 259.It Ic auth-group Ar name 260Assign a previously defined authentication group to the target. 261By default, targets that do not specify their own auth settings, 262using clauses such as 263.Sy chap 264or 265.Sy initiator-name , 266are assigned 267predefined 268.Sy auth-group 269.Qq Ar default , 270which denies all access. 271Another predefined 272.Sy auth-group , 273.Qq Ar no-authentication , 274may be used to permit access 275without authentication. 276Note that this clause can be overridden using the second argument 277to a 278.Sy portal-group 279clause. 280.It Ic auth-type Ar type 281Sets the authentication type. 282Type can be either 283.Qq Ar none , 284.Qq Ar deny , 285.Qq Ar chap , 286or 287.Qq Ar chap-mutual . 288In most cases it is not necessary to set the type using this clause; 289it is usually used to disable authentication for a given 290.Sy target . 291This clause is mutually exclusive with 292.Sy auth-group ; 293one cannot use 294both in a single target. 295.It Ic chap Ar user Ar secret 296A set of CHAP authentication credentials. 297Note that targets must only use one of 298.Sy auth-group , chap , No or Sy chap-mutual ; 299it is a configuration error to mix multiple types in one target. 300.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret 301A set of mutual CHAP authentication credentials. 302Note that targets must only use one of 303.Sy auth-group , chap , No or Sy chap-mutual ; 304it is a configuration error to mix multiple types in one target. 305.It Ic initiator-name Ar initiator-name 306An iSCSI initiator name. 307Only initiators with a name matching one of the defined 308names will be allowed to connect. 309If not defined, there will be no restrictions based on initiator 310name. 311This clause is mutually exclusive with 312.Sy auth-group ; 313one cannot use 314both in a single target. 315.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen 316An iSCSI initiator portal: an IPv4 or IPv6 address, optionally 317followed by a literal slash and a prefix length. 318Only initiators with an address matching one of the defined 319addresses will be allowed to connect. 320If not defined, there will be no restrictions based on initiator 321address. 322This clause is mutually exclusive with 323.Sy auth-group ; 324one cannot use 325both in a single target. 326.Pp 327The 328.Sy auth-type , 329.Sy chap , 330.Sy chap-mutual , 331.Sy initiator-name , 332and 333.Sy initiator-portal 334clauses in the target context provide an alternative to assigning an 335.Sy auth-group 336defined separately, useful in the common case of authentication settings 337specific to a single target. 338.It Ic portal-group Ar name Op Ar ag-name 339Assign a previously defined portal group to the target. 340The default portal group is 341.Qq Ar default , 342which makes the target available 343on TCP port 3260 on all configured IPv4 and IPv6 addresses. 344Optional second argument specifies 345.Sy auth-group 346for connections to this specific portal group. 347If second argument is not specified, target 348.Sy auth-group 349is used. 350.It Ic port Ar name 351.It Ic port Ar name/pp 352.It Ic port Ar name/pp/vp 353Assign specified CTL port (such as "isp0" or "isp2/1") to the target. 354This is used to export the target through a specific physical - eg Fibre 355Channel - port, in addition to portal-groups configured for the target. 356Use 357.Cm "ctladm portlist" 358command to retrieve the list of available ports. 359On startup 360.Xr ctld 8 361configures LUN mapping and enables all assigned ports. 362Each port can be assigned to only one target. 363.It Ic redirect Ar address 364IPv4 or IPv6 address to redirect initiators to. 365When configured, all initiators attempting to connect to this target 366will get redirected using "Target moved temporarily" login response. 367Redirection happens after successful authentication. 368.It Ic lun Ar number Ar name 369Export previously defined 370.Sy lun 371by the parent target. 372.It Ic lun Ar number 373Create a 374.Sy lun 375configuration context, defining a LUN exported by the parent target. 376.Pp 377This is an alternative to defining the LUN separately, useful in the common 378case of a LUN being exported by a single target. 379.El 380.Ss lun Context 381.Bl -tag -width indent 382.It Ic backend Ar block No | Ar ramdisk 383The CTL backend to use for a given LUN. 384Valid choices are 385.Qq Ar block 386and 387.Qq Ar ramdisk ; 388block is used for LUNs backed 389by files or disk device nodes; ramdisk is a bitsink device, used mostly for 390testing. 391The default backend is block. 392.It Ic blocksize Ar size 393The blocksize visible to the initiator. 394The default blocksize is 512 for disks, and 2048 for CD/DVDs. 395.It Ic ctl-lun Ar lun_id 396Global numeric identifier to use for a given LUN inside CTL. 397By default CTL allocates those IDs dynamically, but explicit specification 398may be needed for consistency in HA configurations. 399.It Ic device-id Ar string 400The SCSI Device Identification string presented to the initiator. 401.It Ic device-type Ar type 402Specify the SCSI device type to use when creating the LUN. 403Currently CTL supports Direct Access (type 0), Processor (type 3) 404and CD/DVD (type 5) LUNs. 405.It Ic option Ar name Ar value 406The CTL-specific options passed to the kernel. 407All CTL-specific options are documented in the 408.Sx OPTIONS 409section of 410.Xr ctladm 8 . 411.It Ic path Ar path 412The path to the file, device node, or 413.Xr zfs 8 414volume used to back the LUN. 415For optimal performance, create the volume with the 416.Qq Ar volmode=dev 417property set. 418.It Ic serial Ar string 419The SCSI serial number presented to the initiator. 420.It Ic size Ar size 421The LUN size, in bytes. 422.El 423.Sh FILES 424.Bl -tag -width ".Pa /etc/ctl.conf" -compact 425.It Pa /etc/ctl.conf 426The default location of the 427.Xr ctld 8 428configuration file. 429.El 430.Sh EXAMPLES 431.Bd -literal 432auth-group ag0 { 433 chap-mutual "user" "secret" "mutualuser" "mutualsecret" 434 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret" 435 initiator-portal 192.168.1.1/16 436} 437 438auth-group ag1 { 439 auth-type none 440 initiator-name "iqn.2012-06.com.example:initiatorhost1" 441 initiator-name "iqn.2012-06.com.example:initiatorhost2" 442 initiator-portal 192.168.1.1/24 443 initiator-portal [2001:db8::de:ef] 444} 445 446portal-group pg0 { 447 discovery-auth-group no-authentication 448 listen 0.0.0.0:3260 449 listen [::]:3260 450 listen [fe80::be:ef]:3261 451} 452 453target iqn.2012-06.com.example:target0 { 454 alias "Example target" 455 auth-group no-authentication 456 lun 0 { 457 path /dev/zvol/tank/example_0 458 blocksize 4096 459 size 4G 460 } 461} 462 463lun example_1 { 464 path /dev/zvol/tank/example_1 465 option naa 0x50015178f369f093 466} 467 468target iqn.2012-06.com.example:target1 { 469 auth-group ag0 470 portal-group pg0 471 lun 0 example_1 472 lun 1 { 473 path /dev/zvol/tank/example_2 474 option vendor "FreeBSD" 475 } 476} 477 478target naa.50015178f369f092 { 479 port isp0 480 port isp1 481 lun 0 example_1 482} 483.Ed 484.Pp 485An equivalent configuration in UCL format, for use with 486.Fl u : 487.Bd -literal 488auth-group { 489 ag0 { 490 chap-mutual = [ 491 { 492 user = "user" 493 secret = "secretsecret" 494 mutual-user = "mutualuser" 495 mutual-secret = "mutualsecret" 496 }, 497 { 498 user = "user2" 499 secret = "secret2secret2" 500 mutual-user = "mutualuser" 501 mutual-secret = "mutualsecret" 502 } 503 ] 504 } 505 506 ag1 { 507 auth-type = none 508 initiator-name = [ 509 "iqn.2012-06.com.example:initiatorhost1", 510 "iqn.2012-06.com.example:initiatorhost2" 511 ] 512 initiator-portal = [192.168.1.1/24, "[2001:db8::de:ef]"] 513 } 514} 515 516portal-group { 517 pg0 { 518 discovery-auth-group = no-authentication 519 listen = [ 520 0.0.0.0:3260, 521 "[::]:3260", 522 "[fe80::be:ef]:3261" 523 ] 524 } 525} 526 527lun { 528 example_0 { 529 path = /dev/zvol/tank/example_0 530 blocksize = 4096 531 size = "4G" 532 } 533 534 example_1 { 535 path = /dev/zvol/tank/example_1 536 options { 537 naa = "0x50015178f369f093" 538 } 539 } 540 541 example_2 { 542 path = /dev/zvol/tank/example_2 543 options { 544 vendor = "FreeBSD" 545 } 546 } 547} 548 549target { 550 "iqn.2012-06.com.example:target0" { 551 alias = "Example target" 552 auth-group = no-authentication 553 lun = [ 554 { number = 0, name = example_0 }, 555 ] 556 } 557 558 "iqn.2012-06.com.example:target1" { 559 auth-group = ag0 560 portal-group { name = pg0 } 561 lun = [ 562 { number = 0, name = example_1 }, 563 { number = 1, name = example_2 } 564 ] 565 } 566 567 naa.50015178f369f092 { 568 port = isp0 569 lun = [ 570 { number = 0, name = example_1 } 571 ] 572 } 573} 574.Ed 575.Sh SEE ALSO 576.Xr ctl 4 , 577.Xr ctladm 8 , 578.Xr ctld 8 , 579.Xr zfs 8 580.Sh AUTHORS 581The 582.Nm 583configuration file functionality for 584.Xr ctld 8 585was developed by 586.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org 587under sponsorship from the FreeBSD Foundation. 588