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