GDMA Advanced

Version 1 by Bren Eckles
on Mar 30, 2015 21:33.

compared with
Version 2 by Bren Eckles
on Apr 08, 2017 12:21.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (148)

View Page History
h6. Contents

This section is designed for those that have used GDMA previously, have it already set up and working, and would like to use the advanced features of the new version.
{toc:minLevel=4|maxLevel=54|printable=false}

h4. 1.0 Detailed Installation and Setup

h5. 1.1 Controlling Poller and Spooler Status Messages
h5. 1.1 Controlling poller and spooler status messages

The GDMA profiles contain services called {{gdma_poller}} and {{gdma_spooler}}. By default, these services will receive status messages from the poller and spooler processes. These messages tell you about how much time the poller is using to perform the checks, and whether that time is excessive. The spooler reports transmission failures, and statistics about how many messages it sent, and if any messages were purged, etc. The state of the services will change, as well, based on whether there is an error to report.
* *Warning_Threshold, Critical_Threshold=(integer percent)* \- Applied to the poller, these control when you will get notified that there is a problem with the poller chewing up more than the indicated percentage of its cycle time to perform a single check. That situation is something you probably want to know about, since it means you may be trying to check too frequently, or to check too many services. Remember, _GDMA_ is designed to use very little CPU resources, so it has some built-in waits, and (except in multi-host mode), it actually does not perform checks in parallel. If you are getting close to the limit and you can manage it, you can change these thresholds from their defaults (60 and 80 percent) to cut down on false positives for these services.

h5. 1.2 Using Fully Qualified Host Names
h5. 1.2 Using fully qualified host names

If you manage multiple data centers, or if you have domains of systems that you want to use GDMA on, and want those systems to report all to the same GroundWork server, you may run into a situation where the same short host name is used for more than one host. GroundWork Monitor uses Nagios, which requires that host names be unique. For GDMA, this presents a problem, as the host name is automatically determined on the GDMA system, so it is possible to have two systems reporting status, and the GroundWork server will only represent them as one.
To enable this feature, use the parameter {{Use_Long_Hostname}}. Set this parameter to {{"on"}} in the {{gdma_auto.conf}} file on the GDMA client, and change the host name in GroundWork Monitor Configuration to be the fully qualified name. This will change the way GDMA reports its results for services, and though the first run with the new settings will generate a single spooler messages under the old (short) hostname, subsequent cycles will have the long fully-qualified name used for poller and spooler messages as well.

h5. 1.3 Forcing Determination of GDMA Client Hostname
h5. 1.3 Forcing determination of GDMA client hostname

The {{Forced_Hostname}} directive is used to force determination of the GDMA client hostname to a fixed value. This option is fully supported in the latest GDMA release, on all platforms. {{Forced_Hostname}} is an optional directive in the GDMA client config files. The value is the exact hostname (unqualified or fully-qualified, as specified) to be used in place of any dynamic determination of the hostname. GDMA will lowercase the supplied value before use, to correspond to the uniform use of lowercase hostnames in the rest of GDMA.

The {{Forced_Hostname}} directive is used to force determination of the GDMA client hostname to a fixed value. This option is fully supported in the latest GDMA release, on all platforms. Forced_Hostname is an optional directive in the GDMA client config files. The value is the exact hostname (unqualified or fully-qualified, as specified) to be used in place of any dynamic determination of the hostname. GDMA will lowercase the supplied value before use, to correspond to the uniform use of lowercase hostnames in the rest of GDMA.

Additionally, this option is used in support of GDMA auto-registration so that when a GDMA client successfully registers itself with the GroundWork server, the hostname that the server determined was correct for this client gets returned to the client. The client then stashes that hostname as the value of the {{Forced_Hostname}} option in the new {{gdma/config/gdma_override.conf}} file, so both the poller (which received the hostname from the server) and the spooler (which passively accepts this instruction) know the proper hostname to use even if those components are bounced. This way, the base {{gdma_auto.conf}} configuration file is never modified by the auto-registration processing. When the {{Forced_Hostname}} is used in this manner for auto-registration, any value, which may have been manually set in the {{gdma/config/gdma_auto.conf}} file, will be ignored in favor of the value in the {{gdma/config/gdma_override.conf}} file.

Also note that the GDMA auto-registration feature provides special support on the server for forcing the assignment of hostnames to particular values for certain client hosts, via the {{<hardcoded_hostnames>}} section of the {{config/register_agent.properties}} file.

