1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
3
<meta http-equiv="Content-Language" content="en"><title>Generic Database Output Module (omlibdbi)</title>
7
<h1>Generic Database Output Module (omlibdbi)</h1>
8
<p><b>Module Name: omlibdbi</b></p>
9
<p><b>Author: </b>Rainer Gerhards
10
<rgerhards@adiscon.com></p>
11
<p><b>Description</b>:</p>
12
<p>This modules supports a large number of database systems via <a href="http://libdbi.sourceforge.net/">libdbi</a>.
13
Libdbi abstracts the database layer and provides drivers for many
14
systems. Drivers are available via the <a href="http://libdbi-drivers.sourceforge.net/">libdbi-drivers</a>
15
project. As of this writing, the following drivers are available:</p>
17
<li><a href="http://www.firebird.sourceforge.net/">Firebird/Interbase</a></li>
18
<li><a href="http://www.freetds.org/">FreeTDS</a>
19
(provides access to <a href="http://www.microsoft.com/sql">MS
20
SQL Server</a> and <a href="http://www.sybase.com/products/informationmanagement/adaptiveserverenterprise">Sybase</a>)</li>
21
<li><a href="http://www.mysql.com/">MySQL</a>
23
supported via the native ommysql plugin in rsyslog)</li>
24
<li><a href="http://www.postgresql.org/">PostgreSQL</a>(also
25
supported via the native
26
ommysql plugin in rsyslog)</li>
27
<li><a href="http://www.sqlite.org/">SQLite/SQLite3</a></li>
29
<p>The following drivers are in various stages of completion:</p>
31
<li><a href="http://ingres.com/">Ingres</a></li>
32
<li><a href="http://www.hughes.com.au/">mSQL</a></li>
33
<li><a href="http://www.oracle.com/">Oracle</a></li>
35
<p>These drivers seem to be quite usable, at
36
least from an rsyslog point of view.</p>
37
<p>Libdbi provides a slim layer between rsyslog and the actual
38
database engine. We have not yet done any performance testing (e.g.
39
omlibdbi vs. ommysql) but honestly believe that the performance impact
40
should be irrelevant, if at all measurable. Part of that assumption is
41
that rsyslog just does the "insert" and most of the time is spent
42
either in the database engine or rsyslog itself. It's hard to think of
43
any considerable time spent in the libdbi abstraction layer.</p>
44
<p><span style="font-weight: bold;">Setup</span></p>
45
<p>In order for this plugin to work, you need to have libdbi, the
46
libdbi driver for your database backend and the client software for
47
your database backend installed. There are libdbi packages for many
48
distributions. Please note that rsyslogd requires a quite recent
49
version (0.8.3) of libdbi. It may work with older versions, but these
50
need some special ./configure options to support being called from a
51
dlopen()ed plugin (as omlibdbi is). So in short, you probably save you
52
a lot of headache if you make sure you have at least libdbi version
55
<p><b>Configuration Directives</b>:</p>
57
<li><span style="font-weight: bold;">$ActionLibdbiDriverDirectory /path/to/dbd/drivers</span><br>This
58
is a global setting. It points libdbi to its driver directory. Usually,
59
you do not need to set it. If you installed libdbi-driver's at a
60
non-standard location, you may need to specify the directory here. If
61
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>
62
Name of the dbidriver to use, see libdbi-drivers documentation. As a
63
quick excerpt, at least those were available at the time of this
64
writiting "mysql" (suggest to use ommysql instead), "firebird" (Firbird
65
and InterBase), "ingres", "msql", "Oracle", "sqlite", "sqlite3",
66
"freetds" (for Microsoft SQL and Sybase) and "pgsql" (suggest to use
67
ompgsql instead).</li>
68
<li><span style="font-weight: bold;">$ActionLibdbiHost
70
The host to connect to.</li>
71
<li><span style="font-weight: bold;">$ActionLibdbiUserName
73
The user used to connect to the database.</li>
74
<li><span style="font-weight: bold;">$ActionlibdbiPassword</span><br>
75
That user's password.</li>
76
<li><span style="font-weight: bold;">$ActionlibdbiDBName
78
The database that shall be written to.</li>
79
<li><span style="font-weight: bold;">selector
80
line: :omlibdbi:<span style="font-style: italic;">;template</span></span><br>
81
executes the recently configured omlibdbi action. The ;template part is
82
optional. If no template is provided, a default template is used (which
83
is currently optimized for MySQL - sorry, folks...)</li>
85
<b>Caveats/Known Bugs:</b>
86
<p>You must make sure that any templates used for omlibdbi
87
properly escape strings. This is usually done by supplying the SQL (or
88
STDSQL) option to the template. Omlibdbi rejects templates without this
89
option for security reasons. However, omlibdbi does not detect if you
90
used the right option for your backend. Future versions of rsyslog
91
(with full expression support) will provide advanced
92
ways of handling this situation. So far, you must be careful. The
93
default template provided by rsyslog is suitable for MySQL, but not
94
necessarily for your database backend. Be careful!</p>
95
<p>If you receive the rsyslog error message "libdbi or libdbi
96
drivers not present on this system" you may either not have libdbi and
97
its drivers installed or (very probably) the version is earlier than
98
0.8.3. In this case, you need to make sure you have at least 0.8.3 and
99
the libdbi driver for your database backend present on your system.</p><p>I
100
do not have most of the database supported by omlibdbi in my lab. So it
101
received limited cross-platform tests. If you run into troubles, be
102
sure the let us know at <a href="http://www.rsyslog.com">http://www.rsyslog.com</a>.</p>
103
<p><b>Sample:</b></p>
104
<p>The following sample writes all syslog messages to the
105
database "syslog_db" on mysqlsever.example.com. The server is MySQL and
106
being accessed under the account of "user" with password "pwd" (if you
107
have empty passwords, just remove the $ActionLibdbiPassword line).<br>
109
<textarea rows="15" cols="60">$ModLoad omlibdbi.so
110
$ActionLibdbiDriver mysql
111
$ActionLibdbiHost mysqlserver.example.com
112
$ActionLibdbiUserName user
113
$ActionLibdbiPassword pwd
114
$ActionLibdbiDBName syslog_db
117
<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
118
[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
119
<p><font size="2">This documentation is part of the
120
<a href="http://www.rsyslog.com/">rsyslog</a>
122
Copyright © 2008 by <a href="http://www.gerhards.net/rainer">Rainer
124
<a href="http://www.adiscon.com/">Adiscon</a>.
125
Released under the GNU GPL version 3 or higher.</font></p>
b'\\ No newline at end of file'
added
removed
doc/omlibdbi.html
