Nagios XI - Creating Nagios XI Wizards


This document describes how to write custom configuration wizards in Nagios® XI. This document will cover how to create a new wizard using a custom plugin and also cover how to utilize some of the programming tools within the Nagios XI framework.



Target Audience

This document is intended for use by Nagios XI Administrators and Developers wanting to create custom configuration wizards, and is intended for an audience that has some familiarity with programming and HTML.



Sample Wizard Code

This document does not go into great detail on how to structure or write PHP code for a wizard. A sample wizard has been created that can be used in conjunction with this document and used as the basis of a new wizard.

You can download the example wizard code and structure using the following link:




Setting Up The Development Environment

Developers have unique preferences as to how to set up their development environment in PHP, however, the following setup will be the simplest way to work with and debug a wizard while it's in development.

Please refer to the Configure PHP Development Environment KB article for these steps.

This will generate error output directly to the browser window but will also create enough filtering so that the error output is easier to decipher. Before proceeding to the actual wizard code structure, see the section below on Debugging Tips to save time in the development process.



Debugging Tips

Login to the Nagios XI web interface and navigate to the Admin menu. Right click on the Manage Config Wizards under System Extensions and select “Open In New Tab.” Leave that page there for a moment, and access the Configure menu, and right click the Run the Monitoring Wizard link and select “Open In New Tab” as well. Both of these tabs will be beneficial when testing and developing the wizard.

While developing the wizard, we recommend developing the code on a local workstation and then uploading the zip file periodically to ensure the full functionality and compatibility of the wizard. If you were to access the Manage Configuration Wizards page directly and you uploaded a wizard that had a php syntax error on it, you should clearly see the error output on screen. This allows you to clearly identify any fatal errors in the code before proceeding to the stages of the wizard. 

To fix the syntax error, modify your local copy, rezip the directory, and then upload the wizard again. The old wizard will simply be overwritten. Once the wizard loads with no syntax errors, leave this page open, but select the tab opened to the Monitoring Wizard – Step 1 page. You will likely have to upload the wizard several more times until debugging is complete.

For debugging the wizard stages (monitoringwizard.php), error outputs will appear at the top of the page. Be sure to account for any undefined variables to prevent the Apache logs from being cluttered with error messages, and also to prevent bugs in the wizard itself.

Every time you upload a new wizard into Nagios XI, select the URL for the monitoringwizard.php page, and hit “Enter” to start the wizard over from stage one, and to clear any POST variables that will affect wizard navigation. You will likely need to repeat the process of rezipping the files, uploading to Nagios XI, and restarting the wizard several times, so leave both tabs open while you develop.



XI Wizard Development Guidelines

The development guidelines for Nagios XI Wizards are still somewhat loosely defined, but the following conditions will maximize compatibility, security, and reliability of the Configuration Wizard. Contact the Nagios XI Support Team if you have questions about your code, and see for the best reference on PHP syntax and built-in functions.


This will use some of the security features built into Nagios XI to clean any input variables and prevent XSS vulnerabilities. There is an exception to this in the wizard example, but the input variable is processed and cleaned of vulnerabilities.



Overview of Configuration Wizard Stages

The Nagios XI wizard framework is designed to handle user-defined wizard stages in the following progression. Each of these stages are prepended with CONFIGWIZARD_MODE_



Overriding Stages

Currently, the wizard framework allows for a limited amount of customization to the later stages of the Configuration Wizard, primarily the check settings and alert settings. These override options have been documented internally in the wizarddemo example code for the available options and how to use them. Future versions of Nagios XI will include options to skip entire stages and allow for manual definition of hostgroup, servicegroup, and parent relationships.



Wizard File Structure Overview

The files in a configuration wizard must be structured and named according to the following conventions in order for the wizard to function correctly. The following example will demonstrate naming conventions for a wizard with the name “wizarddemo.” See the zip file from the Sample Wizard Code for more details.

All files must be placed inside of a directory called "wizarddemo" and once completed the entire directory should be zipped into a file called “”











Any additional files that are not PHP scripts must be specified in a file called config.xml. Example of the wizarddemo's config.xml below:

<template filename="wizarddemo.cfg" />
<plugin filename="check_cap" />
<logo filename="wizarddemo.png" />



Using A Session Array For Wizard Data

The wizarddemo code demonstrates in detail how to use a $_SESSION array to work with wizard stages and data. The following code is an example of how to establish a session array for a wizard in the stage: CONFIGWIZARD_MODE_GETSTAGE1HTML.


//check to see if this is a fresh wizard run, or if we're coming back from a later stage
$back = htmlentities(grab_array_var($_POST,'backButton',false),ENT_QUOTES);

//clear any previous session data for this wizard, start a new session array

//create a new session array to hold data from different stages
$_SESSION['wizarddemo'] = array();



Final Thoughts

For any support related questions please visit the Nagios Support Forums at:

Article ID: 53
Created On: Tue, Feb 3, 2015 at 3:06 PM
Last Updated On: Wed, Nov 28, 2018 at 9:46 PM
Authored by: swilkerson

Online URL: