Nagios / Icinga Configuration Files

Nagios/Icinga load their configurations from a series of .cfg files.  This article describes (and provides basic examples of) the different files that control the Nagios/Icinga daemon and the objects it checks.

Main Configuration File

The Main Configuration File (/etc/nagios3/nagios.cfg or /etc/icinga/icinga.cfg) defines global environment settings for the Nagios / Icinga Service.  There are only a few items a beginning Nagios / Icinga administrator needs to alter in this file:

• Configuration file location paths
• Enabling External Commands
• Enabling NDOUtils / IDOUtils Database Integration

Advanced administrators may choose to set a wide array of performance and environment variables, but that is beyond the scope of this article.

Object Configuration Files

Object Configuration Files define all of the objects, services, events and actions Nagios / Icinga uses to monitor a network.  There are 19 commonly-used definitions within the configuration files:

• Services and Service Groups
• Hosts and Host Groups
• Host and Service Templates
• Notification Escalations
• Host and Service Notification Escalations
• Extended Host and Service Information
• Contacts and Contact Groups
• Commands
• Time Periods
• Host, Service, Notification and Execution Dependencies

These 19 commonly-used definitions are explained in the Nagios Documentation, available as a downloadable .pdf file.  Icinga Documentation is available online or as downloads.

Debian Wheezy Default Installation Files

At installation, Debian Wheezy provides the following Nagios configuration files and definition statements:

1) contacts_nagios2.cfg (Contacts and Contact Groups)

