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