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