Icinga Documentation

1. Icinga Hierarchy a. Purposes i. Plugins ii. Commands 1. Macros iii. Hosts 1. Hosts Templates iv. Services 1. Service Templates b. Interactions 2. Configuration a. Creating a new command/host/service i. Adding a new command ii. Adding a new host 1. Without a host template 2. With a host template iii. Adding a new service 1. Without a service template 2. With a service template b. Adding existing host to existing service 3. Icinga Configurator a. Overview b. Executing

1.

Icinga Hierarchy Like Nagios, Icinga is built on a hierarchy.

Services

Service Templates Hosts

Commands
Host Templates

Plugins

a. Purposes i. Plugins On the bottom of this hierarchy are plugins. These can be written in any language and can always be executed in commandline. Most plugins begin with check ie. check_ping Plugin directory: /usr/lib/nagios/plugins

ii.

Commands Next we have commands. The commands layer is important because it allows us to specify which arguments we want our service to use. For example the check_ping plugin has over thirty methods that can be used. In the commands configuration we might want to limit it to three. Here is how we define a command.

Notice that the command only has two fields, command_name and command_line. 1. Macros A macro is simply a variable used to hold a value we use these in the command_line field for our commands. A macro is always started and ended with $ and is always in caps There are three main macros I used. $USER1$ = points to the plugins directory located in /usr/lib/nagios/plugins $HOSTADDRESS$ = The IP address of the host. It pulls this from our host configuration file. $ARGS1$ -ARGSN = Arguments that are specified later in the services. These can hold integer, strings, or anything you put in them. They are simply placeholders. Commands Configuration file: /etc/icinga/checkcommands.cfg

iii.

Hosts Hosts are the physical machines on the network. These configuration files are used to: assign an IP to a host_name, check to see if the host is still up, determine check times, attempts, and frequencies, and finally assign contact information in case of failure. Host Configuration file: /etc/icinga/objects/checkHosts.cfg

1.

Host Templates Often hosts share a lot of the same configuration settings in this case we can create a host template from which several hosts can inherit information from. These are completely optional! Templates can hold ANY information that a regular host can hold. To use a template for a particular host we use the use field in our host configuration file.
*Host templates can also inherit from other templates. As a matter of fact inheritance is infinite, but you should avoid this to prevent mindfucking yourself.

*templates will override fields!

A host template is defined the exact same way a host is:

Host Template Configuration file: /etc/icinga/objects/checkHostTemplates.cfg

iv.

Services Services exist at the very top of the hierarchy. They need three things to operate: a host(s), a command and notifications information (interval and period). When creating a brand new service it is very important that you have a created your appropriate host and command first!

The check_command in this example has three arguments that were defined in our /etc/icinga/checkcommands.cfg configuration. We separate our arguments in services with ! so you are essentially filling $ARG1$ which is obviously a port number with the value 3389 (RDP) $ARG2$ in this case is our warning threshold which and $ARG3$ holds our critical threshold. Service Configuration file: /etc/icinga/objects/checkServices.cfg

1. Service Templates Like host templates service templates hold information that may apply to several services. They are defined the exact same way and the same rules apply to service templates as host templates. Like a host template a service template can be called from the service using the use verb. Again, like host templates these are completely optional!

Service Template Configuration file: /etc/icinga/objects/checkServiceTemplates.cfg

b. Interactions Upon startup Icinga will scan the main configuration file located in /etc/icinga/icinga.cfg

If all goes well you will see the above message. Upon starting the daemon sudo service icinga start, it will check the main configuration file for errors as well as any of the child configuration files, and dozens of files we will never edit.

2.

Configuration c. Creating a new command/host/service i. Creating a new command. 1. SSH to icinga (username: icinga, password tech) 2. Become root sudo i or sudo su 3. Navigate to the plugins directory cd /usr/lib/nagios/plugins 4. List all the plugins ls a 5. Make sure that the plugin that you want to turn into a command is executable chmod +x check_name_of_plugin 6. Play with the plugin. To see what methods are available ./check_name_of_plugin help

Once you get it to compile with the the parameters you want move on to the next step!

7. Navigate to the icinga directory cd /etc/icinga 8. Backup checkcommands.cfg cp checkcommands.cfg objects/BACKUP/checkcommands.cfg.backup 9. Edit checkcommands.cfg nano checkcommands.cfg 10. Use the examples already in the configuration file to shape your addition. 11. For the command_line field paste the command you successfully executed in. In the picture above we used ./check_icmp H cloudalpha. Replace the . with $USER$ and any argument with the appropriate $ARGN$ 12. The converted command_line should be $USER1$/check_icmp H $ARG1$ 13. Check for syntax errors, and write the file ctrl+o (in nano) 14. Restart the daemon service icinga restart
If you did everything right you will see this!

d. Adding a new host i. Without a host template 1. Repeat steps one and two from the creating new commands section 2. Navigate to icinga directory cd /etc/icinga 3. Backup checkHosts.cfg cp checkHosts.cfg BACKUP/checkHosts.cfg.backup 4. Copy the AMAC_Express host definition 5. Paste and adjust fields appropriately a. For the host address make sure you use the equivalent IP not the host-name. b. The host address field is where the macro $HOSTADDRESS$ gets its information. 6. Check for syntax errors, and write the file ctrl+o (in nano) 7. Restart the daemon service icinga restart ii. With a host template 1. Repeat step one and two from the Adding a new host without a host template section 2. Backup checkHostsTemplates.cfg cp checkHostTemplates.cfg BACKUP/checkHostTemplate.cfg.backup 3. Edit checkHostTemplates.cfg 4. Use the generic-host template as a guideline a. Copy b. Paste it to the place of your choosing in the configuration file. 5. Tailor the template to your needs. a. The goal should be to make it generic enough that it applies to the maximum amount of hosts. 6. Check for syntax errors, and write the file ctrl+o (in nano) 7. Follow steps 3-7 under add a new host without a template e. Adding a new Service i. Without a Service template 1. Repeat steps one and two from the creating new commands section 2. Navigate to icinga directory cd /etc/icinga

3. Backup checkServices.cfg cp checkServices.cfg BACKUP/checkServices.cfg.backup 4. Copy the amac-server2 service definition 5. Paste and adjust fields appropriately a. For help with arguments see section 1-a-iv (Services) 6. Check for syntax errors, and write the file ctrl+o (in nano) 7. Restart the daemon service icinga restart ii. With a service template 1. Repeat step one and two from the Adding a new service without a service template section 2. Backup checkServiceTemplates.cfg cp checkServiceTemplates.cfg BACKUP/checkServiceTemplate.cfg.backup 3. Edit checkServiceTemplates.cfg 4. Use the generic-host template as a guideline a. Copy b. Paste it to the place of your choosing in the configuration file. 5. Tailor the template to your needs. a. The goal should be to make it generic enough that it applies to the maximum amount of services. 6. Check for syntax errors, and write the file ctrl+o (in nano) iii. Follow steps 3-7 under add a new Service without a template 3. Icinga Configurator:

a. Overview: Icinga Configurator is a program that I wrote that allows the easy adding of a command/host/service by navigating through a wizard instead of directly editing the configuration files. However, it also provides shortcuts to manually do this as well. The program includes the additional option of backing up an existing configuration (by date and time) and safely restarting the daemon. b. Icinga Configurator is located in the home directory of Icinga (/home/icinga). The program should be executed with root privileges in order to give it write access to the necessary configuration files. To execute this program you log into the Icinga server through ssh. To run simply type sudo ./IcingaConfigurator.py