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