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 11, 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 and empty lines 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", "chap", or "chap-mutual".
 107 In most cases it is not neccessary 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's 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.
 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 that portal group,
 133 to be used for target discovery.
 134 By default, the discovery will be denied.
 135 A special auth-group, "no-authentication", may be used to allow for discovery
 136 without authentication.
 137 .It Ic listen Aq Ar address
 138 Specifies IPv4 or IPv6 address and port to listen on for incoming connections.
 139 .It Ic listen-iser Aq Ar address
 140 Specifies IPv4 or IPv6 address and port to listen on for incoming connections
 141 using iSER (iSCSI over RDMA) protocol.
 142 .El
 143 .Ss target level:
 144 The following statements are available at the target level:
 145 .Bl -tag -width indent
 146 .It Ic alias Aq Ar text
 147 Assigns human-readable description to that target.
 148 There is no default.
 149 .It Ic auth-group Aq Ar name
 150 Assigns previously defined authentication group to that target.
 151 By default, targets that do not specify their own auth settings,
 152 using clauses such as "chap" or "initiator-name", are assigned
 153 predefined auth-group "default", which denies all access.
 154 Another predefined auth-group, "no-authentication", may be used to permit access
 155 without authentication.
 156 .It Ic auth-type Ao Ar type Ac
 157 Specifies authentication type.
 158 Type can be either "none", "chap", or "chap-mutual".
 159 In most cases it is not neccessary to set the type using this clause;
 160 it is usually used to disable authentication for a given target.
 161 This clause is mutually exclusive with auth-group; one cannot use
 162 both in a single target.
 163 .It Ic chap Ao Ar user Ac Aq Ar secret
 164 Specifies CHAP authentication credentials.
 165 Note that targets must use either auth-group, or chap,
 166 or chap-mutual clauses; it's a configuration error to mix them in one target.
 167 .It Ic chap-mutual Ao Ar user Ac Ao Ar secret Ac Ao Ar mutualuser Ac Aq Ar mutualsecret
 168 Specifies mutual CHAP authentication credentials.
 169 Note that targets must use either auth-group, chap, or
 170 chap-mutual clauses; it's a configuration error to mix them in one target.
 171 .It Ic initiator-name Ao Ar initiator-name Ac
 172 Specifies iSCSI initiator name.
 173 If not defined, there will be no restrictions based on initiator
 174 name.
 175 Otherwise, only initiators with names matching one of defined
 176 ones will be allowed to connect.
 177 This clause is mutually exclusive with auth-group; one cannot use
 178 both in a single target.
 179 .It Ic initiator-portal Ao Ar address Ac
 180 Specifies iSCSI initiator portal - IPv4 or IPv6 address.
 181 If not defined, there will be no restrictions based on initiator
 182 address.
 183 Otherwise, only initiators with addresses matching one of defined
 184 ones will be allowed to connect.
 185 This clause is mutually exclusive with auth-group; one cannot use
 186 both in a single target.
 187 .It Ic portal-group Aq Ar name
 188 Assigns previously defined portal group to that target.
 189 Default portal group is "default", which makes the target available
 190 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
 191 .It Ic lun Aq Ar number
 192 Opens a lun configuration section, defining LUN exported by a target.
 193 .El
 194 .Ss lun level
 195 The following statements are available at the lun level:
 196 .Bl -tag -width indent
 197 .It Ic backend Ao Ar block | Ar ramdisk Ac
 198 Specifies the CTL backend to use for a given LUN.
 199 Valid choices are
 200 .Dq block
 201 and
 202 .Dq ramdisk ;
 203 block is used for LUNs backed
 204 by files in the filesystem; ramdisk is a bitsink device, used mostly for
 205 testing.
 206 The default backend is block.
 207 .It Ic blocksize Aq Ar size
 208 Specifies blocksize visible to the initiator.
 209 The default blocksize is 512.
 210 .It Ic device-id Aq Ar string
 211 Specifies SCSI Device Identification string presented to the initiator.
 212 .It Ic option Ao Ar name Ac Aq Ar value
 213 Specifies CTL-specific options passed to the kernel.
 214 .It Ic path Aq Ar path
 215 Specifies path to file used to back the LUN.
 216 .It Ic serial Aq Ar string
 217 Specifies SCSI serial number presented to the initiator.
 218 .It Ic size Aq Ar size
 219 Specifies LUN size, in bytes.
 220 .El
 221 .Sh FILES
 222 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
 223 .It Pa /etc/ctl.conf
 224 The default location of the
 225 .Xr ctld 8
 226 configuration file.
 227 .El
 228 .Sh EXAMPLES
 229 .Bd -literal
 230 pidfile /var/run/ctld.pid
 231
 232 auth-group example2 {
 233         chap-mutual "user" "secret" "mutualuser" "mutualsecret"
 234         chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
 235 }
 236
 237 portal-group example2 {
 238         discovery-auth-group no-authentication
 239         listen 127.0.0.1
 240         listen 0.0.0.0:3261
 241         listen [::]:3261
 242         listen [fe80::be:ef]
 243 }
 244
 245 target iqn.2012-06.com.example:target0 {
 246         alias "Testing target"
 247         auth-group no-authentication
 248         lun 0 {
 249                 path /dev/zvol/example_0
 250                 blocksize 4096
 251                 size 4G
 252         }
 253 }
 254
 255 target iqn.2012-06.com.example:target3 {
 256         chap chapuser chapsecret
 257         lun 0 {
 258                 path /dev/zvol/example_3
 259         }
 260 }
 261
 262 target iqn.2012-06.com.example:target2 {
 263         auth-group example2
 264         portal-group example2
 265         lun 0 {
 266                 path /dev/zvol/example2_0
 267         }
 268         lun 1 {
 269                 path /dev/zvol/example2_1
 270                 option foo bar
 271         }
 272 }
 273 .Ed
 274 .Sh SEE ALSO
 275 .Xr ctl 4 ,
 276 .Xr ctladm 8 ,
 277 .Xr ctld 8
 278 .Sh AUTHORS
 279 The
 280 .Nm
 281 configuration file functionality for
 282 .Xr ctld 8
 283 was developed by
 284 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org
 285 under sponsorship from the FreeBSD Foundation.