1 .\" $NetBSD: ftpd.8,v 1.69 2002/02/08 01:30:07 ross Exp $
3 .\" Copyright (c) 1997-2001 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. All advertising materials mentioning features or use of this software
49 .\" must display the following acknowledgement:
50 .\" This product includes software developed by the University of
51 .\" California, Berkeley and its contributors.
52 .\" 4. Neither the name of the University nor the names of its contributors
53 .\" may be used to endorse or promote products derived from this software
54 .\" without specific prior written permission.
56 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
57 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
58 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
59 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
60 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
61 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
62 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
64 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
65 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
68 .\" @(#)ftpd.8 8.2 (Berkeley) 4/19/94
76 Internet File Transfer Protocol server
89 is the Internet File Transfer Protocol server process.
92 protocol and listens at the port specified in the
94 service specification; see
104 into for anonymous logins.
105 Default is the home directory for the ftp user.
106 This can also be specified with the
111 Change the root directory of the configuration files from
115 This changes the directory for the following files:
118 .Pa /etc/ftpwelcome ,
120 and the file specified by the
127 would be granted access under
128 the restrictions given in
130 and exit without attempting a connection.
132 exits with an exit code of 0 if access would be granted, or 1 otherwise.
133 This can be useful for testing configurations.
135 Debugging information is written to the syslog using a facility of
137 .It Fl e Ar emailaddr
143 .Sx Display file escape sequences )
145 Explicitly set the hostname to advertise as to
147 The default is the hostname associated with the IP address that
150 This ability (with or without
154 is useful when configuring
157 servers, each listening on separate addresses as separate names.
160 for more information on starting services to listen on specific IP addresses.
168 Each successful and failed
170 session is logged using syslog with a facility of
172 If this option is specified more than once, the retrieve (get), store (put),
173 append, delete, make directory, remove directory and rename operations and
174 their file name arguments are also logged.
178 as the data port, overriding the default of using the port one less
183 Enable the use of pid files for keeping track of the number of logged-in
187 Disable the use of pid files for keeping track of the number of logged-in
189 This may reduce the load on heavily loaded
193 Permanently drop root privileges once the user is logged in.
194 The use of this option may result in the server using a port other
195 than the (listening-port - 1) for
197 style commands, which is contrary to the
199 specification, but in practice very few clients rely upon this behaviour.
201 .Sx SECURITY CONSIDERATIONS
202 below for more details.
204 Require a secure authentication mechanism like Kerberos or S/Key to be used.
210 making them visible to commands such as
213 Don't log each concurrent
221 as the version to advertise in the login banner and in the output of
225 instead of the default version information.
230 then don't display any version information.
236 making them visible to commands such as
249 entries to the syslog, prefixed with
253 These syslog entries can be converted to a
257 file suitable for input into a third-party log analysis tool with a command
259 .Dl "grep 'xferlog: ' /var/log/xferlog | \e"
260 .Dl "\ \ \ sed -e 's/^.*xferlog: //' \*[Gt] wuxferlog"
265 can be used to disable
270 displays it and exits.
275 prints it before issuing the
280 exists (under the chroot directory if applicable),
282 prints it after a successful login.
283 This may be changed with the
290 server currently supports the following
293 The case of the requests is ignored.
294 .Bl -column "Request" -offset indent
295 .It Sy Request Ta Sy Description
296 .It ABOR Ta "abort previous command"
297 .It ACCT Ta "specify account (ignored)"
298 .It ALLO Ta "allocate storage (vacuously)"
299 .It APPE Ta "append to a file"
300 .It CDUP Ta "change to parent of current working directory"
301 .It CWD Ta "change working directory"
302 .It DELE Ta "delete a file"
303 .It EPSV Ta "prepare for server-to-server transfer"
304 .It EPRT Ta "specify data connection port"
305 .It FEAT Ta "list extra features that are not defined in" Cm "RFC 959"
306 .It HELP Ta "give help information"
307 .It LIST Ta "give list files in a directory" Pq Dq Li "ls -lA"
308 .It LPSV Ta "prepare for server-to-server transfer"
309 .It LPRT Ta "specify data connection port"
310 .It MLSD Ta "list contents of directory in a machine-processable form"
311 .It MLST Ta "show a pathname in a machine-processable form"
312 .It MKD Ta "make a directory"
313 .It MDTM Ta "show last modification time of file"
314 .It MODE Ta "specify data transfer" Em mode
315 .It NLST Ta "give name list of files in directory"
316 .It NOOP Ta "do nothing"
317 .It OPTS Ta "define persistent options for a given command"
318 .It PASS Ta "specify password"
319 .It PASV Ta "prepare for server-to-server transfer"
320 .It PORT Ta "specify data connection port"
321 .It PWD Ta "print the current working directory"
322 .It QUIT Ta "terminate session"
323 .It REST Ta "restart incomplete transfer"
324 .It RETR Ta "retrieve a file"
325 .It RMD Ta "remove a directory"
326 .It RNFR Ta "specify rename-from file name"
327 .It RNTO Ta "specify rename-to file name"
328 .It SITE Ta "non-standard commands (see next section)"
329 .It SIZE Ta "return size of file"
330 .It STAT Ta "return status of server"
331 .It STOR Ta "store a file"
332 .It STOU Ta "store a file with a unique name"
333 .It STRU Ta "specify data transfer" Em structure
334 .It SYST Ta "show operating system type of server system"
335 .It TYPE Ta "specify data transfer" Em type
336 .It USER Ta "specify user name"
337 .It XCUP Ta "change to parent of current working directory (deprecated)"
338 .It XCWD Ta "change working directory (deprecated)"
339 .It XMKD Ta "make a directory (deprecated)"
340 .It XPWD Ta "print the current working directory (deprecated)"
341 .It XRMD Ta "remove a directory (deprecated)"
344 The following non-standard or
346 specific commands are supported by the SITE request.
348 .Bl -column Request -offset indent
349 .It Sy Request Ta Sy Description
350 .It CHMOD Ta "change mode of a file, e.g. ``SITE CHMOD 755 filename''"
351 .It HELP Ta "give help information."
352 .It IDLE Ta "set idle-timer, e.g. ``SITE IDLE 60''"
353 .It RATEGET Ta "set maximum get rate throttle in bytes/second, e.g. ``SITE RATEGET 5k''"
354 .It RATEPUT Ta "set maximum put rate throttle in bytes/second, e.g. ``SITE RATEPUT 5k''"
355 .It UMASK Ta "change umask, e.g. ``SITE UMASK 002''"
360 requests (as specified in
362 are recognized, but are not implemented:
372 but will appear in the
379 server will abort an active file transfer only when the
381 command is preceded by a Telnet "Interrupt Process" (IP)
382 signal and a Telnet "Synch" signal in the command Telnet stream,
383 as described in Internet
387 command is received during a data transfer, preceded by a Telnet IP
388 and Synch, transfer status will be returned.
391 interprets file names according to the
395 This allows users to utilize the metacharacters
397 .Ss User authentication
399 authenticates users according to five rules.
401 .Bl -enum -offset indent
403 The login name must be in the password data base,
405 and not have a null password.
406 In this case a password must be provided by the client before any
407 file operations may be performed.
408 If the user has an S/Key key, the response from a successful
410 command will include an S/Key challenge.
411 The client may choose to respond with a
413 command giving either
414 a standard password or an S/Key one-time password.
415 The server will automatically determine which type of password it
416 has been given and attempt to authenticate accordingly.
419 for more information on S/Key authentication.
420 S/Key is a Trademark of Bellcore.
422 The login name must be allowed based on the information in
425 The user must have a standard shell returned by
427 If the user's shell field in the password database is empty, the
428 shell is assumed to be
432 the user's shell must be listed with full path in
435 If directed by the file
437 the session's root directory will be changed by
439 to the directory specified in the
443 or to the home directory of the user.
444 However, the user must still supply a password.
445 This feature is intended as a compromise between a fully anonymous account
446 and a fully privileged account.
447 The account should also be set up as for an anonymous account.
456 account must be present in the password
459 In this case the user is allowed
460 to log in by specifying any password (by convention an email address for
461 the user should be used as the password).
463 The server performs a
465 to the directory specified in the
472 or to the home directory of the
476 The server then performs a
478 to the directory specified in the
481 directive (if set), otherwise to
484 If other restrictions are required (such as disabling of certain
485 commands and the setting of a specific umask), then appropriate
490 If the first character of the password supplied by an anonymous user
493 then the verbose messages displayed at login and upon a
495 command are suppressed.
497 .Ss Display file escape sequences
500 displays various files back to the client (such as
504 various escape strings are replaced with information pertinent
505 to the current connection.
507 The supported escape strings are:
508 .Bl -tag -width "Escape" -offset indent -compact
514 Current working directory.
516 Email address given with
521 Maximum number of users for this class.
526 Current number of users for this class.
530 If the result of the most recent
539 If the result of the most recent
556 .Ss Setting up a restricted ftp subtree
557 In order that system security is not breached, it is recommended
563 accounts be constructed with care, following these rules
566 in the following directory names
567 with the appropriate account name for
570 .Bl -tag -width "~ftp/incoming" -offset indent
572 Make the home directory owned by
574 and unwritable by anyone.
576 Make this directory owned by
578 and unwritable by anyone (mode 555).
579 Generally any conversion commands should be installed
582 Make this directory owned by
584 and unwritable by anyone (mode 555).
593 must be present for the
595 command to be able to display owner and group names instead of numbers.
596 The password field in
598 is not used, and should not contain real passwords.
601 if present, will be printed after a successful login.
602 These files should be mode 444.
604 This directory and the subdirectories beneath it should be owned
605 by the users and groups responsible for placing files in them,
606 and be writable only by them (mode 755 or 775).
609 be owned or writable by ftp or its group.
611 This directory is where anonymous users place files they upload.
612 The owners should be the user
614 and an appropriate group.
615 Members of this group will be the only users with access to these
616 files after they have been uploaded; these should be people who
617 know how to deal with them appropriately.
618 If you wish anonymous
620 users to be able to see the names of the
621 files in this directory the permissions should be 770, otherwise
626 directives should be used:
627 .Dl "modify guest off"
628 .Dl "umask guest 0707"
629 .Dl "upload guest on"
631 This will result in anonymous users being able to upload files to this
632 directory, but they will not be able to download them, delete them, or
633 overwrite them, due to the umask and disabling of the commands mentioned
636 This directory is used to create temporary files which contain
637 the error messages generated by a conversion or
640 The owner should be the user
642 The permissions should be 300.
644 If you don't enable conversion commands, or don't want anonymous users
645 uploading files here (see
647 above), then don't create this directory.
648 However, error messages from conversion or
650 commands won't be returned to the user.
651 (This is the traditional behaviour.)
656 can be used to prevent users uploading here.
659 To set up "ftp-only" accounts that provide only
662 login, you can copy/link
670 to allow logging-in via
672 into the accounts, which must have
676 .Bl -tag -width /etc/ftpwelcome -compact
677 .It Pa /etc/ftpchroot
678 List of normal users whose root directory should be changed via
680 .It Pa /etc/ftpd.conf
681 Configure file conversions and other settings.
683 List of unwelcome/restricted users.
684 .It Pa /etc/ftpwelcome
685 Welcome notice before login.
687 Welcome notice after login.
689 If it exists, displayed and access is refused.
690 .It Pa /var/run/ftpd.pids-CLASS
691 State file of logged-in processes for the
696 List of logged-in users on the system.
698 Login history database.
711 recognizes all commands in
713 follows the guidelines in
715 recognizes all commands in
717 (although they are not supported yet),
718 and supports the extensions from
722 .Cm draft-ietf-ftpext-mlst-11 .
729 Various features such as the
734 .Cm draft-ietf-ftpext-mlst-11
735 support was implemented in
737 and later releases by Luke Mewburn \*[Lt]lukem@netbsd.org\*[Gt].
739 The server must run as the super-user to create sockets with
740 privileged port numbers (i.e, those less than
741 .Dv IPPORT_RESERVED ,
745 is listening on a privileged port
746 it maintains an effective user id of the logged in user, reverting
747 to the super-user only when binding addresses to privileged sockets.
750 option can be used to override this behaviour and force privileges to
751 be permanently revoked; see
752 .Sx SECURITY CONSIDERATIONS
753 below for more details.
756 may have trouble handling connections from scoped IPv6 addresses, or
757 IPv4 mapped addresses
763 For the latter case, running two daemons,
764 one for IPv4 and one for IPv6, will avoid the problem.
765 .Sh SECURITY CONSIDERATIONS
767 provides no restrictions on the
769 command, and this can lead to security problems, as
771 can be fooled into connecting to any service on any host.
777 commands with different host addresses, or TCP ports lower than
781 .Sq third-party proxy ftp
783 Use of this option is
785 recommended, and enabled by default.
789 uses a port that is one less than the port it is listening on to
790 communicate back to the client for the
795 commands, unless overridden with
797 As the default port for
799 (21) is a privileged port below
800 .Dv IPPORT_RESERVED ,
802 retains the ability to switch back to root privileges to bind these
804 In order to increase security by reducing the potential for a bug in
806 providing a remote root compromise,
808 will permanently drop root privileges if one of the following is true:
809 .Bl -enum -offset indent
812 is running on a port greater than
814 and the user has logged in as a
827 if you don't want anonymous users to upload files there.
828 That directory is only necessary if you want to display the error
829 messages of conversion commands to the user.
830 Note that if uploads are disabled with the
834 then this directory cannot be abused by the user in this way, so it
835 should be safe to create.