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.