<!DOCTYPE html>
<html>
<head>
<title>ProFTPD module mod_statcache</title>
</head>
<body bgcolor=white>
<hr>
<center>
<h2><b>ProFTPD module <code>mod_statcache</code></b></h2>
</center>
<hr><br>
<p>
The <code>mod_statcache</code> module is designed to cache the results
of <code>stat(2)</code> and <code>lstat(2)</code> 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
<code>stat(2)</code>/<code>lstat(2)</code> calls can add quite a bit of
overhead.
<p>
This module is contained in the <code>mod_statcache.c</code> file for
ProFTPD 1.3.<i>x</i>, and is not compiled by default. Installation
instructions are discussed <a href="#Installation">here</a>. More examples
of <code>mod_statcache</code> usage can be found <a href="#Usage">here</a>.
<p>
The most current version of <code>mod_statcache</code> is distributed with the
ProFTPD source code.
<h2>Author</h2>
<p>
Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any
questions, concerns, or suggestions regarding this module.
<h2>Directives</h2>
<ul>
<li><a href="#StatCacheCapacity">StatCacheCapacity</a>
<li><a href="#StatCacheControlsACLs">StatCacheControlsACLs</a>
<li><a href="#StatCacheEngine">StatCacheEngine</a>
<li><a href="#StatCacheMaxAge">StatCacheMaxAge</a>
<li><a href="#StatCacheTable">StatCacheTable</a>
</ul>
<h2>Control Actions</h2>
<ul>
<li><a href="#statcache"><code>statcache</code></a>
</ul>
<p>
<hr>
<h3><a name="StatCacheCapacity">StatCacheCapacity</a></h3>
<strong>Syntax:</strong> StatCacheCapacity <em>count</em><br>
<strong>Default:</strong> <em>StatCacheCapacity 5000</em><br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_statcache<br>
<strong>Compatibility:</strong> 1.3.4rc2 and later
<p>
The <code>StatCacheCapacity</code> directive configures the <i>capacity</i>
of the cache, <i>i.e.</i> the maximum number of cache entries. By default,
<code>mod_statcache</code> allocates space for 5000 cache entries.
<p>
The <em>count</em> value be 10 or greater. The configured <em>count</em>
is handled as a <i>hint</i>; the actual allocated capacity may be rounded up
to the nearest multiple of the internal block sizes.
<p>
<hr>
<h3><a name="StatCacheControlsACLs">StatCacheControlsACLs</a></h3>
<strong>Syntax:</strong> StatCacheControlsACLs <em>actions|"all" "allow"|"deny" "user"|"group" list</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_statcache<br>
<strong>Compatibility:</strong> 1.3.4rc2 and later
<p>
The <code>StatCacheControlsACLs</code> directive configures access lists of
<em>users</em> or <em>groups</em> who are allowed (or denied) the ability to
use the <em>actions</em> implemented by <code>mod_statcache</code>. The default
behavior is to deny everyone unless an ACL allowing access has been explicitly
configured.
<p>
If "allow" is used, then <em>list</em>, a comma-delimited list
of <em>users</em> or <em>groups</em>, can use the given <em>actions</em>; all
others are denied. If "deny" is used, then the <em>list</em> of
<em>users</em> or <em>groups</em> cannot use <em>actions</em> all others are
allowed. Multiple <code>StatCacheControlsACLs</code> directives may be used to
configure ACLs for different control actions, and for both users and groups.
<p>
The <em>action</em> provided by <code>mod_statcache</code> is
<a href="#statcache">"statcache"</a>.
<p>
Examples:
<pre>
# Allow only user root to examine cache stats
StatCacheControlsACLs all allow user root
</pre>
<p>
<hr>
<h3><a name="StatCacheEngine">StatCacheEngine</a></h3>
<strong>Syntax:</strong> StatCacheEngine <em>on|off</em><br>
<strong>Default:</strong> <em>StatCacheEngine off</em><br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_statcache<br>
<strong>Compatibility:</strong> 1.3.4rc2 and later
<p>
The <code>StatCacheEngine</code> directive enables or disables the module's
caching of <code>stat(2)</code> and <code>lstat(2)</code> calls.
<p>
<hr>
<h3><a name="StatCacheMaxAge">StatCacheMaxAge</a></h3>
<strong>Syntax:</strong> StatCacheMaxAge <em>positive-cache-age [negative-cache-age]</em><br>
<strong>Default:</strong> <em>StatCacheMaxAge 5</em><br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_statcache<br>
<strong>Compatibility:</strong> 1.3.4rc2 and later
<p>
The <code>StatCacheMaxAge</code> directive configures how long the
<code>mod_statcache</code> module will keep the <code>stat(2)</code> or
<code>lstat(2)</code> results cached for a given path. By default,
<code>mod_statcache</code> will cache results for 5 seconds (and will
cache <i>failed</i> <code>stat(2)</code>/<code>lstat(2)</code> calls for
1 second).
<p>
If you configure a single age parameter, then that value will be used for
both positive and negative cache entries. Thus:
<pre>
StatCacheMaxAge 300
</pre>
will cache successful <em>and</em> failed
<code>stat(2)</code>/<code>lstat(2)</code> calls for 5 minutes (300 seconds).
<p>
To disable caching of failed <code>stat(2)</code>/<code>lstat(2)</code> calls
entirely, use a <em>negative-cache-age</em> value of zero, <i>e.g.</i>:
<pre>
# Cache lookups for 60 seconds, and do not cache failed lookups
StatCacheMaxAge 60 0
</pre>
<p>
<hr>
<h3><a name="StatCacheTable">StatCacheTable</a></h3>
<strong>Syntax:</strong> StatCacheTable <em>path</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config<br>
<strong>Module:</strong> mod_statcache<br>
<strong>Compatibility:</strong> 1.3.4rc2 and later
<p>
The <code>StatCacheTable</code> directive configures a <em>path</em> to a file
that <code>mod_statcache</code> uses for handling its cache data. The given
<em>path</em> must be an absolute path. <b>Note</b>: this directive is
<b>required</b> for <code>mod_statcache</code> to function. It is recommended
that this file <b>not</b> be on an NFS mounted partition.
<p>
Note that statcache data <b>is not</b> kept across daemon stop/starts. That is,
once <code>proftpd</code> is shutdown, all current statcache data is lost.
<p>
<hr>
<h2>Control Actions</h2>
<p>
<hr>
<h3><a name="statcache"><code>statcache</code></a></h3>
<strong>Syntax:</strong> ftpdctl statcache <em>info|dump</em><br>
<strong>Purpose:</strong> Display statcache information<br>
<p>
The <code>statcache</code> action is used to display cache statistics about
the statcache data maintained by <code>mod_statcache</code>. For example:
<pre>
# 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)
</pre>
To dump out the entire cache contents (not recommended on a busy server),
you can use:
<pre>
# ftpdctl statcache dump
</pre>
<p>
<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_statcache</code> module is distributed with ProFTPD. For
including <code>mod_statcache</code> as a statically linked module, use:
<pre>
$ ./configure --with-modules=mod_statcache
</pre>
To build <code>mod_statcache</code> as a DSO module:
<pre>
$ ./configure --enable-dso --with-shared=mod_statcache
</pre>
Then follow the usual steps:
<pre>
$ make
$ make install
</pre>
<p>
For those with an existing ProFTPD installation, you can use the
<code>prxs</code> tool to add <code>mod_statcache</code>, as a DSO module, to
your existing server:
<pre>
$ prxs -c -i -d mod_statcache.c
</pre>
<p>
<b>Note</b>: Use of the <code>mod_statcache</code> module <b>will</b>
interfere with the <code>mod_vroot</code> and <code>mod_quotatab</code>
modules.
<p>
<hr>
<h2><a name="Usage">Usage</a></h2>
<p>
The <code>mod_statcache</code> module works by allocating a SysV shared
memory segment. The different <code>proftpd</code> session processes
then attach to that shared memory segment so that they can share statcache
results.
<p>
Example configuration:
<pre>
<IfModule mod_statcache.c>
StatCacheEngine on
StatCacheTable /var/run/proftpd/statcache.tab
</IfModule>
</pre>
<p>
<hr>
<font size=2><b><i>
© Copyright 2013-2017 TJ Saunders<br>
All Rights Reserved<br>
</i></b></font>
<hr>
</body>
</html>
|