Jake Omann's presentation on Developing Nagios XI Components and Wizards. The presentation was given during the Nagios World Conference North America held Sept 20-Oct 2nd, 2013 in Saint Paul, MN. For more information on the conference (including photos and videos), visit: http://go.nagios.com/nwcna

1. Developing Nagios XI
Components and Wizards
Jake Omann
Developer @ Nagios
jomann@nagios.com

2. 2
Components & Wizards
A component can add functionality
Can access internal/external versions of API
A config wizard is supposed to make life easy
Many allow for auto-completion
Step-by-step process

3. 3
Components & Wizards: Links to Docs
Component Development and API
http://assets.nagios.com/downloads/nagiosxi/docs/XI_Component_Development.pdf
Config Wizard Development
http://assets.nagios.com/downloads/nagiosxi/docs/Writing_Custom_Wizards_In_XI.pdf
Example Component & Wizard
There is an example component linked inside
each of the above pdf documents

4. 4
Components
A basic component consists of optional parts
Config settings
Display page(s)
Callbacks
Some components only include a config section
Global Event Handlers
Allows 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

5. 5
Components: Directory Structure
Component file system basics:
componentname/
componentname.inc.php
componentname.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

6. 6
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

7. 7
Components: Example Code - Initialization

8. 8
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

9. 9
Components: Register Callbacks
Inside the init function defined by you
register_callback(CALLBACK_NAME,
'compname_func_do_stuff');
The first 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');

10. 10
Components: Register Callbacks Example
Example of:
Menu item callback
Host/service action button
Host/service tab

11. 11
Components: Add Quick Actions & Tabs
Quick action buttons
CALLBACK_HOST_DETAIL_ACTION_LINK
CALLBACK_SERVICE_DETAIL_ACTION_LINK
Tabs
CALLBACK_HOST_TABS_INIT
CALLBACK_SERVICE_TABS_INIT

12. 12
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

13. 13
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

14. 14
Components: Add a Display Page
Menu item
CALLBACK_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

15. 15
Config Wizards
Guidelines
Free 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 $inargs
Use 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

16. 16
Config Wizards: Directory Structure
Much larger structure than a basic component –
needs quite a few required files
Directory structure:
mongodb_server
logos/mongodb.png
plugins/check_mongodb.py
templates/mongodb_server.cfg
config.xml
install.sh (optional)
mongodb_server.inc.php

17. 17
Config Wizards: Templates
Templates are required to add the command
the wizard will be using to Nagios
mongodb_server.cfg

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

19. 19
Config Wizards: Example Code - Initialization

20. 20
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

21. 21
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

22. 22
Config Wizards: Stage 1
Each stage has 2 sections, html and validate
CONFIGWIZARD_MODE_GETSTAGE1HTML
CONFIGWIZARD_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

23. 23
Config Wizards: Stage 1
Stage 1 running in Nagios XI

24. 24
Config Wizards: Stage 2
CONFIGWIZARD_MODE_GETSTAGE2HTML
CONFIGWIZARD_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

25. 25
Config Wizards: Stage 2

26. 26
Config Wizards: Stage 3 and Final
CONFIGWIZARD_MODE_GETSTAGE2HTML
CONFIGWIZARD_MODE_VALIDATESTAGE2DATA
Stage 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

27. 27
Config Wizards: Get Objects
The final case in the config wizard switch
statement that will be ran
CONFIGWIZARD_MODE_GETOBJECTS

28. 28
Config Wizards: Get Objects
"check_command" =>
"check_mongodb_server!connect!$port!$warning!$critical!$username!$password”

29. 29
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

30. 30
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