This page describes the configuration details for GDMA Auto Registration.

GDMA Configuration

This document describes the configuration details and installation methods for GroundWork Distributed Monitoring Agent (GDMA).

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 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 un-configured 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 (per host) Configuration Parameters

Parameter NameDefault Value (Valid Values)
Used by Poller/Spooler
Description

Auto_Register_Attempts

fibonacci (never, once, arithmetic, exponential, fibonacci, or periodic)

Poller

This option should not be set in host externals; it has no business being managed on the server, as it controls behavior of the GDMA client before the host externals file is downloaded from the server. So this option should appear only in the client's own gdma_auto.conf file.

Specifies what sort of algorithm should be used to decide whether repeated auto-registration attempts should be made, once an initial attempt has failed. This parameter is available starting with GDMA 2.3.1.

The arithmetic, exponential, and fibonacci settings specify increasing delays between successive attempts to auto-register. In each of these cases, the increasing delays are capped by the Auto_Register_Max_Interval setting. The standard default value for Auto_Register_Attempts is fibonacci, which invokes several quick retries and then a slow backoff until the full Auto_Register_Max_Interval period is reached. This allows rapid response when it counts most, eventual automatic recovery if the server doesn't respond for a long time, and low loading for requests that will never be successfully answered.

never: Make no attempts at all, not even an initial attempt

once: Make just one attempt, with no follow-ups.

arithmetic: Make further attempts with the following full-cycle delays between cycles where auto-registration is tried again: 1, 2, 3, 4, 5, 6, etc.

exponential: Make further attempts with the following full-cycle delays between cycles where auto-registration is tried again: 1, 2, 4, 8, 16, 32, etc.

fibonacci: Make further attempts with the following full-cycle delays between cycles where auto-registration is tried again: 1, 1, 2, 3, 5, 8, etc., according to the standard Fibonacci sequence.

periodic: Make further attempts where auto-registration is tried again, with all subsequent attempts spaced by the Auto_Register_Max_Interval setting.

Auto_Register_Host_Profile

empty string (The name of a host profile on the GroundWork server, or an empty string. The usual value is a per-platform host profile, namely one of gdma-aix-host, gdma-linux-host, gdma-solaris-host, or gdma-windows-host. But you may specify another host profile name, if you wish.)

Poller

This option should not be set in host externals; it has no business being managed on the server, as it controls behavior of the GDMA client before the host externals file is downloaded from the server. So this option should appear only in the client's own gdma_auto.conf file.

The host profile to be applied to this machine's monitoring setup during auto-registration. This value is optional; if missing or left blank, the host profile will be defaulted on the server. This parameter is available starting with GDMA 2.3.0.

Auto_Register_Max_Interval

86400 (1-1000000000 seconds)

Poller

This option should not be set in host externals; it has no business being managed on the server, as it controls behavior of the GDMA client before the host externals file is downloaded from the server. So this option should appear only in the client's own gdma_auto.conf file.

Defines the password used for auto-registration attempts. If this value is missing or empty, auto-registration will be disabled, and the client will fall back to using the older auto-configuration protocol. This parameter is available starting with GDMA 2.3.0.

Auto_Register_Pass

no default (the password corresponding to Auto_Register_User, or an empty string)

Poller

This option should not be set in host externals; it has no business being managed on the server, as it controls behavior of the GDMA client before the host externals file is downloaded from the server. So this option should appear only in the client's own gdma_auto.conf file.

Defines the password used for auto-registration attempts. If this value is missing or empty, auto-registration will be disabled, and the client will fall back to using the older auto-configuration protocol. This parameter is available starting with GDMA 2.3.0.

Auto_Register_Service_Profile

empty string (The name of a service profile on the GroundWork server, or an empty string.)

Poller

This option should not be set in host externals; it has no business being managed on the server, as it controls behavior of the GDMA client before the host externals file is downloaded from the server. So this option should appear only in the client's own gdma_auto.conf file.

The service profile to be applied to this machine's monitoring setup during auto-registration. This value is optional; if missing or left blank, no extra service profile (beyond any that are included in the host profile) will be applied. This parameter is available starting with GDMA 2.3.0.

Auto_Register_User

no default (a GroundWork Monitor username reserved for this purpose, or an empty string)

Poller

This option should not be set in host externals; it has no business being managed on the server, as it controls behavior of the GDMA client before the host externals file is downloaded from the server. So this option should appear only in the client's own gdma_auto.conf file.

Defines the username used for auto-registration attempts. If this value is missing or empty, auto-registration will be disabled, and the client will fall back to using the older auto-configuration protocol. This parameter is available starting with GDMA 2.3.0.

Log_Questionable_Certs

on (on, off)

Poller

Specifies whether TLS certificates provided by the server should be saved and analyzed, with the analysis placed in the poller logfile. This is a good idea, because it makes debugging problems with certs much easier.

Allow_Downloaded_Self_Signed_Certs

on (on, off)

Poller

Specifies whether self-signed certs provided by the server should be accepted and trusted (A BAD IDEA IN GENERAL, TO BE USED ONLY DURING PROOF-OF-CONCEPT FIRST DEPLOYMENTS OF GDMA). THIS DEFAULT MAKES YOUR GDMA CLIENT INSECURE, see Obtaining and installing TLS certificates with options. This option will have no effect unless the Log_Questionable_Certs option is enabled.

