Introduction

The various CGIs distributed with Nagios are described here, along with the authorization requirements for accessing and using each CGI. 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
WAP interface CGI
Status world CGI (VRML)
Tactical overview CGI
Network outages CGI
Configuration CGI
Command CGI
Extended information CGI
Event log CGI
Alert history CGI
Notifications CGI
Trends CGI
Availability reporting CGI
Alert histogram CGI
Alert summary CGI

Status CGI

File Name:

status.cgi

Description: This is the most important CGI included with Nagios. 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 and service information entries. Authorization Requirements: If you are authorized for all hosts you can view all hosts and all services. If you are authorized for all services you can view all services. If you are an authenticated contact you can view all hosts and services for which you are a contact.

Status Map CGI

File Name:

statusmap.cgi

Description: This CGI 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. The coordinates used when drawing each host (along with the optional pretty icons) are taken from extended host information definitions. If you'd prefer to let the CGI automatically generate drawing coordinates for you, use the default_statusmap_layout directive to specify a layout algorithm that should be used. If you can't seem to find this CGI, or if you have get errors when trying to compile or run 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...

WAP Interface CGI

File Name:

statuswml.cgi

Description: This CGI serves as a WAP interface to network status information. If you have a WAP-enable device (i.e. an Internet-ready cellphone), you can view status information while you're on the go. Different status views include hostgroup summary, hostgroup overview, host detail, service detail, all problems, and unhandled problems. In addition to viewing status information, you can also disable notifications and checks and acknowledge problems from your cellphone. Pretty cool, huh? Authorization Requirements: If you are authorized for system information you can view Nagios process information. If you are authorized for all hosts you can view status data for all hosts and services. If you are authorized for all services you can view status data for all services. If you are an authenticated contact you can view status data for all hosts and services for which you are a contact.

Status World CGI (VRML)

File Name:

statuswrl.cgi

Description: This CGI creates a 3-D VRML model of all hosts that you have defined on your network. Coordinates used when drawing the hosts (as well as pretty texture maps) are defined using extended host information definitions. If you'd prefer to let the CGI automatically generate drawing coordinates for you, use the default_statuswrl_layout directive to specify a layout algorithm that should be used. 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...

Tactical Overview CGI

File Name:

tac.cgi

Description: This CGI is designed to server as a "birds-eye view" of all network monitoring activity. It allows you to quickly see network outages, host status, and service status. It distinguishes between problems that have been "handled" in some way (i.e. been acknowledged, had notifications disabled, etc.) and those which have not been handled, and thus need attention. Very useful if you've got a lot of hosts/services you're monitoring and you need to keep a single screen up to alert you of problems. Authorization Requirements: If you are authorized for all hosts you can view all hosts and all services. If you are authorized for all services you can view all services. If you are an authenticated contact you can view all hosts and services for which you are a contact.

Network Outages CGI

File Name:

outages.cgi

Description: This CGI will produce a listing of "problem" hosts on your network that are causing network outages. This can be particularly useful if you have a large network and want to quickly identify the source of the problem. Hosts are sorted based on the severity of the outage they are causing. More information on how the network outage CGI works can be found here. 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.

Configuration CGI

File Name:

config.cgi

Description: This CGI allows you to view objects (i.e. hosts, host groups, contacts, contact groups, time periods, services, etc.) that you have defined in your object configuration file(s). Authorization Requirements: You must be authorized for configuration information in order to any kind of configuration information.

Command CGI

File Name:

cmd.cgi

Description: This CGI allows you to send commands to the Nagios process. Although this CGI has several arguments, you would be better to leave them alone. Most will change between different revisions of Nagios. Use the extended information CGI as a starting point for issuing commands. Authorization Requirements: You must be authorized for system commands in order to issue commands that affect the Nagios process (restarts, shutdowns, mode changes, etc.). If you are authorized for all host commands you can issue commands for all hosts and services. If you are authorized for all service commands you can issue commands for all services. If you are an authenticated contact you can issue commands for all hosts and services for which you are a contact. Notes: If you have chosen not to use authentication with the CGIs, this CGI will not allow anyone to issue commands to Nagios. 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 Nagios, you will have to set the proper file and directory permissions as described in this FAQ.

Extended Information CGI

File Name:

extinfo.cgi

Description: This CGI allows you to view Nagios process information, host and service state statistics, host and service comments, and more. It also serves as a launching point for sending commands to Nagios 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 Nagios. 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: You must be authorized for system information in order to view Nagios process information. If you are authorized for all hosts you can view extended information for all hosts and services. If you are authorized for all services you can view extended information for all services. If you are an authenticated contact you can view extended information for all hosts and services for which you are a contact.

Event Log 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: You must be authorized for system information in order to view the log file.

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

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.

Trends CGI

File Name:

trends.cgi

Description: This CGI is used to create a graph of host or service states over an arbitrary period of time. In order for this CGI to be of much use, you should enable log rotation and keep archived logs in the path specified by the log_archive_path directive. The CGI uses Thomas Boutell's gd library (version 1.6.3 or higher) to create the trends image. If you can't seem to find this CGI or if you have get errors when trying to compile or run it, read this FAQ. Authorization Requirements: If you are authorized for all hosts you can view trends for all hosts and all services. If you are authorized for all services you can view trends for all services. If you are an authenticated contact you can view trends for all services and hosts for which you are a contact.

Availability Reporting CGI

File Name:

avail.cgi

Description: This CGI is used to report on the availability of hosts and services over a user-specified period of time. In order for this CGI to be of much use, you should enable log rotation and keep archived logs in the path specified by the log_archive_path directive. Authorization Requirements: If you are authorized for all hosts you can view availability data for all hosts and all services. If you are authorized for all services you can view availability data for all services. If you are an authenticated contact you can view availability data for all services and hosts for which you are a contact.

Alert Histogram CGI

File Name:

histogram.cgi

Description: This CGI is used to report on the availability of hosts and services over a user-specified period of time. In order for this CGI to be of much use, you should enable log rotation and keep archived logs in the path specified by the log_archive_path directive. The CGI uses Thomas Boutell's gd library (version 1.6.3 or higher) to create the histogram image. If you can't seem to find this CGI or if you have get errors when trying to compile or run it, read this FAQ. Authorization Requirements: If you are authorized for all hosts you can view histograms for all hosts and all services. If you are authorized for all services you can view histograms for all services. If you are an authenticated contact you can view histograms for all services and hosts for which you are a contact.

Alert Summary CGI

File Name:

summary.cgi

Description: This CGI provides some generic reports about host and service alert data, including alert totals, top alert producers, etc. Authorization Requirements: If you are authorized for all hosts you can view summary information for all hosts and all services. If you are authorized for all services you can view summary information for all services. If you are an authenticated contact you can view summary information for all services and hosts for which you are a contact.