What Is It?¶

Shinken is a system and network monitoring application. It supervises hosts and services from an IT and business point of view. Alerting or taking action on failures and recovery.

Shinken is a monitoring tool compatible with Nagios configuration, plugins and interfaces. It is written in Python, so it should work under all Python supported platforms.

Some of the many features of Shinken include:

• Web 2.0 Interface named WebUI that has innovative methods to visualize the state of your systems
• Web 2.0 Interface named SkonfUI, that links discovery and configuration management
• Livestatus networked API to provide realtime access to performance, status and configuration data * Interchangeable console or mobile interfaces
• Providing operational or business insight * Ability to map business processes to Hosts and services * Ability to associate a business impact metrics to any warning or outages of hosts and services used to deliver a business process * Ability to define network host hierarchy using “parent” hosts, allowing detection of and distinction between hosts that are down and those that are unreachable
• Monitoring Hosts and Services * Simple plugin design that allows users to easily develop their own service checks * Monitoring of network services (“SMTP”, “POP3”, “HTTP”, “NTP”, PING, etc.) * Monitoring of host resources (processor load, disk usage, etc.) * Hundreds of Nagios check scripts to choose from * High performance plugin modules integrated in the distributed daemons to easily extend the scope of the software * Parallelized service and host checks * Designed for highly available and load balanced monitoring * Acquire performance data from collectd via its network interface
• Define Triggers in the Shinken core to calculate new performance metrics or states based on performance or state data
• Contact notifications when service or host problems occur and get resolved (via email, SMS, pager, or user-defined method)
• Ability to define event handlers to be run during service or host events for proactive problem resolution
• Integrates with PNP4Nagios and Graphite time-series databases for storing data, querying or displaying data.
• Supports distributed retention modules, caches and databases to meet persistence and performance expectations

System Requirements¶

The requirement for running Shinken are the Python interpreter and a very short list of Python modules. You will also want to have TCP/IP configured, as the typical installation will download packages to install from the Internet and most service checks will be performed over the network.

Legacy Requirements¶

You are not required to use the original Nagios user interface CGIs included with Shinken. However, if you do decide to use them for migration purposes, you will need to have the following software installed...

• A web server (preferrably Apache)
• Thomas Boutell’s gd library version 1.6.3 or higher.

Licensing¶

Shinken is licensed under the terms of the GNU Affero General Public License as published by the Free Software Foundation. This gives you legal permission to copy, distribute and/or modify Shinken under certain conditions. Read the ‘LICENSE’ file in the Shinken distribution or read the online version of the license for more details.

Shinken is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.

The Shinken documentation is based on Nagios so is licensed under the terms of the GNU General Public License Version 2 as published by the Free Software Foundation. This gives you legal permission to copy, distribute and/or modify Shinken under certain conditions. Read the ‘LICENSE’ file in the Shinken distribution or read the online version of the license for more details.

Shinken is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgements¶

A long list of people have contributed to Shinken. The THANKS file included as part of Shinken and the project page at http://www.shinken-monitoring.org provide more details.

Downloading The Latest Version¶

You can check for new versions of Shinken at http://www.shinken-monitoring.org.

Change Log¶

The Changelog file is included in the source root directory of the source code distribution.

Summary¶

• Shinken is a true distributed applications which splits the different roles into separate daemons
• Shinken permits the use of modules to extend and enrich the various Shinken daemons
• Shinken is 100% python, from its API, frontend, back-end, discovery engine and high performance poller modules
• Scalability * Shinken has a powerful scheduler for supervising tens of thousands of devices v1.2 * Shinken can supervise multiple independent environments/customers * Shinken uses MongoDB to provide a distributed and highly scalable back-end for storing historical event data (experimental)
• Graphical and statistical analysis * Shinken provides integration with the modern time series database, Graphite * Shinken provides triggers against performance or event data in the core and in external checks (experimental) v1.2
• Correlation * Shinken differentiates the business impact of a critical alert on a toaster versus the web store * Shinken supports efficient correlation between parent-child relationship and business process rules

Notable items for DevOps admins¶

• Use Shinken and Graphite seamlessly in the Shinken WebUI. v1.2
• Export data from Shinken to Graphite and manipulate the data point names with PRE, POST, and SOURCE variables
• Buffered output to Graphite.
• Multiple Graphite destination servers.
• Use check_graphite to poll graphite and generate alerts.
• Use wildcards in checks against Graphite.
• Auto-detection, logging and semi-automatic registration of new passive checks. Planned for v1.4
• Mix and match frontends(Multisite, Nagvis), plugins, alerting(Pagerduty), analysis (Splunk, Logstash, Elastic Search, Kibana)

Notable items for Nagios admins¶

• Modern, Scalable, HA and distributed out of the box.
• Business rules, business impacts levels integrated in the core.
• The code is approachable for sys admins to improve and customize the core and manage additions using modules.
• Supervision packs(templates+commands+etc) and community
• For a full comparison: Shinken versus Nagios page.
• Can you say Graphite integration..

Shinken is the modern Nagios, re-implemented in Python, end of story.

Notable items for Zabbix admins¶

• A powerful and efficient dependency model that does event suppression. Not as flexible as the great Zabbix calculated items, but suffers from much less false positives, which is the whole point, especially at 3am.
• Uses the Graphite time-series database, which is hands-down one of the most modern, easy to use, fast, powerful and flexible time-series databases. None of the slooowness associated with scaling a SQL based storage for time-series.
• The code is approachable for sys admins to improve and customize the core and using modules.
• The new SNMP poller is more intelligent and efficient in its collection against remote devices. Zabbix collects each metric as it is scheduled, so IN/OUT stats of the same interface could be collected at two different times, errr, say what!

Notable items for Zenoss admins¶

• A working dependency model that does good and efficient event suppression and correlation.
• 100% open-source...
• Can you say Graphite integration, MongoDB, distributed architecture and seamless HA.

What we want and how we want it¶

We are here to create an open source monitoring solution that is:

• easy to install;
• easy to use for new users;
• useful for sysadmins and business types;
• built for scalability;
• incorporates high availability;
• multi-platform (and not just Unix ones);
• utf8 compliant;
• nearly fully compatible with Nagios configuration;
• fully compatible with its plugins and interfaces;
• fast enough
• centralized configuration that should be as easy as possible for the admin to manage;
• independent from any huge monitoring solution;
• fun to code :)

More precisely:

• The 2 first points are to make the system accessible to more people by automating and pre-building the typical monitoring environments so that users can focus on customizing, not just getting the basics working.
• Shinken provides a business monitoring service, not just an IT focused service. This means helping users to differentiate between real business impacting outages and minor IT related failures.
• The next two are for the global architecture. We should be able to scale the load within minutes without losing the high availability feature. We believe this has been successfully implemented. :)
• Multi platform is also important. If we only focused on GNU/Linux, a large user segment would be left out (Windows!). Of course, some features inherited from Nagios are Unix-only like named pipes, but we should promote other ways for users to bypass this (like commands sent to livestatus or in a web based API for example). Such “os limited” points must be limited to modules.

This is what we want to have (and already have for the most part).

What we do not want¶

At the beginning of the project, we used to say that what we didn’t want was our own webui. This became a requirement. Why? Because none of the current UIs truly provided the right way to prioritize and display business oriented information to the end users. Features like root problem analysis or business impact. After trying to adapt the external UIs, we had to roll our own. So we did. :)

So there is nothing we do not want, if in the end it helps Shinken’s users.

Feature selection¶

The Shinken Ideascale is a key input in the feature selection process, everyone can propose and vote for his favorite feature. Features are now managed based on expected user value. Features that users desire the most and which fit the project vision will be prioritized. The feature vote should be promoted to all users. The more users vote, the more we are sure to give them the most value for their monitoring system.

Release cycle¶

• “value first priority”
• Major changes are handled in github forks by each developer
• Very open to user submitted patches
• Comprehensive automated QA to enable a fast release cycle without sacrificing stability
• Tagging experimental unfinished features in the documentation
• Release soon and release often mentality

Guides¶

Installation guides are currently available for the following OSs :

• 10 Minute installation Guide for GNU/Linux and Windows
• Shinken installation requirements
• Shinken 1.2 installation requirements
• Shinken installation script
• GNU/Linux Quickstart
• Windows Quickstart
• Nokia N900
• Shinken/Thruk/PNP4Nagios on Red Hat

Post-Installation Modifications¶

Once you get Shinken installed and running properly, you’ll no doubt want to start monitoring more than just your local machine. Check out the following docs for how to go about monitoring other things:

• Monitoring Windows machines
• Monitoring GNU/Linux or other Unix machines
• Monitoring Netware servers
• Monitoring routers/switches
• Monitoring network printers
• Monitoring publicly available services (“HTTP”, “FTP”, “SSH”, etc.)

Also, you can check the next documentations:

• How to monitor

Upgrading From Previous Shinken Releases¶

See the update page for that. Basically it’s only about backuping and installing from a later git version.

Upgrading From Nagios 3.x¶

Just install Shinken and start the arbiter with your Nagios configuration. That’s all.

Introduction¶

Publicly available services that are provided by Windows machines (“HTTP”, “FTP”, “POP3”, etc.) can be monitored easily by following the documentation on Monitoring publicly available services (HTTP, FTP, SSH, etc.).

These instructions assume that you’ve installed Shinken according to the quickstart guide. The sample configuration entries below reference objects that are defined in the sample config files (“commands.cfg”, “templates.cfg”, etc.) that are installed if you follow the quickstart.

Overview¶

Monitoring private services or attributes of a Windows machine requires that you install an agent on it. This agent acts as a proxy between the Nagios plugin that does the monitoring and the actual service or attribute of the Windows machine. Without installing an agent on the Windows box, Shinken would be unable to monitor private services or attributes of the Windows box.

For this example, we will be installing the NSClient++ addon on the Windows machine and using the check_nt plugin to communicate with the NSClient++ addon. The check_nt plugin should already be installed on the Shinken server if you followed the quickstart guide.

Other Windows agents (like NC_Net) could be used instead of NSClient++ if you wish - provided you change command and service definitions, etc. a bit. For the sake of simplicity I will only cover using the NSClient++ addon in these instructions.

Steps¶

There are several steps you’ll need to follow in order to monitor a new Windows machine. They are:

1. Perform first-time prerequisites
2. Install a monitoring agent on the Windows machine
3. Create new host and service definitions for monitoring the Windows machine
4. Restart the Shinken daemon

What’s Already Done For You¶

To make your life a bit easier, a few configuration tasks have already been done for you:

• A check_nt command definition has been added to the “commands.cfg” file. This allows you to use the check_nt plugin to monitor Window services
• Windows server host template (called “windows-server”) has already been created in the “templates.cfg” file. This allows you to add new Windows host definitions in a simple manner

The above-mentioned config files can be found in the “/usr/local/nagios/etc/objects/” directory. You can modify the definitions in these and other definitions to suit your needs better if you’d like. However, I’d recommend waiting until you’re more familiar with configuring Nagios before doing so. For the time being, just follow the directions outlined below and you’ll be monitoring your Windows boxes in no time.

Prerequisites¶

The first time you configure Shinken to monitor a Windows machine, you’ll need to do a bit of extra work. Remember, you only need to do this for the first Windows machine you monitor.

Edit the main Shinken config file.

linux:~ # vi /usr/local/shinken/etc/nagios.cfg

