GDMA Quick Start

This section is designed to get you started monitoring hosts with GDMA quickly.

Target GroundWork Monitor Server: New Installation

This section describes the steps necessary to configure a GroundWork Monitor server to be a Target server for GDMA results, and a source for GDMA configuration data. This section describes setting up for a new installation of GDMA. If upgrading, see Target GroundWork Monitor Server: Upgrade below.

Prerequisites

The following prerequisites exist for configuration of a GDMA Target server:

  • GroundWork Monitor 6.1 or higher correctly installed.
  • Communication allowed from GDMA targets on ports 80 (HTTP) or 443(HTTPS)
  • Communication allowed from GDMA targets on port 5667 (NSCA)
  • Target server and GDMA monitored hosts clock synchronization.
    GDMA operation requires a unified time base for Target servers and the monitored systems. This is normally accomplished using an external clock source such as NTP (Network Time Protocol) for all systems. Messages from systems with out of sync clocks may be dropped silently by the Bronx event broker.
  • Administrative access and familiarity with GroundWork Monitor and Linux.
  • Taking a backup of the monarch database is highly recommended before beginning this operation. See the System Maintenance section in the GroundWork documentation for details.
NSCA Communication Setup
It is important to have target systems and the GroundWork server in sync with respect to time when setting up GDMA. If servers are not in sync, then NSCA messages submitted from the GDMA agents to the GroundWork server will be dropped by the Bronx event broker. In default logging levels for Bronx these drops are not recorded.

GroundWork Monitor 6.0 and later use a Nagios Event Broker (NEB) to process passive check results. The NEB is called Bronx. GDMA supports a feature called spooling which will handle network interruptions between GDMA hosts and the GroundWork server.

When that interruption ceases, results are sent back with correct timestamps. To support these timestamps, the Bronx configuration file, /usr/local/groundwork/config/bronx.cfg, listener_max_packet_age parameter needs to be updated. Set this value to 900 seconds to allow for 15 minutes of GDMA spooling. Longer durations are possible, but may result in transient overload conditions on the GroundWork server while large data volumes are processed.

Similarly, packets will be dropped by Bronx if they contain a future timestamp. This can be an issue in environments where perfect time synchronization is not possible. Setting the listener_max_packet_imminence parameter will compensate for a small amount of future time variance between the monitored node and the Target server. We suggest leaving the default of 1 second unless this is determined to be a problem in the environment.

Finally, the use_client_timestamp parameter should be left at the default of 1, to allow the timestamp from the monitored node to be used. This is useful in collecting the performance data and graphing it in time series graphs in the interface. If this parameter is set to 0, the server timestamp will be used, and graphing may not be accurate.

The following settings are from the Bronx configuration file:

/usr/local/groundwork/config/bronx.cfg
# LISTENER MAX PACKET AGE
# The max allowed age, in seconds, of the passive check result received.
# Any older results are dropped to the floor.
# The maximum allowed value is "900" seconds.
# Set the value to "0" to accept passive checks with older timestamps.
# If not specified, the value will be "30" seconds.
listener_max_packet_age=900

# LISTENER MAX PACKET IMMINENCE
# The max allowed "future age", in seconds, of the passive check result received.
# Any newer results are dropped to the floor.
# The maximum allowed value is "900" seconds.
# Set the value to "0" to disallow passive checks with newer timestamps.
# If not specified, the value will be "1" second, which should be just
# enough to allow for possible slight discrepancies which can arise even
# between time-synchronized client and server machines. In general, we
# highly recommend that the site use NTP or similar time-synchronization
# software to tie together the software clocks on disparate machines to
# high accuracy, to prevent misunderstandings about when events actually
# occur. Note that time synchronization for a VM guest machine can be
# problematic; see your vendor's documentation on this topic.
#listener_max_packet_imminence=1

# USE CLIENT TIMESTAMP
# This parameter, if set to a positive value, configures the listener thread
# to use the timestamp in the passive check result received for processing,
# rather than the time on the server when the check result is processed.
# To prevent confusion in handling data from clients which are not
# time-synchronized to the server, such a check result timestamp will be
# automatically overridden and replaced with the server timestamp if the
# passive check result timestamp is found by the server to be in the future.
# If not specified, the value will be "1".
#use_client_timestamp=0

If any changes to the bronx.cfg file are needed, Nagios must be restarted to put them into effect:

/etc/init.d/groundwork restart nagios
Enable Externals

To enable externals within GroundWork, select Control from the Configuration tab, then Setup and click the Enable Externals box, and Save. You are then able to define, add, and execute externals using the Services, Profiles, and Hosts configuration tabs. The system is now configured for general GDMA operation. To configure the monitored nodes, see the relevant section (Windows GDMA Setup, Linux GDMA Setup). It is likely that you will wish to take advantage of the auto-configuration functions as well, so be sure to review the section on Auto-configuration Setup.

Target GroundWork Monitor Server: Upgrade

This section describes the steps necessary to upgrade an existing GroundWork server with a previous version of GDMA configured to be a Target server for GDMA agents. If this is a new installation, see Target GroundWork Monitor Server: New Installation above.

Prerequisites

The following prerequisites exist for upgrading a GDMA Target server:

  • An existing GroundWork server version 6.0.1 or higher, configured and running with GDMA 1.x or 2.0 or later.
  • Familiarity with GroundWork Monitor and Linux system administration
NSCA Communication Setup
It is important to have target systems and the GroundWork server in sync with respect to time when setting up GDMA. If servers are not in sync, then NSCA messages submitted from the GDMA agents to the GroundWork server will be dropped by the Bronx event broker. In default logging levels for Bronx these drops are not recorded.

As covered in the Target GroundWork Monitor New Installation section above, verify that all the parameters in /usr/local/groundwork/config/bronx.cfg are correct.

GroundWork Monitor 6.0 and above uses a Nagios Event Broker (NEB) to process passive check results. The NEB is called Bronx. GDMA supports a feature called spooling which will handle network interruptions between GDMA hosts and the GroundWork server.

When that interruption ceases, results are sent back with correct timestamps. To support these timestamps, the Bronx configuration file, /usr/local/groundwork/config/bronx.cfg, listener_max_packet_age parameter needs to be updated. Set this value to 900 seconds to allow for 15 minutes of GDMA spooling. Longer durations are possible, but may result in transient overload conditions on the GroundWork server while large data volumes are processed.

Similarly, packets will be dropped by Bronx if they contain a future timestamp. This can be an issue in environments where perfect time synchronization is not possible. Setting the listener_max_packet_imminence parameter will compensate for a small amount of future time variance between the monitored node and the Target server. We suggest leaving the default of 1 second unless this is determined to be a problem in the environment.

Finally, the use_client_timestamp parameter should be left at the default of 1, to allow the timestamp from the monitored node to be used. This is useful in collecting the performance data and graphing it in time series graphs in the interface. If this parameter is set to 0, the server timestamp will be used, and graphing may not be accurate.

The following settings are from the Bronx configuration file:

/usr/local/groundwork/config/bronx.cfg
# LISTENER MAX PACKET AGE
# The max allowed age, in seconds, of the passive check result received.
# Any older results are dropped to the floor.
# The maximum allowed value is "900" seconds.
# Set the value to "0" to accept passive checks with older timestamps.
# If not specified, the value will be "30" seconds.
listener_max_packet_age=900

# LISTENER MAX PACKET IMMINENCE
# The max allowed "future age", in seconds, of the passive check result received.
# Any newer results are dropped to the floor.
# The maximum allowed value is "900" seconds.
# Set the value to "0" to disallow passive checks with newer timestamps.
# If not specified, the value will be "1" second, which should be just
# enough to allow for possible slight discrepancies which can arise even
# between time-synchronized client and server machines. In general, we
# highly recommend that the site use NTP or similar time-synchronization
# software to tie together the software clocks on disparate machines to
# high accuracy, to prevent misunderstandings about when events actually
# occur. Note that time synchronization for a VM guest machine can be
# problematic; see your vendor's documentation on this topic.
#listener_max_packet_imminence=1
# USE CLIENT TIMESTAMP
# This parameter, if set to a positive value, configures the listener thread
# to use the timestamp in the passive check result received for processing,
# rather than the time on the server when the check result is processed.
# To prevent confusion in handling data from clients which are not
# time-synchronized to the server, such a check result timestamp will be
# automatically overridden and replaced with the server timestamp if the
# passive check result timestamp is found by the server to be in the future.
# If not specified, the value will be "1".
#use_client_timestamp=0

If any changes to the bronx.cfg file are needed, Nagios must be restarted to put them into effect:

/etc/init.d/groundwork restart nagios
Create GDMA Build Directory

This is the location that will be used for building and distribution of GDMA host configurations.

As user root create the directory and change ownership to user nagios.

#mkdir /usr/local/groundwork/apache2/htdocs/gdma
#chown nagios.nagios /usr/local/groundwork/apache2/htdocs/gdma

All other steps are contained in the relevant upgrade sections. Please proceed to the sections Windows GDMA Setup or Linux GDMA Setup. You may wish to take advantage of the Auto-Configuration features of GDMA. If so, see Auto Configuration Setup below before proceeding.

Auto Configuration Setup

Theory of Operations

The Auto Configuration feature of GDMA enables GDMA agents to be deployed to target systems without needing to provide a host specific configuration at installation time. When GDMA is first installed and started without a configuration it will operate in Auto Configuration mode. While in Auto Configuration mode the agent will periodically perform a basic discovery of the monitored host system and transmit the discovery information to a predefined Parent system. The predefined host name must be added to DNS, so that the monitored hosts will resolve it as the GroundWork Target server. This information can then be used by the GroundWork Monitor administrator to configure a host-specific configuration for the new monitored host. When the host-specific configuration is available, it will be retrieved by the agent and the agent will self-configure and switch to normal operation.

Auto Configuration Operations

The following is a description of the sequence of operations that occur when a new GDMA is deployed in Auto Configuration mode. It is useful to understand this process, so that the messages received and displayed on the GroundWork Monitor user interface can be understood.

When the agent is first started both the poller and spooler engines are started.

Basic Poller Operation in Auto Configuration Mode
  1. Poller reads: gdma_auto.conf
  2. Poller checks for the presence of a local host configuration file.
  3. Poller attempts to retrieve a host configuration file from the location defined by gdma_auto.conf
  4. If it fails to download a host configuration file it sleeps until Poller_Proc_Interval has expired and starts at step 1.
Basic Spooler Operation in Auto Configuration Mode
  1. Spooler reads: gdma_auto.conf
  2. Spooler checks for the presence of a local host configuration file.
  3. If the host configuration file is not present the spooler transmits an auto configuration message.
  4. Spooler sleeps until Spooler_Proc_Interval has expired and restarts starts at step 1.
    The message is sent via NSCA as a service check result.
    The message is sent to the Target server as coming from the host defined by the GDMA_Auto_Host parameter (default is gdma-autohost) and the service defined by GDMA_Auto_Service (default is gdma_auto).
    The message payload contains the hostname, ip address and operating system information.
Create DNS Entry for gdma-autohost that points to the GroundWork Server

The GDMA agent relies on DNS to resolve the preconfigured hostname gdma-autohost to the Target server where it will submit its check results, and attempt to pick up its configuration file. Using whatever DNS system is available on your network, ensure that the system to be monitored with GDMA can resolve the name gdma-autohost to the GroundWork server.

Import GDMA Auto Configuration Profile

The GDMA Auto Configuration profile provides a template for the auto-configuration virtual host. In order to properly process the messages from the GDMA hosts in Auto Configuration mode, this profile must be loaded, using the following procedure.

  1. In Configuration, select Profiles.
  2. Select Profile importer.
  3. Toggle the checkbox to select gdma-autohost.xml.
  4. Select Import at the bottom of the screen.

Create GDMA Auto-configuration Virtual Host

This virtual host serves as a collection point for notifications and alerts from unconfigured GDMA agents.

  1. In Configuration, select Hosts.
  2. Select Host Wizard.
  3. Fill in the Host Name as gdma-autohost.
    This name is controlled by the GDMA_Auto_Host configuration parameter. Do not modify this path without also modifying all the requisite GDMA agent configurations.
  4. Fill in Alias as gdma-autohost.
  5. Fill in Address as 127.0.0.2.
    Nagios and GroundWork require that all IP addresses for configured hosts be unique. Ensure that the address used here is unique in the configuration.
  6. Select gdma-autohost as the Host profile.
  7. Select Next (4x), then select Continue.
    If you are using clone host or another method for creating this host, please ensure it has no externals associated, or you may see an error when running externals related to the distribution directory. The gdma-autohost}} and its services should have no externals.
  8. Commit changes to activate. The system is now configured to receive auto configuration messages from GDMA targets.
    You may optionally place the gdma-autohost in a hostgroup and configure notification options.
    Your choice of host profile and configuration group in later steps may be matched to operating system in the gdma_auto.pl script.

    The mapping is controlled by the following structure:

    "linux;gdma-21-linux-host;unix-gdma-2.1",
"MSWin32;gdma-21-windows-host;windows-gdma-2.1",
"linux 2.6.9-42.0.3.elsmp;gdma-21-linux-host;unix-gdma-2.1",
"MSWin32 5.00;gdma-21-windows-host;windows-gdma-2.1"

    You may change these defaults, or add matches to the list, by editing the script, as long as you maintain the quoted, comma-delimited string of:

    os string;host_profile;monarch_group
    The last encountered match is what will be used, so you should place general matches first, and more specific matches later in the list.

The GDMA Target server configuration for auto-configuration is now complete. You should periodically check your configuration for new hosts as you deploy the GDMA in your organization. These hosts should be placed in hostgroups and the configuration committed.

