ProFTPD module mod

ProFTPD module `mod_statcache`

The mod_statcache module is designed to cache the results of stat(2) and lstat(2) calls in shared memory, so that the results can be shared among multiple session processes. On a busy server, especially one handling many directory listings, these stat(2)/lstat(2) calls can add quite a bit of overhead.

This module is contained in the mod_statcache.c file for ProFTPD 1.3.x, and is not compiled by default. Installation instructions are discussed here. More examples of mod_statcache usage can be found here.

The most current version of mod_statcache is distributed with the ProFTPD source code.

Author

Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.

Control Actions

statcache

StatCacheCapacity

Syntax: StatCacheCapacity count
Default: StatCacheCapacity 5000
Context: server config
Module: mod_statcache
Compatibility: 1.3.4rc2 and later

The StatCacheCapacity directive configures the capacity of the cache, i.e. the maximum number of cache entries. By default, mod_statcache allocates space for 5000 cache entries.

The count value be 10 or greater. The configured count is handled as a hint; the actual allocated capacity may be rounded up to the nearest multiple of the internal block sizes.

StatCacheControlsACLs

Syntax: StatCacheControlsACLs actions|"all" "allow"|"deny" "user"|"group" list
Default: None
Context: server config
Module: mod_statcache
Compatibility: 1.3.4rc2 and later

The StatCacheControlsACLs directive configures access lists of users or groups who are allowed (or denied) the ability to use the actions implemented by mod_statcache. The default behavior is to deny everyone unless an ACL allowing access has been explicitly configured.

If "allow" is used, then list, a comma-delimited list of users or groups, can use the given actions; all others are denied. If "deny" is used, then the list of users or groups cannot use actions all others are allowed. Multiple StatCacheControlsACLs directives may be used to configure ACLs for different control actions, and for both users and groups.

The action provided by mod_statcache is "statcache".

Examples:

  # Allow only user root to examine cache stats
  StatCacheControlsACLs all allow user root

StatCacheEngine

Syntax: StatCacheEngine on|off
Default: StatCacheEngine off
Context: server config, <VirtualHost>, <Global>
Module: mod_statcache
Compatibility: 1.3.4rc2 and later

The StatCacheEngine directive enables or disables the module's caching of stat(2) and lstat(2) calls.

StatCacheMaxAge

Syntax: StatCacheMaxAge positive-cache-age [negative-cache-age]
Default: StatCacheMaxAge 5
Context: server config
Module: mod_statcache
Compatibility: 1.3.4rc2 and later

The StatCacheMaxAge directive configures how long the mod_statcache module will keep the stat(2) or lstat(2) results cached for a given path. By default, mod_statcache will cache results for 5 seconds (and will cache failed stat(2)/lstat(2) calls for 1 second).

If you configure a single age parameter, then that value will be used for both positive and negative cache entries. Thus:

  StatCacheMaxAge 300

will cache successful and failed stat(2)/lstat(2) calls for 5 minutes (300 seconds).

To disable caching of failed stat(2)/lstat(2) calls entirely, use a negative-cache-age value of zero, e.g.:

  # Cache lookups for 60 seconds, and do not cache failed lookups
  StatCacheMaxAge 60 0

StatCacheTable

Syntax: StatCacheTable path
Default: None
Context: server config
Module: mod_statcache
Compatibility: 1.3.4rc2 and later

The StatCacheTable directive configures a path to a file that mod_statcache uses for handling its cache data. The given path must be an absolute path. Note: this directive is required for mod_statcache to function. It is recommended that this file not be on an NFS mounted partition.

Note that statcache data is not kept across daemon stop/starts. That is, once proftpd is shutdown, all current statcache data is lost.

Control Actions

`statcache`

Syntax: ftpdctl statcache info|dump
Purpose: Display statcache information

The statcache action is used to display cache statistics about the statcache data maintained by mod_statcache. For example:

  # ftpdctl statcache info
  ftpdctl:  hits 773, misses 67: 92.0% hit rate
  ftpdctl:    expires 22, rejects 0
  ftpdctl:  current count: 1 (of 5000) (0.0% usage)
  ftpdctl:  highest count: 45 (of 5000) (0.9% usage)

To dump out the entire cache contents (not recommended on a busy server), you can use:

  # ftpdctl statcache dump

Installation

The mod_statcache module is distributed with ProFTPD. For including mod_statcache as a statically linked module, use:

  $ ./configure --with-modules=mod_statcache

To build mod_statcache as a DSO module:

  $ ./configure --enable-dso --with-shared=mod_statcache

Then follow the usual steps:

  $ make
  $ make install

For those with an existing ProFTPD installation, you can use the prxs tool to add mod_statcache, as a DSO module, to your existing server:

  $ prxs -c -i -d mod_statcache.c

Note: Use of the mod_statcache module will interfere with the mod_vroot and mod_quotatab modules.

Usage

The mod_statcache module works by allocating a SysV shared memory segment. The different proftpd session processes then attach to that shared memory segment so that they can share statcache results.

Example configuration:

  <IfModule mod_statcache.c>
    StatCacheEngine on
    StatCacheTable /var/run/proftpd/statcache.tab
  </IfModule>