Remove the leading pound (#) sign from the following line in the main configuration file:

#cfg_file=/usr/local/shinken/etc/objects/windows.cfg

Save the file and exit.

What did you just do? You told Shinken to look to the “/usr/local/shinken/etc/objects/windows.cfg” to find additional object definitions. That’s where you’ll be adding Windows host and service definitions. That configuration file already contains some sample host, hostgroup, and service definitions. For the first Windows machine you monitor, you can simply modify the sample host and service definitions in that file, rather than creating new ones.

Installing the Windows Agent¶

Before you can begin monitoring private services and attributes of Windows machines, you’ll need to install an agent on those machines. I recommend using the NSClient++ addon, which can be found at http://sourceforge.net/projects/nscplus. These instructions will take you through a basic installation of the NSClient++ addon, as well as the configuration of Shinken for monitoring the Windows machine.

1. Download the latest stable version of the NSClient++ addon from http://sourceforge.net/projects/nscplus
2. Unzip the NSClient++ files into a new C:NSClient++ directory
3. Open a command prompt and change to the C:NSClient++ directory
4. Register the NSClient++ system service with the following command:

C:\> nsclient++ /install

5. Install the NSClient++ systray with the following command (‘SysTray’ is case-sensitive):

C:\> nsclient++ SysTray

6. Open the services manager and make sure the NSClientpp service is allowed to interact with the desktop (see the ‘Log On’ tab of the services manager). If it isn’t already allowed to interact with the desktop, check the box to allow it to.

7. Edit the “NSC.INI file” (located in the “C:NSClient++” directory) and make the following changes:

• Uncomment all the modules listed in the [modules] section, except for “CheckWMI.dll” and “RemoteConfiguration.dll”
• Optionally require a password for clients by changing the “password” option in the [Settings] section.
• Uncomment the “allowed_hosts” option in the [Settings] section. Add the IP address of the Nagios server to this line, or leave it blank to allow all hosts to connect.
• Make sure the “port” option in the [NSClient] section is uncommented and set to ‘12489’ (the default port).

8. Start the NSClient++ service with the following command:

C:\> nsclient++ /start

9. If installed properly, a new icon should appear in your system tray. It will be a yellow circle with a black ‘M’ inside.
10. Success! The Windows server can now be added to the Shinken monitoring configuration...

Configuring Shinken¶

Now it’s time to define some object definitions in your Shinken configuration files in order to monitor the new Windows machine.

Open the “windows.cfg” file for editing.

linux:~ # vi /etc/shinken/objects/windows.cfg

Add a new host definition for the Windows machine that you’re going to monitor. If this is the first Windows machine you’re monitoring, you can simply modify the sample host definition in “windows.cfg”. Change the “host_name”, “alias”, and “address” fields to appropriate values for the Windows box.

define host{
    use     windows-server  ; Inherit default values from a Windows server template (make sure you keep this line!)
    host_name       winserver
    alias       My Windows Server
    address     192.168.1.2
}

Good. Now you can add some service definitions (to the same configuration file) in order to tell Shinken to monitor different aspects of the Windows machine. If this is the first Windows machine you’re monitoring, you can simply modify the sample service definitions in “windows.cfg”.

Replace “”*”winserver”*”” in the example definitions below with the name you specified in the “host_name” directive of the host definition you just added.

Add the following service definition to monitor the version of the NSClient++ addon that is running on the Windows server. This is useful when it comes time to upgrade your Windows servers to a newer version of the addon, as you’ll be able to tell which Windows machines still need to be upgraded to the latest version of NSClient++.

define service{
    use         generic-service
    host_name           winserver
    service_description NSClient++ Version
    check_command       check_nt!CLIENTVERSION
}

Add the following service definition to monitor the uptime of the Windows server.

define service{
    use         generic-service
    host_name           winserver
    service_description Uptime
    check_command       check_nt!UPTIME
}

Add the following service definition to monitor the CPU utilization on the Windows server and generate a CRITICAL alert if the 5-minute CPU load is 90% or more or a WARNING alert if the 5-minute load is 80% or greater.

define service{
    use         generic-service
    host_name           winserver
    service_description CPU Load
    check_command       check_nt!CPULOAD!-l 5,80,90
}

Add the following service definition to monitor memory usage on the Windows server and generate a CRITICAL alert if memory usage is 90% or more or a WARNING alert if memory usage is 80% or greater.

define service{
    use         generic-service
    host_name           winserver
    service_description Memory Usage
    check_command       check_nt!MEMUSE!-w 80 -c 90
}

Add the following service definition to monitor usage of the C:drive on the Windows server and generate a CRITICAL alert if disk usage is 90% or more or a WARNING alert if disk usage is 80% or greater.

define service{
    use         generic-service
    host_name           winserver
    service_description C:\ Drive Space
    check_command       check_nt!USEDDISKSPACE!-l c -w 80 -c 90
}

Add the following service definition to monitor the W3SVC service state on the Windows machine and generate a CRITICAL alert if the service is stopped.

define service{
    use         generic-service
    host_name           winserver
    service_description W3SVC
    check_command       check_nt!SERVICESTATE!-d SHOWALL -l W3SVC
}

Add the following service definition to monitor the Explorer.exe process on the Windows machine and generate a CRITICAL alert if the process is not running.

define service{
    use         generic-service
    host_name           winserver
    service_description Explorer
    check_command       check_nt!PROCSTATE!-d SHOWALL -l Explorer.exe
}

That’s it for now. You’ve added some basic services that should be monitored on the Windows box. Save the configuration file.

Password Protection¶

If you specified a password in the NSClient++ configuration file on the Windows machine, you’ll need to modify the check_nt command definition to include the password. Open the “commands.cfg” file for editing.

linux:~ # vi /usr/local/nagios/etc/commands.cfg

Change the definition of the check_nt command to include the “”-s” <PASSWORD>” argument (where PASSWORD is the password you specified on the Windows machine) like this:

define command {
    command_name    check_nt
    command_line    $USER1$/check_nt -H $HOSTADDRESS$ -p 12489 -s PASSWORD -v $ARG1$ $ARG2$
}

Save the file.

Restarting Shinken¶

You’re done with modifying the Shiknen configuration, so you’ll need to verify your configuration files and restart Shinken.

If the verification process produces any errors messages, fix your configuration file before continuing. Make sure that you don’t (re)start Shinken until the verification process completes without any errors!

Introduction¶

Publicly available services that are provided by Linux servers (“HTTP”, “FTP”, “SSH”, “SMTP”, etc.) can be monitored easily by following the documentation on Monitoring publicly available services.

These instructions assume that you’ve installed Shinken according to the quickstart guide. The sample configuration entries below reference objects that are defined in the sample config files (“commands.cfg”, “templates.cfg”, etc.) that are installed if you follow the quickstart.

Overview¶

[This document has not been completed. I would recommend you read the documentation on the NRPE addon for instructions on how to monitor a remote Linux/Unix server.]

There are several different ways to monitor attributes or remote Linux/Unix servers. One is by using shared “SSH” keys and the check_by_ssh plugin to execute plugins on remote servers. This method will not be covered here, but can result in high load on your monitoring server if you are monitoring hundreds or thousands of services. The overhead of setting up/destroying “SSH” connections is the cause of this.

Another common method of monitoring remote Linux/Unix hosts is to use the NRPE addon. NRPE allows you to execute plugins on remote Linux/Unix hosts. This is useful if you need to monitor local resources/attributes like disk usage, CPU load, memory usage, etc. on a remote host.

Introduction¶

The check_hpjd plugin (which is part of the standard Nagios plugins distribution) allows you to monitor the status of JetDirect-capable printers which have “SNMP” enabled. The plugin is capable of detecting the following printer states:

• Paper Jam
• Out of Paper
• Printer Offline
• Intervention Required
• Toner Low
• Insufficient Memory
• Open Door
• Output Tray is Full
• and more...

These instructions assume that you’ve installed Nagios according to the quickstart guide. The sample configuration entries below reference objects that are defined in the sample config files (“commands.cfg”, “templates.cfg”, etc.) that are installed if you follow the quickstart.

Overview¶

Monitoring the status of a networked printer is pretty simple. JetDirect-enabled printers usually have “SNMP” enabled, which allows Nagios to monitor their status using the check_hpjd plugin.

The check_hpjd plugin will only get compiled and installed if you have the net-snmp and net-snmp-utils packages installed on your system. Make sure the plugin exists in “/usr/local/nagios/libexec” before you continue. If it doesn’t, install net-snmp and net-snmp-utils and recompile/reinstall the Nagios plugins.

Steps¶

There are several steps you’ll need to follow in order to monitor a new network printer. They are:

• Perform first-time prerequisites
• Create new host and service definitions for monitoring the printer
• Restart Shinken services

What’s Already Done For You¶

To make your life a bit easier, a few configuration tasks have already been done for you:

• A check_hpjd command definition has been added to the “commands.cfg” file. This allows you to use the check_hpjd plugin to monitor network printers.
• A printer host template (called generic-printer) has already been created in the “templates.cfg” file. This allows you to add new printer host definitions in a simple manner.

The above-mentioned config files can be found in the “/etc/shinken/objects/” directory. You can modify the definitions in these and other definitions to suit your needs better if you’d like. However, I’d recommend waiting until you’re more familiar with configuring Shinken before doing so. For the time being, just follow the directions outlined below and you’ll be monitoring your network printers in no time.

Prerequisites¶

The first time you configure Shinken to monitor a network printer, you’ll need to do a bit of extra work. Remember, you only need to do this for the first printer you monitor.

Edit the main Nagios config file.

linux:~ # vi /etc/shinken/nagios.cfg

Remove the leading pound (#) sign from the following line in the main configuration file:

#cfg_file=/etc/shinken/objects/printer.cfg

Save the file and exit.

What did you just do? You told Shinken to look to the “/etc/shinken/objects/printer.cfg” to find additional object definitions. That’s where you’ll be adding host and service definitions for the printer. That configuration file already contains some sample host, hostgroup, and service definitions. For the first printer you monitor, you can simply modify the sample host and service definitions in that file, rather than creating new ones.

Configuring Shinken¶

You’ll need to create some object definitions in order to monitor a new printer.

Open the “printer.cfg” file for editing.

linux:~ # vi /etc/shinken/objects/printer.cfg

Add a new host definition for the networked printer that you’re going to monitor. If this is the first printer you’re monitoring, you can simply modify the sample host definition in “printer.cfg”. Change the “host_name”, “alias”, and “address” fields to appropriate values for the printer.

define host{
    use         generic-printer     ; Inherit default values from a template
    host_name   hplj2605dn          ; The name we're giving to this printer
    alias       HP LaserJet 2605dn  ; A longer name associated with the printer
    address     192.168.1.30        ; IP address of the printer
    hostgroups  allhosts            ; Host groups this printer is associated with
}

Now you can add some service definitions (to the same configuration file) to monitor different aspects of the printer. If this is the first printer you’re monitoring, you can simply modify the sample service definition in “printer.cfg”.

Replace “hplj2605dn” in the example definitions below with the name you specified in the “host_name” directive of the host definition you just added.

Add the following service definition to check the status of the printer. The service uses the check_hpjd plugin to check the status of the printer every 10 minutes by default. The “SNMP” community string used to query the printer is “public” in this example.

define service{
    use                   generic-service        ; Inherit values from a template
    host_name             hplj2605dn             ; The name of the host the service is associated with
    service_description   Printer Status         ; The service description
    check_command         check_hpjd!-C public   ; The command used to monitor the service
    normal_check_interval 10  ; Check the service every 10 minutes under normal conditions
    retry_check_interval  1   ; Re-check the service every minute until its final/hard state is determined
}

Add the following service definition to ping the printer every 10 minutes by default. This is useful for monitoring RTA, packet loss, and general network connectivity.

define service{
        use                     generic-service
        host_name               hplj2605dn
        service_description     PING
        check_command           check_ping!3000.0,80%!5000.0,100%
        normal_check_interval   10
        retry_check_interval    1
}

Save the file.

Restarting Shinken¶

Once you’ve added the new host and service definitions to the “printer.cfg” file, you’re ready to start monitoring the printer. To do this, you’ll need to verify your configuration and restart Shinken.

If the verification process produces any errors messages, fix your configuration file before continuing. Make sure that you don’t (re)start Shinken until the verification process completes without any errors!

Introduction¶

I’ll describe how you can monitor the following things on managed switches, hubs, and routers:

• Packet loss, round trip average
• “SNMP” status information
• Bandwidth / traffic rate

These instructions assume that you’ve installed Shinken according to the quickstart guide. The sample configuration entries below reference objects that are defined in the sample config files (“commands.cfg”, “templates.cfg”, etc.) that are installed when you follow the quickstart.

Overview¶

Monitoring switches and routers can either be easy or more involved - depending on what equipment you have and what you want to monitor. As they are critical infrastructure components, you’ll no doubt want to monitor them in at least some basic manner.

Switches and routers can be monitored easily by “pinging” them to determine packet loss, RTA, etc. If your switch supports “SNMP”, you can monitor port status, etc. with the check_snmp plugin and bandwidth (if you’re using MRTG) with the check_mrtgtraf plugin.

The check_snmp plugin will only get compiled and installed if you have the net-snmp and net-snmp-utils packages installed on your system. Make sure the plugin exists in “/usr/local/nagios/libexec” before you continue. If it doesn’t, install net-snmp and net-snmp-utils and recompile/reinstall the Nagios plugins.

Steps¶

There are several steps you’ll need to follow in order to monitor a new router or switch. They are:

• Perform first-time prerequisites
• Create new host and service definitions for monitoring the device
• Restart Shinken services

What’s Already Done For You¶

To make your life a bit easier, a few configuration tasks have already been done for you:

• Two command definitions (check_snmp and check_local_mrtgtraf) have been added to the “commands.cfg” file. These allows you to use the check_snmp and check_mrtgtraf plugins to monitor network routers.
• A switch host template (called generic-switch) has already been created in the “templates.cfg” file. This allows you to add new router/switch host definitions in a simple manner.

The above-mentioned config files can be found in the “/etc/shinken/objects/” directory. You can modify the definitions in these and other definitions to suit your needs better if you’d like. However, I’d recommend waiting until you’re more familiar with configuring Shinken before doing so. For the time being, just follow the directions outlined below and you’ll be monitoring your network routers/switches in no time.

Prerequisites¶

The first time you configure Shinken to monitor a network switch, you’ll need to do a bit of extra work. Remember, you only need to do this for the first switch you monitor.

Edit the main Shinken config file.

linux:~ # vi /etc/shinken/nagios.cfg

Remove the leading pound (#) sign from the following line in the main configuration file:

#cfg_file=/etc/shinken/objects/switch.cfg

Save the file and exit.

What did you just do? You told Shinken to look to the “/etc/shinken/objects/switch.cfg” to find additional object definitions. That’s where you’ll be adding host and service definitions for routers and switches. That configuration file already contains some sample host, hostgroup, and service definitions. For the first router/switch you monitor, you can simply modify the sample host and service definitions in that file, rather than creating new ones.

Configuring Shinken¶

You’ll need to create some object definitions in order to monitor a new router/switch.

Open the “switch.cfg” file for editing.

linux:~ # vi /etc/shinken/objects/switch.cfg

Add a new host definition for the switch that you’re going to monitor. If this is the first switch you’re monitoring, you can simply modify the sample host definition in “switch.cfg”. Change the “host_name”, “alias”, and “address” fields to appropriate values for the switch.

define host{
    use        generic-switch         ; Inherit default values from a template
    host_name  linksys-srw224p        ; The name we're giving to this switch
    alias      Linksys SRW224P Switch ; A longer name associated with the switch
    address    192.168.1.253          ; IP address of the switch
    hostgroups allhosts,switches      ; Host groups this switch is associated with
}

Monitoring Services¶

Now you can add some service definitions (to the same configuration file) to monitor different aspects of the switch. If this is the first switch you’re monitoring, you can simply modify the sample service definition in “switch.cfg”.

Replace linksys-srw224p in the example definitions below with the name you specified in the “host_name” directive of the host definition you just added.

Monitoring Packet Loss and RTA¶

Add the following service definition in order to monitor packet loss and round trip average between the Shinken host and the switch every 5 minutes under normal conditions.

define service{
   use                    generic-service
   host_name              linksys-srw224p
   service_description    PING
   check_command          check_ping!200.0,20%!600.0,60%
   normal_check_interval  5
   retry_check_interval   1
}

1. Inherit values from a template
2. The name of the host the service is associated with
3. The service description
4. The command used to monitor the service
5. Check the service every 5 minutes under normal conditions
6. Re-check the service every minute until its final/hard state is determined

This service will be:

• CRITICAL if the round trip average (RTA) is greater than 600 milliseconds or the packet loss is 60% or more
• WARNING if the RTA is greater than 200 ms or the packet loss is 20% or more
• OK if the RTA is less than 200 ms and the packet loss is less than 20%

Monitoring SNMP Status Information¶

If your switch or router supports “SNMP”, you can monitor a lot of information by using the check_snmp plugin. If it doesn’t, skip this section.

Add the following service definition to monitor the uptime of the switch.

define service{
    use                  generic-service ; Inherit values from a template
    host_name            linksys-srw224p
    service_description  Uptime
    check_command        check_snmp!-C public -o sysUpTime.0
}

In the “check_command” directive of the service definition above, the “-C public” tells the plugin that the “SNMP” community name to be used is “public” and the “-o sysUpTime.0” indicates which OID should be checked.

If you want to ensure that a specific port/interface on the switch is in an up state, you could add a service definition like this:

define service{
    use                 generic-service ; Inherit values from a template
    host_name           linksys-srw224p
    service_description Port 1 Link Status
    check_command       check_snmp!-C public -o ifOperStatus.1 -r 1 -m RFC1213-MIB
}

In the example above, the “-o ifOperStatus.1” refers to the OID for the operational status of port 1 on the switch.

The “-r 1” option tells the check_snmp plugin to return an OK state if “1” is found in the “SNMP” result (1 indicates an “up” state on the port) and CRITICAL if it isn’t found.

The “-m RFC1213-MIB” is optional and tells the check_snmp plugin to only load the “RFC1213-MIB” instead of every single MIB that’s installed on your system, which can help speed things up.

That’s it for the “SNMP” monitoring example. There are a million things that can be monitored via “SNMP”, so its up to you to decide what you need and want to monitor. Good luck!

You can usually find the OIDs that can be monitored on a switch by running the following command (replace 192.168.1.253 with the IP address of the switch): snmpwalk -v1 -c public 192.168.1.253 -m ALL .1

Monitoring Bandwidth / Traffic Rate¶

If you’re monitoring bandwidth usage on your switches or routers using MRTG, you can have Shinken alert you when traffic rates exceed thresholds you specify. The check_mrtgtraf plugin (which is included in the Nagios plugins distribution) allows you to do this.

You’ll need to let the check_mrtgtraf plugin know what log file the MRTG data is being stored in, along with thresholds, etc. In my example, I’m monitoring one of the ports on a Linksys switch. The MRTG log file is stored in “/var/lib/mrtg/192.168.1.253_1.log”. Here’s the service definition I use to monitor the bandwidth data that’s stored in the log file...

define service{
   use                 generic-service ; Inherit values from a template
   host_name           linksys-srw224p
   service_description Port 1 Bandwidth Usage
   check_command       check_local_mrtgtraf!/var/lib/mrtg/192.168.1.253_1.log!AVG!1000000,2000000!5000000,5000000!10
}

In the example above, the “/var/lib/mrtg/192.168.1.253_1.log” option that gets passed to the check_local_mrtgtraf command tells the plugin which MRTG log file to read from.

The AVG option tells it that it should use average bandwidth statistics. The “1000000,2000000” options are the warning thresholds (in bytes) for incoming traffic rates.

The “5000000,5000000” are critical thresholds (in bytes) for outgoing traffic rates. The “10” option causes the plugin to return a CRITICAL state if the MRTG log file is older than 10 minutes (it should be updated every 5 minutes).

Save the file.

Restarting Shinken¶

Once you’ve added the new host and service definitions to the “switch.cfg” file, you’re ready to start monitoring the router/switch. To do this, you’ll need to verify your configuration and restart Sinken.

If the verification process produces any errors messages, fix your configuration file before continuing. Make sure that you don’t (re)start Shinken until the verification process completes without any errors!

Introduction¶

Private services, in contrast, cannot be monitored with Shinken without an intermediary agent of some kind. Examples of private services associated with hosts are things like CPU load, memory usage, disk usage, current user count, process information, etc. These private services or attributes of hosts are not usually exposed to external clients. This situation requires that an intermediary monitoring agent be installed on any host that you need to monitor such information on. More information on monitoring private services on different types of hosts can be found in the documentation on:

• Monitoring Windows machines
• Monitoring Netware servers
• Monitoring Linux/Unix machines

Occasionally you will find that information on private services and applications can be monitored with “SNMP”. The “SNMP” agent allows you to remotely monitor otherwise private (and inaccessible) information about the host. For more information about monitoring services using “SNMP”, check out the documentation on Monitoring routers/switches.

These instructions assume that you’ve installed Shinken according to the quickstart guide. The sample configuration entries below reference objects that are defined in the sample “commands.cfg” and “localhost.cfg” config files.

Plugins For Monitoring Services¶

When you find yourself needing to monitor a particular application, service, or protocol, chances are good that a plugin exists to monitor it. The official Nagios plugins distribution comes with plugins that can be used to monitor a variety of services and protocols. There are also a large number of contributed plugins that can be found in the “contrib/” subdirectory of the plugin distribution. The NagiosExchange.org website hosts a number of additional plugins that have been written by users, so check it out when you have a chance.

If you don’t happen to find an appropriate plugin for monitoring what you need, you can always write your own. Plugins are easy to write, so don’t let this thought scare you off. Read the documentation on developing plugins for more information.

I’ll walk you through monitoring some basic services that you’ll probably use sooner or later. Each of these services can be monitored using one of the plugins that gets installed as part of the Nagios plugins distribution. Let’s get started...

Creating A Host Definition¶

Before you can monitor a service, you first need to define a host that is associated with the service. You can place host definitions in any object configuration file specified by a cfg_file directive or placed in a directory specified by a cfg_dir directive. If you have already created a host definition, you can skip this step.

For this example, lets say you want to monitor a variety of services on a remote host. Let’s call that host remotehost. The host definition can be placed in its own file or added to an already exiting object configuration file. Here’s what the host definition for remotehost might look like:

define host{
    use           generic-host        ; Inherit default values from a template
    host_name     remotehost          ; The name we're giving to this host
    alias         Some Remote Host    ; A longer name associated with the host
    address       192.168.1.50        ; IP address of the host
    hostgroups    allhosts            ; Host groups this host is associated with
}

Now that a definition has been added for the host that will be monitored, we can start defining services that should be monitored. As with host definitions, service definitions can be placed in any object configuration file.

Creating Service Definitions¶

For each service you want to monitor, you need to define a service in Shinken that is associated with the host definition you just created. You can place service definitions in any object configuration file specified by a cfg_file directive or placed in a directory specified by a cfg_dir directive.

Some example service definitions for monitoring common public service (“HTTP”, “FTP”, etc) are given below.

Monitoring HTTP¶

Chances are you’re going to want to monitor web servers at some point - either yours or someone else’s. The check_http plugin is designed to do just that. It understands the “HTTP” protocol and can monitor response time, error codes, strings in the returned HTML, server certificates, and much more.

The “commands.cfg” file contains a command definition for using the check_http plugin. It looks like this:

define command{
    name            check_http
    command_name    check_http
    command_line    $USER1$/check_http -I $HOSTADDRESS$ $ARG1$
    }

A simple service definition for monitoring the “HTTP” service on the remotehost machine might look like this:

define service{
    use                 generic-service     ; Inherit default values from a template
    host_name           remotehost
    service_description HTTP
    check_command       check_http
    }

This simple service definition will monitor the “HTTP” service running on remotehost. It will produce alerts if the web server doesn’t respond within 10 seconds or if it returns “HTTP” errors codes (403, 404, etc.). That’s all you need for basic monitoring. Pretty simple, huh?

For more advanced monitoring, run the check_http plugin manually with “–help” as a command-line argument to see all the options you can give the plugin. This “–help” syntax works with all of the plugins I’ll cover in this document.

A more advanced definition for monitoring the “HTTP” service is shown below. This service definition will check to see if the /download/index.php URI contains the string “latest-version.tar.gz”. It will produce an error if the string isn’t found, the URI isn’t valid, or the web server takes longer than 5 seconds to respond.

define service{
    use                 generic-service   ; Inherit default values from a template
    host_name           remotehost
    service_description Product Download Link
    check_command       check_http!-u /download/index.php -t 5 -s "latest-version.tar.gz"
    }

Monitoring FTP¶

When you need to monitor “FTP” servers, you can use the check_ftp plugin. The “commands.cfg” file contains a command definition for using the check_ftp plugin, which looks like this:

define command{
    command_name    check_ftp
    command_line    $USER1$/check_ftp -H $HOSTADDRESS$ $ARG1$
    }

A simple service definition for monitoring the “FTP” server on remotehost would look like this:

define service{
    use                   generic-service  ; Inherit default values from a template
    host_name             remotehost
    service_description   FTP
    check_command         check_ftp
    }

This service definition will monitor the “FTP” service and generate alerts if the “FTP” server doesn’t respond within 10 seconds.

A more advanced service definition is shown below. This service will check the “FTP” server running on port 1023 on remotehost. It will generate an alert if the server doesn’t respond within 5 seconds or if the server response doesn’t contain the string “Pure-FTPd [TLS]”.

define service{
    use                   generic-service   ; Inherit default values from a template
    host_name             remotehost
    service_description   Special FTP
    check_command         check_ftp!-p 1023 -t 5 -e "Pure-FTPd [TLS]"
    }

Monitoring SSH¶

When you need to monitor “SSH” servers, you can use the check_ssh plugin. The “commands.cfg” file contains a command definition for using the check_ssh plugin, which looks like this:

define command{
    command_name    check_ssh
    command_line    $USER1$/check_ssh $ARG1$ $HOSTADDRESS$
    }

A simple service definition for monitoring the “SSH” server on remotehost would look like this:

define service{
    use                  generic-service  ; Inherit default values from a template
    host_name            remotehost
    service_description  SSH
    check_command        check_ssh
    }

This service definition will monitor the “SSH” service and generate alerts if the “SSH” server doesn’t respond within 10 seconds.

A more advanced service definition is shown below. This service will check the “SSH” server and generate an alert if the server doesn’t respond within 5 seconds or if the server version string string doesn’t match “OpenSSH_4.2”.

define service{
    use                 generic-service   ; Inherit default values from a template
    host_name           remotehost
    service_description SSH Version Check
    check_command       check_ssh!-t 5 -r "OpenSSH_4.2"
    }

Monitoring SMTP¶

The check_smtp plugin can be using for monitoring your email servers. The “commands.cfg” file contains a command definition for using the check_smtp plugin, which looks like this:

define command{
    command_name    check_smtp
    command_line    $USER1$/check_smtp -H $HOSTADDRESS$ $ARG1$
    }

A simple service definition for monitoring the “SMTP” server on remotehost would look like this:

define service{
    use                  generic-service  ; Inherit default values from a template
    host_name            remotehost
    service_description  SMTP
    check_command        check_smtp
    }

This service definition will monitor the “SMTP” service and generate alerts if the “SMTP” server doesn’t respond within 10 seconds.

A more advanced service definition is shown below. This service will check the “SMTP” server and generate an alert if the server doesn’t respond within 5 seconds or if the response from the server doesn’t contain “mygreatmailserver.com”.

define service{
    use                  generic-service  ; Inherit default values from a template
    host_name            remotehost
    service_description  SMTP Response Check
    check_command        check_smtp!-t 5 -e "mygreatmailserver.com"
    }

Monitoring POP3¶

The check_pop plugin can be using for monitoring the “POP3” service on your email servers. The “commands.cfg” file contains a command definition for using the check_pop plugin, which looks like this:

define command{
    command_name    check_pop
    command_line    $USER1$/check_pop -H $HOSTADDRESS$ $ARG1$
    }

A simple service definition for monitoring the “POP3” service on remotehost would look like this:

define service{
    use                  generic-service  ; Inherit default values from a template
    host_name            remotehost
    service_description  POP3
    check_command        check_pop
    }

This service definition will monitor the “POP3” service and generate alerts if the “POP3” server doesn’t respond within 10 seconds.

A more advanced service definition is shown below. This service will check the “POP3” service and generate an alert if the server doesn’t respond within 5 seconds or if the response from the server doesn’t contain “mygreatmailserver.com”.

define service{
    use                  generic-service  ; Inherit default values from a template
    host_name            remotehost
    service_description  POP3 Response Check
    check_command        check_pop!-t 5 -e "mygreatmailserver.com"
    }

Monitoring IMAP¶

The check_imap plugin can be using for monitoring “IMAP4” service on your email servers. The “commands.cfg” file contains a command definition for using the check_imap plugin, which looks like this:

define command{
    command_name    check_imap
    command_line    $USER1$/check_imap -H $HOSTADDRESS$ $ARG1$
    }

A simple service definition for monitoring the “IMAP4” service on remotehost would look like this:

define service{
    use                  generic-service  ; Inherit default values from a template
    host_name            remotehost
    service_description  IMAP
    check_command        check_imap
    }

This service definition will monitor the “IMAP4” service and generate alerts if the “IMAP” server doesn’t respond within 10 seconds.

A more advanced service definition is shown below. This service will check the IAMP4 service and generate an alert if the server doesn’t respond within 5 seconds or if the response from the server doesn’t contain “mygreatmailserver.com”.

define service{
    use                  generic-service  ; Inherit default values from a template
    host_name            remotehost
    service_description  IMAP4 Response Check
    check_command        check_imap!-t 5 -e "mygreatmailserver.com"
    }

Restarting Shinken¶

Once you’ve added the new host and service definitions to your object configuration file(s), you’re ready to start monitoring them. To do this, you’ll need to verify your configuration and restart Shinken.

If the verification process produces any errors messages, fix your configuration file before continuing. Make sure that you don’t (re)start Shinken until the verification process completes without any errors!

Introduction¶

There are several different configuration files that you’re going to need to create or edit before you start monitoring anything. Be patient! Configuring Shinken can take quite a while, especially if you’re first-time user. Once you figure out how things work, it’ll all be well worth your time. :-)

Sample configuration files are installed in the “/usr/local/shinken/etc/” directory when you follow the Quickstart installation guide.

Main Configuration File¶

Main Shinken configuration files are separate in two part :

• Nagios compatible part (nagios.cfg)
• Shinken specific part (shinken-specific.cfg)

Documentation for the main configuration file can be found Main Configuration File Options.

Resource File(s)¶

Resource files can be used to store user-defined macros. The main point of having resource files is to use them to store sensitive configuration information (like passwords), without making them available to the CGIs.

You can specify one or more optional resource files by using the resource_file directive in your main configuration file. ngshinken-configmain#configuringshinken-configmain-resource_file

Object Definition Files¶

Object definition files are used to define hosts, services, hostgroups, contacts, contactgroups, commands, etc. This is where you define all the things you want monitor and how you want to monitor them.

You can specify one or more object definition files by using the cfg_file and/or cfg_dir directives in your main configuration file.

An introduction to object definitions, and how they relate to each other, can be found here.

Config File Location and sample¶

The main configuration files are usually named “nagios.cfg” and “shinken-specific*.cfg”. They are located in the “/etc/shinken/” directory. Sample main configuration files (“/etc/shinken/nagios.cfg”, “/etc/shiken/shinken-specific*.cfg”) are installed for you when you follow the Quickstart installation guide.

Broker Modules¶

Shinken provides a lot of functionality through its interfaces with external systems. To this end, the broker daemon will load modules. The function of the modules is described in more detail in the Broker modules page.

Broker modules are essential for the web frontends, the metric databases, logging state changes in log management systems.

Arbiter, Receiver, Poller, Reactionner Modules¶

Shinken daemons can also load modules to influence what they can do and how they interface with external systems.

The sample configuration file provides succinct explanations of each module, the shinken architecture page also links to the different module configuration pages.

Path, users and log variables¶

Below you will find descriptions of each main Shinken configuration file option.

define broker{
     modules           <logging modules>
     [...]
}

define module{
    module_name      Simple-log
    module_type      simple_log
    path             /var/lib/shinken/nagios.log
    archive_path     /var/lib/shinken/archives/
}

log_level=[DEBUG,INFO,WARNING,ERROR,CRITICAL]

log_level=WARNING

human_timestamp_log=[0/1]

human_timestamp_log=0

cfg_file=<file_name>

cfg_file=/usr/local/shinken/etc/hosts.cfg
cfg_file=/usr/local/shinken/etc/services.cfg
cfg_file=/usr/local/shinken/etc/commands.cfg

cfg_dir=<directory_name>

cfg_dir=/etc/shinken/commands
cfg_dir=/etc/shinken/services
cfg_dir=/etc/shinken/hosts

cfg_dir=

resource_file=/etc/shinken/resource.cfg

user=username

user=shinken

group=groupname

group=shinken

idontcareaboutsecurity=<0/1>

idontcareaboutsecurity=0

enable_notifications=<0/1>

enable_notifications=1

log_rotation_method=<n/h/d/w/m>

log_rotation_method=d

check_external_commands=<0/1>

check_external_commands=1

command_file=<file_name>

command_file=/var/lib/shinken/rw/nagios.cmd

retain_state_information=<0/1>

retain_state_information=1

state_retention_file=<file_name>

state_retention_file=/var/lib/shinken/retention.dat

retention_update_interval=<minutes>

retention_update_interval=60

Scheduling parameters¶

execute_service_checks=<0/1>
execute_host_checks=<0/1>

execute_service_checks=1
execute_host_checks=1

accept_passive_service_checks=<0/1>
accept_passive_host_checks=<0/1>

accept_passive_service_checks=1
accept_passive_host_checks=1

enable_event_handlers=<0/1>

enable_event_handlers=1

no_event_handlers_during_downtimes=<0/1>

no_event_handlers_during_downtimes=1

use_syslog=<0/1>

use_syslog=1

log_notifications=<0/1>

log_notifications=1

log_service_retries=<0/1>
log_host_retries=<0/1>

log_service_retries=0
log_host_retries=0

log_event_handlers=<0/1>

log_event_handlers=1

log_initial_states=<0/1>

log_initial_states=1

log_external_commands=<0/1>

log_external_commands=1

log_passive_checks=<0/1>

log_passive_checks=1

global_host_event_handler=<command>
global_service_event_handler=<command>

global_host_event_handler=log-host-event-to-db
global_service_event_handler=log-service-event-to-db

max_service_check_spread=<minutes>

max_service_check_spread=30

interval_length=<seconds>

interval_length=60

Tuning and advanced parameters¶

Others parameters are useful for advanced features like flapping detection or performance tuning. Please look at the configuringshinken-configmain-advanced page for them.

Old CGI related parameter¶

If you are using the old CGI from Nagios, please migrate to a new WebUI. For historical perspective you can find information on the specific CGI parameters.

Unused parameters¶

The below parameters are inherited from Nagios but are not used in Shinken. You can defined them but if you don’t it will be the same :)

They are listed on another page Unused Nagios parameters.

What Are Objects?¶

Objects are all the elements that are involved in the monitoring and notification logic. Types of objects include:

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

More information on what objects are and how they relate to each other can be found below.

Where Are Objects Defined?¶

Objects can be defined in one or more configuration files and/or directories that you specify using the cfg_file and/or cfg_dir directives in the main configuration file.

When you follow the Quickstart installation guide, several sample object configuration files are placed in “/etc/shinken/objects/”. You can use these sample files to see how object inheritance works and learn how to define your own object definitions.

How Are Objects Defined?¶

Objects are defined in a flexible template format, which can make it much easier to manage your Shinken configuration in the long term. Basic information on how to define objects in your configuration files can be found here.

Once you get familiar with the basics of how to define objects, you should read up on object inheritance, as it will make your configuration more robust for the future. Seasoned users can exploit some advanced features of object definitions as described in the documentation on object tricks.

Objects Explained¶

Some of the main object types are explained in greater detail below...

Introduction¶

One of the features of Shinken’ object configuration format is that you can create object definitions that inherit properties from other object definitions. An explanation of how object inheritance works can be found here. I strongly suggest that you familiarize yourself with object inheritance once you read over the documentation presented below, as it will make the job of creating and maintaining object definitions much easier than it otherwise would be. Also, read up on the object tricks that offer shortcuts for otherwise tedious configuration tasks.

When creating and/or editing configuration files, keep the following in mind:

• Lines that start with a ‘”#”’ character are taken to be comments and are not processed
• Directive names are case-sensitive

Sample Configuration Files¶

Sample object configuration files are installed in the “/etc/shinken/” directory when you follow the quickstart installation guide.

Object Types¶

• Host
• Host Group
• Service
• Service Group
• Contact
• Contact Group
• Time Period
• Command
• Service Dependency
• Service Escalation
• Host Dependency
• Host Escalation
• Extended Host Information
• Extended Service Information
• Realm
• Arbiter
• Scheduler
• Poller
• Reactionner
• Broker

Introduction¶

Users often request that new variables be added to host, service, and contact definitions. These include variables for “SNMP” community, MAC address, AIM username, Skype number, and street address. The list is endless. The problem that I see with doing this is that it makes Nagios less generic and more infrastructure-specific. Nagios was intended to be flexible, which meant things needed to be designed in a generic manner. Host definitions in Nagios, for example, have a generic “address” variable that can contain anything from an IP address to human-readable driving directions - whatever is appropriate for the user’s setup.

Still, there needs to be a method for admins to store information about their infrastructure components in their Nagios configuration without imposing a set of specific variables on others. Nagios attempts to solve this problem by allowing users to define custom variables in their object definitions. Custom variables allow users to define additional properties in their host, service, and contact definitions, and use their values in notifications, event handlers, and host and service checks.

Custom Variable Basics¶

There are a few important things that you should note about custom variables:

• Custom variable names must begin with an underscore (_) to prevent name collision with standard variables
• Custom variable names are case-insensitive
• Custom variables are inherited from object templates like normal variables
• Scripts can reference custom variable values with macros and environment variables

Examples¶

Here’s an example of how custom variables can be defined in different types of object definitions:

define host{
   host_name       linuxserver
   _mac_address    00:06:5B:A6:AD:AA ; <-- Custom MAC_ADDRESS variable
   _rack_number    R32               ; <-- Custom RACK_NUMBER variable
...
}

define service{
   host_name        linuxserver
   description      Memory Usage
   _SNMP_community  public         ; <-- Custom SNMP_COMMUNITY variable
   _TechContact     Jane Doe       ; <-- Custom TECHCONTACT variable
   ....
}

define contact{
   contact_name    john
   _AIM_username   john16        ; <-- Custom AIM_USERNAME variable
   _YahooID        john32        ; <-- Custom YAHOOID variable
   ...
}

Custom Variables As Macros¶

Custom variable values can be referenced in scripts and executables that Nagios runs for checks, notifications, etc. by using macros or environment variables.

In order to prevent name collision among custom variables from different object types, Nagios prepends “_HOST”, “_SERVICE”, or “_CONTACT” to the beginning of custom host, service, or contact variables, respectively, in macro and environment variable names. The table below shows the corresponding macro and environment variable names for the custom variables that were defined in the example above.

Custom Variables And Inheritance¶

Custom object variables are inherited just like standard host, service, or contact variables.

Tuning and advanced parameters¶

Performance data parameters¶

perfdata_timeout=<seconds>

perfdata_timeout=5

process_performance_data=<0/1>

process_performance_data=1

host_perfdata_command=<command>
service_perfdata_command=<command>

host_perfdata_command=process-host-perfdata
services_perfdata_command=process-service-perfdata

host_perfdata_file=<file_name>
service_perfdata_file=<file_name>

host_perfdata_file=/usr/local/shinken/var/host-perfdata.dat
service_perfdata_file=/usr/local/shinken/var/service-perfdata.dat

host_perfdata_file_template=<template>

host_perfdata_file_template=[HOSTPERFDATA]\t$TIMET$\t$HOSTNAME$\t$HOSTEXECUTIONTIME$\t$HOSTOUTPUT$\t$HOSTPERFDATA$

service_perfdata_file_template=<template>

service_perfdata_file_template=[SERVICEPERFDATA]\t$TIMET$\t$HOSTNAME$\t$SERVICEDESC$\t$SERVICEEXECUTIONTIME$\t$SERVICELATENCY$\t$SERVICEOUTPUT$\t$SERVICEPERFDATA$

host_perfdata_file_mode=<mode>
service_perfdata_file_mode=<mode>

host_perfdata_file_mode=a
service_perfdata_file_mode=a

host_perfdata_file_processing_interval=<seconds>
service_perfdata_file_processing_interval=<seconds>

host_perfdata_file_processing_interval=0
service_perfdata_file_processing_interval=0

host_perfdata_file_processing_command=<command>
service_perfdata_file_processing_command=<command>

host_perfdata_file_processing_command=process-host-perfdata-file
service_perfdata_file_processing_command=process-service-perfdata-file

Advanced scheduling parameters¶

passive_host_checks_are_soft=<0/1>

passive_host_checks_are_soft=1

enable_predictive_host_dependency_checks=<0/1>
enable_predictive_service_dependency_checks=<0/1>

enable_predictive_host_dependency_checks=1
enable_predictive_service_dependency_checks=1

check_for_orphaned_services=<0/1>
check_for_orphaned_hosts=<0/1>

check_for_orphaned_services=1
check_for_orphaned_hosts=1

max_plugins_output_length=<int>

max_plugins_output_length=8192

enable_problem_impacts_states_change=<0/1>

enable_problem_impacts_states_change=0

Performance tuning¶

cached_host_check_horizon=<seconds>
cached_service_check_horizon=<seconds>

cached_host_check_horizon=15
cached_service_check_horizon=15

use_large_installation_tweaks=<0/1>

use_large_installation_tweaks=0

enable_environment_macros=<0/1>

enable_environment_macros=0

Flapping parameters¶

enable_flap_detection=<0/1>

enable_flap_detection=1

low_service_flap_threshold=<percent>
low_host_flap_threshold=<percent>

low_service_flap_threshold=25.0
low_host_flap_threshold=25.0

high_service_flap_threshold=<percent>
high_host_flap_threshold=<percent>

high_service_flap_threshold=50.0
high_host_flap_threshold=50.0

flap_history=<int>

flap_history=20

Commands/checks timeout¶

service_check_timeout=<seconds>

service_check_timeout=60

event_handler_timeout=<seconds>  # default: 30s
notification_timeout=<seconds>   # default: 30s
ocsp_timeout=<seconds>           # default: 15s
ochp_timeout=<seconds>           # default: 15s

event_handler_timeout=60
notification_timeout=60
ocsp_timeout=5
ochp_timeout=5

Old Obsess Over commands¶

obsess_over_services=<0/1>

obsess_over_services=1

ocsp_command=<command>

ocsp_command=obsessive_service_handler

obsess_over_hosts=<0/1>

obsess_over_hosts=1

ochp_command=<command>

ochp_command=obsessive_host_handler

Freshness check¶

check_service_freshness=<0/1>
check_host_freshness=<0/1>

check_service_freshness=0
check_host_freshness=0

service_freshness_check_interval=<seconds>
host_freshness_check_interval=<seconds>

service_freshness_check_interval=60
host_freshness_check_interval=60

additional_freshness_latency=<#>

additional_freshness_latency=15

All the others :)¶