Windows GDMA Setup: New Installation

The Windows GDMA installation requires several new profiles to be present on the Target GroundWork server. These profiles must be loaded on the system and applied to the GDMA monitored node hosts. Windows GDMA hosts must be additionally organized into configuration groups. Configuration groups (aka Monarch Groups) are used to control the creation of external (see Configuring Externals) definitions used by GDMA agents. This section covers setting up these parameters in a new installation of GDMA.

Prerequisites

The following prerequisites exist for configuring Windows GDMA agents:

  • GroundWork Monitor 6.1 or later correctly installed.
  • GroundWork Target server configuration complete.
  • Administrative access to GroundWork Monitor and monitored systems and familiarity with the administration of Linux, GroundWork, and Windows systems.
  • Taking a backup of the monarch database is highly recommended before beginning this operation. See System Maintenance>Backup and Restore for details.
GroundWork Monitor Target Server Setup

The following steps need to be performed on the GroundWork server designated as the Target server for the Windows GDMA monitored hosts.

Import GDMA Windows Base OS Host and Service Profile

The Windows Base OS profile configuration parameters for the creation of Windows monitored nodes.

  1. In Configuration, select Profiles.
  2. Select Profile importer.
  3. Toggle the checkbox to select gdma-21-windows-host.xml.
  4. Select Import at the bottom of the screen.

Review and Modify gdma-21-windows Host Externals Properties
  1. In Configuration, select Hosts, Host Externals.
  2. Select Modify.
  3. Select gdma-21-windows.
  4. Here you can modify the Target_Server parameter. This parameter controls where GDMA agents will download their configurations from and where they will send check results. The parameter must be in the form of a URL. This parameter is normally set to the hostname or IP address of the Master system. For details on this and other configuration parameters. See GDMA Configuration Reference. If you are using Auto-configuration, you may set this to http://gdma-autohost.
  5. Select Save.

Configure a GDMA Windows Host

If you are using Auto-configuration, you may skip this step.

  1. In Configuration, Hosts.
  2. Select Host Wizard.
  3. Fill in Host Name (e.g.2000pro).
  4. Fill in Alias (e.g. 2000pro).
  5. Fill in Address (e.g. 196.168.11.72).
  6. Select gdma-21-windows-host as the Host profile.
  7. Select Next (4x), then select Continue.You may optionally place the host in a hostgroup and configure additional host, service and notification options.

Add a New Host to a Monarch Group

If you are using Auto-configuration, you may skip this step.

  1. In Configuration, select Groups.
  2. Expand Groups.
  3. Expand windows-gdma-21.
  4. Select Detail.
  5. Select the Hosts tab.
  6. Toggle checkbox for a host (e.g. 2000pro).
  7. Select Add Hosts. The host will appear in the upper field as an assigned host.

Commit changes and Build Externals

Commit changes to GroundWork Monitor and create a GDMA configuration file.

  1. In Configuration, select Control.
  2. Select Commit, Backup, Commit.
  3. Select Run externals.
  4. The configuration file will be created in /usr/local/groundwork/apache2/htdocs/gdma as defined in the windows-gdma monarch group. The filename will be gwmon_$hostname.cfg in this example gwmon_2000pro.cfg. 
    #ls -al /usr/local/groundwork/apache2/htdocs/gdma/gwmon_2000pro.cfg
-rw-r--r-- 1 nagios nagios /usr/local/groundwork/apache2/htdocs/gdma/gwmon_2000pro.cfg
#
Client Install/Upgrade for Windows GDMA

Use this procedure to install the Windows GDMA on Windows hosts. If upgrading, you must first uninstall the legacy GDMA client.

To uninstall a legacy client:

  1. Access the Windows client user interface.
  2. Start a command window.
  3. Stop the GDMA service with the command: 
    net stop gdma
  4. Remove the GDMA service with the command: 
    sc delete gdma
  5. Backup any custom plugins you may have added to the GDMA in the c:\groundwork directory structure. You will need to move these to the new location.
  6. (Optional) Delete the directory c:\groundwork and all subdirectories.

To install a Windows GDMA 2.2.3 client:

  1. Access the Windows client user interface.
  2. Transfer the binary installer file to a temporary location on the local disk.
  3. Start a command window.
  4. Change to the temporary directory.
  5. Type the name of the binary installer.

Follow the prompts on the screen. If you are using the Auto Configuration feature, you should leave the Target server as gdma-autohost. If not, you should fill in the Target server hostname or IP address.

