## CGI Configuration File Options

Notes

When creating and/or editing configuration files, keep the following in mind:

1. Lines that start with a '#' character are taken to be comments and are not processed
2. Variables names must begin at the start of the line - no white space is allowed before the name
3. Variable names are case-sensitive

Sample Configuration

A sample CGI configuration file can be created by running the 'make config' command. The default name of the CGI configuration file is nscgi.cfg.

Index

Main configuration file location
Physical HTML path
URL HTML path
Process check command
Authentication usage
Default user name
System/process information access
System/process command access
Configuration information access
Global host information access
Global host command access
Global service information access
Global service command access
Extended host information
Extended service information
Statusmap CGI background image
Statuswrl CGI include world
Alert window suppression
CGI refresh rate
Audio alerts

Main Configuration File Location

Format: | main_config_file=<file_name>
Example: | main_config_file=/usr/local/netsaint/etc/netsaint.cfg

This specifies the location of your main configuration file. The CGIs need to know where to find this file in order to get information about configuration information, current host and service status, etc.

Physical HTML Path

Format: | physical_html_path=<path>
Example: | physical_html_path=/usr/local/netsaint/share

This is the physical path where the HTML files for NetSaint are kept on your workstation or server. NetSaint assumes that the documentation and images files (used by the CGIs) are stored in subdirectories called docs/ and images/, respectively.

URL HTML Path

Format: | url_html_path=<path>
Example: | url_html_path=/netsaint

If, when accessing NetSaint via a web browser, you point to an URL like http://www.myhost.com/netsaint, this value should be /netsaint. Basically, its the path portion of the URL that is used to access the NetSaint HTML pages.

Process Check Command

Format: | process_check_command=<command_line>
Example: | process_check_command=/usr/local/netsaint/libexec/check_netsaint /usr/local/netsaint/var/status.log 5 '/usr/local/netsaint/bin/netsaint -d /usr/local/netsaint/etc/netsaint.cfg'

This is the command that the CGIs should use to check the status of the NetSaint process. This provides the CGIs (as well as yourself) with some idea of whether or not NetSaint is still running. If the CGIs cannot determine whether or not NetSaint is running on the local machine, some features like external commands in the extended information and command CGIs may not be available. The process check command that you specify should follow the same guidelines that are required of the plugins.

Notes:

- The check_netsaint plugin is ideal for the purpose of checking both the status of the NetSaint process and the "freshness" of the data in the status log. I would highly recommend using it in this situation.
- If you are running a chroot'ed web server, you will have to place the plugin (or whatever you're using) in the sbin/ subdirectory of your NetSaint installation.

Authentication Usage

Format: | use_authentication=<0/1>
Example: | use_authentication=1

This option controls whether or not the CGIs will use the authentication and authorization functionality when determining what information and commands users have access to. I would strongly suggest that you use the authentication functionality for the CGIs. If you decide not to use authentication, make sure to remove the command CGI to prevent unauthorized users from issuing commands to NetSaint. The CGI will not issue commands to NetSaint if authentication is disabled, but I would suggest removing it altogether just to be on the safe side. More information on how to setup authentication and configure authorization for the CGIs can be found here.

- 0 = Don't use authentication functionality
- 1 = Use authentication and authorization functionality (default)

Default User Name

Format: | default_user_name=<username>
Example: | default_user_name=guest

Setting this variable will define a default username that can access the CGIs. This allows people within a secure domain (i.e., behind a firewall) to access the CGIs without necessarily having to authenticate to the web server. You may want to use this to avoid having to use basic authentication if you are not using a secure server, as basic authentication transmits passwords in clear text over the Internet.

Important: Do not define a default username unless you are running a secure web server and are sure that everyone who has access to the CGIs has been authenticated in some manner! If you define this variable, anyone who has not authenticated to the web server will inherit all rights you assign to this user!

System/Process Information Access

Format: | authorized_for_system_information=<user1>,<user2>,<user3>,...<usern>
Example: | authorized_for_system_information=netsaintadmin,theboss

This is a comma-delimited list of names of authenticated users who can view system/process information in the extended information CGI. Users in this list are not automatically authorized to issue system/process commands. If you want users to be able to issue system/process commands as well, you must add them to the authorized_for_system_commands variable. More information on how to setup authentication and configure authorization for the CGIs can be found here.

System/Process Command Access

Format: | authorized_for_system_commands=<user1>,<user2>,<user3>,...<usern>
Example: | authorized_for_system_commands=netsaintadmin

This is a comma-delimited list of names of authenticated users who can issue system/process commands via the command CGI. Users in this list are not automatically authorized to view system/process information. If you want users to be able to view system/process information as well, you must add them to the authorized_for_system_information variable. More information on how to setup authentication and configure authorization for the CGIs can be found here.

Configuration Information Access

Format: | authorized_for_configuration_information=<user1>,<user2>,<user3>,...<usern>
Example: | authorized_for_configuration_information=netsaintadmin

