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