date_format=<option>

date_format=us

use_timezone=<tz>

use_timezone=US/Mountain

illegal_object_name_chars=<chars...>

illegal_object_name_chars=`~!$%^&*"|'<>?,()=

illegal_macro_output_chars=<chars...>

illegal_macro_output_chars=`~$^&"|'<>

use_regexp_matching=<0/1>

use_regexp_matching=0

use_true_regexp_matching=<0/1>

use_true_regexp_matching=0

admin_email=<email_address>

admin_email=root@localhost.localdomain

admin_pager=<pager_number_or_pager_email_gateway>

admin_pager=pageroot@localhost.localdomain

How to verify the configuration¶

In order to verify your configuration, run Shinken-arbiter with the “-v” command line option like so:

linux:~ # /usr/local/shinken/bin/shinken-arbiter -v -c /usr/local/shinken/etc/nagios.cfg -c /usr/local/shinken/etc/shinken-specific.cfg

If you’ve forgotten to enter some critical data or misconfigured things, Shinken will spit out a warning or error message that should point you to the location of the problem. Error messages generally print out the line in the configuration file that seems to be the source of the problem. On errors, Shinken will exit the pre-flight check. If you get any error messages you’ll need to go and edit your configuration files to remedy the problem. Warning messages can generally be safely ignored, since they are only recommendations and not requirements.

