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