Step 1: Prerequisites

• Python 3: The script uses Python, so make sure you have it installed so you can test your plugin as you develop it. It can be downloaded here.
• A code editor: To create this plugin I used VS Code, which can be downloaded here.

Step 2: Set Up the Python Script

Create a new Python file named check_route_hops.py and begin with a shebang line and essential import statements.

#!/usr/bin/env python3

import sys
import traceback
import argparse
import subprocess

def main():

if __name__ == "__main__":
    main()

Define the Nagios status codes to make the code more readable.

OK = 0
WARNING = 1
CRITICAL = 2
UNKNOWN = 3

Now, create a global variable for the command line arguments.

_args = None

Step 3: Parse Command-Line Arguments

The plugin should accept arguments to specify the target host, thresholds, and other options. Use Python’s argparse module to define and handle these arguments. This code should be placed within the main function.

parser = argparse.ArgumentParser(
 description='This script checks the number of hops to a target host using traceroute.'
 'You can define warning and critical thresholds for hop counts. '
 'If the host is unreachable with the default protocol (UDP) other protocols will be       tried.')
        
        # Define the arguments
        parser.add_argument('-H', '--host', required=True, type=str, help='Target host IP to check hop count')

        parser.add_argument('-t', '--timeout', default=3, type=int, help='Timeout duration in seconds for the check (default is 3)')

        parser.add_argument('-w', '--warning', required=False, type=int, help='Warning threshold for hop count')

        parser.add_argument('-c', '--critical', required=False, type=int, help='Critical threshold for hop count')

        parser.add_argument('-v', '--verbose', required=False, type=int, default=0, help=(
            'The verbosity level of the output. '
            '(0: Single line summary, '
            '1: Single line with additional information, '
            '2: Multi line with configuration debug output)'
        ))

        parser.add_argument('-p', '--protocol', type=str, default='UDP', help='First protocol to attempt for traceroute (default: UDP)')

        parser.add_argument('--debug', action='store_true', help='Enable debug mode')
        
        _args = parser.parse_args(sys.argv[1:])

Step 4: Implement the Traceroute Logic

Create a helper function to execute traceroute and calculate the number of hops to the host. Use subprocess.run to call the traceroute command. The stdout result of the command is then used to count the number of hops to the host. Different protocols are used by adding additional arguments to the command.

def get_route_hops(protocol):
    global _args

    try:
        result = None
        if protocol == "UDP":
            result = subprocess.run(['traceroute', _args.host], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=_args.timeout)
        elif protocol == "ICMP":
            result = subprocess.run(['traceroute', _args.host, '-I'], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=_args.timeout)
        
        # Count the number of hops (lines returned by traceroute)
        hops = len(result.stdout.splitlines()) - 1

        return hops if hops > 0 else 0

    except subprocess.TimeoutExpired:
        return 0
    except Exception as e:
        return 0

def get_route_hops(protocol):
    global _args

    try:
        result = None
        if protocol == "UDP":
            result = subprocess.run(['traceroute', _args.host], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=_args.timeout)
        elif protocol == "ICMP":
            result = subprocess.run(['traceroute', _args.host, '-I'], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=_args.timeout)
        
        # Count the number of hops (lines returned by traceroute)
        hops = len(result.stdout.splitlines()) - 1

        return hops if hops > 0 else 0

    except subprocess.TimeoutExpired:
        return 0
    except Exception as e:
        return 0

Step 5: Combine Logic in the Main Function

The main function shall do the following:

1. Parse arguments.
2. Attempt traceroute on the specified protocol.
3. Fallback to alternative protocols if the specified protocol fails.
4. Compare the hop counts against the thresholds.
5. Build and print a Nagios status message.
6. Exit with the proper status code.

For testing, you can add debug statements that print out additional information if the –debug argument exists.

    # Find the number of hops to the host using different protocols    
    protocols = ['UDP', 'ICMP']    
    if _args.protocol in protocols:        
      protocols.remove(_args.protocol)       
      protocols.insert(0, _args.protocol)   
      
      hops = 0   
      used_protocol = _args.protocol  
      
      # Check the default protocol first   
      hops = get_route_hops(_args.protocol)  
      
      # If the default protocol fails, try the other protocols   
      if hops == 0:     
      for protocol in protocols[1:]:        
        hops = get_route_hops(protocol)
             
        if hops > 0:            
          used_protocol = protocol             
          break
        if hops == 0:       
          print("CRITICAL - Failed to determine hop count for all protocols")            
          sys.exit(CRITICAL)  
            
        # Set the status code based on the number of hops to the host    
        status_code = OK   
        if _args.warning and hops >= _args.warning:       
          status_code = WARNING   
        if _args.critical and hops >= _args.critical:       
          status_code = CRITICAL
          status_dict = {      
            0: "OK",       
            1: "WARNING",      
            2: "CRITICAL",   
          }
         
        # Build the status message   
        message = ''   
        if (hops == 1):      
          message = f"{status_dict[status_code]} - {hops} hop was counted to {_args.host}" 
        else:       
        message = f"{status_dict[status_code]} - {hops} hops were counted to {_args.host}"
         
        print(message)    
        sys.exit(status_code)

    # Find the number of hops to the host using different protocols    
    protocols = ['UDP', 'ICMP']    
    if _args.protocol in protocols:        
      protocols.remove(_args.protocol)       
      protocols.insert(0, _args.protocol)   
      
      hops = 0   
      used_protocol = _args.protocol  
      
      # Check the default protocol first   
      hops = get_route_hops(_args.protocol)  
      
      # If the default protocol fails, try the other protocols   
      if hops == 0:     
      for protocol in protocols[1:]:        
        hops = get_route_hops(protocol)
             
        if hops > 0:            
          used_protocol = protocol             
          break
        if hops == 0:       
          print("CRITICAL - Failed to determine hop count for all protocols")            
          sys.exit(CRITICAL)  
            
        # Set the status code based on the number of hops to the host    
        status_code = OK   
        if _args.warning and hops >= _args.warning:       
          status_code = WARNING   
        if _args.critical and hops >= _args.critical:       
          status_code = CRITICAL
          status_dict = {      
            0: "OK",       
            1: "WARNING",      
            2: "CRITICAL",   
          }
         
        # Build the status message   
        message = ''   
        if (hops == 1):      
          message = f"{status_dict[status_code]} - {hops} hop was counted to {_args.host}" 
        else:       
        message = f"{status_dict[status_code]} - {hops} hops were counted to {_args.host}"
         
        print(message)    
        sys.exit(status_code)