This is a comma-delimited list of names of authenticated users who can view configuration information in the configuration CGI. Users in this list can view information on all configured hosts, host groups, services, contacts, contact groups, time periods, and commands. More information on how to setup authentication and configure authorization for the CGIs can be found here.

Global Host Information Access

Format: | authorized_for_all_hosts=<user1>,<user2>,<user3>,...<usern>
Example: | authorized_for_all_hosts=netsaintadmin,theboss

This is a comma-delimited list of names of authenticated users who can view status and configuration information for all hosts. Users in this list are also automatically authorized to view information for all services. Users in this list are not automatically authorized to issue commands for all hosts or services. If you want users able to issue commands for all hosts and services as well, you must add them to the authorized_for_all_host_commands variable. More information on how to setup authentication and configure authorization for the CGIs can be found here.

Global Host Command Access

Format: | authorized_for_all_host_commands=<user1>,<user2>,<user3>,...<usern>
Example: | authorized_for_all_host_commands=netsaintadmin

This is a comma-delimited list of names of authenticated users who can issue commands for all hosts via the command CGI. Users in this list are also automatically authorized to issue commands for all services. Users in this list are not automatically authorized to view status or configuration information for all hosts or services. If you want users able to view status and configuration information for all hosts and services as well, you must add them to the authorized_for_all_hosts variable. More information on how to setup authentication and configure authorization for the CGIs can be found here.

Global Service Information Access

Format: | authorized_for_all_services=<user1>,<user2>,<user3>,...<usern>
Example: | authorized_for_all_services=netsaintadmin,theboss

This is a comma-delimited list of names of authenticated users who can view status and configuration information for all services. Users in this list are not automatically authorized to view information for all hosts. Users in this list are not automatically authorized to issue commands for all services. If you want users able to issue commands for all services as well, you must add them to the authorized_for_all_service_commands variable. More information on how to setup authentication and configure authorization for the CGIs can be found here.

Global Service Command Access

Format: | authorized_for_all_service_commands=<user1>,<user2>,<user3>,...<usern>
Example: | authorized_for_all_service_commands=netsaintadmin

This is a comma-delimited list of names of authenticated users who can issue commands for all services via the command CGI. Users in this list are not automatically authorized to issue commands for all hosts. Users in this list are not automatically authorized to view status or configuration information for all hosts. If you want users able to view status and configuration information for all services as well, you must add them to the authorized_for_all_services variable. More information on how to setup authentication and configure authorization for the CGIs can be found here.

Extended Host Information

Format: | hostextinfo[<host_name>]=<notes_url>;<icon_image>;<vrml_image>;<gd2_image>;<alt_tag>;<x_2d>,<y_2d>;<x_3d>,<y_3d>,<z_3d>
Example: | hostextinfo[router3]=/hostinfo/router3.html;cat5000.gif;cat5000.jpg;cat5000.gd2;Cisco Catalyst 5000;100,50;3.5,2.0,5.5

Extended host information entries are basically used to make the output from the status, statusmap, statuswrl, and extinfo CGIs look pretty. They have no effect on monitoring and are completely optional.

<host_name> | This is a short name of the host, as defined in the host configuration file.

<notes_url>

This is an optional URL that can be used to provide more information about the host. If you specify an URL, you will see a link that says "Notes About This Host" in the extended information CGI (when you are viewing information about the specified host). Any valid URL can be used. If you plan on using relative paths, the base path will the the same as what is used to access the CGIs (i.e. /cgi-bin/netsaint/). This can be very useful if you want to make detailed information on the host, emergency contact methods, etc available to other support staff.

<icon_image> | The name of a GIF, PNG, or JPG image that should be associated with this host. This image will be displayed in the status and extended information CGIs. The image will look best if it is 40x40 pixels in size. Images for hosts are assumed to be in the logos/ subdirectory in your HTML images directory (i.e. /usr/local/netsaint/share/images/logos).

<vrml_image>

The name of a GIF, PNG, or JPG image that should be associated with this host. This image will be used as the texture map for the specified host in the statuswrl CGI. Unlike the image you use for the <icon_image> variable, this one should probably not have any transparency. If it does, the host object will look a bit wierd. Images for hosts are assumed to be in the logos/ subdirectory in your HTML images directory (i.e. /usr/local/netsaint/share/images/logos).

<gd2_image>

The name of a GD2 format image that should be associated with this host. This image will be used in the image created by the statusmap CGI. GD2 images can be created from PNG images by using the pngtogd2 utility supplied with Thomas Boutell's gd library. The GD2 images should be created in uncompressed format in order to minimize CPU load when the statusmap CGI is generating the network map image. The image will look best if it is 40x40 pixels in size. You can leave these option blank if you are not using the statusmap CGI. Images for hosts are assumed to be in the logos/ subdirectory in your HTML images directory (i.e. /usr/local/netsaint/share/images/logos).

