Icinga Version 1.9 Documentation Icinga Version 1.9 Documentation Next Icinga Version 1.9 Documentation Copyright 2009-2013 Icinga Development Team. Portions copyright © by Nagios/Icinga community members - see the THANKS file in the Icinga core sources for more information.. Credits to Yoann LAMY for creating the Vautour Style we use for the Icinga Classic UI Icinga 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 Icinga under certain conditions. Read the ’LICENSE’ file in the Icinga distribution or read the online version of the license for more details. Icinga is provided “AS IS” with “NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.” Nagios 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 Nagios under certain conditions. Read the ’LICENSE’ file in the Nagios distribution or read the online version of the license for more details. Nagios and the Nagios logo are registered trademarks of Ethan Galstad. All other trademarks, servicemarks, registered trademarks, and registered servicemarks mentioned herein may be the property of their respective owner(s). The information contained herein is provided “AS IS” with “NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.” 2013.05.07 1 Icinga Version 1.9 Documentation Revision History Revision 1.9 2013-04-25 1.9 Icinga Documentation Revision 1.x 2010-2012 1.x Icinga Documentation Revision 0.1 2009-08-12 First Release Table of Contents 1. About About Icinga What is Icinga? System requirements Licensing Acknowledgements Downloading The Latest Version Compatibility What’s New in Icinga 1.9 CHANGES Core Classic UI IDOutils Icinga-Web Icinga-Reporting Docs More information 2. Getting Started Advice for beginners Icinga Overview Icinga web GUI comparison Quickstart Installation Guides Icinga Quickstart Introduction Prerequisites Install packages Create Account Information Download Icinga and the Plugins Compile and install Icinga Customise Configuration Configure the Classic Web Interface Compile and Install the Nagios Plugins Adjusting the SELinux settings Start Icinga Login to the Classic Web Interface Other Modifications You’re Done Icinga Quickstart FreeBSD 2 Icinga Version 1.9 Documentation Icinga with IDOUtils Quickstart Introduction Prerequisites New features for the IDOUtils: Install Packages Create Account Information Download Icinga and the Plugins Compile and Install Icinga with IDOUtils Compile and Install Customise Configuration Enable the idomod event broker module Creation of Database and IDOUtils Configure the Classic Web Interface Compile and Install the Nagios Plugins Adjusting the SELinux settings Start IDOUtils and Icinga Configure Icinga Startup Login to the Classic Web Interface Other Modifications You’re Done Icinga and IDOUtils Quickstart on FreeBSD Icinga Packages for Linux Distributions Links to other published Howtos Upgrading (to) Icinga Upgrading from previous Icinga Releases Upgrading from Nagios 3.x Releases Upgrading from Nagios 2.x Releases Upgrading from an RPM Installation Upgrading IDOUtils Database Upgrading IDOUtils to 1.9 Upgrading IDOUtils to 1.8 Upgrading IDOUtils to 1.7 Upgrading IDOUtils to 1.5 Upgrading IDOUtils to 1.4 Upgrading IDOUtils to 1.3 Upgrading IDOUtils to 1.0.3 Upgrading IDOUtils to 1.0.2 Upgrading IDOUtils to 1.0.1 Upgrading IDOUtils to 1.0 Monitoring Overview Monitoring Windows Machines Introduction Overview Steps What’s Already Done For You Prerequisites Installing the Windows Agent Configuring Icinga Password Protection Restarting Icinga Troubleshooting Monitoring Linux/Unix Machines Introduction 3 Icinga Version 1.9 Documentation Overview Monitoring Netware Servers Monitoring Network Printers Introduction Overview Steps What’s Already Done For You Prerequisites Configuring Icinga Restarting Icinga Monitoring Routers and Switches Introduction Overview Steps What’s Already Done For You Prerequisites Configuring Icinga Restarting Icinga Monitoring Publicly Available Services Introduction Plugins for Monitoring Services Creating a Host Definition Creating Service Definitions Restarting Icinga 3. Configuring Icinga Configuration Overview Introduction File names Main Configuration File Resource File(s) Object Definition Files CGI Configuration File Main Configuration File Options Object Configuration Overview Object Definitions Host definition Hostgroup Definition Service Definition Servicegroup Definition Contact Definition Contactgroup Definition Timeperiod Definition Command Definition Servicedependency Definition Serviceescalation Definition Hostdependency Definition Hostescalation Definition Hostextinfo Definition Serviceextinfo Definition Module Definition Custom Object Variables Introduction Custom Variable Basics 4 Icinga Version 1.9 Documentation Examples Custom Variables As Macros Custom Variables And Inheritance CGI Configuration File Options Authentication And Authorization In The CGIs Introduction Definitions Setting Up Authenticated Users Enabling Authentication/Authorization Functionality In The CGIs Default Permissions To CGI Information Granting Additional Permissions To CGI Information CGI Authorization Requirements Authentication On Secured Web Servers 4. Running Icinga Verifying Your Configuration Starting and Stopping Icinga 5. The Basics Icinga Plugins Introduction What Are Plugins? Plugins As An Abstraction Layer What Plugins Are Available? Obtaining Plugins Switch to the Icinga user Extending the environment How Do I Use Plugin X? Integrating a new plugin Raw command line Threshold and ranges Activating the definition Plugin API Understanding Macros and How They Work Macros Macro Substitution - How Macros Work Example 1: Host Address Macro Example 2: Command Argument Macros On-Demand Macros On-Demand Group Macros Custom Variable Macros Macro Cleaning Macros as Environment Variables Available Macros Standard Macros in Icinga Macro Validity Macro Availability Chart Host Checks Introduction When Are Host Checks Performed? Cached Host Checks Dependencies and Checks Parallelization of Host Checks Host States Host State Determination 5 Icinga Version 1.9 Documentation Host State Changes Service Checks Introduction When Are Service Checks Performed? Cached Service Checks Dependencies and Checks Parallelization of Service Checks Service States Service State Determination Services State Changes Active Checks Introduction How Are Active Checks Performed? When Are Active Checks Executed? Passive Checks Introduction Uses For Passive Checks How Passive Checks Work Enabling Passive Checks Submitting Passive Service Check Results Submitting Passive Host Check Results Passive Checks and Host States Submitting Passive Check Results From Remote Hosts State Types Introduction Service and Host Check Retries Soft States Hard States Example Time Periods Introduction Precedence in Time Periods How Time Periods Work With Host and Service Checks How Time Periods Work With Contact Notifications How Time Periods Work With Notification Escalations How Time Periods Work With Dependencies Determining Status and Reachability of Network Hosts Introduction Example Network Defining Parent/Child Relationships Reachability Logic in Action UNREACHABLE States and Notifications Notifications Introduction When Do Notifications Occur? Who Gets Notified? What Filters Must Be Passed In Order For Notifications To Be Sent? Program-Wide Filter: Service and Host Filters: Contact Filters: Notification Methods Notification Type Macro Helpful Resources 6 Icinga Version 1.9 Documentation Notifications: Examples and troubleshooting Introduction Some examples Troubleshooting 6. User Interfaces Icinga Classic UI: Information On The CGIs Information On CGI parameters Introduction Executing CGIs on the command line Properties / Statustypes Matrix Parameters / CGIs Executing CGIs on the command line Introduction Prerequisites Examples Installation of the Icinga-Web Frontend Introduction Prerequisites The installation Settings Use It! Test & Errors? Upgrading Icinga-Web and Icinga-Web Database Upgrading Icinga-Web The Upgrade Upgrading the Icinga-Web Database Configuration Overview of Icinga-Web Where are my config files? Index Global Configuration Section Troubleshooting Module Configuration Customised Configuration Introduction to Icinga-Web Introduction to Icinga-Web (>= 1.9) Integration of PNP4Nagios into Icinga-Web Install PNP4Nagios Templates Extension Create a configuration to include PNP4Nagios host pages in Icinga-Web Create a configuration to include pnp4nagios service pages in icinga-web Clearing the cache 7. Advanced Topics External Commands Introduction Enabling External Commands When Does Icinga Check For External Commands? Using External Commands Command Format External Commands List List of External Commands Event Handlers Introduction When Are Event Handlers Executed? 7 Icinga Version 1.9 Documentation Event Handler Types Enabling Event Handlers Event Handler Execution Order Writing Event Handler Commands Permissions For Event Handler Commands Service Event Handler Example Volatile Services Introduction What Are They Useful For? What’s So Special About Volatile Services? The Power Of Two Icinga Configuration: PortSentry Configuration: Port Scan Script: Service