nagios conference 2013 - jake omann - developing nagios xi components and wizards
TRANSCRIPT
Developing Nagios XI Components and Wizards
Jake Omann
Developer @ [email protected]
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