USAGE:
------

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. Thse 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 satus 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 paramaters.

* 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 seperate 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 seperated 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 seperated 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 seperated by a colon (":").
 
The main difference in incoking 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&params=param1[:param2...:paramx]



* Status command usage:	

	http://localhost/cgi/nxe.pl?type=status&params=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&params=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&params=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 seperated by a colon. 



* Transform_cmd command usage:

	http://localhost/cgi/nxe.pl?type=transform_cmd&params=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 seperated 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 paramters. 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 accross 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://myproxy/ http://somehost/cgi/nxe.pl status status1

run nxe_client with the -h option for full usage instructions.