{warning:title=Renaming a GDMA Host}\\
Known issue:
{note:title=KNOWN ISSUE - Renaming a GDMA Host}{note}
* Known Issue:
Using the Rename button, located at the bottom of the host detail screen (Configuration > Hosts > Hosts > {hostgroup\} > {host\} > Detail), to rename a GDMA host will cause the host to stop receiving checks. This action fails to overwrite the agent configuration on the remote machine and restart the remote agent to allow it to pull the new configuration. Once the workaround below has been completed, a new configuration file will present itself with the corrected name, and the forced config file is also updated with the correct name.
!rename_host.jpg|border=1!\\
\\
Workaround:
!bookshelf_gdma_advanced_01.jpg|thumbnail!
* Workaround:
This must happen on the GDMA client only +after+ the next Commit after the server-side Rename occurs.&nbsp; That way, the new setup will be in place on the server when the updated client reaches for it. Also note that, after the Commit, the administrator should re-build externals, so make sure they are all up-to-date, before making changes on the GDMA client.
** Stop GDMA service
** Delete the forced config and the host named config files
** Start GDMA service
* GDMA client files to delete:
** {{gdma/config/gdma_override.conf}} (which file is supplied to the GDMA client by the GroundWork server during auto-registration, and holds a {{Forced_Hostname}} directive specifying the form and content of the hostname that the client is to use when interacting with the server)
** {{gdma/config/gwmon\_}}{{{}{_}hostname{_}{}}}{{.cfg}} (which file, named using the precise form of the client hostname which the client should be using, is supplied to the GDMA client by the GroundWork server, and contains host and service externals from the server which are relevant to this client, note this is the actual hostname of the GDMA client, not the literal characters "hostname")

This must happen on the GDMA client only *after* the next Commit after the server-side Rename occurs.&nbsp; That way, the new setup will be in place on the server when the updated client reaches for it. Also note that, after the Commit, the administrator should re-build externals, so make sure they are all up-to-date, before making changes on the GDMA client.
* Stop GDMA service
* Delete the forced config and the host named config files
* Start GDMA service
h5. 1.4 Checking multiple hosts from a single Linux GDMA host

GDMA client files to delete:
* {{gdma/config/gdma_override.conf}} (which file is supplied to the GDMA client by the GroundWork server during auto-registration, and holds a {{Forced_Hostname}} directive specifying the form and content of the hostname that the client is to use when interacting with the server)
* {{gdma/config/gwmon\_}}{{{}{*}{_}hostname{_}{*}{}}}{{.cfg}} (which file, named using the precise form of the client hostname which the client should be using, is supplied to the GDMA client by the GroundWork server, and contains host and service externals from the server which are relevant to this client, note this is the actual hostname of the GDMA client, not the literal characters "hostname")
{warning}

h5. 1.4 Checking Multiple Hosts from a Single Linux GDMA Host

This is an advanced feature that is useful when checking clustered hosts, or simply setting up some lightweight monitoring of nearby hosts from a single Linux GDMA.

{note}

h5. 2.1 Enable the Plugin Download Feature plugin download feature

# Edit the file:
{code} {noformat}
/usr/local/groundwork/config/foundation.properties
{code} {noformat}
change:
{code} {noformat}
gdma.plugin.upload.enable=false
{code} {noformat}
to:
{code} {noformat}
gdma.plugin.upload.enable=true
{code} {noformat}
and save the file.
# Edit the file:
{code} {noformat}
/usr/local/groundwork/apache2/conf/httpd.conf
{code} {noformat}
change:
{code} {noformat}
#Alias /plugin_download "/usr/local/groundwork/apache2/htdocs/agents/plugin_download"
{code} {noformat}
to:
{code} {noformat}
Alias /plugin_download "/usr/local/groundwork/apache2/htdocs/agents/plugin_download"
{code} {noformat}
and save the file.
# Restart gwservices, Foundation, run as {{root}}:
{code} {noformat}
/etc/init.d/groundwork restart gwservices
service groundwork restart gwservices
{code} {noformat}
# Restart aApache, run as {{root}}:
{code} {noformat}
/etc/init.d/groundwork restart apache
service groundwork restart apache
{code} {noformat}
{note}
This will log off all users.
{note}

h5. 2.2 Upload the New Plugin Files
h5. 2.2 Upload new plugin files

# Go to Administration>Foundation, then select the link Manage Plugins.
!gdma_manageplugins1.png|align=left|hspace=5px!
# Click on the Add button in the upload screen:
!gdma_manageplugins2.png|align=left|hspace=5px!
# Go to _GroundWork Administration_ > _Foundation_, and select the link _Manage Plugins_.
\\ !bookshelf_gdma_advanced_02.jpg|thumbnail!
# Click the add icon from the Plugin List screen.
!bookshelf_gdma_advanced_03.jpg|thumbnail!
# Choose the platform and architecture that the plugin you are uploading being uploaded will be used on from the drop-down. If your plugin will work on all the platforms on which you run _GDMA_, choose one of the Multiplatform options. If you want to run the plugin on both 32-bit and 64-bit platforms, you will need to upload it twice, once for Multiplatform 32 bit and once for Multiplatform 64 bit. Generally, however, you will have to upload a different version of a plugin for each platform you want to use it on.
\\
\\
The names of the plugins for different operating systems or bit widths can be the same, though you will need to keep them in separate, well-defined places on your source machine to keep track of which copy is for which platform. The uploaded plugins will be stored in separate directories on the server, so there will be no confusion there. For instance, a plugin written as a shell script might work on just Linux but for both 32 bit and 64 bit versions of that OS, so you would upload it once for _Linux Intel 32 bit_ and once for _Linux Intel 64 bit_. Click Upload.
# Click Upload.
# To check if your plugins are present, click the Home icon in the lower-left corner of the Add Plugin box. Or click Foundation in the menu, and then click the Manage Plugins link again. You should see a list of uploaded plugins:
!gdma_pluglist.png|align=left|hspace=5px!
!bookshelf_gdma_advanced_04.jpg|thumbnail!
# To view your current plugins, click the _Home_ icon in the lower-left corner of the Add Plugin box. Or click Foundation in the menu, and then click the Manage Plugins link again. You should see a list of uploaded plugins.
!bookshelf_gdma_advanced_05.jpg|thumbnail!
# In GroundWork Monitor (6.5 and later), if you need to update a plugin (keeping the same name, but changing its content), you will need to delete and re-add it on each platform. The extra step involved in a delete/add as opposed to just re-uploading will be addressed in a future release.

