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
31 .Dd September 27, 2015
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 redirect Aq Ar address
233 IPv4 or IPv6 address to redirect initiators to.
234 When configured, all initiators attempting to connect to portal
237 will get redirected using "Target moved temporarily" login response.
238 Redirection happens before authentication and any
244 Unique 16-bit tag value of this
246 If not specified, the value is generated automatically.
250 is listened by some other host.
251 This host will announce it on discovery stage, but won't listen.
254 .Bl -tag -width indent
256 Assign a human-readable description to the target.
258 .It Ic auth-group Ar name
259 Assign a previously defined authentication group to the target.
260 By default, targets that do not specify their own auth settings,
261 using clauses such as
269 which denies all access.
272 .Qq Ar no-authentication ,
273 may be used to permit access
274 without authentication.
275 Note that targets must only use one of
276 .Sy auth-group , chap , No or Sy chap-mutual ;
277 it is a configuration error to mix multiple types in one target.
278 .It Ic auth-type Ar type
279 Sets the authentication type.
286 In most cases it is not necessary to set the type using this clause;
287 it is usually used to disable authentication for a given
289 This clause is mutually exclusive with
292 both in a single target.
293 .It Ic chap Ar user Ar secret
294 A set of CHAP authentication credentials.
295 Note that targets must only use one of
296 .Sy auth-group , chap , No or Sy chap-mutual ;
297 it is a configuration error to mix multiple types in one target.
298 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
299 A set of mutual CHAP authentication credentials.
300 Note that targets must only use one of
301 .Sy auth-group , chap , No or Sy chap-mutual ;
302 it is a configuration error to mix multiple types in one target.
303 .It Ic initiator-name Ar initiator-name
304 An iSCSI initiator name.
305 Only initiators with a name matching one of the defined
306 names will be allowed to connect.
307 If not defined, there will be no restrictions based on initiator
309 This clause is mutually exclusive with
312 both in a single target.
313 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
314 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
315 followed by a literal slash and a prefix length.
316 Only initiators with an address matching one of the defined
317 addresses will be allowed to connect.
318 If not defined, there will be no restrictions based on initiator
320 This clause is mutually exclusive with
323 both in a single target.
324 .It Ic portal-group Ar name Op Ar agname
325 Assign a previously defined portal group to the target.
326 The default portal group is
328 which makes the target available
329 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
330 Optional second argument specifies auth group name for connections
331 to this specific portal group.
332 If second argument is not specified, target auth group is used.
334 .It Ic port Ar name/pp
335 .It Ic port Ar name/pp/vp
336 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
337 On startup ctld configures LUN mapping and enables all assigned ports.
338 Each port can be assigned to only one target.
339 .It Ic redirect Aq Ar address
340 IPv4 or IPv6 address to redirect initiators to.
341 When configured, all initiators attempting to connect to this target
342 will get redirected using "Target moved temporarily" login response.
343 Redirection happens after successful authentication.
344 .It Ic lun Ar number Ar name
345 Export previously defined
347 by the parent target.
351 configuration context, defining a LUN exported by the parent target.
354 .Bl -tag -width indent
355 .It Ic backend Ar block No | Ar ramdisk
356 The CTL backend to use for a given LUN.
361 block is used for LUNs backed
362 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
364 The default backend is block.
365 .It Ic blocksize Ar size
366 The blocksize visible to the initiator.
367 The default blocksize is 512 for disks, and 2048 for CD/DVDs.
368 .It Ic ctl-lun Ar lun_id
369 Global numeric identifier to use for a given LUN inside CTL.
370 By default CTL allocates those IDs dynamically, but explicit specification
371 may be needed for consistency in HA configurations.
372 .It Ic device-id Ar string
373 The SCSI Device Identification string presented to the initiator.
374 .It Ic device-type Ar type
375 Specify the SCSI device type to use when creating the LUN.
376 Currently CTL supports Direct Access (type 0), Processor (type 3)
377 and CD/DVD (type 5) LUNs.
378 .It Ic option Ar name Ar value
379 The CTL-specific options passed to the kernel.
380 All CTL-specific options are documented in the
385 The path to the file, device node, or
387 volume used to back the LUN.
388 For optimal performance, create the volume with the
391 .It Ic serial Ar string
392 The SCSI serial number presented to the initiator.
394 The LUN size, in bytes.
397 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
399 The default location of the
406 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
407 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
412 initiator-name "iqn.2012-06.com.example:initiatorhost1"
413 initiator-name "iqn.2012-06.com.example:initiatorhost2"
414 initiator-portal 192.168.1.1/24
415 initiator-portal [2001:db8::de:ef]
419 discovery-auth-group no-authentication
422 listen [fe80::be:ef]:3261
425 target iqn.2012-06.com.example:target0 {
426 alias "Example target"
427 auth-group no-authentication
429 path /dev/zvol/tank/example_0
436 path /dev/zvol/tank/example_1
437 option naa 0x50015178f369f093
440 target iqn.2012-06.com.example:target1 {
445 path /dev/zvol/tank/example_2
450 target naa.50015178f369f092 {
464 configuration file functionality for
467 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org
468 under sponsorship from the FreeBSD Foundation.