Information On The CGIs


Introduction

This is a brief description of each CGI distributed with NetSaint, along with the various options that can be specified in the URL to control output. Authorization requirements for each CGI are also discussed.

Important: By default, the CGIs require that you have authenticated to the web server and are authorized to view any information you are requesting. For more information on configuring your web server and CGI configuration file to allow for this, read the sections on setting up the web interface and CGI authorization.

Index

Status CGI
Status map CGI
Status world CGI (VRML)
Configuration CGI
Command CGI
Extended information CGI
Log file CGI
History CGI
Notifications CGI

Status CGI
Status CGI - Detail Status CGI - Overview
File Name: status.cgi

Description:
This is the most important CGI included with NetSaint. It allows you to view the current status of all hosts and services that are being monitored. The status CGI can produce two main types of output - a status overview of all host groups (or a particular host group) and a detailed view of all services (or those associated with a particular host). Pretty icons can be associated with hosts by defining extended host information entries in the CGI configuration file.

Authorization Requirements:

CGI Arguments:
Argument Description
host=all This will produce a detailed view of the status of all services being monitored with NetSaint
host=xxxx This will produce a detailed view of the status of all services associated with host xxxx, where xxxx is the short name of the host as defined in the host configuration file.
hostgroup=all This will produce an overview of all services (and their associated hosts) being monitored with NetSaint, grouped into various host groups.
hostgroup=xxxx This will produce an overview of all services (and their associated hosts) belonging to host group xxxx, where xxxx is the short name of the host group as defined in the host configuration file.
columns=x This option may only be used in conjunction with the hostgroup=all argument. It allows you to control how many columns of hostgroups are displayed on the generated page. For instance, supplying hostgroup=all&columns=4 as arguments to the CGI will produce an overview page that contains four columns of host groups.
style=detail This option may only be used in conjunction with the hostgroup argument. Supplying this option will produce a detailed view of all services for hosts that are members of the hostgroup you specified. If you do not supply this option, the default action is to produce a status overview page.
nopopup This option will suppress the host alert console window that gets displayed when one or more monitored hosts is either down or unreachable.

Status Map CGI
Status Map CGI
File Name: statusmap.cgi

Description:
This CGI dynamically creates a map of all hosts that you have defined on your network. The CGI uses Thomas Boutell's gd library (version 1.6.3 or higher) to create a PNG image of your network layout. Pretty icons can be associated with the hosts in the generated image by defining extended host information entries in the CGI configuration file. If you can't seem to find this CGI, or if you have get errors when trying to compile it, read this FAQ.

Authorization Requirements:

  • If you are authorized for all hosts you can view all hosts.
  • If you are an authenticated contact you can view hosts for which you are a contact.

Note: Users who are not authorized to view specific hosts will see unknown nodes in those positions. I realize that they really shouldn't see anything there, but it doesn't make sense to even generate the map if you can't see all the host dependencies...

CGI Arguments:
Argument Description
host=all This will produce a network map of all hosts being monitored with NetSaint
host=xxxx This will produce a network map of host xxxx and all of its child hosts, where xxxx is the short name of the host as defined in the host configuration file.
maxwidth=xxxx This will limit the maximum width of the produced image to xxxx pixels.
maxheight=xxxx This will limit the maximum height of the produced image to xxxx pixels.
hspacing=xx This sets the horizontal spacing between host nodes to xx pixels.
vspacing=xx This sets the vertical spacing between host nodes to xx pixels.
createimage This instructs the CGI to create the PNG image instead of the HTML code with imagemap coordinates

Status World CGI (VRML)
3-D Status Map CGI
File Name: statuswrl.cgi

Description:
This CGI dynamically creates a 3-D VRML model of all hosts that you have defined on your network. Images can be used as texture maps on host objects defining extended host information entries in the CGI configuration file. You'll need a VRML browser (like Cortona, Cosmo Player or WorldView) installed on your system before you can actually view the generated model.

Authorization Requirements:

  • If you are authorized for all hosts you can view all hosts.
  • If you are an authenticated contact you can view hosts for which you are a contact.

Note: Users who are not authorized to view specific hosts will see unknown nodes in those positions. I realize that they really shouldn't see anything there, but it doesn't make sense to even generate the map if you can't see all the host dependencies...

CGI Arguments:
Argument Description
host=all This will produce a network model of all hosts being monitored with NetSaint
host=xxxx This will produce a network model of host xxxx and all of its child hosts, where xxxx is the short name of the host as defined in the host configuration file.
notextures This will prevent images from being texture mapped onto host objects.
notext This will suppress the billboard text (host name and status) that is displayed over the host objects.

Configuration CGI
Configuration CGI - Hosts
File Name: config.cgi

Description:
This CGI allows you to view host, host group, contact, contact group, time period, service, and command definitions that you have defined in your host configuration file(s).

Authorization Requirements:

  • You must be authorized for configuration information in order to view contact, contact group, host group, time period, and command definitions. You will also be able to view all host and service definitions.
  • If you are authorized for all hosts you can view all host and service definitions.
  • If you are authorized for all services you can view all service definitions.
  • If you are an authenticated contact you can view all host and service definitions for which you are a contact.