define contact {

define contactgroup {

2) extinfo_nagios2.cfg (Extended Host Information)

define hostextinfo {

3) generic-host_nagios2.cfg (Host Templates)

define host {

…

register     0

4) generic-service_nagios2.cfg (Service Templates)

define service {

…

register     0

5) hostgroups_nagios2.cfg (Host Groups)

define hostgroup {

6) localhost_nagios2.cfg (Hosts and Services)

define host {

7) services_nagios2.cfg (Services)

define service {

8) timeperiods_nagios2.cfg (Time Periods)

define timeperiod {

Notice how the above files organize commands.  For the most part, each type of definition has its own file.  However, there are related definitions placed together, and some of the services are split between files.

• all Contact and Contact Group information are placed in the contacts_nagios2.cfg file,
• all Host and host-specific Services information are placed in<hostname>_nagios2.cfg file and
• all services assigned to multiple hosts in the services_nagios2.cfg file.

Thus, the installed object definition files specify 9 of the 19 commonly-used configurations in 8 files.  The contacts_nagios2.cfg file specifies Contacts and Contact Groups.  Services are defined in two files:  localhost_nagios2.cfg and services_nagios2.cfg.  There is a subtle, but important, distinction.  Those defined in the localhost file are specific to that host; those specified in the services file may be applied to multiple hosts using Host Groups and Service Groups.

Following the example above, one would continue defining 

• all Contact and Contact Group information in a single file (e.g. contacts.cfg)
• all Services used by multiple hosts in a single file (e.g. services.cfg) and
• hosts and host-specific services in separate files for each host (e.g. <hostname>.cfg)

This is a logical solution and easy to troubleshoot.  However,it is not necessarily the most efficient way to describe a network.  With experience, it becomes more manageable to use 19 different files, each with its own specific definitions corresponding to the first bullet list in this section.  More on the in Advanced Configuration.  Nagios / Icinga are designed for flexible configuration.  At service start up, they read all files with a .cfg extension – regardless of name – within the specified paths and use all properly-formatted “define” commands.  This allows the administrator to define any sets of definitions that sensibly define the network.

The video below demonstrates the flexibility and portability of Nagios / Icinga configuration files.  A fully-configured Icinga server monitoring 11 hosts for 287 services uses 14 configuration files in two directories to define the network.  These files are grouped by the type of defintions they contain (e.g. Hosts, Host Groups, etc.)  A Nagios server's Main Configuration file is modified to only search the /etc/nagios3/conf.d directory for definition files.  The Icinga files are all copied to the Nagios server, which is then restarted.  After five minutes, the two servers return identical information about the network.

Manually-Written Configuration Files

Writing Nagios / Icinga configuration files requires trial and error experience.  Learning how to correctly – and efficiently – define a network is best learned in a test environment.  Hence these articles use virtual machines installed on a laptop for demonstration purposes.

Network definitions using the sets of logical definitions installed by default works well.  For instance, each host on the network will have its name and host-specific services defined in a file, resulting in a<hostname>.cfg file for each node; Services and Service Groups may be defined in a single services.cfg file; Contacts and Contact Groups may be defined within a single contacts.cfg file, etc.  The administrator must, however, adhere to a uniform and logically-understandable format or the configuration quickly becomes unmanageable.

Below is a brief set of example commands using the configuration file format in which each type of definition is included in a separate file.  These commands ARE NOT optimized, with some duplication of definitions between hosts/services and host templates/service templates.  However, definition file optimizations are another topic.

Services

define service {

                service_description       Hardware - CPU Processes - Total

                notification_interval       0

                check_command           check_procs!250!400

                check_period                 24x7

                notification_period        24x7

                hostgroup_name           linux_servers,windows_servers

                servicegroups                linux_servers_servicegroup,windows_servers_servicegroup

                use                                   generic-service

                contact_groups              admins

}

define service {

                service_description       Hardware - CPU Processes - Current Load

                notification_interval       0

                check_command           check_load!5.0!4.0!3.0!10.0!6.0!4.0

                check_period                 24x7

                notification_period        24x7

                hostgroup_name           linux_servers,windows_servers

                servicegroups                linux_servers_servicegroup,windows_servers_servicegroup

                use                                   generic-service

                contact_groups              admins

}

Service Groups

define servicegroup {

                servicegroup_name      dns_servers_servicegroup

                alias                                 Servers - DNS

}

define servicegroup {

                servicegroup_name      squid_servers_servicegroup

                alias                                 Server - Squid Proxy

}

Hosts 

define host {

                host_name                     pit-monitor.pittsburgh.mydomain.com

                alias                                pit-monitor.pittsburgh.mydomain.com

                address                          10.202.0.50

                icon_image_alt             Linux

                icon_image                   base/linux40.gif

                statusmap_image        base/linux40.gd2

                check_command         check-host-alive

                check_period               24x7

                notification_period      24x7

                use                                generic-host

                contact_groups           admins

}

define host {

                host_name                     pit-router.pittsburgh.mydomain.com

                alias                                 pit-router.pittsburgh.mydomain.com

                address                           10.203.0.254

                icon_image_alt              Linux

                icon_image                     base/linux40.gif

                statusmap_image          base/linux40.gd2

                check_command           check-host-alive

                check_period                 24x7

                notification_period        24x7

                parents                           pit-monitor.pittsburgh.mydomain.com

                use                                  generic-host

                contact_groups             admins

}

Host Groups

define hostgroup {

                hostgroup_name           linux_servers

                alias                                Linux Servers

                members                        pit-monitor.pittsburgh.mydomain.com,pit-router.pittsburgh.mydomain.com,pit-san.pittsburgh.mydomain.com,hbg-router.harrisburg.mydomain.com,hbg-backup.harrisburg.mydomain.com,phl-router.philadelphia.mydomain.com,phl-san.philadelphia.mydomain.com,phl-monitor.philadelphia.mydomain.com,laptop.coudersport.mydomain.com

}

define hostgroup {

                hostgroup_name          debian_servers

                alias                               Debian Servers

                members                       pit-monitor.pittsburgh.mydomain.com,pit-router.pittsburgh.mydomain.com,pit-san.pittsburgh.mydomain.com,hbg-router.harrisburg.mydomain.com,hbg-backup.harrisburg.mydomain.com,phl-router.philadelphia.mydomain.com,phl-san.philadelphia.mydomain.com,phl-monitor.philadelphia.mydomain.com

}

Host Templates

define host {

                name                                       Default_collector_server

                register                                    0

                active_checks_enabled       1

                passive_checks_enabled    0

                notifications_enabled           1

                check_freshness                   0

                freshness_threshold             86400

}

define host {

                name                                       Default_monitor_server

                register                                    0

                active_checks_enabled       0

                passive_checks_enabled    1

                notifications_enabled           1

                check_freshness                   0

                freshness_threshold             86400

}

Service Templates

define service {

                name                                  generic-service

                register                                   0

                max_check_attempts           4

                check_interval                       5

                retry_interval                          1

                notification_interval              0

                notification_options              w,u,c,r

                active_checks_enabled      1

                passive_checks_enabled   1

                notifications_enabled           1

                check_freshness                   0

                check_period                         24x7

                notification_period                24x7

                contact_groups                     admins

}

Contacts 

define contact {

                contact_name                           Stephen_Fritz

                alias                                            Stephen Fritz

                host_notification_options        u,d,r

                service_notification_options   w,u,c,r

                email                                           fritzs@mydomain.com

                host_notification_period          24x7

                service_notification_period     24x7

                host_notification_commands        notify-host-by-email

                service_notification_commands   notify-service-by-email

}

Contact Groups

define contactgroup {

                contactgroup_name      admins

                alias                                 Systems Administrators

                members                         Stephen_Fritz

}

Commands

define command {

                command_name                      check_apt

                command_line                          /usr/lib/nagios/plugins/check_apt

}

define command {

                command_name                      check_apt_distupgrade

                command_line                          /usr/lib/nagios/plugins/check_apt -d

}

Time Periods

define timeperiod {

                timeperiod_name          24x7

                alias                                 24 Hours A Day, 7 Days A Week

                sunday                            00:00-24:00

                monday                           00:00-24:00

                tuesday                           00:00-24:00

                wednesday                     00:00-24:00

                thursday                          00:00-24:00

                friday                                00:00-24:00

                saturday                          00:00-24:00

}

define timeperiod {

                timeperiod_name          workhours

                alias                                Standard Work Hours

                monday                           09:00-17:00

                tuesday                           09:00-17:00

                wednesday                    09:00-17:00

                thursday                          09:00-17:00

                friday                               09:00-17:00

}