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.
255 .Bl -tag -width indent
257 Assign a human-readable description to the target.
259 .It Ic auth-group Ar name
260 Assign a previously defined authentication group to the target.
261 By default, targets that do not specify their own auth settings,
262 using clauses such as
270 which denies all access.
273 .Qq Ar no-authentication ,
274 may be used to permit access
275 without authentication.
276 Note that this clause can be overridden using the second argument
280 .It Ic auth-type Ar type
281 Sets the authentication type.
288 In most cases it is not necessary to set the type using this clause;
289 it is usually used to disable authentication for a given
291 This clause is mutually exclusive with
294 both in a single target.
295 .It Ic chap Ar user Ar secret
296 A set of CHAP authentication credentials.
297 Note that targets must only use one of
298 .Sy auth-group , chap , No or Sy chap-mutual ;
299 it is a configuration error to mix multiple types in one target.
300 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
301 A set of mutual CHAP authentication credentials.
302 Note that targets must only use one of
303 .Sy auth-group , chap , No or Sy chap-mutual ;
304 it is a configuration error to mix multiple types in one target.
305 .It Ic initiator-name Ar initiator-name
306 An iSCSI initiator name.
307 Only initiators with a name matching one of the defined
308 names will be allowed to connect.
309 If not defined, there will be no restrictions based on initiator
311 This clause is mutually exclusive with
314 both in a single target.
315 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
316 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
317 followed by a literal slash and a prefix length.
318 Only initiators with an address matching one of the defined
319 addresses will be allowed to connect.
320 If not defined, there will be no restrictions based on initiator
322 This clause is mutually exclusive with
325 both in a single target.
334 clauses in the target context provide an alternative to assigning an
336 defined separately, useful in the common case of authentication settings
337 specific to a single target.
338 .It Ic portal-group Ar name Op Ar ag-name
339 Assign a previously defined portal group to the target.
340 The default portal group is
342 which makes the target available
343 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
344 Optional second argument specifies
346 for connections to this specific portal group.
347 If second argument is not specified, target
351 .It Ic port Ar name/pp
352 .It Ic port Ar name/pp/vp
353 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
354 This is used to export the target through a specific physical - eg Fibre
355 Channel - port, in addition to portal-groups configured for the target.
357 .Cm "ctladm portlist"
358 command to retrieve the list of available ports.
361 configures LUN mapping and enables all assigned ports.
362 Each port can be assigned to only one target.
363 .It Ic redirect Ar address
364 IPv4 or IPv6 address to redirect initiators to.
365 When configured, all initiators attempting to connect to this target
366 will get redirected using "Target moved temporarily" login response.
367 Redirection happens after successful authentication.
368 .It Ic lun Ar number Ar name
369 Export previously defined
371 by the parent target.
375 configuration context, defining a LUN exported by the parent target.
377 This is an alternative to defining the LUN separately, useful in the common
378 case of a LUN being exported by a single target.
381 .Bl -tag -width indent
382 .It Ic backend Ar block No | Ar ramdisk
383 The CTL backend to use for a given LUN.
388 block is used for LUNs backed
389 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
391 The default backend is block.
392 .It Ic blocksize Ar size
393 The blocksize visible to the initiator.
394 The default blocksize is 512 for disks, and 2048 for CD/DVDs.
395 .It Ic ctl-lun Ar lun_id
396 Global numeric identifier to use for a given LUN inside CTL.
397 By default CTL allocates those IDs dynamically, but explicit specification
398 may be needed for consistency in HA configurations.
399 .It Ic device-id Ar string
400 The SCSI Device Identification string presented to the initiator.
401 .It Ic device-type Ar type
402 Specify the SCSI device type to use when creating the LUN.
403 Currently CTL supports Direct Access (type 0), Processor (type 3)
404 and CD/DVD (type 5) LUNs.
405 .It Ic option Ar name Ar value
406 The CTL-specific options passed to the kernel.
407 All CTL-specific options are documented in the
412 The path to the file, device node, or
414 volume used to back the LUN.
415 For optimal performance, create the volume with the
418 .It Ic serial Ar string
419 The SCSI serial number presented to the initiator.
421 The LUN size, in bytes.
424 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
426 The default location of the
433 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
434 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
435 initiator-portal 192.168.1.1/16
440 initiator-name "iqn.2012-06.com.example:initiatorhost1"
441 initiator-name "iqn.2012-06.com.example:initiatorhost2"
442 initiator-portal 192.168.1.1/24
443 initiator-portal [2001:db8::de:ef]
447 discovery-auth-group no-authentication
450 listen [fe80::be:ef]:3261
453 target iqn.2012-06.com.example:target0 {
454 alias "Example target"
455 auth-group no-authentication
457 path /dev/zvol/tank/example_0
464 path /dev/zvol/tank/example_1
465 option naa 0x50015178f369f093
468 target iqn.2012-06.com.example:target1 {
473 path /dev/zvol/tank/example_2
474 option vendor "FreeBSD"
478 target naa.50015178f369f092 {
485 An equivalent configuration in UCL format, for use with
493 secret = "secretsecret"
494 mutual-user = "mutualuser"
495 mutual-secret = "mutualsecret"
499 secret = "secret2secret2"
500 mutual-user = "mutualuser"
501 mutual-secret = "mutualsecret"
509 "iqn.2012-06.com.example:initiatorhost1",
510 "iqn.2012-06.com.example:initiatorhost2"
512 initiator-portal = [192.168.1.1/24, "[2001:db8::de:ef]"]
518 discovery-auth-group = no-authentication
529 path = /dev/zvol/tank/example_0
535 path = /dev/zvol/tank/example_1
537 naa = "0x50015178f369f093"
542 path = /dev/zvol/tank/example_2
550 "iqn.2012-06.com.example:target0" {
551 alias = "Example target"
552 auth-group = no-authentication
554 { number = 0, name = example_0 },
558 "iqn.2012-06.com.example:target1" {
560 portal-group { name = pg0 }
562 { number = 0, name = example_1 },
563 { number = 1, name = example_2 }
567 naa.50015178f369f092 {
570 { number = 0, name = example_1 }
583 configuration file functionality for
586 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
587 under sponsorship from the FreeBSD Foundation.