Welcome to DBD2
(The Home of DBD2 On-Line Documentation)
This site is the home for on-line DBD2 documentation and reference material.
If you have downloaded the DBD2 project source code and compiled from scratch, you should find a 'docs' directory in your download
containing '.odt' files suitable for producing hard-copies. This site will always be more current than the files made available for download and off-line viewing.
However, attempting to print hardcopies from this website may lead to frustration due to the eye-saving black background-color that will cause excessive use of printer ink.
This site is still under construction, but I wanted to make as much information on DBD2 as available as possible as soon as possible, so please bear with me while I build this documentation site.
Whether acknowledged or not, I believe there is a need and use for an ability to send update information to a database from anywhere in the network
without having to first install (and then maintain) database libraries on every system or having to write specific data-base-related code.
This is the capability DBD2 was originally designed to provide.
Because DBD2 shares a lot of code and concepts with its sister-project: Syslogd2, parts of its
desgn and functionality may seem familiar to users of Syslogd2. However, interoperability of the two projects is maximized.
The main components of the DBD2 project are:
Since its original conception, DBD2 has grown and advanced significantly while still just scratching the surface of what is possible.
For example, the original (dbcl-supporting) server now accepts syslog traffic over TCP. DBD2 uses much of the same code as Syslogd2 when parsing
selector-stringgs (used as routing templates) and when parsing the syslog-input fields (especially the time-field).
DBD2 also uses much of the integrated name-cache code from Syslogd2.
If you have needs or requests for DBD2 to perform some action or conversion that it does not currently perform, please notify me and I'll see if I can
accomodate your request. -- Ed Freesmeyer.
NOTE: Attempting to print copies of this web page may result in frustration due to the copious amount of ink that will be used in printing these black pages.
The color choice is more to prevent eye-strain than to facilitate printing.
I'll very likely provide some down-loadable reference files for printing purposes at a later date.
In DBD2, all output-locations (destinations) are referred to as 'databases' (though they may actually be output-files or a socket connection).
This is partly because DBD2 was origginally conceived to be used exclusively to write to databases, but mostly because databases are the most complex
output type and it helps to think about destinations in database terms -- and because so much of the terminology and concepts used are database-oriented.
dbcl is the client application provided with DBD2.
It is a command-line-driven application with no configuration file or installation requirements since it has no libraries to install and takes all
configuration from the command-line.
Run this program with no parameters to get usage instructions.
dbcl usage looks scary, but can be 'boiled down' to:
dbcl <hostname-or-address> <TCP-Port> template=string name1=value1 [name2=value2] ...
or
dbcl <linux-socket-path> template=string name1=value1 [name2=value2] ...
The dbcl client (when executed) will read its command-line parameters, then immdiately background itself before attempting to contact the DBD2 server in the background.
This allows shell-scripts to continue executing (even terminating) while the dbcl client continues to run in its attempt(s) to contact the DBD2 server.
There are two parameters for dbcl that are worth highlighting at this point. Both take a time-string as their only parameter.
The files.module sample file contains a shell script (at the end of the file) that uses dbcl to process multiple templates that cause DBD2 to print out multiple variable formats using different variable types for demonsstration. The display will look something like this:
Var-Name Var1 Var2 var3 Raw [ubuntudesktop.localdomain] [host63] [192.168.2.50] PHostName [ubuntudesktop] [cachehost53] [ubuntudesktop] PHostDomain [localdomain] [localdomain] [localdomain] PFQDN [ubuntudesktop.localdomain] [cachehost53.localdomain] [ubuntudesktop.localdomain] PIPv4 [192.168.2.60] [192.168.2.53] [192.168.2.60] PIPv6 [fec0:2::a0] [fec0:2::93] [fec0:2::a0] Var-Name RelayHost ServerHost EventHost Raw [127.0.0.1] [ubuntudesktop.localdomain] [] PHostName [localhost] [ubuntudesktop] [] PHostDomain [localdomain] [localdomain] [] PFQDN [localhost.localdomain] [ubuntudesktop.localdomain] [] PIPv4 [127.0.0.1] [192.168.2.60] [] PIPv6 [::1] [fec0:2::a0] [] Raw Input: "ubuntudesktop.localdomain": [ubuntudesktop] [localdomain] [ubuntudesktop.localdomain] [192.168.2.60] [fec0:2::a0] Var-Name Var1 Var2 var3 Raw [1680852276] [Mar 31 15:33:22 2021] [2023-05-14 18:30:40-06:30] TimeUTCInt [1680852276] [1617222802] [1684112440] TimeUTCDb [20230407072436] [20210331203322] [20230515010040] TimeUTCRfc [2023-04-07T07:24:36Z] [2021-03-31T20:33:22Z] [2023-05-15T01:00:40Z] TimeUTCSyslog [Apr 7 07:24:36] [Mar 31 20:33:22] [May 15 01:00:40] TimeUTCString1000 [Fri, Apr 7 07:24:36 2023 (am)] [Wed, Mar 31 20:33:22 2021 (pm)] [Mon, May 15 01:00:40 2023 (am)] TimeLocalInt [1680834276] [1617204802] [1684094440] TimeLocalDb [20230407022436] [20210331153322] [20230514200040] TimeLocalRfc [2023-04-07T02:24:36-05:00] [2021-03-31T15:33:22-05:00] [2023-05-14T20:00:40-05:00] TimeLocalSyslog [Apr 7 02:24:36] [Mar 31 15:33:22] [May 14 20:00:40] TimeLocalString1001 [2023-Apr-07 02:24:36 (CDT / dst:1)] [2021-Mar-31 15:33:22 (CDT / dst:1)] [2023-May-14 20:00:40 (CDT / dst:1)] Var-Name ServerHost EventHost RelayHost Raw [1680852278] [1680852278] [] TimeUTCInt [1680852278] [1680852278] [] TimeUTCDb [20230407072438] [20230407072438] [] TimeUTCRfc [2023-04-07T07:24:38Z] [2023-04-07T07:24:38Z] [] TimeUTCSyslog [Apr 7 07:24:38] [Apr 7 07:24:38] [] TimeUTCString1000 [] [] [] TimeLocalInt [1680834278] [1680834278] [] TimeLocalDb [20230407022438] [20230407022438] [] TimeLocalRfc [2023-04-07T02:24:38-05:00] [2023-04-07T02:24:38-05:00] [] TimeLocalSyslog [Apr 7 02:24:38] [Apr 7 02:24:38] [] Var-Name User1 User2 Group1 Group2 Raw [ed] [librenms] [1000] [998] String [ed] [librenms] [ed] [librenms] Numeric [1000] [998] [1000] [998] UserName [ed] [librenms] Gecos [Ed Freesmeyer,,,] [] Raw User Input: "1000": [ed] [1000] [ed] [Ed Freesmeyer,,,] Raw Group Input: "1000": [ed] [1000]
There is nothing 'magical' (prorietary) about the dbcl client. It can be replaced by your own code if you desire.
The 'dbcl interface' protocol is nothing more than a new-line-terminated (printable text) string sent to the server over a streaming protocol (TCP or Streaming Linux socket) in the following format:
[<event-time in system-clock format> + ',' + ] <comma-separated list of 'name=value' pairs>
(one of the 'name=value' pairs must be "'template=' + string").
For example, one of the dbcl commands used to produce the above display would have sent a string like this one to DBD2:
1680852278, template=z1100z1101z1102z1103, user1=ed, user2=librenms, group1=1000, group2=998
As has been said elsewhere, DBD2 is flexible with whitespace around equal-signs and commas, but this protocol is not meant for generic user visibility, so if you wish to bypass the dbcl client and write a direct interface, please stick to the format above as closely as possible to minimize errors and maximize your chance of success.