h5. 2.3 Tell GDMA to Ddownload the Pplugins

# Go to Configuration>Hosts, _Configuration_ > _Hosts_,&nbsp;_Host Externals_&nbsp;> _Modify_ and expand the Host Externals section to modify select a host external for the hosts that will be downloading plugins. Alternatively you can enable this for individual hosts by opening the host external for the specific host you want, but changing the host external for all like hosts will make it the downloads apply to many hosts at once. You may wish to try this on one host, and make sure you have it right before rolling out to all hosts of a given type.
{note}
Only modify host externals for hosts running _GDMA_ (2.2.1 or later). Older versions will error out if these parameters are placed in the host externals.
{note}
# #* Add the following lines to the selected host external where <Server Name> is the resolvable name of the GroundWork server from the point of view of the GDMA:
{code}
{noformat}Enable_Poller_Plugins_Upgrade = "On"
Poller_Plugins_Upgrade_URL="http://<Server Name>/foundation-webapp/restwebservices/pluginUpdates/findUpdates"{noformat}
{code}
You may also use an https URL if you have configured _GroundWork Monitor_ to use _HTTPS_, e.g:{noformat}
{code}
Poller_Plugins_Upgrade_URL="https://<Server Name>/foundation-webapp/restwebservices/pluginUpdates/findUpdates"
{code} {noformat}
# Save the host external and choose Replace existing externals or Merge with existing externals as appropriate.
# Go to Configuration>Control, and select Build Externals.
{note:title=Important Note}When using HTTPS, the <Server Name> must exactly match what is in the server's SSL certificate (typically, a fully-qualified name). For more information regarding SSL support see the Bookshelf document [DOCDEV:How to enable SSL support].{note}
#* Save the host external and choose _Replace existing externals_ or _Merge with existing externals_ as appropriate.
!bookshelf_gdma_advanced_06.jpg|thumbnail!
# And build externals, _Configuration_ > _Control_ > _Build Externals_. Plugins will be downloaded to the GDMA {{libexec}} directory, and will be flagged executable by the user running the GDMA process (_gdma_&nbsp;by default). Existing plugins with the same file name will be replaced.

Plugins will now be downloaded to the GDMA libexec directory, and will be flagged executable by the user running the GDMA process ("gdma" by default). Existing plugins with the same file name will be replaced.
h5. 2.4 Plugin dependencies (UNIX versions)

h5. 2.4 Plugin Dependencies (UNIX versions)
You may want to use a plugin that depends on a library that GroundWork Monitor does not supply with the GDMA. For Windows systems, this is not usually the case, since though one could characterize a .dll file as a dependency, most Windows plugins are either VBScript (executed by {{cscript.exe}}), PowerShell (executed by {{powershell.exe}}) or Windows {{.bat}} batch files (executed by {{cmd.exe}}). If you need to download a .dll file to Windows, you should simply add it as you would a plugin, and it will be copied to the {{libexec}} subdirectory of the GDMA, where it will be available for the plugin.

You may want to use a plugin that depends on a library that GroundWork Monitor does not supply with the GDMA. For Windows systems, this is not usually the case, since though one could characterize a .dll file as a dependency, most Windows plugins are either vbscript (executed by {{cscript.exe}}), powershell (executed by {{powershell.exe}}) or Windows {{.bat}} batch files, executed by cmd.exe. If you need to download a .dll file to Windows, you should simply add it as you would a plugin, and it will be copied to the {{libexec}} subdirectory of the GDMA, where it will be available for the plugin.
If you are using the UNIX GDMA (Linux, Solaris or AIX), you may have access to the library you need. If you have this library (typically, one or more {{.so}} files) available, you can transfer it to the GDMA host into the {{groundwork/common/lib}} directory. Simply perform the above procedure, uploading the dependency files first, choosing platform and architecture as you would for the plugin. Then, when you have the library (or libraries) uploaded, upload the plugin, selecting the libraries in the dependency screen.

