<-
Apache > HTTP Server > Documentation > Version 2.4 > Modules

Apache Module mod_ftp

Available Languages:  en 

Description:Provides support for the File Transfer Protocol
Status:External
Module Identifier:ftp_module
Source File:mod_ftp.c
Compatibility:Apache 2.2 and higher

Summary

This module provides support for the File Transfer Protocol within the Apache HTTP Server. It was originally developed by Covalent Technologies, Inc. and contributed by them to the Apache HTTP Server project.

The FTP protocol module for Apache can work with the access control modules, mod_ssl and any dynamic content generator to provide veratile, scalable and secure FTP services.

Further details, discussion and examples are provided in the FTP documentation.

Directives

See also

top

FTP Directive

Description:Run an FTP Server on this host
Syntax:FTP on|off
Default:FTP off
Context:server config, virtual host
Status:External
Module:mod_ftp

You must define a Listen directive to listen for FTP requests.

This directive is not inherited from the global configuration file.
top

FTPActiveRange Directive

Description:Ports the server will use for connecting to the client
Syntax:FTPActiveRange min [max]
Default:an ephemeral high-numbered port
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive defines the port or ports that mod_ftp will use when making an active connection to the client. It accepts one or two arguments. If only one argument is given, the server will always use that port. If two arguments are given, the server will treat them as a range of ports to be used.

Use a sufficient range to satisfy all client requests! Between the time that the client makes a data channel request following the PORT or EPRT request, and the point at which the server has connected to the client, the origin port may be unavailable to any other client.
Windows allows any process to access privileged ports. However, to assign FTPActiveRange below 1024 on a unix platform, mod_ftp requires unix domain sockets, and will create an additional httpd process to serve these bound, low numbered ports to the httpd child worker processes.

FTPActiveRange 20

Force the server to use the ftp-data scheme convention

FTPActiveRange 5050

Force the server to use port 5050

FTPActiveRange 5050 5080

Allow the server to use any port between 5050 and 5080, inclusive.

top

FTPBannerMessage Directive

Description:Set initial login message
Syntax:FTPBannerMessage message|file:/path/to/file
Default:none
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive sets a message that is displayed to the client on initial connection. This can either be a string, or a path to a file. The message can contain a variety of meta-characters:

%TLocal time (in the form Mon Apr 29 20:36:48 2002)
%CCurrent working directory
%hRemote host
%LLocal host
%EServer administrator (as given by ServerAdmin)
%aRemote IP-address
%ALocal IP-address
%uRemote user
%fNumber of files transferred
%tTotal bytes downloaded
%xNumber of data transfers
%bTotal traffic for the session (both control and data)
top

FTPDataBlockSize Directive

Description:Block size in bytes between control channel tests
Syntax:FTPDataBlockSize bytes
Default:FTPDataBlockSize 48000
Context:server config, virtual host
Status:External
Module:mod_ftp

When mod_ftp is transmitting data via the operating system, it's not possible to monitor the control channel for ABOR signals. FTPDataBlockSize partitions the transfer; between each block mod_ftp will see if there is a pending control channel request, or if the socket is ready to send more data, and proceed to the next block. Based on anticipated bandwidth, set this value to a reasonable window of time in which the server should answer the control channel.

top

FTPDirUmask Directive

Description:Set the umask for created directory
Syntax:FTPDirUmask umask
Default:FTPDirUmask 022
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:External
Module:mod_ftp

This directive sets the permission mask for directory creation access. The default is 022 which gives the owner complete access and disables write access for the group and other users.

This directive is not supported on Windows.
top

FTPDocRootEnv Directive

Description:Set the DocumentRoot based on the given environment variable, such as a per-user LDAP property
Syntax:FTPDocRootEnv envvar
Default:none
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive will cause FTP to use the value of the envvar environment variable in place of the default DocumentRoot, if the environment variable is defined. The envvar variable must contain a full, rooted file path, e.g. /some/path on Unix or d:/some/path on Windows.

