1 .\" $NetBSD: ftpd.8,v 1.74 2003-08-07 09:46:39 agc Exp $
3 .\" Copyright (c) 1997-2003 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
6 .\" This code is derived from software contributed to The NetBSD Foundation
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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.
37 .\" Copyright (c) 1985, 1988, 1991, 1993
38 .\" The Regents of the University of California. All rights reserved.
40 .\" Redistribution and use in source and binary forms, with or without
41 .\" modification, are permitted provided that the following conditions
43 .\" 1. Redistributions of source code must retain the above copyright
44 .\" notice, this list of conditions and the following disclaimer.
45 .\" 2. Redistributions in binary form must reproduce the above copyright
46 .\" notice, this list of conditions and the following disclaimer in the
47 .\" documentation and/or other materials provided with the distribution.
48 .\" 3. Neither the name of the University nor the names of its contributors
49 .\" may be used to endorse or promote products derived from this software
50 .\" without specific prior written permission.
52 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
53 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
54 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
55 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
56 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
57 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
58 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
59 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
60 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
61 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
64 .\" @(#)ftpd.8 8.2 (Berkeley) 4/19/94
72 Internet File Transfer Protocol server
81 .Op Fl L Ar xferlogfile
86 is the Internet File Transfer Protocol server process.
89 protocol and listens at the port specified in the
91 service specification; see
101 into for anonymous logins.
102 Default is the home directory for the ftp user.
103 This can also be specified with the
108 Change the root directory of the configuration files from
112 This changes the directory for the following files:
115 .Pa /etc/ftpwelcome ,
117 and the file specified by the
124 would be granted access under
125 the restrictions given in
127 and exit without attempting a connection.
129 exits with an exit code of 0 if access would be granted, or 1 otherwise.
130 This can be useful for testing configurations.
132 Debugging information is written to the syslog using a facility of
134 .It Fl e Ar emailaddr
140 .Sx Display file escape sequences )
142 Explicitly set the hostname to advertise as to
144 The default is the hostname associated with the IP address that
147 This ability (with or without
151 is useful when configuring
154 servers, each listening on separate addresses as separate names.
157 for more information on starting services to listen on specific IP addresses.
165 Each successful and failed
167 session is logged using syslog with a facility of
169 If this option is specified more than once, the retrieve (get), store (put),
170 append, delete, make directory, remove directory and rename operations and
171 their file name arguments are also logged.
172 .It Fl L Ar xferlogfile
182 as the data port, overriding the default of using the port one less
187 Enable the use of pid files for keeping track of the number of logged-in
191 Disable the use of pid files for keeping track of the number of logged-in
193 This may reduce the load on heavily loaded
197 Permanently drop root privileges once the user is logged in.
198 The use of this option may result in the server using a port other
199 than the (listening-port - 1) for
201 style commands, which is contrary to the
203 specification, but in practice very few clients rely upon this behaviour.
205 .Sx SECURITY CONSIDERATIONS
206 below for more details.
208 Require a secure authentication mechanism like Kerberos or S/Key to be used.
214 making them visible to commands such as
217 Don't log each concurrent
225 as the version to advertise in the login banner and in the output of
229 instead of the default version information.
234 then don't display any version information.
240 making them visible to commands such as
253 entries to the syslog, prefixed with
257 These syslog entries can be converted to a
261 file suitable for input into a third-party log analysis tool with a command
263 .Dl "grep 'xferlog: ' /var/log/xferlog | \e"
264 .Dl "\ \ \ sed -e 's/^.*xferlog: //' \*[Gt] wuxferlog"
269 can be used to disable
274 displays it and exits.
279 prints it before issuing the
284 exists (under the chroot directory if applicable),
286 prints it after a successful login.
287 This may be changed with the
294 server currently supports the following
297 The case of the requests is ignored.
298 .Bl -column "Request" -offset indent
299 .It Sy Request Ta Sy Description
300 .It ABOR Ta "abort previous command"
301 .It ACCT Ta "specify account (ignored)"
302 .It ALLO Ta "allocate storage (vacuously)"
303 .It APPE Ta "append to a file"
304 .It CDUP Ta "change to parent of current working directory"
305 .It CWD Ta "change working directory"
306 .It DELE Ta "delete a file"
307 .It EPSV Ta "prepare for server-to-server transfer"
308 .It EPRT Ta "specify data connection port"
309 .It FEAT Ta "list extra features that are not defined in" Cm "RFC 959"
310 .It HELP Ta "give help information"
311 .It LIST Ta "give list files in a directory" Pq Dq Li "ls -lA"
312 .It LPSV Ta "prepare for server-to-server transfer"
313 .It LPRT Ta "specify data connection port"
314 .It MLSD Ta "list contents of directory in a machine-processable form"
315 .It MLST Ta "show a pathname in a machine-processable form"
316 .It MKD Ta "make a directory"
317 .It MDTM Ta "show last modification time of file"
318 .It MODE Ta "specify data transfer" Em mode
319 .It NLST Ta "give name list of files in directory"
320 .It NOOP Ta "do nothing"
321 .It OPTS Ta "define persistent options for a given command"
322 .It PASS Ta "specify password"
323 .It PASV Ta "prepare for server-to-server transfer"
324 .It PORT Ta "specify data connection port"
325 .It PWD Ta "print the current working directory"
326 .It QUIT Ta "terminate session"
327 .It REST Ta "restart incomplete transfer"
328 .It RETR Ta "retrieve a file"
329 .It RMD Ta "remove a directory"
330 .It RNFR Ta "specify rename-from file name"
331 .It RNTO Ta "specify rename-to file name"
332 .It SITE Ta "non-standard commands (see next section)"
333 .It SIZE Ta "return size of file"
334 .It STAT Ta "return status of server"
335 .It STOR Ta "store a file"
336 .It STOU Ta "store a file with a unique name"
337 .It STRU Ta "specify data transfer" Em structure
338 .It SYST Ta "show operating system type of server system"
339 .It TYPE Ta "specify data transfer" Em type
340 .It USER Ta "specify user name"
341 .It XCUP Ta "change to parent of current working directory (deprecated)"
342 .It XCWD Ta "change working directory (deprecated)"
343 .It XMKD Ta "make a directory (deprecated)"
344 .It XPWD Ta "print the current working directory (deprecated)"
345 .It XRMD Ta "remove a directory (deprecated)"
348 The following non-standard or
350 specific commands are supported by the SITE request.
352 .Bl -column Request -offset indent
353 .It Sy Request Ta Sy Description
354 .It CHMOD Ta "change mode of a file, e.g. ``SITE CHMOD 755 filename''"
355 .It HELP Ta "give help information."
356 .It IDLE Ta "set idle-timer, e.g. ``SITE IDLE 60''"
357 .It RATEGET Ta "set maximum get rate throttle in bytes/second, e.g. ``SITE RATEGET 5k''"
358 .It RATEPUT Ta "set maximum put rate throttle in bytes/second, e.g. ``SITE RATEPUT 5k''"
359 .It UMASK Ta "change umask, e.g. ``SITE UMASK 002''"
364 requests (as specified in
366 are recognized, but are not implemented:
376 but will appear in the
383 server will abort an active file transfer only when the
385 command is preceded by a Telnet "Interrupt Process" (IP)
386 signal and a Telnet "Synch" signal in the command Telnet stream,
387 as described in Internet
391 command is received during a data transfer, preceded by a Telnet IP
392 and Synch, transfer status will be returned.
395 interprets file names according to the
399 This allows users to use the metacharacters
401 .Ss User authentication
403 authenticates users according to five rules.
405 .Bl -enum -offset indent
407 The login name must be in the password data base,
409 and not have a null password.
410 In this case a password must be provided by the client before any
411 file operations may be performed.
412 If the user has an S/Key key, the response from a successful
414 command will include an S/Key challenge.
415 The client may choose to respond with a
417 command giving either
418 a standard password or an S/Key one-time password.
419 The server will automatically determine which type of password it
420 has been given and attempt to authenticate accordingly.
423 for more information on S/Key authentication.
424 S/Key is a Trademark of Bellcore.
426 The login name must be allowed based on the information in
429 The user must have a standard shell returned by
431 If the user's shell field in the password database is empty, the
432 shell is assumed to be
436 the user's shell must be listed with full path in
439 If directed by the file
441 the session's root directory will be changed by
443 to the directory specified in the
447 or to the home directory of the user.
448 However, the user must still supply a password.
449 This feature is intended as a compromise between a fully anonymous account
450 and a fully privileged account.
451 The account should also be set up as for an anonymous account.
460 account must be present in the password
463 In this case the user is allowed
464 to log in by specifying any password (by convention an email address for
465 the user should be used as the password).
467 The server performs a
469 to the directory specified in the
476 or to the home directory of the
480 The server then performs a
482 to the directory specified in the
485 directive (if set), otherwise to
488 If other restrictions are required (such as disabling of certain
489 commands and the setting of a specific umask), then appropriate
494 If the first character of the password supplied by an anonymous user
497 then the verbose messages displayed at login and upon a
499 command are suppressed.
501 .Ss Display file escape sequences
504 displays various files back to the client (such as
508 various escape strings are replaced with information pertinent
509 to the current connection.
511 The supported escape strings are:
512 .Bl -tag -width "Escape" -offset indent -compact
518 Current working directory.
520 Email address given with
525 Maximum number of users for this class.
530 Current number of users for this class.
534 If the result of the most recent
543 If the result of the most recent
560 .Ss Setting up a restricted ftp subtree
561 In order that system security is not breached, it is recommended
567 accounts be constructed with care, following these rules
570 in the following directory names
571 with the appropriate account name for
574 .Bl -tag -width "~ftp/incoming" -offset indent
576 Make the home directory owned by
578 and unwritable by anyone.
580 Make this directory owned by
582 and unwritable by anyone (mode 555).
583 Generally any conversion commands should be installed
586 Make this directory owned by
588 and unwritable by anyone (mode 555).
597 must be present for the
599 command to be able to display owner and group names instead of numbers.
600 The password field in
602 is not used, and should not contain real passwords.
605 if present, will be printed after a successful login.
606 These files should be mode 444.
608 This directory and the subdirectories beneath it should be owned
609 by the users and groups responsible for placing files in them,
610 and be writable only by them (mode 755 or 775).
613 be owned or writable by ftp or its group.
615 This directory is where anonymous users place files they upload.
616 The owners should be the user
618 and an appropriate group.
619 Members of this group will be the only users with access to these
620 files after they have been uploaded; these should be people who
621 know how to deal with them appropriately.
622 If you wish anonymous
624 users to be able to see the names of the
625 files in this directory the permissions should be 770, otherwise
630 directives should be used:
631 .Dl "modify guest off"
632 .Dl "umask guest 0707"
633 .Dl "upload guest on"
635 This will result in anonymous users being able to upload files to this
636 directory, but they will not be able to download them, delete them, or
637 overwrite them, due to the umask and disabling of the commands mentioned
640 This directory is used to create temporary files which contain
641 the error messages generated by a conversion or
644 The owner should be the user
646 The permissions should be 300.
648 If you don't enable conversion commands, or don't want anonymous users
649 uploading files here (see
651 above), then don't create this directory.
652 However, error messages from conversion or
654 commands won't be returned to the user.
655 (This is the traditional behaviour.)
660 can be used to prevent users uploading here.
663 To set up "ftp-only" accounts that provide only
666 login, you can copy/link
674 to allow logging-in via
676 into the accounts, which must have
680 .Bl -tag -width /etc/ftpwelcome -compact
681 .It Pa /etc/ftpchroot
682 List of normal users whose root directory should be changed via
684 .It Pa /etc/ftpd.conf
685 Configure file conversions and other settings.
687 List of unwelcome/restricted users.
688 .It Pa /etc/ftpwelcome
689 Welcome notice before login.
691 Welcome notice after login.
693 If it exists, displayed and access is refused.
694 .It Pa /var/run/ftpd.pids-CLASS
695 State file of logged-in processes for the
700 List of logged-in users on the system.
702 Login history database.
715 recognizes all commands in
717 follows the guidelines in
719 recognizes all commands in
721 (although they are not supported yet),
722 and supports the extensions from
726 .Cm draft-ietf-ftpext-mlst-11 .
733 Various features such as the
738 .Cm draft-ietf-ftpext-mlst-11
739 support was implemented in
741 and later releases by Luke Mewburn.
743 The server must run as the super-user to create sockets with
744 privileged port numbers (i.e, those less than
745 .Dv IPPORT_RESERVED ,
749 is listening on a privileged port
750 it maintains an effective user id of the logged in user, reverting
751 to the super-user only when binding addresses to privileged sockets.
754 option can be used to override this behaviour and force privileges to
755 be permanently revoked; see
756 .Sx SECURITY CONSIDERATIONS
757 below for more details.
760 may have trouble handling connections from scoped IPv6 addresses, or
761 IPv4 mapped addresses
767 For the latter case, running two daemons,
768 one for IPv4 and one for IPv6, will avoid the problem.
769 .Sh SECURITY CONSIDERATIONS
771 provides no restrictions on the
773 command, and this can lead to security problems, as
775 can be fooled into connecting to any service on any host.
781 commands with different host addresses, or TCP ports lower than
785 .Sq third-party proxy ftp
787 Use of this option is
789 recommended, and enabled by default.
793 uses a port that is one less than the port it is listening on to
794 communicate back to the client for the
799 commands, unless overridden with
801 As the default port for
803 (21) is a privileged port below
804 .Dv IPPORT_RESERVED ,
806 retains the ability to switch back to root privileges to bind these
808 In order to increase security by reducing the potential for a bug in
810 providing a remote root compromise,
812 will permanently drop root privileges if one of the following is true:
813 .Bl -enum -offset indent
816 is running on a port greater than
818 and the user has logged in as a
831 if you don't want anonymous users to upload files there.
832 That directory is only necessary if you want to display the error
833 messages of conversion commands to the user.
834 Note that if uploads are disabled with the
838 then this directory cannot be abused by the user in this way, so it
839 should be safe to create.