Step 6: Test the Plugin

Run your script manually to verify that your plugin functions as expected. Try different combinations of arguments to ensure everything functions as expected.

Here is an example of what you could run in your terminal:

python3 check_route_hops.py -H example.com -w 10 -c 20 -p ICMP --debug

Step 7: Upload your plugin to Nagios XI

Follow the steps here to add your new plugin to Nagios XI!

Video

Conclusion

You’ve successfully created a custom Nagios plugin to monitor route hops. This plugin is highly customizable, allowing you to modify thresholds and protocols as needed. It’s a solid tool for monitoring network paths and troubleshooting connectivity issues.

Nagios Documentation & Guides

➤ We recently revamped all of our documentation, providing you with accurate, easy-to-understand instructions and helpful tips for using Nagios. These Nagios docs will guide you through the basics, help you get started, and support you in learning more about Nagios tools.

Nagios Documentation

A new comprehensive documentation site replacing the legacy Support Knowledgebase. Here, you’ll find guides for commercial solutions and open-source projects with step-by-step tutorials, technical documentation, and best practices.

Nagios Library

Library is a central place for detailed Nagios training docs, how-to guides, articles on the latest industry insights, and real-life stories about using Nagios:

Admin Guides

Looking for step-by-step instructions? These guides walk you through installation, configuration, and advanced setup:

Nagios Support Options

➤ Support options are designed to provide both quick answers and in-depth assistance. Nagios offers these resources with every license.

Nagios Customer Success Managers

If you have a Nagios license, you can contact a Nagios Customer Success Manager (CSM). CSMs can help with a wide variety of Nagios-related information. They can help answer basic questions about Nagios, get you in contact with the right support, as well as help you renew or buy a new license.

To contact a Nagios CSM, email csm@nagios.com.

Nagios Support Plans

Guaranteed one-business-day response from Nagios Technicians for support tickets (up to 10 per year), with the option to purchase additional support plans as needed:

Nagios Answer Hub

Find answers to frequently asked questions and product-specific help:

Nagios Support Website

The Nagios Support makes it easy to find what you need, with quick access to the Knowledge Base, Library, Support Forum, and product-specific resource pages:

Nagios Video Resources

➤ Prefer to learn visually? Our video resources walk through installation, setup, Nagios training, and more.

Nagios YouTube Channel

Explore our video tutorials, product demos, and best practices all in one place:

Nagios Webinars

Want deeper insights? Nagios Webinars offer regular sessions covering best practices, use cases, and expert tips:

Nagios Community Resources

➤ Access years of collective experience, along with support options and answers to common questions.

Nagios Support Forum

The Nagios Support Forum is an ideal place to get quick answers to “how-to” questions. Ask questions, find answers, and contribute to active discussions:

Nagios Exchange

Browse thousands of community-created plugins, add-ons, and integrations, or share your own projects with the Nagios Community.

Where to Go Next

➤ If you’re still looking for more resources, Nagios offers free one-on-one sessions with a Nagios Technician—plus free trials to help you get started.

Personalized Demo

See Nagios in action, explore key features, and discover how Nagios fits your infrastructure:

Download a Free Trial

Get a free, 30-day trial of any Nagios Enterprise Solution to try it out yourself:

Quickstart Session

Get your instance up and running, discuss your environment, and receive tailored configuration help:

There’s no single way to get started with Nagios. Some like to dig into the documentation, while others prefer more hands-on Nagios training, such as a product walkthrough or demo. However you like to learn, there’s a resource to match your style.

Have Questions? Reach Out to Us

Reach out anytime to sales@nagios.com if you have questions or need support. We’re here to help you get the most out of Nagios.

Helpful Extras to Check Out

Nagios’ Social Media

Get the latest updates and stay in the loop:

Introduction

In the first article in this series, I introduced the concept of hostgroup inheritance and (hopefully) laid it out in a way that it can be well understood. In this article, I’m going to start walking you through setting up a solid hostgroup inheritance foundation.

By the end of this article, you should have a functional hostgroup inheritance setup; however, I do not recommend running through these steps in your production environment. There will be future articles where we will expand on the functionality laid out here.

With that said, if you are running Nagios XI, you are allowed three instances of Nagios XI: Production, Test, and Disaster Recovery. This would be a good opportunity to fire up that “Test” instance of Nagios XI.

Begin by Beginning

For this first example, we’re going to setup hostgroup inheritance with a fresh install of Nagios XI. Once we’re done with this, you should have a good idea of how to retro fit an existing XI instance.

We’ll start this off by running a Configuration Wizard against a host that you want to monitor. The host that you want to monitor will, presumably, be one of a large number of similar hosts. In our example, we’ll use a basic Windows host being monitored using NCPA.

Now I don’t want to walk you through running the NCPA Wizard to monitor your Windows host. I’ll leave that as an exercise to you. The end result is that in the Core Configuration Manager (CCM), you now have a host with multiple services being monitored. If you go to the Services section of the CCM and display the config for the Windows machine you are monitoring, you should see something similar to this:

Changing a Single Service Check

You can see we’ve got CPU, disk, bandwidth, memory, and a service that we’re monitoring on this Windows box. Now we know that for all of our servers, whether Windows or Linux (or AIX, or Solaris, or FreeBSD, etc.), we want to monitor CPU and memory usage. Why create that over and over again? Why not just have that in some kind of template that can be applied to each server as you add it?

That’s what we’re going to do here. Before we modify that service, let’s create a hostgroup that will hold service checks for any OS. Click on Monitoring -> Host Groups -> Add New. Now for the Host Group Name and Alias fields, I like to keep this brief, yet descriptive. For this one I’m going to call it ncpa-anyos. Meaning the system is monitored using NCPA, and the service checks apply to any operating system. Click save.

Now go back to Monitoring -> Services and open up the CPU Usage service check definition (or whatever service you want to make available via hostgroup inheritance) and let’s convert it.

The first field we want to change is the Config Name field. In Nagios XI, this field typically lines up with the name or IP of the host it is tied to. But it doesn’t have to be that way. Let’s create a new config name by changing this to AnyOS. Meaning the service checks in this config will apply to any operating system.

Next, click the Manage Hosts button and remove the assigned host. And finally, click the Manage Host Groups button, and add the service check to the ncpa-anyos hostgroup. Realistically, that’s it. Now any host that you put in the ncpa-anyos hostgroup will have that CPU Usage service check. Go ahead and add a host to the ncpa-anyos hostgroup, apply the configuration, and check your host status screen.

Limitations

There are some immediate limitations with this setup as it is right now. We’ll dive into the fixes for them in my next article for this series. For now, I just want to call out one in particular.

Not all of your hosts will have the same CPU warning and/or critical thresholds. Or maybe they have different NCPA tokens. For those of you who don’t want to wait for the next article, I’ll point you in the right direction. In the next article, we’ll touch on using custom host variables and host templates to deal with the limitation of needing to customize different pieces of a service check. We’ll also be touching on creating a new command.

Additional Reading for Overachievers

Nagios Custom Macros.

Managing Plugins in Nagios XI 2024. Specifically, we will be looking at the Define A Command section of this document.

And since we’ll be talking about host and service templates, it might be good to brush up on Object Inheritance.

1. Using the Report

To access the report, navigate to the Reports menu, then select Capacity Planning. Next, select the Period (how far into the future you want to project), and select the specific Host, Hostgroup, or Servicegroup to graph the results for.

Once you make all of your customization selections, you can then save, email, export, and even (another great Enterprise Edition feature) schedule the report for automatic delivery at set times.

Alternately, you can navigate to the Status Detail page for a service and go to the Capacity Planning tab to view projections.

The options tabs to the right of the initial graph provide access to a data Summary, all of the individual data points, and the option to customize your Time Period and Extrapolation Method.

2. Adding Graphs to Dashboards

You’ll notice the Dashify icon on the upper left of each Capacity Planning graph, which you can click to easily add them to your Dashboards. This provides an easy way to quickly access at-a-glance projections for key services in your environment and to roll them into other Dashboards you’ve created.

3. Using the Wizard

It’s even possible to set up alerts on projections using the Capacity Planning Wizard, found in the Configure > Configuration Wizards menu. In Step 1 you’ll choose which service to monitor. Then in Step 2 you’ll choose how far ahead the check should look, what algorithm it should use, the projected value at which you want to be alerted, and how many days in advance of the resource hitting the custom value you wish to be alerted.

You can choose to either add the newly created services to the host under which the services producing the performance data reside or check the “Put all new services on a specific host” checkbox to assign them elsewhere (for example, to a dummy host reserved just for capacity planning checks).

You can click the Render Graph link at the bottom of the wizard to see a graph of current and projected data and to see where your Custom Value selection falls within it.

Once the checks are created, you can monitor them like any other service or even roll them into your Business Process Intelligence groups:

Resources

For a more detailed overview of using Capacity Planning, take a look at this guide:

How to Use Capacity Planning in Nagios XI

If you’d like a tour of all of the Enterprise Edition features, this article provides a comprehensive overview:

10 Great Features of the Nagios XI Enterprise Edition

If you’d like to try Capacity Planning out for yourself, we offer a free trial version you can take for a spin:

Nagios XI Free Trial Download

We’d also be happy to offer you a custom Demo session if want a guided tour of our solutions, or a free Quickstart remote session with a sales engineer to help you get a few things set up. You can email sales@nagios.com for details on setting up either option.

This is especially important if you have an extensive environment or large team where different users and groups manage specific segments. You may wish to have everything from read-only viewers to full access superadmins accessing the Nagios user interfaces (UIs), with varying degrees in-between.

In this article we’ll take a look at the multi-tenancy options available in each Nagios solution.

Nagios XI Multi-tenancy

XI provides the most robust multi-tenancy capabilities of the entire Nagios suite. What each user you create can see and do in the user interface is deeply customizable. By default, the visibility and object control granted to regular users will be limited to those hosts and services they are a Contact on, but you can also check a box in the Security Settings section to allow them to see all hosts and services. You also decide which Users have access to the REST API, auto-deployment, and the Core Config Manager, and can click a single box to make any User read-only.

To create and edit Users in Nagios XI, navigate to Admin > Manage Users.

Nagios XI Dashboards

Dashboards in XI can be deployed to other users easily in the Dashboards > Deploy Dashboards menu. You can even either let the users you deploy to update their copy of the Dashboard as they see fit or choose to keep it synced with changes you make.

Nagios Core

Nagios Core is the open source monitoring engine used by Nagios XI. Although all configuration is done from the Linux command line, it does provide a basic web display which shows status information and a includes a few options for interacting with the monitoring engine. Object visibility in the Core interface can be limited based on what hosts and services users are contacts on, as can their ability to send commands to the Core daemon.

