Adding and changing GDMA credentials

The credentials used by the deployed GDMA agents need to be managed so the calls to auto-registration and auto-setup can be properly authorized and succeed. By default, a new GroundWork server is configured to use the username gdma with password gdma. It is recommended to change the password regularly.

Change the default username and password

Before you start, it is good practice to change at least the password to the account used for GDMA auto-registration.

As a user with the Admin role, from the Administration menu item, choose Security.
Changing the password and username:
- To change the password, click Update and enter and confirm the new password.
  
  Do not use the “/” character in the password. It is accepted, but can cause issues in some cases.
- To change the username, you actually define a second one, with its own password. Click Add GDMA Account and fill out the form. You can have two active at the same time, which allows you to migrate the agent configurations to the new account periodically.

Change the password on the agent

To change the password on the agent, you can update the the following file on each agent:

/usr/local/groundwork/gdma/config/gdma_auto.conf

and change the parameters:

Auto_Register_Pass
Auto_Register_User

to reflect the new values.

These are in clear text, however, the file itself is restricted to superuser access only. We recommend using a configuration management tool such as Ansible or Puppet to manage large numbers of agents in this way.

Configuring GDMA

The first section below outlines steps to configure the GroundWork server as the target server for GDMA results and a source for GDMA configuration data. The next section outlines the configuration for GDMA client servers (monitored systems).

Configuring the GroundWork server

The following steps should be followed for new installations and upgrades. If you are upgrading an existing GDMA target server the following steps may already be in place however should be verified.

Back up the Monarch database - It is highly recommended in a production environment to back up the Monarch database before beginning a GDMA configuration, see System Back up Restore.
Create port accessibility - The GDMA agents on the GDMA client servers must have access to the GDMA target on ports 80 (HTTP) or 443 (HTTPS). Also, the GDMA client servers must be able to write to the GDMA target port 5667 (NSCA). Make sure these ports are accessible before you try to deploy. The GroundWork Server firewall needs to have these ports open.
Synchronize target server and GDMA monitored hosts clocks - The GDMA operation requires a unified time base for target servers and 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 Nagios Event Broker (Bronx).
Set up NSCA communication - GroundWork Monitor (6.0 and later) uses Bronx to process passive check results for Nagios and it listens at port 5667 for NSCA messages. Most of the GDMA messages will arrive in real time, although there may be short network outages and GDMA can buffer messages during these short interruptions. While communication is down, monitored results are locally spooled on the hosts and when communication is restored GDMA sends the spooled results with their original timestamps. The GroundWork server and all monitored hosts clocks must be synchronized to within the tolerances specified in the server Bronx configuration, typically plus or minus 15 minutes.

To set times edit the Bronx file:
```
vi /usr/local/groundwork/config/bronx.cfg
```
Scroll down to the LISTENER MAX PACKET AGE section and edit the listener_max_packet_age 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. If any changes are made, Nagios must be restarted to put them into effect, /etc/init.d/groundwork restart nagios.
```
# 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.
# The GroundWork-recommended value is 900, largely because Windows
# machines often have trouble maintaining Internet time synchronization.
listener_max_packet_imminence=900 \\ \\
# 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
```
Freshness Checking - The Check service freshness option determines whether or not Nagios will periodically check the freshness of service results. Historically freshness checking has not been enabled at a global level in the GroundWork Monitor default Nagios Main Configuration, and this will suppress freshness checking for GDMA-run services. Enabling this option is useful for ensuring that passive checks are received in a timely manner. A checked value means the freshness checking is enabled. This setting should be verified and enabled on a GDMA target server.

To verify/enable freshness checking go to Configuration > Nagios Monitoring > Control > Nagios main configuration > Freshness Check.
Enable Externals - The configuration for GDMA monitored hosts must have Externals enabled to allow access to all the externals-related screens and options. Depending on the version of GroundWork Monitor you are using this directive may already be enabled.

To verify/enable externals go to Configuration > Nagios Monitoring > Control > Setup > Enable externals.
Set up Auto-Registration Host Group - This is configured by default.

To verify go to Configuration > Nagios Monitoring > Hosts > Host groups > Modify . If the host group does not yet exist, add a host group named Auto-Registration (using the exact character format), under Configuration > Nagios Monitoring > Hosts > Host groups > New.
Set up auto-registration Monarch Group - This is configured by default.