Flag_Downloaded_Self_Signed_Certs

on (on, off)

Poller

Specifies whether check results manufactured for the service specified by the Poller_Service directive will be prefixed by INSECURE: to provide some slightly-annoying notice that you should be not really be using self-signed certs. Such prefixing may only last until the GDMA poller is bounced, so it should not be depended on for an ongoing report of insecure operation.

A good idea to provide some (though imperfect) notice that you are running in an insecure mode of operation. Disabling this option requires an explicit action on the part of the customer, who thereby assumes all risk when operating in such a mode. 

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_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

Enable_Auto_Setup

off (on, off) 

Poller

This option should not be set in host externals; it has no business being managed on the server, as it controls behavior of the GDMA client before the host externals file is downloaded from the server. So this option should appear only in the client's own gdma_auto.conf file.

Enables and disables GDMA Auto-Setup mode. For Auto-Setup to operate, the Auto_Register_User and Auto_Register_Pass parameters must also be set. This parameter is available starting with GDMA 2.6.1. 

Also, if you intend to run in Auto-Setup mode, Auto-Registration should be further blocked from running inadvertently if the Enable_Auto_Setup value is ever accidentally changed. That can be done either by setting  Auto_Register_Attempts to "never", or by setting Auto_Register_Host_Profile to some invalid value like "none".

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.

As of GDMA 2.6.1, we have automatic internally-driven log rotation active if local logging is enabled, and logging can be enabled without fear of unlimited logfile growth.

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.

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"

GDMA_Multihost

off (on, off)

Poller

Enable Multihost behavior (monitoring of multiple hosts from a single GDMA client machine).

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.

Max_Server_Redirects

5 (unsigned integer)

Poller

Specifies the maximum number of HTTP(S) redirects the client will tolerate when fetching data from the server and sending automated agent registration requests. A non-zero value helps with allowing redirection when transitioning an entire infrastructure from use of HTTP to use of HTTPS, for instance. The Max_Server_Redirects value can be set to 0 to completely disallow redirects, for the highest level of security.

Because many of the uses of this parameter involve actions that precede having an externals file from the server in hand, it really only makes sense to set this parameter in the client's own gdma_auto.conf file, not in host externals.

This option is available starting with the GDMA 2.3.2 release.

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

Poller_Proc_Interval

600 (10-3600 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_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_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_NSCA_Timeout

10 (1-30 seconds)

Spooler

NSCA send timeout

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.

Spooler_Retention_Time

900 (1 <= integer <= 900)

Spooler

Unsent spooled results older than this will be purged.

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.

Forced_Hostname

The exact hostname (unqualified or fully-qualified, as specified) to be used in place of any dynamic determination of the hostname.

Poller, Spooler

This is a directive used to force determination of the GDMA client hostname to a fixed value. It is fully supported in the GDMA 2.3.0 release, on all platforms.

Use_Long_Hostname

undefined (on, off, or undefined (not specified))

(Note: GDMA 2.3.0 inappropriately set this option to "on" in the freshly installed gdma_auto.conf file; that setting is not appropriate for many customers. Users may wish to install GDMA 2.3.1 instead, which does not define this option by default, or comment out the value in the config file.)

Poller, Spooler

Controls whether the poller and spooler use a fully-qualified hostname for thegwmon_$host.cfgfilename, and the hostname under which GDMA reports its results.

"on"
means that the GDMA client will attempt to use its fully-qualified hostname when retrieving its externals file from the GroundWork Monitor server and when reporting check results.

"off"
means that the GDMA client will attempt to use its unqualified hostname in those circumstances.

If this option is not set at all,
the GDMA client will attempt to use a fully-qualified hostname when retrieving its externals file, then fall back to using an unqualified hostname if that fails. Whichever form succeeds will be used for reporting check results.

A site which wants to force the use of fully-qualified hostnames should set this option "on" in the gdma_auto.conf file for those hosts. Setting this parameter in host externals is too late and thus should be avoided, because this parameter affects the name of the downloaded configuration file that contains those host externals. 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.

The setting of this option will be effectively ignored if the Forced_Hostname option is in play. (Forced_Hostname is to be used sparingly in manual configurations, only in exceptional conditions when the local configuration simply cannot be set up to correctly determine the hostname by ordinary automatic means.) In particular, a successful auto-registration creates an extra gdma_override.conf file that contains a Forced_Hostname directive specifying the GDMA client hostname as determined by the GroundWork Monitor server. The auto-registration code on the server has its own controls over the format of the hostnames it returns to clients, and those controls take precedence over the Use_Long_Hostname option on the client when the server determines the desired client hostname. See FAQs for Auto Registration for a detailed description.

Use_Lowercase_Hostname

off (on, off)

Windows hosts hostnames in CAPS. If you have Windows hosts hostnames using uppercase letters you may need to set a flag within the C:\Program Files (x86)\groundwork\gdma\config\gdma_auto.conf file. To do this, edit the gdma_auto.conf file on the Windows host, and uncomment the line # Use_Lowercase_Hostname = "on".

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.

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.

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 NameDefault 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

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.

Related Resources