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: stable/10/usr.sbin/ctld/ctl.conf.5 279002 2015-02-19 14:31:16Z mav $
|
28.\" $FreeBSD: stable/10/usr.sbin/ctld/ctl.conf.5 279006 2015-02-19 14:52:01Z mav $ |
29.\"
|
30.Dd February 1, 2015
|
30.Dd February 6, 2015 |
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 lun Ar name No { 64.Dl path Ar path 65} 66 67.No target Ar name { 68.Dl auth-group Ar name
|
69.Dl portal-group Ar name
|
69.Dl portal-group Ar name Op Ar agname |
70.Dl lun Ar number Ar name 71.Dl lun Ar number No { 72.Dl path Ar path 73.Dl } 74.Dl ... 75} 76.Ed 77.Ss Global Context 78.Bl -tag -width indent 79.It Ic auth-group Ar name 80Create an 81.Sy auth-group 82configuration context, 83defining a new auth-group, 84which can then be assigned to any number of targets. 85.It Ic debug Ar level 86The debug verbosity level. 87The default is 0. 88.It Ic maxproc Ar number 89The limit for concurrently running child processes handling 90incoming connections. 91The default is 30. 92A setting of 0 disables the limit. 93.It Ic pidfile Ar path 94The path to the pidfile. 95The default is 96.Pa /var/run/ctld.pid . 97.It Ic portal-group Ar name 98Create a 99.Sy portal-group 100configuration context, 101defining a new portal-group, 102which can then be assigned to any number of targets. 103.It Ic lun Ar name 104Create a 105.Sy lun 106configuration context, defining a LUN to be exported by some target(s). 107.It Ic target Ar name 108Create a 109.Sy target 110configuration context, which can contain one or more 111.Sy lun 112contexts. 113.It Ic timeout Ar seconds 114The timeout for login sessions, after which the connection 115will be forcibly terminated. 116The default is 60. 117A setting of 0 disables the timeout. 118.It Ic isns-server Ar address 119An IPv4 or IPv6 address and optionally port of iSNS server to register on. 120.It Ic isns-period Ar seconds 121iSNS registration period. 122Registered Network Entity not updated during this period will be unregistered. 123The default is 900. 124.It Ic isns-timeout Ar seconds 125Timeout for iSNS requests. 126The default is 5. 127.El 128.Ss auth-group Context 129.Bl -tag -width indent 130.It Ic auth-type Ar type 131Sets the authentication type. 132Type can be either 133.Qq Ar none , 134.Qq Ar deny , 135.Qq Ar chap , 136or 137.Qq Ar chap-mutual . 138In most cases it is not necessary to set the type using this clause; 139it is usually used to disable authentication for a given 140.Sy auth-group . 141.It Ic chap Ar user Ar secret 142A set of 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 chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret 151A set of mutual CHAP authentication credentials. 152Note that for any 153.Sy auth-group , 154the configuration may only contain either 155.Sy chap 156or 157.Sy chap-mutual 158entries; it is an error to mix them. 159.It Ic initiator-name Ar initiator-name 160An iSCSI initiator name. 161Only initiators with a name matching one of the defined 162names will be allowed to connect. 163If not defined, there will be no restrictions based on initiator 164name. 165.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen 166An iSCSI initiator portal: an IPv4 or IPv6 address, optionally 167followed by a literal slash and a prefix length. 168Only initiators with an address matching one of the defined 169addresses will be allowed to connect. 170If not defined, there will be no restrictions based on initiator 171address. 172.El 173.Ss portal-group Context 174.Bl -tag -width indent 175.It Ic discovery-auth-group Ar name 176Assign a previously defined authentication group to the portal group, 177to be used for target discovery. 178By default, portal groups are assigned predefined 179.Sy auth-group 180.Qq Ar default , 181which denies discovery. 182Another predefined 183.Sy auth-group , 184.Qq Ar no-authentication , 185may be used 186to permit discovery without authentication. 187.It Ic discovery-filter Ar filter 188Determines which targets are returned during discovery. 189Filter can be either 190.Qq Ar none , 191.Qq Ar portal , 192.Qq Ar portal-name , 193or 194.Qq Ar portal-name-auth . 195When set to 196.Qq Ar none , 197discovery will return all targets assigned to that portal group. 198When set to 199.Qq Ar portal , 200discovery will not return targets that cannot be accessed by the 201initiator because of their 202.Sy initiator-portal . 203When set to 204.Qq Ar portal-name , 205the check will include both 206.Sy initiator-portal 207and 208.Sy initiator-name . 209When set to 210.Qq Ar portal-name-auth , 211the check will include 212.Sy initiator-portal , 213.Sy initiator-name , 214and authentication credentials. 215The target is returned if it does not require CHAP authentication, 216or if the CHAP user and secret used during discovery match those 217used by the target. 218Note that when using 219.Qq Ar portal-name-auth , 220targets that require CHAP authentication will only be returned if 221.Sy discovery-auth-group 222requires CHAP. 223The default is 224.Qq Ar none . 225.It Ic listen Ar address 226An IPv4 or IPv6 address and port to listen on for incoming connections. 227.\".It Ic listen-iser Ar address 228.\"An IPv4 or IPv6 address and port to listen on for incoming connections 229.\"using iSER (iSCSI over RDMA) protocol. 230.It Ic redirect Aq Ar address 231IPv4 or IPv6 address to redirect initiators to. 232When configured, all initiators attempting to connect to portal 233belonging to this 234.Sy portal-group 235will get redirected using "Target moved temporarily" login response. 236Redirection happens before authentication and any 237.Sy initiator-name 238or 239.Sy initiator-portal 240checks are skipped. 241.El 242.Ss target Context 243.Bl -tag -width indent 244.It Ic alias Ar text 245Assign a human-readable description to the target. 246There is no default. 247.It Ic auth-group Ar name 248Assign a previously defined authentication group to the target. 249By default, targets that do not specify their own auth settings, 250using clauses such as 251.Sy chap 252or 253.Sy initiator-name , 254are assigned 255predefined 256.Sy auth-group 257.Qq Ar default , 258which denies all access. 259Another predefined 260.Sy auth-group , 261.Qq Ar no-authentication , 262may be used to permit access 263without authentication. 264Note that targets must only use one of 265.Sy auth-group , chap , No or Sy chap-mutual ; 266it is a configuration error to mix multiple types in one target. 267.It Ic auth-type Ar type 268Sets the authentication type. 269Type can be either 270.Qq Ar none , 271.Qq Ar deny , 272.Qq Ar chap , 273or 274.Qq Ar chap-mutual . 275In most cases it is not necessary to set the type using this clause; 276it is usually used to disable authentication for a given 277.Sy target . 278This clause is mutually exclusive with 279.Sy auth-group ; 280one cannot use 281both in a single target. 282.It Ic chap Ar user Ar secret 283A set of CHAP authentication credentials. 284Note that targets must only use one of 285.Sy auth-group , chap , No or Sy chap-mutual ; 286it is a configuration error to mix multiple types in one target. 287.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret 288A set of mutual CHAP authentication credentials. 289Note that targets must only use one of 290.Sy auth-group , chap , No or Sy chap-mutual ; 291it is a configuration error to mix multiple types in one target. 292.It Ic initiator-name Ar initiator-name 293An iSCSI initiator name. 294Only initiators with a name matching one of the defined 295names will be allowed to connect. 296If not defined, there will be no restrictions based on initiator 297name. 298This clause is mutually exclusive with 299.Sy auth-group ; 300one cannot use 301both in a single target. 302.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen 303An iSCSI initiator portal: an IPv4 or IPv6 address, optionally 304followed by a literal slash and a prefix length. 305Only initiators with an address matching one of the defined 306addresses will be allowed to connect. 307If not defined, there will be no restrictions based on initiator 308address. 309This clause is mutually exclusive with 310.Sy auth-group ; 311one cannot use 312both in a single target.
|
313.It Ic portal-group Ar name
|
313.It Ic portal-group Ar name Op Ar agname |
314Assign a previously defined portal group to the target. 315The default portal group is 316.Qq Ar default , 317which makes the target available 318on TCP port 3260 on all configured IPv4 and IPv6 addresses.
|
319Optional second argument specifies auth group name for connections 320to this specific portal group. 321If second argument is not specified, target auth group is used. |
322.It Ic redirect Aq Ar address 323IPv4 or IPv6 address to redirect initiators to. 324When configured, all initiators attempting to connect to this target 325will get redirected using "Target moved temporarily" login response. 326Redirection happens after successful authentication. 327.It Ic lun Ar number Ar name 328Export previously defined 329.Sy lun 330by the parent target. 331.It Ic lun Ar number 332Create a 333.Sy lun 334configuration context, defining a LUN exported by the parent target. 335.El 336.Ss lun Context 337.Bl -tag -width indent 338.It Ic backend Ar block No | Ar ramdisk 339The CTL backend to use for a given LUN. 340Valid choices are 341.Qq Ar block 342and 343.Qq Ar ramdisk ; 344block is used for LUNs backed 345by files or disk device nodes; ramdisk is a bitsink device, used mostly for 346testing. 347The default backend is block. 348.It Ic blocksize Ar size 349The blocksize visible to the initiator. 350The default blocksize is 512. 351.It Ic device-id Ar string 352The SCSI Device Identification string presented to the initiator. 353.It Ic option Ar name Ar value 354The CTL-specific options passed to the kernel. 355All CTL-specific options are documented in the 356.Sx OPTIONS 357section of 358.Xr ctladm 8 . 359.It Ic path Ar path 360The path to the file or device node used to back the LUN. 361.It Ic serial Ar string 362The SCSI serial number presented to the initiator. 363.It Ic size Ar size 364The LUN size, in bytes. 365.El 366.Sh FILES 367.Bl -tag -width ".Pa /etc/ctl.conf" -compact 368.It Pa /etc/ctl.conf 369The default location of the 370.Xr ctld 8 371configuration file. 372.El 373.Sh EXAMPLES 374.Bd -literal 375auth-group ag0 { 376 chap-mutual "user" "secret" "mutualuser" "mutualsecret" 377 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret" 378} 379 380auth-group ag1 { 381 auth-type none 382 initiator-name "iqn.2012-06.com.example:initiatorhost1" 383 initiator-name "iqn.2012-06.com.example:initiatorhost2" 384 initiator-portal 192.168.1.1/24 385 initiator-portal [2001:db8::de:ef] 386} 387 388portal-group pg0 { 389 discovery-auth-group no-authentication 390 listen 0.0.0.0:3260 391 listen [::]:3260 392 listen [fe80::be:ef]:3261 393} 394 395target iqn.2012-06.com.example:target0 { 396 alias "Example target" 397 auth-group no-authentication 398 lun 0 { 399 path /dev/zvol/tank/example_0 400 blocksize 4096 401 size 4G 402 } 403} 404 405lun example_1 { 406 path /dev/zvol/tank/example_1 407} 408 409target iqn.2012-06.com.example:target1 { 410 chap chapuser chapsecret 411 lun 0 example_1 412} 413 414target iqn.2012-06.com.example:target2 { 415 auth-group ag0 416 portal-group pg0 417 lun 0 example_1 418 lun 1 { 419 path /dev/zvol/tank/example_2 420 option foo bar 421 } 422} 423.Ed 424.Sh SEE ALSO 425.Xr ctl 4 , 426.Xr ctladm 8 , 427.Xr ctld 8 428.Sh AUTHORS 429The 430.Nm 431configuration file functionality for 432.Xr ctld 8 433was developed by 434.An Edward Tomasz Napierala Aq trasz@FreeBSD.org 435under sponsorship from the FreeBSD Foundation.
|