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 279006 2015-02-19 14:52:01Z mav $
29.\"
30.Dd February 6, 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 Op Ar agname
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 Op Ar agname
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.
319Optional second argument specifies auth group name for connections
320to this specific portal group.
321If second argument is not specified, target auth group is used.
322.It Ic redirect Aq Ar address
323IPv4 or IPv6 address to redirect initiators to.
324When configured, all initiators attempting to connect to this target
325will get redirected using "Target moved temporarily" login response.
326Redirection happens after successful authentication.
327.It Ic lun Ar number Ar name
328Export previously defined
329.Sy lun
330by the parent target.
331.It Ic lun Ar number
332Create a
333.Sy lun
334configuration context, defining a LUN exported by the parent target.
335.El
336.Ss lun Context
337.Bl -tag -width indent
338.It Ic backend Ar block No | Ar ramdisk
339The CTL backend to use for a given LUN.
340Valid choices are
341.Qq Ar block
342and
343.Qq Ar ramdisk ;
344block is used for LUNs backed
345by files or disk device nodes; ramdisk is a bitsink device, used mostly for
346testing.
347The default backend is block.
348.It Ic blocksize Ar size
349The blocksize visible to the initiator.
350The default blocksize is 512.
351.It Ic device-id Ar string
352The SCSI Device Identification string presented to the initiator.
353.It Ic option Ar name Ar value
354The CTL-specific options passed to the kernel.
355All CTL-specific options are documented in the
356.Sx OPTIONS
357section of
358.Xr ctladm 8 .
359.It Ic path Ar path
360The path to the file or device node used to back the LUN.
361.It Ic serial Ar string
362The SCSI serial number presented to the initiator.
363.It Ic size Ar size
364The LUN size, in bytes.
365.El
366.Sh FILES
367.Bl -tag -width ".Pa /etc/ctl.conf" -compact
368.It Pa /etc/ctl.conf
369The default location of the
370.Xr ctld 8
371configuration file.
372.El
373.Sh EXAMPLES
374.Bd -literal
375auth-group ag0 {
376 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
377 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
378}
379
380auth-group ag1 {
381 auth-type none
382 initiator-name "iqn.2012-06.com.example:initiatorhost1"
383 initiator-name "iqn.2012-06.com.example:initiatorhost2"
384 initiator-portal 192.168.1.1/24
385 initiator-portal [2001:db8::de:ef]
386}
387
388portal-group pg0 {
389 discovery-auth-group no-authentication
390 listen 0.0.0.0:3260
391 listen [::]:3260
392 listen [fe80::be:ef]:3261
393}
394
395target iqn.2012-06.com.example:target0 {
396 alias "Example target"
397 auth-group no-authentication
398 lun 0 {
399 path /dev/zvol/tank/example_0
400 blocksize 4096
401 size 4G
402 }
403}
404
405lun example_1 {
406 path /dev/zvol/tank/example_1
407}
408
409target iqn.2012-06.com.example:target1 {
410 chap chapuser chapsecret
411 lun 0 example_1
412}
413
414target iqn.2012-06.com.example:target2 {
415 auth-group ag0
416 portal-group pg0
417 lun 0 example_1
418 lun 1 {
419 path /dev/zvol/tank/example_2
420 option foo bar
421 }
422}
423.Ed
424.Sh SEE ALSO
425.Xr ctl 4 ,
426.Xr ctladm 8 ,
427.Xr ctld 8
428.Sh AUTHORS
429The
430.Nm
431configuration file functionality for
432.Xr ctld 8
433was developed by
434.An Edward Tomasz Napierala Aq trasz@FreeBSD.org
435under 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 279006 2015-02-19 14:52:01Z mav $
29.\"
30.Dd February 6, 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 Op Ar agname
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 Op Ar agname
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.
319Optional second argument specifies auth group name for connections
320to this specific portal group.
321If second argument is not specified, target auth group is used.
322.It Ic redirect Aq Ar address
323IPv4 or IPv6 address to redirect initiators to.
324When configured, all initiators attempting to connect to this target
325will get redirected using "Target moved temporarily" login response.
326Redirection happens after successful authentication.
327.It Ic lun Ar number Ar name
328Export previously defined
329.Sy lun
330by the parent target.
331.It Ic lun Ar number
332Create a
333.Sy lun
334configuration context, defining a LUN exported by the parent target.
335.El
336.Ss lun Context
337.Bl -tag -width indent
338.It Ic backend Ar block No | Ar ramdisk
339The CTL backend to use for a given LUN.
340Valid choices are
341.Qq Ar block
342and
343.Qq Ar ramdisk ;
344block is used for LUNs backed
345by files or disk device nodes; ramdisk is a bitsink device, used mostly for
346testing.
347The default backend is block.
348.It Ic blocksize Ar size
349The blocksize visible to the initiator.
350The default blocksize is 512.
351.It Ic device-id Ar string
352The SCSI Device Identification string presented to the initiator.
353.It Ic option Ar name Ar value
354The CTL-specific options passed to the kernel.
355All CTL-specific options are documented in the
356.Sx OPTIONS
357section of
358.Xr ctladm 8 .
359.It Ic path Ar path
360The path to the file or device node used to back the LUN.
361.It Ic serial Ar string
362The SCSI serial number presented to the initiator.
363.It Ic size Ar size
364The LUN size, in bytes.
365.El
366.Sh FILES
367.Bl -tag -width ".Pa /etc/ctl.conf" -compact
368.It Pa /etc/ctl.conf
369The default location of the
370.Xr ctld 8
371configuration file.
372.El
373.Sh EXAMPLES
374.Bd -literal
375auth-group ag0 {
376 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
377 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
378}
379
380auth-group ag1 {
381 auth-type none
382 initiator-name "iqn.2012-06.com.example:initiatorhost1"
383 initiator-name "iqn.2012-06.com.example:initiatorhost2"
384 initiator-portal 192.168.1.1/24
385 initiator-portal [2001:db8::de:ef]
386}
387
388portal-group pg0 {
389 discovery-auth-group no-authentication
390 listen 0.0.0.0:3260
391 listen [::]:3260
392 listen [fe80::be:ef]:3261
393}
394
395target iqn.2012-06.com.example:target0 {
396 alias "Example target"
397 auth-group no-authentication
398 lun 0 {
399 path /dev/zvol/tank/example_0
400 blocksize 4096
401 size 4G
402 }
403}
404
405lun example_1 {
406 path /dev/zvol/tank/example_1
407}
408
409target iqn.2012-06.com.example:target1 {
410 chap chapuser chapsecret
411 lun 0 example_1
412}
413
414target iqn.2012-06.com.example:target2 {
415 auth-group ag0
416 portal-group pg0
417 lun 0 example_1
418 lun 1 {
419 path /dev/zvol/tank/example_2
420 option foo bar
421 }
422}
423.Ed
424.Sh SEE ALSO
425.Xr ctl 4 ,
426.Xr ctladm 8 ,
427.Xr ctld 8
428.Sh AUTHORS
429The
430.Nm
431configuration file functionality for
432.Xr ctld 8
433was developed by
434.An Edward Tomasz Napierala Aq trasz@FreeBSD.org
435under sponsorship from the FreeBSD Foundation.