If you are using the UNIX GDMA (Linux, Solaris or AIX), you may have access to the library you need. If you have this library (typically, one or more {{.so}} files) available, you can transfer it to the GDMA host into the {{groundwork/common/lib}} directory. Simply perform the above procedure, uploading the dependency files first, choosing platform and architecture as you would for the plugin. Then, when you have the library (or libraries) uploaded, upload the plugin, selecting the libraries in the dependency screen:
!gdma_depsupload.gif|align=left|hspace=5px!
In this example, the&nbsp;{{test001.so}}&nbsp;library is needed by the new&nbsp;{{check_my_app}}&nbsp;plugin. Selecting the dependency when the plugin is loaded identifies {{test001.so}} as a dependency, which goes to the&nbsp;{{groundwork/common/lib}}&nbsp;directory, and&nbsp;{{check_my_app}}&nbsp;as a plugin, which gets placed in the&nbsp;{{groundwork/nagios/libexec}}&nbsp;directory.

In this example, the {{test001.so}} library is needed by the new {{check_my_app}} plugin. Selecting the dependency when the plugin is loaded identifies test001.so as a dependency, which goes to the {{groundwork/common/lib}} directory, and {{check_my_app}} as a plugin, which gets placed in the {{groundwork/nagios/libexec}} directory.
If you update an existing plugin, the new version will simply overwrite the old. No special action will be taken to preserve the original plugin.

If you update an existing plugin, the new version will simply overwrite the old. No special action will be taken to preserve the original plugin.
Plugins are downloaded only as needed. The system will check to see if the plugins are new, and have a different ND5 sum prior to downloading, so there is no downside to keeping a large number of plugins and dependencies on the GroundWork server.

Plugins are downloaded only as needed. The system will check to see if the plugins are new, and have a different ND5 sum prior to downloading, so there is no downside to keeping a large number of plugins and dependencies on the GroundWork server.
You may remove a plugin or dependency (or several at once) at any time from the&nbsp;_Manage Plugins_&nbsp;screen, by selecting the files to be removed and clicking the&nbsp;_X_&nbsp;button.

You may remove a plugin or dependency (or several at once) at any time from the _Manage Plugins_ screen, by selecting the files to be removed and clicking the _X_ button.
!bookshelf_gdma_advanced_07.png|thumbnail!

h4. 3.0 Working with PowersShell

The GDMA for Windows can be used to run Windows PowersShell Commandlets, or small powershell PowerShell programs that you write or modify to return results that can be interpreted as status and performance data by GroundWork Monitor. Especially in 64-bit environments, this is quite a powerful way to monitor your Windows systems.

GroundWork Monitor (6.4 and later) and GDMA (2.2.1 and later) come with some sample PowersShell scripts that leverage commandlets to check some otherwise difficult-to-access data about 64-bit Windows systems. This section will take you through getting GDMA set up to run these examples.

h5. 3.1 Installing PowersShell

