1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
****************************************
omlibdbi: Generic Database Output Module
****************************************
=========================== ===========================================================================
**Module Name:** **omlibdbi**
**Author:** `Rainer Gerhards <https://rainer.gerhards.net/>`_ <rgerhards@adiscon.com>
=========================== ===========================================================================
Purpose
=======
This modules supports a large number of database systems via
`libdbi <http://libdbi.sourceforge.net/>`_. Libdbi abstracts the
database layer and provides drivers for many systems. Drivers are
available via the
`libdbi-drivers <http://libdbi-drivers.sourceforge.net/>`_ project. As
of this writing, the following drivers are available:
- `Firebird/Interbase <http://www.firebird.sourceforge.net/>`_
- `FreeTDS <http://www.freetds.org/>`_ (provides access to `MS SQL
Server <http://www.microsoft.com/sql>`_ and
`Sybase <http://www.sybase.com/products/informationmanagement/adaptiveserverenterprise>`_)
- `MySQL <http://www.mysql.com/>`_ (also supported via the native
`ommysql <ommysql.html>`_ plugin in rsyslog)
- `PostgreSQL <http://www.postgresql.org/>`_\ (also supported via the
native `ommysql <ommysql.html>`_ plugin in rsyslog)
- `SQLite/SQLite3 <http://www.sqlite.org/>`_
The following drivers are in various stages of completion:
- `Ingres <http://ingres.com/>`_
- `mSQL <http://www.hughes.com.au/>`_
- `Oracle <http://www.oracle.com/>`_
These drivers seem to be quite usable, at least from an rsyslog point of
view.
Libdbi provides a slim layer between rsyslog and the actual database
engine. We have not yet done any performance testing (e.g. omlibdbi vs.
:doc:`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.
Setup
=====
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.
Configuration Parameters
========================
.. note::
Parameter names are case-insensitive.
Module Parameters
-----------------
DriverDirectory
^^^^^^^^^^^^^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "none", "no", "``$ActionLibdbiDriverDirectory``"
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 not use this configuration parameter.
Usually, everything works just fine.
Template
^^^^^^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "none", "no", "none"
Standard template used for the actions.
Action Parameters
-----------------
Driver
^^^^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "none", "yes", "``$ActionLibdbiDriver``"
Name of the dbidriver to use, see libdbi-drivers documentation. As a
quick excerpt, at least those were available at the time of this
writing:
- ``mysql`` (:doc:`ommysql` is recommended instead)
- ``firebird`` (Firebird and InterBase)
- ``ingres``
- ``msql``
- ``Oracle``
- ``sqlite``
- ``sqlite3``
- ``freetds`` (for Microsoft SQL and Sybase)
- ``pgsql`` (:doc:`ompgsql` is recommended instead)
Server
^^^^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "none", "yes", "``$ActionLibdbiHost``"
The host to connect to.
UID
^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "none", "yes", "``$ActionLibdbiUserName``"
The user used to connect to the database.
PWD
^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "none", "yes", "``$ActionlibdbiPassword``"
That user's password.
DB
^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "none", "yes", "``$ActionlibdbiDBName``"
The database that shall be written to.
Template
^^^^^^^^
.. csv-table::
:header: "type", "default", "mandatory", "|FmtObsoleteName| directive"
:widths: auto
:class: parameter-table
"word", "none", "no", "none"
Template used for this action.
Caveats/Known Bugs:
===================
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!
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.
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
`http://www.rsyslog.com <http://www.rsyslog.com>`_.
Examples
========
Example 1
---------
The following sample writes all syslog messages to the database
"syslog_db" on mysqlserver.example.com. The server is MySQL and being
accessed under the account of "user" with password "pwd".
.. code-block:: none
module(load="omlibdbi")
action(type="omlibdbi" driver="mysql" server="mysqlserver.example.com"
uid="user" pwd="pwd" db="syslog_db")
|
