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.\"
| 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.\"
|
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.
| 71.Dl lun Ar number Ar name
72.Dl lun Ar number No {
73.Dl path Ar path
74.Dl }
75.Dl ...
76}
77.Ed
78.Ss Global Context
79.Bl -tag -width indent
80.It Ic auth-group Ar name
81Create an
82.Sy auth-group
83configuration context,
84defining a new auth-group,
85which can then be assigned to any number of targets.
86.It Ic debug Ar level
87The debug verbosity level.
88The default is 0.
89.It Ic maxproc Ar number
90The limit for concurrently running child processes handling
91incoming connections.
92The default is 30.
93A setting of 0 disables the limit.
94.It Ic pidfile Ar path
95The path to the pidfile.
96The default is
97.Pa /var/run/ctld.pid .
98.It Ic portal-group Ar name
99Create a
100.Sy portal-group
101configuration context,
102defining a new portal-group,
103which can then be assigned to any number of targets.
104.It Ic lun Ar name
105Create a
106.Sy lun
107configuration context, defining a LUN to be exported by some target(s).
108.It Ic target Ar name
109Create a
110.Sy target
111configuration context, which can contain one or more
112.Sy lun
113contexts.
114.It Ic timeout Ar seconds
115The timeout for login sessions, after which the connection
116will be forcibly terminated.
117The default is 60.
118A setting of 0 disables the timeout.
119.It Ic isns-server Ar address
120An IPv4 or IPv6 address and optionally port of iSNS server to register on.
121.It Ic isns-period Ar seconds
122iSNS registration period.
123Registered Network Entity not updated during this period will be unregistered.
124The default is 900.
125.It Ic isns-timeout Ar seconds
126Timeout for iSNS requests.
127The default is 5.
128.El
129.Ss auth-group Context
130.Bl -tag -width indent
131.It Ic auth-type Ar type
132Sets the authentication type.
133Type can be either
134.Qq Ar none ,
135.Qq Ar deny ,
136.Qq Ar chap ,
137or
138.Qq Ar chap-mutual .
139In most cases it is not necessary to set the type using this clause;
140it is usually used to disable authentication for a given
141.Sy auth-group .
142.It Ic chap Ar user Ar secret
143A set of CHAP authentication credentials.
144Note that for any
145.Sy auth-group ,
146the configuration may only contain either
147.Sy chap
148or
149.Sy chap-mutual
150entries; it is an error to mix them.
151.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
152A set of mutual CHAP authentication credentials.
153Note that for any
154.Sy auth-group ,
155the configuration may only contain either
156.Sy chap
157or
158.Sy chap-mutual
159entries; it is an error to mix them.
160.It Ic initiator-name Ar initiator-name
161An iSCSI initiator name.
162Only initiators with a name matching one of the defined
163names will be allowed to connect.
164If not defined, there will be no restrictions based on initiator
165name.
166.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
167An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
168followed by a literal slash and a prefix length.
169Only initiators with an address matching one of the defined
170addresses will be allowed to connect.
171If not defined, there will be no restrictions based on initiator
172address.
173.El
174.Ss portal-group Context
175.Bl -tag -width indent
176.It Ic discovery-auth-group Ar name
177Assign a previously defined authentication group to the portal group,
178to be used for target discovery.
179By default, portal groups are assigned predefined
180.Sy auth-group
181.Qq Ar default ,
182which denies discovery.
183Another predefined
184.Sy auth-group ,
185.Qq Ar no-authentication ,
186may be used
187to permit discovery without authentication.
188.It Ic discovery-filter Ar filter
189Determines which targets are returned during discovery.
190Filter can be either
191.Qq Ar none ,
192.Qq Ar portal ,
193.Qq Ar portal-name ,
194or
195.Qq Ar portal-name-auth .
196When set to
197.Qq Ar none ,
198discovery will return all targets assigned to that portal group.
199When set to
200.Qq Ar portal ,
201discovery will not return targets that cannot be accessed by the
202initiator because of their
203.Sy initiator-portal .
204When set to
205.Qq Ar portal-name ,
206the check will include both
207.Sy initiator-portal
208and
209.Sy initiator-name .
210When set to
211.Qq Ar portal-name-auth ,
212the check will include
213.Sy initiator-portal ,
214.Sy initiator-name ,
215and authentication credentials.
216The target is returned if it does not require CHAP authentication,
217or if the CHAP user and secret used during discovery match those
218used by the target.
219Note that when using
220.Qq Ar portal-name-auth ,
221targets that require CHAP authentication will only be returned if
222.Sy discovery-auth-group
223requires CHAP.
224The default is
225.Qq Ar none .
226.It Ic listen Ar address
227An IPv4 or IPv6 address and port to listen on for incoming connections.
228.\".It Ic listen-iser Ar address
229.\"An IPv4 or IPv6 address and port to listen on for incoming connections
230.\"using iSER (iSCSI over RDMA) protocol.
231.It Ic redirect Aq Ar address
232IPv4 or IPv6 address to redirect initiators to.
233When configured, all initiators attempting to connect to portal
234belonging to this
235.Sy portal-group
236will get redirected using "Target moved temporarily" login response.
237Redirection happens before authentication and any
238.Sy initiator-name
239or
240.Sy initiator-portal
241checks are skipped.
242.El
243.Ss target Context
244.Bl -tag -width indent
245.It Ic alias Ar text
246Assign a human-readable description to the target.
247There is no default.
248.It Ic auth-group Ar name
249Assign a previously defined authentication group to the target.
250By default, targets that do not specify their own auth settings,
251using clauses such as
252.Sy chap
253or
254.Sy initiator-name ,
255are assigned
256predefined
257.Sy auth-group
258.Qq Ar default ,
259which denies all access.
260Another predefined
261.Sy auth-group ,
262.Qq Ar no-authentication ,
263may be used to permit access
264without authentication.
265Note that targets must only use one of
266.Sy auth-group , chap , No or Sy chap-mutual ;
267it is a configuration error to mix multiple types in one target.
268.It Ic auth-type Ar type
269Sets the authentication type.
270Type can be either
271.Qq Ar none ,
272.Qq Ar deny ,
273.Qq Ar chap ,
274or
275.Qq Ar chap-mutual .
276In most cases it is not necessary to set the type using this clause;
277it is usually used to disable authentication for a given
278.Sy target .
279This clause is mutually exclusive with
280.Sy auth-group ;
281one cannot use
282both in a single target.
283.It Ic chap Ar user Ar secret
284A set of CHAP authentication credentials.
285Note that targets must only use one of
286.Sy auth-group , chap , No or Sy chap-mutual ;
287it is a configuration error to mix multiple types in one target.
288.It Ic chap-mutual Ar user Ar secret Ar mutualuser Ar mutualsecret
289A set of mutual CHAP authentication credentials.
290Note that targets must only use one of
291.Sy auth-group , chap , No or Sy chap-mutual ;
292it is a configuration error to mix multiple types in one target.
293.It Ic initiator-name Ar initiator-name
294An iSCSI initiator name.
295Only initiators with a name matching one of the defined
296names will be allowed to connect.
297If not defined, there will be no restrictions based on initiator
298name.
299This clause is mutually exclusive with
300.Sy auth-group ;
301one cannot use
302both in a single target.
303.It Ic initiator-portal Ar address Ns Op / Ns Ar prefixlen
304An iSCSI initiator portal: an IPv4 or IPv6 address, optionally
305followed by a literal slash and a prefix length.
306Only initiators with an address matching one of the defined
307addresses will be allowed to connect.
308If not defined, there will be no restrictions based on initiator
309address.
310This clause is mutually exclusive with
311.Sy auth-group ;
312one cannot use
313both in a single target.
314.It Ic portal-group Ar name Op Ar agname
315Assign a previously defined portal group to the target.
316The default portal group is
317.Qq Ar default ,
318which makes the target available
319on TCP port 3260 on all configured IPv4 and IPv6 addresses.
320Optional second argument specifies auth group name for connections
321to this specific portal group.
322If second argument is not specified, target auth group is used.
|