Before you can run the PowersShell plugins, you must have PowersShell installed and working on your Windows system. Please see [http://technet.microsoft.com/en-us/library/ee692944.aspx] for information on getting PowersShell running.

In particular you MUST enable Powesershell PowerShell to run scripts. To do this, launch each version of the PowersShell interpreter on your system (both the 64 bit Windows PowersShell and the 32-bit Windows PowersShell (x86)), and type:
{code} {noformat}
Set-ExecutionPolicy RemoteSigned
{code} {noformat}

h5. 3.2 Loading Example Profile
* *gdma_22_powershell_getcluster*: A plugin to get the status of a Microsoft cluster server, if it is installed
* *gdma_22_powershell_getcounter*: A generic plugin that gets any perf counter, but must be modified before it will be useful
* *gdma_22_powershell_getwmi*: An example of calling a WMI counter (CPU in this case) from a PowersShell script


The modification of these example scripts in to more useful or specific uses is ongoing at GroundWork, and will doubtless be the source for many more profiles. For the moment, however, these are a starting point. To get these examples loaded:
# Go to Configuration>Profiles.
# Click on Profile Importer.
# Select gdma-22-windows-host.xml from the list.
# Select Import.
*# Go to _Configuration_ > _Profiles_ > _Profile Importer_.
*# Select _gdma-22-windows-host.xml_ from the list.
*# Click _Import_. This will result in a host profile, which you can then apply to a host. Make this the host on which you have installed and enabled PowerShell previously. Once you commit, and build externals these services will be active. Of course, it's normal not to have OK status on an un-configured service, so {{gdma_22_powershell_getcounter}}&nbsp;will be in warning until you modify the plugin and give it something to monitor. Also, unless you have Microsoft Cluster Server loaded on the host, you will not get logical output from {{gdma_22_powershell_getcluster}}.
\\ !gdma_pwrshlsnippet.png|align=left|hspace=5px!
{note}The service externals are not generic, and may need to be modified to work with your system.{note}
The service externals assume the default location of PowerShell and GDMA. The example here explicitly calls {{powershell.exe}} in the default location, and passes it the full, no-spaces version of the path to the PowerShell script to run. The quoting used is standard, and can be used in most cases. See 'Command='Line Tricks below.
{note}If you instal GDMA in a different directory, you will need to modify this path. The short form Progra~2 expands out to Program Files (x86), which is where GDMA, a 32-bit program, is installed in 64-bit Windows by default.{note}
{noformat}
This will result in a host profile, which you can them apply to a host. Make this the host on which you have installed and enabled Powershell previously. Once you commit, and build it's externals these services will be active.
!gdma_pwrshlsnippet.png|align=left|hspace=5px!

Of course, it's normal not to have OK status on an unconfigured service, so {{gdma_22_powershell_getcounter}} will be in warning until you modify the plugin and give it something to monitor. Also, unless you have Microsoft Cluster Server loaded on the host, you will not get logical output from {{gdma_22_powershell_getcluster}}.
{note}
The service externals are not generic, and may need to be modified to work with your system.
{note}
The service externals assume the default location of Powershell and GDMA. The example here explicitly calls {{powershell.exe}} in the default location, and passes it the full, no-spaces version of the path to the Powershell script to run. The quoting used is standard, and can be used in most cases. See 'Command='Line Tricks below.
{code}
Check_gdma_powershell_getcounter[1]_Command="c:\windows\system32\WindowsPowerShell\v1.0\powershell.exe 'C:\Progra~2\groundwork\gdma\libexec\v3\getCounter.ps1'"
{code} {noformat}

If you instal GDMA in a different directory, you will need to modify this path. The short form Progra~2 expands out to Program Files (x86), which is where GDMA, a 32-bit program, is installed in 64-bit Windows by default.
h5. 3.3 'Command='line Tricks

h4. 4.0 'Command='line Tricks

In some cases you may want to execute a check command that does not fall under the usual formatting rules. In particular if you want to make your own plugins, or integrate a plugin that you download off of the Internet, you may need to adjust the format of the command line in the _Service External_ you use to control the plugin execution.

!gdma_commandline.png|align=left|hspace=5px!

The entire command line is enclosed in double quotes. Within this enclosure, there are two main sections. The first is the executing program ({{cscript.exe}}, in this case, but in the PowersShell example in the previous section, it was {{powershell.exe}}). Any arguments to the executing program come next. If you are using UNIX, the executing program is implicit: the command shell. In that case you can stop there, for example:
{code} {noformat}
Check_gdma_linux_mem[1]_Command="check_mem.pl -F -w 20 -c 10"
{code} {noformat}
In Windows, as well, you can run compiled programs as plugins in this way without any further specifications. Just be sure to include the enclosing double quotes.

The second main part is the interpreted plugin, with its full path, encased in single quotes. You can usually use the {{$Plugin_Directory$}} macro, and this will be replaced with the location of the plugins in your GDMA installation. Note that you can have subdirectories off of this mail location, for example many of the vbscript plugins we supply are stored in the v2 subdirectory. PowersShell plugins are stored in v3 by convention.

After the single-quoted full path to the interpreted plugin, and before the terminating double quote mark, you can supply any arguments to the interpreted plugin. The GDMA will understand bare arguments, arguments specified with a dash "-", or with a slash "/".

h4. 54.0 Process for Macro Substitutions

GDMA macro substitution is done in two places:

# When externals are built on the server:
## Nagios resource macros are substituted first.&nbsp; These are {{*$USERn$*}} references, as defined under *Configuration* > *Control* > *Nagios&nbsp; resource macros*.
## Next, Monarch group macros are substituted, as defined under *Configuration* > *Groups* > *Macros* (to first establish the existence of a given macro name) and then under *Configuration* > *Groups* > *Groups* > _group name_ > *Detail* > *Macros*.
## Nagios resource macros are substituted first.&nbsp; These are {{$USERn$}} references, as defined under _Configuration_ > _Control_ > _Nagios&nbsp; resource macros_.
## Next, Monarch group macros are substituted, as defined under _Configuration_ > _Groups_ > _Macros_ (to first establish the existence of a given macro name) and then under _Configuration_ > _Groups_ > _Groups_ > <_group name>_ > _Detail_ > _Macros_.
\\
\\
\\
When externals are built for a given host, they are really only built for each top-level Monarch group associated with that host; you don't get an extra externals file for each sub-group to which the host belongs.
## Finally, a few fixed-name macros are substituted, in order: {{*$HOSTNAME$*}}, {{*$HOSTADDRESS$*}}, {{$HOSTNAME$}}, {{$HOSTADDRESS$}}, and {{*$HOSTALIAS$*}}. {{$HOSTALIAS$}}. These values are drawn from the Monarch configuration for this host.
# When externals are interpreted on the client:
## {{*$Plugin_Directory$*}} {{$Plugin_Directory$}} (drawn from the client's configured {{{*}Poller_Plugin_Directory{*}}}) {{Poller_Plugin_Directory}}) and {{*$Monitor_Host$*}} {{$Monitor_Host$}} (the name of the host for which the check is being run) are substituted first into each plugin execution string.
## Option parameters are substituted into the plugin execution string, in essentially arbitrary order (you can't depend on a specific ordering of these substitutions).

\\
\\

{html}Check_gdma_linux_swap[1]_Enable="ON"{html}\\
{html}Check_gdma_linux_swap[1]_Service="linux_swap"{html}\\
{html}Check_gdma_linux_swap[1]_Check_Interval="1"{html}\\
\\

you can also define any number of "Parm" parameters for a given service, in any of several forms:
\\
\\

{html}Check_Disk[1]_Parm_--warning = "10%"{html}\\
The value of a double-quoted parameter value is set to the string that is enclosed in quotes.
to be substituted into the plugin execution string by having the string {{\--errors-only}} be appended to the command line. But it looks like the present code will instead append {{\--errors-only=}}; this can be considered a bug. There are probably some other boundary cases that are also not handled as well as they should be. We will need to clean up these things in a future GDMA release.

h4. 6.0 Troubleshooting

h5. 6.1 Common Issues

h6. Time sync
h4. 5.0 Configuration Reference

Many installations do not properly synchronize time with NTP. This is particularly an issue with Virtual environments, where time slicing may introduce latency and drift to otherwise stable time signatures. For this reason, GDMA has been made tolerant of time drift. In the setup instructions, the file {{/usr/local/groundwork/config/bronx.cfg}} was modified to allow up to 900 seconds latency and 90 seconds imminence, or future timestamps, on incoming messages.
h5. 5.1 GDMA Configuration

If the time synchronization is sufficiently off to be outside this 16.5 minute envelope, the GroundWork server will reject the incoming message. To correct this situation, you must either:
# Synchronize the time on all monitored systems and the GroundWork server, or
# Widen the envelope by changing the parameters in {{bronx.cfg}}.
It is highly recommended that the time be synchronized.
{note}
The GroundWork Monitor version of {{send_nsca}} supplied with GDMA allows for the sending of old time stamps, which are the time stamps associated with when the check was run, not when the spooler has sent the data, which is potentially much later. This allows the system to accurately process performance data for checks that have been spooled, potentially for long periods.
{note}
This section describes the configuration details and installation methods for GroundWork Distributed Monitoring Agent (GDMA).

h6. Encryption Mismatch
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] .