Important caveats¶

1. Shinken will not check the syntax of module variables
2. Shinken will not check the validity of data passed to modules
3. Shinken will NOT notify you if you mistyped an expected variable, it will treat it as a custom variable.
4. Shinken sometimes uses variables that expect lists, the order of items in lists is important, check the relevant documentation

How to apply your changes¶

Once you’ve verified your configuration files and fixed any errors you can go ahead and (re)start Shinken.

Starting Shinken¶

• Init Script: The easiest way to start the Shinken daemon is by using the init script like so:

linux:~ # /etc/rc.d/init.d/shinken start

• Manually: You can start the Shinken daemon manually with the “-d” command line option like so:

linux:~ # /usr/local/shinken/bin/shinken-scheduler -d -c /usr/local/shinken/etc/schedulerd.ini
linux:~ # /usr/local/shinken/bin/shinken-poller -d -c /usr/local/shinken/etc/pollerd.ini
linux:~ # /usr/local/shinken/bin/shinken-reactionner -d -c /usr/local/shinken/etc/reactionnerd.ini
linux:~ # /usr/local/shinken/bin/shinken-broker -d -c /usr/local/shinken/etc/brokerd.ini
linux:~ # /usr/local/shinken/bin/shinken-arbiter -d -c /usr/local/shinken/etc/nagios.cfg -c /usr/local/shinken/etc/shinken-specific.cfg

