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 29, 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 discovery-filter Ar filter 179Determines which targets are returned during discovery. 180Filter can be either 181.Qq Ar none , 182.Qq Ar portal , 183.Qq Ar portal-name , 184or 185.Qq Ar portal-name-auth . 186When set to 187.Qq Ar none , 188discovery will return all targets assigned to that portal group. 189When set to 190.Qq Ar portal , 191discovery will not return targets that cannot be accessed by the 192initiator because of their 193.Sy initiator-portal . 194When set to 195.Qq Ar portal-name , 196the check will include both 197.Sy initiator-portal 198and 199.Sy initiator-name . 200When set to 201.Qq Ar portal-name-auth , 202the check will include 203.Sy initiator-portal , 204.Sy initiator-name , 205and authentication credentials, ie. if the target does not require 206CHAP authentication, or if CHAP user and secret used during discovery 207match CHAP user and secret required to access the target. 208Note that when using 209.Qq Ar portal-name-auth , 210targets that require CHAP authentication will only be returned if 211.Sy discovery-auth-group 212requires CHAP. 213The default is 214.Qq Ar none . 215.It Ic listen Ar address 216An IPv4 or IPv6 address and port to listen on for incoming connections. 217.\".It Ic listen-iser Ar address 218.\"An IPv4 or IPv6 address and port to listen on for incoming connections 219.\"using iSER (iSCSI over RDMA) protocol. 220.El 221.Ss target Context 222.Bl -tag -width indent 223.It Ic alias Ar text 224Assign a human-readable description to the target. 225There is no default. 226.It Ic auth-group Ar name 227Assign a previously defined authentication group to the target. 228By default, targets that do not specify their own auth settings, 229using clauses such as 230.Sy chap 231or 232.Sy initiator-name , 233are assigned 234predefined 235.Sy auth-group 236.Qq Ar default , 237which denies all access. 238Another predefined 239.Sy auth-group , 240.Qq Ar no-authentication , 241may be used to permit access 242without authentication. 243Note that targets must only use one of 244.Sy auth-group , chap , No or Sy chap-mutual ; 245it is a configuration error to mix multiple types in one target. 246.It Ic auth-type Ar type 247Sets the authentication type. 248Type can be either 249.Qq Ar none , 250.Qq Ar deny , 251.Qq Ar chap , 252or 253.Qq Ar chap-mutual . 254In most cases it is not necessary to set the type using this clause; 255it is usually used to disable authentication for a given 256.Sy target . 257This clause is mutually exclusive with 258.Sy auth-group ; 259one cannot use 260both in a single target. 261.It Ic chap Ar user Ar secret 262A set of CHAP authentication credentials. 263Note that targets must only use one of 264.Sy auth-group , chap , No or Sy chap-mutual ; 265it is a configuration error to mix multiple types in one target. 266.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret 267A set of mutual CHAP authentication credentials. 268Note that targets must only use one of 269.Sy auth-group , chap , No or Sy chap-mutual ; 270it is a configuration error to mix multiple types in one target. 271.It Ic initiator-name Ar initiator-name 272An iSCSI initiator name. 273Only initiators with a name matching one of the defined 274names will be allowed to connect. 275If not defined, there will be no restrictions based on initiator 276name. 277This clause is mutually exclusive with 278.Sy auth-group ; 279one cannot use 280both in a single target. 281.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen 282An iSCSI initiator portal: an IPv4 or IPv6 address, optionally 283followed by a literal slash and a prefix length. 284Only initiators with an address matching one of the defined 285addresses will be allowed to connect. 286If not defined, there will be no restrictions based on initiator 287address. 288This clause is mutually exclusive with 289.Sy auth-group ; 290one cannot use 291both in a single target. 292.It Ic portal-group Ar name 293Assign a previously defined portal group to the target. 294The default portal group is 295.Qq Ar default , 296which makes the target available 297on TCP port 3260 on all configured IPv4 and IPv6 addresses. 298.It Ic lun Ar number 299Create a 300.Sy lun 301configuration context, defining a LUN exported by the parent target. 302.El 303.Ss lun Context 304.Bl -tag -width indent 305.It Ic backend Ar block No | Ar ramdisk 306The CTL backend to use for a given LUN. 307Valid choices are 308.Qq Ar block 309and 310.Qq Ar ramdisk ; 311block is used for LUNs backed 312by files or disk device nodes; ramdisk is a bitsink device, used mostly for 313testing. 314The default backend is block. 315.It Ic blocksize Ar size 316The blocksize visible to the initiator. 317The default blocksize is 512. 318.It Ic device-id Ar string 319The SCSI Device Identification string presented to the initiator. 320.It Ic option Ar name Ar value 321The CTL-specific options passed to the kernel. 322All CTL-specific options are documented in the 323.Sx OPTIONS 324section of 325.Xr ctladm 8 . 326.It Ic path Ar path 327The path to the file or device node used to back the LUN. 328.It Ic serial Ar string 329The SCSI serial number presented to the initiator. 330.It Ic size Ar size 331The LUN size, in bytes. 332.El 333.Sh FILES 334.Bl -tag -width ".Pa /etc/ctl.conf" -compact 335.It Pa /etc/ctl.conf 336The default location of the 337.Xr ctld 8 338configuration file. 339.El 340.Sh EXAMPLES 341.Bd -literal 342pidfile /var/run/ctld.pid 343 344auth-group ag0 { 345 chap-mutual "user" "secret" "mutualuser" "mutualsecret" 346 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret" 347 initiator-portal 192.168.1.1/16 348} 349 350auth-group ag1 { 351 auth-type none 352 initiator-name "iqn.2012-06.com.example:initiatorhost1" 353 initiator-name "iqn.2012-06.com.example:initiatorhost2" 354 initiator-portal 192.168.1.1/24 355 initiator-portal [2001:db8::de:ef] 356} 357 358portal-group pg0 { 359 discovery-auth-group no-authentication 360 listen 0.0.0.0:3260 361 listen [::]:3260 362 listen [fe80::be:ef]:3261 363} 364 365target iqn.2012-06.com.example:target0 { 366 alias "Example target" 367 auth-group no-authentication 368 lun 0 { 369 path /dev/zvol/tank/example_0 370 blocksize 4096 371 size 4G 372 } 373} 374 375target iqn.2012-06.com.example:target1 { 376 chap chapuser chapsecret 377 lun 0 { 378 path /dev/zvol/tank/example_1 379 } 380} 381 382target iqn.2012-06.com.example:target2 { 383 auth-group ag0 384 portal-group pg0 385 lun 0 { 386 path /dev/zvol/tank/example2_0 387 } 388 lun 1 { 389 path /dev/zvol/tank/example2_1 390 option foo bar 391 } 392} 393.Ed 394.Sh SEE ALSO 395.Xr ctl 4 , 396.Xr ctladm 8 , 397.Xr ctld 8 398.Sh AUTHORS 399The 400.Nm 401configuration file functionality for 402.Xr ctld 8 403was developed by 404.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org 405under sponsorship from the FreeBSD Foundation. 406