Nagios Fusion Multi-tenancy

In Nagios Fusion, users you create can either be a User or an Administrator. If you check the Administrator box in General Settings for a user, they will be able to see and access the Admin menu and all of its functions:

Fusion also provides the ability to determine which of the fused servers you’re collecting data from each user should be able to see in the Server User Mapping section of their user settings. In the case of fused Nagios XI servers, you can also map your Fusion users to XI users so that within the Fusion UI, and when they click through to the XI UIs, the objects they can see will be tied to their XI user.

Your favorite Dashboards in Fusion can also be deployed to other users just like in Nagios XI.

To manage Fusion users, navigate to Admin Admin > Manage Users.

Nagios Log Server Multi-tenancy

In Nagios Log Server, you have the ability to control both which log sources users can see data from, and which menus and functions they can access. Admin level users can modify and delete across all components and settings, while User level users are limited to editing only their account and personal dashboards, unless other User Permissions are granted using the checkboxes in the Admin > User Management > Create/Edit User menu, in the Permissions tab.

You can also restrict visibility of source log data to Host Lists (groups of sources you create), or individual sources, as well as determining whether API access is available.

On the Dashboards front, each Dashboard users create can be saved as a personal Dashboard visible only to them, or as a Global Dashboard visible to all Log Server users.

Finally, query-based Log Server alerts can be easily integrated with Nagios XI for additional control of user visibility.

Nagios Network Analyzer Multi-tenancy

In Network Analyzer, all users have full visibility of the entirety of Source data, but you determine whether they are a full access Admin, or a regular User which hides the configuration options and limits what they can edit. You also determine whether each regular user has API access:

You can also integrate Network Analyzer alerts with Nagios XI if you’re using both solutions, and limit access in the XI UI to only certain source alerts to control visibility.

Navigate to the Administration > User Management menu to create and edit Network Analyzer users.

Resources

• Understanding User Rights in Nagios XI

• Authentication and Authorization in the Nagios Core CGIs

• Managing Nagios Fusion Users

• Managing Nagios Log Server Users

• Managing Network Analyzer Users

If you’d like to take any or all of the Nagios tools for a spin, you can find free trial download links here:

Nagios Solutions

Also feel free to contact us at sales@nagios.com if there are any questions we can assist you with, or if you’d like a custom Demo or Quickstart remote session to help you explore Nagios further.

Nagios XI Check Architecture

Nagios XI can monitor both actively and passively, using agent-based and agentless methods. The best approach will depend on the specifics of your environment and requirements.

Agent-based vs. Agentless Checks

With agent-based methods, a lightweight agent is installed on the monitored host, which enables Nagios to connect to it and run checks. Agents provide the flexibility to monitor a wider array of metrics than agentless methods, since they are not limited strictly to data made available by a native protocol and can incorporate custom plugins. However, agents slightly increase administrative overhead, since they need to be installed and updated. A smart agent like NCPA provides even more utility by enabling Nagios XI to scan your hosts for things like drives and running services/processes, and by providing powerful additional tools like a web UI and check API.

With agentless methods, a native protocol like SNMP is leveraged to run checks. Although, as stated above, an agentless method will be limited to the specific metrics the native protocol can produce, agentless methods don’t require direct updates outside of regular software and firmware updates. Native protocols may also enable you to scan your hosts for elements that can be monitored. For example, the Network Switch and Router wizard will scan your network device for interfaces.

Active Checks

Active checks in Nagios XI are scheduled and executed by the Nagios server, so communication is outbound from Nagios to the monitored host. Examples of active checks include:

• NCPA and NRPE agent checks.
• SNMP polling (for example, checks configured using the Network Switch and Router wizard).
• Checks created with the Network Analyzer or Log Server wizards.
• Website checks (using the Website monitoring wizard).

Active checks tend to be easier to configure since they can often be set up using Nagios XI’s comprehensive suite of monitoring wizards but do require a direct inbound network path to your host.

Passive Checks

In a passive model, checks are initiated by the remote host and sent upstream to Nagios XI.

Examples of passive checks include:

• NCPA (which has both an active and passive capability) and NRDP agent checks.
• SNMP Traps.
• Nagios Network Analyzer and Nagios Log Server alerts configured in those tools (which use NRDP to send results upstream to Nagios XI).

Passive checks can be more challenging to initially configure but are useful in situations where inbound access to the monitored host network isn’t possible or desirable. Passive checks also reduce load on your Nagios XI server, enabling you to get more checks out of a single monitoring server.

Event Handlers and Actions

Event handlers are automated, scripted actions that Nagios XI can be configured to execute in response to detected state changes. Actions are manually executed using clickable icons in the UI. In both cases, Nagios executes the handler, and communication is outbound from Nagios to the target host. If the handler or action is designed to execute a script (for example, to restart a stopped service), this is often carried out by a local agent such as NCPA running on the remote host.

Nagios Mod-Gearman

Nagios Mod-Gearman (NMG) is a Nagios Event Broker (NEB) module that can be used for a variety of
purposes including load reduction, load balancing, and distributed monitoring.

Separate Linux servers running the NMG Worker module are assigned checks for the general host and
service queue, or specific hostgroups and servicegroups, which they execute locally, then forward the
results upstream to the NMG Server module running on the Nagios server. Worker communication and check result forwarding is inbound to the Nagios server from the workers, so inbound network access to the worker server from Nagios is not required for NMG itself to function.

Nagios XI 2024R2.1+ includes a Remote Workers feature that enables the NMG Server module and workers to be managed right from the web UI. The ability to deploy, and sync workers from the XI UI does require inbound network access to the workers from the Nagios XI server via SSH on port 22.

This article provides a detailed overview of NMG and links to key documentation:

