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 August 24, 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 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 lun Ar name
  99 Create a
 100 .Sy lun
 101 configuration context, defining a LUN to be exported by any number of targets.
 102 .It Ic target Ar name
 103 Create a
 104 .Sy target
 105 configuration context, which can optionally contain one or more
 106 .Sy lun
 107 contexts.
 108 .It Ic timeout Ar seconds
 109 The timeout for login sessions, after which the connection
 110 will be forcibly terminated.
 111 The default is 60.
 112 A setting of 0 disables the timeout.
 113 .It Ic isns-server Ar address
 114 An IPv4 or IPv6 address and optionally port of iSNS server to register on.
 115 .It Ic isns-period Ar seconds
 116 iSNS registration period.
 117 Registered Network Entity not updated during this period will be unregistered.
 118 The default is 900.
 119 .It Ic isns-timeout Ar seconds
 120 Timeout for iSNS requests.
 121 The default is 5.
 122 .El
 123 .Ss auth-group Context
 124 .Bl -tag -width indent
 125 .It Ic auth-type Ar type
 126 Sets the authentication type.
 127 Type can be either
 128 .Qq Ar none ,
 129 .Qq Ar deny ,
 130 .Qq Ar chap ,
 131 or
 132 .Qq Ar chap-mutual .
 133 In most cases it is not necessary to set the type using this clause;
 134 it is usually used to disable authentication for a given
 135 .Sy auth-group .
 136 .It Ic chap Ar user Ar secret
 137 A set of CHAP authentication credentials.
 138 Note that for any
 139 .Sy auth-group ,
 140 the configuration may only contain either
 141 .Sy chap
 142 or
 143 .Sy chap-mutual
 144 entries; it is an error to mix them.
 145 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 146 A set of mutual CHAP authentication credentials.
 147 Note that for any
 148 .Sy auth-group ,
 149 the configuration may only contain either
 150 .Sy chap
 151 or
 152 .Sy chap-mutual
 153 entries; it is an error to mix them.
 154 .It Ic initiator-name Ar initiator-name
 155 An iSCSI initiator name.
 156 Only initiators with a name matching one of the defined
 157 names will be allowed to connect.
 158 If not defined, there will be no restrictions based on initiator
 159 name.
 160 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 161 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 162 followed by a literal slash and a prefix length.
 163 Only initiators with an address matching one of the defined
 164 addresses will be allowed to connect.
 165 If not defined, there will be no restrictions based on initiator
 166 address.
 167 .El
 168 .Ss portal-group Context
 169 .Bl -tag -width indent
 170 .It Ic discovery-auth-group Ar name
 171 Assign a previously defined authentication group to the portal group,
 172 to be used for target discovery.
 173 By default, portal groups are assigned predefined
 174 .Sy auth-group
 175 .Qq Ar default ,
 176 which denies discovery.
 177 Another predefined
 178 .Sy auth-group ,
 179 .Qq Ar no-authentication ,
 180 may be used
 181 to permit discovery without authentication.
 182 .It Ic discovery-filter Ar filter
 183 Determines which targets are returned during discovery.
 184 Filter can be either
 185 .Qq Ar none ,
 186 .Qq Ar portal ,
 187 .Qq Ar portal-name ,
 188 or
 189 .Qq Ar portal-name-auth .
 190 When set to
 191 .Qq Ar none ,
 192 discovery will return all targets assigned to that portal group.
 193 When set to
 194 .Qq Ar portal ,
 195 discovery will not return targets that cannot be accessed by the
 196 initiator because of their
 197 .Sy initiator-portal .
 198 When set to
 199 .Qq Ar portal-name ,
 200 the check will include both
 201 .Sy initiator-portal
 202 and
 203 .Sy initiator-name .
 204 When set to
 205 .Qq Ar portal-name-auth ,
 206 the check will include
 207 .Sy initiator-portal ,
 208 .Sy initiator-name ,
 209 and authentication credentials.
 210 The target is returned if it does not require CHAP authentication,
 211 or if the CHAP user and secret used during discovery match those
 212 used by the target.
 213 Note that when using
 214 .Qq Ar portal-name-auth ,
 215 targets that require CHAP authentication will only be returned if
 216 .Sy discovery-auth-group
 217 requires CHAP.
 218 The default is
 219 .Qq Ar none .
 220 .It Ic listen Ar address
 221 An IPv4 or IPv6 address and port to listen on for incoming connections.
 222 .\".It Ic listen-iser Ar address
 223 .\"An IPv4 or IPv6 address and port to listen on for incoming connections
 224 .\"using iSER (iSCSI over RDMA) protocol.
 225 .It Ic offload Ar driver
 226 Define iSCSI hardware offload driver to use for this
 227 .Sy portal-group .
 228 .It Ic redirect Ar address
 229 IPv4 or IPv6 address to redirect initiators to.
 230 When configured, all initiators attempting to connect to portal
 231 belonging to this
 232 .Sy portal-group
 233 will get redirected using "Target moved temporarily" login response.
 234 Redirection happens before authentication and any
 235 .Sy initiator-name
 236 or
 237 .Sy initiator-portal
 238 checks are skipped.
 239 .El
 240 .Ss target Context
 241 .Bl -tag -width indent
 242 .It Ic alias Ar text
 243 Assign a human-readable description to the target.
 244 There is no default.
 245 .It Ic auth-group Ar name
 246 Assign a previously defined authentication group to the target.
 247 By default, targets that do not specify their own auth settings,
 248 using clauses such as
 249 .Sy chap
 250 or
 251 .Sy initiator-name ,
 252 are assigned
 253 predefined
 254 .Sy auth-group
 255 .Qq Ar default ,
 256 which denies all access.
 257 Another predefined
 258 .Sy auth-group ,
 259 .Qq Ar no-authentication ,
 260 may be used to permit access
 261 without authentication.
 262 Note that this clause can be overridden using the second argument
 263 to a
 264 .Sy portal-group
 265 clause.
 266 .It Ic auth-type Ar type
 267 Sets the authentication type.
 268 Type can be either
 269 .Qq Ar none ,
 270 .Qq Ar deny ,
 271 .Qq Ar chap ,
 272 or
 273 .Qq Ar chap-mutual .
 274 In most cases it is not necessary to set the type using this clause;
 275 it is usually used to disable authentication for a given
 276 .Sy target .
 277 This clause is mutually exclusive with
 278 .Sy auth-group ;
 279 one cannot use
 280 both in a single target.
 281 .It Ic chap Ar user Ar secret
 282 A set of CHAP authentication credentials.
 283 Note that targets must only use one of
 284 .Sy auth-group , chap , No or Sy chap-mutual ;
 285 it is a configuration error to mix multiple types in one target.
 286 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 287 A set of mutual CHAP authentication credentials.
 288 Note that targets must only use one of
 289 .Sy auth-group , chap , No or Sy chap-mutual ;
 290 it is a configuration error to mix multiple types in one target.
 291 .It Ic initiator-name Ar initiator-name
 292 An iSCSI initiator name.
 293 Only initiators with a name matching one of the defined
 294 names will be allowed to connect.
 295 If not defined, there will be no restrictions based on initiator
 296 name.
 297 This clause is mutually exclusive with
 298 .Sy auth-group ;
 299 one cannot use
 300 both in a single target.
 301 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 302 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 303 followed by a literal slash and a prefix length.
 304 Only initiators with an address matching one of the defined
 305 addresses will be allowed to connect.
 306 If not defined, there will be no restrictions based on initiator
 307 address.
 308 This clause is mutually exclusive with
 309 .Sy auth-group ;
 310 one cannot use
 311 both in a single target.
 312 .Pp
 313 The
 314 .Sy auth-type ,
 315 .Sy chap ,
 316 .Sy chap-mutual ,
 317 .Sy initiator-name ,
 318 and
 319 .Sy initiator-portal
 320 clauses in the target context provide an alternative to assigning an
 321 .Sy auth-group
 322 defined separately, useful in the common case of authentication settings
 323 specific to a single target.
 324 .It Ic portal-group Ar name Op Ar ag-name
 325 Assign a previously defined portal group to the target.
 326 The default portal group is
 327 .Qq Ar default ,
 328 which makes the target available
 329 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
 330 Optional second argument specifies
 331 .Sy auth-group
 332 for connections to this specific portal group.
 333 If second argument is not specified, target
 334 .Sy auth-group
 335 is used.
 336 .It Ic port Ar name
 337 .It Ic port Ar name/pp
 338 .It Ic port Ar name/pp/vp
 339 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
 340 This is used to export the target through a specific physical - eg Fibre
 341 Channel - port, in addition to portal-groups configured for the target.
 342 Use
 343 .Cm "ctladm portlist"
 344 command to retrieve the list of available ports.
 345 On startup
 346 .Xr ctld 8
 347 configures LUN mapping and enables all assigned ports.
 348 Each port can be assigned to only one target.
 349 .It Ic redirect Ar address
 350 IPv4 or IPv6 address to redirect initiators to.
 351 When configured, all initiators attempting to connect to this target
 352 will get redirected using "Target moved temporarily" login response.
 353 Redirection happens after successful authentication.
 354 .It Ic lun Ar number Ar name
 355 Export previously defined
 356 .Sy lun
 357 by the parent target.
 358 .It Ic lun Ar number
 359 Create a
 360 .Sy lun
 361 configuration context, defining a LUN exported by the parent target.
 362 .Pp
 363 This is an alternative to defining the LUN separately, useful in the common
 364 case of a LUN being exported by a single target.
 365 .El
 366 .Ss lun Context
 367 .Bl -tag -width indent
 368 .It Ic backend Ar block No | Ar ramdisk
 369 The CTL backend to use for a given LUN.
 370 Valid choices are
 371 .Qq Ar block
 372 and
 373 .Qq Ar ramdisk ;
 374 block is used for LUNs backed
 375 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
 376 testing.
 377 The default backend is block.
 378 .It Ic blocksize Ar size
 379 The blocksize visible to the initiator.
 380 The default blocksize is 512.
 381 .It Ic device-id Ar string
 382 The SCSI Device Identification string presented to the initiator.
 383 .It Ic option Ar name Ar value
 384 The CTL-specific options passed to the kernel.
 385 All CTL-specific options are documented in the
 386 .Sx OPTIONS
 387 section of
 388 .Xr ctladm 8 .
 389 .It Ic path Ar path
 390 The path to the file, device node, or
 391 .Xr zfs 8
 392 volume used to back the LUN.
 393 For optimal performance, create the volume with the
 394 .Qq Ar volmode=dev
 395 property set.
 396 .It Ic serial Ar string
 397 The SCSI serial number presented to the initiator.
 398 .It Ic size Ar size
 399 The LUN size, in bytes.
 400 .El
 401 .Sh FILES
 402 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
 403 .It Pa /etc/ctl.conf
 404 The default location of the
 405 .Xr ctld 8
 406 configuration file.
 407 .El
 408 .Sh EXAMPLES
 409 .Bd -literal
 410 auth-group ag0 {
 411         chap-mutual "user" "secret" "mutualuser" "mutualsecret"
 412         chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
 413         initiator-portal 192.168.1.1/16
 414 }
 415
 416 auth-group ag1 {
 417         auth-type none
 418         initiator-name "iqn.2012-06.com.example:initiatorhost1"
 419         initiator-name "iqn.2012-06.com.example:initiatorhost2"
 420         initiator-portal 192.168.1.1/24
 421         initiator-portal [2001:db8::de:ef]
 422 }
 423
 424 portal-group pg0 {
 425         discovery-auth-group no-authentication
 426         listen 0.0.0.0:3260
 427         listen [::]:3260
 428         listen [fe80::be:ef]:3261
 429 }
 430
 431 target iqn.2012-06.com.example:target0 {
 432         alias "Example target"
 433         auth-group no-authentication
 434         lun 0 {
 435                 path /dev/zvol/tank/example_0
 436                 blocksize 4096
 437                 size 4G
 438         }
 439 }
 440
 441 lun example_1 {
 442         path /dev/zvol/tank/example_1
 443         option naa 0x50015178f369f093
 444 }
 445
 446 target iqn.2012-06.com.example:target1 {
 447         auth-group ag0
 448         portal-group pg0
 449         lun 0 example_1
 450         lun 1 {
 451                 path /dev/zvol/tank/example_2
 452                 option vendor "FreeBSD"
 453         }
 454 }
 455
 456 target naa.50015178f369f092 {
 457         port isp0
 458         port isp1
 459         lun 0 example_1
 460 }
 461 .Ed
 462 .Sh SEE ALSO
 463 .Xr ctl 4 ,
 464 .Xr ctladm 8 ,
 465 .Xr ctld 8 ,
 466 .Xr zfs 8
 467 .Sh AUTHORS
 468 The
 469 .Nm
 470 configuration file functionality for
 471 .Xr ctld 8
 472 was developed by
 473 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
 474 under sponsorship from the FreeBSD Foundation.