This may be used with any authentication module which sets the value of an environment variable based on the logged in user or another condition (similar to mod_env or mod_setenvif to change FTP's Document Root on a per-user basis.

This directive is not inherited from the global configuration file.
top

FTPEPSVIgnoreFamily Directive

Description:Force EPSV to ignore the requested IP family (IPv4 vs. IPv6)
Syntax:FTPEPSVIgnoreFamily On
Default:FTPEPSVIgnoreFamily Off
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive allows the client's EPSV request to bind to the local address, ignoring IPv4 vs. IPv6 requested by the client, in order to work around network address translation which presented an apparently different family. You may find this useful when the FTP Server is behind a firewall.

top

FTPExitMessage Directive

Description:Set logout message
Syntax:FTPExitMessage message|file:/path/to/file
Default:none
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive sets a message that is displayed to the client on disconnect. This can either be a string, or a path to a file. The message can contain a variety of meta-characters (see FTPBannerMessage).

top

FTPHomeDir Directive

Description:Set the path to directory containing user's home directories
Syntax:FTPHomeDir /directory
Default:none
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive defines where the user home directory is located. This directory must be given as an absolute path, but is actually relative to the configured DocumentRoot for the server. For example, FTPHomeDir /home will cause the Apache FTP Server to look for the user home in the directory DocumentRoot/home/username (where username is the login name of the user).

If FTPHomeDir has been specified and the home directory for the user does not exist, the server logs an error and user is logged into the root ("/") directory. If you want the home directory created automatically, see the CreateHomeDirs option to the FTPOptions directive.

This directive is not inherited from the global configuration file.
top

FTPImplicitSSL Directive

Description:Use SSL implicitly
Syntax:FTPImplicitSSL on|off
Default:FTPImplicitSSL off
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive determines the security on the control connection when the user connects. When set to On, the user is expected to connect using SSL. When set to Off, the user must connect insecurely then issue the AUTH command to start a secure session.

This directive is not inherited from the global configuration file.
top

FTPJailUser Directive

Description:Users are not allowed to leave their home directories
Syntax:FTPJailUser on|off
Default:FTPJailUser off
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive confines the user to the directory tree in which they were placed upon login. The user can access any subdirectory of their default directory, but cannot access the parent directory or any other related directories.

If the FTPHomeDir directive is not used, then FTPJailUser has no effect. This combination of directives can be very powerful for restricting where in your filesystem users may traverse.

This directive is not inherited from the global configuration file.
top

FTPLimitDBFile Directive

Description:Set the location for the Login Limit DB file
Syntax:FTPLimitDBFile file-path
Default:FTPLimitDBFile logs/ftplogins
Context:server config
Status:External
Module:mod_ftp

To provide FTPLimitLoginUser, FTPLimitLoginServer and FTPLimitLoginIP features, mod_ftp uses a small DBM file to store login data. This directive determines the filename-path of that database file. If either FTPLimit directive is used, this directive must specify a filename for this DBM, writeable by the server.

FTPLimitDBFile logs/ftplogins

top

FTPLimitLoginIP Directive

Description:Set the maximum number of concurrent logins per IP address
Syntax:
Default:FTPLimitLoginIP 0 (unlimited)
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive allows the administrator to limit the total number of concurrent/simultaneous FTP logins. For example, if set to 10, no more than 10 FTP logins from the same IP address would be allowed. The default value is 0 (unlimited).

top

FTPLimitLoginServer Directive

Description:Set the maximum number of concurrent logins per server
Syntax:FTPLimitLoginServer number
Default:FTPLimitLoginServer 0 (unlimited)
Context:server config
Status:External
Module:mod_ftp

This directive allows the administrator to limit the total number of concurrent/simultaneous FTP logins. For example, if set to 100, no more than 100 FTP logins to the same virtual host would be allowed. The default value is 0 (unlimited).

top

FTPLimitLoginUser Directive

Description:Set the maximum number of concurrent logins per user
Syntax:FTPLimitLoginUser number
Default:FTPLimitLoginUser 0 (unlimited)
Context:server config
Status:External
Module:mod_ftp

This directive allows the administrator to limit the number of concurrent/simultaneous logins of a single FTP user. For example, if set to 3, then no single FTP account would be allowed to have more than 3 concurrent logins (including the guest/anonymous account). The default value is 0 (unlimited).

top

FTPLowPortSock Directive

Description:The filename prefix of the unix domain socket used to pass low numbered origin port requests
Syntax:FTPLowPortSock pathname
Default:FTPLowPortSock logs/ftp-lowportd-sock
Context:server config
Status:External
Module:mod_ftp

This directive sets the filename prefix of the socket to use for communication with the CGI daemon, an extension corresponding to the process ID of the server will be appended. The socket will be created using the permissions of the user who starts Apache (usually root). To maintain the security of communications with CGI scripts, it is important that no other user has permission to write in the directory where the socket is located.

Example

FTPLowPortSock /var/run/cgid.sock

top

FTPMaxLoginAttempts Directive

Description:Maximum number of login attempts
Syntax:FTPMaxLoginAttempts attempts
Default:FTPMaxLoginAttempts 3
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive controls the number of failed attempts to log in that are allowed before breaking the connection and logging the failed attempts.

top

FTPOptions Directive

Description:Set options for this server
Syntax:FTPOptions option1 [option2] ...
Default:none
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive sets per server options.

Current options:

AllowProxyPASV

This option permits connection to the server's data channel when it originates from an IP address other than the control channel client's IP. It affects both the PASV and EPSV data connections.` As proxy FTP is rarely used and considered potentially insecure, this directive should be used with caution.

AllowProxyPORT

This option permits the server to create a data channel connection to an IP address other than the control channel client's IP. It affects both the PORT and EPRT data connections. As proxy FTP is rarely used and considered potentially insecure, this directive should be used with caution.

CheckMaxClients

This option denies login to a client when the server is full. If it is not enabled, the client will wait on the accept queue until another client disconnects.

CreateHomeDirs

This option causes the server to automatically create a home directory in the location specified by the FTPHomeDir directive. If the FTPHomeDir directive is not specified, this option has no effect.

Setting this option on an anonymous site is not recommended. This is because a directory is created for each unique user (usually identified by their email address) that logs onto the server.

This option will only work if the FTPHomeDir directories are accessible to the process owner of the Apache HTTP Server, typically on UNIX systems the user nobody.

LISTisNLST

This option causes the server to display identical output when it receives either a LIST request or an NLST request. Unlike NLSTisLIST, the output is a list of files without details. If the -l option is passed to LIST requests, details will be provided, whether this option is set or not.

NLSTisLIST

This option causes the server to display identical output when it receives either a LIST request or an NLST request. Like NLSTShowDirs, this option is used for FTP clients that send different requests for ls or dir commands.

Setting this option will cause commands that request multiple files to fail and should be used with caution.

NLSTShowDirs

This option causes the server to display directories as well as files when it receives an NLST request. Some FTP clients send an NLST requests when the user issues an ls or dir commands. Since the default response is to display files only, the user may be confused.

Setting this option will cause commands that request multiple files to fail and should be used with caution.

NoUTF8Feature

By default, mod_ftp will advertise UTF8 in response to the FEAT command. This ensures the client is aware they may use 8-bit filenames (rather than 7-bit ASCII), preferably using the UTF-8 character set. This flag, available only in the global context, disables this default behavior for all hosts, omitting UTF8 from the FEAT server response.

RemoveUserGroup

This option causes the server to print the UID and GID rather than the user name and group name for directory listings. It has no effect on Windows systems.

RequireSSL

This option requires the client to issue an AUTH command to switch to SSL before sending any password information. This is much like implicit SSL in that it forces the client to use SSL to send password information. The difference is that using the RequireSSL option will allow a client to connect without SSL, but then issue the AUTH SSL command before sending the username and password.

ShowUnAuthorizedFiles

This option causes the server to show files that the user does not have authorization to retrieve and directories that the user does not have authorization to enter (cd will fail) when it receives a LIST or similar NLST command. These commands will then behave as most standard FTP servers, where users see the list of all files and directories, even those they are not allowed to access.

StripHostname

When the user presents a USER {user@hostname} command, strip the "@hostname" text from the provided name before presenting "user" to the authentication modules. Most commonly used in conjunction with the VirtualHostByUser option below.

VirtualHostByUser

When the user presents a USER {user@hostname} command, select a VirtualHost by the "hostname" text of the provided name. The NameVirtualHost must be configured appropriately to match these hosts. If no named virtual host matches by its ServerName or any of its ServerAliass, the login falls into the first matching VirtualHost by IP, just as HTTP treats an unmatched Host: header.

top

FTPPASVaddr Directive

Description:Set the apparent server IP address for PASV data channels
Syntax:FTPPASVAddr IP address
Default:The server's actual IP address of the control channel connection
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive allows you to specify a different IP address to be presented to the client in response to PASV requests. It has no effect on the IP address the server will listen on, use FTPPASVbindaddr instead to affect the IP address of the actual data connection.

You may find this useful when the FTP Server is behind a firewall. It has no effect on EPSV requests.

This directive is not inherited from the global configuration file.
top

FTPPASVbindaddr Directive

Description:Set and bind the allowed PASV server IP address for the data channel
Syntax:FTPPASVbindaddr IP address
Default:The specified FTPPASVaddr, or in its absense, the server's actual IP address of the control channel connection
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive is similar to the FTPPASVaddr directive, except that the Apache FTP Server attempts to bind to the specified IP address, and note that any FTPPASVaddr directive continues to override the address presented to the client.

You may find this useful when the FTP Server is behind a firewall. It has no effect on EPSV requests.

This directive is not inherited from the global configuration file.
top

FTPPASVrange Directive

Description:Set the allowed passive port range
Syntax:FTPPASVrange number number
Default:an ephemeral high-numbered port
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive defines the port range (number to number inclusive) to be used for all passive connections, including PASV and EPSV requests. This directive is designed for use in environments where you only want to open a specific range of ports on your firewall.

Use a sufficient range to satisfy all client requests! Between the time that the server answers a PASV or EPSV request, and the point at which the client connects to the indiciated port, that specific port is unavailable to any other client.
top

FTPReadmeMessage Directive

Description:Set per-directory Readme file
Syntax:FTPReadmeMessage message|file:/path/to/file
Default:none
Context:server config, virtual host, directory, .htaccess
Override:Any
Status:External
Module:mod_ftp

This directive sets a message that is displayed to the client upon entering a new directory. This can either be a string, or a path to a file. The message can contain a variety of meta-characters (see FTPBannerMessage).

When this directive is placed in the <VirtualHost> container, the README message will apply to all directories. When it is used in a <Directory> container or placed in an .htaccess file, only that directory will inherit the README message.

Configuring a README message for a directory will also override any global README messages.

top

FTPTimeoutData Directive

Description:Idle time allowed during a data transfer
Syntax:FTPTimeoutData time
Default:FTPTimeoutData 300
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive sets the time in seconds the server will wait during a data transfer. If no data is sent to the client in this amount of time, the data connection is closed.

top

FTPTimeoutIdle Directive

Description:Idle time allowed during a FTP session
Syntax:FTPTimeoutIdle time
Default:FTPTimeoutIdle 600
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive sets the amount of time in seconds allowed between commands sent by the client. If no commands are received in this amount of time, the user is disconnected.

top

FTPTimeoutLogin Directive

Description:Idle time allowed when logging in
Syntax:FTPTimeoutLogin time
Default:FTPTimeoutLogin 60
Context:server config, virtual host
Status:External
Module:mod_ftp

This directive sets the amount of time in seconds that a user has to send a username to the server. If the username is not received in this amount of time, the user is disconnected.

top

FTPUmask Directive

Description:Set the umask for created files
Syntax:FTPUmask umask
Default:FTPUmask 022
Context:server config, virtual host, directory, .htaccess
Override:FileInfo
Status:External
Module:mod_ftp

This directive sets the permission mask for file creation access. The default is 022 which gives the owner complete access and disables write access for the group and other users.

This directive is not supported on Windows.

Available Languages:  en 

top

Comments

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our mailing lists.