Gear Up with Nagios Mod-Gearman: Maximize and Distribute Checks Efficiently

Nagios XI Application Architecture

If you’d like to learn more about the components and architecture of the Nagios XI application itself, this document provides an in-depth overview and diagram:

Nagios XI Architecture Overview

Network Analyzer

Flow data from network devices and servers running flow clients travels upstream from the devices to Network Analyzer, which acts as a collector and aggregator.

Nagios Log Server

Log data is sent upstream to Log Server by the sources you are collecting from. Data is also passed back and forth between the cluster instances by Opensearch for clustered redundancy of your collected logs. One option is to send the data directly to individual Log Server instances.

This approach works well unless the instance breaks, in which case incoming log data will have nowhere to go and will queue on the sending source until the instance recovers. As long as you’re running a multi-instance cluster, previously collected logs will still be protected, but new results won’t be collected.

A more resilient approach is to incorporate a load balancer or round robin DNS setup, so that incoming log events from the sources will always be routed to an available instance.

Nagios Fusion

Nagios Fusion polls remote Nagios XI, Nagios Core, Nagios Log Server, and Nagios Network Analyzer servers via HTTP/HTTPS. Communication is initiated by an outbound connection from Fusion to your fused Nagios servers, but since standard web ports are used it’s often easier to get approval for this architecture from network security teams.

Federated Monitoring

In a federated architecture, data is sent upstream from remote Nagios XI and Core servers to a centralized XI server. The transmission is handled by NRDP, so it is sent via HTTP/HTTPS just like regular NRDP passive checks.

The pro of this model is that it provides centralized reporting and notification management capabilities, and since the incoming results are passive, enables the centralized XI server to handle more total checks than if it were running the checks itself. However, Fusion is better suited to handle massive scale.

You can find more details about the above distributed architecture options in this document:

Nagios Monitoring Architecture Solutions For Large Organizations

Hopefully, the above overview has provided you with great directions to help you navigate the planning, execution, and cultivation of your Nagios deployment. Here are a few additional resources to help you succeed with Nagios:

How to Maximize Your Free Trial of Nagios XI

Nagios XI Enterprise Edition: 10 Great Features

Please feel free to email us at sales@nagios.com if there’s anything we can assist with!

Capable as the wizards are, they’re no match for the Core Config Manager (CCM) when it comes to managing existing objects and advanced settings. In this article, we’ll dig into the CCM and explore how it works, what it does, and how it’s used.

Accessing the CCM

To get to the Core Config Manager, go to Configure > Core Config Manager.

On the CCM main page, you’ll see an Object Summary of all the Core objects, a list of Recent Snapshots, and a left-hand menu full of options. Let’s explore some key functions and capabilities.

Making Small Changes

One of the most common tasks you’ll complete in the CCM is making granular changes to specific settings on your monitored hosts and services. We’ll cover a simple example here, and you can refer to the full guides for complete details:

Service management with the CCM

Host management with the CCM

If you wanted to make the check interval on a key service more aggressive, you’d simply click Services in the left-hand submenu, then do a quick search to locate your service:

Once you locate the service and click through, you’ll be brought to the Service Management section. Hit the Check Settings tab, update the Check Interval to your new setting, and click Save.

Applying Your Config

Once you’ve saved your change, you will be returned to the Services directory and will notice a banner at the top indicating you need to Apply Configuration:

Changes made in the Nagios XI user interface need to be written to the underlying Nagios Core monitoring engine in order to take effect. Apply Configuration verifies that your configuration changes are valid, then updates the Core configs.

Uh-oh… Something Went Wrong

If you apply the config and an error is detected, you’ll see a screen like this:

Don’t panic! Until you apply a working config, the Core engine will continue monitoring based on the last known good config, so your monitoring will continue uninterrupted.

In this example, we can see that our service is missing a service description. If we navigate to the Apache-Weblogger services, we can quickly spot the problem, which shows red ‘Not Applied’ text in the Status column:

Simply update the settings (in this case by adding a Service Description) and Apply Configuration again to write the changes.

Also note that each time you Apply Configuration, a snapshot is taken. These can be viewed in the Quick Tools > Configuration Snapshots section of the CCM. You can roll back to previous configurations anytime by clicking the circular arrow icon in the Actions column.

You can also review exactly what was changed by clicking the View diff button in the Diff Changes column for an entry:

Managing Groups

The CCM is also where you’ll manage your host groups and service groups, which enable you to quickly filter things like dashboards and reports to focus on specific subsets of your monitored assets and to carry out advanced approaches like hostgroup inheritance, whereby any host added to a group inherits various common services automatically. You can learn more about managing groups in this article:

Master Host and Service Groups in Nagios XI

Advanced Options

Dependencies

Host and Service Dependencies can be managed in the Advanced section of the CCM. You may already be familiar with parent/child relationships, which enable you to define host topology so that Nagios XI alerts you intelligently based on its ability to reach hosts. When a parent breaks, the child hosts and their services are marked as Unreachable rather than Critical, and you can customize whether and how Unreachable states alert.

Dependencies function in a similar way but aren’t meant to be dictated by topology alone. Any host or service can be made dependent on any other hosts or services you wish, providing a way to define advanced relationships based on the specifics of your environment. Note that, unlike Parent/Child relationships, dependencies don’t impact auto-generated topology diagrams like the Hypermap and Network Status Map.

Escalations

Host and Service Escalations provide a way to customize notifications when problems persist for too long, for example, sending an email to a manager if a host is still down after three notifications are sent to admins. These can be managed in either the Alerting > Host Escalations/Service Escalations section or via the handy Escalation Wizard in the Tools section of the CCM.

Event Handlers

Event handlers are automated actions you set XI to take when state changes occur. A simple example would be to execute a restart script on a host when Nagios detects that a key service is stopped, but ultimately, anything you can script can be done, so the possibilities are vast. This document provides full details and an example to try:

Introduction to Event Handlers in Nagios XI

Commands

These are the commands Nagios runs to do things like execute status checks, send notifications, and fire off event handlers. You’ll notice 160+ pre-loaded commands that XI uses to support the default monitoring wizards and alerting functions and can add your own as needed. This example shows the check_xi_ncpa command, which is run when Nagios executes a check on a host running the NCPA agent:

Import Config Files

If you’re currently using Nagios Core and would like to import your config files into Nagios XI, you can learn more about the process, the ready-made Import Prep Tool, and carry out the import in this section of the CCM.

Making Big Changes

The Bulk Modifications Tool has long been a favorite of Enterprise Edition users, especially those with large and dynamic environments. The tool enables you to quickly modify a key setting on as many hosts or services as you’d like with a few clicks.

Bulk Renaming not only provides a way to rename many objects at once but, even better (unlike renaming one at a time in the Core Config Manager) ensures that your historical performance data is retained even after changing the name of an object.

Give it a Try

As you can see, understanding and utilizing the CCM’s key capabilities is an important element of mastering XI administration.

If you’re not already using Nagios XI, the free trial version is a great way to experience the power of the Core Config Manager for yourself:

Nagios XI Free Trial

If you have any questions or need a hand, you can reach us at sales@nagios.com.

This article kicks off our Nagios Hostgroup Inheritance Series, where you will learn helpful tips and best practices for Hostgroup Inheritance.

Hostgroup Inheritance: What Is It?

Having worked in support and technical sales here at Nagios Enterprises, one of the requests I’ve regularly seen is the ability to have a “template of services” that can be assigned to a host. I put “template of services” in quotes because I don’t want you to confuse them with Service Templates, which are already a thing in Nagios, but they are distinctly not what people are looking for.

Currently, we don’t have an Easy Button for this, but there is a process called Hostgroup Inheritance that effectively gives people that “template of services” option. Upfront, there is a good chunk of work to be done. But in large environments, it will save you a ton of time.

It should also be noted that for smaller environments, Nagios XI has the Bulk Host Cloning & Import Wizard. This wizard can serve as a happy medium between running wizards against all of your hosts individually and implementing Hostgroup Inheritance.

The goal of this article series is to lay out the best features to use with Hostgroup Inheritance and how to set it up. I’ll be taking you through step by step, introducing each feature and the issue that it solves as we go.

In this article, I’m going to talk about configuration management and growing that configuration management, then I’ll be listing off all of the features we’ll be going over in the coming articles. In addition to all of that, I’ll lay out how to build a service check to use Hostgroup Inheritance from the ground up, followed by a shortcut that is specific to Nagios XI users.

There is a lot to cover, so let’s get started.

Out-Of-The-Box Nagios XI Config Management

The way that a person defines objects like hosts and services within Nagios Core (and by extension, Nagios XI) is through the use of plain text configuration files. There is no specific directory structure that you must use, which is somewhat of a double-edged sword. On the one hand, it offers maximum flexibility. On the other hand, I’ve seen countless systems where all hosts were defined in host.cfg, and all services were defined in services.cfg. Certainly, a valid way to do it. But that can get tricky when you try to implement it in larger environments.

The way Nagios XI manages configuration files is by using hosts and services directories. Each host has its host definition in the hosts directory. All of its services are defined in the services directory, in a file named after the hostname in the host definition.

So, in Nagios XI, when you look at a service definition in the Core Config Manager, you’ll see Config Name as the first setting. On the surface, this is a very safe and clean way to manage host and service configuration files. But there may be some issues of scaling when we look at larger environments.

Making Config Management Scale

The standard Nagios XI configuration management scheme does have plenty of upsides. However, I don’t feel like it scales very well. If you think about it, if you’re monitoring 100 servers, you’ve got 100 CPU service check definitions hanging out. Now, if you need to change the baseline for all 100 CPU service checks, you have to change 100 configuration entries.

Now that’s something that could be mitigated by the Bulk Modification Tools, Bulk Host Cloning & Import, or even some handy scripting with the Nagios XI API. But what if we also added configuration standardization into the mix?

Let’s say you’ve got a thousand or more servers you need to monitor properly. And let’s also say that a good chunk of them run Microsoft SQL Server. Like a good SQL Server admin, you configured those systems to have a drive for the OS, a drive for the data, and a drive for the transaction logs. Your other Windows servers only have a single drive. But these have three.

Do you want to remember to add monitoring for the two additional drives? Or do you want to assign a handy template to the host, a template with the name of the software the host is running, and have all of the appropriate service checks just show up? One of these sounds a heck of a lot better to me.

Why Doesn’t Nagios XI Just Do This?

Hostgroup Inheritance takes more than a little bit of setup. I’ve got dreams and aspirations of making a configuration wizard to help streamline the setup of Hostgroup Inheritance, but for right now, it does require a certain amount of thought, planning, and execution. More so than just standing up Nagios XI and running wizards against everything you need to monitor.

Thus, for many of our smaller customers, Hostgroup Inheritance isn’t worth the price of entry. Now, Nagios has always been about customization and fitting into as many environments as possible. To that end, I do want to see Hostgroup Inheritance made easier, making that price of entry come down, and making it available to more of our customers who fall somewhere between small and large environments.

Features You Need To Know

This article is already getting long. So, I’m going to lay out some additional reading that will help you in your Hostgroup Inheritance journey. I’ll cover the need-to-know in future articles related to Hostgroup Inheritance. But if you’re interested in the nitty-gritty, you might get a kick out of the features below.

Hostgroups

Well, we’re working with Hostgroup Inheritance. So, it’s best to know about hostgroups.
https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/4/en/objectdefinitions.html#hostgroup

Inheritance