CGI Arguments:
Argument Description
type=xxxx This option allows you to specify what type of definitions you would like to view. Valid options include "hosts", "hostgroups", "contacts", "contactgroups", "timeperiods", "commands", and "services".

Command CGI
Command CGI
File Name: cmd.cgi

Description:
This CGI allows you to send commands to the NetSaint process. Although this CGI has several arguments, you would be better to leave them alone. Most will change between different revisions of NetSaint. Use the extended information CGI as a starting point for issuing commands.

Authorization Requirements:

Notes:

  • If you have chosen not to use authentication with the CGIs, this CGI will not allow anyone to issue commands to NetSaint. This is done for your own protection. I would suggest removing this CGI altogether if you decide not to use authentication with the CGIs.
  • In order for the CGI to issue commands to NetSaint, you will have to set the proper file and directory permissions as described in this FAQ.

Extended Information CGI
Extended Information CGI - Process Information Extended Information CGI - Network Health Extended Information CGI - Host Information Extended Information CGI - Service Information
File Name: extinfo.cgi

Description:
This CGI allows you to view NetSaint process information, host and service state statistics, host and service comments, and more. It also serves as a launching point for sending commands to NetSaint via the command CGI. Although this CGI has several arguments, you would be better to leave them alone - they are likely to change between different releases of NetSaint. You can access this CGI by clicking on the 'Network Health' and 'Process Information' links on the side navigation bar, or by clicking on a host or service link in the output of the status CGI.

Authorization Requirements:

Log File CGI
Log File CGI
File Name: showlog.cgi

Description:
This CGI will display the log file. If you have log rotation enabled, you can browse notifications present in archived log files by using the navigational links near the top of the page.

Authorization Requirements:

CGI Arguments:
Argument Description
archive=x This option allows you to browse notifications in the xth latest log archive. A value of 0 will cause the current log file to be used, a value of 1 will cause the most recent archived log to be used, and so on...
oldestfirst This option allows view notifications with older entries at the top of the page and newer entries at the bottom. The CGI will normally reverse the log file so that newer log entries show up at the top of the page while older ones are at the bottom.

History CGI
History CGI
File Name: history.cgi

Description:
This CGI is used to display the history of problems with either a particular host or all hosts. The output is basically a subset of the information that is displayed by the log file CGI. You have the ability to filter the output to display only the specific types of problems you wish to see (i.e. hard and/or soft alerts, various types of service and host alerts, all types of alerts, etc.). If you have log rotation enabled, you can browse history information present in archived log files by using the navigational links near the top of the page.

Authorization Requirements:

  • If you are authorized for all hosts you can view history information for all hosts and all services.
  • If you are authorized for all services you can view history information for all services.
  • If you are an authenticated contact you can view history information for all services and hosts for which you are a contact.

CGI Arguments:
Argument Description
host=all This will display the history of all hosts being monitored with NetSaint
host=xxxx This will display the history of host xxxx, where xxxx is the short name of the host as defined in the host configuration file.
type=x This option allows you to control which types of historical alerts are displayed. As x is a numerical value generated by the CGI, I would suggest using the dropdown box to select the type of alerts you want to view.
statetype=x This option allows you to control whether soft or hard alerts (or both) are displayed. As x is a numerical value generated by the CGI, I would suggest using the dropdown box to select the type of alerts you want to view.
archive=x This option allows you to browse the history information in the xth latest log archive. A value of 0 will cause the current log file to be used, a value of 1 will cause the most recent archived log to be used, and so on...
oldestfirst This option allows view history information with older entries at the top of the page and newer entries at the bottom. The CGI will normally reverse the log file so that newer log entries show up at the top of the page while older ones are at the bottom.

Notifications CGI
Notifications CGI
File Name: notifications.cgi

Description:
This CGI is used to display host and service notifications that have been sent to various contacts. The output is basically a subset of the information that is displayed by the log file CGI. You have the ability to filter the output to display only the specific types of notifications you wish to see (i.e. service notifications, host notifications, notifications sent to specific contacts, etc). If you have log rotation enabled, you can browse notifications present in archived log files by using the navigational links near the top of the page.

Authorization Requirements:

  • If you are authorized for all hosts you can view notifications for all hosts and all services.
  • If you are authorized for all services you can view notifications for all services.
  • If you are an authenticated contact you can view notifications for all services and hosts for which you are a contact.

CGI Arguments:
Argument Description
host=all This will display all notifications that have been sent out for all hosts (and their associated services) being monitored with NetSaint
host=xxxx This will display all notifications that have been sent out for host xxxx (and its associated services), where xxxx is the short name of the host as defined in the host configuration file.
contact=all This will display all service and host notifications that have been sent out to all contacts.
contact=xxxx This will display all service and host notifications that have been sent out to contact xxxx, where xxxx is the short name of the contact as defined in the host configuration file.
type=x This option allows you to control which types of notifications are displayed. As x is a numerical value generated by the CGI, I would suggest using the dropdown box to select the types of notifications you want to view.
archive=x This option allows you to browse notifications in the xth latest log archive. A value of 0 will cause the current log file to be used, a value of 1 will cause the most recent archived log to be used, and so on...
oldestfirst This option allows view notifications with older entries at the top of the page and newer entries at the bottom. The CGI will normally reverse the log file so that newer log entries show up at the top of the page while older ones are at the bottom.