To verify go to Configuration > Nagios Monitoring > Groups > Groups > auto-registration > Detail. If the monarch group does not yet exist, add a group named auto-registration (using the exact character format), under Configuration > Nagios Monitoring > Groups > New. Further down on the same page verify or set the Build folder to be /usr/local/groundwork/apache2/htdocs/gdma so that the externals files will be placed where GDMA clients will be looking to pick them up.
Add Auto-Registration to auto-registration - It is generally recommended that you add the Auto-Registration hostgroup to the auto-registration Monarch configuration group. This step is not a system default, you should consider making this change.

Go to Configuration > Nagios Monitoring > Groups > Groups > auto-registration > Detail > select the Hosts tab. Scroll down to Add Hostgroup(s), check and add Auto-Registration. This will simplify the actions when new hosts are added, by allowing the individual hosts to be indirectly associated with the Monarch configuration group via the hostgroup, instead of being assigned directly to the Monarch configuration group.
Import GDMA host profiles - This is configured by default. The host profiles will form the basis for configuring new auto-registered GDMA hosts running the respective operating-system types. You are not required to use these profiles as the GDMA client installer allows you to select an alternate host profile and an optional service profile to be applied on the server to the auto-registered client's configuration.

To verify, select Configuration > Nagios Monitoring > Profiles > Host profiles > Modify. To add new host profiles and related objects, select Configuration > Nagios Monitoring > Profiles > Profile importer > Import. Choose the GDMA category and select the appropriate host-profile files; gdma-aix-host.xml, gdma-linux-host.xml, gdma-solaris-host.xml, gdma-windows-host.xml, then click Import at the bottom of the screen.
Add a default contact group to the host templates - Edit each of the new host templates just verified/imported; gdma-aix-host.xml, gdma-linux-host.xml, gdma-solaris-host.xml, gdma-windows-host.xml, and add one or more default contact groups.

Navigate to Configuration > Nagios Monitoring > Hosts > Host Templates > Modify, then select each one of the GDMA host templates listed and establish the basic contact group(s) for hosts using this host template (perhaps just nagiosadmin at this point, as a kind of safe default). Save each host template after making this change. The setting here can be overridden later on at other levels, but this provides at least a standard setting for all auto-registered hosts.

Configuring the client server

If upgrading an existing GDMA client server, start with step 1. Uninstall the legacy client. If this is a new installation, start with step 2. Download the agent.

Uninstall the legacy client
- For Linux:
  1. Access a command line interface for the Linux GDMA client server, (e.g., PuTTY).
  2. Backup any custom plugins in the /usr/local/groundwork directory structure, you may have added. You will need to move these to the new location.
  3. Next, run the following script to uninstall the agent:
    /usr/local/groundwork/uninstall
  4. You will be prompted with the question Do you want to uninstall GroundWork Distributed Monitoring Agent and all of its modules?, confirm the uninstall.
  5. Remove the groundwork sub-directory and all sub-directories:
    rm -Rf /usr/local/groundwork
  6. On the GroundWork server delete the GDMA client host within the Auto Registration host group (Configuration > Nagios Monitoring > Hosts > Hosts > Auto-Registration > <hostname> > Detail > delete), and run a Commit operation (Configuration > Nagios Monitoring > Control > Commit).
- For Windows:
  1. Access the File Manager for the Windows GDMA client server, (e.g., Start, Computer).
  2. Back up any custom plugins in the C:\Program Files (x86)\groundwork directory structure, you may have added. You will need to move these to the new location.
  3. Next, from the C:\Program Files (x86)\groundwork directory, select and run the uninstall.exe file. You will be prompted with the question Do you want to uninstall GroundWork Distributed Monitoring Agent and all of its modules?, answer Yes to uninstall and proceed.
  4. Using the File Manager remove the groundwork directory all all sub-directories.
  5. On the GroundWork server delete the GDMA client host within the Auto Registration host group and run a Commit operation.
Download the agent - To download the agent, go to the Downloads page, the available packages include Windows GDMA, Linux 32-bit GDMA, Linux 64-bit GDMA, Solaris Intel GDMA, Solaris SPARC GDMA, and AIX.

Install the Agent

For Linux:

If necessary, relocate the agent to the client server. Make the installer executable (example below, please use the current .run file):
```
chmod +x groundworkagent-2.6.1-103-linux-64-installer.run
```
Launch the agent (example below, please use the current .run file):
```
./groundworkagent-2.6.1-103-linux-64-installer.run
```

Continue with the installation. You will be prompted with a series of questions. Make sure to enter:

