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
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
231 .It Ic option Ar name Ar value
232 The CTL-specific port options passed to the kernel.
233 .It Ic redirect Ar address
234 IPv4 or IPv6 address to redirect initiators to.
235 When configured, all initiators attempting to connect to portal
238 will get redirected using "Target moved temporarily" login response.
239 Redirection happens before authentication and any
245 Unique 16-bit tag value of this
247 If not specified, the value is generated automatically.
251 is listened by some other host.
252 This host will announce it on discovery stage, but won't listen.
254 The DiffServ Codepoint used for sending data. The DSCP can be
255 set to numeric, or hexadecimal values directly, as well as the
262 The 802.1Q Priority CodePoint used for sending packets.
263 The PCP can be set to a value in the range between
267 When omitted, the default for the outgoing interface is used.
270 .Bl -tag -width indent
272 Assign a human-readable description to the target.
274 .It Ic auth-group Ar name
275 Assign a previously defined authentication group to the target.
276 By default, targets that do not specify their own auth settings,
277 using clauses such as
285 which denies all access.
288 .Qq Ar no-authentication ,
289 may be used to permit access
290 without authentication.
291 Note that this clause can be overridden using the second argument
295 .It Ic auth-type Ar type
296 Sets the authentication type.
303 In most cases it is not necessary to set the type using this clause;
304 it is usually used to disable authentication for a given
306 This clause is mutually exclusive with
309 both in a single target.
310 .It Ic chap Ar user Ar secret
311 A set of CHAP authentication credentials.
312 Note that targets must only use one of
313 .Sy auth-group , chap , No or Sy chap-mutual ;
314 it is a configuration error to mix multiple types in one target.
315 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
316 A set of mutual CHAP authentication credentials.
317 Note that targets must only use one of
318 .Sy auth-group , chap , No or Sy chap-mutual ;
319 it is a configuration error to mix multiple types in one target.
320 .It Ic initiator-name Ar initiator-name
321 An iSCSI initiator name.
322 Only initiators with a name matching one of the defined
323 names will be allowed to connect.
324 If not defined, there will be no restrictions based on initiator
326 This clause is mutually exclusive with
329 both in a single target.
330 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
331 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
332 followed by a literal slash and a prefix length.
333 Only initiators with an address matching one of the defined
334 addresses will be allowed to connect.
335 If not defined, there will be no restrictions based on initiator
337 This clause is mutually exclusive with
340 both in a single target.
349 clauses in the target context provide an alternative to assigning an
351 defined separately, useful in the common case of authentication settings
352 specific to a single target.
353 .It Ic portal-group Ar name Op Ar ag-name
354 Assign a previously defined portal group to the target.
355 The default portal group is
357 which makes the target available
358 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
359 Optional second argument specifies
361 for connections to this specific portal group.
362 If second argument is not specified, target
366 .It Ic port Ar name/pp
367 .It Ic port Ar name/pp/vp
368 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
369 This is used to export the target through a specific physical - eg Fibre
370 Channel - port, in addition to portal-groups configured for the target.
372 .Cm "ctladm portlist"
373 command to retrieve the list of available ports.
376 configures LUN mapping and enables all assigned ports.
377 Each port can be assigned to only one target.
378 .It Ic redirect Ar address
379 IPv4 or IPv6 address to redirect initiators to.
380 When configured, all initiators attempting to connect to this target
381 will get redirected using "Target moved temporarily" login response.
382 Redirection happens after successful authentication.
383 .It Ic lun Ar number Ar name
384 Export previously defined
386 by the parent target.
390 configuration context, defining a LUN exported by the parent target.
392 This is an alternative to defining the LUN separately, useful in the common
393 case of a LUN being exported by a single target.
396 .Bl -tag -width indent
397 .It Ic backend Ar block No | Ar ramdisk
398 The CTL backend to use for a given LUN.
403 block is used for LUNs backed
404 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
406 The default backend is block.
407 .It Ic blocksize Ar size
408 The blocksize visible to the initiator.
409 The default blocksize is 512 for disks, and 2048 for CD/DVDs.
410 .It Ic ctl-lun Ar lun_id
411 Global numeric identifier to use for a given LUN inside CTL.
412 By default CTL allocates those IDs dynamically, but explicit specification
413 may be needed for consistency in HA configurations.
414 .It Ic device-id Ar string
415 The SCSI Device Identification string presented to the initiator.
416 .It Ic device-type Ar type
417 Specify the SCSI device type to use when creating the LUN.
418 Currently CTL supports Direct Access (type 0), Processor (type 3)
419 and CD/DVD (type 5) LUNs.
420 .It Ic option Ar name Ar value
421 The CTL-specific options passed to the kernel.
422 All CTL-specific options are documented in the
427 The path to the file, device node, or
429 volume used to back the LUN.
430 For optimal performance, create the volume with the
433 .It Ic serial Ar string
434 The SCSI serial number presented to the initiator.
436 The LUN size, in bytes or by number with a suffix of
438 (for kilobytes, megabytes, gigabytes, or terabytes).
439 When the configuration is in UCL format, use the suffix format
440 .Sy kKmMgG Ns | Ns Sy bB ,
441 (i.e., 4GB, 4gb, and 4Gb are all equivalent).
444 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
446 The default location of the
453 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
454 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
455 initiator-portal 192.168.1.1/16
460 initiator-name "iqn.2012-06.com.example:initiatorhost1"
461 initiator-name "iqn.2012-06.com.example:initiatorhost2"
462 initiator-portal 192.168.1.1/24
463 initiator-portal [2001:db8::de:ef]
467 discovery-auth-group no-authentication
470 listen [fe80::be:ef]:3261
473 target iqn.2012-06.com.example:target0 {
474 alias "Example target"
475 auth-group no-authentication
477 path /dev/zvol/tank/example_0
484 path /dev/zvol/tank/example_1
485 option naa 0x50015178f369f093
488 target iqn.2012-06.com.example:target1 {
493 path /dev/zvol/tank/example_2
494 option vendor "FreeBSD"
498 target naa.50015178f369f092 {
505 An equivalent configuration in UCL format, for use with
513 secret = "secretsecret"
514 mutual-user = "mutualuser"
515 mutual-secret = "mutualsecret"
519 secret = "secret2secret2"
520 mutual-user = "mutualuser"
521 mutual-secret = "mutualsecret"
529 "iqn.2012-06.com.example:initiatorhost1",
530 "iqn.2012-06.com.example:initiatorhost2"
532 initiator-portal = [192.168.1.1/24, "[2001:db8::de:ef]"]
538 discovery-auth-group = no-authentication
549 path = /dev/zvol/tank/example_0
555 path = /dev/zvol/tank/example_1
557 naa = "0x50015178f369f093"
562 path = /dev/zvol/tank/example_2
570 "iqn.2012-06.com.example:target0" {
571 alias = "Example target"
572 auth-group = no-authentication
574 { number = 0, name = example_0 },
578 "iqn.2012-06.com.example:target1" {
580 portal-group { name = pg0 }
582 { number = 0, name = example_1 },
583 { number = 1, name = example_2 }
587 naa.50015178f369f092 {
590 { number = 0, name = example_1 }
603 configuration file functionality for
606 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
607 under sponsorship from the FreeBSD Foundation.