Restarting Shinken¶

Restarting/reloading is nececessary when you modify your configuration files and want those changes to take effect.

• Init Script: The easiest way to restart the Shinken daemon is by using the init script like so:

linux:~ # /etc/rc.d/init.d/shinken restart

• Manually: You can restart the Shinken process by sending it a SIGTERM signal like so:

linux:~ # kill <arbiter_pid>
linux:~ # /usr/local/shinken/bin/shinken-arbiter. -d -c /usr/local/shinken/etc/nagios.cfg

Stopping Shinken¶

• Init Script: The easiest way to stop the Shinken daemons is by using the init script like so:

linux:~ # /etc/rc.d/init.d/shinken stop

• Manually: You can stop the Shinken process by sending it a SIGTERM signal like so:

linux:~ # kill <arbiter_pid> <scheduler_pid> <poller_pid> <reactionner_pid> <broker_pid>

Default Shinken configuration¶

If you followed the 10 Minute Shinken Installation Guide tutorial you were able to install and launch Shinken.

The default configuration deployed with the Shinken sources contains:

• one arbiter
• one scheduler
• one poller
• one reactionner
• one broker
• one receiver (commented out)

All these elements must have a basic configuration. The Arbiter must know about the other daemons and how to communicate with them, just as the other daemons need to know on which TCP port they must listen on.

