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
64 .Dl auth-group Ar name
65 .Dl portal-group Ar name
66 .Dl lun Ar number No {
73 .Bl -tag -width indent
74 .It Ic auth-group Ar name
77 configuration context,
78 defining a new auth-group,
79 which can then be assigned to any number of targets.
81 The debug verbosity level.
83 .It Ic maxproc Ar number
84 The limit for concurrently running child processes handling
87 A setting of 0 disables the limit.
88 .It Ic pidfile Ar path
89 The path to the pidfile.
91 .Pa /var/run/ctld.pid .
92 .It Ic portal-group Ar name
95 configuration context,
96 defining a new portal-group,
97 which can then be assigned to any number of targets.
101 configuration context, which can contain one or more
104 .It Ic timeout Ar seconds
105 The timeout for login sessions, after which the connection
106 will be forcibly terminated.
108 A setting of 0 disables the timeout.
109 .It Ic isns-server Ar address
110 An IPv4 or IPv6 address and optionally port of iSNS server to register on.
111 .It Ic isns-period Ar seconds
112 iSNS registration period.
113 Registered Network Entity not updated during this period will be unregistered.
115 .It Ic isns-timeout Ar seconds
116 Timeout for iSNS requests.
119 .Ss auth-group Context
120 .Bl -tag -width indent
121 .It Ic auth-type Ar type
122 Sets the authentication type.
129 In most cases it is not necessary to set the type using this clause;
130 it is usually used to disable authentication for a given
132 .It Ic chap Ar user Ar secret
133 A set of CHAP authentication credentials.
136 the configuration may only contain either
140 entries; it is an error to mix them.
141 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
142 A set of mutual CHAP authentication credentials.
145 the configuration may only contain either
149 entries; it is an error to mix them.
150 .It Ic initiator-name Ar initiator-name
151 An iSCSI initiator name.
152 Only initiators with a name matching one of the defined
153 names will be allowed to connect.
154 If not defined, there will be no restrictions based on initiator
156 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
157 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
158 followed by a literal slash and a prefix length.
159 Only initiators with an address matching one of the defined
160 addresses will be allowed to connect.
161 If not defined, there will be no restrictions based on initiator
164 .Ss portal-group Context
165 .Bl -tag -width indent
166 .It Ic discovery-auth-group Ar name
167 Assign a previously defined authentication group to the portal group,
168 to be used for target discovery.
169 By default, portal groups are assigned predefined
172 which denies discovery.
175 .Qq Ar no-authentication ,
177 to permit discovery without authentication.
178 .It Ic discovery-filter Ar filter
179 Determines which targets are returned during discovery.
185 .Qq Ar portal-name-auth .
188 discovery will return all targets assigned to that portal group.
191 discovery will not return targets that cannot be accessed by the
192 initiator because of their
193 .Sy initiator-portal .
196 the check will include both
201 .Qq Ar portal-name-auth ,
202 the check will include
203 .Sy initiator-portal ,
205 and authentication credentials.
206 The target is returned if it does not require CHAP authentication,
207 or if the CHAP user and secret used during discovery match those
210 .Qq Ar portal-name-auth ,
211 targets that require CHAP authentication will only be returned if
212 .Sy discovery-auth-group
216 .It Ic listen Ar address
217 An IPv4 or IPv6 address and port to listen on for incoming connections.
218 .\".It Ic listen-iser Ar address
219 .\"An IPv4 or IPv6 address and port to listen on for incoming connections
220 .\"using iSER (iSCSI over RDMA) protocol.
221 .It Ic redirect Aq Ar address
222 IPv4 or IPv6 address to redirect initiators to.
223 When configured, all initiators attempting to connect to portal
226 will get redirected using "Target moved temporarily" login response.
227 Redirection happens before authentication and any
234 .Bl -tag -width indent
236 Assign a human-readable description to the target.
238 .It Ic auth-group Ar name
239 Assign a previously defined authentication group to the target.
240 By default, targets that do not specify their own auth settings,
241 using clauses such as
249 which denies all access.
252 .Qq Ar no-authentication ,
253 may be used to permit access
254 without authentication.
255 Note that targets must only use one of
256 .Sy auth-group , chap , No or Sy chap-mutual ;
257 it is a configuration error to mix multiple types in one target.
258 .It Ic auth-type Ar type
259 Sets the authentication type.
266 In most cases it is not necessary to set the type using this clause;
267 it is usually used to disable authentication for a given
269 This clause is mutually exclusive with
272 both in a single target.
273 .It Ic chap Ar user Ar secret
274 A set of CHAP authentication credentials.
275 Note that targets must only use one of
276 .Sy auth-group , chap , No or Sy chap-mutual ;
277 it is a configuration error to mix multiple types in one target.
278 .It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
279 A set of mutual CHAP authentication credentials.
280 Note that targets must only use one of
281 .Sy auth-group , chap , No or Sy chap-mutual ;
282 it is a configuration error to mix multiple types in one target.
283 .It Ic initiator-name Ar initiator-name
284 An iSCSI initiator name.
285 Only initiators with a name matching one of the defined
286 names will be allowed to connect.
287 If not defined, there will be no restrictions based on initiator
289 This clause is mutually exclusive with
292 both in a single target.
293 .It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
294 An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
295 followed by a literal slash and a prefix length.
296 Only initiators with an address matching one of the defined
297 addresses will be allowed to connect.
298 If not defined, there will be no restrictions based on initiator
300 This clause is mutually exclusive with
303 both in a single target.
304 .It Ic portal-group Ar name
305 Assign a previously defined portal group to the target.
306 The default portal group is
308 which makes the target available
309 on TCP port 3260 on all configured IPv4 and IPv6 addresses.
310 .It Ic redirect Aq Ar address
311 IPv4 or IPv6 address to redirect initiators to.
312 When configured, all initiators attempting to connect to this target
313 will get redirected using "Target moved temporarily" login response.
314 Redirection happens after successful authentication.
318 configuration context, defining a LUN exported by the parent target.
321 .Bl -tag -width indent
322 .It Ic backend Ar block No | Ar ramdisk
323 The CTL backend to use for a given LUN.
328 block is used for LUNs backed
329 by files or disk device nodes; ramdisk is a bitsink device, used mostly for
331 The default backend is block.
332 .It Ic blocksize Ar size
333 The blocksize visible to the initiator.
334 The default blocksize is 512.
335 .It Ic device-id Ar string
336 The SCSI Device Identification string presented to the initiator.
337 .It Ic option Ar name Ar value
338 The CTL-specific options passed to the kernel.
339 All CTL-specific options are documented in the
344 The path to the file or device node used to back the LUN.
345 .It Ic serial Ar string
346 The SCSI serial number presented to the initiator.
348 The LUN size, in bytes.
351 .Bl -tag -width ".Pa /etc/ctl.conf" -compact
353 The default location of the
360 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
361 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
362 initiator-portal 192.168.1.1/16
367 initiator-name "iqn.2012-06.com.example:initiatorhost1"
368 initiator-name "iqn.2012-06.com.example:initiatorhost2"
369 initiator-portal 192.168.1.1/24
370 initiator-portal [2001:db8::de:ef]
374 discovery-auth-group no-authentication
377 listen [fe80::be:ef]:3261
380 target iqn.2012-06.com.example:target0 {
381 alias "Example target"
382 auth-group no-authentication
384 path /dev/zvol/tank/example_0
390 target iqn.2012-06.com.example:target1 {
391 chap chapuser chapsecret
393 path /dev/zvol/tank/example_1
397 target iqn.2012-06.com.example:target2 {
401 path /dev/zvol/tank/example2_0
404 path /dev/zvol/tank/example2_1
416 configuration file functionality for
419 .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
420 under sponsorship from the FreeBSD Foundation.