If you wish to install the GDMA via a scripted method, such as a software distribution package or a batch script, you may wish to take advantage of the unattended mode option. Type the name of the binary installer followed by --help for a list of available options.

Linux GDMA Setup

This section describes the steps necessary to configure GDMA agents for Linux systems including a basic installation.

Prerequisites

The following prerequisites exist for configuring Linux GDMA agents

  • GroundWork Monitor 6.1 or later correctly installed.
  • GroundWork Target server configuration complete.
  • Administrative access to GroundWork Monitor and monitored systems and familiarity with the administration of Linux, GroundWork, and Windows systems.
  • Taking a backup of the monarch database is highly recommended before beginning this operation. See System Maintenance>Backup and Restore for details.
GroundWork Monitor Setup
Import GDMA Linux Base OS Host and Service Profile

The Linux Base OS profile provides configuration parameters for the creation of Linux targets.

  1. In Configuration, select Profiles.
  2. Select Profile importer.
  3. Toggle the checkbox to select gdma-21-linux-host.xml.
  4. Select Import at the bottom of the screen.

Review and Modify gdma-21-linux Host Externals Properties
  1. In Configuration, select Hosts, Host Externals.
  2. Select Modify.
  3. Select gdma-21-linux.
  4. Here you can modify the Target_Server parameter. This parameter controls where GDMA agents will download their configurations from and where they will send check results. The parameter must be in the form of a URL. This parameter is normally set to the hostname or IP address of the Master system. For details on this and other configuration parameters see GDMA Configuration Reference.
  5. Select Save.

Configure a GDMA Linux Host
  1. In Configuration, Hosts.
  2. Select Host Wizard.
  3. Fill in Host Name (e.g.linux_gdma).
  4. Fill in Alias (e.g. linux_gdma).
  5. Fill in Address (e.g. 196.168.11.220).
  6. Select gdma-21-linux-host as the Host profile.
  7. Select Next (4x), then select Continue. You may optionally place the host in a hostgroup and configure additional host, service and notification options.

Add a New Host to a Monarch Group
  1. In Configuration, select Groups.
  2. Expand Groups.
  3. Expand unix-gdma-2.1.
  4. Select Detail.
  5. Select the Hosts tab.
  6. Toggle checkbox for a host (e.g. linux-gdma).
  7. Select Add Hosts. The host will appear in the upper field as an assigned host.

Commit Changes and Build Externals

Commit changes to GroundWork Monitor and create a GDMA configuration file.

  1. In Configuration, select Control.
  2. Select Commit, Commit.
  3. Select Run externals.
  4. The configuration file will be created in /usr/local/groundwork/apache2/htdocs/gdma as defined in the unix-gdma-2.1 monarch group. The filename will be gwmon_$hostname.cfg in this example gwmon_linux-gdma.cfg. 
    #ls -al /usr/local/groundwork/apache2/htdocs/gdma/gwmon_linux-gdma.cfg
-rw-r--r-- 1 nagios nagios /usr/local/groundwork/apache2/htdocs/gdma/gwmon_linux-gdma.cfg
#
Client Install/Upgrade for Linux GDMA

Use this procedure to install the Linux GDMA on Linux hosts. If upgrading, you must first uninstall the legacy GDMA client.

To uninstall a legacy client:
  1. Access the client command line interface.
  2. Backup any custom plugins you may have added to the GDMA in the following directory structure. You will need to move these to the new location. 
    /usr/local/groundwork
  3. Delete the following directory and all subdirectories: 
    /usr/local/groundwork
  4. Type: 
    chkconfig gdma off
  5. Type: 
    /etc/init.d/gdma stop
  6. Remove the file /etc/init.d/gdma with the command: 
    rm /etc/init.d/gdma
  7. Remove the entire /usr/local/groundwork directory with the command: 
    rm -Rf /usr/local/groundwork
    Linux GDMA 2.1 can be uninstalled with the script /usr/local/groundwork/uninstall
To install a Linux GDMA 2.2.3 client:
  1. Access the client command line interface.
  2. Transfer the binary installer file to a temporary location on the local disk.
  3. Change to the temporary directory.
  4. Type the following to make the installer executable, substitute the name of your installer: 
    chmod +x groundworkagent-2.1-14-linux-32-installer.bin
    Linux GDMA has a 32 and a 64 bit version. Please select the correct one for your architecture.

    Follow the prompts on the screen. If you are using Auto Configuration feature, you should leave the Target server as gdma-autohost. If not, you should fill in the Target server hostname or IP address.

If you wish to install the GDMA via a scripted method, such as a software distribution package or a batch script, you may wish to take advantage of the unattended mode option. Type the name of the binary installer followed by --help for a list of available options.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.