Index
Introduction
Out with the old...
Getting started
Compiling with MySQL support
Compiling with PostgreSQL support
Configuration Directives
Introduction
This will explain how to optionally compile both the core program and the CGIs so that they natively support storage of various types of data in one or more databases. Currently only MySQL and PostgreSQL databases are supported, although more may be supported in the future.
Out With The Old...
Okay, before we go ahead and get into the details of the database integration stuff, you need to understand something. The default method for storing status data, comments, etc. in Nagios is (and probably will continue to be) in plain old text files. The standard files used by the default external data routines include the status file, downtime file, comment file, and the state_retention file. With the default install, extended host and service information is not stored in its own file, but in extended host and service information definitions in the CGI configuration file.
Assuming you plan on using a database to store some or all external data, a few things are obviously going to change. Data will no longer be stored in text files, but rather in one or more databases. Since I don't feel like rewriting a lot of documentation, you're going to have to make a mental transition. You'll need to realize that status information is no longer stored in the status log, but rather in a few tables in a database somewhere. Same thing applies for other types of external data (downtime data, comments, retention information, and extended host information).
Getting Started
First off, I assume you've got a MySQL or PostgreSQL database server up and running on your network somewhere and you've got the appropriate client libraries installed on the same machine where you're going to compile and run Nagios. I'm also assumimg you're familiar with creating databases and tables and managing accounts and security in the particular database system(s) you're going to use. If you're not, go out and learn before you attempt to compile Nagios with database support.
Very Important Note: Once you (re)run the configure script to add support for database storage (as will be described below), make sure you recompile both the core program and all the CGIs (using the make all command)!!
Compiling With MySQL Support
In order to support storage of various types of data in MySQL, you're going to have to supply one or more options to the configure script.
You have a few options here. First, you need to decide what data you want to keep in MySQL and what (if any) you want to leave in the older format (text files). Use the table below to determine what options you'll need to supply to the configure script once you determine your needs. Note: MySQL support for storage of object data (service, host, and command definitions, etc) is not yet supported.
| Data Type | Configure Script Option | Comments |
|---|---|---|
| All types | --with-mysql-xdata | This will compile in MySQL support for all types of external data (downtime data, comment data, status data, retention data, and extended data). Support for object data (service and host definitions, etc.) is as of yet non-existent. |
| Comment data | --with-mysql-downtime | This will compile in MySQL support for downtime data (it will replace the standard downtime file) |
| Comment data | --with-mysql-comments | This will compile in MySQL support for comment data (it will replace the standard comment file) |
| Status data | --with-mysql-status | This will compile in MySQL support for status data (it will replace the standard status log) |
| Retention data | --with-mysql-retention | This will compile in MySQL support for retention data (it will replace the standard state_retention file) |
| Extended data | --with-mysql-extinfo | This will compile in MySQL support for extended data (it will replace the standard hostextinfo[] and serviceextinfo[] definitions in the CGI config file) |
Compiling With PostgreSQL Support
In order to support storage of various types of data in PostgreSQL, you're going to have to supply one or more options to the configure script.
You have a few options here. First, you need to decide what data you want to keep in PostgreSQL and what (if any) you want to leave in the older format (text files) or possibly in MySQL. Use the table below to determine what options you'll need to supply to the configure script once you determine your needs. Note: PostgreSQL support for storage of object data (service, host, and command definitions, etc) is not yet supported.
| Data Type | Configure Script Option | Comments |
|---|---|---|
| All types | --with-pgsql-xdata | This will compile in PostgreSQL support for all types of external data (downtime data, comment data, status data, retention data, and extended data). Support for object data (service and host definitions, etc.) is as of yet non-existent. |
| Comment data | --with-pgsql-downtime | This will compile in PostgreSQL support for downtime data (it will replace the standard downtime file) |
| Comment data | --with-pgsql-comments | This will compile in PostgreSQL support for comment data (it will replace the standard comment file) |
| Status data | --with-pgsql-status | This will compile in PostgreSQL support for status data (it will replace the standard status log) |
| Retention data | --with-pgsql-retention | This will compile in PostgreSQL support for retention data (it will replace the standard state_retention file) |
| Extended data | --with-pgsql-extinfo | This will compile in PostgreSQL support for extended data (it will replace the standard hostextinfo[] and serviceextinfo[] definitions in the CGI config file) |
Configuration Directives
Once you decide what types of external data you want to store in one or more databases, you'll have to add some configuration directives to the resource file and/or the CGI config file. Here we go...
Configuration Directives For Downtime Data: (--with-mysql-downtime or --with-pgsql-downtime options):
In the CGI config file, you need to add the following directives (the downtime_file directive in the main configuration file is no longer used)...
xdddb_host=database_host
xdddb_port=database_port
xdddb_username=database_user
xdddb_password=database_password
xdddb_database=database_name
These are fairly self-explanatory. They are used by the CGIs to identify the address of your database server (and the port it is running on), the name of the database in which the downtime entries should be stored, and the username/password that should be used when connecting to the databse server. Nagios will assume that two tables (as defined here) exist in this database for storage of downtime data. Note: The CGIs only need read access to the downtime data, so this user should only have SELECT privileges on the comment tables.
In a resource file, you need to add the following directives...
xdddb_host=database_host
xdddb_port=database_port
xdddb_username=database_user
xdddb_password=database_password
xdddb_database=database_name
xdddb_optimize_data=[0/1]
There directives are identical to the ones you added to the CGI config file, except these are used by the Nagios process. The database user you specify here needs to have SELECT, INSERT, UPDATE, and DELETE privileges on the downtime tables. The CGIs do not attempt to read the contents of any resource files, so you can set restrictive permissions on them and make sure that no one other than the Nagios process can read them. The xdddb_optimize_data option will force Nagios to optimize data in the downtime tables when it starts/restarts. If you're using PostgreSQL DB support for downtime data, this means that a VACUUM is run on the downtime tables.
Configuration Directives For Comment Data: (--with-mysql-comments or --with-pgsql-comments options):
In the CGI config file, you need to add the following directives (the comment_file directive in the main configuration file is no longer used)...
xcddb_host=database_host
xcddb_port=database_port
xcddb_username=database_user
xcddb_password=database_password
xcddb_database=database_name
These are fairly self-explanatory. They are used by the CGIs to identify the address of your database server (and the port it is running on), the name of the database in which the comments should be stored, and the username/password that should be used when connecting to the databse server. Nagios will assume that two tables (as defined here) exist in this database for storage of comment data. Note: The CGIs only need read access to the comments, so this user should only have SELECT privileges on the comment tables.
In a resource file, you need to add the following directives...
xcddb_host=database_host
xcddb_port=database_port
xcddb_username=database_user
xcddb_password=database_password
xcddb_database=database_name
xcddb_optimize_data=[0/1]
There directives are identical to the ones you added to the CGI config file, except these are used by the Nagios process. The database user you specify here needs to have SELECT, INSERT, UPDATE, and DELETE privileges on the comment tables. The CGIs do not attempt to read the contents of any resource files, so you can set restrictive permissions on them and make sure that no one other than the Nagios process can read them. The xcddb_optimize_data option will force Nagios to optimize data in the comment tables when it starts/restarts. If you're using PostgreSQL DB support for comments, this means that a VACUUM is run on the comment data tables.
Configuration Directives For Status Data: (--with-mysql-status or --with-pgsql-status options):
In the CGI config file, you need to add the following directives (the status_file directive in the main configuration file is no longer used)...
xsddb_host=database_host
xsddb_port=database_port
xsddb_username=database_user
xsddb_password=database_password
xsddb_database=database_name
These are fairly self-explanatory. They are used by the CGIs to identify the address of your database server (and the port it is running on), the name of the database in which the status data should be stored, and the username/password that should be used when connecting to the database. Nagios will assume that three tables (as defined here) exist in this database for storage of status data. Note: The CGIs only need read access to the status data, so the database user you specify here should only have SELECT privileges on the status tables.
In a resource file, you need to add the following directives...
xsddb_host=database_host
xsddb_port=database_port
xsddb_username=database_user
xsddb_password=database_password
xsddb_database=database_name
xsddb_optimize_data=[0/1]
xsddb_optimize_interval=seconds
These directives are used by the Nagios process instead of the CGIs. The only difference between these directives and those found in the CGI config file is the fact that the database user you specify here needs to have SELECT, INSERT, UPDATE, and DELETE privileges on the status tables. The CGIs do not attempt to read the contents of any resource files, so you can set restrictive permissions on them and make sure that no one other than the Nagios process can read them. The xsddb_optimize_data option will force Nagios to periodically optimize data in the status tables. The frequency of optimization is determined by the number of seconds specified by the xsddb_optimize_interval option. If you're using PostgreSQL DB support for status data, this means that a VACUUM is run on the status data tables.
Configuration Directives For Retention Data: (--with-mysql-retention or --with-pgsql-retention options):
In a resource file, you need to add the following directives (the state_retention_file directive in the main config file is no longer used)...
xrddb_host=database_host
xrddb_port=database_port
xrddb_username=database_user
xrddb_password=database_password
xrddb_database=database_name
xrddb_optimize_data=[0/1]
These are fairly self-explanatory. They are used by the Nagios process to identify the address of your database server (and the port it is running on), the name of the database in which the retention data should be stored, and the username/password that should be used when connecting to the database. Nagios will assume that three tables (as defined here) exist in this database for storage of retention data. The user you specify here needs to have SELECT, INSERT, UPDATE, and DELETE privileges on the retention tables. The CGIs do not attempt to read the contents of any resource files, so you can set restrictive permissions on them and make sure that no one other than the Nagios process can read them. The xrddb_optimize_data option will force Nagios to optimize data in the retention tables when it starts/restarts. If you're using PostgreSQL DB support for retention data, this means that a VACUUM is run on the retention data tables.
Configuration Directives For Extended Data: (--with-mysql-extinfo or --with-pgsql-extinfo options):
In the CGI config file, you need to add the following directives (the hostextino[] and serviceextinfo[] directives in the CGI config file are no longer used)...
xeddb_host=database_host
xeddb_port=database_port
xeddb_username=database_user
xeddb_password=database_password
xeddb_database=database_name
These are fairly self-explanatory. They are used by the CGIs to identify the address of your database server (and the port it is running on), the name of the database in which the extended data is stored, and the username/password that should be used when connecting to the database. Nagios will assume that two tables (as defined here) exists in this database for storage of extended data. The user you specify here should only have SELECT privileges on the extended info tables.
Table Definitions
In order to read from or write to a database, you first have to create it and setup some tables to hold your data. Note: If you are storing more than one type of external data in databases, you could create separate databases for each type of data (comments, status info, etc.) You could also keep everything in a single database (different data is kept in different tables). In your database(s) you're going to have to setup the appropriate table(s) so Nagios can actually read/write data.
Important: Scripts for creating tables for all types of external data for both MySQL and PostgreSQL databases can be found in the contrib/database/ directory of the distribution.
Downtime Data Tables:
There are two tables (named hostdowntime and servicedowntime) you need to create in order to store downtime entries in a database. One of the tables is used to store host downtime and the other for service downtime. The CGIs only need SELECT rights on these tables, while the main Nagios process needs SELECT, INSERT, UPDATE, and DELETE privileges.
Comment Data Tables:
There are two tables (named hostcomments and servicecomments) you need to create in order to store comments in a database. One of the tables is used to store host comments and the other for service comments. The CGIs only need SELECT rights on these tables, while the main Nagios process needs SELECT, INSERT, UPDATE, and DELETE privileges.
Status Data Tables:
There are three tables (named programstatus, hoststatus, and servicestatus) you need to create in order to store status data in a database. One of the tables is used to store program status data, one for host status data, and another for service status data. The CGIs only need SELECT rights on these tables, while the main process needs SELECT, INSERT, UPDATE, and DELETE privileges.
Retention Data Tables:
There are three tables (named programretention, hostretention, and serviceretention) you need to create in order to store retention data in a database. One is used to store program data, one for host data, and another for service data. The main process needs SELECT, INSERT, UPDATE, and DELETE privileges on these tables. The CGIs do not access these tables at all.
Extended Data Tables:
There are two tables (named hostextinfo and serviceextinfo) you need to create in order to store extended data in a database. One table is used to store extended host information and the other for extended service information (used by the CGIs). The CGIs need SELECT privileges on these tables. The main Nagios process does not access these tables at all.