contrib/lukemftpd/src/ftpd.conf.5

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