GDMA requires clock synchronization between this system and the master GroundWork system.
Before installing, ensure that the clock on this system is correct. GDMA requires network
name resolution (DNS) to locate and communicate with the master GroundWork system.
Before installing, ensure that name resolution is functional on this system.
Continue? [Y/n]: Y

Make sure to enter the name of the GroundWork server in place of [gdma-autohost].

Enter the name of the GroundWork server. This can be a resolvable short name, a
fully-qualified domain name, or an IP address. It will be used to download the
configuration for this agent, as well as to send the monitoring results to.
Target Server [gdma-autohost]:

Please select which protocol will be used for communication with the GroundWork server.
[1] HTTP
[2] HTTPS: If you choose HTTPS, you will need to manually set up certificates as well.
Please choose an option [1]:

Use the credentials here you added in section 1.0 above.

Enter the user name and password to be used for auto-registration of this GDMA machine.
If these credentials are not provided, auto-registration will be disabled on this machine,
and the older auto-configuration protocol will be used instead.
Registration username []: Registration password:

Enter the host profile and service profile names to be applied to this machine's
monitoring setup during auto-registration. These values are optional; if left blank, the
host profile will be defaulted on the server, and no extra service profile will be applied.
Host profile name [gdma-linux-host]:
Service profile name []:

Do you want to start the GDMA service after the installation? [Y/n]:

Setup is now ready to begin installing GroundWork Distributed Monitoring Agent on your computer.
Do you want to continue? [Y/n]:

For Windows:

As of the Windows GDMA 2.6.1 release (supported in GroundWork Monitor 7.2.0 and bundled into GroundWork Monitor 7.2.1 and later), it is possible for a site to run the GDMA service as a non-administrative user. Many customers would prefer this, as a means of limiting the overall security profile of this service. Before installation please refer to the document Windows GDMA as non-admin user.

If necessary, relocate the agent to the client server. Find and run the installer file, e.g., groundworkagent-2.6.2-104-windows-installer.exe, on each of your GDMA client machines.

Continue with the installation. You will be prompted with a series of questions:

GDMA requires clock synchronization between this system and the master GroundWork system.
Before installing, ensure that the clock on this system is correct. GDMA requires network name
resolution (DNS) to locate and communicate with the master GroundWork system. Before installing,
ensure that name resolution is functional on this system.
Continue? Yes

Welcome to the GroundWork Distributed Monitoring agent Setup Wizard.

Installation directory: c:\Program Files (x86)\groundwork.

Enter the name of the GroundWork server. This can be a resolvable short name, a
fully-qualified domain name, or an IP address. It will be used to download the configuration for
this agent, as well as to send the monitoring results to.
Target Server:

It is important to read the article, Windows GDMA as non-admin user, regarding the username entry on this screen. By passing the username and password entries will default to running GDMA as an administrator. This is the correct setup in nearly all cases. Only if you were installing as an ordinary user, which should be rare, would you need to provide a password.

Please specify the user name to be used by the Agent.
GDMA username:
GDMA user password needed? (only for an ordinary user account)
GDMA user password

Please select which protocol will be used for communication with the GroundWork server.
HTTP or HTTPS: If you choose HTTPS, you will need to manually set up certificates as well. Next.

Enter the user name and password to be used for auto-registration of this GDMA machine.
If these credentials are not provided, auto-registration will be disabled on this machine, and the
older auto-configuration protocol will be used instead.
Registration username: e.g., gdma Registration password: e.g., gdma Re-enter password: e.g., gdma. Next.

Enter the host profile and service profile names to be applied to this machine's monitoring
setup during auto-registration. These values are optional; if left blank, the host profile will be
defaulted on the server, and no extra service profile will be applied.
Host profile name: e.g., gdma-windows-host, Service profile name: <blank>. Next.

Setup is now ready to begin installing GroundWork Distributed Monitoring Agent on
your computer. Next.

Commit - Just like the addition of any other host, you will need to run a Configuration > Nagios Monitoring > Control > Commit operation to allow the monitoring engine to recognize the host and see it in Status.
Build Externals - Additionally, since this is an addition of a GDMA host you will need to run a Configuration > Nagios Monitoring > Control > Build externals operation so the configuration changes can be picked up by GDMA hosts.

How to install and configure GDMA Auto-Registration

Change the default username and password

Change the password on the agent

Configuring the GroundWork server

Configuring the client server

Related articles