1 .\" Copyright (c) 2012 The FreeBSD Foundation
2 .\" Copyright (c) 2015 Alexander Motin <mav@FreeBSD.org>
3 .\" All rights reserved.
5 .\" This software was developed by Edward Tomasz Napierala under sponsorship
6 .\" from the FreeBSD Foundation.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .Nd CAM Target Layer / iSCSI target daemon configuration file
40 configuration file is used by the
45 are interpreted as comments.
46 The general syntax of the
49 .Bd -literal -offset indent
52 .No auth-group Ar name No {
53 .Dl chap Ar user Ar secret
57 .No portal-group Ar name No {
59 .\".Dl listen-iser Ar address
60 .Dl discovery-auth-group Ar name
69 .Dl auth-group Ar name
70 .Dl portal-group Ar name Op Ar agname
72 .Dl lun Ar number Ar name
73 .Dl lun Ar number No {
80 .Bl -tag -width indent
81 .It Ic auth-group Ar name
84 configuration context,
85 defining a new auth-group,
86 which can then be assigned to any number of targets.
88 The debug verbosity level.
90 .It Ic maxproc Ar number
91 The limit for concurrently running child processes handling
94 A setting of 0 disables the limit.
95 .It Ic pidfile Ar path
96 The path to the pidfile.
98 .Pa /var/run/ctld.pid .
99 .It Ic portal-group Ar name
102 configuration context,
103 defining a new portal-group,
104 which can then be assigned to any number of targets.
108 configuration context, defining a LUN to be exported by some target(s).
109 .It Ic target Ar name
112 configuration context, which can contain one or more
115 .It Ic timeout Ar seconds
116 The timeout for login sessions, after which the connection
117 will be forcibly terminated.
119 A setting of 0 disables the timeout.
120 .It Ic isns-server Ar address
121 An IPv4 or IPv6 address and optionally port of iSNS server to register on.
122 .It Ic isns-period Ar seconds
123 iSNS registration period.
124 Registered Network Entity not updated during this period will be unregistered.
126 .It Ic isns-timeout Ar seconds
127 Timeout for iSNS requests.
130 .Ss auth-group Context
131 .Bl -tag -width indent
132 .It Ic auth-type Ar type
133 Sets the authentication type.
140 In most cases it is not necessary to set the type using this clause;
141 it is usually used to disable authentication for a given
143 .It Ic chap Ar user Ar secret
144 A set of CHAP authentication credentials.
147 the configuration may only contain either
151 entries; it is an error to mix them.
152 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
153 A set of mutual CHAP authentication credentials.
156 the configuration may only contain either
160 entries; it is an error to mix them.
161 .It Ic initiator-name Ar initiator-name
162 An iSCSI initiator name.
163 Only initiators with a name matching one of the defined
164 names will be allowed to connect.
165 If not defined, there will be no restrictions based on initiator
167 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
168 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
169 followed by a literal slash and a prefix length.
170 Only initiators with an address matching one of the defined
171 addresses will be allowed to connect.
172 If not defined, there will be no restrictions based on initiator
175 .Ss portal-group Context
176 .Bl -tag -width indent
177 .It Ic discovery-auth-group Ar name
178 Assign a previously defined authentication group to the portal group,
179 to be used for target discovery.
180 By default, portal groups are assigned predefined
183 which denies discovery.
186 .Qq Ar no-authentication ,
188 to permit discovery without authentication.
189 .It Ic discovery-filter Ar filter
190 Determines which targets are returned during discovery.
196 .Qq Ar portal-name-auth .
199 discovery will return all targets assigned to that portal group.
202 discovery will not return targets that cannot be accessed by the
203 initiator because of their
204 .Sy initiator-portal .
207 the check will include both
212 .Qq Ar portal-name-auth ,
213 the check will include
214 .Sy initiator-portal ,
216 and authentication credentials.
217 The target is returned if it does not require CHAP authentication,
218 or if the CHAP user and secret used during discovery match those
221 .Qq Ar portal-name-auth ,
222 targets that require CHAP authentication will only be returned if
223 .Sy discovery-auth-group
227 .It Ic listen Ar address
228 An IPv4 or IPv6 address and port to listen on for incoming connections.
229 .\".It Ic listen-iser Ar address
230 .\"An IPv4 or IPv6 address and port to listen on for incoming connections
231 .\"using iSER (iSCSI over RDMA) protocol.
232 .It Ic option Ar name Ar value
233 The CTL-specific port options passed to the kernel.
234 .It Ic redirect Ar address
235 IPv4 or IPv6 address to redirect initiators to.
236 When configured, all initiators attempting to connect to portal
239 will get redirected using "Target moved temporarily" login response.
240 Redirection happens before authentication and any
246 Unique 16-bit tag value of this
248 If not specified, the value is generated automatically.
252 is listened by some other host.
253 This host will announce it on discovery stage, but won't listen.
256 .Bl -tag -width indent
258 Assign a human-readable description to the target.
260 .It Ic auth-group Ar name
261 Assign a previously defined authentication group to the target.
262 By default, targets that do not specify their own auth settings,
263 using clauses such as
271 which denies all access.
274 .Qq Ar no-authentication ,
275 may be used to permit access
276 without authentication.
277 Note that targets must only use one of
278 .Sy auth-group , chap , No or Sy chap-mutual ;
279 it is a configuration error to mix multiple types in one target.
280 .It Ic auth-type Ar type
281 Sets the authentication type.
288 In most cases it is not necessary to set the type using this clause;
289 it is usually used to disable authentication for a given
291 This clause is mutually exclusive with
294 both in a single target.
295 .It Ic chap Ar user Ar secret
296 A set of CHAP authentication credentials.
297 Note that targets must only use one of
298 .Sy auth-group , chap , No or Sy chap-mutual ;
299 it is a configuration error to mix multiple types in one target.
300 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
301 A set of mutual CHAP authentication credentials.
302 Note that targets must only use one of
303 .Sy auth-group , chap , No or Sy chap-mutual ;
304 it is a configuration error to mix multiple types in one target.
305 .It Ic initiator-name Ar initiator-name
306 An iSCSI initiator name.
307 Only initiators with a name matching one of the defined
308 names will be allowed to connect.
309 If not defined, there will be no restrictions based on initiator
311 This clause is mutually exclusive with
314 both in a single target.
315 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
316 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
317 followed by a literal slash and a prefix length.
318 Only initiators with an address matching one of the defined
319 addresses will be allowed to connect.
320 If not defined, there will be no restrictions based on initiator
322 This clause is mutually exclusive with
325 both in a single target.
326 .It Ic portal-group Ar name Op Ar agname
327 Assign a previously defined portal group to the target.
328 The default portal group is
330 which makes the target available
331 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
332 Optional second argument specifies auth group name for connections
333 to this specific portal group.
334 If second argument is not specified, target auth group is used.
336 .It Ic port Ar name/pp
337 .It Ic port Ar name/pp/vp
338 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
339 On startup ctld configures LUN mapping and enables all assigned ports.
340 Each port can be assigned to only one target.
341 .It Ic redirect Aq Ar address
342 IPv4 or IPv6 address to redirect initiators to.
343 When configured, all initiators attempting to connect to this target
344 will get redirected using "Target moved temporarily" login response.
345 Redirection happens after successful authentication.
346 .It Ic lun Ar number Ar name
347 Export previously defined
349 by the parent target.
353 configuration context, defining a LUN exported by the parent target.
356 .Bl -tag -width indent
357 .It Ic backend Ar block No | Ar ramdisk
358 The CTL backend to use for a given LUN.
363 block is used for LUNs backed
364 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
366 The default backend is block.
367 .It Ic blocksize Ar size
368 The blocksize visible to the initiator.
369 The default blocksize is 512 for disks, and 2048 for CD/DVDs.
370 .It Ic ctl-lun Ar lun_id
371 Global numeric identifier to use for a given LUN inside CTL.
372 By default CTL allocates those IDs dynamically, but explicit specification
373 may be needed for consistency in HA configurations.
374 .It Ic device-id Ar string
375 The SCSI Device Identification string presented to the initiator.
376 .It Ic device-type Ar type
377 Specify the SCSI device type to use when creating the LUN.
378 Currently CTL supports Direct Access (type 0), Processor (type 3)
379 and CD/DVD (type 5) LUNs.
380 .It Ic option Ar name Ar value
381 The CTL-specific options passed to the kernel.
382 All CTL-specific options are documented in the
387 The path to the file, device node, or
389 volume used to back the LUN.
390 For optimal performance, create the volume with the
393 .It Ic serial Ar string
394 The SCSI serial number presented to the initiator.
396 The LUN size, in bytes.
399 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
401 The default location of the
408 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
409 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
414 initiator-name "iqn.2012-06.com.example:initiatorhost1"
415 initiator-name "iqn.2012-06.com.example:initiatorhost2"
416 initiator-portal 192.168.1.1/24
417 initiator-portal [2001:db8::de:ef]
421 discovery-auth-group no-authentication
424 listen [fe80::be:ef]:3261
427 target iqn.2012-06.com.example:target0 {
428 alias "Example target"
429 auth-group no-authentication
431 path /dev/zvol/tank/example_0
438 path /dev/zvol/tank/example_1
439 option naa 0x50015178f369f093
442 target iqn.2012-06.com.example:target1 {
447 path /dev/zvol/tank/example_2
452 target naa.50015178f369f092 {
466 configuration file functionality for
469 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org
470 under sponsorship from the FreeBSD Foundation.