| Current File : //usr/share/doc/proftpd-1.3.5e/contrib/mod_log_forensic.html |
<!-- $Id: mod_log_forensic.html,v 1.3 2013-08-14 21:40:17 castaglia Exp $ -->
<!-- $Source: /home/proftpd-core/backup/proftp-cvsroot/proftpd/doc/contrib/mod_log_forensic.html,v $ -->
<html>
<head>
<title>ProFTPD module mod_log_forensic</title>
</head>
<body bgcolor=white>
<hr>
<center>
<h2><b>ProFTPD module <code>mod_log_forensic</code></b></h2>
</center>
<hr><br>
<p>
The <code>mod_log_forensic</code> module "captures" log messages generated
by <code>proftpd</code>, for all sorts of log destinations, <i>even if those
log messages would otherwise <b>not</b> be written out</i>, and buffers them
in memory. When certain criteria are met (<i>e.g.</i> failed logins,
segfaults, <i>etc</i>), the <code>mod_log_forensic</code> module will flush
the buffered log messages out to a file. Installation instructions are
discussed <a href="#Installation">here</a>.
<p>
The most current version of <code>mod_log_forensic</code> can be found at:
<pre>
<a href="http://www.castaglia.org/proftpd/">http://www.castaglia.org/proftpd/</a>
</pre>
<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="#ForensicLogBufferSize">ForensicLogBufferSize</a>
<li><a href="#ForensicLogCapture">ForensicLogCapture</a>
<li><a href="#ForensicLogCriteria">ForensicLogCriteria</a>
<li><a href="#ForensicLogEngine">ForensicLogEngine</a>
<li><a href="#ForensicLogFile">ForensicLogFile</a>
</ul>
<p>
<hr>
<h2><a name="ForensicLogBufferSize">ForensicLogBufferSize</a></h2>
<strong>Syntax:</strong> ForensicLogBufferSize <em>count</em><br>
<strong>Default:</strong> 1024<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_log_forensic<br>
<strong>Compatibility:</strong> 1.3.4rc3 and later
<p>
The <code>ForensicLogBufferSize</code> directives configures the <em>count</em>
of log messages that <code>mod_log_forensic</code> will buffer. It is
effectively the count of the last <em>count</em> log messages you wish to
see logged, when one of the
<a href="#ForensicLogCriteria"><code>ForensicLogCriteria</code></a> are met.
<p>
<hr>
<h2><a name="ForensicLogCapture">ForensicLogCapture</a></h2>
<strong>Syntax:</strong> ForensicLogCapture <em>log-type1 ...</em><br>
<strong>Default:</strong> Unspec TransferLog syslog SystemLog ExtendedLog TraceLog<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_log_forensic<br>
<strong>Compatibility:</strong> 1.3.4rc3 and later
<p>
The <code>ForensicLogCapture</code> directive configures which log types
the <code>mod_log_forensic</code> module "captures" for later writing. By
default, <code>mod_log_forensic</code> captures messages for all log types.
<p>
The supported log types are:
<ul>
<li><code>Unspec</code>
<p>
This "type" covers any unspecified/unknown log, <i>e.g.</i> module-specific
log files such as <code>SFTPLog</code>, <code>SQLLogFile</code>,
<code>TLSLog</code>, <i>etc</i>.
</li>
<p>
<li><code>TransferLog</code>
<li><code>syslog</code>
<li><code>SystemLog</code>
<li><code>ExtendedLog</code>
<li><code>TraceLog</code>
</ul>
<p>
<hr>
<h2><a name="ForensicLogCriteria">ForensicLogCriteria</a></h2>
<strong>Syntax:</strong> ForensicLogCriteria <em>criterion1 ...</em><br>
<strong>Default:</strong> FailedLogin UntimelyDeath<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_log_forensic<br>
<strong>Compatibility:</strong> 1.3.4rc3 and later
<p>
The <code>ForensicLogCriteria</code> directive configures the criteria
which determine when <code>mod_log_forensic</code> will flush its buffered
log messages out to the configured
<a href="#ForensicLogFile"><code>ForensicLogFile</code></a>. Multiple
criteria can be specified.
<p>
The currently supported criteria are:
<ul>
<li><code>FailedLogin</code>
<p>
The buffered log messages will be written to the
<code>ForensicLogFile</code> if the login fails for any reason.
</li>
<p>
<li><code>UntimelyDeath</code>
<p>
If a session dies prematurely, <i>e.g.</i> due to a segfault or other
internal error, the buffered log messages will be written to the
<code>ForensicLogFile</code>.
</li>
<p>
<li><code>ModuleConfig</code>
<p>
If a session dies due to a module-specific policy, the buffered log
messages will be written to the <code>ForensicLogFile</code>.
</li>
</ul>
<p>
<hr>
<h2><a name="ForensicLogEngine">ForensicLogEngine</a></h2>
<strong>Syntax:</strong> ForensicLogEngine <em>on|off</em><br>
<strong>Default:</strong> off<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_log_forensic<br>
<strong>Compatibility:</strong> 1.3.4rc3 and later
<p>
The <code>ForensicLogEngine</code> directive enables or disables the
<code>mod_log_forensic</code> module.
<p>
<hr>
<h2><a name="ForensicLogFile">ForensicLogFile</a></h2>
<strong>Syntax:</strong> ForensicLogFile <em>file</em><br>
<strong>Default:</strong> None<br>
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
<strong>Module:</strong> mod_log_forensic<br>
<strong>Compatibility:</strong> 1.3.4rc3 and later
<p>
The <code>ForensicLogFile</code> directive configures a file used for logging
by <code>mod_log_forensic</code>. The configured <em>file</em> must be an
absolute path.
<p>
<b>Note</b> that this directive is <b>required</b> for
<code>mod_log_forensic</code> to function properly.
<p>
<hr>
<h2><a name="Installation">Installation</a></h2>
To install <code>mod_log_forensic</code>, copy the
<code>mod_log_forensic.c</code> into the third-party module directory in
the proftpd source code:
<pre>
# cp mod_log_forensic.c <i>proftpd-dir</i>/contrib/
</pre>
after unpacking the latest proftpd-1.3.<i>x</i> source code. For including
<code>mod_log_forensic</code> as a staticly linked module:
<pre>
./configure --with-modules=mod_log_forensic ...
</pre>
Alternatively, <code>mod_log_forensic</code> can be built as a DSO module:
<pre>
./configure --enable-dso --with-shared=mod_log_forensic ...
</pre>
Then follow the usual steps:
<pre>
make
make install
</pre>
<p>
Alternatively, if your proftpd was compiled with DSO support, you can
use the <code>prxs</code> tool to build <code>mod_log_forensic</code> as a
shared module:
<pre>
prxs -c -i -d mod_log_forensic.c
</pre>
<p>
<hr>
<h2><a name="Usage">Usage</a></h2>
<p>
Example <code>mod_log_forensic</code> configuration:
<pre>
<IfModule mod_log_forensic.c>
ForensicLogEngine on
ForensicLogFile /path/to/forensic.log
</IfModule>
</pre>
<p>
For a failed login, the configured <code>ForensicLogFile</code> will
contain a block of log lines, <i>e.g.</i>:
<pre>
-----BEGIN FAILED LOGIN FORENSICS-----
Client-Address: 127.0.0.1
Server-Address: ::ffff:127.0.0.1:5376
Elapsed: 1245
Protocol: ftp
User: tj
UID: 501
GID: 501
Raw-Bytes-In: 46
Raw-Bytes-Out: 158
Total-Bytes-In: 0
Total-Bytes-Out: 0
Total-Files-In: 0
Total-Files-Out: 0
...
[syslog:7, PID 16044] dispatching CMD command 'PASS (hidden)' to mod_auth
[syslog:7, PID 16044] retrieved UID 1000 for user 'tj'
[syslog:7, PID 16044] retrieved group IDs: 1000, 0, 4, 20, 24, 46, 108, 109, 110
[syslog:7, PID 16044] retrieved group names: tj, root, adm, dialout, cdrom, plugdev, lpadmin, sambashare, admin
[syslog:7, PID 16044] ROOT PRIVS at mod_auth_pam.c:312
[syslog:7, PID 16044] RELINQUISH PRIVS at mod_auth_pam.c:482
[syslog:7, PID 16044] ROOT PRIVS at mod_auth_unix.c:467
[syslog:7, PID 16044] RELINQUISH PRIVS at mod_auth_unix.c:548
[SystemLog:5] familiar proftpd[15509] localhost (localhost[127.0.0.1]): USER tj (Login failed): Incorrect password.
[syslog:7, PID 16044] dispatching POST_CMD_ERR command 'PASS (hidden)' to mod_delay
[syslog:7, PID 16044] dispatching LOG_CMD_ERR command 'PASS (hidden)' to mod_log
-----END FAILED LOGIN FORENSICS-----
</pre>
For sessions which suffer an "untimely death", the begin/end markers in the
<code>ForensicLogFile</code> are:
<pre>
-----BEGIN UNTIMELY DEATH FORENSICS-----
Client-Address: 127.0.0.1
Server-Address: ::ffff:127.0.0.1:5376
Elapsed: 1245
Protocol: ftp
User: tj
UID: 501
GID: 501
Raw-Bytes-In: 46
Raw-Bytes-Out: 158
Total-Bytes-In: 0
Total-Bytes-Out: 0
Total-Files-In: 0
Total-Files-Out: 0
...
-----END UNTIMELY DEATH FORENSICS-----
</pre>
<p>
<b>Advantages</b><br>
What's the big deal with this module? What advantage does it provide
over the normal <code>proftpd</code> logging? The advantage is that with
<code>mod_log_forensic</code>, you do not have to configure ProFTPD to use
verbose logging (<i>i.e.</i> high <code>DebugLevel</code> and/or
<code>Trace</code> levels). If ProFTPD generated a log message internally
<b>but</b> that log message was filtered, then that log message would not
normally be written to disk -- <i>but <code>mod_log_forensic</code> buffers
that log message anyway</i>.
<p>
To see this, simply use the following in your <code>proftpd.conf</code>:
<pre>
TraceLog /path/to/ftpd/trace.log
Trace DEFAULT:0
<IfModule mod_log_forensic.c>
ForensicLogEngine on
ForensicLogFile /path/to/ftpd/forensic.log
</IfModule>
</pre>
This configured <code>proftpd</code> for trace logging, but turns the
trace logging levels down to zero so that normally, nothing would be written
in the configured <code>TraceLog</code> file.
<p>
Now attempt to log into <code>proftpd</code>, deliberately using a wrong/bad
password (or unknown user). The <code>mod_log_forensic</code> module will
write out all of the trace logging messages
(and the other <code>SystemLog</code>/syslog messages) to the
<code>ForensicLogFile</code>, even though the debug level is at the default
level of zero, and the trace levels are all zero. Thus you get the verbose
logging needed to help diagnose failed logins and such, without having
the verbose logging enabled all of the time.
<p>
<hr><br>
Author: <i>$Author: castaglia $</i><br>
Last Updated: <i>$Date: 2013-08-14 21:40:17 $</i><br>
<br><hr>
<font size=2><b><i>
© Copyright 2011-2013 TJ Saunders<br>
All Rights Reserved<br>
</i></b></font>
<hr><br>
</body>
</html>