Copyright © 2003, 2004, 2005, 2006, 2007 Edward Rudd
| Revision History | |
|---|---|
| Revision 0.6 | 2007-01-25 |
| Added documentation about Pasv Override parameters | |
| Revision 0.5 | 2006-02-13 |
| Converted to Simpliefied docbook 1.1 | |
| Revision 0.4 | 2005-01-30 |
| Added documentation about FtpAllowOverwrite | |
| Revision 0.3 | 2004-02-09 |
| Added DBI documentation provided by Paul Querna | |
| Revision 0.2 | 2004-01-08 |
| Updated to reflect changes on mod_ftpd 0.12.0 | |
| Revision 0.1 | 2004-01-07 |
| Initial Conversion from Text to Docbook | |
Table of Contents
This is a FTP Protocol Server module for Apache 2.0 and 2.1. It is based loosely on the mod_pop3 code base, so many thanks to the author of mod_pop3. This is still a developmental module, and directives and features may change without notice from release to release. There is a sample configuration provided at the end of this document.
This document, mod_ftpd Manual, is Copyright© 2002 by Edward Rudd. Permission is granted to copy and distribute this document so long as it is included with the associated application, mod_ftpd, in source or binary form.
In this document, I have the pleasure of acknowledging:
Paul Querna <chip force-elite.com> for testing and bouncing ideas off of and writing DBI provider.
Feedback is most certainly welcome for this document. Send your additions, comments and criticisms to the following email address : <urkle <at> outoforder <dot> cc>.
Currently I there are no translations of this document. However if you would like to translate this document into other languages please do so and submit them to this email address : <urkle <at> outoforder <dot> cc>.
Example 1. A sample Apaceh 2.0 configuration
LoadModule ftpd_module modules/mod_ftpd.so
# Load any of the provider modules here (for user specific chroots)
#LoadModule ftpd_dbm_module modules/mod_ftpd_dbm.so
#LoadModule ftpd_dbi_module modules/mod_ftpd_dbi.so
LoadModule ftpd_default_module modules/mod_ftpd_default.so
#LoadModule ftpd_fail_module modules/mod_ftpd_fail.so
Listen 21
<VirtualHost *:21>
DocumentRoot /var/ftp
FtpProtocol On
FtpShowRealPermissions Off
FtpAllowActive On
FtpPasvMinPort 1024
FtpPasvPaxPort 65535
FtpLimitOrder default
FtpDefaultMaxLogins 100
<Directory /var/ftp>
AuthUserFile /usr/local/httpd/ftp
Anonymous_Authoritative On
AuthAuthoritative Off
Anonymous_NoUserID Off
Anonymous_MustGiveEmail Off
Anonymous_VerifyEmail Off
Anonymous_LogEmail Off
Anonymous anonymous
AuthName ftp
AuthType Basic
require valid-user
order allow,deny
allow from all
</Directory>
# only allow changing, retrieving files, and listing on the site
<Location />
<LimitExtept CHDIR GET LIST>
deny from all
</LimitExcept>
</Location>
# allow making directories, listing, chdir, and uploading files.
# But don't allow retrieving files.
<Location /upload>
<LimitExcept LIST PUT MKCOL CHDIR>
deny from all
</LimitExcept>
FtpAllowOverWrite Off
</Location>
</VirtualHost>Whether this server is serving the FTP protocol. The default is Off
Show Real Permissions of files? the default is Off. When Off files will show as mode 644, and directories as 755.
If FTPShowRealPermissions is OFf then this is the group name that is displayed in directory listings. The default is ftp.
If FTPShowRealPermissions is OFf then this is the user name that is displayed in directory listings. The default is ftp.
Allow active(PORT) data transfers from the server. The default is On.
Allow FXP transfer mode. That is to allow using two control connections to two different server and have them transfer files directly to each other. If this is off then data connections are only allowed to come from the client that has the control connection. The default is Off.
Minimum PASV port to use for Data connections. The default value is 1024. This value must be less than FTPPasvMaxPort.
Maximum PASV port to use for Data connections. The default value is 65535. This value must be greater than FTPPasvMinPort.
Override the Passive source port (the ftp server) returned to the client with this IP. The default is to use the IP based on incoming connection.
CIDR formatted (ip/{mask or # of bits) netblock that will NOT be overriden when FtpPasvOverrideAddr is set. Example: 192.168.1.0/24
This is the chroot provider order to use for determining what chroot dir the user should be locked into. The providers are separate modules that must be loaded after mod_ftpd.so (dbm, dbi, default, and fail are included). The default is to do no chroot mapping. A value of none empties the chroot order list.
This is the limit provider order to use for determining when too many users are logged into the FTP server. Currently there is only the default provider. As with the Chroot providers, these are separate modules that must be loaded after mod_ftpd.so. The default is to do no limiting. A value of none empties the limit order list.
Setting this to Off will prevent the mod_ftpd/VERSION tag from being added to the server header in Apache HTTP requests. This does not change the initial server response when a client connects via FTP to the server. The default value is On.
Setting this to On will prevent an ftp client from overwriting an existing file. In order for the file to be replaced, it must be deleted from the server first (DELETE method rights). This is good for an upload only directory where you do not want users overwriting existing files. The default value is On.
To limit what users can and cannot do in directories the Limit and LimitExcept must be used.
ability to change into this directory (required for login)
ability to download a file
ability to get a directory listing
ability to upload a file
ability to append to an existing file (either APPE, or STOR with REST)
ability to delete a file
ability to make a directory
ability to delete a directory
ability to move files or directories
LoadModule ftpd_default_module modules/mod_ftpd_default.so
This module is useful to provide a fail-back chroot path if other modules do not provide one for the user attempting to login.
This is the path that this module will return as the chroot.. It will ALWAYS return this path and no other. The default is empty, and the server will use the DocumentRoot as the chroot.
This is the maximum number of logins to allow when this module is listed in the FtpLimitOrder directive. The default is 20, and the value must be greater than zero.
LoadModule ftpd_fail_module modules/mod_ftpd_fail.so
There is no configuration for this module.. Just add it to FtpChrootOrder and any user that hits this module will immediately fail and not be allowed to login. Use this in a chain of modules and this as a fail-back to deny logins if they do not have a chroot assigned.
LoadModule ftpd_dbm_module modules/mod_ftpd_dbm.so
The filename of the database to use. Can be absolute or relative to the server root.
The type of Database the file is (default,DB,GDBM,NDBM,SDBM)
LoadModule ftpd_dbi_module modules/mod_ftpd_dbi.so
Database Driver to use from libdbi
Directory containing the libdbi database drivers. The default value is from set at compile time
Hostname of the Database Server to connect to
The username for the database connection
The password for the database connection
The name of the database containing the tables
The name of the table containing the usernames and password hashes
The table field that contains the username
The table field that contains the password
The SQL query to pick the chroot value from
The table field that contains the active account flag
The Minimum Number of Database Connections
The Soft Maximum Number of Database Connections
The Hard Maximum Number of Database Connections
The Database Pool Time To Live for Each Connection
The name of the configuration to use for this section
These are some of the known issues and limitations of the module. Also check the TODO file for any issues that did not make their way into this document. And of course, if you feel the urge to actually implement something on my TODO list feel free to submit a unified diff patch to the following email address : <urkle <at> outoforder <dot> cc>.
This module has been build using Apache 2.0.48. I have had people test it on 2.0.47 and 2.1 CVS HEAD.. But I have not officially tested it on 2.1 yet. When an official release of 2.1 is out, then I will test and modify my module for this branch of Apache.
Transferred files do NOT currently go through apache filters and bucket brigades.. When I figure them out, I will support that feature.. (dynamic FTP content..)
I have not load tested this at all.. So I do not know how well it will stand up to stress testing. Can some people run dkftpbench on this thing?
The code has not been thoroughly tested for security related issues.. However, the code is relatively simple, and all ACL checks go through one function, which passes everything to Apache. The source is also available and can be audited by anyone who wishes to.
I do not support the ABOR command, currently, nor do I check for the Telnet command sequences.. Can someone give me an example client that uses these?
There is code in there for unfinished features, just ignore it.. It will be either finished or removed in future releases.
There are no timeouts of any sort currently.. I am trying to find a portable way of doing it, however the apr_poll functions seem to be of no use as I can not get access to the connection socket.
content providers SHOULD check FTP_PLUGIN_VERSION and if it is not the same bailout and refuse to compile as the API is going to be different.
I need to write documentation on the provider interface. However, the header file mod_ftpd.h is quite self documented.
You can contact me via the following mediums.
nickname urkle on irc.freenode.net in the #apache-modules channel.
My website http://www.outoforder.cc/.
email: <urkle <at> outoforder <dot> cc>
mailing list: <mod_ftpd@lists.outoforder.cc> You can subscribe to the mod_ftpd mailing list by sending an e-mail to <mod_ftpd-subscribe@lists.outoforder.cc>.
Please use a meaningful subject line for e-mail, otherwise your e-mail may be silently deposited in my junk mail folder by my SPAM filters and possibly never seen by me. Use something like "mod_ftpd patch to implement feature X" would be quite acceptable, however, "PLEASE READ THIS NOW" is quite unacceptable and will most likely never be read.