usr.sbin/ctld/ctl.conf.5

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