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 October 23, 2014 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 target Ar name 99Create a 100.Sy target 101configuration context, which can contain one or more 102.Sy lun 103contexts. 104.It Ic timeout Ar seconds 105The timeout for login sessions, after which the connection 106will be forcibly terminated. 107The default is 60. 108A setting of 0 disables the timeout. 109.It Ic isns-server Ar address 110An IPv4 or IPv6 address and optionally port of iSNS server to register on. 111.It Ic isns-period Ar seconds 112iSNS registration period. 113Registered Network Entity not updated during this period will be unregistered. 114.It Ic isns-timeout Ar seconds 115Timeout for iSNS requests. 116.El 117.Ss auth-group Context 118.Bl -tag -width indent 119.It Ic auth-type Ar type 120Sets the authentication type. 121Type can be either 122.Qq Ar none , 123.Qq Ar deny , 124.Qq Ar chap , 125or 126.Qq Ar chap-mutual . 127In most cases it is not necessary to set the type using this clause; 128it is usually used to disable authentication for a given 129.Sy auth-group . 130.It Ic chap Ar user Ar secret 131A set of CHAP authentication credentials. 132Note that for any 133.Sy auth-group , 134the configuration may only contain either 135.Sy chap 136or 137.Sy chap-mutual 138entries; it is an error to mix them. 139.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret 140A set of mutual CHAP authentication credentials. 141Note that for any 142.Sy auth-group , 143the configuration may only contain either 144.Sy chap 145or 146.Sy chap-mutual 147entries; it is an error to mix them. 148.It Ic initiator-name Ar initiator-name 149An iSCSI initiator name. 150Only initiators with a name matching one of the defined 151names will be allowed to connect. 152If not defined, there will be no restrictions based on initiator 153name. 154.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen 155An iSCSI initiator portal: an IPv4 or IPv6 address, optionally 156followed by a literal slash and a prefix length. 157Only initiators with an address matching one of the defined 158addresses will be allowed to connect. 159If not defined, there will be no restrictions based on initiator 160address. 161.El 162.Ss portal-group Context 163.Bl -tag -width indent 164.It Ic discovery-auth-group Ar name 165Assign a previously defined authentication group to the portal group, 166to be used for target discovery. 167By default, portal groups are assigned predefined 168.Sy auth-group 169.Qq Ar default , 170which denies discovery. 171Another predefined 172.Sy auth-group , 173.Qq Ar no-authentication , 174may be used 175to permit discovery without authentication. 176.It Ic listen Ar address 177An IPv4 or IPv6 address and port to listen on for incoming connections. 178.\".It Ic listen-iser Ar address 179.\"An IPv4 or IPv6 address and port to listen on for incoming connections 180.\"using iSER (iSCSI over RDMA) protocol. 181.El 182.Ss target Context 183.Bl -tag -width indent 184.It Ic alias Ar text 185Assign a human-readable description to the target. 186There is no default. 187.It Ic auth-group Ar name 188Assign a previously defined authentication group to the target. 189By default, targets that do not specify their own auth settings, 190using clauses such as 191.Sy chap 192or 193.Sy initiator-name , 194are assigned 195predefined 196.Sy auth-group 197.Qq Ar default , 198which denies all access. 199Another predefined 200.Sy auth-group , 201.Qq Ar no-authentication , 202may be used to permit access 203without authentication. 204Note that targets must only use one of 205.Sy auth-group , chap , No or Sy chap-mutual ; 206it is a configuration error to mix multiple types in one target. 207.It Ic auth-type Ar type 208Sets the authentication type. 209Type can be either 210.Qq Ar none , 211.Qq Ar deny , 212.Qq Ar chap , 213or 214.Qq Ar chap-mutual . 215In most cases it is not necessary to set the type using this clause; 216it is usually used to disable authentication for a given 217.Sy target . 218This clause is mutually exclusive with 219.Sy auth-group ; 220one cannot use 221both in a single target. 222.It Ic chap Ar user Ar secret 223A set of CHAP authentication credentials. 224Note that targets must only use one of 225.Sy auth-group , chap , No or Sy chap-mutual ; 226it is a configuration error to mix multiple types in one target. 227.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret 228A set of mutual CHAP authentication credentials. 229Note that targets must only use one of 230.Sy auth-group , chap , No or Sy chap-mutual ; 231it is a configuration error to mix multiple types in one target. 232.It Ic initiator-name Ar initiator-name 233An iSCSI initiator name. 234Only initiators with a name matching one of the defined 235names will be allowed to connect. 236If not defined, there will be no restrictions based on initiator 237name. 238This clause is mutually exclusive with 239.Sy auth-group ; 240one cannot use 241both in a single target. 242.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen 243An iSCSI initiator portal: an IPv4 or IPv6 address, optionally 244followed by a literal slash and a prefix length. 245Only initiators with an address matching one of the defined 246addresses will be allowed to connect. 247If not defined, there will be no restrictions based on initiator 248address. 249This clause is mutually exclusive with 250.Sy auth-group ; 251one cannot use 252both in a single target. 253.It Ic portal-group Ar name 254Assign a previously defined portal group to the target. 255The default portal group is 256.Qq Ar default , 257which makes the target available 258on TCP port 3260 on all configured IPv4 and IPv6 addresses. 259.It Ic lun Ar number 260Create a 261.Sy lun 262configuration context, defining a LUN exported by the parent target. 263.El 264.Ss lun Context 265.Bl -tag -width indent 266.It Ic backend Ar block No | Ar ramdisk 267The CTL backend to use for a given LUN. 268Valid choices are 269.Qq Ar block 270and 271.Qq Ar ramdisk ; 272block is used for LUNs backed 273by files or disk device nodes; ramdisk is a bitsink device, used mostly for 274testing. 275The default backend is block. 276.It Ic blocksize Ar size 277The blocksize visible to the initiator. 278The default blocksize is 512. 279.It Ic device-id Ar string 280The SCSI Device Identification string presented to the initiator. 281.It Ic option Ar name Ar value 282The CTL-specific options passed to the kernel. 283All CTL-specific options are documented in the 284.Sx OPTIONS 285section of 286.Xr ctladm 8 . 287.It Ic path Ar path 288The path to the file or device node used to back the LUN. 289.It Ic serial Ar string 290The SCSI serial number presented to the initiator. 291.It Ic size Ar size 292The LUN size, in bytes. 293.El 294.Sh FILES 295.Bl -tag -width ".Pa /etc/ctl.conf" -compact 296.It Pa /etc/ctl.conf 297The default location of the 298.Xr ctld 8 299configuration file. 300.El 301.Sh EXAMPLES 302.Bd -literal 303pidfile /var/run/ctld.pid 304 305auth-group ag0 { 306 chap-mutual "user" "secret" "mutualuser" "mutualsecret" 307 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret" 308 initiator-portal 192.168.1.1/16 309} 310 311auth-group ag1 { 312 auth-type none 313 initiator-name "iqn.2012-06.com.example:initiatorhost1" 314 initiator-name "iqn.2012-06.com.example:initiatorhost2" 315 initiator-portal 192.168.1.1/24 316 initiator-portal [2001:db8::de:ef] 317} 318 319portal-group pg0 { 320 discovery-auth-group no-authentication 321 listen 0.0.0.0:3260 322 listen [::]:3260 323 listen [fe80::be:ef]:3261 324} 325 326target iqn.2012-06.com.example:target0 { 327 alias "Example target" 328 auth-group no-authentication 329 lun 0 { 330 path /dev/zvol/tank/example_0 331 blocksize 4096 332 size 4G 333 } 334} 335 336target iqn.2012-06.com.example:target1 { 337 chap chapuser chapsecret 338 lun 0 { 339 path /dev/zvol/tank/example_1 340 } 341} 342 343target iqn.2012-06.com.example:target2 { 344 auth-group ag0 345 portal-group pg0 346 lun 0 { 347 path /dev/zvol/tank/example2_0 348 } 349 lun 1 { 350 path /dev/zvol/tank/example2_1 351 option foo bar 352 } 353} 354.Ed 355.Sh SEE ALSO 356.Xr ctl 4 , 357.Xr ctladm 8 , 358.Xr ctld 8 359.Sh AUTHORS 360The 361.Nm 362configuration file functionality for 363.Xr ctld 8 364was developed by 365.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org 366under sponsorship from the FreeBSD Foundation. 367