Developing Nagios XI Components and Wizards

Jake Omann

Developer @ Nagiosjomann@nagios.com

Components & Wizards

A component can add functionalityCan access internal/external versions of API

A config wizard is supposed to make life easyMany allow for auto-completion

Step-by-step process

Components & Wizards: Links to Docs

Component Development and APIhttp://assets.nagios.com/downloads/nagiosxi/docs/XI_Component_Development.pdf

Config Wizard Developmenthttp://assets.nagios.com/downloads/nagiosxi/docs/Writing_Custom_Wizards_In_XI.pdf

Example Component & WizardThere is an example component linked inside each of the above pdf documents

Components

A basic component consists of optional partsConfig settings

Display page(s)

Callbacks

Some components only include a config sectionGlobal Event HandlersAllows user to set up events to be ran when an action happens there's no actual display page except the config settings

A majority of components have a display page that lets you interact with it

Components: Directory Structure

Component file system basics:componentname/componentname.inc.phpcomponentname.php

Images should be added into an images folder in component directory

Included files, scripts, libraries should be added into an include or lib folder inside your component directory

Example: BirdsEye 3

Components: Init function

Must define an init function

Controls information about the component and runs the component registration, sets up the main component config function, and registers callbacks

Components: Example Code - Initialization

Components: Config Settings

Creating a settings button next to the installed component with config settings

COMPONENT_CONFIGFUNCTION defines the config function to be used

Inside the function you've created for the component is a switch with two cases:COMPONENT_CONFIGMODE_GETSETTINGSHTML

COMPONENT_CONFIGMODE_SAVESETTINGS

Components: Register Callbacks

Inside the init function defined by you

register_callback(CALLBACK_NAME, 'compname_func_do_stuff');Thefirst variable, CALLBACK_NAME must be a valid XI callback some helpful ones are shown later

The second variable is the name of the function we want to run

function compname_func_do_stuff($cbtype,&$cbargs)Can use grab_array_var ex:
$service = grab_array_var($cbargs, 'service');

Components: Register Callbacks Example

Example of:Menu item callback

Host/service action button

Host/service tab

Components: Add Quick Actions & Tabs

Quick action buttonsCALLBACK_HOST_DETAIL_ACTION_LINK

CALLBACK_SERVICE_DETAIL_ACTION_LINK

TabsCALLBACK_HOST_TABS_INIT

CALLBACK_SERVICE_TABS_INIT

Components: Creating a QA

Adding an item to the $cbargs['actions'] will display that item in the QA section

This is an example of adding a popup window

Components: Creating a Tab

$content is a string of HTML

$newtab is an array of id, title, and content which will be displayed on the page

Adding to $cbdata[tabs] creates a new tab

Components: Add a Display Page

Menu itemCALLBACK_MENUS_INITIALIZED

Adds a menu item that will take the user to the location we want them to go, normally the non .inc.php file included with the component

Config Wizards

GuidelinesFree from FATAL, SYNTAX, and NOTICE messages

Never run UPDATE or INSERT SQL query on nagios or nagiosql databases

Avoid using $_POST, $_GET, $_GLOBALS since the post variables are already located in $inargsUse grab_array_var instead

$form_var = grab_array_var($inargs, $varname, 'default value')

Most newer wizards store data being passed between steps inside session arrays instead of the old way of passing using serialized arrays

Config Wizards: Directory Structure

Much larger structure than a basic component needs quite a few required files

Directory structure:mongodb_serverlogos/mongodb.pngplugins/check_mongodb.pytemplates/mongodb_server.cfgconfig.xmlinstall.sh (optional)mongodb_server.inc.php

Config Wizards: Templates

Templates are required to add the command the wizard will be using to Nagios

mongodb_server.cfg

Config Wizards: Config XML

config.xml has three nodes plugins, templates, logos - you have to add any plugins - you need to add any commands here (optional) - logo that is in your logos folder

Config Wizards: Example Code - Initialization

Config Wizards: Example Code The Function

This function was defined in the init function

Everything from the switch statement up must be included and edited for your config wizard

Config Wizards: Stages

Has a set of steps in Nagios XI and stages in the code

Note: Config wizards start on step 2, step 2-4 are editable inside a config wizard's code

Steps are not Stages... step #n = stage #n-1

Inside the switch statement we have each step of the config wizard

CONFIGWIZARD_MODE_GETSTAGE1HTML
(stage 1) in your config wizard code is actually step 2 when using a config wizard

Config Wizards: Stage 1

Each stage has 2 sections, html and validateCONFIGWIZARD_MODE_GETSTAGE1HTMLCONFIGWIZARD_MODE_VALIDATESTAGE1DATA

To return to a stage during validation:

$result is the return 0 = ok, 1 = error

This stage is for gathering information about the host/service you want to configure

Config Wizards: Stage 1

Stage 1 running in Nagios XI

Config Wizards: Stage 2

CONFIGWIZARD_MODE_GETSTAGE2HTMLCONFIGWIZARD_MODE_VALIDATESTAGE2DATA

Stage 2 allows you to select what you want to monitor and how you want to monitor it

Some wizards will auto-populate the information in stage 2 by contacting the host

Note: Clicking forward OR back should save data from this stage and all others be sure to pass data along data using a session

Config Wizards: Stage 2

Config Wizards: Stage 3 and Final

CONFIGWIZARD_MODE_GETSTAGE2HTMLCONFIGWIZARD_MODE_VALIDATESTAGE2DATAStage 3 is already populated with monitoring settings you cannot change in the wizard

Stage 3 is mostly used for saving data and passing it on to be used

CONFIGWIZARD_MODE_GETFINALSTAGEHTML

The Final stage is the same you will have to continue passing the data if required (not using session method of passing data)

Example: MySQL Server Wizard

Config Wizards: Get Objects

The final case in the config wizard switch statement that will be ran

CONFIGWIZARD_MODE_GETOBJECTS

Config Wizards: Get Objects

"check_command" => "check_mongodb_server!connect!$port!$warning!$critical!$username!$password

Config Wizards: Get Objects

Before breaking out of this section, add the objects to the outargs

Will set up your commands in the Nagios config for you after this stage

Examples & Tips

Example/base wizards and components can be downloaded via links in the corresponding developer help docs

Tip: Check out the source of some of the wizards and components that you use (except the protected Nagios XI ones) to get more of a feel for how they work

Click to edit the outline text format

Second Outline Level

Third Outline Level

Fourth Outline Level

Fifth Outline Level

Sixth Outline Level

Seventh Outline Level

Eighth Outline Level

Ninth Outline Level

Click to edit the title text format

Click to edit the title text format

Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline LevelSeventh Outline LevelEighth Outline LevelNinth Outline Level