mod_core
The mod_core
module handles most of the core FTP commands.
<VirtualHost>
, <Global>
, <Anonymous>
,
<Directory>
, .ftpaccess
The AllowFilter
directive allows the configuration of a regular
expression pattern that must be matched for all command arguments sent
to ProFTPD. It is extremely useful in controlling what characters may be sent
in a command to ProFTPD, preventing some possible types of attacks against
ProFTPD.
The regular expression pattern is applied against the arguments to the command sent by the client, so care must be taken when creating a proper regex. Commands that fail the regex match result in a "Forbidden command" error being returned to the client. If the pattern contains whitespace, it must be enclosed in quotes.
The optional flags parameter, if present, modifies how the given pattern will be evaludated. The supported flags are:
The example below allows commands which contain alphanumeric characters and whitespace:
AllowFilter "^[a-zA-Z0-9 ,]*$"
The Filters howto covers filtering in greater detail.
See also: DenyFilter
, PathAllowFilter
, PathDenyFilter
<VirtualHost>
, <Global>
, <Anonymous>
Normally, proftpd
disallows clients from using the FTP
PORT
or EPRT
command with anything other than their
own IP address (i.e. the source IP address of the FTP control
connection), as well as preventing the use of PORT
or
EPRT
to specify a low-numbered (i.e. less than 1024) port
number. In either case, the client is sent an "Invalid port" response error
and a message is logged indicating either "address mismatch" or "bounce attack".
By enabling the AllowForeignAddress
directive, proftpd
will allow clients to transmit foreign data connection addresses that do not
match the client's IP address. This allows such tricks as permitting a client
to transfer a file between two FTP servers without involving itself in the
actual data connection. However, allowing this functionality is generally
considered a bad idea, security-wise. The AllowForeignAddress
directive only affects FTP data connection addresses; not TCP ports. There is
no way (and no valid reason) to allow a client to use a low-numbered port in
its PORT
or EPRT
command.
<VirtualHost>
, <Global>
, <Anonymous>
Normally, the proftpd
server will look for, and parse, any files
named .ftpaccess
in the encountered directories. These files
provide functionality similar to Apache's .htaccess
files --
mini-configuration files. This AllowOverride
directive controls
when/if these .ftpaccess
files will be parsed.
<VirtualHost>
, <Global>
The AuthOrder
directive configures the names of auth modules, and
the order in which they will be checked when authenticating a client.
At least one module name must be given; there is no maximum number of modules that can be listed. The listed module names must the full name of the source file, e.g. "mod_auth_unix.c". To see a full list of module names, use:
$ proftpd -lDo not use "mod_auth.c", as that module is the authentication front end module, and is necessary. Also, do not use "mod_auth_pam.c" as the only module, as that module does not provide, by itself, all of the information needed by proftpd for authenticating a client.
You can make an auth module be "authoritative" by appending an asterisk (*) after the module name. Usually this is done for the "mod_auth_pam.c" module, to ensure that the login fails if the PAM check fails.
Examples
# Use only AuthUserFiles when authenticating, and not the system's /etc/passwd AuthOrder mod_auth_file.c # If the user's information is not in LDAP, they're not a user to use # this server. AuthOrder mod_ldap.c # Use SQL tables first, then LDAP, for authentication AuthOrder mod_sql.c mod_ldap.c # Use the normal system /etc/passwd and PAM, but make sure that PAM is # authoritative about accepting or rejecting the login AuthOrder mod_auth_pam.c* mod_auth_unix.c
<VirtualHost>
, <Global>
The DebugLevel
directive configures the debugging level the
server will use when logging. The level parameter must be between 0
and 10. This directive will take precedence over any
-d
/--debug
command-line debugging option used.
The Logging howto covers logging in greater detail.
The DefaultAddress
directive sets the the address to which the
main server instance (i.e. the server configured by the "server config"
context) will bind. The default behaviour is to select whatever IP address
is reported by the operating system as the primary IP address.
Starting with proftpd-1.3.0rc1
, it is possible to use more than
one FQDN or IP address.
Examples
ServerName "Default FTP Server" Port 21 # We want the main server instance to listen on a specific IP DefaultAddress 192.168.10.30 # Since 1.3.0rc1 it's also possible to use the following: DefaultAddress 192.168.10.30 my.domain.tld
In proftpd-1.3.5rc1
, the DefaultAddress
directive
also handles names which indicates the device-name (or
interface-name); the IP address associated with this device/interface
will be used. For example, you can use:
DefaultAddress eth0Using the device/interface name is useful in cases where the same
proftpd.conf
file is going to be deployed to multiple different
machines, which will have the same device/interface names but different IP
addresses.
See also: <VirtualHost>
<VirtualHost>
, <Global>
, <Anonymous>
,<Directory>
, .ftpaccess
The DenyFilter
directive, like the AllowFilter
directive, specifies a regular expression pattern which must not
match any of the command arguments. If the pattern does match, a
"Forbidden command" error is returned to the client. This can be especially
useful for forbidding certain command argument combinations from ever reaching
ProFTPD.
Note that the PASV
SFTP command cannot be blocked using
this directive.
The optional flags parameter, if present, modifies how the given pattern will be evaludated. The supported flags are:
For example, to reject commands which contain the percent (%
)
character, you could use:
DenyFilter "%"
The Filters howto covers filtering in greater detail.
See also: AllowFilter
, PathAllowFilter
, PathDenyFilter
<VirtualHost>
, <Global>
, <Anonymous>
, <Directory>
The DisplayChdir
directive configures the name of a text file that
will be displayed to the user, every time they change into a directory. If the
text file should only be displayed once to the client, the first time
they change into the directory (or if proftpd
detects that the
DisplayChdir
file has been changed since it was last displayed
to the client), then set the optional second parameter to on or
true.
If the filename is relative, it is looked for in the directory that
the user has changed into. Note that for anonymous ftp logins,
filename must reside within the chroot()
ed
directory. If filename cannot be found or accessed, no error occurs
and nothing is logged or displayed to the client.
See the Display files howto for
more information on the variables that can be used in a
DisplayChdir
file.
See also: DisplayConnect
, DisplayQuit
<VirtualHost>
, <Global>
The DisplayConnect
directive configures the filename of a
text file that will be displayed to the user when they initially connect,
before they login. The filename can be either relative or
absolute. In the case of a relative filename, the file is searched for
starting in the home directory of the User
as which the server is
running. As this can lead confusion, absolute pathnames are highly
recommended. If filename cannot be found or accessed, no error
occurs and nothing is logged or displayed to the client.
See the Display files howto for
more information on the variables that can be used in a
DisplayConnect
file.
See also: DisplayChdir
,
DisplayQuit
<VirtualHost>
, <Global>
, <Anonymous>
The DisplayQuit
directive configures the filename of a
text file that will be displayed to the user when they explicitly end the
FTP session using the QUIT
command. The filename can be
either relative or absolute. In the case of a relative filename, the file is
searched for starting in the home directory of the logged-in user. Note:
if the session is restricted via chroot
, either by the
DefaultRoot
directive or because its an
<Anonymous>
login, then filename must reside
within the chroot()
directory. As this can lead confusion,
absolute pathnames are highly recommended. If filename cannot
be found or accessed, no error occurs and nothing is logged or displayed to
the client.
See the Display files howto for
more information on the variables that can be used in a
DisplayQuit
file.
See also: DisplayChdir
,
DisplayConnect
<VirtualHost>
, <Global>
The FSCachePolicy
directive configures the internal
filesystem-related cache, used for performance optimizations on e.g.
network filesystems. This directive can be used to disable this internal
cache, or to tune the caching policy.
To disable the cache altogether, use:
FSCachePolicy off
To configure the maximum number of entries in the cache before eviction happens:
FSCachePolicy size 64
To configure the maximum age (in seconds) of a cached entry before it is evicted:
FSCachePolicy maxAge 60
The size and maxAge parameters can be combined/set in the same directive, e.g.:
# Set the maximum cache size at 128, and the max age at 120 seconds FSCachePolicy size 128 maxAge 120
<Anonymous>
, <Directory>
, .ftpaccess
The GroupOwner
directive configures which group (via the
group-name parameter) will own all newly created directories and files,
within the configuration context that GroupOwner
is set. The
group ID of group-name cannot be 0.
Note that GroupOwner
cannot be used to override the operating
system/filesystem user/group paradigm. If the current user is not a member of
the specified group, new files and directories cannot be chown()
ed
to the GroupOwner
group. If this happens, the STOR
and MKD
/XMKD
FTP commands will succeed normally,
however the new directory entries will be owned by the current user's default
group (and a warning message logged). However, if you also use
the UserOwner
directive in the same configuration context, this
restriction is lifted.
Some operating systems (e.g. FreeBSD) will use the GID of the parent directory where the new file/directory is created, rather than GID of the logged-in user which creates the new file/directory. To force the GID of the newly created file to be that of the logged-in user, use:
# The tilde (~) syntax uses the GID of the logged-in user GroupOwner ~
See also: UserOwner
<Anonymous>
, <Directory>
The HideGroup
directive configures a <Directory>
or <Anonymous>
section to hide all directory entries owned
by the specified group-name. The group-name can also be
~
(tilde), which is evaluated as the group-name of
the primary group of the logged-in user. This can be combined with a prefix
!
(exclamation point) character, e.g. "!~", to mean
"any group that is not the primary group of the logged-in-user".
Normally, hidden directories and files cannot be seen via LIST
or
NLST
commands but can be operated on via other FTP commands
(CWD
, DELE
, RETR
, etc). This
behavior can be modified via the IgnoreHidden
directive.
Examples:
<Directory path> # Hide all files belonging to group 'wheel' HideGroup wheel # Hide all files belonging to the primary group of the logged-in user HideGroup ~ # Hide all files that are NOT owned by the primary group of the logged-in # user HideGroup !~ </Directory>
See also: HideUser
, HideNoAccess
, IgnoreHidden
<Anonymous>
, <Directory>
The HideNoAccess
directive configures a
<Directory>
or <Anonymous>
section to
hide all directory entries in a directory listing (e.g. via the
LIST
or NLST
FTP commands) to which the current
logged-in, authenticated user has no access. Normal Unix-style permissions
always apply, so that although a user may not be able to see a directory
entry that has "HideNoAccess on" applied, they will receive a normal
"Permission denied" error message when attempting to blindly manipulate the
file system object. The directory or file can be made completely invisible to
all FTP commands by applying IgnoreHidden
in conjunction with
HideNoAccess
.
See also: HideGroup
, HideUser
, IgnoreHidden
<Anonymous>
, <Directory>
The HideUser
directive configures a <Directory>
or <Anonymous>
section to hide all directory entries owned
by the specified user-name. The user-name can also be
~
(tilde), which is evaluated as the user-name of
the logged-in user. This can be combined with a prefix !
(exclamation point) character, e.g. "!~", to mean "any user that is not
the logged-in-user".
Normally, hidden directories and files cannot be seen via LIST
or
NLST
commands but can be operated on via other FTP commands
(CWD
, DELE
, RETR
, etc). This
behavior can be modified via the IgnoreHidden
directive.
Examples:
<Directory path> # Hide all files belonging to user 'root' HideUser root # Hide all files belonging to the logged-in user HideUser ~ # Hide all files that are NOT owned by the logged-in user HideUser !~ </Directory>
See also: HideGroup
, HideNoAccess
, IgnoreHidden
<VirtualHost>
, <Global>
, <Anonymous>
, <Directory>
The Include
directive allows inclusion of other configuration
files from within the server configuration files.
Shell-style (fnmatch(3)
) wildcard characters can be used to
include several files at once, in alphabetical order. (If no matches for
the pattern are found, the Include
directive is silently ignored.)
In addition, if Include
points to a directory, rather than a file,
then proftpd
will read all files in that directory. Note
that including entire directories is not recommended, as it is easy to
accidentally leave temporary files in a directory that can cause
proftpd
to fail.
The path must be an absolute path. Examples:
Include /etc/proftpd/conf/tls.conf Include /etc/proftpd/conf/vhosts/*.conf
<VirtualHost>
The MasqueradeAddress
directive causes the server to display the
network information for the specified IP address or DNS hostname to the client
in the responses to PASV
and EPSV
FTP commands, on
the assumption that that IP address or DNS host is acting as a NAT gateway or
port forwarder for the server. For example:
MasqueradeAddress nat-gw.mydomain.com
The MasqueradeAddress
directive also handles a parameter which
indicates the device-name (or interface-name); the IP address
associated with this device/interface will be used. For example, you can
use:
MasqueradeAddress eth0Using the device/interface name is useful in cases where the same
proftpd.conf
file is going to be deployed to multiple different
machines, which will have the same device/interface names but different IP
addresses.
<VirtualHost>
, <Global>
The MaxCommandRate
directive is used to configure a maximum
number of commands per time interval, after which proftpd
will
start injecting a delay before handling the command. The more over the
configured command/sec rate the client is, the longer the delay. This feature
is used to "throttle" automated and/or malicious clients.
For example:
MaxCommandRate 200sets a maximum command rate of 200 commands per sec. Or:
MaxCommandRate 500 2sets a maximum command rate of 500 commands every 2 seconds.
The MaxConnectionRate
directive is used to configure a maximum
count of connections per time interval (in seconds). If
this connection rate is reached, proftpd
will simply close
additional connections, until the connection rate drops below the threshold.
The default interval is 1 second.
For example:
MaxConnectionRate 200sets a maximum connection rate of 200 connections per sec. Or:
MaxConnectionRate 500 2sets a maximum connection rate of 500 connections every 2 seconds.
The MaxInstances
directive configures the maximum number of child
(session) processes that may be spawned by the proftpd
daemon
process when running with "ServerType standalone" configured. The directive
has no effect when proftpd
is configured with "ServerType inetd".
Each proftpd
child process represents a single client connection,
and thus this directive also controls the maximum number of simultaneous
connections allowed. Additional connections beyond the configured limit are
logged, and silently disconnected. The MaxInstances
directive
can be used to prevent undesirable denial-of-service attacks (e.g.
by repeatedly connecting to the FTP control port, a malicious client could try
to cause proftpd
to repeatedly fork new processes, creating a
"fork-bomb"). By default, no limit is placed on the number of child
processes that may run at one time; it is highly recommended that a
maximum number, suitable to your sites traffic, be configured.
<VirtualHost>
, <Global>
The PassivePorts
directive restricts the range of ports from which
the server will select, when the client sends the PASV
or
EPSV
commands (i.e. requesting a passive data transfer).
The server will randomly choose a number from within the specified range until
an open port is found. Should no open ports be found within the
configured range, the server will default to a random kernel-assigned port,
and a message logged.
The port range configured must be in the non-privileged range (e.g. greater than or equal to 1024); it is STRONGLY RECOMMENDED that the chosen range be large enough to handle many simultaneous passive connections (for example, 49152-65534, the IANA-registered ephemeral port range). The smaller your configured port range is, the greater the chance that all of those ports will be in use (depending on the traffic to your FTP server), and thus the greater the chance that a port outside that range will be configured.
Example:
# Use the IANA registered ephemeral port range PassivePorts 49152 65534
Note: Many admins wonder why the recommended port range is so large.
The answer is that there is really no value in having a small range. ProFTPD
does NOT automatically listen on these ports. For those people who are
worried about port scanning, having a larger PassivePorts
range
will not mean that port scans will show those ports as being open AND that
something is listening there. Conversely, the question to ask yourself as
an administrator is: why do you think you need such a small
PassivePorts
range?
<VirtualHost>
, <Global>
, <Anonymous>
, <Directory>
, .ftpaccess
The PathAllowFilter
directive allows the configuration of a
regular expression pattern that must be matched for all newly
uploaded (stored) files. The regular expression is applied against the entire
pathname specified by the client, so care must be taken when creating a proper
regex. Paths that fail the regex match result in a "Forbidden filename" error
being returned to the client. If the regular expression pattern
parameter contains whitespace, it must be enclosed in quotes.
For example:
# Only allow a-z 0-9 . - _ in file names PathAllowFilter ^[a-z0-9._-]+$ # As above but with upper case characters as well PathAllowFilter ^[A-Za-z0-9._-]+$
The optional flags parameter, if present, modifies how the given pattern will be evaludated. The supported flags are:
The Filters howto covers filtering in greater detail.
See also: PathDenyFilter
<VirtualHost>
, <Global>
, <Anonymous>
, <Directory>
, .ftpaccess
Similar to the PathAllowFilter
directive, PathDenyFilter
specifies a regular expression
pattern which must not match any uploaded pathnames. If the
regex does match, a "Forbidden filename" error is returned to the client.
This can be especially useful for forbidding .ftpaccess or .htaccess files.
For example:
# We don't want .ftpaccess or .htaccess files to be uploaded PathDenyFilter "(\\.ftpaccess|\\.htaccess)$"
The optional flags parameter, if present, modifies how the given pattern will be evaludated. The supported flags are:
The Filters howto covers filtering in greater detail.
See also: PathAllowFilter
<VirtualHost>
The Port
directive configures the TCP port to which
proftpd
will listen while running in standalone mode. This
directive has no effect when used on a server running in inetd mode;
see ServerType
. The directive can be
used in conjunction with
<VirtualHost>
in order to run a
virtual server on the same IP address as the master server, but listening on a
different port.
For any server, either <VirtualHost>
or "server
config", using a number value of zero (0) will effectively
disable/turn off that server:
<VirtualHost ...> # This virtual server is disabled because of this Port setting Port 0 ... </VirtualHost>
The ProcessTitles
directive is used to tweak how
proftpd
modifies the process title for session processes.
By default, proftpd
updates the process title to show the current
FTP command and its arguments for every session, e.g.:
# ps aux | grep proftpd proftpd 30667 0.0 0.1 7304 1584 ? Ss 02:12 0:00 proftpd: (accepting connections) user1 31892 0.2 0.3 8004 3505 ? SL 20:13 0:12 proftpd: user1 - remote.client1.com: RETR file1.doc user2 31934 0.0 0.3 8004 3500 ? SL 21:27 0:00 proftpd: user2 - 4.3.2.1: STOR file2.zip user3 31891 0.2 0.3 8004 3504 ? SL 20:11 0:09 proftpd: user3 - remote.client2.com: RETR whatever.isoThis is the same as having:
ProcessTitles verbosein your proftpd.conf.
To obscure the process titles, you can use:
ProcessTitles tersewhich results in process titles which look like:
# ps aux | grep proftpd proftpd 30667 0.0 0.1 7304 1584 ? Ss 02:12 0:00 proftpd: (accepting connections) user1 31892 0.2 0.3 8004 3505 ? SL 20:13 0:12 proftpd: processing connection user2 31934 0.0 0.3 8004 3500 ? SL 21:27 0:00 proftpd: processing connection user3 31891 0.2 0.3 8004 3504 ? SL 20:11 0:09 proftpd: processing connection
<VirtualHost>
, <Global>
The Protocols
directive is used to enable/disable specific
protocols support by the proftpd
and its collection of modules.
This directive can be used, in conjunction with the
mod_ifsession
module,
to enable certain features for specific users/groups/classes.
The allowed protocols must be configured as a space-delimited list. For example:
# Only enable FTPS and SFTP support, but not FTP or SCP Protocols ftps sftp
The currently known/supported protocols include:
The ScoreboardFile
directive sets the path to the file where the
daemon will store its run-time "scoreboard" session information. This file is
necessary for support features such as
MaxClients
to work properly,
as well as other utilities (such as ftpwho,
ftptop, and
ftpcount). Note that the directory
containing the scoreboard cannot be world-writable.
For performance reasons, it is strongly recommended that the
ScoreboardFile
path not be located on a networked
filesystem, but rather be located on a local physical disk.
In order to disable scoreboarding (which can increase performance, at the cost of functionality), any of the following can be used:
ScoreboardFile /dev/null ScoreboardFile none ScoreboardFile offPlease read the Scoreboard howto before disabling scoreboarding.
The ScoreboardMutex
directive sets the path to a "mutex" file
which is used for scoreboard locking/synchronization; this mutex is used to
increase the daemon's performance under load.
For performance reasons, it is strongly recommended that the
ScoreboardMutex
path not be located on a networked
filesystem, but rather be located on a local physical disk. It is best if
the ScoreboardMutex
be located in the same directory as the
ScoreboardFile
.
<VirtualHost>
, <Global>
The ServerAlias
directive is used to configure a hostname
for the virtual server, such than an FTP client can connect to that virtual
server using the HOST
command. In effect, you use
ServerAlias
to define the names that you want to support, for
true name-based virtual hosting.
For example, you could define a virtual host using an IP address, and
explicitly add the HOST
names which should be "hosted" (handled)
by that virtual host configuration, like so:
<VirtualHost 1.2.3.4> Port 21 ServerAlias *.domain.com ServerAlias example.com ... </VirtualHost>So an FTP client which connected to 1.2.3.4:21, and issued:
HOST ftp.domain.comor:
HOST example.comwould be handled as one would expect.
Defining a virtual host using DNS names would automatically handle the DNS
name as a ServerAlias
:
<VirtualHost example.com> Port 21 ... </VirtualHost>would work just like:
<VirtualHost 1.2.3.4> Port 21 ServerAlias example.com ... </VirtualHost>(assuming that "example.com" resolved to 1.2.3.4, of course).
<VirtualHost>
, <Global>
The ServerIdent
directive sets the default message displayed when
a new client connects. Setting this to off displays:
[hostname] FTP server ready.If set to on, the directive can take an optional string argument, which will be displayed instead of the default text. Sites desiring to give out minimal information will probably want a setting like:
ServerIdent on "FTP Server ready."which won't even reveal the hostname.
An example of a custom identification string might be:
ServerIdent on "Welcome to ftp.linux.co.uk"
Note that the following variables can be used in the configured
ServerIdent
text:
%L
(server IP address)
%V
(server fully-qualified domain name)
%v
(ServerName
)
%{version}
(ProFTPD version)
ServerIdent on "Welcome to %v"
<VirtualHost>
The ServerName
directive configures the text that will be
displayed to a client connecting to the server. This text will be displayed
to the client e.g. as part of the response for a HELP
command.
The ServerType
directive configures the proftpd
server operating mode. The parameter can either be inetd or
standalone.
A parameter value of inetd configures proftpd
to expect
to be run from the inetd
/xinetd
"super server." New
connections are passed from inetd
/xinetd
to
proftpd
and are processed immediately.
A parameter value of standalone configures proftpd
to
start up on its own, and to begin listening to the configured addresses/ports
for incoming connections. New connections result in forked child processes
dedicated to processing all requests from the newly connected client.
The SocketBindTight
directive controls how proftpd
creates and binds its initial TCP listening sockets in "ServerType standalone"
mode (see ServerType
). This directive
has no effect upon servers running with "ServerType inetd", because
the TCP listening sockets in that mode are not needed or created by
proftpd
.
When SocketBindTight
is set to off (the default), a
single TCP listening socket is created for each port that the server must
listen on, regardless of the number of IP addresses being used by
<VirtualHost>
configurations. This has the benefit of
requiring a relatively small number of file descriptors (one for each socket)
for the master daemon process, even if a large number of virtual servers are
configured. Each of these listening sockets is bound to the "wildcard"
address, meaning that on all IP addresses on that port (e.g. "*:21").
When SocketBindTight
is set to on, a TCP listening socket
is created and bound to a specific IP address for the main "server
config" server and all configured virtual servers. This allows for situations
where an administrator may wish to have a particular port be used by both
proftpd
(on one IP address) and another daemon (on a different IP
address). The drawback is that considerably more file descriptors will be
required if a large number of virtual servers must be supported.
Here's an example. Two servers have been configured (one "server config" and
one <VirtualHost>
), with the IP addresses 10.0.0.1 and
10.0.0.2, respectively. The 10.0.0.1 server runs on port 21, while 10.0.0.2
runs on port 2001.
If we use:
SocketBindTight offthen
proftpd
creates two sockets, both bound to all
available addresses; one socket listens on port 21 (i.e. "*:21"), the
other on port 2001 (i.e. "*.2001"). Since each socket is bound to all
available addresses, no other daemon or process will be allowed to bind to
ports 21 or 2001.
On the other hand, if we use:
SocketBindTight onthen
proftpd
again creates two sockets. However one is bound to
10.0.0.1, port 21 (i.e. "10.0.0.1:21") and the other is bound to
10.0.0.2, port 2001 (i.e. "10.0.0.2:2001"). Thus these sockets are
"tightly" bound to the IP addresses. This means that port 21 can be
reused on any address other than 10.0.0.1, and similarly for port 2001
and 10.0.0.2.
One side effect of setting SocketBindTight
to on is that
connections to non-bound addresses will result in a "connection refused"
message rather than the more common:
500 Sorry, no server available to handle request on a.b.c.d.due to the fact that no TCP listening socket has been bound to the particular address/port pair. This may or may not be aesthetically desirable, depending on your circumstances.
<VirtualHost>
The SocketOptions
directive is used to tune various socket-level
options. The rcvbuf and sndbuf parameters are used for
setting the TCP send/receive window sizes. The maxseg parameter is
used for setting a MSS (Maximum Segment Size) via setsockopt(2)
's
TCP_MAXSEG
option. If the MSS is larger than the network
interface's MTU, it is ignored and has no effect.
Examples:
# Use buffer sizes of 32KB for both reading and writing SocketOptions rcvbuf 32768 sndbuf 32768
In proftpd-1.3.5rc1
, the SocketOptions
directive
gained support for the keepalive parameter. By default,
proftpd
enables TCP keepalives on all of its connections,
both control and data. To disable use of TCP keepalives, use:
SocketOptions keepalive offwhile to have TCP keepalives explicitly enabled in the config, you would use:
SocketOptions keepalive on
The keepalive parameter also handles an argument in the form of a "keepalive-spec", which is a colon-separated string of three numeric values: idle-secs, probe-count, and interval-secs. On most TCP stacks, the default TCP keepalive behavior uses 2 hours as the time (per recommendation in RFC 1122), with 9 probes at 75 seconds between each probe. Using the keepalive parameter, this would be configured as:
SocketOption keepalive 7200:9:75The first number (idle-secs) indicates the number of seconds the TCP connection must be idle before the first TCP keepalive probe is sent. Once the idle-secs time has passed, the TCP stack will send a number of "probes", trying to elicit a response (
ACK
, RST
,
etc) from the remote peer; the number of probes sent is configured by
the second number (probe-count). The probes will be sent out at
intervals governed by the third number (interval-secs), which configures
the number of seconds between each keepalive probe.
Note that not all platforms support configuring the idle, count, and interval values of the TCP keepalive behavior in their TCP stack. On such platforms, if the keepalive spec format is used, e.g.:
SocketOptions keepalive 7500:9:75and
proftpd
knows that it cannot alter the TCP keepalive values,
then proftpd
will assume that the keepalive configuration
is equivalent to:
SocketOptions keepalive on
By default, ProFTPD logs its activity via the Unix syslog mechanism, which
allows for several different general classifications of logging messages,
known as "facilities." Normally, all authentication related messages are
logged with the AUTHPRIV
(or AUTH
) facility
(since these messages are intended to be secure, and never seen by unwanted
eyes), while normal operational messages are logged with the
DAEMON
facility. The SyslogFacility
directive
allows all logging messages to be directed to a different facility than
the default.
When this directive is used, all logging is done with the specified facility, both authentication (secure) and otherwise. The facility argument must be one of the following:
AUTH
(or AUTHPRIV
)
CRON
DAEMON
FTP
KERN
LPR
MAIL
NEWS
USER
UUCP
LOCAL0
LOCAL1
LOCAL2
LOCAL3
LOCAL4
LOCAL5
LOCAL6
LOCAL7
syslog.conf
man page.
The Logging howto covers logging in greater detail.
See also: SyslogLevel
,
SystemLog
The SyslogLevel
directive adjusts the verbosity of the messages
recorded via the default Unix syslog logging. The following levels
are available, in order of decreasing significance:
Level | Description |
emerg |
Emergencies (e.g. the system is unusable) |
alert |
Action must be taken immediately |
crit |
Critical conditions |
error |
Error conditions |
warn |
Warning conditions |
notice |
Normal but significant conditions |
info |
Informational |
debug |
Debug-level messages |
When a particular level is specified, messages from all other levels of higher significance will be reported as well. For example, when:
SyslogLevel infois configured, then messages with log levels of
notice
and
warn
will also be logged. Using a level of at least
crit
is recommended.
The Logging howto covers logging in greater detail.
See also: SyslogFacility
,
SystemLog
The TCPBacklog
directive controls the TCP connection queue
size for listening sockets; this directive only applies to proftpd
when it is configured with "ServerType standalone
". It has
no effect if "ServerType inetd
" is configured.
When a TCP connection is established by the TCP/IP stack within the kernel,
there is a short period of time between the actual establishment of the
TCP connection and when that connection is accepted for use by the listening
daemon via the accept(2)
system call. The duration of this period
of time can vary quite a bit, and can depend upon several factors (e.g.
hardware, system load, etc). Any TCP connection which hasn't been
accepted by the listening daemon is placed in a "backlog" or queue of pending
connections. The TCPBacklog
directive controls how the size
of this queue of pending connections.
If this queue of pending connections becomes full, new TCP connections cannot be estaslished. Under heavy load, this can result in occasional (or even frequent) errors seen by clients, such as "Connection refused", even though the daemon is clearly running.
The larger the backlog-size, the more TCP connections can be established to the daemon. This also means more kernel memory and other kernel resources.
The issue is complicated further by the fact that different operating
systems handle the backlog-size value differently. The pending
connection queue is a critical kernel-level structure, and is sensitive
to TCP syn floods.
Each operating system, then, has different ways of handling incoming and
pending connections, to attempt to guard against such attacks. For Linux
systems, read the tcp(7)
man page and specifically about
tcp_abort_on_overflow
, tcp_max_syn_backlog,
and tcp_syncookies
. On FreeBSD, read the
syncookies(4)
man page. And read
here for
additional tuning considerations on Solaris.
<VirtualHost>
, <Global>
, <Anonymous>
The TimeoutIdle
directive configures the maximum number of
seconds that proftpd
will allow clients to stay connected
without receiving any data on either the control or data connection. If data
are received on either connection, the idle timer is reset. Setting
TimeoutIdle
to zero disables the idle timer completely, meaning
that clients can stay connected forever, without sending data. Note:
this is generally a very bad idea, as a "hung" TCP connection which is
never properly disconnected (e.g. the remote network may have become
disconnected from the Internet, etc) will cause a session process to
never exit, until manually killed. This session process will thus linger, using
up one of the MaxInstances
as well as
any of the other configured limits. The maximum allowed seconds value
is 65535 (108 minutes).
See also: TimeoutLogin
,
TimeoutNoTransfer
,
TimeoutStalled
.
<VirtualHost>
, <Global>
The TimeoutLinger
directive configures the maximum number of
seconds that proftpd
will wait (or "linger") when closing a data
connection (i.e. for uploads, downloads, and directory listings). Once
the data connection is closed, proftpd
will send a response
message ("226 Transfer complete") on the control connection indicating the
closure. This delay is necessary for properly handling some FTP clients.
If the client aborts a transfer and there is a long delay, this lingering close
is the most likely culprit. So if you encounter this delay, set
TimeoutLinger
to a low number to remove the delay. The maximum
allowed seconds is 65535 (108 minutes).
For the curious, here are the full details: some FTP clients will close their
end of a data connection as soon as they are done sending their data; other
FTP clients will wait until the server closes its end of the data connection,
and some will close their side of the data connection only after they
receive the "226 Transfer complete" message on the control connection. In
order to ensure that all of the data has been transferred on a data connection,
proftpd
will "linger" for a certain amount of time (governed
by the TimeoutLinger
directive) before sending that
"226 Transfer complete" response, thus giving all client behaviors a chance
to do the right thing. However, this means that some clients will see a
this TimeoutLinger
delay unnecessarily. The proftpd
daemon can't detect which type of behavior the client will use, so it is
up to the site admin to configure proftpd
to work best with
their FTP clients.
<VirtualHost>
, <Global>
The Trace
directive is used to configure which trace channels
are logged to the TraceLog
file, and
which log levels for messages in that trace channel.
For example, to get the default trace channels logged:
Trace DEFAULT:10
To disable logging of a particular trace channel entirely, use a log level of zero, e.g.:
# Log all of the default trace channels except for 'lock' and # 'scoreboard' Trace DEFAULT:10 lock:0 scoreboard:0
To see only a certain range of log levels in a given trace channel, you can specify the log level range like this:
# Log only messages at levels 7-10 for the default channels TraceLog DEFAULT:7-10
See the Tracing howto for more information.
The TraceLog
directive is used to specify a log file for trace
logging messages. The path parameter given must be the full path to
the file to use for logging.
Note that this path must not be to a world-writable directory and,
unless AllowLogSymlinks
is explicitly set to on
(generally a bad idea), the path must not be a symbolic link.
See the Tracing howto for more information.
The TraceOptions
directive can be used to change the format
of the TraceLog
messages, e.g.
adding/remove certain fields of data.
The options supported by the TraceOptions
directive are:
To enable an option, preface the option name with a '+' (plus) character; to disable the option, use a '-' (minus) character prefix. For example:
# Log timestamps inncluding millisecs, but do not include the connection # IP address/port information TraceOptions +TimestampMillis -ConnIPs
The
See also:
The
An optional second dir-umask parameter can specify a different
Note: ProFTPD will not create files that have the executable bit
enabled; this is a security-driven design decision. The permissions of an
uploaded file can be changed by issuing a
The
The
When the
See also:
The
By using the
When
The daemon examines the destination address and port of the incoming
connection being handed off from
After parsing the configuration file, the daemon begins listening for
connections on all configured ports, spawning child processes as necessary
to handle connections for either the main server or any
Because of the method that the daemon uses to listen for connections when
in standalone mode, it is possible to support an exceedingly large number
of virtual servers, potentially exceeding the number of per-process file
descriptors. This is due to the fact that a single file descriptor is used
to listen to each configured port, regardless of the number of addresses
being monitored. Note that it may be necessary to increase the
Starting with
Examples:
TransferLog
directive configures the full path to the
"wu-ftpd style" file transfer log; see the xferlog(5)
description or man page for a description
of this log file format. Separate log files can be created for each
<Anonymous>
and/or <VirtualHost>
.
Additionally, the special keyword "none" (available in proftpd-1.1.7 and later)
can be used, which disables wu-ftpd style transfer logging for the context in
which the directive is used.
ExtendedLog
,
LogFormat
Umask
Syntax: Umask file-umask [dir-umask]
Default: None
Context: "server config", <VirtualHost>, <Global>, <Anonymous>, .ftpaccess
Module: mod_core
Compatibility: 0.99.0 and later
Umask
directive sets the mask applied to newly created file
and directory permissions. Any parameters supplied must be an octal number,
in the format 0xxx
.
Umask
to be used when creating directories, rather than files.
If this second parameter is not used, directories are created using the
file-umask value from the first parameter. For more information on
umasks, consult your operating system documentation/man pages.
SITE CHMOD
command,
e.g.:
SITE CHMOD 0755 /path/to/uploaded/file
Umask
howto also talks about
umasks in greater detail.
UserOwner
Syntax: UserOwner user-name
Default: None
Context: <Anonymous>, <Directory>
Module: mod_core
Compatibility: 1.2pre11 and later
UserOwner
directive is used to specify the user-name
which will own all created files and directories within the
<Anonymous>
or <Directory>
section
contain the UserOwner
directive; the default behavior is that
all created files/directories will be owned by the logged-in user, of course.
UserOwner
directive is used, the
GroupOwner
directive is not restricted to groups to which
the logged-in user belongs.
GroupOwner
<VirtualHost>
Syntax: <VirtualHost ip-address|dns-name [ip-address|dns-name ...]>
Default: None
Context: "server config"
Module: mod_core
Compatibility: 0.99.0 and later
<VirtualHost>
configuration section is used to create
an independent set of configuration directives that apply to a particular
hostname or IP address. It is often used in conjunction with system level
IP aliasing or dummy network interfaces in order to establish one or more
virtual servers which all run on the same physical machine. The
section is terminated with a </VirtualHost>
directive.
Port
directive inside a
<VirtualHost>
section, it is possible to create a virtual
server which uses the same IP address as the master server, but
which listens on a different TCP port (Note, however, that this
approach is incompatible with a
ServerType
of "inetd").
proftpd
starts up, virtual server connections are handled in
one of two ways, depending on the
ServerType
setting:
inetd/xinetd
. If the
connection matches one of the configured <VirtualHost>
sections, the connection is handled by that matching configuration. If no
<VirtualHost>
section matches, and the main server does
not match, the client is informed that no server is available to handle
their requests, and the client is disconnected.
<VirtualHost>
sections.
TCPBackLog
value on heavily loaded
servers in order to avoid kernel-rejected client connections; clients
will receive a "Connection refused" error when this condition happens.
proftpd-1.3.0rc1
, it is possible to use more than
one DNS name or IP address. And starting with proftpd-1.3.5rc1
,
a device/interface name can also be used.
<VirtualHost host1.domain.com host2.domain.com>
...
</VirtualHost>
# Establish a virtual server for the eth1 interface
<VirtualHost eth1>
...
</VirtualHost>
The virtual server howto also talks about
virtual servers in greater detail.
See also: DefaultAddress
mod_core
module is always installed.
Question: How do I configure
Frequently Asked Questions
proftpd
to
only listen to connections on one address, e.g. 127.0.0.1? If I use
the following in my proftpd.conf
:
DefaultAddress localhost
I am still able to connect to proftpd
from another machine.
Answer: The solution is to use the
SocketBindTight
, like this:
DefaultAddress localhost
SocketBindTight on
The SocketBindTight
directive tells proftpd
to
listen only on that 'localhost' IP address, rather than on all
addresses.
© Copyright 2000-2016 The ProFTPD Project
All Rights Reserved