The first a bug in pax and should be commited to FBSD, too.
[dragonfly.git] / contrib / lukemftpd / src / ftpd.conf.5
1 .\"     $NetBSD: ftpd.conf.5,v 1.19 2002/01/15 02:20:50 wiz Exp $
2 .\"
3 .\" Copyright (c) 1997-2001 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Luke Mewburn.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\"    notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\"    notice, this list of conditions and the following disclaimer in the
16 .\"    documentation and/or other materials provided with the distribution.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\"    must display the following acknowledgement:
19 .\"        This product includes software developed by the NetBSD
20 .\"        Foundation, Inc. and its contributors.
21 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
22 .\"    contributors may be used to endorse or promote products derived
23 .\"    from this software without specific prior written permission.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35 .\" POSSIBILITY OF SUCH DAMAGE.
36 .\"
37 .Dd December 5, 2001
38 .Dt FTPD.CONF 5
39 .Os
40 .Sh NAME
41 .Nm ftpd.conf
42 .Nd
43 .Xr ftpd 8
44 configuration file
45 .Sh DESCRIPTION
46 The
47 .Nm
48 file specifies various configuration options for
49 .Xr ftpd 8
50 that apply once a user has authenticated their connection.
51 .Pp
52 .Nm
53 consists of a series of lines, each of which may contain a
54 configuration directive, a comment, or a blank line.
55 Directives that appear later in the file override settings by previous
56 directives.
57 This allows
58 .Sq wildcard
59 entries to define defaults, and then have class-specific overrides.
60 .Pp
61 A directive line has the format:
62 .Dl command class [arguments]
63 .Pp
64 A
65 .Dq \e
66 is the escape character; it can be used to escape the meaning of the
67 comment character, or if it is the last character on a line, extends
68 a configuration directive across multiple lines.
69 A
70 .Dq #
71 is the comment character, and all characters from it to the end of
72 line are ignored (unless it is escaped with the escape character).
73 .Pp
74 Each authenticated user is a member of a
75 .Em class ,
76 which is determined by
77 .Xr ftpusers 5 .
78 .Em class
79 is used to determine which
80 .Nm
81 entries apply to the user.
82 The following special classes exist when parsing entries in
83 .Nm "" :
84 .Bl -tag -width "chroot" -compact -offset indent
85 .It Sy all
86 Matches any class.
87 .It Sy none
88 Matches no class.
89 .El
90 .Pp
91 Each class has a type, which may be one of:
92 .Bl -tag -width "CHROOT" -offset indent
93 .It Sy GUEST
94 Guests (as per the
95 .Dq anonymous
96 and
97 .Dq ftp
98 logins).
99 A
100 .Xr chroot 2
101 is performed after login.
102 .It Sy CHROOT
103 .Xr chroot 2 ed
104 users (as per
105 .Xr ftpchroot 5 ) .
106 A
107 .Xr chroot 2
108 is performed after login.
109 .It Sy REAL
110 Normal users.
111 .El
112 .Pp
113 The
114 .Xr ftpd 8
115 .Sy STAT
116 command will return the class settings for the current user as defined by
117 .Nm "" ,
118 unless the
119 .Sy private
120 directive is set for the class.
121 .Pp
122 Each configuration line may be one of:
123 .Bl -tag -width 4n
124 .It Sy advertise Ar class Ar host
125 .It Sy advertize Ar class Ar host
126 Set the address to advertise in the response to the
127 .Sy PASV
128 and
129 .Sy LPSV
130 commands to the address for
131 .Ar host
132 (which may be either a host name or IP address).
133 This may be useful in some firewall configurations, although many
134 ftp clients may not work if the address being advertised is different
135 to the address that they've connected to.
136 If
137 .Ar class
138 is
139 .Dq none
140 or no argument is given, disable this.
141 .It Sy checkportcmd Ar class Op Sy off
142 Check the
143 .Sy PORT
144 command for validity.
145 The
146 .Sy PORT
147 command will fail if the IP address specified does not match the
148 .Tn FTP
149 command connection, or if the remote TCP port number is less than
150 .Dv IPPORT_RESERVED .
151 It is
152 .Em strongly
153 encouraged that this option be used, espcially for sites concerned
154 with potential security problems with
155 .Tn FTP
156 bounce attacks.
157 If
158 .Ar class
159 is
160 .Dq none
161 or
162 .Sy off
163 is given, disable this feature, otherwise enable it.
164 .It Sy chroot Ar class Op Sy pathformat
165 If
166 .Ar pathformat
167 is not given or
168 .Ar class
169 is
170 .Dq none ,
171 use the default behaviour (see below).
172 Otherwise,
173 .Ar pathformat
174 is parsed to create a directory to create as the root directory with
175 .Xr chroot 2
176 into upon login.
177 .Pp
178 .Ar pathformat
179 can contain the following escape strings:
180 .Bl -tag -width "Escape" -offset indent -compact
181 .It Sy "Escape"
182 .Sy Description
183 .It "\&%c"
184 Class name.
185 .It "\&%d"
186 Home directory of user.
187 .It "\&%u"
188 User name.
189 .It "\&%\&%"
190 A
191 .Dq \&%
192 character.
193 .El
194 .Pp
195 The default root directory is:
196 .Bl -tag -width "CHROOT" -offset indent -compact
197 .It Sy CHROOT
198 The user's home directory.
199 .It Sy GUEST
200 If
201 .Fl a Ar anondir
202 is given, use
203 .Ar anondir ,
204 otherwise the home directory of the
205 .Sq ftp
206 user.
207 .It Sy REAL
208 By default no
209 .Xr chroot 2
210 is performed.
211 .El
212 .It Sy classtype Ar class Ar type
213 Set the class type of
214 .Ar class
215 to
216 .Ar type
217 (see above).
218 .It Xo Sy conversion Ar class
219 .Ar suffix Op Ar "type disable command"
220 .Xc
221 Define an automatic in-line file conversion.
222 If a file to retrieve ends in
223 .Ar suffix ,
224 and a real file (sans
225 .Ar suffix )
226 exists, then the output of
227 .Ar command
228 is returned instead of the contents of the file.
229 .Pp
230 .Bl -tag -width "disable" -offset indent
231 .It Ar suffix
232 The suffix to initiate the conversion.
233 .It Ar type
234 A list of valid filetypes for the conversion.
235 Valid types are:
236 .Sq f
237 (file), and
238 .Sq d
239 (directory).
240 .It Ar disable
241 The name of file that will prevent conversion if it exists.
242 A file name of
243 .Dq Pa \&.
244 will prevent this disabling action
245 (i.e., the conversion is always permitted.)
246 .It Ar command
247 The command to run for the conversion.
248 The first word should be the full path name
249 of the command, as
250 .Xr execv 3
251 is used to execute the command.
252 All instances of the word
253 .Dq %s
254 in
255 .Ar command
256 are replaced with the requested file (sans
257 .Ar suffix ) .
258 .El
259 .Pp
260 Conversion directives specified later in the file override earlier
261 conversions with the same suffix.
262 .It Sy denyquick Ar class Op Sy off
263 Enforce
264 .Xr ftpusers 5
265 rules after the
266 .Sy USER
267 command is received, rather than after the
268 .Sy PASS
269 command is received.
270 Whilst enabling this feature may allow information leakage about
271 available accounts (for example, if you allow some users of a
272 .Sy REAL
273 or
274 .Sy CHROOT
275 class but not others), it is useful in preventing a denied user
276 (such as
277 .Sq root )
278 from entering their password across an insecure connection.
279 This option is
280 .Em strongly
281 recommended for servers which run an anonymous-only service.
282 If
283 .Ar class
284 is
285 .Dq none
286 or
287 .Sy off
288 is given, disable this feature, otherwise enable it.
289 .It Sy display Ar class Op Ar file
290 If
291 .Ar file
292 is not given or
293 .Ar class
294 is
295 .Dq none ,
296 disable this.
297 Otherwise, each time the user enters a new directory, check if
298 .Ar file
299 exists, and if so, display its contents to the user.
300 Escape sequences are supported; refer to
301 .Sx Display file escape sequences
302 in
303 .Xr ftpd 8
304 for more information.
305 .It Sy homedir Ar class Op Sy pathformat
306 If
307 .Ar pathformat
308 is not given or
309 .Ar class
310 is
311 .Dq none ,
312 use the default behaviour (see below).
313 Otherwise,
314 .Ar pathformat
315 is parsed to create a directory to change into upon login, and to use
316 as the
317 .Sq home
318 directory of the user for tilde expansion in pathnames, etc.
319 .Ar pathformat
320 is parsed as per the
321 .Sy chroot
322 directive.
323 .Pp
324 The default home directory is the home directory of the user for
325 .Sy REAL
326 users, and
327 .Pa /
328 for
329 .Sy GUEST
330 and
331 .Sy CHROOT
332 users.
333 .It Xo Sy limit Ar class
334 .Ar count Op Ar file
335 .Xc
336 Limit the maximum number of concurrent connections for
337 .Ar class
338 to
339 .Ar count ,
340 with
341 .Sq 0
342 meaning unlimited connections.
343 If the limit is exceeded and
344 .Ar file
345 is given, display its contents to the user.
346 If
347 .Ar class
348 is
349 .Dq none
350 or
351 .Ar count
352 is not specified, disable this.
353 If
354 .Ar file
355 is a relative path, it will be searched for in
356 .Pa /etc
357 (which can be overridden with
358 .Fl c Ar confdir ) .
359 .It Sy maxfilesize Ar class Ar size
360 Set the maximum size of an uploaded file to
361 .Ar size .
362 If
363 .Ar class
364 is
365 .Dq none
366 or no argument is given, disable this.
367 .It Sy maxtimeout Ar class Ar time
368 Set the maximum timeout period that a client may request,
369 defaulting to two hours.
370 This cannot be less than 30 seconds, or the value for
371 .Sy timeout .
372 If
373 .Ar class
374 is
375 .Dq none
376 or
377 .Ar time
378 is not specified, set to default of 2 hours.
379 .It Sy modify Ar class Op Sy off
380 If
381 .Ar class
382 is
383 .Dq none
384 or
385 .Sy off
386 is given, disable the following commands:
387 .Sy CHMOD ,
388 .Sy DELE ,
389 .Sy MKD ,
390 .Sy RMD ,
391 .Sy RNFR ,
392 and
393 .Sy UMASK .
394 Otherwise, enable them.
395 .It Sy motd Ar class Op Ar file
396 If
397 .Ar file
398 is not given or
399 .Ar class
400 is
401 .Dq none ,
402 disable this.
403 Otherwise, use
404 .Ar file
405 as the message of the day file to display after login.
406 Escape sequences are supported; refer to
407 .Sx Display file escape sequences
408 in
409 .Xr ftpd 8
410 for more information.
411 If
412 .Ar file
413 is a relative path, it will be searched for in
414 .Pa /etc
415 (which can be overridden with
416 .Fl c Ar confdir ) .
417 .It Sy notify Ar class Op Ar fileglob
418 If
419 .Ar fileglob
420 is not given or
421 .Ar class
422 is
423 .Dq none ,
424 disable this.
425 Otherwise, each time the user enters a new directory,
426 notify the user of any files matching
427 .Ar fileglob .
428 .It Sy passive Ar class Op Sy off
429 If
430 .Ar class
431 is
432 .Dq none
433 or
434 .Sy off
435 is given, prevent passive
436 .Sy ( PASV ,
437 .Sy LPSV ,
438 and
439 .Sy EPSV )
440 connections.
441 Otherwise, enable them.
442 .It Sy portrange Ar class Ar min Ar max
443 Set the range of port number which will be used for the passive data port.
444 .Ar max
445 must be greater than
446 .Ar min ,
447 and both numbers must be be between
448 .Dv IPPORT_RESERVED
449 (1024) and 65535.
450 If
451 .Ar class
452 is
453 .Dq none
454 or no arguments are given, disable this.
455 .It Sy private Ar class Op Sy off
456 If
457 .Ar class
458 is
459 .Dq none
460 or
461 .Sy off
462 is given, do not display class information in the output of the
463 .Sy STAT
464 command.
465 Otherwise, display the information.
466 .It Sy rateget Ar class Ar rate
467 Set the maximum get
468 .Pq Sy RETR
469 transfer rate throttle for
470 .Ar class
471 to
472 .Ar rate
473 bytes per second.
474 If
475 .Ar rate
476 is 0, the throttle is disabled.
477 If
478 .Ar class
479 is
480 .Dq none
481 or no arguments are given, disable this.
482 .Pp
483 An optional suffix may be provided, which changes the intrepretation of
484 .Ar rate
485 as follows:
486 .Bl -tag -width 3n -offset indent -compact
487 .It b
488 Causes no modification. (Default; optional)
489 .It k
490 Kilo; multiply the argument by 1024
491 .It m
492 Mega; multiply the argument by 1048576
493 .It g
494 Giga; multiply the argument by 1073741824
495 .It t
496 Tera; multiply the argument by 1099511627776
497 .El
498 .It Sy rateput Ar class Ar rate
499 Set the maximum put
500 .Pq Sy STOR
501 transfer rate throttle for
502 .Ar class
503 to
504 .Ar rate
505 bytes per second,
506 which is parsed as per
507 .Sy rateget Ar rate .
508 If
509 .Ar class
510 is
511 .Dq none
512 or no arguments are given, disable this.
513 .It Sy sanenames Ar class Op Sy off
514 If
515 .Ar class
516 is
517 .Dq none
518 or
519 .Sy off
520 is given, allow uploaded file names to contain any characters valid for a
521 file name.
522 Otherwise, only permit file names which don't start with a
523 .Sq \&.
524 and only comprise of characters from the set
525 .Dq [-+,._A-Za-z0-9] .
526 .It Sy template Ar class Op Ar refclass
527 Define
528 .Ar refclass
529 as the
530 .Sq template
531 for
532 .Ar class ;
533 any reference to
534 .Ar refclass
535 in following directives will also apply to members of
536 .Ar class .
537 This is useful to define a template class so that other classes which are
538 to share common attributes can be easily defined without unnecessary
539 duplication.
540 There can be only one template defined at a time.
541 If
542 .Ar refclass
543 is not given, disable the template for
544 .Ar class .
545 .It Sy timeout Ar class Ar time
546 Set the inactivity timeout period.
547 (the default is fifteen minutes).
548 This cannot be less than 30 seconds, or greater than the value for
549 .Sy maxtimeout .
550 If
551 .Ar class
552 is
553 .Dq none
554 or
555 .Ar time
556 is not specified, set to the default of 15 minutes.
557 .It Sy umask Ar class Ar umaskval
558 Set the umask to
559 .Ar umaskval .
560 If
561 .Ar class
562 is
563 .Dq none
564 or
565 .Ar umaskval
566 is not specified, set to the default of
567 .Li 027 .
568 .It Sy upload Ar class Op Sy off
569 If
570 .Ar class
571 is
572 .Dq none
573 or
574 .Sy off
575 is given, disable the following commands:
576 .Sy APPE ,
577 .Sy STOR ,
578 and
579 .Sy STOU ,
580 as well as the modify commands:
581 .Sy CHMOD ,
582 .Sy DELE ,
583 .Sy MKD ,
584 .Sy RMD ,
585 .Sy RNFR ,
586 and
587 .Sy UMASK .
588 Otherwise, enable them.
589 .El
590 .Sh DEFAULTS
591 The following defaults are used:
592 .Pp
593 .Bd -literal -offset indent -compact
594 checkportcmd  all
595 classtype     chroot CHROOT
596 classtype     guest  GUEST
597 classtype     real   REAL
598 display       none
599 limit         all    -1     # unlimited connections
600 maxtimeout    all    7200   # 2 hours
601 modify        all
602 motd          all    motd
603 notify        none
604 passive       all
605 timeout       all    900    # 15 minutes
606 umask         all    027
607 upload        all
608 modify        guest  off
609 umask         guest  0707
610 .Ed
611 .Sh FILES
612 .Bl -tag -width /usr/share/examples/ftpd/ftpd.conf -compact
613 .It Pa /etc/ftpd.conf
614 This file.
615 .It Pa /usr/share/examples/ftpd/ftpd.conf
616 A sample
617 .Nm
618 file.
619 .El
620 .Sh SEE ALSO
621 .Xr ftpchroot 5 ,
622 .Xr ftpusers 5 ,
623 .Xr ftpd 8
624 .Sh HISTORY
625 The
626 .Nm
627 functionality was implemented in
628 .Nx 1.3
629 and later releases by Luke Mewburn, based on work by Simon Burge.