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 September 14, 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.El 110.Ss auth-group Context 111.Bl -tag -width indent 112 113.It Ic auth-type Ar type 114Sets the authentication type. 115Type can be either 116.Qq Ar none , 117.Qq Ar deny , 118.Qq Ar chap , 119or 120.Qq Ar chap-mutual . 121In most cases it is not necessary to set the type using this clause; 122it is usually used to disable authentication for a given 123.Sy auth-group . 124.It Ic chap Ar user Ar secret 125A set of CHAP authentication credentials. 126Note that for any 127.Sy auth-group , 128the configuration may only contain either 129.Sy chap 130or 131.Sy chap-mutual 132entries; it is an error to mix them. 133.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret 134A set of mutual CHAP authentication credentials. 135Note that for any 136.Sy auth-group , 137the configuration may only contain either 138.Sy chap 139or 140.Sy chap-mutual 141entries; it is an error to mix them. 142.It Ic initiator-name Ar initiator-name 143An iSCSI initiator name. 144Only initiators with a name matching one of the defined 145names will be allowed to connect. 146If not defined, there will be no restrictions based on initiator 147name. 148.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen 149An iSCSI initiator portal: an IPv4 or IPv6 address, optionally 150followed by a literal slash and a prefix length. 151Only initiators with an address matching one of the defined 152addresses will be allowed to connect. 153If not defined, there will be no restrictions based on initiator 154address. 155.El 156.Ss portal-group Context 157.Bl -tag -width indent 158.It Ic discovery-auth-group Ar name 159Assign a previously defined authentication group to the portal group, 160to be used for target discovery. 161By default, portal groups that do not specify their own auth settings, 162using clauses such as 163.Sy chap 164or 165.Sy initiator-name , 166are assigned 167predefined 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 179An IPv4 or IPv6 address and port to listen on for incoming connections 180using 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 example2 { 306 chap-mutual "user" "secret" "mutualuser" "mutualsecret" 307 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret" 308 initiator-portal 192.168.1.1/16 309} 310 311portal-group example2 { 312 discovery-auth-group no-authentication 313 listen 127.0.0.1 314 listen 0.0.0.0:3261 315 listen [::]:3261 316 listen [fe80::be:ef] 317} 318 319target iqn.2012-06.com.example:target0 { 320 alias "Example target" 321 auth-group no-authentication 322 lun 0 { 323 path /dev/zvol/example_0 324 blocksize 4096 325 size 4G 326 } 327} 328 329target iqn.2012-06.com.example:target3 { 330 chap chapuser chapsecret 331 lun 0 { 332 path /dev/zvol/example_3 333 } 334} 335 336target iqn.2012-06.com.example:target2 { 337 auth-group example2 338 portal-group example2 339 lun 0 { 340 path /dev/zvol/example2_0 341 } 342 lun 1 { 343 path /dev/zvol/example2_1 344 option foo bar 345 } 346} 347.Ed 348.Sh SEE ALSO 349.Xr ctl 4 , 350.Xr ctladm 8 , 351.Xr ctld 8 352.Sh AUTHORS 353The 354.Nm 355configuration file functionality for 356.Xr ctld 8 357was developed by 358.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org 359under sponsorship from the FreeBSD Foundation. 360