1 .\" Copyright (c) 2012 The FreeBSD Foundation
2 .\" All rights reserved.
4 .\" This software was developed by Edward Tomasz Napierala under sponsorship
5 .\" from the FreeBSD Foundation.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .Nd CAM Target Layer / iSCSI target daemon configuration file
39 configuration file is used by the
44 are interpreted as comments.
45 The general syntax of the
48 .Bd -literal -offset indent
51 .No auth-group Ar name No {
52 .Dl chap Ar user Ar secret
56 .No portal-group Ar name No {
58 .\".Dl listen-iser Ar address
59 .Dl discovery-auth-group Ar name
68 .Dl auth-group Ar name
69 .Dl portal-group Ar name Op Ar agname
71 .Dl lun Ar number Ar name
72 .Dl lun Ar number No {
79 .Bl -tag -width indent
80 .It Ic auth-group Ar name
83 configuration context,
84 defining a new auth-group,
85 which can then be assigned to any number of targets.
87 The debug verbosity level.
89 .It Ic maxproc Ar number
90 The limit for concurrently running child processes handling
93 A setting of 0 disables the limit.
94 .It Ic pidfile Ar path
95 The path to the pidfile.
97 .Pa /var/run/ctld.pid .
98 .It Ic portal-group Ar name
101 configuration context,
102 defining a new portal-group,
103 which can then be assigned to any number of targets.
107 configuration context, defining a LUN to be exported by some target(s).
108 .It Ic target Ar name
111 configuration context, which can contain one or more
114 .It Ic timeout Ar seconds
115 The timeout for login sessions, after which the connection
116 will be forcibly terminated.
118 A setting of 0 disables the timeout.
119 .It Ic isns-server Ar address
120 An IPv4 or IPv6 address and optionally port of iSNS server to register on.
121 .It Ic isns-period Ar seconds
122 iSNS registration period.
123 Registered Network Entity not updated during this period will be unregistered.
125 .It Ic isns-timeout Ar seconds
126 Timeout for iSNS requests.
129 .Ss auth-group Context
130 .Bl -tag -width indent
131 .It Ic auth-type Ar type
132 Sets the authentication type.
139 In most cases it is not necessary to set the type using this clause;
140 it is usually used to disable authentication for a given
142 .It Ic chap Ar user Ar secret
143 A set of CHAP authentication credentials.
146 the configuration may only contain either
150 entries; it is an error to mix them.
151 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
152 A set of mutual CHAP authentication credentials.
155 the configuration may only contain either
159 entries; it is an error to mix them.
160 .It Ic initiator-name Ar initiator-name
161 An iSCSI initiator name.
162 Only initiators with a name matching one of the defined
163 names will be allowed to connect.
164 If not defined, there will be no restrictions based on initiator
166 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
167 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
168 followed by a literal slash and a prefix length.
169 Only initiators with an address matching one of the defined
170 addresses will be allowed to connect.
171 If not defined, there will be no restrictions based on initiator
174 .Ss portal-group Context
175 .Bl -tag -width indent
176 .It Ic discovery-auth-group Ar name
177 Assign a previously defined authentication group to the portal group,
178 to be used for target discovery.
179 By default, portal groups are assigned predefined
182 which denies discovery.
185 .Qq Ar no-authentication ,
187 to permit discovery without authentication.
188 .It Ic discovery-filter Ar filter
189 Determines which targets are returned during discovery.
195 .Qq Ar portal-name-auth .
198 discovery will return all targets assigned to that portal group.
201 discovery will not return targets that cannot be accessed by the
202 initiator because of their
203 .Sy initiator-portal .
206 the check will include both
211 .Qq Ar portal-name-auth ,
212 the check will include
213 .Sy initiator-portal ,
215 and authentication credentials.
216 The target is returned if it does not require CHAP authentication,
217 or if the CHAP user and secret used during discovery match those
220 .Qq Ar portal-name-auth ,
221 targets that require CHAP authentication will only be returned if
222 .Sy discovery-auth-group
226 .It Ic listen Ar address
227 An IPv4 or IPv6 address and port to listen on for incoming connections.
228 .\".It Ic listen-iser Ar address
229 .\"An IPv4 or IPv6 address and port to listen on for incoming connections
230 .\"using iSER (iSCSI over RDMA) protocol.
231 .It Ic redirect Aq 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
244 .Bl -tag -width indent
246 Assign a human-readable description to the target.
248 .It Ic auth-group Ar name
249 Assign a previously defined authentication group to the target.
250 By default, targets that do not specify their own auth settings,
251 using clauses such as
259 which denies all access.
262 .Qq Ar no-authentication ,
263 may be used to permit access
264 without authentication.
265 Note that targets must only use one of
266 .Sy auth-group , chap , No or Sy chap-mutual ;
267 it is a configuration error to mix multiple types in one target.
268 .It Ic auth-type Ar type
269 Sets the authentication type.
276 In most cases it is not necessary to set the type using this clause;
277 it is usually used to disable authentication for a given
279 This clause is mutually exclusive with
282 both in a single target.
283 .It Ic chap Ar user Ar secret
284 A set of CHAP authentication credentials.
285 Note that targets must only use one of
286 .Sy auth-group , chap , No or Sy chap-mutual ;
287 it is a configuration error to mix multiple types in one target.
288 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
289 A set of mutual CHAP authentication credentials.
290 Note that targets must only use one of
291 .Sy auth-group , chap , No or Sy chap-mutual ;
292 it is a configuration error to mix multiple types in one target.
293 .It Ic initiator-name Ar initiator-name
294 An iSCSI initiator name.
295 Only initiators with a name matching one of the defined
296 names will be allowed to connect.
297 If not defined, there will be no restrictions based on initiator
299 This clause is mutually exclusive with
302 both in a single target.
303 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
304 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
305 followed by a literal slash and a prefix length.
306 Only initiators with an address matching one of the defined
307 addresses will be allowed to connect.
308 If not defined, there will be no restrictions based on initiator
310 This clause is mutually exclusive with
313 both in a single target.
314 .It Ic portal-group Ar name Op Ar agname
315 Assign a previously defined portal group to the target.
316 The default portal group is
318 which makes the target available
319 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
320 Optional second argument specifies auth group name for connections
321 to this specific portal group.
322 If second argument is not specified, target auth group is used.
324 .It Ic port Ar name/pp
325 .It Ic port Ar name/pp/vp
326 Assign specified CTL port (such as "isp0" or "isp2/1") to the target.
327 On startup ctld configures LUN mapping and enables all assigned ports.
328 Each port can be assigned to only one target.
329 .It Ic redirect Aq Ar address
330 IPv4 or IPv6 address to redirect initiators to.
331 When configured, all initiators attempting to connect to this target
332 will get redirected using "Target moved temporarily" login response.
333 Redirection happens after successful authentication.
334 .It Ic lun Ar number Ar name
335 Export previously defined
337 by the parent target.
341 configuration context, defining a LUN exported by the parent target.
344 .Bl -tag -width indent
345 .It Ic backend Ar block No | Ar ramdisk
346 The CTL backend to use for a given LUN.
351 block is used for LUNs backed
352 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
354 The default backend is block.
355 .It Ic blocksize Ar size
356 The blocksize visible to the initiator.
357 The default blocksize is 512.
358 .It Ic device-id Ar string
359 The SCSI Device Identification string presented to the initiator.
360 .It Ic option Ar name Ar value
361 The CTL-specific options passed to the kernel.
362 All CTL-specific options are documented in the
367 The path to the file, device node, or
369 volume used to back the LUN.
370 For optimal performance, create the volume with the
373 .It Ic serial Ar string
374 The SCSI serial number presented to the initiator.
376 The LUN size, in bytes.
379 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
381 The default location of the
388 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
389 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
394 initiator-name "iqn.2012-06.com.example:initiatorhost1"
395 initiator-name "iqn.2012-06.com.example:initiatorhost2"
396 initiator-portal 192.168.1.1/24
397 initiator-portal [2001:db8::de:ef]
401 discovery-auth-group no-authentication
404 listen [fe80::be:ef]:3261
407 target iqn.2012-06.com.example:target0 {
408 alias "Example target"
409 auth-group no-authentication
411 path /dev/zvol/tank/example_0
418 path /dev/zvol/tank/example_1
419 option naa 0x50015178f369f093
422 target iqn.2012-06.com.example:target1 {
427 path /dev/zvol/tank/example_2
432 target naa.50015178f369f092 {
446 configuration file functionality for
449 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org
450 under sponsorship from the FreeBSD Foundation.