<alt_tag> | An optional string that is used in the ALT tag of the image specified by the <icon_image> argument. The ALT tag is used in both the status and statusmap CGIs.

<x_2d>,<y_2d>

Coordinates to use when drawing the host in the statusmap CGI. Coordinates should be given in positive integers, as the correspond to physical pixels in the generated image. The origin for drawing (0,0) is in the upper left hand corner of the image and extends in the positive x direction (to the right) along the top of the image and in the positive y direction (down) along the left hand side of the image. For reference, the size of the icons drawn is usually about 40x40 pixels (text takes a little extra space). The coordinates you specify here are for the upper left hand corner of the host icon that is drawn. Note: Don't worry about what the maximum x and y coordinates that you can use are. The CGI will automatically calculate the maximum dimensions of the image it creates based on the largest x and y coordinates you specify. Also of note, if you want to create 2-D coordinates for use in drawing the hosts in the statusmap CGI by visually moving hosts around, I would suggest giving David Kmoch's Saintmap addon a spin.

<x_3d>,<y_3d>,<z_3d> | Coordinates to use when drawing the host in the statuswrl CGI. Coordinates can be positive or negative real numbers. The origin for drawing is (0.0,0.0,0.0). For reference, the size of the host cubes drawn is 0.5 units on each side (text takes a little more space). The coordinates you specify here are used as the center of the host cube.

Extended Service Information

Format: | serviceextinfo[<host_name>;<svc_description>]=<notes_url>;<icon_image>;<alt_tag>
Example: | serviceextinfo[router3;PING]=/serviceinfo/router3.html#PING;ping.gif;PING Stats

Extended service information entries are basically used to make the output from the status and extinfo CGIs look pretty. They have no effect on monitoring and are completely optional.

<host_name> | This is a short name of the host associated with the service, as specified in the service definition.
<svc_description> | This is a description of the service, as specified in the service definition.

<notes_url>

This is an optional URL that can be used to provide more information about the service. If you specify an URL, you will see a link that says "Notes About This Service" in the extended information CGI (when you are viewing information about the specified service). Any valid URL can be used. If you plan on using relative paths, the base path will the the same as what is used to access the CGIs (i.e. /cgi-bin/netsaint/). This can be very useful if you want to make detailed information on the service, emergency contact methods, etc available to other support staff.

<icon_image> | The name of a GIF, PNG, or JPG image that should be associated with this service. This image will be displayed in the status and extended information CGIs. The image will look best if it is 40x40 pixels in size. Images for hosts are assumed to be in the logos/ subdirectory in your HTML images directory (i.e. /usr/local/netsaint/share/images/logos).
<alt_tag> | An optional string that is used in the ALT tag of the image specified by the <icon_image> argument. The ALT tag is used in the status CGI.

Statusmap CGI Background Image

Format: | statusmap_background_image=<gd2_image>
Example: | statusmap_background_image=statusmapbg.gd2

This option allows you to specify an image to be used as a background in the statusmap CGI. It is assumed that the image resides in the HTML images path (i.e. /usr/local/netsaint/share/images). This path is automatically determined by appending "/images" to the path specified by the physical_html_path directive. Note: The image file must be in GD2 format (preferably in uncompressed format)!

Statuswrl CGI Include World

Format: | statuswrl_include=<vrml_file>
Example: | statuswrl_include=myworld.wrl

This option allows you to include your own objects in the generated VRML world. It is assumed that the file resides in the path specified by the physical_html_path directive. Note: This file must be a fully qualified VRML world (i.e. you can view it by itself in a VRML browser).

Alert Window Suppression

Format: | suppress_alert_window=<0/1>
Example: | suppress_alert_window=1

This option allows you to specify whether or not you want to permanently suppress the host alert window in the status CGI. Normally the alert window will be displayed if one or more hosts is down or unreachable.

- 0 = Don't suppress alert window, allow it to be displayed (default)
- 1 = Don't display alert window at any time

CGI Refresh Rate

Format: | refresh_rate=<rate_in_seconds>
Example: | refresh_rate=90

This option allows you to specify the number of seconds between page refreshes for the status, statusmap, and extinfo CGIs.

Audio Alerts

Formats: | host_unreachable_sound=<sound_file> host_down_sound=<sound_file> service_critical_sound=<sound_file> service_warning_sound=<sound_file> service_unknown_sound=<sound_file>
Examples: | host_unreachable_sound=hostu.wav host_down_sound=hostd.wav service_critical_sound=critical.wav service_warning_sound=warning.wav service_unknown_sound=unknown.wav

These options allow you to specify an audio file that should be played in your browser if there are problems when you are viewing the status CGI. If there are problems, the audio file for the most critical type of problem will be played. The most critical type of problem is on or more unreachable hosts, while the least critical is one or more services in an unknown state (see the order in the example above). Audio files are assumed to be in the media/ subdirectory in your HTML images directory (i.e. /usr/local/netsaint/share/media).