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