E-mail
This document describes the configuration details and installation methods for GroundWork Distributed Monitoring Agent (GDMA).
GDMA Configuration
In normal operation, a GDMA host configuration is generated via the configuration tool Monarch using the Externals capability. Global (per-host) configuration parameters are set via a host external property and per-service parameters are set via a service external property, see Configuring Externals.
GDMA uses two configuration files to control its operation. These files share the same structure and command parameters.
Autoconfiguration Config
The file $basedir/config/gdma_auto.conf is a component of the installation image and governs the behavior of the newly installed agent in an unconfigured state. The purpose of this file is to enable the agent to contact the master server and obtain a host configuration file without operator intervention. In general, this file should not be modified unless special circumstances require non-default autoconfiguration behavior. This file is also used to enable the agent to revert to autoconfiguration in the event that the host configuration file becomes corrupted or if the master server becomes unavailable.
Host Config
The file $basedir/config/gwmon_$host.cfg contains the normal-mode configuration for the agent. This file overrides all parameters from the autoconfiguration file when it exists. This file will contain the global (per-host) configuration and per service configuration details for the agent and the services to be monitored.
Global Configuration Parameters
| Parameter Name | Default Value [Valid Values] |
Used by [Poller/Spooler] |
Description |
|---|---|---|---|
| Target_Server | [http://gdma-autohost ][a valid http or https url] |
Poller, Spooler | Defines the address(es) to pull configuration files from and send all check results to. This may be in the form of a comma separated list to send results to multiple targets. If a list is specified, the first element in the list is the one from which configuration files will be pulled. |
| Target_Server_Secondary | no default [a valid http or https url] |
Spooler | Defines the system where the agent will attempt to send check results when the Target_Server is unavailable. |
| GDMAConfigDir | gdma [valid path string] |
Poller | Defines the path where the agent will attempt to pull a valid gwmon_$host.cfg file from. This value is concatenated with Target_Server and the hostname of the target system to identify the configuration file to pull. Example: gdma_auto.conf: Target_Server="http://gdma-autohost" gdma_auto.conf: GDMAConfigDir=”gdma” Target hostname="gdma-test" Would result in the agent pulling its configuration file from "http://gdma-autohost/gdma/gwmon_gdma-test.cfg" |
| Enable_Auto | on [on, off] |
Poller, Spooler | Enables and disables auto configuration mode. This should normally be toggled on in gdma_auto.conf and off in gwmon_$host.cfg |
| GDMA_Auto_Host | gdma-autohost [string conforming to GroundWork/Nagios host object rules] |
Spooler | Host, defined in GroundWork Monitor Configuration, for which GDMA will submit auto configuration messages to the Target_Server as the status of the gdma_auto service. |
| GDMA_Auto_Service | gdma_auto [string conforming to GroundWork/Nagios service object rules] |
Spooler | GroundWork service under which GDMA will submit autoconfiguration messages. |
| Poller_Service | gdma_poller [string conforming to GroundWork/Nagios service object rules] |
Poller | GroundWork service under which GDMA will submit poller messages. |
| Spooler_Service | gdma_spooler [string conforming to GroundWork/Nagios service object rules] |
Spooler | GroundWork service under which GDMA will submit spooler messages. |
| Poller_Status | off [on, off] |
Poller | On: Send poller heartbeat status messages, containing poller statistical data. Off: Do not send any poller heartbeat status messages. |
| Spooler_Status | on [on, off, Updates] |
Spooler | On: Send all spooler status messages. Off: Do not send any spool processing updates. Updates: Only send when there are other checks being submitted (e.g. Do not send status message when the only update is a spooler status message.) |
| ConfigFile_Pull_Cycle | 1 [1-10] |
Poller | Controls how often new configuration information should be pulled from the Master server. The value is a multiple of Poller_Proc_Interval. |
| ConfigPull_Timeout | 10 [1-100] |
Poller | Controls how long in seconds to wait before timing out a configuration file pull attempt. |
| Enable_Local_Logging | off [on:off] |
Poller, Spooler | Enables local logging of events and errors. Default is off. If this is enabled, some provision to clear or rotate logs should be employed. |
| Logdir | /usr/local/groundwork/gdma/log/ or c:\program files\groundwork\gdma\log [absolute directory path] |
Poller, Spooler | Path to write local log files. Must be valid absolute path and writable by agent user. |
| Poller_Proc_Interval | 600 [60-900 seconds] |
Poller | Controls how often the poller engine will run. Also used as a base interval by ConfigFile_Pull_Cycle and Check_(service)_Check_Interval. Modifying this value is not recommended without understanding the full impact on performance data collection and target system overhead for the environment. |
| Poller_Pull_Failure_Interval | 86400 ( 1 Day) [0- 2592000 seconds (0-30Days)] |
Poller | Controls how long the poller will continue to operate in normal mode with the current host configuration after it can no longer pull a configuration file from the master server. When this timer expires, the poller engine will remove the current host configuration file and revert to autoconfiguration mode. Setting this value to 0 disables this feature and the agent will continue to operate in normal mode with the stale configuration file indefinitely. |
| Poller_Plugin_Timeout | 5 [0- 900 seconds] |
Poller | Controls how long the poller will wait for a plugin to execute, if a per-service Check_(service)_Timeout value is not specified. |
| Poller_Plugin_Directory | /usr/local/groundwork/gdma/libexec/ or c:\program files\groundwork\gdma\libexec [absolute directory path] |
Poller | Path to local plugins |
| Spooler_Batch_Size | 20 [integer >= 5] |
Spooler | Defines the max NSCA batch size to use when transmitting results to each master server. |
| Spooler_Max_Retries | 10 [1 <= integer <= 100] |
Spooler | Attempt transmission of results this many times before being purging. Multiple of Spooler_Proc_Interval time. |
| Spooler_Retention_Time | 900 [1 <= integer <= 900] |
Spooler | Unsent spooled results older than this will be purged. |
| Spooler_NSCA_Config | /usr/local/groundwork/gdma/config/send_nsca.cfg or c:\Program Files (x86)\groundwork\gdma\config\send_nsca.cfg | Spooler | This is the absolute path to the configuration file for send_nsca. |
| Spooler_NSCA_Port | 5667 [valid tcp port number] |
Spooler | Port to use when transmitting spooled results. This port number must match the bronx.cfg listener_port value on the master server (each individual Target_Server machine). |
| Spooler_NSCA_Timeout | 10 [1-30 seconds] |
Spooler | NSCA send timeout |
| Spooler_NSCA_Program | /usr/local/groundwork/common/bin/send_nsca or c:\Program Files\groundwork\gdma\bin\send_nsca.exe | Spooler | Location of send nsca program |
| Spooler_Proc_Interval | 180 [60-900 seconds] |
Spooler | Controls how often the spooler engine will run. Also used as a base interval by Spooler_Max_Retries. |
| GDMA_Multihost | off [on, off] |
Poller | Enable Multihost (windows child) behavior. See Windows Child How to for details. |
| Use_Long_Hostname | no default [on, off] |
Poller, Spooler | Controls whether the poller and spooler use a fully-qualified hostname for the gwmon_$host.cfg filename, and the hostname under which GDMA reports its results. A site which wants to force the use of fully-qualified hostnames should set this option on in the host externals for those hosts. See GDMA Advanced Features for details. If this parameter is left undefined, GDMA will first try to use a long hostname (FQDN), and if that fails, it will try a short (unqualified) hostname. This provides a convenient automatic failover mechanism. |
| Warning_Threshold | 60 [1 <= integer <= 100] |
Poller | This is a threshold, specified as an integer percentage, that will generate a warning from the poller on the service specified in the Poller_Service parameter if the polling cycle takes longer than the specified percentage of the time specified in the Poller_Proc_Interval. Default is 60, so a warning status will be generated if more than 60% of the Poller_Proc_Interval is used for polling. |
| Critical_Threshold | 80 [1 <= integer <= 100] |
Poller | This is a threshold, specified as an integer percentage, that will generate a critical status from the poller on the service specified in the Poller_Service parameter if the polling cycle takes longer than the specified percentage of the time specified in the Poller_Proc_Interval. Default is 80, so a critical status will be generated if more than 80% of the Poller_Proc_Interval is used for polling. |
Per Service Configuration Parameters
The parameters in this section are generally provided via host externals and service externals which are managed via the Monarch configuration tool.
The (service) component of the following parameter names must be substituted with a name for the service, followed by an instance number in square brackets, numbered starting with 1. The (service) name specified here need not exactly match the name of the service as it is known elsewhere in Monarch or Nagios. For instance, a single instance of the gdma_wmi_disk_C service would be listed as gdma_wmi_disk_C[1], and it might have some or all of the following parameters defined where the Check_gdma_wmi_disk_C[1]_Service value might be gdma_21_wmi_disk_C (the name by which this service would be known to GroundWork Monarch and Nagios):
- Check_gdma_wmi_disk_C[1]_Enable
- Check_gdma_wmi_disk_C[1]_Service
- Check_gdma_wmi_disk_C[1]_Command
- Check_gdma_wmi_disk_C[1]_Timeout
- Check_gdma_wmi_disk_C[1]_Check_Interval
| Parameter Name | Default Value [Valid Values] |
Used by Spooler/Poller | Description |
| Check_(service)_Enable | on [on, off] |
Poller | Enable or disable this service check |
| Check_(service)_Service | n/a [string conforming to GroundWork/Nagios service object rules] |
Poller | GroundWork/Nagios service name |
| Check_(service)_Command | n/a [command definition to be executed by the poller] |
Poller | Command definition |
| Check_(service)_Timeout | 5 [0- 900 seconds] |
Poller | Controls how long the poller will wait for this service command to execute. |
| Check_(service)_Check_Interval | n/a [positive integer] |
Poller | Controls how often the service check will run, as a positive integral multiple of Poller_Proc _Interval. Defaults to 1 (run during every poller cycle) if not specified. |
Error and Status Messaging
Unless configured with Enable_Local_Logging = on GDMA will not produce any log output on the target system. Normal messaging is returned to the Master system via the standard spooling and NSCA transmission methods.
- gdma_auto, missing configuration - Indicates unconfigured GDMA host or corrupt configuration file.
- gdma-autohost;gdma_auto;3;No configuration file: my_host [192.168.5.13] running MSWin32 5.00
- gdma_spooler startup message - Indicates normal startup
- my_host;gdma_spooler;0;Spool processor 1.0 started at Wednesday January 6 16:55:27 2010
- gdma_spooler status message - Indicates normal operation
- my_host;gdma_spooler;0;Spooler transmitted 11 results in 0 secs
- gdma_spooler transmission failure - Indicates that spooler failed in transmitting results
- my_host;gdma_spooler;2;Failed to transmit 1 results to 192.168.5.74
- gdma_spooler purge message - Indicates that results are being expired from the spool
- my_host;gdma_spooler;1;Retention timer 900 reached for 38 messages, messages purged
- gdma_poller status message - Indicates normal operation
- my_host;gdma_poller;0;OK Poller processed 9 checks in 8.547 secs Using 1.42% of 600 sec Polling Interval
- gdma_poller startup message Indicates normal startup
- my_host;gdma_poller;0;Poller 1.0 started at Wednesday January 6 17:01:08 2010
- gdma_poller config change message - Indicates that a configuration change has been detected.
- my_host;gdma_poller;1;Configuration change detected :C:\groundwork\gdma\config\gwmon_my_host.cfg at Wednesday January 6 16:13:06 2010
GDMA Switches
gdma_poll and gdma_spool_processor provide the following switches for troubleshooting. These should not be used in normal operation.
Poller Switches
The GDMA poller agent monitors system statistics on this server, and dumps the results to a spool file. Available options can be shown via a command such as:
/usr/local/groundwork/perl/bin/perl gdma_poll.pl -h
Options:
| -c <CONFIG FILE> | Config file containing monitoring parameters. |
| -a <AUTOCONF FILE> | File with default settings. Must contain a target server address. |
| -l <LOG DIR> | Full path for log directory for this script |
| -d <DEBUGLEVEL> | Debug mode. Will log additional messages to the log file; <DEBUGLEVEL> should be 1 for moderate logging, or 2 for additional detail. |
| -h | Displays help message. |
| -x | Run once. If this option is not selected, run continually with sleep. |
| -i | Run interactively - shows output to the Command Line Interface (CLI; used in non-service mode) as well as to the log file. |
| -v | Show version. |
Spooler Switches
The GDMA spool processor picks up results from the spool file and sends them back to the GroundWork server(s) using NSCA. Available options can be shown via a command such as:
/usr/local/groundwork/perl/bin/perl gdma_spool_processor.pl -h
Options:
| -c <CONFIG FILE> | Config file containing monitoring parameters. |
| -a <AUTOCONF FILE> | File with default settings. Must contain a target server address. |
| -l <LOG DIR> | Log directory for this script, relative to GDMA HOME. |
| -d <DEBUGLEVEL> | Debug mode. Will log additional messages to the log file; <DEBUGLEVEL> should be 1 for moderate logging, or 2 for additional detail. |
| -h | Displays help message. |
| -x | Run once. If this option is not selected, run continually with sleep. |
| -i | Run interactively - shows output to the Command Line Interface (CLI; used in non-service mode) as well as to the log file. |
| -v | Show version. |