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
65 .Dl auth-group Ar name
66 .Dl portal-group Ar name
67 .Dl lun Ar number No {
74 .Bl -tag -width indent
75 .It Ic auth-group Ar name
78 configuration context,
79 defining a new auth-group,
80 which can then be assigned to any number of targets.
82 The debug verbosity level.
84 .It Ic maxproc Ar number
85 The limit for concurrently running child processes handling
88 A setting of 0 disables the limit.
89 .It Ic pidfile Ar path
90 The path to the pidfile.
92 .Pa /var/run/ctld.pid .
93 .It Ic portal-group Ar name
96 configuration context,
97 defining a new portal-group,
98 which can then be assigned to any number of targets.
102 configuration context, defining a LUN to be exported by any number of targets.
103 .It Ic target Ar name
106 configuration context, which can optionally contain one or more
109 .It Ic timeout Ar seconds
110 The timeout for login sessions, after which the connection
111 will be forcibly terminated.
113 A setting of 0 disables the timeout.
114 .It Ic isns-server Ar address
115 An IPv4 or IPv6 address and optionally port of iSNS server to register on.
116 .It Ic isns-period Ar seconds
117 iSNS registration period.
118 Registered Network Entity not updated during this period will be unregistered.
120 .It Ic isns-timeout Ar seconds
121 Timeout for iSNS requests.
124 .Ss auth-group Context
125 .Bl -tag -width indent
126 .It Ic auth-type Ar type
127 Sets the authentication type.
134 In most cases it is not necessary to set the type using this clause;
135 it is usually used to disable authentication for a given
137 .It Ic chap Ar user Ar secret
138 A set of CHAP authentication credentials.
141 the configuration may only contain either
145 entries; it is an error to mix them.
146 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
147 A set of mutual CHAP authentication credentials.
150 the configuration may only contain either
154 entries; it is an error to mix them.
155 .It Ic initiator-name Ar initiator-name
156 An iSCSI initiator name.
157 Only initiators with a name matching one of the defined
158 names will be allowed to connect.
159 If not defined, there will be no restrictions based on initiator
161 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
162 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
163 followed by a literal slash and a prefix length.
164 Only initiators with an address matching one of the defined
165 addresses will be allowed to connect.
166 If not defined, there will be no restrictions based on initiator
169 .Ss portal-group Context
170 .Bl -tag -width indent
171 .It Ic discovery-auth-group Ar name
172 Assign a previously defined authentication group to the portal group,
173 to be used for target discovery.
174 By default, portal groups are assigned predefined
177 which denies discovery.
180 .Qq Ar no-authentication ,
182 to permit discovery without authentication.
183 .It Ic discovery-filter Ar filter
184 Determines which targets are returned during discovery.
190 .Qq Ar portal-name-auth .
193 discovery will return all targets assigned to that portal group.
196 discovery will not return targets that cannot be accessed by the
197 initiator because of their
198 .Sy initiator-portal .
201 the check will include both
206 .Qq Ar portal-name-auth ,
207 the check will include
208 .Sy initiator-portal ,
210 and authentication credentials.
211 The target is returned if it does not require CHAP authentication,
212 or if the CHAP user and secret used during discovery match those
215 .Qq Ar portal-name-auth ,
216 targets that require CHAP authentication will only be returned if
217 .Sy discovery-auth-group
221 .It Ic listen Ar address
222 An IPv4 or IPv6 address and port to listen on for incoming connections.
223 .\".It Ic listen-iser Ar address
224 .\"An IPv4 or IPv6 address and port to listen on for incoming connections
225 .\"using iSER (iSCSI over RDMA) protocol.
226 .It Ic offload Ar driver
227 Define iSCSI hardware offload driver to use for this
229 .It Ic redirect Ar address
230 IPv4 or IPv6 address to redirect initiators to.
231 When configured, all initiators attempting to connect to portal
234 will get redirected using "Target moved temporarily" login response.
235 Redirection happens before authentication and any
241 Unique 16-bit tag value of this
243 If not specified, the value is generated automatically.
247 is listened by some other host.
248 This host will announce it on discovery stage, but won't listen.
251 .Bl -tag -width indent
253 Assign a human-readable description to the target.
255 .It Ic auth-group Ar name
256 Assign a previously defined authentication group to the target.
257 By default, targets that do not specify their own auth settings,
258 using clauses such as
266 which denies all access.
269 .Qq Ar no-authentication ,
270 may be used to permit access
271 without authentication.
272 Note that this clause can be overridden using the second argument
276 .It Ic auth-type Ar type
277 Sets the authentication type.
284 In most cases it is not necessary to set the type using this clause;
285 it is usually used to disable authentication for a given
287 This clause is mutually exclusive with
290 both in a single target.
291 .It Ic chap Ar user Ar secret
292 A set of CHAP authentication credentials.
293 Note that targets must only use one of
294 .Sy auth-group , chap , No or Sy chap-mutual ;
295 it is a configuration error to mix multiple types in one target.
296 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
297 A set of mutual CHAP authentication credentials.
298 Note that targets must only use one of
299 .Sy auth-group , chap , No or Sy chap-mutual ;
300 it is a configuration error to mix multiple types in one target.
301 .It Ic initiator-name Ar initiator-name
302 An iSCSI initiator name.
303 Only initiators with a name matching one of the defined
304 names will be allowed to connect.
305 If not defined, there will be no restrictions based on initiator
307 This clause is mutually exclusive with
310 both in a single target.
311 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
312 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
313 followed by a literal slash and a prefix length.
314 Only initiators with an address matching one of the defined
315 addresses will be allowed to connect.
316 If not defined, there will be no restrictions based on initiator
318 This clause is mutually exclusive with
321 both in a single target.
330 clauses in the target context provide an alternative to assigning an
332 defined separately, useful in the common case of authentication settings
333 specific to a single target.
334 .It Ic portal-group Ar name Op Ar ag-name
335 Assign a previously defined portal group to the target.
336 The default portal group is
338 which makes the target available
339 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
340 Optional second argument specifies
342 for connections to this specific portal group.
343 If second argument is not specified, target
347 .It Ic port Ar name/pp
348 .It Ic port Ar name/pp/vp
349 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
350 This is used to export the target through a specific physical - eg Fibre
351 Channel - port, in addition to portal-groups configured for the target.
353 .Cm "ctladm portlist"
354 command to retrieve the list of available ports.
357 configures LUN mapping and enables all assigned ports.
358 Each port can be assigned to only one target.
359 .It Ic redirect Ar address
360 IPv4 or IPv6 address to redirect initiators to.
361 When configured, all initiators attempting to connect to this target
362 will get redirected using "Target moved temporarily" login response.
363 Redirection happens after successful authentication.
364 .It Ic lun Ar number Ar name
365 Export previously defined
367 by the parent target.
371 configuration context, defining a LUN exported by the parent target.
373 This is an alternative to defining the LUN separately, useful in the common
374 case of a LUN being exported by a single target.
377 .Bl -tag -width indent
378 .It Ic backend Ar block No | Ar ramdisk
379 The CTL backend to use for a given LUN.
384 block is used for LUNs backed
385 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
387 The default backend is block.
388 .It Ic blocksize Ar size
389 The blocksize visible to the initiator.
390 The default blocksize is 512 for disks, and 2048 for CD/DVDs.
391 .It Ic ctl-lun Ar lun_id
392 Global numeric identifier to use for a given LUN inside CTL.
393 By default CTL allocates those IDs dynamically, but explicit specification
394 may be needed for consistency in HA configurations.
395 .It Ic device-id Ar string
396 The SCSI Device Identification string presented to the initiator.
397 .It Ic device-type Ar type
398 Specify the SCSI device type to use when creating the LUN.
399 Currently CTL supports Direct Access (type 0), Processor (type 3)
400 and CD/DVD (type 5) LUNs.
401 .It Ic option Ar name Ar value
402 The CTL-specific options passed to the kernel.
403 All CTL-specific options are documented in the
408 The path to the file, device node, or
410 volume used to back the LUN.
411 For optimal performance, create the volume with the
414 .It Ic serial Ar string
415 The SCSI serial number presented to the initiator.
417 The LUN size, in bytes.
420 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
422 The default location of the
429 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
430 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
431 initiator-portal 192.168.1.1/16
436 initiator-name "iqn.2012-06.com.example:initiatorhost1"
437 initiator-name "iqn.2012-06.com.example:initiatorhost2"
438 initiator-portal 192.168.1.1/24
439 initiator-portal [2001:db8::de:ef]
443 discovery-auth-group no-authentication
446 listen [fe80::be:ef]:3261
449 target iqn.2012-06.com.example:target0 {
450 alias "Example target"
451 auth-group no-authentication
453 path /dev/zvol/tank/example_0
460 path /dev/zvol/tank/example_1
461 option naa 0x50015178f369f093
464 target iqn.2012-06.com.example:target1 {
469 path /dev/zvol/tank/example_2
470 option vendor "FreeBSD"
474 target naa.50015178f369f092 {
488 configuration file functionality for
491 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
492 under sponsorship from the FreeBSD Foundation.