The second word in Hostgroup Inheritance, is worth knowing about.
https://assets.nagios.com/downloads/nagioscore/docs/nagioscore/4/en/objectinheritance.html

Host Templates

Host Templates will be key in our configuration of Hostgroup Inheritance.
https://support.nagios.com/kb/article/managing-host-templates-906.html

Custom Variables

Custom Variables will also be extremely important later in this series.
https://library.nagios.com/techtips/custom-variables-in-nagios-xi/

Stay tuned for Part 2 in the next article of the Nagios Hostgroup Inheritance Series!

What is Contained in the API

The Nagios XI API is divided into three core sections: Objects, Config, and System. Each section serves a distinct purpose, making the API highly flexible and powerful.

Objects: This section is read-only and provides detailed information about various elements within Nagios XI. It allows users to query important resources, such as hosts, services, and other objects, providing insight into their current states and configurations. The data retrieved from this section can be delivered in either XML or JSON formats, making it easy to integrate and process within other applications or systems.

Config: The Config section is designed for administrative tasks, giving administrators the ability to add, remove, and modify objects such as hosts, services, and other configurations within Nagios XI. This section works directly with the Core Config Manager, allowing the creation and deletion of items. It provides a more dynamic role within the API, as it enables direct management and updates of system configurations to meet specific needs or changes in the infrastructure.

System: Like the Config section, the System section is reserved for administrators and provides the ability to manage the core subsystems of Nagios XI. It allows admins to execute system-level commands, configure system settings, and perform administrative tasks that impact the overall functionality and health of the Nagios XI environment.

Types of API Requests

When interacting with the Nagios XI API, you’ll primarily use four types of HTTP requests to interact with the system: GET, POST, PUT, and DELETE. Each request type serves a different purpose, allowing you to retrieve, create, update, or delete data.

1. GET – Retrieve Data
   The GET request is used to retrieve information from the Nagios XI API. It is typically used to query data such as host status, service status, or configuration details. This is a read-only operation and does not modify any data within the system. For example, you might use a GET request to check the current status of a host or service.
   Example: Retrieve host status or service details.
2. POST – Create or Submit Data
   The POST request is used to send data to the server, typically to create new resources or submit information. For example, when adding a new host or service to Nagios XI, you’ll use a POST request to submit the necessary configuration data. It is used when creating new objects or triggering actions that modify the state of the system.
   Example: Add a new host, service, or update configuration.
3. PUT – Update Data
   The PUT request is used to update or modify an existing resource. It’s typically used when you want to change the configuration of a current host, service, or other object in Nagios XI. Unlike POST, which creates new resources, PUT is meant for updating existing ones.
   Example: Update the configuration of an existing host or service.
4. DELETE – Remove Data
   The DELETE request is used to remove a resource from the Nagios XI system. It’s used when you want to delete objects such as hosts, services, or configurations. Deleting data through the API is a permanent operation, so it’s important to be sure before making this type of request.
   Example: Remove a host or service from the system.

How to Access the API via URL

The Nagios XI API can be accessed in a similar way to how you interact with Nagios XI itself—using a web browser. However, it’s important to note that this method is limited to GET requests, which allow you to retrieve and view data from the system. For tasks like creating, updating, or deleting resources (such as adding hosts or modifying configurations), you’ll need to use a different approach, typically by making POST, PUT, or DELETE requests through code. To get started, simply enter the following URL in your browser:

http://<Your Nagios XI IP>/nagiosxi/api/v1/

At this point, you’ll see an error message—this is expected since no requests have been made yet. To retrieve data, you need to specify the section of the API you want to query and the resource you’re interested in. The URL should look like this:

http://<Your Nagios XI IP>/nagiosxi/api/v1/<section>/<resource>

The section refers to a main area of the API, like objects, config, or system, each offering access to different data or functions. For example, the objects section retrieves information about items like hosts and services, while the config section allows administrators to manage those objects. A resource is a specific data type or object within that section that you query or manipulate. In the objects section, a resource might be hoststatus, showing the current status of hosts, while in the config section, a resource could be service, used to manage service configurations.

To access the API, you’ll also need to include your API key in the URL. This key grants you access to the system and helps determine the permissions you have based on your user role. Depending on your level of access, different sections and resources may be available to you.

To find your API key, navigate to the admin section of Nagios XI. Once you have it, append it to the URL like this:

http://<Your Nagios XI IP>/nagiosxi/api/v1/<section>/<resource>?apikey=<API key>

With everything set up correctly, you should now see real data returned from the API. We’ll use the results from querying hoststatus objects as an example.

By default, the output can appear a bit messy. To improve readability, you can check the Pretty-print checkbox in the UI, which automatically organizes the response. Alternatively, append &pretty=1 to the end of the URL for instant formatting. This makes the output clean, organized, and easy to digest.

http://<Your Nagios XI IP>/nagiosxi/api/v1/objects/hoststatus?apikey=<API key>&pretty=1

Objects are for displaying information, while Config and System are used for adding, removing, or modifying objects. What you write will depend on the action you want to perform with the API. For tasks like editing or modifying data, you’ll need to use code, as this involves making requests that modify the system.

Using with Code

There are many reasons why you might want to access the Nagios XI API programmatically. For instance, you may want to fetch the data posted to the system, monitor host/service statuses, or edit configurations directly through your code. Interacting with the API via code provides flexibility and automation, streamlining your workflow.

To access the API, we can use the appropriate method for interacting with URLs in the programming language you’re working with. Since Nagios XI runs on a web-based interface, the most common language for writing programs inside Nagios XI itself is PHP.

Below is an example of how to access and interact with the Nagios XI API using PHP:

<?php
// Define the server IP and API token
$server_ip = '<Your Nagios XI IP>';  // Replace with your Nagios XI IP
$api_token = '<Your API Key>';  // Replace with your Nagios XI API key

