1.\" Copyright (c) 2012 The FreeBSD Foundation
2.\" All rights reserved.
3.\"
4.\" This software was developed by Edward Tomasz Napierala under sponsorship
5.\" from the FreeBSD Foundation.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
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.
15.\"
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
26.\" SUCH DAMAGE.
27.\"
28.\" $FreeBSD: stable/10/usr.sbin/ctld/ctl.conf.5 279002 2015-02-19 14:31:16Z mav $
29.\"
30.Dd February 1, 2015
31.Dt CTL.CONF 5
32.Os
33.Sh NAME
34.Nm ctl.conf
35.Nd CAM Target Layer / iSCSI target daemon configuration file
36.Sh DESCRIPTION
37The
38.Nm
39configuration file is used by the
40.Xr ctld 8
41daemon.
42Lines starting with
43.Ql #
44are interpreted as comments.
45The general syntax of the
46.Nm
47file is:
48.Bd -literal -offset indent
49.No pidfile Ar path
50
51.No auth-group Ar name No {
52.Dl chap Ar user Ar secret
53.Dl ...
54}
55
56.No portal-group Ar name No {
57.Dl listen Ar address
58.\".Dl listen-iser Ar address
59.Dl discovery-auth-group Ar name
60.Dl ...
61}
62
63.No lun Ar name No {
64.Dl path Ar path
65}
66
67.No target Ar name {
68.Dl auth-group Ar name
69.Dl portal-group Ar name
70.Dl lun Ar number Ar name
71.Dl lun Ar number No {
72.Dl path Ar path
73.Dl }
74.Dl ...
75}
76.Ed
77.Ss Global Context
78.Bl -tag -width indent
79.It Ic auth-group Ar name
80Create an
81.Sy auth-group
82configuration context,
83defining a new auth-group,
84which can then be assigned to any number of targets.
85.It Ic debug Ar level
86The debug verbosity level.
87The default is 0.
88.It Ic maxproc Ar number
89The limit for concurrently running child processes handling
90incoming connections.
91The default is 30.
92A setting of 0 disables the limit.
93.It Ic pidfile Ar path
94The path to the pidfile.
95The default is
96.Pa /var/run/ctld.pid .
97.It Ic portal-group Ar name
98Create a
99.Sy portal-group
100configuration context,
101defining a new portal-group,
102which can then be assigned to any number of targets.
103.It Ic lun Ar name
104Create a
105.Sy lun
106configuration context, defining a LUN to be exported by some target(s).
107.It Ic target Ar name
108Create a
109.Sy target
110configuration context, which can contain one or more
111.Sy lun
112contexts.
113.It Ic timeout Ar seconds
114The timeout for login sessions, after which the connection
115will be forcibly terminated.
116The default is 60.
117A setting of 0 disables the timeout.
118.It Ic isns-server Ar address
119An IPv4 or IPv6 address and optionally port of iSNS server to register on.
120.It Ic isns-period Ar seconds
121iSNS registration period.
122Registered Network Entity not updated during this period will be unregistered.
123The default is 900.
124.It Ic isns-timeout Ar seconds
125Timeout for iSNS requests.
126The default is 5.
127.El
128.Ss auth-group Context
129.Bl -tag -width indent
130.It Ic auth-type Ar type
131Sets the authentication type.
132Type can be either
133.Qq Ar none ,
134.Qq Ar deny ,
135.Qq Ar chap ,
136or
137.Qq Ar chap-mutual .
138In most cases it is not necessary to set the type using this clause;
139it is usually used to disable authentication for a given
140.Sy auth-group .
141.It Ic chap Ar user Ar secret
142A set of CHAP authentication credentials.
143Note that for any
144.Sy auth-group ,
145the configuration may only contain either
146.Sy chap
147or
148.Sy chap-mutual
149entries; it is an error to mix them.
150.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
151A set of mutual CHAP authentication credentials.
152Note that for any
153.Sy auth-group ,
154the configuration may only contain either
155.Sy chap
156or
157.Sy chap-mutual
158entries; it is an error to mix them.
159.It Ic initiator-name Ar initiator-name
160An iSCSI initiator name.
161Only initiators with a name matching one of the defined
162names will be allowed to connect.
163If not defined, there will be no restrictions based on initiator
164name.
165.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
166An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
167followed by a literal slash and a prefix length.
168Only initiators with an address matching one of the defined
169addresses will be allowed to connect.
170If not defined, there will be no restrictions based on initiator
171address.
172.El
173.Ss portal-group Context
174.Bl -tag -width indent
175.It Ic discovery-auth-group Ar name
176Assign a previously defined authentication group to the portal group,
177to be used for target discovery.
178By default, portal groups are assigned predefined
179.Sy auth-group
180.Qq Ar default ,
181which denies discovery.
182Another predefined
183.Sy auth-group ,
184.Qq Ar no-authentication ,
185may be used
186to permit discovery without authentication.
187.It Ic discovery-filter Ar filter
188Determines which targets are returned during discovery.
189Filter can be either
190.Qq Ar none ,
191.Qq Ar portal ,
192.Qq Ar portal-name ,
193or
194.Qq Ar portal-name-auth .
195When set to
196.Qq Ar none ,
197discovery will return all targets assigned to that portal group.
198When set to
199.Qq Ar portal ,
200discovery will not return targets that cannot be accessed by the
201initiator because of their
202.Sy initiator-portal .
203When set to
204.Qq Ar portal-name ,
205the check will include both
206.Sy initiator-portal
207and
208.Sy initiator-name .
209When set to
210.Qq Ar portal-name-auth ,
211the check will include
212.Sy initiator-portal ,
213.Sy initiator-name ,
214and authentication credentials.
215The target is returned if it does not require CHAP authentication,
216or if the CHAP user and secret used during discovery match those
217used by the target.
218Note that when using
219.Qq Ar portal-name-auth ,
220targets that require CHAP authentication will only be returned if
221.Sy discovery-auth-group
222requires CHAP.
223The default is
224.Qq Ar none .
225.It Ic listen Ar address
226An IPv4 or IPv6 address and port to listen on for incoming connections.
227.\".It Ic listen-iser Ar address
228.\"An IPv4 or IPv6 address and port to listen on for incoming connections
229.\"using iSER (iSCSI over RDMA) protocol.
230.It Ic redirect Aq Ar address
231IPv4 or IPv6 address to redirect initiators to.
232When configured, all initiators attempting to connect to portal
233belonging to this
234.Sy portal-group
235will get redirected using "Target moved temporarily" login response.
236Redirection happens before authentication and any
237.Sy initiator-name
238or
239.Sy initiator-portal
240checks are skipped.
241.El
242.Ss target Context
243.Bl -tag -width indent
244.It Ic alias Ar text
245Assign a human-readable description to the target.
246There is no default.
247.It Ic auth-group Ar name
248Assign a previously defined authentication group to the target.
249By default, targets that do not specify their own auth settings,
250using clauses such as
251.Sy chap
252or
253.Sy initiator-name ,
254are assigned
255predefined
256.Sy auth-group
257.Qq Ar default ,
258which denies all access.
259Another predefined
260.Sy auth-group ,
261.Qq Ar no-authentication ,
262may be used to permit access
263without authentication.
264Note that targets must only use one of
265.Sy auth-group , chap , No or Sy chap-mutual ;
266it is a configuration error to mix multiple types in one target.
267.It Ic auth-type Ar type
268Sets the authentication type.
269Type can be either
270.Qq Ar none ,
271.Qq Ar deny ,
272.Qq Ar chap ,
273or
274.Qq Ar chap-mutual .
275In most cases it is not necessary to set the type using this clause;
276it is usually used to disable authentication for a given
277.Sy target .
278This clause is mutually exclusive with
279.Sy auth-group ;
280one cannot use
281both in a single target.
282.It Ic chap Ar user Ar secret
283A set of CHAP authentication credentials.
284Note that targets must only use one of
285.Sy auth-group , chap , No or Sy chap-mutual ;
286it is a configuration error to mix multiple types in one target.
287.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
288A set of mutual CHAP authentication credentials.
289Note that targets must only use one of
290.Sy auth-group , chap , No or Sy chap-mutual ;
291it is a configuration error to mix multiple types in one target.
292.It Ic initiator-name Ar initiator-name
293An iSCSI initiator name.
294Only initiators with a name matching one of the defined
295names will be allowed to connect.
296If not defined, there will be no restrictions based on initiator
297name.
298This clause is mutually exclusive with
299.Sy auth-group ;
300one cannot use
301both in a single target.
302.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
303An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
304followed by a literal slash and a prefix length.
305Only initiators with an address matching one of the defined
306addresses will be allowed to connect.
307If not defined, there will be no restrictions based on initiator
308address.
309This clause is mutually exclusive with
310.Sy auth-group ;
311one cannot use
312both in a single target.
313.It Ic portal-group Ar name
314Assign a previously defined portal group to the target.
315The default portal group is
316.Qq Ar default ,
317which makes the target available
318on TCP port 3260 on all configured IPv4 and IPv6 addresses.
319.It Ic redirect Aq Ar address
320IPv4 or IPv6 address to redirect initiators to.
321When configured, all initiators attempting to connect to this target
322will get redirected using "Target moved temporarily" login response.
323Redirection happens after successful authentication.
324.It Ic lun Ar number Ar name
325Export previously defined
326.Sy lun
327by the parent target.
328.It Ic lun Ar number
329Create a
330.Sy lun
331configuration context, defining a LUN exported by the parent target.
332.El
333.Ss lun Context
334.Bl -tag -width indent
335.It Ic backend Ar block No | Ar ramdisk
336The CTL backend to use for a given LUN.
337Valid choices are
338.Qq Ar block
339and
340.Qq Ar ramdisk ;
341block is used for LUNs backed
342by files or disk device nodes; ramdisk is a bitsink device, used mostly for
343testing.
344The default backend is block.
345.It Ic blocksize Ar size
346The blocksize visible to the initiator.
347The default blocksize is 512.
348.It Ic device-id Ar string
349The SCSI Device Identification string presented to the initiator.
350.It Ic option Ar name Ar value
351The CTL-specific options passed to the kernel.
352All CTL-specific options are documented in the
353.Sx OPTIONS
354section of
355.Xr ctladm 8 .
356.It Ic path Ar path
357The path to the file or device node used to back the LUN.
358.It Ic serial Ar string
359The SCSI serial number presented to the initiator.
360.It Ic size Ar size
361The LUN size, in bytes.
362.El
363.Sh FILES
364.Bl -tag -width ".Pa /etc/ctl.conf" -compact
365.It Pa /etc/ctl.conf
366The default location of the
367.Xr ctld 8
368configuration file.
369.El
370.Sh EXAMPLES
371.Bd -literal
372auth-group ag0 {
373 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
374 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
375}
376
377auth-group ag1 {
378 auth-type none
379 initiator-name "iqn.2012-06.com.example:initiatorhost1"
380 initiator-name "iqn.2012-06.com.example:initiatorhost2"
381 initiator-portal 192.168.1.1/24
382 initiator-portal [2001:db8::de:ef]
383}
384
385portal-group pg0 {
386 discovery-auth-group no-authentication
387 listen 0.0.0.0:3260
388 listen [::]:3260
389 listen [fe80::be:ef]:3261
390}
391
392target iqn.2012-06.com.example:target0 {
393 alias "Example target"
394 auth-group no-authentication
395 lun 0 {
396 path /dev/zvol/tank/example_0
397 blocksize 4096
398 size 4G
399 }
400}
401
402lun example_1 {
403 path /dev/zvol/tank/example_1
404}
405
406target iqn.2012-06.com.example:target1 {
407 chap chapuser chapsecret
408 lun 0 example_1
409}
410
411target iqn.2012-06.com.example:target2 {
412 auth-group ag0
413 portal-group pg0
414 lun 0 example_1
415 lun 1 {
416 path /dev/zvol/tank/example_2
417 option foo bar
418 }
419}
420.Ed
421.Sh SEE ALSO
422.Xr ctl 4 ,
423.Xr ctladm 8 ,
424.Xr ctld 8
425.Sh AUTHORS
426The
427.Nm
428configuration file functionality for
429.Xr ctld 8
430was developed by
431.An Edward Tomasz Napierala Aq trasz@FreeBSD.org
432under sponsorship from the FreeBSD Foundation.
2.\" All rights reserved.
3.\"
4.\" This software was developed by Edward Tomasz Napierala under sponsorship
5.\" from the FreeBSD Foundation.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
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.
15.\"
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
26.\" SUCH DAMAGE.
27.\"
28.\" $FreeBSD: stable/10/usr.sbin/ctld/ctl.conf.5 279002 2015-02-19 14:31:16Z mav $
29.\"
30.Dd February 1, 2015
31.Dt CTL.CONF 5
32.Os
33.Sh NAME
34.Nm ctl.conf
35.Nd CAM Target Layer / iSCSI target daemon configuration file
36.Sh DESCRIPTION
37The
38.Nm
39configuration file is used by the
40.Xr ctld 8
41daemon.
42Lines starting with
43.Ql #
44are interpreted as comments.
45The general syntax of the
46.Nm
47file is:
48.Bd -literal -offset indent
49.No pidfile Ar path
50
51.No auth-group Ar name No {
52.Dl chap Ar user Ar secret
53.Dl ...
54}
55
56.No portal-group Ar name No {
57.Dl listen Ar address
58.\".Dl listen-iser Ar address
59.Dl discovery-auth-group Ar name
60.Dl ...
61}
62
63.No lun Ar name No {
64.Dl path Ar path
65}
66
67.No target Ar name {
68.Dl auth-group Ar name
69.Dl portal-group Ar name
70.Dl lun Ar number Ar name
71.Dl lun Ar number No {
72.Dl path Ar path
73.Dl }
74.Dl ...
75}
76.Ed
77.Ss Global Context
78.Bl -tag -width indent
79.It Ic auth-group Ar name
80Create an
81.Sy auth-group
82configuration context,
83defining a new auth-group,
84which can then be assigned to any number of targets.
85.It Ic debug Ar level
86The debug verbosity level.
87The default is 0.
88.It Ic maxproc Ar number
89The limit for concurrently running child processes handling
90incoming connections.
91The default is 30.
92A setting of 0 disables the limit.
93.It Ic pidfile Ar path
94The path to the pidfile.
95The default is
96.Pa /var/run/ctld.pid .
97.It Ic portal-group Ar name
98Create a
99.Sy portal-group
100configuration context,
101defining a new portal-group,
102which can then be assigned to any number of targets.
103.It Ic lun Ar name
104Create a
105.Sy lun
106configuration context, defining a LUN to be exported by some target(s).
107.It Ic target Ar name
108Create a
109.Sy target
110configuration context, which can contain one or more
111.Sy lun
112contexts.
113.It Ic timeout Ar seconds
114The timeout for login sessions, after which the connection
115will be forcibly terminated.
116The default is 60.
117A setting of 0 disables the timeout.
118.It Ic isns-server Ar address
119An IPv4 or IPv6 address and optionally port of iSNS server to register on.
120.It Ic isns-period Ar seconds
121iSNS registration period.
122Registered Network Entity not updated during this period will be unregistered.
123The default is 900.
124.It Ic isns-timeout Ar seconds
125Timeout for iSNS requests.
126The default is 5.
127.El
128.Ss auth-group Context
129.Bl -tag -width indent
130.It Ic auth-type Ar type
131Sets the authentication type.
132Type can be either
133.Qq Ar none ,
134.Qq Ar deny ,
135.Qq Ar chap ,
136or
137.Qq Ar chap-mutual .
138In most cases it is not necessary to set the type using this clause;
139it is usually used to disable authentication for a given
140.Sy auth-group .
141.It Ic chap Ar user Ar secret
142A set of CHAP authentication credentials.
143Note that for any
144.Sy auth-group ,
145the configuration may only contain either
146.Sy chap
147or
148.Sy chap-mutual
149entries; it is an error to mix them.
150.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
151A set of mutual CHAP authentication credentials.
152Note that for any
153.Sy auth-group ,
154the configuration may only contain either
155.Sy chap
156or
157.Sy chap-mutual
158entries; it is an error to mix them.
159.It Ic initiator-name Ar initiator-name
160An iSCSI initiator name.
161Only initiators with a name matching one of the defined
162names will be allowed to connect.
163If not defined, there will be no restrictions based on initiator
164name.
165.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
166An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
167followed by a literal slash and a prefix length.
168Only initiators with an address matching one of the defined
169addresses will be allowed to connect.
170If not defined, there will be no restrictions based on initiator
171address.
172.El
173.Ss portal-group Context
174.Bl -tag -width indent
175.It Ic discovery-auth-group Ar name
176Assign a previously defined authentication group to the portal group,
177to be used for target discovery.
178By default, portal groups are assigned predefined
179.Sy auth-group
180.Qq Ar default ,
181which denies discovery.
182Another predefined
183.Sy auth-group ,
184.Qq Ar no-authentication ,
185may be used
186to permit discovery without authentication.
187.It Ic discovery-filter Ar filter
188Determines which targets are returned during discovery.
189Filter can be either
190.Qq Ar none ,
191.Qq Ar portal ,
192.Qq Ar portal-name ,
193or
194.Qq Ar portal-name-auth .
195When set to
196.Qq Ar none ,
197discovery will return all targets assigned to that portal group.
198When set to
199.Qq Ar portal ,
200discovery will not return targets that cannot be accessed by the
201initiator because of their
202.Sy initiator-portal .
203When set to
204.Qq Ar portal-name ,
205the check will include both
206.Sy initiator-portal
207and
208.Sy initiator-name .
209When set to
210.Qq Ar portal-name-auth ,
211the check will include
212.Sy initiator-portal ,
213.Sy initiator-name ,
214and authentication credentials.
215The target is returned if it does not require CHAP authentication,
216or if the CHAP user and secret used during discovery match those
217used by the target.
218Note that when using
219.Qq Ar portal-name-auth ,
220targets that require CHAP authentication will only be returned if
221.Sy discovery-auth-group
222requires CHAP.
223The default is
224.Qq Ar none .
225.It Ic listen Ar address
226An IPv4 or IPv6 address and port to listen on for incoming connections.
227.\".It Ic listen-iser Ar address
228.\"An IPv4 or IPv6 address and port to listen on for incoming connections
229.\"using iSER (iSCSI over RDMA) protocol.
230.It Ic redirect Aq Ar address
231IPv4 or IPv6 address to redirect initiators to.
232When configured, all initiators attempting to connect to portal
233belonging to this
234.Sy portal-group
235will get redirected using "Target moved temporarily" login response.
236Redirection happens before authentication and any
237.Sy initiator-name
238or
239.Sy initiator-portal
240checks are skipped.
241.El
242.Ss target Context
243.Bl -tag -width indent
244.It Ic alias Ar text
245Assign a human-readable description to the target.
246There is no default.
247.It Ic auth-group Ar name
248Assign a previously defined authentication group to the target.
249By default, targets that do not specify their own auth settings,
250using clauses such as
251.Sy chap
252or
253.Sy initiator-name ,
254are assigned
255predefined
256.Sy auth-group
257.Qq Ar default ,
258which denies all access.
259Another predefined
260.Sy auth-group ,
261.Qq Ar no-authentication ,
262may be used to permit access
263without authentication.
264Note that targets must only use one of
265.Sy auth-group , chap , No or Sy chap-mutual ;
266it is a configuration error to mix multiple types in one target.
267.It Ic auth-type Ar type
268Sets the authentication type.
269Type can be either
270.Qq Ar none ,
271.Qq Ar deny ,
272.Qq Ar chap ,
273or
274.Qq Ar chap-mutual .
275In most cases it is not necessary to set the type using this clause;
276it is usually used to disable authentication for a given
277.Sy target .
278This clause is mutually exclusive with
279.Sy auth-group ;
280one cannot use
281both in a single target.
282.It Ic chap Ar user Ar secret
283A set of CHAP authentication credentials.
284Note that targets must only use one of
285.Sy auth-group , chap , No or Sy chap-mutual ;
286it is a configuration error to mix multiple types in one target.
287.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
288A set of mutual CHAP authentication credentials.
289Note that targets must only use one of
290.Sy auth-group , chap , No or Sy chap-mutual ;
291it is a configuration error to mix multiple types in one target.
292.It Ic initiator-name Ar initiator-name
293An iSCSI initiator name.
294Only initiators with a name matching one of the defined
295names will be allowed to connect.
296If not defined, there will be no restrictions based on initiator
297name.
298This clause is mutually exclusive with
299.Sy auth-group ;
300one cannot use
301both in a single target.
302.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
303An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
304followed by a literal slash and a prefix length.
305Only initiators with an address matching one of the defined
306addresses will be allowed to connect.
307If not defined, there will be no restrictions based on initiator
308address.
309This clause is mutually exclusive with
310.Sy auth-group ;
311one cannot use
312both in a single target.
313.It Ic portal-group Ar name
314Assign a previously defined portal group to the target.
315The default portal group is
316.Qq Ar default ,
317which makes the target available
318on TCP port 3260 on all configured IPv4 and IPv6 addresses.
319.It Ic redirect Aq Ar address
320IPv4 or IPv6 address to redirect initiators to.
321When configured, all initiators attempting to connect to this target
322will get redirected using "Target moved temporarily" login response.
323Redirection happens after successful authentication.
324.It Ic lun Ar number Ar name
325Export previously defined
326.Sy lun
327by the parent target.
328.It Ic lun Ar number
329Create a
330.Sy lun
331configuration context, defining a LUN exported by the parent target.
332.El
333.Ss lun Context
334.Bl -tag -width indent
335.It Ic backend Ar block No | Ar ramdisk
336The CTL backend to use for a given LUN.
337Valid choices are
338.Qq Ar block
339and
340.Qq Ar ramdisk ;
341block is used for LUNs backed
342by files or disk device nodes; ramdisk is a bitsink device, used mostly for
343testing.
344The default backend is block.
345.It Ic blocksize Ar size
346The blocksize visible to the initiator.
347The default blocksize is 512.
348.It Ic device-id Ar string
349The SCSI Device Identification string presented to the initiator.
350.It Ic option Ar name Ar value
351The CTL-specific options passed to the kernel.
352All CTL-specific options are documented in the
353.Sx OPTIONS
354section of
355.Xr ctladm 8 .
356.It Ic path Ar path
357The path to the file or device node used to back the LUN.
358.It Ic serial Ar string
359The SCSI serial number presented to the initiator.
360.It Ic size Ar size
361The LUN size, in bytes.
362.El
363.Sh FILES
364.Bl -tag -width ".Pa /etc/ctl.conf" -compact
365.It Pa /etc/ctl.conf
366The default location of the
367.Xr ctld 8
368configuration file.
369.El
370.Sh EXAMPLES
371.Bd -literal
372auth-group ag0 {
373 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
374 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
375}
376
377auth-group ag1 {
378 auth-type none
379 initiator-name "iqn.2012-06.com.example:initiatorhost1"
380 initiator-name "iqn.2012-06.com.example:initiatorhost2"
381 initiator-portal 192.168.1.1/24
382 initiator-portal [2001:db8::de:ef]
383}
384
385portal-group pg0 {
386 discovery-auth-group no-authentication
387 listen 0.0.0.0:3260
388 listen [::]:3260
389 listen [fe80::be:ef]:3261
390}
391
392target iqn.2012-06.com.example:target0 {
393 alias "Example target"
394 auth-group no-authentication
395 lun 0 {
396 path /dev/zvol/tank/example_0
397 blocksize 4096
398 size 4G
399 }
400}
401
402lun example_1 {
403 path /dev/zvol/tank/example_1
404}
405
406target iqn.2012-06.com.example:target1 {
407 chap chapuser chapsecret
408 lun 0 example_1
409}
410
411target iqn.2012-06.com.example:target2 {
412 auth-group ag0
413 portal-group pg0
414 lun 0 example_1
415 lun 1 {
416 path /dev/zvol/tank/example_2
417 option foo bar
418 }
419}
420.Ed
421.Sh SEE ALSO
422.Xr ctl 4 ,
423.Xr ctladm 8 ,
424.Xr ctld 8
425.Sh AUTHORS
426The
427.Nm
428configuration file functionality for
429.Xr ctld 8
430was developed by
431.An Edward Tomasz Napierala Aq trasz@FreeBSD.org
432under sponsorship from the FreeBSD Foundation.