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