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 September 14, 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 .El
 110 .Ss auth-group Context
 111 .Bl -tag -width indent
 112
 113 .It Ic auth-type Ar type
 114 Sets the authentication type.
 115 Type can be either
 116 .Qq Ar none ,
 117 .Qq Ar deny ,
 118 .Qq Ar chap ,
 119 or
 120 .Qq Ar chap-mutual .
 121 In most cases it is not necessary to set the type using this clause;
 122 it is usually used to disable authentication for a given
 123 .Sy auth-group .
 124 .It Ic chap Ar user Ar secret
 125 A set of CHAP authentication credentials.
 126 Note that for any
 127 .Sy auth-group ,
 128 the configuration may only contain either
 129 .Sy chap
 130 or
 131 .Sy chap-mutual
 132 entries; it is an error to mix them.
 133 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 134 A set of mutual CHAP authentication credentials.
 135 Note that for any
 136 .Sy auth-group ,
 137 the configuration may only contain either
 138 .Sy chap
 139 or
 140 .Sy chap-mutual
 141 entries; it is an error to mix them.
 142 .It Ic initiator-name Ar initiator-name
 143 An iSCSI initiator name.
 144 Only initiators with a name matching one of the defined
 145 names will be allowed to connect.
 146 If not defined, there will be no restrictions based on initiator
 147 name.
 148 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 149 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 150 followed by a literal slash and a prefix length.
 151 Only initiators with an address matching one of the defined
 152 addresses will be allowed to connect.
 153 If not defined, there will be no restrictions based on initiator
 154 address.
 155 .El
 156 .Ss portal-group Context
 157 .Bl -tag -width indent
 158 .It Ic discovery-auth-group Ar name
 159 Assign a previously defined authentication group to the portal group,
 160 to be used for target discovery.
 161 By default, portal groups that do not specify their own auth settings,
 162 using clauses such as
 163 .Sy chap
 164 or
 165 .Sy initiator-name ,
 166 are assigned
 167 predefined
 168 .Sy auth-group
 169 .Qq Ar default ,
 170 which denies discovery.
 171 Another predefined
 172 .Sy auth-group ,
 173 .Qq Ar no-authentication ,
 174 may be used
 175 to permit discovery without authentication.
 176 .It Ic listen Ar address
 177 An IPv4 or IPv6 address and port to listen on for incoming connections.
 178 .It Ic listen-iser Ar address
 179 An IPv4 or IPv6 address and port to listen on for incoming connections
 180 using iSER (iSCSI over RDMA) protocol.
 181 .El
 182 .Ss target Context
 183 .Bl -tag -width indent
 184 .It Ic alias Ar text
 185 Assign a human-readable description to the target.
 186 There is no default.
 187 .It Ic auth-group Ar name
 188 Assign a previously defined authentication group to the target.
 189 By default, targets that do not specify their own auth settings,
 190 using clauses such as
 191 .Sy chap
 192 or
 193 .Sy initiator-name ,
 194 are assigned
 195 predefined
 196 .Sy auth-group
 197 .Qq Ar default ,
 198 which denies all access.
 199 Another predefined
 200 .Sy auth-group ,
 201 .Qq Ar no-authentication ,
 202 may be used to permit access
 203 without authentication.
 204 Note that targets must only use one of
 205 .Sy auth-group , chap , No or Sy chap-mutual ;
 206 it is a configuration error to mix multiple types in one target.
 207 .It Ic auth-type Ar type
 208 Sets the authentication type.
 209 Type can be either
 210 .Qq Ar none ,
 211 .Qq Ar deny ,
 212 .Qq Ar chap ,
 213 or
 214 .Qq Ar chap-mutual .
 215 In most cases it is not necessary to set the type using this clause;
 216 it is usually used to disable authentication for a given
 217 .Sy target .
 218 This clause is mutually exclusive with
 219 .Sy auth-group ;
 220 one cannot use
 221 both in a single target.
 222 .It Ic chap Ar user Ar secret
 223 A set of CHAP authentication credentials.
 224 Note that targets must only use one of
 225 .Sy auth-group , chap , No or Sy chap-mutual ;
 226 it is a configuration error to mix multiple types in one target.
 227 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
 228 A set of mutual CHAP authentication credentials.
 229 Note that targets must only use one of
 230 .Sy auth-group , chap , No or Sy chap-mutual ;
 231 it is a configuration error to mix multiple types in one target.
 232 .It Ic initiator-name Ar initiator-name
 233 An iSCSI initiator name.
 234 Only initiators with a name matching one of the defined
 235 names will be allowed to connect.
 236 If not defined, there will be no restrictions based on initiator
 237 name.
 238 This clause is mutually exclusive with
 239 .Sy auth-group ;
 240 one cannot use
 241 both in a single target.
 242 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
 243 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
 244 followed by a literal slash and a prefix length.
 245 Only initiators with an address matching one of the defined
 246 addresses will be allowed to connect.
 247 If not defined, there will be no restrictions based on initiator
 248 address.
 249 This clause is mutually exclusive with
 250 .Sy auth-group ;
 251 one cannot use
 252 both in a single target.
 253 .It Ic portal-group Ar name
 254 Assign a previously defined portal group to the target.
 255 The default portal group is
 256 .Qq Ar default ,
 257 which makes the target available
 258 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
 259 .It Ic lun Ar number
 260 Create a
 261 .Sy lun
 262 configuration context, defining a LUN exported by the parent target.
 263 .El
 264 .Ss lun Context
 265 .Bl -tag -width indent
 266 .It Ic backend Ar block No | Ar ramdisk
 267 The CTL backend to use for a given LUN.
 268 Valid choices are
 269 .Qq Ar block
 270 and
 271 .Qq Ar ramdisk ;
 272 block is used for LUNs backed
 273 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
 274 testing.
 275 The default backend is block.
 276 .It Ic blocksize Ar size
 277 The blocksize visible to the initiator.
 278 The default blocksize is 512.
 279 .It Ic device-id Ar string
 280 The SCSI Device Identification string presented to the initiator.
 281 .It Ic option Ar name Ar value
 282 The CTL-specific options passed to the kernel.
 283 All CTL-specific options are documented in the
 284 .Sx OPTIONS
 285 section of
 286 .Xr ctladm 8 .
 287 .It Ic path Ar path
 288 The path to the file or device node used to back the LUN.
 289 .It Ic serial Ar string
 290 The SCSI serial number presented to the initiator.
 291 .It Ic size Ar size
 292 The LUN size, in bytes.
 293 .El
 294 .Sh FILES
 295 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
 296 .It Pa /etc/ctl.conf
 297 The default location of the
 298 .Xr ctld 8
 299 configuration file.
 300 .El
 301 .Sh EXAMPLES
 302 .Bd -literal
 303 pidfile /var/run/ctld.pid
 304
 305 auth-group example2 {
 306         chap-mutual "user" "secret" "mutualuser" "mutualsecret"
 307         chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
 308 }
 309
 310 portal-group example2 {
 311         discovery-auth-group no-authentication
 312         listen 127.0.0.1
 313         listen 0.0.0.0:3261
 314         listen [::]:3261
 315         listen [fe80::be:ef]
 316 }
 317
 318 target iqn.2012-06.com.example:target0 {
 319         alias "Example target"
 320         auth-group no-authentication
 321         lun 0 {
 322                 path /dev/zvol/example_0
 323                 blocksize 4096
 324                 size 4G
 325         }
 326 }
 327
 328 target iqn.2012-06.com.example:target3 {
 329         chap chapuser chapsecret
 330         lun 0 {
 331                 path /dev/zvol/example_3
 332         }
 333 }
 334
 335 target iqn.2012-06.com.example:target2 {
 336         auth-group example2
 337         portal-group example2
 338         lun 0 {
 339                 path /dev/zvol/example2_0
 340         }
 341         lun 1 {
 342                 path /dev/zvol/example2_1
 343                 option foo bar
 344         }
 345 }
 346 .Ed
 347 .Sh SEE ALSO
 348 .Xr ctl 4 ,
 349 .Xr ctladm 8 ,
 350 .Xr ctld 8
 351 .Sh AUTHORS
 352 The
 353 .Nm
 354 configuration file functionality for
 355 .Xr ctld 8
 356 was developed by
 357 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org
 358 under sponsorship from the FreeBSD Foundation.