Configure the Shinken Daemons¶

The schedulers, pollers, reactionners and brokers daemons need to know in which directory to work on, and on which TCP port to listen. That’s all.

Each daemon has one configuration file. The default location is /usr/local/shinken/etc/.

Let’s see what it looks like:

$cat etc/schedulerd.ini

[daemon]
workdir=/usr/local/shinken/var
pidfile=%(workdir)s/schedulerd.pid
port=7768
host=0.0.0.0

daemon_enabled=1

# Optional configurations

user=shinken
group=shinken
idontcareaboutsecurity=0
use_ssl=0
#certs_dir=etc/certs
#ca_cert=etc/certs/ca.pem
#server_cert=etc/certs/server.pem
hard_ssl_name_check=0
use_local_log=1
local_log=brokerd.log
log_level=INFO
max_queue_size=100000

So here we have a scheduler:

• workdir: working directory of the daemon. By default /usr/local/shinken/var

• pidfile: pid file of the daemon (so we can kill it :) ). By default /usr/local/shinken/var/schedulerd.pid for a scheduler.

• port: TCP port to listen to. By default:

  • scheduler: 7768
  • poller: 7771
  • reactionner: 7769
  • broker: 7772
  • arbiter: 7770 (the arbiter configuration will be seen later)

• host: IP interface to listen on. The default 0.0.0.0 means all interfaces

• user: user used by the daemon to run. By default shinken

• group: group of the user. By default shinken.

• idontcareaboutsecurity: if set to 1, you can run it under the root account. But seriously: do not to this. The default is 0 of course.

• daemon_enabled : if set to 0, the daemon won’t run. Useful for distributed setups where you only need a poller for example.

• use_ssl=0

• #certs_dir=etc/certs

• #ca_cert=etc/certs/ca.pem

• #server_cert=etc/certs/server.pem

• hard_ssl_name_check=0

• use_local_log=1 : Log all messages that match the log_level for this daemon in a local directory

• local_log=brokerd.log : name of the log file where to save the logs

• log_level=INFO : Log_level that will be permitted to be logger. Warning permits Warning, Error, Critical to be logged. INFO by default.

• max_queue_size=100000 : If a module got a brok queue() higher than this value, it will be killed and restarted. Put to 0 to disable it

Daemon declaration in the global configuration¶

Now each daemon knows in which directory to run, and on which tcp port to listen. A daemon is a resource in the Shinken architecture. Such resources must be declared in the global configuration (where the Arbiter is) for them to be utilized.

The global configuration file is: /usr/local/shinken/etc/shinken-specific.cfg/

The daemon declarations are quite simple: each daemon is represented by an object. The information contained in the daemon object are network parameters about how its resources should be treated (is it a spare, ...).

Each objects type corresponds to a daemon:

• arbiter
• scheduler
• poller
• reactionner
• broker
• receiver

The names were chosen to understand their roles more easily. :)

They have these parameters in common:

• *_name: name of the resource
• address: IP or DNS address to connect to the daemon
• port: I think you can find it on your own by now :)
• [spare]: 1 or 0, is a spare or not. See advanced features for this.
• [realm]: realm membership See advanced features for this.
• [manage_sub_realms]: manage or not sub realms. See advanced features for this.
• [modules]: modules used by the daemon. See below.

define arbiter{
     arbiter_name  arbiter-1
     host_name     server-1
     address       192.168.0.1
     port          7770
     spare         0
}

define scheduler{
     scheduler_name   scheduler-1
     address          192.168.0.1
     port             7768
     spare            0
}

define reactionner{
     reactionner_name     reactionner-1
     address              192.168.0.1
     port                 7769
     spare                0
}

define poller{
     poller_name     poller-1
     address         192.168.0.1
     port            7771
     spare           0
}

define broker{
     broker_name      broker-1
     address          192.168.0.1
     port             7772
     spare            0
     modules          Status-Dat,Simple-log
}

define module{
     module_name      Simple-log
     module_type      simple_log
     path             /usr/local/shinken/var/shinken.log
}

define module{
     module_name              Status-Dat
     module_type              status_dat
     status_file              /usr/local/shinken/var/status.data
     object_cache_file        /usr/local/shinken/var/objects.cache
     status_update_interval   15 ; update status.dat every 15s
}

daemon_path -d -c daemon_configuration.ini

/usr/local/shinken/bin/shinken-scheduler -d -c /usr/local/shinken/etc/schedulerd.ini
/usr/local/shinken/bin/shinken-poller -d -c /usr/local/shinken/etc/pollerd.ini
/usr/local/shinken/bin/shinken-reactionner -d -c /usr/local/shinken/etc/reactionnerd.ini
/usr/local/shinken/bin/shinken-broker -d -c /usr/local/shinken/etc/brokerd.ini

#First we should check the configuration for errors
python bin/shinken-arbiter -v -c etc/nagios.cfg -c etc/shinken-specific.cfg

#then, we can really launch it
python bin/shinken-arbiter -d -c etc/nagios.cfg -c etc/shinken-specific.cfg

What next¶

You are ready to continue to the next section, get DATA IN Shinken.

If you feel in the mood for testing even more shinken features, now would be the time to look at advanced_features to play with distributed and high availability architectures!

Introduction¶

Shinken includes a set of scalable internal mechanisms for checking the status of hosts and services on your network. These are called modules and can be loaded by the various Shinken daemons involved in data acquisition (Poller daemons, Receiver daemons, Arbiter Daemon) Shinken also relies on external programs (called plugins) to do monitor a very wide variety of devices, applications and networked services.

What Are Plugins?¶

Plugins are compiled executables or scripts (Perl scripts, shell scripts, etc.) that can be run from a command line to check the status or a host or service. Shinken uses the results from plugins to determine the current status of hosts and services on your network.

Shinken will execute a plugin whenever there is a need to check the status of a service or host. The plugin does something (notice the very general term) to perform the check and then simply returns the results to Shinken. It will process the results that it receives from the plugin and take any necessary actions (running event handlers, sending out notifications, etc).

Shinken integrated data acquisition modules¶

These replace traditional unscalable plugins with high performance variants that are more tightly coupled with Shinken.

• The Shinken architecture describes how to fit with the Shinken daemons
• The Shinken NRPE module configuration page describes how it works and its configuration

Integrated Shinken data acquisition modules support the following protocols:

• NRPE
• SNMP

Plugins As An Abstraction Layer¶

DEPRECATED IMAGE - TODO Replace with Shinken specific.

Plugins act as an abstraction layer between the monitoring logic present in the Shinken daemon and the actual services and hosts that are being monitored.

The upside of this type of plugin architecture is that you can monitor just about anything you can think of. If you can automate the process of checking something, you can monitor it with Shinken. There are already a lot of plugins that have been created in order to monitor basic resources such as processor load, disk usage, ping rates, etc. If you want to monitor something else, take a look at the documentation on writing plugins and roll your own. Its simple!

