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