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