summaryrefslogtreecommitdiffstats
path: root/doc/omlibdbi.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/omlibdbi.html')
-rw-r--r--doc/omlibdbi.html126
1 files changed, 126 insertions, 0 deletions
diff --git a/doc/omlibdbi.html b/doc/omlibdbi.html
new file mode 100644
index 00000000..c66dc06b
--- /dev/null
+++ b/doc/omlibdbi.html
@@ -0,0 +1,126 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head>
+<meta http-equiv="Content-Language" content="en"><title>Generic Database Output Module (omlibdbi)</title>
+
+</head>
+<body>
+<h1>Generic Database Output Module (omlibdbi)</h1>
+<p><b>Module Name:&nbsp;&nbsp;&nbsp; omlibdbi</b></p>
+<p><b>Author: </b>Rainer Gerhards
+&lt;rgerhards@adiscon.com&gt;</p>
+<p><b>Description</b>:</p>
+<p>This modules supports a large number of database systems via <a href="http://libdbi.sourceforge.net/">libdbi</a>.
+Libdbi abstracts the database layer and provides drivers for many
+systems. Drivers are available via the <a href="http://libdbi-drivers.sourceforge.net/">libdbi-drivers</a>
+project. As of this writing, the following drivers are available:</p>
+<ul>
+<li><a href="http://www.firebird.sourceforge.net/">Firebird/Interbase</a></li>
+<li><a href="http://www.freetds.org/">FreeTDS</a>
+(provides access to <a href="http://www.microsoft.com/sql">MS
+SQL Server</a> and <a href="http://www.sybase.com/products/informationmanagement/adaptiveserverenterprise">Sybase</a>)</li>
+<li><a href="http://www.mysql.com/">MySQL</a>
+(also
+supported via the native ommysql plugin in rsyslog)</li>
+<li><a href="http://www.postgresql.org/">PostgreSQL</a>(also
+supported via the native
+ommysql plugin in rsyslog)</li>
+<li><a href="http://www.sqlite.org/">SQLite/SQLite3</a></li>
+</ul>
+<p>The following drivers are in various stages of completion:</p>
+<ul>
+<li><a href="http://ingres.com/">Ingres</a></li>
+<li><a href="http://www.hughes.com.au/">mSQL</a></li>
+<li><a href="http://www.oracle.com/">Oracle</a></li>
+</ul>
+<p>These drivers seem to be quite usable, at
+least from an rsyslog point of view.</p>
+<p>Libdbi provides a slim layer between rsyslog and the actual
+database engine. We have not yet done any performance testing (e.g.
+omlibdbi vs. ommysql) but honestly believe that the performance impact
+should be irrelevant, if at all measurable. Part of that assumption is
+that rsyslog just does the "insert" and most of the time is spent
+either in the database engine or rsyslog itself. It's hard to think of
+any considerable time spent in the libdbi abstraction layer.</p>
+<p><span style="font-weight: bold;">Setup</span></p>
+<p>In order for this plugin to work, you need to have libdbi, the
+libdbi driver for your database backend and the client software for
+your database backend installed. There are libdbi packages for many
+distributions. Please note that rsyslogd requires a quite recent
+version (0.8.3) of libdbi. It may work with older versions, but these
+need some special ./configure options to support being called from a
+dlopen()ed plugin (as omlibdbi is). So in short, you probably save you
+a lot of headache if you make sure you have at least libdbi version
+0.8.3 on your system.
+</p>
+<p><b>Configuration Directives</b>:</p>
+<ul>
+<li><span style="font-weight: bold;">$ActionLibdbiDriverDirectory /path/to/dbd/drivers</span><br>This
+is a global setting. It points libdbi to its driver directory. Usually,
+you do not need to set it. If you installed libdbi-driver's at a
+non-standard location, you may need to specify the directory here. If
+you are unsure, do <span style="font-weight: bold;">not</span> use this configuration directive. Usually, everything works just fine.<strong></strong></li><li><strong>$ActionLibdbiDriver drivername</strong><br>
+Name of the dbidriver to use, see libdbi-drivers documentation. As a
+quick excerpt, at least those were available at the time of this
+writiting "mysql" (suggest to use ommysql instead), "firebird" (Firbird
+and InterBase), "ingres", "msql", "Oracle", "sqlite", "sqlite3",
+"freetds" (for Microsoft SQL and Sybase) and "pgsql" (suggest to use
+ompgsql instead).</li>
+<li><span style="font-weight: bold;">$ActionLibdbiHost
+hostname</span><br>
+The host to connect to.</li>
+<li><span style="font-weight: bold;">$ActionLibdbiUserName
+user</span><br>
+The user used to connect to the database.</li>
+<li><span style="font-weight: bold;">$ActionlibdbiPassword</span><br>
+That user's password.</li>
+<li><span style="font-weight: bold;">$ActionlibdbiDBName
+db</span><br>
+The database that shall be written to.</li>
+<li><span style="font-weight: bold;">selector
+line: :omlibdbi:<span style="font-style: italic;">;template</span></span><br>
+executes the recently configured omlibdbi action. The ;template part is
+optional. If no template is provided, a default template is used (which
+is currently optimized for MySQL - sorry, folks...)</li>
+</ul>
+<b>Caveats/Known Bugs:</b>
+<p>You must make sure that any templates used for omlibdbi
+properly escape strings. This is usually done by supplying the SQL (or
+STDSQL) option to the template. Omlibdbi rejects templates without this
+option for security reasons. However, omlibdbi does not detect if you
+used the right option for your backend. Future versions of rsyslog
+(with full&nbsp;expression&nbsp; support) will provide advanced
+ways of handling this situation. So far, you must be careful. The
+default template provided by rsyslog is suitable for MySQL, but not
+necessarily for your database backend. Be careful!</p>
+<p>If you receive the rsyslog error message "libdbi or libdbi
+drivers not present on this system" you may either not have libdbi and
+its drivers installed or (very probably) the version is earlier than
+0.8.3. In this case, you need to make sure you have at least 0.8.3 and
+the libdbi driver for your database backend present on your system.</p><p>I
+do not have most of the database supported by omlibdbi in my lab. So it
+received limited cross-platform tests. If you run into troubles, be
+sure the let us know at <a href="http://www.rsyslog.com">http://www.rsyslog.com</a>.</p>
+<p><b>Sample:</b></p>
+<p>The following sample writes all syslog messages to the
+database "syslog_db" on mysqlsever.example.com. The server is MySQL and
+being accessed under the account of "user" with password "pwd" (if you
+have empty passwords, just remove the $ActionLibdbiPassword line).<br>
+</p>
+<textarea rows="15" cols="60">$ModLoad omlibdbi.so
+$ActionLibdbiDriver mysql
+$ActionLibdbiHost mysqlserver.example.com
+$ActionLibdbiUserName user
+$ActionLibdbiPassword pwd
+$ActionLibdbiDBName syslog_db
+*.* :omlibdbi:
+</textarea>
+<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
+[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
+<p><font size="2">This documentation is part of the
+<a href="http://www.rsyslog.com/">rsyslog</a>
+project.<br>
+Copyright © 2008 by <a href="http://www.gerhards.net/rainer">Rainer
+Gerhards</a> and
+<a href="http://www.adiscon.com/">Adiscon</a>.
+Released under the GNU GPL version 3 or higher.</font></p>
+</body></html> \ No newline at end of file