xref: /freebsd/usr.sbin/ctld/ctl.conf.5 (revision 0e97acdf58fe27b09c4824a474b0344daf997c5f)
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$
29.\"
30.Dd October 29, 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 discovery-filter Ar filter
179Determines which targets are returned during discovery.
180Filter can be either
181.Qq Ar none ,
182.Qq Ar portal ,
183.Qq Ar portal-name ,
184or
185.Qq Ar portal-name-auth .
186When set to
187.Qq Ar none ,
188discovery will return all targets assigned to that portal group.
189When set to
190.Qq Ar portal ,
191discovery will not return targets that cannot be accessed by the
192initiator because of their
193.Sy initiator-portal .
194When set to
195.Qq Ar portal-name ,
196the check will include both
197.Sy initiator-portal
198and
199.Sy initiator-name .
200When set to
201.Qq Ar portal-name-auth ,
202the check will include
203.Sy initiator-portal ,
204.Sy initiator-name ,
205and authentication credentials, ie. if the target does not require
206CHAP authentication, or if CHAP user and secret used during discovery
207match CHAP user and secret required to access the target.
208Note that when using
209.Qq Ar portal-name-auth ,
210targets that require CHAP authentication will only be returned if
211.Sy discovery-auth-group
212requires CHAP.
213The default is
214.Qq Ar none .
215.It Ic listen Ar address
216An IPv4 or IPv6 address and port to listen on for incoming connections.
217.\".It Ic listen-iser Ar address
218.\"An IPv4 or IPv6 address and port to listen on for incoming connections
219.\"using iSER (iSCSI over RDMA) protocol.
220.El
221.Ss target Context
222.Bl -tag -width indent
223.It Ic alias Ar text
224Assign a human-readable description to the target.
225There is no default.
226.It Ic auth-group Ar name
227Assign a previously defined authentication group to the target.
228By default, targets that do not specify their own auth settings,
229using clauses such as
230.Sy chap
231or
232.Sy initiator-name ,
233are assigned
234predefined
235.Sy auth-group
236.Qq Ar default ,
237which denies all access.
238Another predefined
239.Sy auth-group ,
240.Qq Ar no-authentication ,
241may be used to permit access
242without authentication.
243Note that targets must only use one of
244.Sy auth-group , chap , No or Sy chap-mutual ;
245it is a configuration error to mix multiple types in one target.
246.It Ic auth-type Ar type
247Sets the authentication type.
248Type can be either
249.Qq Ar none ,
250.Qq Ar deny ,
251.Qq Ar chap ,
252or
253.Qq Ar chap-mutual .
254In most cases it is not necessary to set the type using this clause;
255it is usually used to disable authentication for a given
256.Sy target .
257This clause is mutually exclusive with
258.Sy auth-group ;
259one cannot use
260both in a single target.
261.It Ic chap Ar user Ar secret
262A set of CHAP authentication credentials.
263Note that targets must only use one of
264.Sy auth-group , chap , No or Sy chap-mutual ;
265it is a configuration error to mix multiple types in one target.
266.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
267A set of mutual CHAP authentication credentials.
268Note that targets must only use one of
269.Sy auth-group , chap , No or Sy chap-mutual ;
270it is a configuration error to mix multiple types in one target.
271.It Ic initiator-name Ar initiator-name
272An iSCSI initiator name.
273Only initiators with a name matching one of the defined
274names will be allowed to connect.
275If not defined, there will be no restrictions based on initiator
276name.
277This clause is mutually exclusive with
278.Sy auth-group ;
279one cannot use
280both in a single target.
281.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
282An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
283followed by a literal slash and a prefix length.
284Only initiators with an address matching one of the defined
285addresses will be allowed to connect.
286If not defined, there will be no restrictions based on initiator
287address.
288This clause is mutually exclusive with
289.Sy auth-group ;
290one cannot use
291both in a single target.
292.It Ic portal-group Ar name
293Assign a previously defined portal group to the target.
294The default portal group is
295.Qq Ar default ,
296which makes the target available
297on TCP port 3260 on all configured IPv4 and IPv6 addresses.
298.It Ic lun Ar number
299Create a
300.Sy lun
301configuration context, defining a LUN exported by the parent target.
302.El
303.Ss lun Context
304.Bl -tag -width indent
305.It Ic backend Ar block No | Ar ramdisk
306The CTL backend to use for a given LUN.
307Valid choices are
308.Qq Ar block
309and
310.Qq Ar ramdisk ;
311block is used for LUNs backed
312by files or disk device nodes; ramdisk is a bitsink device, used mostly for
313testing.
314The default backend is block.
315.It Ic blocksize Ar size
316The blocksize visible to the initiator.
317The default blocksize is 512.
318.It Ic device-id Ar string
319The SCSI Device Identification string presented to the initiator.
320.It Ic option Ar name Ar value
321The CTL-specific options passed to the kernel.
322All CTL-specific options are documented in the
323.Sx OPTIONS
324section of
325.Xr ctladm 8 .
326.It Ic path Ar path
327The path to the file or device node used to back the LUN.
328.It Ic serial Ar string
329The SCSI serial number presented to the initiator.
330.It Ic size Ar size
331The LUN size, in bytes.
332.El
333.Sh FILES
334.Bl -tag -width ".Pa /etc/ctl.conf" -compact
335.It Pa /etc/ctl.conf
336The default location of the
337.Xr ctld 8
338configuration file.
339.El
340.Sh EXAMPLES
341.Bd -literal
342pidfile	/var/run/ctld.pid
343
344auth-group ag0 {
345	chap-mutual "user" "secret" "mutualuser" "mutualsecret"
346	chap-mutual "user2" "secret2" "mutualuser" "mutualsecret"
347	initiator-portal 192.168.1.1/16
348}
349
350auth-group ag1 {
351	auth-type none
352	initiator-name "iqn.2012-06.com.example:initiatorhost1"
353	initiator-name "iqn.2012-06.com.example:initiatorhost2"
354	initiator-portal 192.168.1.1/24
355	initiator-portal [2001:db8::de:ef]
356}
357
358portal-group pg0 {
359	discovery-auth-group no-authentication
360	listen 0.0.0.0:3260
361	listen [::]:3260
362	listen [fe80::be:ef]:3261
363}
364
365target iqn.2012-06.com.example:target0 {
366	alias "Example target"
367	auth-group no-authentication
368	lun 0 {
369		path /dev/zvol/tank/example_0
370		blocksize 4096
371		size 4G
372	}
373}
374
375target iqn.2012-06.com.example:target1 {
376	chap chapuser chapsecret
377	lun 0 {
378		path /dev/zvol/tank/example_1
379	}
380}
381
382target iqn.2012-06.com.example:target2 {
383	auth-group ag0
384	portal-group pg0
385	lun 0 {
386		path /dev/zvol/tank/example2_0
387	}
388	lun 1 {
389		path /dev/zvol/tank/example2_1
390		option foo bar
391	}
392}
393.Ed
394.Sh SEE ALSO
395.Xr ctl 4 ,
396.Xr ctladm 8 ,
397.Xr ctld 8
398.Sh AUTHORS
399The
400.Nm
401configuration file functionality for
402.Xr ctld 8
403was developed by
404.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org
405under sponsorship from the FreeBSD Foundation.
406