NXE has been designed to be both flexible and easy to use. The
first step after successfully installing NXE is to add entries
to the nxe.config file. This file specified aliases for files
you would like to use with NXE. Instead of having to specify long
ugly file names on the command line, in URLs to NXE or in XML-RPC
parameters , you can use the aliases listed in the nxe.config
file.
You must list all Nagios status log files you wish to access,
all XSLT style sheets you wish to use and all Nagios external
command files you wish to write to in the nxe.config file. NXE
will not accept file paths in commands for many good reasons (including
security).
A sample nxe.config file is included in the NXE package. Entries
in a typical file would look like this:
############################################
#The following are nxe.config sample entries
#
status1=/usr/local/nagios/var/status.log
ext_cmd1=/usr/local/nagios/var/command.log
status2=/usr/local/nagios2/var/status.log
ext_cmd2=/usr/local/nagios2/var/command.log
HTMLcmdreply=/usr/local/nxe/stylesheets/html_command_reply.xsl
PDFstatus=/usr/local/nxe/stylesheets/pdfstatus.xsl
#
# End of Sample nxe.config entries
###########################################
Examples of using aliases are documented in each of the NXE commands
below.
NXE COMMANDS:
NXE accepts 4 basic commands via any of the access methods available.
These commands are:
- status : The status command takes one or
more file aliases (as defined in nxe.config) pointing to Nagios
status log files as arguments and outputs a well formed (and
valid) XML document containing entries for each object in the
Nagios status log files specified. The XML format is described
in detail in the nxe.dtd file included with NXE.
- transform : The transform command takes a
file alias (as defined in nxe.config) for a XSLT style sheet
as its first parameter followed by one or more file aliases
for Nagios status log files. The transform command aggregates
the data from the multiple status log files in the same XML
format used by NXE's status command and then transforms it using
the specified style sheet before output.
- cmd : The cmd command adds a Nagios external
command to a Nagios external command file. cmd takes a file
alias (as defined in nxe.config) for the external command file
to update as its first parameter followed by the Nagios external
command and all of its parameters
- transform_cmd : This command takes the output
of a NXE cmd (defined in the nxe.dtd file) and transforms using
a specified style sheet. The first parameter this command takes
is a file alias for the style sheet followed by a file alias
for a Nagios external command file followed by the Nagios external
command and finally each of its parameters.
The following section contains detailed usage information on
how to access NXE using any of the 3 available methods. NXE can
be accessed via XML-RPC, command line or HTTP GET (URL).
Command Line Mode:
Each parameter should be separate by a single space.
General Usage:
nxe.pl command param1 [param2 ... paramx]
* Status command usage:
nxe.pl status status1
- status is the command being issued to nxe.pl
- status1 is a file alias to a Nagios status log file defined
in nxe.config.
* Transform command usage:
nxe.pl transform PDFstatus status1
- transform is the command being issued to nxe.pl
- PDFstatus is a file alias for an XSLT style sheet
- status1 is a file alias for a Nagios status log file.
* Cmd command usage:
nxe.pl cmd ext_cmd1 NAGCMD [NagCMDParam1 ...NagCMDParamx]
- cmd is the command being issued to nxe.pl
- ext_cmd1 is an alias for a Nagios external command file
- NAGCMD is the Nagios command to write to the external command
file
- NagCMDParam[x] are the parameters required by the Nagios external
command as specified in the Nagios documentation. Each parameter
should be separated by a space.
* Transform_cmd command usage:
nxe.pl transform_cmd HTMLcmdreply ext_cmd2 NAGCMD [NagCMDParam1
... NagCMDParamx]
- transform_cmd is the command being issued to nxe.pl
- HTMLcmdreply is a file alias for a style sheet that will be
applied to the result of the NXE cmd function (detailed in nxe.dtd).
- ext_cmd2 which is a file alias pointing to a Nagios external
command file.
- NAGCMD is the Nagios command to write to the external command
file
- NagCMDParam[x] are the parameters required by the Nagios external
command as specified in the Nagios documentation. Each parameter
should be separated by a space.
HTTP GET (URL) Mode:
Using NXE in HTTP GET mode provides an easy way to integrate Nagios
data or commands into any Web based application. By creating URLs
linking to NXE installed as a CGI on a Web server you can easily
create custom Nagios administration web pages.
If you create the links in an XSLT stylesheet that you then use
to transform NXE output with you can create a fully functional
CGI management & reporting interface to Nagios using nothing
more then NXE & some custom stylesheets.
When invoking NXE via a URL, it takes 2 URL parameters; the "type"
parameter specifies the NXE command to issue and the "params"
parameter specifies each of the parameters to that command separated
by a colon (":").
The main difference in invoking NXE from a URL versus the XML-RPC
or command line mode is that when you use either of the transform
commands (transform or transform_cmd), the first parameter must
specify the output type, be it xml, html, pdf or some other mime
type recognized by the receiving client. Note that the string
"text/" will be pre-appended to any mime type you specify.
General Usage:
http://localhost/cgi/nxe.pl?type=command¶ms=param1[:param2...:paramx]
* Status command usage:
http://localhost/cgi/nxe.pl?type=status¶ms=status1
- status is the command being issued to nxe.pl
- status1 is a file alias to a Nagios status log file defined
in nxe.config.
* Transform command usage:
http://localhost/cgi/nxe.pl?type=transform¶ms=pdf:PDFstatus:status1
- transform is the command being issued to nxe.pl
- pdf is the mime type of the document to return
- PDFstatus is a file alias for an XSLT style sheet
- status1 is a file alias for a Nagios status log file.
* Cmd command usage:
http://localhost/cgi/nxe.pl?type=cmd¶ms=ext_cmd1:NAGCMD[:NagCMDParam1...:NagCMDParamx]
- cmd is the command being issued to nxe.pl
- ext_cmd1 is an alias for a Nagios external command file
- NAGCMD is the Nagios command to write to the external command
file
- NagCMDParam[x] are the parameters required by the Nagios external
command as specified in the Nagios documentation. Each parameter
should be separated by a colon.
* Transform_cmd command usage:
http://localhost/cgi/nxe.pl?type=transform_cmd¶ms=html:HTMLcmdreply:ext_cmd2:NAGCMD[:NagCMDParam1...:NagCMDParamx]
- transform_cmd is the command being issued to nxe.pl
- html is the mime type of the document to return
- HTMLcmdreply is a file alias for a style sheet that will be
applied to the result of the NXE cmd function (detailed in nxe.dtd).
- ext_cmd2 which is a file alias pointing to a Nagios external
command file.
- NAGCMD is the Nagios command to write to the external command
file
- NagCMDParam[x] are the parameters required by the Nagios external
command as specified in the Nagios documentation. Each parameter
should be separated by a space.
XML-RPC Mode:
XML-RPC makes use of a specific XML RPC protocol which runs on
top of the standard HTTP protocol using POST methods. A full discussion
of the XML-RPC implementation is beyond the scope of this document.
NXE handles all the XML-RPC document creation, transmission and
interpretation for you. No need to build methodcall xml fragments
by hand.
A typical XML-RPC request consists of a methodname followed by
parameters. To use NXE with any XML-RPC client, simply point your
RPC source to the NXE script installed as a CGI on a Web server
and pass the same method name and parameters you would using the
command line version of NXE (documented above).
For example, the command line example:
nxe.pl status status1
Would become (using the nxe_client XML-RPC client as an example):
nxe_client.pl http://somehost/cgi/nxe.pl status status1
It's really that easy. The XML-RPC client is included in the
package for you to play with, but any XML-RPC compliant system
can access NXE in the same manner.
Some technical Details about XML-RPC:
* The status & cmd commands return valid XML documents in
the "message" section of the XML-RPC reply.
* The transform & transform_cmd commands return the entire
transformed document pf whatever type in the "message"
section of the XML-RPC reply.
* When in XML-RPC mode all errors are returned in standard XML-RPC
error format. The message section contains only the error message
and not an entire XML document.
nxe_client.pl Additional Notes:
The nxe_client.pl is a small Perl script that will run on any
Perl enabled platform. It can be used to access NXE via its XML-RPC
interface across the network as if it were local. The XML-RPC
Mode documentation illustrates its use pretty clearly. One additional
feature worth mentioning is that it can also take a parameter
for a http proxy server to use as follows:
nxe_client.pl -p http://my proxy/ http://somehost/cgi/nxe.pl
status status1
run nxe_client with the -h option for full usage instructions.
NXE will run under both Win32 and Unix platforms. A system with
Perl installed is the only major requirement. It should either
have Nagios running on the same host or have access to the status
log and external command files of any Nagios systems you would
like to use NXE with. If you want to use NXE in either HTTP GET
(URL) mode or XML-RPC mode the system must have Web server capable
of running Perl CGIs.
The transformation functions of NXE are based on the availability
of a 3rd party XSLT engine. These are available for free for almost
every platform. NXE supports the following XSLT engines:
* libxslt
* sablotron
* xalan
* xslt
* xt
* saxon
We recommend Sablotron (http://www.gingerall.com/) if you are
new to XSLT because it is easy to install on both Win32 &
Unix platforms. We will use Sablotron as an example in this file,
but the installation steps should be roughly the same regardless
of the XSLT engine used. For maximum performance on Unix systems,
we recommend using the LibXSLT (http://xmlsoft.org/XSLT/) engine.
1) Verify Perl is installed correctly.
2) Verify Web server is setup and can handle Perl CGIs properly
if you are going to use the XML-RPC or the HTTP GET functionality
of NXE.
3) Most XSLT engines require that the Expat processor is installed.
If you are going to use XSLT transformations with NXE now is when
you should download Expat. Check the documentation of the XSLT
engine you are planning on using, but more then likely it uses
Expat. Get Expat from http://sourceforge.net/projects/expat .
4) Download & install the XSLT engine you would like to use.
Ex: Sablotron from http://www.gingerall.com/ or LibXSLT from http://xmlsoft.org/XSLT/
.
5) This should be in the installation instructions for your XSLT
engine, but often users overlook it. After you have installed
your XSLT engine (on Unix systems only) you must run the "ldconfig"
command.
6) Make sure the XSLT engine is in your path. Test it by trying
to run the XSLT engine from the command line in a directory it
is not installed in.
7) Start up CPAN (or PPM for Win32 users) by typing "cpan"
(or "ppm") at a command prompt. Once in the CPAN prompt
type:
install xxx
Where xxx is each of the following modules:
XML::Writer
XML::Parser
XML::Writer::String
Sys::Hostname
Frontier::RPC2
XML::XSLT::Wrapper
CGI
8) Still at the CPAN (or PPM) prompt install the Perl modules
for your XSLT engine. For example if you were using Sablotron
you would type: "install XML::Sablotron" for LibXSLT
it would be: "install XML::LibXML" and then "install
XML::LibXSLT". See your XSLT engine documentation for details.
9) Copy the nxe.pl script to a CGI directory of your Web server
if you would like to use XML-RPC of HTTP GET modes of NXE.
10) Make script executable chmod +x nxe.pl on Unix systems.
11) NXE uses an editable config file named "nxe.config"
(you can change the name) to create aliases for specifying paths
to different files (multiple Nagios status logs, XSLT templates,
etc..). Alias entries take the form of "status1=/usr/local/nagios/var/status.log"
on Unix systems and "HTML1=c:\XSLT\Nag2HTML.xsl" on
Win32 systems. See the usage section below and the comments in
the nxe.config file for details.
12) By default NXE will look for the nxe.config file in the same
directory it is being run from. This is not a recommended configuration
when being used with a Web server. To change the location or name
of nxe.config edit the first line of the nxe.pl script (the "$CONFIG_FILE"
variable) to point to the correct file.
13) Ensure that the user running NXE can read nxe.config &
all files specified in nxe.config. The user should also have ability
to write to any Nagios external command files specified in nxe.config.
Nagios is a registered trademark of Ethan Galstad.
For more information see http://www.nagios.org or http://nxe.sourceforge.net
Copyright (C) 2003 Daniel Koffler
The Nagios XML Engine (NXE) is free software; you can redistribute
it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
NXE is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
A copy of the GNU Lesser General Public License can be obtained
from the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA
or try the following url: http://www.gnu.org/copyleft/lesser.html#SEC1
|
