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 July 28, 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 pidfile <path>
  50
  51 auth-group <name> {
  52         chap <user> <secret>
  53         ...
  54 }
  55
  56 portal-group <name> {
  57         listen <address>
  58         listen-iser <address>
  59         discovery-auth-group <name>
  60         ...
  61 }
  62
  63 target <name> {
  64         auth-group <name>
  65         portal-group <name>
  66         lun <number> {
  67                 path <path>
  68         }
  69         ...
  70 }
  71 .Ed
  72 .Ss global level
  73 The following statements are available at the global level:
  74 .Bl -tag -width indent
  75 .It Ic auth-group Aq Ar name
  76 Opens an auth-group section, defining an authentication group,
  77 which can then be assigned to any number of targets.
  78 .It Ic debug Aq Ar level
  79 Specifies debug level.
  80 The default is 0.
  81 .It Ic maxproc Aq Ar number
  82 Specifies limit for concurrently running child processes handling
  83 incoming connections.
  84 The default is 30.
  85 Setting it to 0 disables the limit.
  86 .It Ic pidfile Aq Ar path
  87 Specifies path to pidfile.
  88 The default is
  89 .Pa /var/run/ctld.pid .
  90 .It Ic portal-group Aq Ar name
  91 Opens a portal-group section, defining a portal group,
  92 which can then be assigned to any number of targets.
  93 .It Ic target Aq Ar name
  94 Opens a target configuration section.
  95 .It Ic timeout Aq Ar seconds
  96 Specifies timeout for login session, after which the connection
  97 will be forcibly terminated.
  98 The default is 60.
  99 Setting it to 0 disables the timeout.
 100 .El
 101 .Ss auth-group level
 102 The following statements are available at the auth-group level:
 103 .Bl -tag -width indent
 104 .It Ic auth-type Ao Ar type Ac
 105 Specifies authentication type.
 106 Type can be either "none", "deny", "chap", or "chap-mutual".
 107 In most cases it is not necessary to set the type using this clause;
 108 it is usually used to disable authentication for a given auth-group.
 109 .It Ic chap Ao Ar user Ac Aq Ar secret
 110 Specifies CHAP authentication credentials.
 111 .It Ic chap-mutual Ao Ar user Ac Ao Ar secret Ac Ao Ar mutualuser Ac Aq Ar mutualsecret
 112 Specifies mutual CHAP authentication credentials.
 113 Note that for any auth-group, configuration may contain either chap,
 114 or chap-mutual entries; it is an error to mix them.
 115 .It Ic initiator-name Ao Ar initiator-name Ac
 116 Specifies iSCSI initiator name.
 117 If not defined, there will be no restrictions based on initiator
 118 name.
 119 Otherwise, only initiators with names matching one of defined
 120 ones will be allowed to connect.
 121 .It Ic initiator-portal Ao Ar address Ac
 122 Specifies iSCSI initiator portal - IPv4 or IPv6 address or network.
 123 If not defined, there will be no restrictions based on initiator
 124 address.
 125 Otherwise, only initiators with addresses matching one of defined
 126 ones will be allowed to connect.
 127 .El
 128 .Ss portal-group level
 129 The following statements are available at the portal-group level:
 130 .Bl -tag -width indent
 131 .It Ic discovery-auth-group Aq Ar name
 132 Assigns previously defined authentication group to the portal group,
 133 to be used for target discovery.
 134 By default, portal groups that do not specify their own auth settings,
 135 using clauses such as "chap" or "initiator-name", are assigned
 136 predefined auth-group "default", which denies discovery.
 137 Another predefined auth-group, "no-authentication", may be used
 138 to permit discovery without authentication.
 139 .It Ic listen Aq Ar address
 140 Specifies IPv4 or IPv6 address and port to listen on for incoming connections.
 141 .It Ic listen-iser Aq Ar address
 142 Specifies IPv4 or IPv6 address and port to listen on for incoming connections
 143 using iSER (iSCSI over RDMA) protocol.
 144 .El
 145 .Ss target level:
 146 The following statements are available at the target level:
 147 .Bl -tag -width indent
 148 .It Ic alias Aq Ar text
 149 Assigns human-readable description to the target.
 150 There is no default.
 151 .It Ic auth-group Aq Ar name
 152 Assigns previously defined authentication group to the target.
 153 By default, targets that do not specify their own auth settings,
 154 using clauses such as "chap" or "initiator-name", are assigned
 155 predefined auth-group "default", which denies all access.
 156 Another predefined auth-group, "no-authentication", may be used to permit access
 157 without authentication.
 158 .It Ic auth-type Ao Ar type Ac
 159 Specifies authentication type.
 160 Type can be either "none", "deny", "chap", or "chap-mutual".
 161 In most cases it is not necessary to set the type using this clause;
 162 it is usually used to disable authentication for a given target.
 163 This clause is mutually exclusive with auth-group; one cannot use
 164 both in a single target.
 165 .It Ic chap Ao Ar user Ac Aq Ar secret
 166 Specifies CHAP authentication credentials.
 167 Note that targets must use either auth-group, or chap,
 168 or chap-mutual clauses; it is a configuration error to mix them in one target.
 169 .It Ic chap-mutual Ao Ar user Ac Ao Ar secret Ac Ao Ar mutualuser Ac Aq Ar mutualsecret
 170 Specifies mutual CHAP authentication credentials.
 171 Note that targets must use either auth-group, chap, or
 172 chap-mutual clauses; it is a configuration error to mix them in one target.
 173 .It Ic initiator-name Ao Ar initiator-name Ac
 174 Specifies iSCSI initiator name.
 175 If not defined, there will be no restrictions based on initiator
 176 name.
 177 Otherwise, only initiators with names matching one of defined
 178 ones will be allowed to connect.
 179 This clause is mutually exclusive with auth-group; one cannot use
 180 both in a single target.
 181 .It Ic initiator-portal Ao Ar address Ac
 182 Specifies iSCSI initiator portal - IPv4 or IPv6 address.
 183 If not defined, there will be no restrictions based on initiator
 184 address.
 185 Otherwise, only initiators with addresses matching one of defined
 186 ones will be allowed to connect.
 187 This clause is mutually exclusive with auth-group; one cannot use
 188 both in a single target.
 189 .It Ic portal-group Aq Ar name
 190 Assigns previously defined portal group to the target.
 191 Default portal group is "default", which makes the target available
 192 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
 193 .It Ic lun Aq Ar number
 194 Opens a lun configuration section, defining LUN exported by a target.
 195 .El
 196 .Ss lun level
 197 The following statements are available at the lun level:
 198 .Bl -tag -width indent
 199 .It Ic backend Ao Ar block | Ar ramdisk Ac
 200 Specifies the CTL backend to use for a given LUN.
 201 Valid choices are
 202 .Dq block
 203 and
 204 .Dq ramdisk ;
 205 block is used for LUNs backed
 206 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
 207 testing.
 208 The default backend is block.
 209 .It Ic blocksize Aq Ar size
 210 Specifies blocksize visible to the initiator.
 211 The default blocksize is 512.
 212 .It Ic device-id Aq Ar string
 213 Specifies SCSI Device Identification string presented to the initiator.
 214 .It Ic option Ao Ar name Ac Aq Ar value
 215 Specifies CTL-specific options passed to the kernel.
 216 .It Ic path Aq Ar path
 217 Specifies path to file or device node used to back the LUN.
 218 .It Ic serial Aq Ar string
 219 Specifies SCSI serial number presented to the initiator.
 220 .It Ic size Aq Ar size
 221 Specifies LUN size, in bytes.
 222 .El
 223 .Sh FILES
 224 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
 225 .It Pa /etc/ctl.conf
 226 The default location of the
 227 .Xr ctld 8
 228 configuration file.
 229 .El
 230 .Sh EXAMPLES
 231 .Bd -literal
 232 pidfile /var/run/ctld.pid
 233
 234 auth-group example2 {
 235         chap-mutual "user" "secret" "mutualuser" "mutualsecret"
 236         chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
 237 }
 238
 239 portal-group example2 {
 240         discovery-auth-group no-authentication
 241         listen 127.0.0.1
 242         listen 0.0.0.0:3261
 243         listen [::]:3261
 244         listen [fe80::be:ef]
 245 }
 246
 247 target iqn.2012-06.com.example:target0 {
 248         alias "Example target"
 249         auth-group no-authentication
 250         lun 0 {
 251                 path /dev/zvol/example_0
 252                 blocksize 4096
 253                 size 4G
 254         }
 255 }
 256
 257 target iqn.2012-06.com.example:target3 {
 258         chap chapuser chapsecret
 259         lun 0 {
 260                 path /dev/zvol/example_3
 261         }
 262 }
 263
 264 target iqn.2012-06.com.example:target2 {
 265         auth-group example2
 266         portal-group example2
 267         lun 0 {
 268                 path /dev/zvol/example2_0
 269         }
 270         lun 1 {
 271                 path /dev/zvol/example2_1
 272                 option foo bar
 273         }
 274 }
 275 .Ed
 276 .Sh SEE ALSO
 277 .Xr ctl 4 ,
 278 .Xr ctladm 8 ,
 279 .Xr ctld 8
 280 .Sh AUTHORS
 281 The
 282 .Nm
 283 configuration file functionality for
 284 .Xr ctld 8
 285 was developed by
 286 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org
 287 under sponsorship from the FreeBSD Foundation.