Route Hops: How to Create a Nagios Plugin to Monitor Them

Tyler Larson — Tue, 04 Nov 2025 14:45:00 +0000

An important metric in network diagnostics is the number of hops it takes to reach a target host. In this article, we will create a plugin for Nagios using Python to monitor route hops to a target host.

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:

Parse arguments.
Attempt traceroute on the specified protocol.
Fallback to alternative protocols if the specified protocol fails.
Compare the hop counts against the thresholds.
Build and print a Nagios status message.
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.

How to Use the Meraki Switch Wizard in Nagios XI

Ayub Huruse — Thu, 25 Sep 2025 13:57:47 +0000

Nagios XI includes a Meraki Switch Wizard that discovers Cisco Meraki switches via the Meraki API or SNMP, auto-detects interfaces, and lets you quickly set up per-port monitoring for status and bandwidth (Rate In/Rate Out) with bulk selection and warning/critical thresholds across one or many switches.

You can also refer to this documentation for full details:

Monitoring-Meraki-Switches-with-Nagios-XI

Here is a direct link to the PDF as well:

How To Monitor Meraki Switches With Nagios XI 2026

Configuring Switches And Routers To Send Netflow Data To Nagios Network Analyzer

Ethan Galstad — Fri, 06 Sep 2013 22:31:52 +0000

This document describes how to setup Netflow data collection on enterprise grade switches and routers, and relay that information to Nagios Network Analyzer (NNA). It is intended for use by network administrators who are doing the initial setup of their NNA software.

Network Analyzer 2026

Configuring Switches & Routers to Send Flow Data to NNA – 2026

Network Analyzer 2024

Configuring Switches & Routers to Send Flow Data to NNA – 2024

Network Analyzer v2 (Legacy)

Configuring Switches & Routers to Send Flow Data to NNA – v2 (Legacy)

Nagios XI – Adding Service Switch or Router

Ethan Galstad — Fri, 17 Aug 2012 02:13:33 +0000

Often times, adding ports to a switch, or interfaces to a router must be done dynamically. This document shows how to add ports or interfaces to your monitoring switch or router using Nagios XI’s Switch/Router Monitoring wizard.

This document is intended for use by Nagios XI Administrators who have dynamic environments and must adjust their switch infrastructure monitoring to reflect those changes.

Adding Service to Switch or Router

Note: No Longer Necessary

As of XI 2014 these steps are no longer necessary to add new services to an existing switch or
router, as MRTG now stores configurations in per-device .cfg files. The XI Switch / Router Wizard
handles all of the logic for you.

Simply re-run the wizard, using the exact same hostname as the existing host in Step 2, and add an additional services you wish.

Router and Switch Monitoring – Nagios Library