// Build the URL for the API request
$url = "http://$server_ip/nagiosxi/api/v1/<section>/<resource>?apikey=$api_token&pretty=1";

// Initialize cURL session
$ch = curl_init();

// Set the URL for the request
curl_setopt($ch, CURLOPT_URL, $url);

// Set option to return the response as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Execute the request and store the response
$response = curl_exec($ch);

// Check if the request was successful
if ($response === false) {
    echo "Error: " . curl_error($ch);  // Handle errors if the request fails
} else {
    // Decode the JSON response
    $data = json_decode($response, true);
    
    // Output the response (for testing or processing)
    echo "<pre>";
    print_r($data);  // Print the data in a readable format
    echo "</pre>";
}

// Close the cURL session
curl_close($ch);
?>

This code example demonstrates how to send a request to the API, process the response, and display the data in a readable format. It’s a simple and efficient way to automate interactions with Nagios XI.

When interacting with the Nagios XI API to modify data, such as adding a new host, the process differs significantly from simply retrieving information. Instead of making a GET request, we’ll use a POST request, which allows us to send data to the server to create or modify resources. The Config section of the API is used for this purpose, as it enables administrators to make changes to the Nagios XI configuration.

Here’s an example of how you can easily add a host to your Nagios XI setup using the API and PHP. This example walks you through how to structure the API request, send the necessary data, and handle the response. By automating the process like this, you can quickly add hosts to your Nagios XI environment, saving time and reducing the need for manual configuration.

function add_host_via_api($api_token)
{
    // Example: Prepare the POST data
    $data = [
        'host_name'                => 'testapihost',
        'address'                  => '127.0.0.1',
        'check_command'            => 'check_ping!3000,80%!5000,100%',
        'max_check_attempts'       => 2,
        'check_period'             => '24x7',
        'contacts'                 => 'nagiosadmin',
        'notification_interval'    => 5,
        'notification_period'      => '24x7',
        'applyconfig'              => 1
    ];

    // Set up the POST fields
    $post_fields = http_build_query($data);

    // Get the Nagios server IP address
    $server_ip = get_nagios_server_ip();

    // Prepare the URL for the API call
    $url = "http://$server_ip/nagiosxi/api/v1/config/host?apikey=$api_token";

    // Use cURL to send the POST request
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_fields);

    // Execute the cURL request and get the response
    $response = curl_exec($ch);

    // Check for errors in the cURL request
    if ($response === false) {
        return curl_error($ch);
    }

    // Close the cURL handle
    curl_close($ch);

    // Decode the response (optional)
    $response_data = json_decode($response, true);
    
    // Check for success or failure in response
    if (isset($response_data['error'])) {
        return "API Error: " . $response_data['error'];
    }

    return true;  // Return true if the host was added successfully
}

Once the request is made, the response will let you know if the host was added successfully or if there were any issues. We’ve included error handling to catch potential problems, such as network errors or invalid parameters. If everything goes as planned, the function will return true, confirming the host was added with no issues.

This example highlights how modifying your Nagios XI configuration through the API is quite different from just retrieving data. With POST requests, you gain the ability to create, update, and delete resources, giving you full control over your Nagios XI instance.

The other types of calls that can be made are PUT requests which are used to edit existing data in the API and DELETE requests, which deletes aspects of the API. We are going to finish with a look at a DELETE request to the API.

Conclusion

The Nagios XI API is a powerful tool for managing your Nagios XI instance, offering programmatic access to key data and configuration management capabilities. By following the steps outlined here, you can quickly integrate the API into your processes, improving your workflow. Whether you’re querying status data, managing configurations, or integrating with other systems, the Nagios XI API gives you the flexibility to enhance your Nagios XI experience.

For additional assistance, be sure to check the Nagios XI help section for more in-depth resources and support regarding the API.

Prerequisites

Here is what you need before you begin:

• A system running Kali Linux
• Nagios Log Server instance to access the web interface
• Root or sudo access for advanced operations
• Internet access to download packages

Step 1: Install Rsyslog

Open the terminal and update your packages, and then install rsyslog, which is typically used for log management.

sudo apt update
sudo apt install rsyslog

Step 2: Configure the Rsyslog File

Configure rsyslog by editing the rsyslog configuration file in /etc/rsyslog.conf.

sudo nano /etc/rsyslog.conf

Add the following lines to the end of the file; switch nagios_log_server_ip with the IP address of your Nagios Log Server.

*.* @nagios_log_server_ip:5544

Save your file and restart rsyslog.

sudo systemctl restart rsyslog

Step 3. Add a New Log Source in Nagios Log Server

Boot up a browser and login to your Nagios Log Server web interface.

From the homepage, click + Linux to configure your logs.

On the Linux configuration page, Nagios Log Server provides a setup script to configure rsyslog from the box below.

Run the setup using curl and execute the downloaded script to configure rsyslog. Change <your-nagios-log-server-address> to your IP address of your Nagios Log Server.

curl -sS -O http://<your-nagios-log-server-address>/nagioslogserver/scripts/setup-linux.sh

sudo bash setup-linux.sh -s <your-nagios-log-server-address> -p 5544

Put your Kali Linux IP address and check if the logs are being sent to the Nagios Log Server.

Step 4: Verify the Logs from the Dashboard

Navigate to the Nagios Log Server dashboard by clicking the four squares icon. Verify that logs from your Kali Linux machine are being received by running a query for its IP address.

Conclusion

By following these steps, you can efficiently send logs from Kali Linux to Nagios Log Server, centralizing your log data for easier monitoring and analysis. This setup helps you track system events, troubleshoot issues, and maintain a secure network environment. If you have additional questions or other support-related questions, please visit us at our Nagios Support Forum, Nagios Knowledge Base, or Nagios Library.