libexec/ftpd/ftpd.conf.5

   1 .\"     $NetBSD: ftpd.conf.5,v 1.36 2008/09/13 02:41:52 lukem 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.