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
263 .Bl -tag -width indent
265 Assign a human-readable description to the target.
267 .It Ic auth-group Ar name
268 Assign a previously defined authentication group to the target.
269 By default, targets that do not specify their own auth settings,
270 using clauses such as
278 which denies all access.
281 .Qq Ar no-authentication ,
282 may be used to permit access
283 without authentication.
284 Note that this clause can be overridden using the second argument
288 .It Ic auth-type Ar type
289 Sets the authentication type.
296 In most cases it is not necessary to set the type using this clause;
297 it is usually used to disable authentication for a given
299 This clause is mutually exclusive with
302 both in a single target.
303 .It Ic chap Ar user Ar secret
304 A set of CHAP authentication credentials.
305 Note that targets must only use one of
306 .Sy auth-group , chap , No or Sy chap-mutual ;
307 it is a configuration error to mix multiple types in one target.
308 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
309 A set of mutual CHAP authentication credentials.
310 Note that targets must only use one of
311 .Sy auth-group , chap , No or Sy chap-mutual ;
312 it is a configuration error to mix multiple types in one target.
313 .It Ic initiator-name Ar initiator-name
314 An iSCSI initiator name.
315 Only initiators with a name matching one of the defined
316 names will be allowed to connect.
317 If not defined, there will be no restrictions based on initiator
319 This clause is mutually exclusive with
322 both in a single target.
323 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
324 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
325 followed by a literal slash and a prefix length.
326 Only initiators with an address matching one of the defined
327 addresses will be allowed to connect.
328 If not defined, there will be no restrictions based on initiator
330 This clause is mutually exclusive with
333 both in a single target.
342 clauses in the target context provide an alternative to assigning an
344 defined separately, useful in the common case of authentication settings
345 specific to a single target.
346 .It Ic portal-group Ar name Op Ar ag-name
347 Assign a previously defined portal group to the target.
348 The default portal group is
350 which makes the target available
351 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
352 Optional second argument specifies
354 for connections to this specific portal group.
355 If second argument is not specified, target
359 .It Ic port Ar name/pp
360 .It Ic port Ar name/pp/vp
361 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
362 This is used to export the target through a specific physical - eg Fibre
363 Channel - port, in addition to portal-groups configured for the target.
365 .Cm "ctladm portlist"
366 command to retrieve the list of available ports.
369 configures LUN mapping and enables all assigned ports.
370 Each port can be assigned to only one target.
371 .It Ic redirect Ar address
372 IPv4 or IPv6 address to redirect initiators to.
373 When configured, all initiators attempting to connect to this target
374 will get redirected using "Target moved temporarily" login response.
375 Redirection happens after successful authentication.
376 .It Ic lun Ar number Ar name
377 Export previously defined
379 by the parent target.
383 configuration context, defining a LUN exported by the parent target.
385 This is an alternative to defining the LUN separately, useful in the common
386 case of a LUN being exported by a single target.
389 .Bl -tag -width indent
390 .It Ic backend Ar block No | Ar ramdisk
391 The CTL backend to use for a given LUN.
396 block is used for LUNs backed
397 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
399 The default backend is block.
400 .It Ic blocksize Ar size
401 The blocksize visible to the initiator.
402 The default blocksize is 512 for disks, and 2048 for CD/DVDs.
403 .It Ic ctl-lun Ar lun_id
404 Global numeric identifier to use for a given LUN inside CTL.
405 By default CTL allocates those IDs dynamically, but explicit specification
406 may be needed for consistency in HA configurations.
407 .It Ic device-id Ar string
408 The SCSI Device Identification string presented to the initiator.
409 .It Ic device-type Ar type
410 Specify the SCSI device type to use when creating the LUN.
411 Currently CTL supports Direct Access (type 0), Processor (type 3)
412 and CD/DVD (type 5) LUNs.
413 .It Ic option Ar name Ar value
414 The CTL-specific options passed to the kernel.
415 All CTL-specific options are documented in the
420 The path to the file, device node, or
422 volume used to back the LUN.
423 For optimal performance, create the volume with the
426 .It Ic serial Ar string
427 The SCSI serial number presented to the initiator.
429 The LUN size, in bytes or by number with a suffix of
431 (for kilobytes, megabytes, gigabytes, or terabytes).
432 When the configuration is in UCL format, use the suffix format
433 .Sy kKmMgG Ns | Ns Sy bB ,
434 (i.e., 4GB, 4gb, and 4Gb are all equivalent).
437 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
439 The default location of the
446 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
447 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
448 initiator-portal 192.168.1.1/16
453 initiator-name "iqn.2012-06.com.example:initiatorhost1"
454 initiator-name "iqn.2012-06.com.example:initiatorhost2"
455 initiator-portal 192.168.1.1/24
456 initiator-portal [2001:db8::de:ef]
460 discovery-auth-group no-authentication
463 listen [fe80::be:ef]:3261
466 target iqn.2012-06.com.example:target0 {
467 alias "Example target"
468 auth-group no-authentication
470 path /dev/zvol/tank/example_0
477 path /dev/zvol/tank/example_1
478 option naa 0x50015178f369f093
481 target iqn.2012-06.com.example:target1 {
486 path /dev/zvol/tank/example_2
487 option vendor "FreeBSD"
491 target naa.50015178f369f092 {
498 An equivalent configuration in UCL format, for use with
506 secret = "secretsecret"
507 mutual-user = "mutualuser"
508 mutual-secret = "mutualsecret"
512 secret = "secret2secret2"
513 mutual-user = "mutualuser"
514 mutual-secret = "mutualsecret"
522 "iqn.2012-06.com.example:initiatorhost1",
523 "iqn.2012-06.com.example:initiatorhost2"
525 initiator-portal = [192.168.1.1/24, "[2001:db8::de:ef]"]
531 discovery-auth-group = no-authentication
542 path = /dev/zvol/tank/example_0
548 path = /dev/zvol/tank/example_1
550 naa = "0x50015178f369f093"
555 path = /dev/zvol/tank/example_2
563 "iqn.2012-06.com.example:target0" {
564 alias = "Example target"
565 auth-group = no-authentication
567 { number = 0, name = example_0 },
571 "iqn.2012-06.com.example:target1" {
573 portal-group { name = pg0 }
575 { number = 0, name = example_1 },
576 { number = 1, name = example_2 }
580 naa.50015178f369f092 {
583 { number = 0, name = example_1 }
596 configuration file functionality for
599 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
600 under sponsorship from the FreeBSD Foundation.