A common security requirement that GroundWork Monitor supports is the encryption of data sent over the NSCA channel. By default, however, GDMA is installed with encryption turned off, which is also the default on the GroundWork server. Thus it is possible to have an encryption mismatch, for example, if you enable encryption on the GroundWork server (in {{bronx.cfg}}), and fail to enable it on the GDMA in {{send_nsca.cfg}}. Always make sure these files are consistent between GDMA ({{send_nsca.cfg}}) and GroundWork ({{bronx.cfg}}).
GDMA uses two configuration files to control its operation. These files share the same structure and command parameters.

One way to manage this situation is to set up GDMA to use an alternate send_nsca.cfg file. This file can be downloaded to the GDMA as if it were a plugin, and specified for use via the host external using the GDMA parameter called {{Spooler_NSCA_Config}}. For example:
If you create a file called:
{code}
send_nsca_gdma_encrypted.cfg
{code}
and you set it up for download as a plugin for Linux, it will be placed on the Linux GDMA in:
{code}
/usr/local/groundwork/gdma/tmp/send_nsca_gdma_encrypted.cfg
{code}
That means you could set up the GDMA to start using this file at the same time you switch the GroundWork server to use encryption, just by changing:
{code}
Spooler_NSCA_Config="/usr/local/groundwork/gdma/tmp/send_nsca_gdma_encrypted.cfg"
{code}
* *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.

h5. 6.2 Generating Logs
h6. Global Configuration Parameters

In general, GDMA will not output much in the way of log information unless you specify that it should do so. If you want logs, you can use the {{Enable_Local_Logging}} parameter to output log data to the file specified in the Logdir parameter, which is the log subdirectory by default. You should not leave this enabled permanently, as there is no facility to remove old logs.

h5. 6.3 Running by Hand
h5.

You can also generate useful output (the same as what gets placed in the log) by running the GDMA Poller and/or Spooler by hand.
|| Parameter Name || Default Value \\
\[Valid Values\] || Used by \\
\[Poller/Spooler\] || Description ||
| Auto_Register_Attempts | {{fibonacci}} \\
\[{{never}}, {{once}}, {{arithmetic}}, {{exponential}}, {{fibonacci}}, or {{periodic}}\] | Poller | {Note}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.{Note} 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 | {Note}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.{Note} 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 | {Note}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.{Note} Defines the maximum period (specified in seconds) to wait between successive auto-registration attempts. This parameter is available starting with GDMA 2.3.1. |
| Auto_Register_Pass | no default \\
\[the password corresponding to Auto_Register_User, or an empty string\] | Poller | {Note}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.{Note} 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 | {Note}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.{Note} 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 | {Note}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.{Note} 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. |
| 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_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. |
| 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 (windows child) behavior. \\ |
| 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&nbsp;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. See [GDMA Advanced] for details. |
| 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 the {{gwmon_$host.cfg}} filename, 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. See [DOC67:GDMA Advanced] 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. \\
\\
{Note}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 [DOCDEV:GDMA FAQs] &nbsp;for a detailed description.{Note} |
| 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. |

