<!DOCTYPE html>
<html>
<head>
<title>ProFTPD module mod_tls_shmcache</title>
</head>
<body bgcolor=white>
<hr>
<center>
<h2><b>ProFTPD module <code>mod_tls_shmcache</code></b></h2>
</center>
<hr>
<p>
The <code>mod_tls_shmcache</code> submodule is contained in the
<code>mod_tls_shmcache.c</code> file, and is not compiled by default.
Installation instructions are discussed <a href="#Installation">here</a>.
<p>
This submodule provides a SysV shared memory-based implementation of
an external SSL session cache for use by the <code>mod_tls</code> module's
<a href="mod_tls.html#TLSSessionCache"><code>TLSSessionCache</code></a>
directive. The module also implements a SysV shared memory-based
implementation of an external OCSP response cache for the
<a href="mod_tls.html#TLSStaplingCache"><code>TLSStaplingCache</code></a>
directive.
<p>
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
<p>
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).
<h2>Author</h2>
<p>
Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any
questions, concerns, or suggestions regarding this module.
<p>
The <code>mod_tls_shmcache</code> module supports the "shm" string
for the <em>type</em> parameter of the
<a href="mod_tls.html#TLSSessionCache"><code>TLSSessionCache</code></a>
configuration directive. The <em>info</em> parameter for
<code>mod_tls_shmcache</code> must be formatted like:
<pre>
/file=<i>/path/to/cache/file</i>[&size=<i>bytes</i>]
</pre>
The configured path is used for synchronizing access to the shared memory
segment among the various server processes. The default shared memory
segment size allocated is 1.5MB; use the optional <em>size</em> key to
configure a different size, in bytes. Note that the configured size
<i>must</i> be able to hold at least one cached session; if a too-small size
is configured, that size will be ignored and the default size will be used.
<p>
The <code>mod_tls_shmcache</code> module also supports the "shm"
string for the <em>type</em> parameter of the
<a href="mod_tls.html#TLSStaplingCache"><code>TLStaplingCache</code></a>
configuration directive. The <em>info</em> parameter for
<code>mod_tls_shmcache</code> must be formatted like:
<pre>
/file=<i>/path/to/cache/file</i>[&size=<i>bytes</i>]
</pre>
The configured path is used for synchronizing access to the shared memory
segment among the various server processes. The default shared memory
segment size allocated is 1.5MB; use the optional <em>size</em> key to
configure a different size, in bytes. Note that the configured size
<i>must</i> be able to hold at least one cached OCSP response; if a too-small
size is configured, that size will be ignored and the default size will be used.
<p>
<b>Examples</b><br>
<p>
Use the default shared memory segment size and timeout:
<pre>
<IfModule mod_tls.c>
...
<IfModule mod_tls_shmcache.c>
TLSSessionCache shm:/file=/var/ftpd/sess_cache
TLSStaplingCache shm:/file=/var/ftpd/ocsp_pcache
</IfModule>
</IfModule>
</pre>
<p>
Use a larger shared memory segment size:
<pre>
<IfModule mod_tls.c>
...
<IfModule mod_tls_shmcache.c>
TLSSessionCache shm:/file=/var/ftpd/sess_cache&size=2097152
TLSStaplingCache shm:/file=/var/ftpd/ocsp_cache&size=2097152
</IfModule>
</IfModule>
</pre>
<p>
Use a smaller shared memory size, and a shorter timeout:
<pre>
<IfModule mod_tls.c>
...
<IfModule mod_tls_shmcache.c>
TLSSessionCache shm:/file=/var/ftpd/sess_cache&size=512000 600
# Note that TLSStaplingCache does not use a timeout
TLSStaplingCache shm:/file=/var/ftpd/ocsp_cache&size=512000
</IfModule>
</IfModule>
</pre>
<p>
<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_tls_shmcache</code> module is distributed with the ProFTPD
source code. Simply follow the normal steps for using third-party modules
in ProFTPD, being sure to include the <code>mod_tls</code> module (on which
<code>mod_tls_shmcache</code> depends):
<pre>
$ ./configure --with-modules=mod_tls:mod_tls_shmcache
$ make
$ make install
</pre>
<p>
Alternatively, if your <code>proftpd</code> was compiled with DSO support, you
can use the <code>prxs</code> tool to build <code>mod_tls_shmcache</code> as
a shared module:
<pre>
$ prxs -c -i -d mod_tls_shmcache.c
</pre>
<p>
<b>Note</b>: If using <code>mod_tls_shmcache</code> as a shared module, make
sure that this module is loaded <i>after</i> the <code>mod_tls</code> module,
<i>i.e.</i>:
<pre>
# Load mod_tls first
LoadModule mod_tls.c
# Then load any SSL caching modules
LoadModule mod_tls_shmcache.c
</pre>
<p>
<hr>
<h2><a name="Usage">Usage</a></h2>
<p>
<b>Logging</b><br>
The <code>mod_tls_shmcache</code> module supports <a href="../howto/Tracing.html">trace logging</a>, via the module-specific log channels:
<ul>
<li>tls.shmcache
</ul>
Thus for trace logging, to aid in debugging, you would use the following in
your <code>proftpd.conf</code>:
<pre>
TraceLog /path/to/ftpd/trace.log
Trace tls.shmcache:20
</pre>
This trace logging can generate large files; it is intended for debugging use
only, and should be removed from any production configuration.
<p><a name="FAQ">
<b>Frequently Asked Questions</b><br>
<p><a name="TLSShmcacheEmptyFile">
<font color=red>Question</font>: I configured a <code>TLSSessionCache</code> file, but it is empty. Is <code>mod_tls_shmcache</code> not working properly?<br>
<font color=blue>Answer</font>: Yes, <code>mod_tls_shmcache</code> is working
properly. The actual cache of SSL/TLS session data is stored in shared memory,
not on the filesystem. Storing data in system shared memory requires a unique
key; the <code>mod_tls_shmcache</code> uses the configured file to create
this unique key. The module also uses the configured
<code>TLSSessionCache</code> file for locking, as when handling a
<code>ftpdctl</code> request to clear the cache.
<p><a name="TLSShmcacheUndefinedSymbol">
<font color=red>Question</font>: I am trying to use
<code>mod_tls_shmcache</code> as a shared module, but my <code>proftpd</code>
server fails to start up, failing with this error:
<pre>
proftpd: symbol lookup error: /usr/local/libexec/mod_tls_shmcache.so: undefined symbol: tls_sess_cache_register
</pre>
<font color=blue>Answer</font>: This happens when your configuration is
loading the <code>mod_tls_shmcache</code> module <i>before</i> the
<code>mod_tls</code> has been loaded. The fix, then, is to make sure
your config looks something like this:
<pre>
LoadModule mod_tls.c
LoadModule mod_tls_shmcache.c
</pre>
<p>
<hr>
<font size=2><b><i>
© Copyright 2009-2015 TJ Saunders<br>
All Rights Reserved<br>
</i></b></font>
<hr>
</body>
</html>
|