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 274873 2014-11-22 17:56:03Z trasz $
29.\"
30.Dd October 22, 2014
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 target Ar name {
64.Dl auth-group Ar name
65.Dl portal-group Ar name
66.Dl lun Ar number No {
67.Dl path Ar path
68.Dl }
69.Dl ...
70}
71.Ed
72.Ss Global Context
73.Bl -tag -width indent
74.It Ic auth-group Ar name
75Create an
76.Sy auth-group
77configuration context,
78defining a new auth-group,
79which can then be assigned to any number of targets.
80.It Ic debug Ar level
81The debug verbosity level.
82The default is 0.
83.It Ic maxproc Ar number
84The limit for concurrently running child processes handling
85incoming connections.
86The default is 30.
87A setting of 0 disables the limit.
88.It Ic pidfile Ar path
89The path to the pidfile.
90The default is
91.Pa /var/run/ctld.pid .
92.It Ic portal-group Ar name
93Create a
94.Sy portal-group
95configuration context,
96defining a new portal-group,
97which can then be assigned to any number of targets.
98.It Ic target Ar name
99Create a
100.Sy target
101configuration context, which can contain one or more
102.Sy lun
103contexts.
104.It Ic timeout Ar seconds
105The timeout for login sessions, after which the connection
106will be forcibly terminated.
107The default is 60.
108A setting of 0 disables the timeout.
109.El
110.Ss auth-group Context
111.Bl -tag -width indent
112.It Ic auth-type Ar type
113Sets the authentication type.
114Type can be either
115.Qq Ar none ,
116.Qq Ar deny ,
117.Qq Ar chap ,
118or
119.Qq Ar chap-mutual .
120In most cases it is not necessary to set the type using this clause;
121it is usually used to disable authentication for a given
122.Sy auth-group .
123.It Ic chap Ar user Ar secret
124A set of CHAP authentication credentials.
125Note that for any
126.Sy auth-group ,
127the configuration may only contain either
128.Sy chap
129or
130.Sy chap-mutual
131entries; it is an error to mix them.
132.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
133A set of mutual CHAP authentication credentials.
134Note that for any
135.Sy auth-group ,
136the configuration may only contain either
137.Sy chap
138or
139.Sy chap-mutual
140entries; it is an error to mix them.
141.It Ic initiator-name Ar initiator-name
142An iSCSI initiator name.
143Only initiators with a name matching one of the defined
144names will be allowed to connect.
145If not defined, there will be no restrictions based on initiator
146name.
147.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
148An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
149followed by a literal slash and a prefix length.
150Only initiators with an address matching one of the defined
151addresses will be allowed to connect.
152If not defined, there will be no restrictions based on initiator
153address.
154.El
155.Ss portal-group Context
156.Bl -tag -width indent
157.It Ic discovery-auth-group Ar name
158Assign a previously defined authentication group to the portal group,
159to be used for target discovery.
160By default, portal groups are assigned predefined
161.Sy auth-group
162.Qq Ar default ,
163which denies discovery.
164Another predefined
165.Sy auth-group ,
166.Qq Ar no-authentication ,
167may be used
168to permit discovery without authentication.
169.It Ic listen Ar address
170An IPv4 or IPv6 address and port to listen on for incoming connections.
171.It Ic listen-iser Ar address
172An IPv4 or IPv6 address and port to listen on for incoming connections
173using iSER (iSCSI over RDMA) protocol.
174.El
175.Ss target Context
176.Bl -tag -width indent
177.It Ic alias Ar text
178Assign a human-readable description to the target.
179There is no default.
180.It Ic auth-group Ar name
181Assign a previously defined authentication group to the target.
182By default, targets that do not specify their own auth settings,
183using clauses such as
184.Sy chap
185or
186.Sy initiator-name ,
187are assigned
188predefined
189.Sy auth-group
190.Qq Ar default ,
191which denies all access.
192Another predefined
193.Sy auth-group ,
194.Qq Ar no-authentication ,
195may be used to permit access
196without authentication.
197Note that targets must only use one of
198.Sy auth-group , chap , No or Sy chap-mutual ;
199it is a configuration error to mix multiple types in one target.
200.It Ic auth-type Ar type
201Sets the authentication type.
202Type can be either
203.Qq Ar none ,
204.Qq Ar deny ,
205.Qq Ar chap ,
206or
207.Qq Ar chap-mutual .
208In most cases it is not necessary to set the type using this clause;
209it is usually used to disable authentication for a given
210.Sy target .
211This clause is mutually exclusive with
212.Sy auth-group ;
213one cannot use
214both in a single target.
215.It Ic chap Ar user Ar secret
216A set of CHAP authentication credentials.
217Note that targets must only use one of
218.Sy auth-group , chap , No or Sy chap-mutual ;
219it is a configuration error to mix multiple types in one target.
220.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
221A set of mutual CHAP authentication credentials.
222Note that targets must only use one of
223.Sy auth-group , chap , No or Sy chap-mutual ;
224it is a configuration error to mix multiple types in one target.
225.It Ic initiator-name Ar initiator-name
226An iSCSI initiator name.
227Only initiators with a name matching one of the defined
228names will be allowed to connect.
229If not defined, there will be no restrictions based on initiator
230name.
231This clause is mutually exclusive with
232.Sy auth-group ;
233one cannot use
234both in a single target.
235.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
236An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
237followed by a literal slash and a prefix length.
238Only initiators with an address matching one of the defined
239addresses will be allowed to connect.
240If not defined, there will be no restrictions based on initiator
241address.
242This clause is mutually exclusive with
243.Sy auth-group ;
244one cannot use
245both in a single target.
246.It Ic portal-group Ar name
247Assign a previously defined portal group to the target.
248The default portal group is
249.Qq Ar default ,
250which makes the target available
251on TCP port 3260 on all configured IPv4 and IPv6 addresses.
252.It Ic lun Ar number
253Create a
254.Sy lun
255configuration context, defining a LUN exported by the parent target.
256.El
257.Ss lun Context
258.Bl -tag -width indent
259.It Ic backend Ar block No | Ar ramdisk
260The CTL backend to use for a given LUN.
261Valid choices are
262.Qq Ar block
263and
264.Qq Ar ramdisk ;
265block is used for LUNs backed
266by files or disk device nodes; ramdisk is a bitsink device, used mostly for
267testing.
268The default backend is block.
269.It Ic blocksize Ar size
270The blocksize visible to the initiator.
271The default blocksize is 512.
272.It Ic device-id Ar string
273The SCSI Device Identification string presented to the initiator.
274.It Ic option Ar name Ar value
275The CTL-specific options passed to the kernel.
276All CTL-specific options are documented in the
277.Sx OPTIONS
278section of
279.Xr ctladm 8 .
280.It Ic path Ar path
281The path to the file or device node used to back the LUN.
282.It Ic serial Ar string
283The SCSI serial number presented to the initiator.
284.It Ic size Ar size
285The LUN size, in bytes.
286.El
287.Sh FILES
288.Bl -tag -width ".Pa /etc/ctl.conf" -compact
289.It Pa /etc/ctl.conf
290The default location of the
291.Xr ctld 8
292configuration file.
293.El
294.Sh EXAMPLES
295.Bd -literal
296pidfile /var/run/ctld.pid
297
298auth-group example2 {
299 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
300 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
301}
302
303portal-group example2 {
304 discovery-auth-group no-authentication
305 listen 127.0.0.1
306 listen 0.0.0.0:3261
307 listen [::]:3261
308 listen [fe80::be:ef]
309}
310
311target iqn.2012-06.com.example:target0 {
312 alias "Example target"
313 auth-group no-authentication
314 lun 0 {
315 path /dev/zvol/example_0
316 blocksize 4096
317 size 4G
318 }
319}
320
321target iqn.2012-06.com.example:target3 {
322 chap chapuser chapsecret
323 lun 0 {
324 path /dev/zvol/example_3
325 }
326}
327
328target iqn.2012-06.com.example:target2 {
329 auth-group example2
330 portal-group example2
331 lun 0 {
332 path /dev/zvol/example2_0
333 }
334 lun 1 {
335 path /dev/zvol/example2_1
336 option foo bar
337 }
338}
339.Ed
340.Sh SEE ALSO
341.Xr ctl 4 ,
342.Xr ctladm 8 ,
343.Xr ctld 8
344.Sh AUTHORS
345The
346.Nm
347configuration file functionality for
348.Xr ctld 8
349was developed by
350.An Edward Tomasz Napierala Aq trasz@FreeBSD.org
351under 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 274873 2014-11-22 17:56:03Z trasz $
29.\"
30.Dd October 22, 2014
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 target Ar name {
64.Dl auth-group Ar name
65.Dl portal-group Ar name
66.Dl lun Ar number No {
67.Dl path Ar path
68.Dl }
69.Dl ...
70}
71.Ed
72.Ss Global Context
73.Bl -tag -width indent
74.It Ic auth-group Ar name
75Create an
76.Sy auth-group
77configuration context,
78defining a new auth-group,
79which can then be assigned to any number of targets.
80.It Ic debug Ar level
81The debug verbosity level.
82The default is 0.
83.It Ic maxproc Ar number
84The limit for concurrently running child processes handling
85incoming connections.
86The default is 30.
87A setting of 0 disables the limit.
88.It Ic pidfile Ar path
89The path to the pidfile.
90The default is
91.Pa /var/run/ctld.pid .
92.It Ic portal-group Ar name
93Create a
94.Sy portal-group
95configuration context,
96defining a new portal-group,
97which can then be assigned to any number of targets.
98.It Ic target Ar name
99Create a
100.Sy target
101configuration context, which can contain one or more
102.Sy lun
103contexts.
104.It Ic timeout Ar seconds
105The timeout for login sessions, after which the connection
106will be forcibly terminated.
107The default is 60.
108A setting of 0 disables the timeout.
109.El
110.Ss auth-group Context
111.Bl -tag -width indent
112.It Ic auth-type Ar type
113Sets the authentication type.
114Type can be either
115.Qq Ar none ,
116.Qq Ar deny ,
117.Qq Ar chap ,
118or
119.Qq Ar chap-mutual .
120In most cases it is not necessary to set the type using this clause;
121it is usually used to disable authentication for a given
122.Sy auth-group .
123.It Ic chap Ar user Ar secret
124A set of CHAP authentication credentials.
125Note that for any
126.Sy auth-group ,
127the configuration may only contain either
128.Sy chap
129or
130.Sy chap-mutual
131entries; it is an error to mix them.
132.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
133A set of mutual CHAP authentication credentials.
134Note that for any
135.Sy auth-group ,
136the configuration may only contain either
137.Sy chap
138or
139.Sy chap-mutual
140entries; it is an error to mix them.
141.It Ic initiator-name Ar initiator-name
142An iSCSI initiator name.
143Only initiators with a name matching one of the defined
144names will be allowed to connect.
145If not defined, there will be no restrictions based on initiator
146name.
147.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
148An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
149followed by a literal slash and a prefix length.
150Only initiators with an address matching one of the defined
151addresses will be allowed to connect.
152If not defined, there will be no restrictions based on initiator
153address.
154.El
155.Ss portal-group Context
156.Bl -tag -width indent
157.It Ic discovery-auth-group Ar name
158Assign a previously defined authentication group to the portal group,
159to be used for target discovery.
160By default, portal groups are assigned predefined
161.Sy auth-group
162.Qq Ar default ,
163which denies discovery.
164Another predefined
165.Sy auth-group ,
166.Qq Ar no-authentication ,
167may be used
168to permit discovery without authentication.
169.It Ic listen Ar address
170An IPv4 or IPv6 address and port to listen on for incoming connections.
171.It Ic listen-iser Ar address
172An IPv4 or IPv6 address and port to listen on for incoming connections
173using iSER (iSCSI over RDMA) protocol.
174.El
175.Ss target Context
176.Bl -tag -width indent
177.It Ic alias Ar text
178Assign a human-readable description to the target.
179There is no default.
180.It Ic auth-group Ar name
181Assign a previously defined authentication group to the target.
182By default, targets that do not specify their own auth settings,
183using clauses such as
184.Sy chap
185or
186.Sy initiator-name ,
187are assigned
188predefined
189.Sy auth-group
190.Qq Ar default ,
191which denies all access.
192Another predefined
193.Sy auth-group ,
194.Qq Ar no-authentication ,
195may be used to permit access
196without authentication.
197Note that targets must only use one of
198.Sy auth-group , chap , No or Sy chap-mutual ;
199it is a configuration error to mix multiple types in one target.
200.It Ic auth-type Ar type
201Sets the authentication type.
202Type can be either
203.Qq Ar none ,
204.Qq Ar deny ,
205.Qq Ar chap ,
206or
207.Qq Ar chap-mutual .
208In most cases it is not necessary to set the type using this clause;
209it is usually used to disable authentication for a given
210.Sy target .
211This clause is mutually exclusive with
212.Sy auth-group ;
213one cannot use
214both in a single target.
215.It Ic chap Ar user Ar secret
216A set of CHAP authentication credentials.
217Note that targets must only use one of
218.Sy auth-group , chap , No or Sy chap-mutual ;
219it is a configuration error to mix multiple types in one target.
220.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
221A set of mutual CHAP authentication credentials.
222Note that targets must only use one of
223.Sy auth-group , chap , No or Sy chap-mutual ;
224it is a configuration error to mix multiple types in one target.
225.It Ic initiator-name Ar initiator-name
226An iSCSI initiator name.
227Only initiators with a name matching one of the defined
228names will be allowed to connect.
229If not defined, there will be no restrictions based on initiator
230name.
231This clause is mutually exclusive with
232.Sy auth-group ;
233one cannot use
234both in a single target.
235.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
236An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
237followed by a literal slash and a prefix length.
238Only initiators with an address matching one of the defined
239addresses will be allowed to connect.
240If not defined, there will be no restrictions based on initiator
241address.
242This clause is mutually exclusive with
243.Sy auth-group ;
244one cannot use
245both in a single target.
246.It Ic portal-group Ar name
247Assign a previously defined portal group to the target.
248The default portal group is
249.Qq Ar default ,
250which makes the target available
251on TCP port 3260 on all configured IPv4 and IPv6 addresses.
252.It Ic lun Ar number
253Create a
254.Sy lun
255configuration context, defining a LUN exported by the parent target.
256.El
257.Ss lun Context
258.Bl -tag -width indent
259.It Ic backend Ar block No | Ar ramdisk
260The CTL backend to use for a given LUN.
261Valid choices are
262.Qq Ar block
263and
264.Qq Ar ramdisk ;
265block is used for LUNs backed
266by files or disk device nodes; ramdisk is a bitsink device, used mostly for
267testing.
268The default backend is block.
269.It Ic blocksize Ar size
270The blocksize visible to the initiator.
271The default blocksize is 512.
272.It Ic device-id Ar string
273The SCSI Device Identification string presented to the initiator.
274.It Ic option Ar name Ar value
275The CTL-specific options passed to the kernel.
276All CTL-specific options are documented in the
277.Sx OPTIONS
278section of
279.Xr ctladm 8 .
280.It Ic path Ar path
281The path to the file or device node used to back the LUN.
282.It Ic serial Ar string
283The SCSI serial number presented to the initiator.
284.It Ic size Ar size
285The LUN size, in bytes.
286.El
287.Sh FILES
288.Bl -tag -width ".Pa /etc/ctl.conf" -compact
289.It Pa /etc/ctl.conf
290The default location of the
291.Xr ctld 8
292configuration file.
293.El
294.Sh EXAMPLES
295.Bd -literal
296pidfile /var/run/ctld.pid
297
298auth-group example2 {
299 chap-mutual "user" "secret" "mutualuser" "mutualsecret"
300 chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
301}
302
303portal-group example2 {
304 discovery-auth-group no-authentication
305 listen 127.0.0.1
306 listen 0.0.0.0:3261
307 listen [::]:3261
308 listen [fe80::be:ef]
309}
310
311target iqn.2012-06.com.example:target0 {
312 alias "Example target"
313 auth-group no-authentication
314 lun 0 {
315 path /dev/zvol/example_0
316 blocksize 4096
317 size 4G
318 }
319}
320
321target iqn.2012-06.com.example:target3 {
322 chap chapuser chapsecret
323 lun 0 {
324 path /dev/zvol/example_3
325 }
326}
327
328target iqn.2012-06.com.example:target2 {
329 auth-group example2
330 portal-group example2
331 lun 0 {
332 path /dev/zvol/example2_0
333 }
334 lun 1 {
335 path /dev/zvol/example2_1
336 option foo bar
337 }
338}
339.Ed
340.Sh SEE ALSO
341.Xr ctl 4 ,
342.Xr ctladm 8 ,
343.Xr ctld 8
344.Sh AUTHORS
345The
346.Nm
347configuration file functionality for
348.Xr ctld 8
349was developed by
350.An Edward Tomasz Napierala Aq trasz@FreeBSD.org
351under sponsorship from the FreeBSD Foundation.