1 .\" $NetBSD: ftpd.8,v 1.76 2005/08/07 11:13:34 wiz 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
75 .Op Fl 46DdHlQqrsUuWwX
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
99 is specified, bind to IPv4 addresses only.
103 is specified, bind to IPv6 addresses only.
109 into for anonymous logins.
110 Default is the home directory for the ftp user.
111 This can also be specified with the
118 would be granted access under
119 the restrictions given in
121 and exit without attempting a connection.
123 exits with an exit code of 0 if access would be granted, or 1 otherwise.
124 This can be useful for testing configurations.
126 Change the root directory of the configuration files from
130 This changes the directory for the following files:
133 .Pa /etc/ftpwelcome ,
135 and the file specified by the
142 will listen on the default FTP port for incoming connections
143 and fork a child for each connection.
144 This is lower overhead than starting
148 and thus might be useful on busy servers to reduce load.
150 Debugging information is written to the syslog using a facility of
152 .It Fl e Ar emailaddr
158 .Sx Display file escape sequences )
166 Explicitly set the hostname to advertise as to
168 The default is the hostname associated with the IP address that
171 This ability (with or without
175 is useful when configuring
178 servers, each listening on separate addresses as separate names.
181 for more information on starting services to listen on specific IP addresses.
182 .It Fl L Ar xferlogfile
190 Each successful and failed
192 session is logged using syslog with a facility of
194 If this option is specified more than once, the retrieve (get), store (put),
195 append, delete, make directory, remove directory and rename operations and
196 their file name arguments are also logged.
200 as the data port, overriding the default of using the port one less
205 Disable the use of pid files for keeping track of the number of logged-in
207 This may reduce the load on heavily loaded
211 Enable the use of pid files for keeping track of the number of logged-in
215 Permanently drop root privileges once the user is logged in.
216 The use of this option may result in the server using a port other
217 than the (listening-port - 1) for
219 style commands, which is contrary to the
221 specification, but in practice very few clients rely upon this behaviour.
223 .Sx SECURITY CONSIDERATIONS
224 below for more details.
226 Require a secure authentication mechanism like Kerberos or S/Key to be used.
228 Don't log each concurrent
238 making them visible to commands such as
243 as the version to advertise in the login banner and in the output of
247 instead of the default version information.
252 then don't display any version information.
263 making them visible to commands such as
271 entries to the syslog, prefixed with
275 These syslog entries can be converted to a
279 file suitable for input into a third-party log analysis tool with a command
281 .Dl "grep 'xferlog: ' /var/log/xferlog | \e"
282 .Dl "\ \ \ sed -e 's/^.*xferlog: //' \*[Gt] wuxferlog"
287 can be used to disable
292 displays it and exits.
297 prints it before issuing the
302 exists (under the chroot directory if applicable),
304 prints it after a successful login.
305 This may be changed with the
312 server currently supports the following
315 The case of the requests is ignored.
316 .Bl -column "Request" -offset indent
317 .It Sy Request Ta Sy Description
318 .It ABOR Ta "abort previous command"
319 .It ACCT Ta "specify account (ignored)"
320 .It ALLO Ta "allocate storage (vacuously)"
321 .It APPE Ta "append to a file"
322 .It CDUP Ta "change to parent of current working directory"
323 .It CWD Ta "change working directory"
324 .It DELE Ta "delete a file"
325 .It EPSV Ta "prepare for server-to-server transfer"
326 .It EPRT Ta "specify data connection port"
327 .It FEAT Ta "list extra features that are not defined in" Cm "RFC 959"
328 .It HELP Ta "give help information"
329 .It LIST Ta "give list files in a directory" Pq Dq Li "ls -lA"
330 .It LPSV Ta "prepare for server-to-server transfer"
331 .It LPRT Ta "specify data connection port"
332 .It MLSD Ta "list contents of directory in a machine-processable form"
333 .It MLST Ta "show a pathname in a machine-processable form"
334 .It MKD Ta "make a directory"
335 .It MDTM Ta "show last modification time of file"
336 .It MODE Ta "specify data transfer" Em mode
337 .It NLST Ta "give name list of files in directory"
338 .It NOOP Ta "do nothing"
339 .It OPTS Ta "define persistent options for a given command"
340 .It PASS Ta "specify password"
341 .It PASV Ta "prepare for server-to-server transfer"
342 .It PORT Ta "specify data connection port"
343 .It PWD Ta "print the current working directory"
344 .It QUIT Ta "terminate session"
345 .It REST Ta "restart incomplete transfer"
346 .It RETR Ta "retrieve a file"
347 .It RMD Ta "remove a directory"
348 .It RNFR Ta "specify rename-from file name"
349 .It RNTO Ta "specify rename-to file name"
350 .It SITE Ta "non-standard commands (see next section)"
351 .It SIZE Ta "return size of file"
352 .It STAT Ta "return status of server"
353 .It STOR Ta "store a file"
354 .It STOU Ta "store a file with a unique name"
355 .It STRU Ta "specify data transfer" Em structure
356 .It SYST Ta "show operating system type of server system"
357 .It TYPE Ta "specify data transfer" Em type
358 .It USER Ta "specify user name"
359 .It XCUP Ta "change to parent of current working directory (deprecated)"
360 .It XCWD Ta "change working directory (deprecated)"
361 .It XMKD Ta "make a directory (deprecated)"
362 .It XPWD Ta "print the current working directory (deprecated)"
363 .It XRMD Ta "remove a directory (deprecated)"
366 The following non-standard or
368 specific commands are supported by the SITE request.
370 .Bl -column Request -offset indent
371 .It Sy Request Ta Sy Description
372 .It CHMOD Ta "change mode of a file, e.g. ``SITE CHMOD 755 filename''"
373 .It HELP Ta "give help information."
374 .It IDLE Ta "set idle-timer, e.g. ``SITE IDLE 60''"
375 .It RATEGET Ta "set maximum get rate throttle in bytes/second, e.g. ``SITE RATEGET 5k''"
376 .It RATEPUT Ta "set maximum put rate throttle in bytes/second, e.g. ``SITE RATEPUT 5k''"
377 .It UMASK Ta "change umask, e.g. ``SITE UMASK 002''"
382 requests (as specified in
384 are recognized, but are not implemented:
394 but will appear in the
401 server will abort an active file transfer only when the
403 command is preceded by a Telnet "Interrupt Process" (IP)
404 signal and a Telnet "Synch" signal in the command Telnet stream,
405 as described in Internet
409 command is received during a data transfer, preceded by a Telnet IP
410 and Synch, transfer status will be returned.
413 interprets file names according to the
417 This allows users to use the metacharacters
419 .Ss User authentication
421 authenticates users according to five rules.
423 .Bl -enum -offset indent
425 The login name must be in the password data base,
427 and not have a null password.
428 In this case a password must be provided by the client before any
429 file operations may be performed.
430 If the user has an S/Key key, the response from a successful
432 command will include an S/Key challenge.
433 The client may choose to respond with a
435 command giving either
436 a standard password or an S/Key one-time password.
437 The server will automatically determine which type of password it
438 has been given and attempt to authenticate accordingly.
441 for more information on S/Key authentication.
442 S/Key is a Trademark of Bellcore.
444 The login name must be allowed based on the information in
447 The user must have a standard shell returned by
449 If the user's shell field in the password database is empty, the
450 shell is assumed to be
454 the user's shell must be listed with full path in
457 If directed by the file
459 the session's root directory will be changed by
461 to the directory specified in the
465 or to the home directory of the user.
466 However, the user must still supply a password.
467 This feature is intended as a compromise between a fully anonymous account
468 and a fully privileged account.
469 The account should also be set up as for an anonymous account.
478 account must be present in the password
481 In this case the user is allowed
482 to log in by specifying any password (by convention an email address for
483 the user should be used as the password).
485 The server performs a
487 to the directory specified in the
494 or to the home directory of the
498 The server then performs a
500 to the directory specified in the
503 directive (if set), otherwise to
506 If other restrictions are required (such as disabling of certain
507 commands and the setting of a specific umask), then appropriate
512 If the first character of the password supplied by an anonymous user
515 then the verbose messages displayed at login and upon a
517 command are suppressed.
519 .Ss Display file escape sequences
522 displays various files back to the client (such as
526 various escape strings are replaced with information pertinent
527 to the current connection.
529 The supported escape strings are:
530 .Bl -tag -width "Escape" -offset indent -compact
536 Current working directory.
538 Email address given with
543 Maximum number of users for this class.
548 Current number of users for this class.
552 If the result of the most recent
561 If the result of the most recent
578 .Ss Setting up a restricted ftp subtree
579 In order that system security is not breached, it is recommended
585 accounts be constructed with care, following these rules
588 in the following directory names
589 with the appropriate account name for
592 .Bl -tag -width "~ftp/incoming" -offset indent
594 Make the home directory owned by
596 and unwritable by anyone.
598 Make this directory owned by
600 and unwritable by anyone (mode 555).
601 Generally any conversion commands should be installed
604 Make this directory owned by
606 and unwritable by anyone (mode 555).
615 must be present for the
617 command to be able to display owner and group names instead of numbers.
618 The password field in
620 is not used, and should not contain real passwords.
623 if present, will be printed after a successful login.
624 These files should be mode 444.
626 This directory and the subdirectories beneath it should be owned
627 by the users and groups responsible for placing files in them,
628 and be writable only by them (mode 755 or 775).
631 be owned or writable by ftp or its group.
633 This directory is where anonymous users place files they upload.
634 The owners should be the user
636 and an appropriate group.
637 Members of this group will be the only users with access to these
638 files after they have been uploaded; these should be people who
639 know how to deal with them appropriately.
640 If you wish anonymous
642 users to be able to see the names of the
643 files in this directory the permissions should be 770, otherwise
648 directives should be used:
649 .Dl "modify guest off"
650 .Dl "umask guest 0707"
651 .Dl "upload guest on"
653 This will result in anonymous users being able to upload files to this
654 directory, but they will not be able to download them, delete them, or
655 overwrite them, due to the umask and disabling of the commands mentioned
658 This directory is used to create temporary files which contain
659 the error messages generated by a conversion or
662 The owner should be the user
664 The permissions should be 300.
666 If you don't enable conversion commands, or don't want anonymous users
667 uploading files here (see
669 above), then don't create this directory.
670 However, error messages from conversion or
672 commands won't be returned to the user.
673 (This is the traditional behaviour.)
678 can be used to prevent users uploading here.
681 To set up "ftp-only" accounts that provide only
684 login, you can copy/link
692 to allow logging-in via
694 into the accounts, which must have
698 .Bl -tag -width /etc/ftpwelcome -compact
699 .It Pa /etc/ftpchroot
700 List of normal users whose root directory should be changed via
702 .It Pa /etc/ftpd.conf
703 Configure file conversions and other settings.
705 List of unwelcome/restricted users.
706 .It Pa /etc/ftpwelcome
707 Welcome notice before login.
709 Welcome notice after login.
711 If it exists, displayed and access is refused.
712 .It Pa /var/run/ftpd.pids-CLASS
713 State file of logged-in processes for the
718 List of logged-in users on the system.
720 Login history database.
733 recognizes all commands in
735 follows the guidelines in
737 recognizes all commands in
739 (although they are not supported yet),
740 and supports the extensions from
744 .Cm draft-ietf-ftpext-mlst-11 .
751 Various features such as the
756 .Cm draft-ietf-ftpext-mlst-11
757 support was implemented in
759 and later releases by Luke Mewburn.
761 The server must run as the super-user to create sockets with
762 privileged port numbers (i.e, those less than
763 .Dv IPPORT_RESERVED ,
767 is listening on a privileged port
768 it maintains an effective user id of the logged in user, reverting
769 to the super-user only when binding addresses to privileged sockets.
772 option can be used to override this behaviour and force privileges to
773 be permanently revoked; see
774 .Sx SECURITY CONSIDERATIONS
775 below for more details.
778 may have trouble handling connections from scoped IPv6 addresses, or
779 IPv4 mapped addresses
785 For the latter case, running two daemons,
786 one for IPv4 and one for IPv6, will avoid the problem.
787 .Sh SECURITY CONSIDERATIONS
789 provides no restrictions on the
791 command, and this can lead to security problems, as
793 can be fooled into connecting to any service on any host.
799 commands with different host addresses, or TCP ports lower than
803 .Sq third-party proxy ftp
805 Use of this option is
807 recommended, and enabled by default.
811 uses a port that is one less than the port it is listening on to
812 communicate back to the client for the
817 commands, unless overridden with
819 As the default port for
821 (21) is a privileged port below
822 .Dv IPPORT_RESERVED ,
824 retains the ability to switch back to root privileges to bind these
826 In order to increase security by reducing the potential for a bug in
828 providing a remote root compromise,
830 will permanently drop root privileges if one of the following is true:
831 .Bl -enum -offset indent
834 is running on a port greater than
836 and the user has logged in as a
849 if you don't want anonymous users to upload files there.
850 That directory is only necessary if you want to display the error
851 messages of conversion commands to the user.
852 Note that if uploads are disabled with the
856 then this directory cannot be abused by the user in this way, so it
857 should be safe to create.