# omlibdbi: Generic Database Output Module

Module Name: | omlibdbi
Author: | Rainer Gerhards <rgerhards@adiscon.com>

## Purpose

This modules supports a large number of database systems via libdbi. Libdbi abstracts the database layer and provides drivers for many systems. Drivers are available via the libdbi-drivers project. As of this writing, the following drivers are available:

- Firebird/Interbase

- FreeTDS (provides access to MS SQL Server and Sybase)

- MySQL (also supported via the native ommysql plugin in rsyslog)

- PostgreSQL(also supported via the native ommysql plugin in rsyslog)

- SQLite/SQLite3

The following drivers are in various stages of completion:

- Ingres

- mSQL

- Oracle

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. ommysql: MySQL Database Output Module) 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

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
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

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | none | no | none

Standard template used for the actions.

### Action Parameters

#### Driver

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
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` (ommysql: MySQL Database Output Module is recommended instead)

- `firebird` (Firebird and InterBase)

- `ingres`

- `msql`

- `Oracle`

- `sqlite`

- `sqlite3`

- `freetds` (for Microsoft SQL and Sybase)

- `pgsql` (PostgreSQL Database Output Module (ompgsql) is recommended instead)

#### Server

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | none | yes | `$ActionLibdbiHost`

The host to connect to.

#### UID

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | none | yes | `$ActionLibdbiUserName`

The user used to connect to the database.

#### PWD

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | none | yes | `$ActionlibdbiPassword`

That user’s password.

#### DB

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
word | none | yes | `$ActionlibdbiDBName`

The database that shall be written to.

#### Template

type | default | mandatory | `obsolete legacy` directive
--- | --- | --- | ---
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.

## 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”.

    module(load="omlibdbi")
    action(type="omlibdbi" driver="mysql" server="mysqlserver.example.com"
                           uid="user" pwd="pwd" db="syslog_db")

See also

Help with configuring/using `Rsyslog`:

- Mailing list - best route for general questions

- GitHub: rsyslog source project - detailed questions, reporting issues that are believed to be bugs with `Rsyslog`

- Stack Exchange (View, Ask) - experimental support from rsyslog community

See also

Contributing to `Rsyslog`:

- Source project: rsyslog project README.

- Documentation: rsyslog-doc project README

Copyright 2008-2020 Rainer Gerhards (Großrinderfeld), and Others.