trAvis - MANAGER

Edit File: mod_log_forensic.html

<html>
<head>
<title>ProFTPD module mod_log_forensic</title>
</head>

<hr>
<center>
<h2>ProFTPD module <code>mod_log_forensic</code></h2>
</center>
<hr>

The <code>mod_log_forensic</code> module "captures" log messages generated
by <code>proftpd</code>, for all sorts of log destinations, even if those
log messages would otherwise not be written out, and buffers them
in memory. When certain criteria are met (e.g. failed logins,
segfaults, etc), 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>.

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>

Please contact TJ Saunders &lt;tj at castaglia.org&gt; 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>

<hr>
<h2><a name="ForensicLogBufferSize">ForensicLogBufferSize</a></h2>
Syntax: ForensicLogBufferSize count 
Default: 1024 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_log_forensic 
Compatibility: 1.3.4rc3 and later

The <code>ForensicLogBufferSize</code> directives configures the count
of log messages that <code>mod_log_forensic</code> will buffer. It is
effectively the count of the last count log messages you wish to
see logged, when one of the
<a href="#ForensicLogCriteria"><code>ForensicLogCriteria</code></a> are met.

<hr>
<h2><a name="ForensicLogCapture">ForensicLogCapture</a></h2>
Syntax: ForensicLogCapture log-type1 ... 
Default: Unspec TransferLog syslog SystemLog ExtendedLog TraceLog 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_log_forensic 
Compatibility: 1.3.4rc3 and later

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.

The supported log types are:
<ul>
 <li><code>Unspec</code>
 
 This "type" covers any unspecified/unknown log, e.g. module-specific
 log files such as <code>SFTPLog</code>, <code>SQLLogFile</code>,
 <code>TLSLog</code>, etc.
 </li>

<li><code>TransferLog</code>
 <li><code>syslog</code>
 <li><code>SystemLog</code>
 <li><code>ExtendedLog</code>
 <li><code>TraceLog</code>
</ul>

<hr>
<h2><a name="ForensicLogCriteria">ForensicLogCriteria</a></h2>
Syntax: ForensicLogCriteria criterion1 ... 
Default: FailedLogin UntimelyDeath 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_log_forensic 
Compatibility: 1.3.4rc3 and later

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.

The currently supported criteria are:
<ul>
 <li><code>FailedLogin</code>
 
 The buffered log messages will be written to the
 <code>ForensicLogFile</code> if the login fails for any reason.
 </li>

<li><code>UntimelyDeath</code>
 
 If a session dies prematurely, e.g. due to a segfault or other
 internal error, the buffered log messages will be written to the
 <code>ForensicLogFile</code>.
 </li>

<li><code>ModuleConfig</code>
 
 If a session dies due to a module-specific policy, the buffered log
 messages will be written to the <code>ForensicLogFile</code>.
 </li>
</ul>

<hr>
<h2><a name="ForensicLogEngine">ForensicLogEngine</a></h2>
Syntax: ForensicLogEngine on|off 
Default: off 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_log_forensic 
Compatibility: 1.3.4rc3 and later

The <code>ForensicLogEngine</code> directive enables or disables the
<code>mod_log_forensic</code> module.

<hr>
<h2><a name="ForensicLogFile">ForensicLogFile</a></h2>
Syntax: ForensicLogFile file 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_log_forensic 
Compatibility: 1.3.4rc3 and later

The <code>ForensicLogFile</code> directive configures a file used for logging
by <code>mod_log_forensic</code>. The configured file must be an
absolute path.

Note that this directive is required for
<code>mod_log_forensic</code> to function properly.

<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 proftpd-dir/contrib/
</pre>
after unpacking the latest proftpd-1.3.x 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>

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>

<hr>
<h2><a name="Usage">Usage</a></h2>

Example <code>mod_log_forensic</code> configuration:
<pre>
 &lt;IfModule mod_log_forensic.c&gt;
 ForensicLogEngine on
 ForensicLogFile /path/to/forensic.log
 &lt;/IfModule&gt;
</pre>

For a failed login, the configured <code>ForensicLogFile</code> will
contain a block of log lines, e.g.:
<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>

Advantages 
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.e. high <code>DebugLevel</code> and/or
<code>Trace</code> levels). If ProFTPD generated a log message internally
but that log message was filtered, then that log message would not
normally be written to disk -- but <code>mod_log_forensic</code> buffers
that log message anyway.

To see this, simply use the following in your <code>proftpd.conf</code>:
<pre>
 TraceLog /path/to/ftpd/trace.log
 Trace DEFAULT:0

&lt;IfModule mod_log_forensic.c&gt;
 ForensicLogEngine on
 ForensicLogFile /path/to/ftpd/forensic.log
 &lt;/IfModule&gt;
</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.

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.

<hr>

Author: $Author: castaglia $ 
Last Updated: $Date: 2013-08-14 21:40:17 $

<hr>

<hr>

</body>
</html>