diff options
Diffstat (limited to 'doc/omlibdbi.html')
| -rw-r--r-- | doc/omlibdbi.html | 126 |
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: omlibdbi</b></p> +<p><b>Author: </b>Rainer Gerhards +<rgerhards@adiscon.com></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 expression 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 |