A User's Guide

Mark Lowes

Permission to use, copy, modify and distribute the ProFTPD User Guide and its accompanying documentation for any purpose and without fee is hereby granted in perpetuity, provided that the above copyright notice and this paragraph appear in all copies.

The copyright holders make no representation about the suitability of this document for any purpose. It is provided "as is" without expressed or implied warranty.


This book is dedicated to Lady Kayla.

Table of Contents
This Book's Audience
Why Read This Book?
Request for Comments
Organisation of This Book
Copyrights and Trademarks
I. Introduction
1. Background
What is Proftpd
Who codes/maintains Proftpd?
Website & documentation
Bug reporting?
Mailing lists
Copyright Issues
The FTP protocol
2. Compilation and installing
Installing packaged versions
Compiling from source
Compatibility Issues
How do I get debug output
Using non-default modules
Plans for next version (1.3.x)
Longer term development
NT Support
New features/modules
3. Security Issues
Securing ftp servers
Daemon security
Password Issues
Server attacks
Firewall issues
Security by obscurity and warnings
How can I control what commands the server accepts?
Secure Sockets Layer (SSL)
4. Day to day issues
Starting and stopping your server
Timezone issues
Log management
II. Configuration
5. Getting ready
What do you want from your server?
Config file
Scoreboard file
Standalone or inetd?
6. Generic issues
File permissions and UMASK
Setting the Umask
7. Virtual Hosting
What is virtual hosting
IP address space considerations
VirtualHost directive
Setting up a basic virtual host
Anonymous only servers
vhost notes
DNS issues
Reloading the config
8. Authentication
Password files
Pluggable Authentication Modules (PAM)
Lightweight Directory Access Protocol (LDAP)
Normal users can't login, only anon.
Other authentication methods
9. DefaultRoot and other issues
Locking users into a directory (chroot)
Finer grained control
Symlinks and chroot()
10. Anonymous Servers
How do I create individual anonymous FTP sites for my users?
I want to support normal login and Anonymous under a particular user
I only want to allow anonymous access to a virtual server.
Why doesn't Anonymous ftp work
Additional anonymous accounts
Secure upload facilities
11. Using AuthUserFiles
Choice of IDs
Shadow passwords
ID-to-name mapping
12. Configuration for NAT
Basic information
Configuring ProFTPD
Configuring Linux
13. Configuring ProFTPD for FTP over SSH
Basic premise
Client Configuration
Server Configuration
III. Advanced configuration
14. Access controls
Access limitation
Bandwidth control
Quota controls
Access controls
Controlling permission changes
.ftpaccess files
15. Debugging Problems
Know the version
Know the modules
Perform syntax checks
Common problems
Locate log files
Collect debug information
16. Common Problems
17. More complex Configuration Issues
How can I stop my users from using their space as a warez repository
Can I rotate files out of an upload directory after upload?
How can I hide a directory from anonymous clients.
File/Directory hiding isn't working for me!
I want to prevent users from accessing a hidden directory
How do I setup a virtual FTP server?
How does <Limit LOGIN> work, and where should I use it?
18. Running ProFTPD As A Nonroot User
IV. WorkShop
19. Cleaned sections
Cleaned - part A
20. Initial ponderings from the list
21. Compatibility and Integration
Regular expressions
22. Cookbook
V. References
I. Configuration Directives
AccessDenyMsg -- Customise the response on failed authentication
AccessGrantMsg -- Customise the response on successful authentication
Allow -- Access control directive
AllowAll -- Allow all clients
AllowChmod -- Enable the CHMOD command (deprecated)
AllowFilter -- Regular expression of command arguments to be accepted
AllowForeignAddress -- Control the use of the PORT command
AllowGroup -- Group based allow rules
AllowLogSymlinks -- Permit logging to symlinked files
AllowOverride -- Toggles handling of .ftpaccess files
AllowOverwrite -- Enable files to be overwritten
AllowRetrieveRestart -- Allow clients to resume downloads
AllowStoreRestart -- Allow clients to resume uploads
AllowUser -- User based allow rules
AnonRatio -- Ratio directive
AnonRequirePassword -- Make anonymous users supply a valid password
Anonymous -- Define an anonymous server
AnonymousGroup -- Treat group members as anonymous users
AuthAliasOnly -- Allow only aliased login names
AuthGroupFile -- Specify alternate group file
AuthOrder -- Configure auth module checking order
AuthPAM -- Enable/Disable PAM authentication
AuthPAMAuthoritative -- Set whether PAM is the authoritive authentication scheme
AuthPAMConfig -- Select PAM service name
AuthUserFile -- Specify alternate passwd file
AuthUsingAlias -- Authenticate via Alias-name instead of mapped username
Bind -- Bind the server or Virtualhost to a specific IP address
ByteRatioErrMsg -- Ratio directive
CDPath -- Sets "search paths" for the cd command
CapabilitiesEngine -- Enable/disable mod_cap
CapabilitiesSet -- Configure the set of Linux capabilities processed
Class -- Definition statements for class based tracking
Classes -- Enable Class based connection tracking
CommandBufferSize -- Limit the maximum command length
CreateHome -- Create and populate users' home directories as needed
CwdRatioMsg -- Ratio directive
DebugLevel -- Set the debugging output level
DefaultAddress -- Set the address for the server to listen on
DefaultChdir -- Set starting directory for FTP sessions
DefaultRoot -- Sets default chroot directory
DefaultServer -- Set the default server
DefaultTransferMode -- Set the default method of data transfer
DeferWelcome -- Don't show welcome message until user has authenticated
Define -- Initialises Defines for IfDefine
DeleteAbortedStores -- Enable automatic deletion of partially uploaded files
Deny -- Access control directive
DenyAll -- Deny all clients
DenyFilter -- Regular expression of command arguments to be blocked
DenyGroup -- Group based deny rules
DenyUser -- User based deny rules
DirFakeGroup -- Hide real file/directory group
DirFakeMode -- Hide real file/directory permissions
DirFakeUser -- Hide real file/directory owner
Directory -- Directory-limited configuration directives
DisplayConnect -- Sets connect banner file
DisplayFirstChdir -- Set the file to display when first entering a directory
DisplayGoAway -- Set the file to display to a rejected connection
DisplayLogin -- Set the file to display on login
DisplayQuit -- Set the file to display on quit
DisplayReadme -- Enable display of file modification times on a file pattern
ExtendedLog -- Specify custom logfiles
FileRatioErrMsg -- FIXME FIXME
FooBarDirective -- Dummy directive
Global -- Set some directives to apply across the entire daemon
Group -- Set the group the server normally runs as
GroupOwner -- Change default group for new files and directories
GroupPassword -- FIXME FIXME
GroupRatio -- Ratio directive
HiddenStor -- Enables more safe file uploads
HiddenStores -- FIXFIXFIX
HideFiles -- Enable hiding of files based on regular expressions
HideGroup -- Enable hiding of files based on group owner
HideNoAccess -- Block the listing of directory entries to which the user has no access permissions
HostRatio -- Ratio directive
IdentLookups -- Toggle ident lookups
IfDefine -- To control the use of sections of the configuration
IfModule -- Parse a section of config based on module name
IgnoreHidden -- Treat 'hidden' files as if they don't exist
Include -- Load additional configuration directives from a file
LDAPDNInfo -- Set DN information to be used for initial bind
LDAPDefaultAuthScheme --  Set the authentication scheme/hash that is used when no leading {hashname} is present.
LDAPDefaultGID --  Set the default GID to be assigned to users when no uidNumber attribute is found.
LDAPDefaultUID --  Set the default GID to be assigned to users when no uidNumber attribute is found.
LDAPDoAuth -- Enable LDAP authentication
LDAPDoGIDLookups --  Enable LDAP lookups for user group membership and GIDs in directory listings
LDAPDoQuotaLookups -- Enable LDAP authentication
LDAPDoUIDLookups --  Enable LDAP lookups for UIDs in directory listings
LDAPForceDefaultGID -- Force all LDAP-authenticated users to use the same GID.
LDAPForceDefaultUID -- Force all LDAP-authenticated users to use the same UID.
LDAPForceHomedirOnDemand --  Force all LDAP-authenticated users to use the default HomeDironDemand prefix/suffix.
LDAPHomedirOnDemand --  Enable the creation of user home directories on demand
LDAPHomedirOnDemandPrefix --  Enable the creation of user home directories on demand
LDAPHomedirOnDemandPrefixNoUsername -- FIXFIXFIX
LDAPHomedirOnDemandSuffix --  Specify an additional directory to be created inside a user's home directory on demand.
LDAPNegativeCache -- Enable negative caching for LDAP lookups
LDAPQueryTimeout -- Set a timeout for LDAP queries
LDAPSearchScope -- Specify the search scope used in LDAP queries
LDAPServer -- Specify the LDAP server to use for lookups
LDAPUseTLS -- Enable TLS/SSL connections to the LDAP server.
LeechRatioMsg -- Sets the 'over ratio' error message
Limit -- Set the commands/actions to be controlled
ListOptions -- Configure options used when listing directories
LogFormat -- Specify a logging format
LoginPasswordPrompt -- FIXME FIXME
LsDefaultOptions -- FIXME FIXME
MasqueradeAddress -- Configure the server address presented to clients
MaxClients -- Limits the number of users that can connect
MaxClientsPerHost -- Limits the connections per client machine
MaxClientsPerUser -- Limit the number of connections per userid
MaxConnectionRate -- Maximum TCP socket connection rate
MaxHostsPerUser -- Limit the number of connections per userid
MaxInstances -- Sets the maximum number of child processes to be spawned
MaxLoginAttempts -- Sets how many password attempts are allowed before disconnection
MaxRetrieveFileSize -- Restrict size of downloaded files
MaxStoreFileSize -- Restrict size of uploaded files
MultilineRFC2228 -- Enable RFC2228 multiline response mode
MySQLInfo -- Configures the MySQL driver
Order -- Configures the precedence of the Limit directives
PassivePorts -- Specify the ftp-data port range to be used
PathAllowFilter -- Only allow new files which match a specified pattern
PathDenyFilter -- Disallow new files which match a specified pattern
PersistentPasswd -- Sets handling of unix auth files
PidFile -- Set the filepath to hold the pid of the master server
Port -- Set the port for the control socket
PostgresInfo -- Postgres backend configuration (Deprecated)
PostgresPort -- Sets the port postgres is listening on
RLimitCPU -- Configure the maximum CPU time in seconds used by a process
RLimitMemory -- Configure the maximum memory in bytes used by a process
RLimitOpenFiles -- Configure the maximum number of open files used by a process
RadiusAcctServer -- Setup RADIUS accounting details
RadiusAuthServer -- Setup RADIUS authenticator details
RadiusEngine -- Enable RADIUS support
RadiusLog -- Specify the logfile for reporting / debugging
RadiusRealm -- Setup the authentication realm
RadiusUserInfo -- Configure login information via RADIUS
RateReadFreeBytes -- FIXME FIXME
RateWriteFreeBytes -- FIXME FIXME
RatioFile -- Ratio directive
RatioTempFile -- Ratio directive
RequireValidShell -- Allow connections based on /etc/shells
RewriteCondition -- FIXFIXFIX
RewriteEngine -- FIXFIXFIX
RewriteLock -- FIXFIXFIX
RewriteLog -- FIXFIXFIX
RewriteMap -- FIXFIXFIX
RewriteRule -- FIXFIXFIX
RootLogin -- Permit root user logins
SQLAuthenticate --  Specify authentication methods and what to authenticate
SQLAuthoritative -- Deprecated
SQLDefaultHomedir -- FIXFIXFIX
SQLDoAuth -- Deprecated
SQLDoGroupAuth -- Deprecated
SQLEmptyPasswords -- Allow zero length passwords (DEPRECATED)
SQLEncryptedPasswords -- Assume SQL passwords are encrypted (DEPRECATED)
SQLGidField -- Set the field holding gid information (deprecated)
SQLGroupGIDField -- Deprecated
SQLGroupMembersField -- Deprecated
SQLGroupTable -- Deprecated
SQLGroupWhereClause -- FIXFIXFIX
SQLGroupnameField -- Deprecated
SQLHomedir -- Deprecated
SQLHomedirField -- Deprecated
SQLHomedirOnDemand -- FIXME FIXME
SQLLogDirs -- Deprecated
SQLLogHits -- Deprecated
SQLLogHosts -- Deprecated
SQLLogStats -- Deprecated
SQLLoginCountField -- Deprecated
SQLNegativeCache -- Enable negative caching for SQL lookups
SQLPasswordField -- Deprecated
SQLProcessGrEnt -- Deprecated
SQLProcessPwEnt -- Deprecated
SQLSSLHashedPasswords -- FIXME FIXME
SQLScrambledPasswords -- FIXME FIXME
SQLShellField -- Deprecated
SQLUidField -- Set the field holding uid information (deprecated)
SQLUserTable -- Deprecated
SQLUserWhereClause -- FIXFIXFIX
SQLUsernameField -- Deprecated
SaveRatios -- FIXME FIXME
ScoreboardFile -- Sets the name and path of the scoreboard file
ScoreboardPath -- FIXFIXFIX
ServerAdmin -- Set the address for the server admin
ServerIdent -- Set the message displayed on connect
ServerLog -- Configure logs on a per-server basis
ServerName -- Configure the name displayed to connecting users
ServerType -- Set the mode proftpd runs in
ShowDotFiles -- Toggle display of 'dotfiles'
ShowSymlinks -- Toggle the display of symlinks
SocketBindTight -- Controls how TCP/IP sockets are created
StoreUniquePrefix -- Set the prefix to be added to uniquely generated filenames
SyslogFacility -- Set the facility level used for logging
SyslogLevel -- Set the verbosity level of system logging
SystemLog -- Redirect syslogging to a file
TCPAccessFiles -- Sets the access files to use
TCPAccessSyslogLevels -- Sets the logging levels for mod_wrap
TCPGroupAccessFiles -- Sets the access files to use
TCPServiceName -- Configures the name proftpd will use with mod_wrap
TCPUserAccessFiles -- Sets the access files to use
TLSCACertificateFile -- FIXFIXFIX
TLSCACertificatePath -- FIXFIXFIX
TLSCARevocationFile -- FIXFIXFIX
TLSCARevocationPath -- FIXFIXFIX
TLSCertificateChainFile -- FIXFIXFIX
TLSDSACertificateFile -- FIXFIXFIX
TLSDSACertificateKeyFile -- FIXFIXFIX
TLSRSACertificateFile -- FIXFIXFIX
TLSRSACertificateKeyFile -- FIXFIXFIX
TLSRenegotiate -- FIXFIXFIX
TLSVerifyClient -- FIXFIXFIX
TimeoutIdle -- Sets the idle connection timeout
TimeoutLogin -- Sets the login timeout
TimeoutNoTransfer -- Sets the connection without transfer timeout
TimeoutSession -- Sets a timeout for an entire session
TimeoutStalled -- Sets the timeout on stalled downloads
TimesGMT -- Toggle time display between GMT and local
TransferLog -- Specify the path to the transfer log
TransferRate -- Configure upload, download transfer rates
Umask -- Set the default Umask
UseFtpUsers -- Block based on /etc/ftpusers
UseGlobbing -- Toggles use of glob() functionality
UseReverseDNS -- Toggle rDNS lookups
User -- Set the user the daemon will run as
UserAlias -- Alias a username to a system user
UserDirRoot -- Set the chroot directory to a subdirectory of the anonymous server
UserOwner -- Set the user ownership of new files / directories
UserPassword -- Creates a hardcoded username/password pair
UserRatio -- Ratio directive
VirtualHost -- Define a virtual ftp server
WtmpLog -- Toggle logging to wtmp
tcpBackLog -- Control the tcp backlog in standalone mode
tcpNoDelay -- Control the use of TCP_NODELAY
tcpReceiveWindow -- Set the size of the tcp receive window
tcpSendWindow -- Set the size of the tcp send window
II. Configuration by Module
mod_auth -- Authentication module
mod_cap -- Capabilities module
mod_core -- Core module
mod_ldap -- LDAP authentication support
mod_log -- Logging support
mod_ls -- file listing functionality
mod_radius -- RADIUS based authentication support
mod_ratio -- FIX ME FIX ME
mod_readme -- "README" file support
mod_rewrite -- Rewriting support
mod_sample -- Example module
mod_site -- FIX ME FIX ME
mod_sql -- SQL support module
mod_tls -- TLS support
mod_wrap -- Interface to libwrap
mod_xfer -- FIX ME FIX ME
III. Configuration by Context
server config -- server config
Global -- Global
VirtualHost -- VirtualHost
Anonymous -- Anonymous
Limit -- Limit
.ftpaccess -- .ftpaccess
VI. Appendices
A. Resources
Latest Versions of DocBook
Resources for Resources
Introductory Material on the Web
References and Technical Noteson the Web
Internet RFCs
Books and Printed Resources
B. Cookbook examples
List of Examples
2-1. Configuring for additional modules
3-1. Other approaches
4-1. logrotate configuration
4-2. logrotate configuration
4-3. logrotate configuration
4-4. Configuration fragment
8-1. Generic Linux PAM config
8-2. Redhat 6.* configuration
8-3. SuSe configuration
8-4. FreeBSD configuration
8-5. ...
8-6. A typical configuration fragment
9-1. Simple DefaultRoot setup
9-2. Sample svc.conf file
9-3. DefaultRoot, modified by system group
10-1. Access control using LIMIT
14-1. Configuration using classes
14-2. Simple throttling config
14-3. Rate limiting
14-4. .ftpaccess file
16-1. xinetd configuration
19-1. Filter example
21-2. Contents
21-3. SQL database layout
21-4. Configuration fragment for SQL
21-6. Contents
21-7. proftpd.conf
21-8. Updated authentication table
21-9. File tracking table
21-10. proftpd.conf
B-1. Basic Configuration
B-2. VirtualHost Config
B-3. Complex Configuration