The downside to this type of plugin architecture is the fact that Shinken has absolutely no idea what it is that you’re monitoring. You could be monitoring network traffic statistics, data error rates, room temperate, CPU voltage, fan speed, processor load, disk space, or the ability of your super-fantastic toaster to properly brown your bread in the morning... Shinken doesn’t understand the specifics of what’s being monitored - it just tracks changes in the state of those resources. Only the plugins themselves know exactly what they’re monitoring and how to perform the actual checks.

What Plugins Are Available?¶

There are plugins currently available to monitor many different kinds of devices and services, including:

• “HTTP”, “POP3”, “IMAP”, “FTP”, “SSH”, “DHCP”
• CPU Load, Disk Usage, Memory Usage, Current Users
• Unix/Linux, Windows, and Netware Servers
• Routers and Switches
• etc.

Obtaining Plugins¶

Shinken also organizes monitoring configuration packages. These are pre-built for fast no nonsense deployments. They include the check command definitions, service templates, host templates, discovery rules and integration hooks to the Community web site. The integration with the community web site permits for deployment and updates of monitoring packs.

Get started with Shinken Monitoring Packages “Packs” today.

The plugins themseles are not distributed with Shinken, but you can download the official Nagios plugins and many additional plugins created and maintained by Nagios users from the following locations:

• Nagios Plugins Project: http://nagiosplug.sourceforge.net/
• Nagios Downloads Page: http://www.nagios.org/download/
• NagiosExchange.org: http://www.nagiosexchange.org/

How Do I Use Plugin X?¶

Most all plugins will display basic usage information when you execute them using “-h” or “–help” on the command line. For example, if you want to know how the check_http plugin works or what options it accepts, you should try executing the following command:

./check_http --help

Plugin API¶

You can find information on the technical aspects of plugins, as well as how to go about creating your own custom plugins here.

Macros¶

One of the main features that make Shinken so flexible is the ability to use macros in command defintions. Macros allow you to reference information from hosts, services, and other sources in your commands.

Macro Substitution - How Macros Work¶

Before Shinken executes a command, it will replace any macros it finds in the command definition with their corresponding values. This macro substitution occurs for all types of commands that Shinken executes - host and service checks, notifications, event handlers, etc.

Certain macros may themselves contain other macros. These include the “$HOSTNOTES$”, “$HOSTNOTESURL$”, “$HOSTACTIONURL$”, “$SERVICENOTES$”, “$SERVICENOTESURL$”, and “$SERVICEACTIONURL$” macros.

Example 1: Host Address Macro¶

When you use host and service macros in command definitions, they refer to values for the host or service for which the command is being run. Let’s try an example. Assuming we are using a host definition and a check_ping command defined like this:

define host{
  host_name    linuxbox
  address    192.168.1.2
  check_command    check_ping
  ...
}

define command{
  command_name    check_ping
  command_line    /usr/local/shinken/libexec/check_ping -H $HOSTADDRESS$ -w 100.0,90% -c 200.0,60%
}

the expanded/final command line to be executed for the host’s check command would look like this:

/usr/local/shinken/libexec/check_ping -H 192.168.1.2 -w 100.0,90% -c 200.0,60%

Pretty simple, right? The beauty in this is that you can use a single command definition to check an unlimited number of hosts. Each host can be checked with the same command definition because each host’s address is automatically substituted in the command line before execution.

Example 2: Command Argument Macros¶

You can pass arguments to commands as well, which is quite handy if you’d like to keep your command definitions rather generic. Arguments are specified in the object (i.e. host or service) definition, by separating them from the command name with exclamation points (!) like so:

define service{
  host_name    linuxbox
  service_description    PING
  check_command    check_ping!200.0,80%!400.0,40%
  ...
}

In the example above, the service check command has two arguments (which can be referenced with $ARGn$ macros). The $ARG1$ macro will be “200.0,80%” and “$ARG2$” will be “400.0,40%” (both without quotes). Assuming we are using the host definition given earlier and a check_ping command defined like this:

define command{
  command_name    check_ping
  command_line    /usr/local/shinken/libexec/check_ping -H $HOSTADDRESS$ -w $ARG1$ -c $ARG2$
}

the expanded/final command line to be executed for the service’s check command would look like this:

/usr/local/shinken/libexec/check_ping -H 192.168.1.2 -w 200.0,80% -c 400.0,40%

If you need to pass bang (!) characters in your command arguments, you can do so by escaping them with a backslash (). If you need to include backslashes in your command arguments, they should also be escaped with a backslash.

On-Demand Macros¶

Normally when you use host and service macros in command definitions, they refer to values for the host or service for which the command is being run. For instance, if a host check command is being executed for a host named “linuxbox”, all the standard host macros will refer to values for that host (“linuxbox”).

If you would like to reference values for another host or service in a command (for which the command is not being run), you can use what are called “on-demand” macros. On-demand macros look like normal macros, except for the fact that they contain an identifier for the host or service from which they should get their value. Here’s the basic format for on-demand macros:

• “$HOSTMACRONAME:host_name$”
• “$SERVICEMACRONAME:host_name:service_description$”

Replace “HOSTMACRONAME” and “SERVICEMACRONAME” with the name of one of the standard host of service macros found here.

Note that the macro name is separated from the host or service identifier by a colon (:). For on-demand service macros, the service identifier consists of both a host name and a service description - these are separated by a colon (:) as well.

On-demand service macros can contain an empty host name field. In this case the name of the host associated with the service will automatically be used.

Examples of on-demand host and service macros follow:

“$HOSTDOWNTIME:myhost$ <— On-demand host macro”

“$SERVICESTATEID:novellserver:DS Database$ <— On-demand service macro”

“$SERVICESTATEID::CPU Load$ <— On-demand service macro with blank host name field”

On-demand macros are also available for hostgroup, servicegroup, contact, and contactgroup macros. For example:

“$CONTACTEMAIL:john$ <— On-demand contact macro”

“$CONTACTGROUPMEMBERS:linux-admins$ <— On-demand contactgroup macro”

“$HOSTGROUPALIAS:linux-servers$ <— On-demand hostgroup macro”

“$SERVICEGROUPALIAS:DNS-Cluster$ <— On-demand servicegroup macro”

On-Demand Group Macros¶

You can obtain the values of a macro across all contacts, hosts, or services in a specific group by using a special format for your on-demand macro declaration. You do this by referencing a specific host group, service group, or contact group name in an on-demand macro, like so:

• “$HOSTMACRONAME:hostgroup_name:delimiter$”
• “$SERVICEMACRONAME:servicegroup_name:delimiter$”
• “$CONTACTMACRONAME:contactgroup_name:delimiter$”

Replace “HOSTMACRONAME”, “SERVICEMACRONAME”, and “CONTACTMACRONAME” with the name of one of the standard host, service, or contact macros found here. The delimiter you specify is used to separate macro values for each group member.

For example, the following macro will return a comma-separated list of host state ids for hosts that are members of the hg1 hostgroup:

"$HOSTSTATEID:hg1:,$"

This macro definition will return something that looks like this:

"0,2,1,1,0,0,2"

Custom Variable Macros¶

Any custom object variables that you define in host, service, or contact definitions are also available as macros. Custom variable macros are named as follows:

• “$_HOSTvarname$”
• “$_SERVICEvarname$”
• “$_CONTACTvarname$”

Take the following host definition with a custom variable called “”_MACADDRESS””...

define host{
  host_name    linuxbox
  address    192.168.1.1
  _MACADDRESS    00:01:02:03:04:05
  ...
}

The “_MACADDRESS” custom variable would be available in a macro called “$_HOSTMACADDRESS$”. More information on custom object variables and how they can be used in macros can be found here.

Macro Cleansing¶

Some macros are stripped of potentially dangerous shell metacharacters before being substituted into commands to be executed. Which characters are stripped from the macros depends on the setting of the illegal_macro_output_chars directive. The following macros are stripped of potentially dangerous characters:

• $HOSTOUTPUT$
• $LONGHOSTOUTPUT$
• $HOSTPERFDATA$
• $HOSTACKAUTHOR$
• $HOSTACKCOMMENT$
• $SERVICEOUTPUT$
• $LONGSERVICEOUTPUT$
• $SERVICEPERFDATA$
• $SERVICEACKAUTHOR$
• $SERVICEACKCOMMENT$

Macros as Environment Variables¶

Most macros are made available as environment variables for easy reference by scripts or commands that are executed by Shinken. For purposes of security and sanity, $USERn$ and “on-demand” host and service macros are not made available as environment variables.

Environment variables that contain standard macros are named the same as their corresponding macro names (listed here), with “NAGIOS_” prepended to their names. For example, the $HOSTNAME$ macro would be available as an environment variable named “NAGIOS_HOSTNAME”.

Available Macros¶

A list of all the macros that are available in Shinken, as well as a chart of when they can be used, can be found here.

Macro Validity¶

Although macros can be used in all commands you define, not all macros may be “valid” in a particular type of command. For example, some macros may only be valid during service notification commands, whereas other may only be valid during host check commands. There are ten types of commands that Nagios recognizes and treats differently. They are as follows:

• Service checks
• Service notifications
• Host checks
• Host notifications
• Service event handlers and/or a global service event handler
• Host event handlers and/or a global host event handler
• OCSP command
• OCHP command
• Service performance data commands
• Host performance data commands

The tables below list all macros currently available in Shinken, along with a brief description of each and the types of commands in which they are valid. If a macro is used in a command in which it is invalid, it is replaced with an empty string. It should be noted that macros consist of all uppercase characters and are enclosed in $ characters.

Macro Availability Chart¶

Legend:

Macro Descriptions¶