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
34 .Nd CAM Target Layer / iSCSI target daemon configuration file
38 configuration file is used by the
43 are interpreted as comments.
44 The general syntax of the
47 .Bd -literal -offset indent
50 .No auth-group Ar name No {
51 .Dl chap Ar user Ar secret
55 .No portal-group Ar name No {
57 .\".Dl listen-iser Ar address
58 .Dl discovery-auth-group Ar name
63 .Dl auth-group Ar name
64 .Dl portal-group Ar name
65 .Dl lun Ar number No {
72 .Bl -tag -width indent
73 .It Ic auth-group Ar name
76 configuration context,
77 defining a new auth-group,
78 which can then be assigned to any number of targets.
80 The debug verbosity level.
82 .It Ic maxproc Ar number
83 The limit for concurrently running child processes handling
86 A setting of 0 disables the limit.
87 .It Ic pidfile Ar path
88 The path to the pidfile.
90 .Pa /var/run/ctld.pid .
91 .It Ic portal-group Ar name
94 configuration context,
95 defining a new portal-group,
96 which can then be assigned to any number of targets.
100 configuration context, defining a LUN to be exported by any number of targets.
101 .It Ic target Ar name
104 configuration context, which can optionally contain one or more
107 .It Ic timeout Ar seconds
108 The timeout for login sessions, after which the connection
109 will be forcibly terminated.
111 A setting of 0 disables the timeout.
112 .It Ic isns-server Ar address
113 An IPv4 or IPv6 address and optionally port of iSNS server to register on.
114 .It Ic isns-period Ar seconds
115 iSNS registration period.
116 Registered Network Entity not updated during this period will be unregistered.
118 .It Ic isns-timeout Ar seconds
119 Timeout for iSNS requests.
122 .Ss auth-group Context
123 .Bl -tag -width indent
124 .It Ic auth-type Ar type
125 Sets the authentication type.
132 In most cases it is not necessary to set the type using this clause;
133 it is usually used to disable authentication for a given
135 .It Ic chap Ar user Ar secret
136 A set of CHAP authentication credentials.
139 the configuration may only contain either
143 entries; it is an error to mix them.
144 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
145 A set of mutual CHAP authentication credentials.
148 the configuration may only contain either
152 entries; it is an error to mix them.
153 .It Ic initiator-name Ar initiator-name
154 An iSCSI initiator name.
155 Only initiators with a name matching one of the defined
156 names will be allowed to connect.
157 If not defined, there will be no restrictions based on initiator
159 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
160 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
161 followed by a literal slash and a prefix length.
162 Only initiators with an address matching one of the defined
163 addresses will be allowed to connect.
164 If not defined, there will be no restrictions based on initiator
167 .Ss portal-group Context
168 .Bl -tag -width indent
169 .It Ic discovery-auth-group Ar name
170 Assign a previously defined authentication group to the portal group,
171 to be used for target discovery.
172 By default, portal groups are assigned predefined
175 which denies discovery.
178 .Qq Ar no-authentication ,
180 to permit discovery without authentication.
181 .It Ic discovery-filter Ar filter
182 Determines which targets are returned during discovery.
188 .Qq Ar portal-name-auth .
191 discovery will return all targets assigned to that portal group.
194 discovery will not return targets that cannot be accessed by the
195 initiator because of their
196 .Sy initiator-portal .
199 the check will include both
204 .Qq Ar portal-name-auth ,
205 the check will include
206 .Sy initiator-portal ,
208 and authentication credentials.
209 The target is returned if it does not require CHAP authentication,
210 or if the CHAP user and secret used during discovery match those
213 .Qq Ar portal-name-auth ,
214 targets that require CHAP authentication will only be returned if
215 .Sy discovery-auth-group
219 .It Ic listen Ar address
220 An IPv4 or IPv6 address and port to listen on for incoming connections.
221 .\".It Ic listen-iser Ar address
222 .\"An IPv4 or IPv6 address and port to listen on for incoming connections
223 .\"using iSER (iSCSI over RDMA) protocol.
224 .It Ic offload Ar driver
225 Define iSCSI hardware offload driver to use for this
229 .It Ic option Ar name Ar value
230 The CTL-specific port options passed to the kernel.
231 .It Ic redirect Ar address
232 IPv4 or IPv6 address to redirect initiators to.
233 When configured, all initiators attempting to connect to portal
236 will get redirected using "Target moved temporarily" login response.
237 Redirection happens before authentication and any
243 Unique 16-bit tag value of this
245 If not specified, the value is generated automatically.
249 is listened by some other host.
250 This host will announce it on discovery stage, but won't listen.
252 The DiffServ Codepoint used for sending data. The DSCP can be
253 set to numeric, or hexadecimal values directly, as well as the
260 The 802.1Q Priority CodePoint used for sending packets.
261 The PCP can be set to a value in the range between
265 When omitted, the default for the outgoing interface is used.
268 .Bl -tag -width indent
270 Assign a human-readable description to the target.
272 .It Ic auth-group Ar name
273 Assign a previously defined authentication group to the target.
274 By default, targets that do not specify their own auth settings,
275 using clauses such as
283 which denies all access.
286 .Qq Ar no-authentication ,
287 may be used to permit access
288 without authentication.
289 Note that this clause can be overridden using the second argument
293 .It Ic auth-type Ar type
294 Sets the authentication type.
301 In most cases it is not necessary to set the type using this clause;
302 it is usually used to disable authentication for a given
304 This clause is mutually exclusive with
307 both in a single target.
308 .It Ic chap Ar user Ar secret
309 A set of 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 chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
314 A set of mutual CHAP authentication credentials.
315 Note that targets must only use one of
316 .Sy auth-group , chap , No or Sy chap-mutual ;
317 it is a configuration error to mix multiple types in one target.
318 .It Ic initiator-name Ar initiator-name
319 An iSCSI initiator name.
320 Only initiators with a name matching one of the defined
321 names will be allowed to connect.
322 If not defined, there will be no restrictions based on initiator
324 This clause is mutually exclusive with
327 both in a single target.
328 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
329 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
330 followed by a literal slash and a prefix length.
331 Only initiators with an address matching one of the defined
332 addresses will be allowed to connect.
333 If not defined, there will be no restrictions based on initiator
335 This clause is mutually exclusive with
338 both in a single target.
347 clauses in the target context provide an alternative to assigning an
349 defined separately, useful in the common case of authentication settings
350 specific to a single target.
351 .It Ic portal-group Ar name Op Ar ag-name
352 Assign a previously defined portal group to the target.
353 The default portal group is
355 which makes the target available
356 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
357 Optional second argument specifies
359 for connections to this specific portal group.
360 If second argument is not specified, target
364 .It Ic port Ar name/pp
365 .It Ic port Ar name/pp/vp
366 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
367 This is used to export the target through a specific physical - eg Fibre
368 Channel - port, in addition to portal-groups configured for the target.
370 .Cm "ctladm portlist"
371 command to retrieve the list of available ports.
374 configures LUN mapping and enables all assigned ports.
375 Each port can be assigned to only one target.
376 .It Ic redirect Ar address
377 IPv4 or IPv6 address to redirect initiators to.
378 When configured, all initiators attempting to connect to this target
379 will get redirected using "Target moved temporarily" login response.
380 Redirection happens after successful authentication.
381 .It Ic lun Ar number Ar name
382 Export previously defined
384 by the parent target.
388 configuration context, defining a LUN exported by the parent target.
390 This is an alternative to defining the LUN separately, useful in the common
391 case of a LUN being exported by a single target.
394 .Bl -tag -width indent
395 .It Ic backend Ar block No | Ar ramdisk
396 The CTL backend to use for a given LUN.
401 block is used for LUNs backed
402 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
404 The default backend is block.
405 .It Ic blocksize Ar size
406 The blocksize visible to the initiator.
407 The default blocksize is 512 for disks, and 2048 for CD/DVDs.
408 .It Ic ctl-lun Ar lun_id
409 Global numeric identifier to use for a given LUN inside CTL.
410 By default CTL allocates those IDs dynamically, but explicit specification
411 may be needed for consistency in HA configurations.
412 .It Ic device-id Ar string
413 The SCSI Device Identification string presented to the initiator.
414 .It Ic device-type Ar type
415 Specify the SCSI device type to use when creating the LUN.
416 Currently CTL supports Direct Access (type 0), Processor (type 3)
417 and CD/DVD (type 5) LUNs.
418 .It Ic option Ar name Ar value
419 The CTL-specific options passed to the kernel.
420 All CTL-specific options are documented in the
425 The path to the file, device node, or
427 volume used to back the LUN.
428 For optimal performance, create the volume with the
431 .It Ic serial Ar string
432 The SCSI serial number presented to the initiator.
434 The LUN size, in bytes or by number with a suffix of
436 (for kilobytes, megabytes, gigabytes, or terabytes).
437 When the configuration is in UCL format, use the suffix format
438 .Sy kKmMgG Ns | Ns Sy bB ,
439 (i.e., 4GB, 4gb, and 4Gb are all equivalent).
442 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
444 The default location of the
451 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
452 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
453 initiator-portal 192.168.1.1/16
458 initiator-name "iqn.2012-06.com.example:initiatorhost1"
459 initiator-name "iqn.2012-06.com.example:initiatorhost2"
460 initiator-portal 192.168.1.1/24
461 initiator-portal [2001:db8::de:ef]
465 discovery-auth-group no-authentication
468 listen [fe80::be:ef]:3261
471 target iqn.2012-06.com.example:target0 {
472 alias "Example target"
473 auth-group no-authentication
475 path /dev/zvol/tank/example_0
482 path /dev/zvol/tank/example_1
483 option naa 0x50015178f369f093
486 target iqn.2012-06.com.example:target1 {
491 path /dev/zvol/tank/example_2
492 option vendor "FreeBSD"
496 target naa.50015178f369f092 {
503 An equivalent configuration in UCL format, for use with
511 secret = "secretsecret"
512 mutual-user = "mutualuser"
513 mutual-secret = "mutualsecret"
517 secret = "secret2secret2"
518 mutual-user = "mutualuser"
519 mutual-secret = "mutualsecret"
527 "iqn.2012-06.com.example:initiatorhost1",
528 "iqn.2012-06.com.example:initiatorhost2"
530 initiator-portal = [192.168.1.1/24, "[2001:db8::de:ef]"]
536 discovery-auth-group = no-authentication
547 path = /dev/zvol/tank/example_0
553 path = /dev/zvol/tank/example_1
555 naa = "0x50015178f369f093"
560 path = /dev/zvol/tank/example_2
568 "iqn.2012-06.com.example:target0" {
569 alias = "Example target"
570 auth-group = no-authentication
572 { number = 0, name = example_0 },
576 "iqn.2012-06.com.example:target1" {
578 portal-group { name = pg0 }
580 { number = 0, name = example_1 },
581 { number = 1, name = example_2 }
585 naa.50015178f369f092 {
588 { number = 0, name = example_1 }
601 configuration file functionality for
604 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
605 under sponsorship from the FreeBSD Foundation.