In Windows, open a command shell, and type:
{code}
cd \Program Files\groundwork\gdma\bin
gdma_poll.exe -i -d2 -x
{code}
As the Windows GDMA can be installed in alternate locations, you may need to enter a different path. For example in 64-bit Windows, GDMA is installed in \Program Files (x86)\groundwork\gdma by default.
h6. Per Service Configuration Parameters

This will give you output similar to the following:
{code}
C:\Users\Administrator>cd "\Program Files (x86)\groundwork\gdma"\bin

C:\Program Files (x86)\groundwork\gdma\bin>gdma_poll.exe -i -d2 -x
Getting [http://gdma-autohost/gdma/gwmon_wingdma64-qa-2.cfg] to C:\Program Files (x86)\groundwork\gdma\config\gwmon_wingdma64-qa-2.cfg(timeout 10)
Attempting to get [http://gdma-autohost/gdma/gwmon_wingdma64-qa-2.cfg] to C:\Program Files (x86)\groundwork\gdma\config\gwmon_wingdma64-qa-2.cfg (timeout is set to 10)
get_gdma_cfg_file_using_http: config file modified
h5.

Retrieved content for [http://gdma-autohost/gdma/gwmon_wingdma64-qa-2.cfg]
The parameters in this section are generally provided via host externals and service externals which are managed via the Monarch configuration tool.

Checking autoconfig file for a change.
Reloading config file
Successfully read host config file
Host config file syntax is ok.
Spooling poller startup message
spool_startup_info: Poller 2.2.2 started at Wednesday January 12 11:34:25 2011
Pushed result into the buffer: 0 0 1294860865 wingdma64-qa-2 gdma_poller 0 Poller 2.2.2 started at Wednesday January 12 11:34:25 2011
Executing poller normal mode.
ConfigFile_Pull_Cycle = 1
ConfigPull_Timeout = 10
Enable_Auto = On
Enable_Local_Logging = on
GDMAConfigDir = gdma
GDMA_Auto_Host = gdma-autohost
GDMA_Auto_Service = gdma_auto
GDMA_Multihost = off
HostSequenceNumber = 10
Logdir = C:\Program Files (x86)\groundwork\gdma\log\
Max_Concurrent_Hosts = 1
NumHostsInInstallation = 11
Poller_Plugin_Directory = C:\Program Files (x86)\groundwork\gdma\libexec\
Poller_Plugin_Timeout = 45
Poller_Proc_Interval = 600
Poller_Pull_Failure_Interval = 86400
Poller_Service = gdma_poller
Poller_Status = Off
Spooler_Batch_Size = 20
Spooler_Max_Retries = 10
Spooler_NSCA_Config = C:\Program Files (x86)\groundwork\gdma\config\send_nsca.cfg
Spooler_NSCA_Port = 5667
Spooler_NSCA_Program = C:\Program Files (x86)\groundwork\gdma\bin\send_nsca.exe
Spooler_NSCA_Timeout = 5
Spooler_Proc_Interval = 30
Spooler_Retention_Time = 900
Spooler_Service = gdma_spooler
Spooler_Status = Updates
Target_Server = [http://gdma-autohost]
wingdma64-qa-2_Check_gdma_powershell_getcluster[1]_Command = c:\windows\system32\WindowsPowerShell\v1.0\powershell.exe C:\Progra~2\groundwork\gdma\libexec\v3\getCluster.ps1
...
{code}
There are several diagnostic steps that GDMA goes through each time it runs. Errors in the retrieval of the config file, or with a syntax error in that file, will be presented near the top of this output. Any problems running the checks will appear in the last sections.
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):

If all of that is working ok, then you might try running the spooler:
{code}
C:\Program Files (x86)\groundwork\gdma\bin>gdma_spool_processor.exe -i -d2 -x
Checking config [file:C:\Program] Files (x86)\groundwork\gdma\config\gwmon_wingdma64-qa-2.cfg for a change.
Checking config [file:C:\Program] Files (x86)\groundwork\gdma\config\gdma_auto.conf for a change.
Reloading config files.
Successfully read host config file
Host config file syntax is ok.
The configuration file contains:
ConfigFile_Pull_Cycle = 1
ConfigPull_Timeout = 10
Enable_Auto = off
Enable_Local_Logging = on
GDMAConfigDir = gdma
GDMA_Auto_Host = gdma-autohost
GDMA_Auto_Service = gdma_auto
GDMA_Multihost = off
HostSequenceNumber = 10
Logdir = C:\Program Files (x86)\groundwork\gdma\log\
Max_Concurrent_Hosts = 1
NumHostsInInstallation = 11
Poller_Plugin_Directory = C:\Program Files (x86)\groundwork\gdma\libexec\
Poller_Plugin_Timeout = 45
Poller_Proc_Interval = 600
Poller_Pull_Failure_Interval = 86400
Poller_Service = gdma_poller
Poller_Status = Off
Spooler_Batch_Size = 20
Spooler_Max_Retries = 10
Spooler_NSCA_Config = C:\Program Files (x86)\groundwork\gdma\config\send_nsca.cfg
Spooler_NSCA_Port = 5667
Spooler_NSCA_Program = C:\Program Files (x86)\groundwork\gdma\bin\send_nsca.exe
Spooler_NSCA_Timeout = 5
Spooler_Proc_Interval = 30
Spooler_Retention_Time = 900
Spooler_Service = gdma_spooler
Spooler_Status = Updates
Target_Server = [http://gdma-autohost]
wingdma64-qa-2_Check_gdma_powershell_getcluster[1]_Command = c:\windows\system32\WindowsPowerShell\v1.0\powershell.exe C:\Progra~2\groundwork\gdma\libexec\v3\getCluster.ps1
wingdma64-qa-2_Check_gdma_powershell_getcluster[1]_Enable = ON
wingdma64-qa-2_Check_gdma_powershell_getcluster[1]_Check_Interval = 1
wingdma64-qa-2_Check_gdma_powershell_getcluster[1]_Service = gdma_22_powershell_getcluster
wingdma64-qa-2_Check_gdma_powershell_getcounter[1]_Command = c:\windows\system32\WindowsPowerShell\v1.0\powershell.exe C:\Progra~2\groundwork\gdma\libexec\v3\getCounter.ps1
wingdma64-qa-2_Check_gdma_powershell_getcounter[1]_Enable = ON
wingdma64-qa-2_Check_gdma_powershell_getcounter[1]_Check_Interval = 1
wingdma64-qa-2_Check_gdma_powershell_getcounter[1]_Service = gdma_22_powershell_getcounter
wingdma64-qa-2_Check_gdma_powershell_getwmi[1]_Command = c:\windows\system32\WindowsPowerShell\v1.0\powershell.exe C:\Progra~2\groundwork\gdma\libexec\v3\getWMI.ps1
wingdma64-qa-2_Check_gdma_powershell_getwmi[1]_Enable = ON
wingdma64-qa-2_Check_gdma_powershell_getwmi[1]_Check_Interval = 1
wingdma64-qa-2_Check_gdma_powershell_getwmi[1]_Service = gdma_22_powershell_getwmi
Spooling spool processor startup message
spool_startup_info: Spool processor 2.2.2 started at Wednesday January 12 11:38:52 2011
Pushed result into the buffer: 0 0 1294861132 wingdma64-qa-2 gdma_spooler 0 Spool processor 2.2.2 started at Wednesday January 12 11:38:
52 2011
Spool processor running in normal mode.
Processing live targets.
Processing for target gdma-autohost
Spooling heart beat message
Spooler heart beat message: Spooler transmitted 2 results in 0.308 secs | RESULTS=2;;;;TIME=0.308sec;;;;
Pushed result into the buffer: 0 0 1294861132 wingdma64-qa-2 gdma_spooler 0 Spooler transmitted 2 results in 0.308 secs | RESULTS=2;;;;T
IME=0.308sec;;;;
Loop count=0. Last loop exec time = 0.313 seconds.
{code}
The spooler merely takes output from the checks that have been run and sends it to the Target server or servers. Of interest here is if it succeeded in contacting the Target, which will be indicated as Processing live targets. Dead targets are Target servers that can't be reached for some reason, and indicate a down primary or standby system, or network issues in contacting the Target. The spooler will keep trying until it reaches a dead target, or times out according to the {{Spooler_Retention_Time and Spooler_Max_Retries}} parameters.
* 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

For UNIX, the command is similar, but you must run as the gdma user, with the full execution environment of that user, and specify the GroundWork-supplied perl interpreter.
| *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. |

h6. On Linux and AIX
{code}
su - gdma
cd /usr/local/groundwork/gdma/bin
/usr/local/groundwork/perl/bin/perl gdma_poll.pl -i -d2 -x
{code}
h5. 5.2 Error and Status Messaging

h6. On Solaris
{code}
su - gdma
cd /opt/groundwork/gdma/bin
/opt/groundwork/perl/bin/perl gdma_poll.pl -i -d2 -x
{code}
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.

The output is essentially the same for UNIX as for Windows.
* 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

h5. 5.3 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:
{noformat}/usr/local/groundwork/perl/bin/perl gdma_poll.pl -h{noformat}
** 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:
{noformat}/usr/local/groundwork/perl/bin/perl gdma_spool_processor.pl -h{noformat}
** 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. |