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