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 Assign specified CTL port (such as "isp0") to the target.
325 On startup ctld configures LUN mapping and enables all assigned ports.
326 Each port can be assigned to only one target.
327 .It Ic redirect Aq Ar address
328 IPv4 or IPv6 address to redirect initiators to.
329 When configured, all initiators attempting to connect to this target
330 will get redirected using "Target moved temporarily" login response.
331 Redirection happens after successful authentication.
332 .It Ic lun Ar number Ar name
333 Export previously defined
335 by the parent target.
339 configuration context, defining a LUN exported by the parent target.
342 .Bl -tag -width indent
343 .It Ic backend Ar block No | Ar ramdisk
344 The CTL backend to use for a given LUN.
349 block is used for LUNs backed
350 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
352 The default backend is block.
353 .It Ic blocksize Ar size
354 The blocksize visible to the initiator.
355 The default blocksize is 512.
356 .It Ic device-id Ar string
357 The SCSI Device Identification string presented to the initiator.
358 .It Ic option Ar name Ar value
359 The CTL-specific options passed to the kernel.
360 All CTL-specific options are documented in the
365 The path to the file, device node, or
367 volume used to back the LUN.
368 For optimal performance, create the volume with the
371 .It Ic serial Ar string
372 The SCSI serial number presented to the initiator.
374 The LUN size, in bytes.
377 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
379 The default location of the
386 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
387 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
392 initiator-name "iqn.2012-06.com.example:initiatorhost1"
393 initiator-name "iqn.2012-06.com.example:initiatorhost2"
394 initiator-portal 192.168.1.1/24
395 initiator-portal [2001:db8::de:ef]
399 discovery-auth-group no-authentication
402 listen [fe80::be:ef]:3261
405 target iqn.2012-06.com.example:target0 {
406 alias "Example target"
407 auth-group no-authentication
409 path /dev/zvol/tank/example_0
416 path /dev/zvol/tank/example_1
417 option naa 0x50015178f369f093
420 target iqn.2012-06.com.example:target1 {
425 path /dev/zvol/tank/example_2
430 target naa.50015178f369f092 {
444 configuration file functionality for
447 .An Edward Tomasz Napierala Aq trasz@FreeBSD.org
448 under sponsorship from the FreeBSD Foundation.