About GDMA Installation

This document outlines the installation of the GroundWork Distributed Monitoring Agent (GDMA) version 2.7.1 for Linux and Windows client servers. This installation process will prompt for the type of auto-configuration to run to establish the setup for the GDMA client, either Auto-Registration which is based on profile names configured on the client, or Auto-Setup which is based on discovery instructions managed on the server. In the install steps below, you will first need to uninstall the legacy client if you are upgrading an existing GDMA client server, then proceed to downloading the agent and installing the agent. The GroundWork server, as the target server for GDMA results and a source for GDMA configuration data, is setup to auto register GDMA client servers. For an overview of GDMA and other related documentation please see GDMA Monitoring.

Pre Installation Checklist

GDMA Release Notes
The Release Notes for GDMA version 2.7.1 contain new features, important updates, and pre-configuration considerations.

Database Backup and Restore
Monarch is the configuration database. It is highly recommended in a production environment to back up the Monarch database before beginning a GDMA configuration.

GDMA Accounts
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. These same credentials are also used when HTTP (or HTTPS) is selected during installation instead of NSCA as the spooler transport for sending check results to the GroundWork server.

GDMA Windows as Non-admin User
It is possible for a site to run the GDMA server as a non-administrative user. Many customers would prefer this as a means of limiting the overall security profile of this service.

Non-Windows GDMA Unix user account must be local
To avoid any dependencies that might disrupt the monitoring, the GDMA Unix user account supplied during installation must be a local account, not an LDAP or Active Directory account. The GDMA installer will create this account when you provide the username/password info, but you must ensure LDAP or AD does not interfere with that action and create a network account instead.

DNS
The use of 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.

Clock Synchronization
GDMA requires clock synchronization between your GDMA system and the master GroundWork system. Before installing, ensure that the clock on this system is correct.

Installation for Linux

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

Uninstall the Legacy Client (Linux)

Access a command line interface for the Linux GDMA client server.
Backup any custom plugins in the /usr/local/groundwork directory structure.
Next, as root user (sudo su -), run the following script to uninstall the agent:
```
/usr/local/groundwork/uninstall
```
CODE
- You will be prompted with the question Do you want to uninstall GroundWork Distributed Monitoring Agent and all of its modules?, confirm the uninstall.
Remove the groundwork sub-directory and all sub-directories:
```
rm -rf /usr/local/groundwork
```
CODE
On the GroundWork server delete the GDMA client host within the Auto Registration host group by selecting Configuration > Nagios Monitoring > Hosts > Hosts > Auto-Registration, select the host, select Detail, scroll down to the bottom of the page and click Delete. Then run a Commit operation by selecting Configuration > Nagios Monitoring > Control > Commit.

Download the Agent (Linux)

You can download the latest GDMA from the Downloads page.
If necessary relocate the agent to the client server.

Install the Agent (Linux)

The following steps are for a Linux text-mode install, the most common install if you're not performing an unattended-mode install. Linux, just like Windows, also supports a GUI-mode install. For additional information see the section Special Considerations below.

As root user (sudo su -), make the installer executable (example shown, please use the current .run file):
```
chmod +x groundworkagent-2.7.1-127-linux-64-installer.run
```
CODE
Launch the agent (example shown, please use the current .run file):
```
./groundworkagent-2.7.1-127-linux-64-installer.run
```
CODE
During the installation process you will be prompted with a series of questions outlined here:
1. Synchronization and DNS
  
  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
2. GroundWork server name
  
  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:
  - Make sure to enter the name of the GroundWork server with a real FQDN in place of [gdma-autohost].
3. OS username
  
  Please specify the user name to be used by the Agent. This is the operating-system user account that will own the installed GDMA files and that will run the GDMA service.
  GDMA username [gdma]:
4. Protocol
  
  Please select which protocol will be used to transmit configuration data between the GDMA client and the GroundWork server.
  Server communication protocol
  [1] HTTP: This option is no longer recommended, because it is insecure.
  [2] HTTPS: If you choose HTTPS, you must set up TLS certificates (see the following options).
5. TLS certificates
  
  How should TLS certificates be installed when HTTPS is being used?
  Automatic TLS certificate downloading and installation
  [1] Download certs automatically: The GDMA client will download certs from the GroundWork server.
  [2] Install certs yourself: You will install certs manually or using your own automation.
  - This is a sub-level question presented if [2] HTTPS was selected in the prior question.
6. Auto download self-signed TLS certificate
  
  How should automatically-downloaded TLS certificates be treated if they are self-signed?
  [1] Install downloaded self-signed certs: Accept such certs (not recommended; insecure).
  [2] Reject downloaded self-signed certs: Treat such certs as failing verification (recommended).
  - This is a sub-level question presented if [1] Download cert automatically was selected in the prior question.
7. Auto download TLS certificate server name match
  
  How should automatically-downloaded TLS certificates be treated if the server name in the cert does not match the server name used to retrieve the cert?
  [1] Install downloaded certs with bad server names: Accept such certs (not recommended; insecure).
  [2] Reject downloaded certs with bad server names: Treat such certs as failing verification (recommended).
  - This is a sub-level question presented if [1] Download cert automatically was selected in a prior question.
8. GDMA username and password
  
  Enter the user name and password to be used for Auto-Registration or Auto-Setup of this GDMA machine, and/or transport of check results via HTTP/S. If these credentials are not provided, then Auto-Registration, Auto-Setup, and transport via HTTP/S will all be disabled on this machine, and the NSCA transport protocol will be used to send check results.
  Registration username:
  Registration password:
  - This is the user name and password you may have set in Administration > Security under GDMA Accounts, or it may be the default credentials gdma/gdma.
9. Type of auto configuration
  
  Please select what type of auto-configuration will be run to establish the setup for this GDMA client.
  [1] Auto-Registration: Initial setup is based on profile names configured on the client.
  [2] Auto-Setup: Initial setup is based on discovery instructions managed on the server.
  [3] None: The GDMA client will not invoke any automated configuration.
10. GDMA profiles
  
  Enter the host profile and service profile names to be applied to this machines 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:
  Service profile name:
11. Check result protocol
  
  Please select which protocol will be used to send check results to the GroundWork server.
  [1] NSCA: Use the legacy NSCA protocol for check-result transport.
  [2] HTTP: Use either HTTP or HTTPS, as selected earlier, also for check-result transport.
12. Delay GDMA startup
  
  Delaying the initial start-up gives you a chance to make modifications to the setup before the first run. That might include installing a TLS certificate to support HTTPS communication with the server, or adjusting client config-file options.
  Do you want to start the GDMA service immediately after the installation? [Y/n]:
After a GDMA installation and just like the addition of any other host, you will need to run a Commit operation to allow the monitoring engine to recognize the host and display it in GroundWork Monitor. To commit, go to Configuration > Nagios Monitoring > Control > Commit.
For RHEl9 and Centos9 users, please execute the following script after installing GDMA:
1. On the Linux gdma host, download and copy the install_systemd_gdma.sh script.
2. Go to the diretry where the script is uploaded.
3. Run the following command to change the file permissions:
  
  chmod +x install_systemd_gdma.sh
  
  CODE
4. Run the following command to install the script:
  
  ./install_systemd_gdma.sh
  
  CODE
Since this is an addition of a GDMA host you will need to run a Build Externals operation so the configuration changes can be picked up by GDMA hosts. To do this, go to Configuration > Nagios Monitoring > Control > Build externals.

Installation for Windows

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

Uninstall the Legacy Client (Windows)

Access the File Explorer on the Windows GDMA client server.
Back up any custom plugins from the C:\Program Files (x86)\groundwork directory structure that you may have added. You will need to move these to the new location.
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?, click Yes to uninstall and proceed.
Using the File Explorer remove the groundwork directory and sub-directories.
On the GroundWork server delete the GDMA client host within the Auto Registration host group by selecting Configuration > Nagios Monitoring > Hosts > Hosts > Auto-Registration, select the host, select Detail, scroll down to the bottom of the page and click Delete. Then run a Commit operation by selecting Configuration > Nagios Monitoring > Control > Commit.

Download the Agent (Windows)

You can download the latest agent from the Downloads page.
If necessary relocate the agent to the client server.

Install the Agent (Windows)

The following steps are for a Windows GUI-mode install. Windows does not support a text-mode install, because of the manner in which Windows makes a split between GUI and command-line applications. That split is not healed by our Windows GDMA installer.

Find and run the installer file, e.g., groundworkagent-2.7.1-116-windows-installer.exe, on each of your GDMA client machines.
During the installation process you will be prompted with a series of questions outlined here:
1. Synchronization and DNS
  
  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
2. Installation directory
  
  Installation directory: c:\Program Files (x86)\groundwork
3. GroundWork server name
  
  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:
  - Make sure to enter the name of the GroundWork server with a real FQDN in place of [gdma-autohost].
4. OS username
  
  Please specify the user name to be used by the Agent. This is the operating-system user account that will own the installed GDMA files and that will run the GDMA service.
  GDMA username:
  GDMA user password needed? (only for an ordinary user account)
  Please specify the password to be used by the Agent.
  GDMA user password:
  - Regarding the username entry on this screen, by selecting Next > and 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.
  - If this is a standalone Windows 10 installation, then the GDMA username will be in the format of hostname\username_account_name, e.g., host name is Win10, user name is joe, so GDMA username entry would be Win10\joe.
5. Protocol
  
  Please select which protocol will be used to transmit configuration dat between the GDMA client and the GroundWork server.
  HTTP: This option is no longer recommended, because it is insecure.
  HTTPS: If you choose HTTPS, you must set up TLS certificates (see the following options).
6. TLS certificates
  
  How should TLS certificates be installed when HTTPS is being used?
  Download certs automatically: The GDMA client will download certs from the GroundWork server.
  Install certs yourself: You will install certs manually or using your own automation.
  - This is a sub-level question presented if HTTPS was selected in the prior question.
    
    Note
    
    Automatic cert downloading works in Linux GDMA 2.7.0, and all platforms starting in GDMA 2.7.1. The code for it is present in Windows GDMA 2.7.0 but it does not work on that platform.
7. Auto download self-signed TLS certificate
  
  How should automatically-downloaded TLS certificates be treated if they are self-signed?
  Install downloaded self-signed certs: Accept such certs (not recommended; insecure).
  Reject downloaded self-signed certs: Treat such certs as failing verification (recommended).
  - This is a sub-level question presented if Download cert automatically was selected in the prior question.
8. Auto download TLS certificate server name match
  
  How should automatically-downloaded TLS certificates be treated if the server name in the cert does not match the server name used to retrieve the cert?
  Install downloaded certs with bad server names: Accept such certs (not recommended; insecure).
  Reject downloaded certs with bad server names: Treat such certs as failing verification (recommended).
  - This is a sub-level question presented if Download cert automatically was selected in a prior question.
9. GDMA username and password
  
  Enter the user name and password to be used for Auto-Registration or Auto-Setup of this GDMA machine, and/or transport of check results via HTTP/S. If these credentials are not provided, then Auto-Registration, Auto-Setup, and transport via HTTP/S will all be disabled on this machine, and the NSCA transport protocol will be used to send check results.
  Registration username:
  Registration password:
  Re-enter password:
10. Type of auto-configuration
  
  Please select what type of auto-configuration will be run to establish the setup for this GDMA client.
  Auto-Registration: Initial setup is based on profile names configured on the client.
  Auto-Setup: Initial setup is based on discovery instructions managed on the server.
  None: The GDMA client will not invoke any automated configuration.
11. GDMA profiles
  
  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-windows-host
  Service profile name:
12. Check result protocol
  
  Please select which protocol will be used to send check results to the GroundWork server.
  NSCA: Use the legacy NSCA protocol for check-result transport.
  HTTP: Use either HTTP or HTTPS, as selected earlier, also for check-result transport.
13. Delay GDMA startup
  
  Delaying the initial start-up gives you a chance to make modifications to the setup before the first run. That might include installing a TLS certificate to support HTTPS communication with the server, or adjusting client config-file options.
  Do you want to start the GDMA service immediately after the installation?
  Yes
  No
If you need to install a cert, you will need to transfer the necessary root cert or self-signed cert to the GroundWork server, convert it from CRT to PEM format if necessary, then WinSCP to your Windows box.
1. Log into your GroundWork server.
2. Enter the following commands substituting your information:
```
cd gw8
mkdir certs
cd certs
docker cp dockergw8_revproxy_1:/root/certs/$YOUR_FQDN$/$YOUR_FQDN$_self-public-cert.crt .
openssl x509 -in $YOUR_FQDN$_self-public-cert.crt -out $YOUR_FQDN$_self-public-cert.pem
```
3. Run WinSCP $YOUR_FQDN$_self-public-cert.crt to your windows box c:\Program Files (x86)\groundwork\gdma\certs directory, run cmd as administrator, then:
```
cd c:\Program Files (x86)\groundwork\gdma\certs
```
4. And now c_rehash the cert from above directory:
```
..\..\common\bin\c_rehash
```
5. Now you can start your GDMA agent.
After a GDMA installation and just like the addition of any other host, you will need to run a Commit operation to allow the monitoring engine to recognize the host and display it in GroundWork Monitor. To commit, go to Configuration > Nagios Monitoring > Control > Commit.
If you've selected auto-registration or auto-setup as the means of auto-configuration, the first cut of externals is built automatically when one of those two processes is run. Generally you would only need to run a Build Externals operation if you are managing the configuration all yourself, or if you make changes later on within Monarch and want to see them reflected out on the GDMA clients. To do this, go to Configuration > Nagios Monitoring > Control > Build externals.

Special Considerations

Linux GUI-mode install

In addition to the text-mode Install the agent (Linux) that is outlined above, Linux, just like Windows, also supports a GUI-mode install. To access that mode from a remote machine, use the ssh -X option when you log in to the GDMA client, for example:

ssh -X root@myclient.com

Modern Linux distributions tend not to allow sharing of the window manager like this from remote machines, so it might take some additional setup on your desktop to allow that to work.

Unattended-mode install

All platforms support an unattended-mode install, wherein all the questions that would have been asked can be set via command-line options, and you don't get either a GUI presentation or interactive prompting. This may be useful if you want to script everything and not have to run stuff manually on hundreds or thousands of GDMA clients.

Command-line options

There is a way to provide most of the command-line options in an options file, and refer to it with an options-file option, to simplify your actual command line. The available command-line options are displayed if you run the installer with the --help option. Command-line options can be used to set initial defaults even if you're not running an unattended-mode install.

Our example below uses Linux and the contents of the options file may need to be customized for each type of platform.

Command line example: Launching the Linux installer unattended

./groundworkagent-2.7.1-127-linux-64-installer.run --mode unattended --optionfile /<path to file>/unattended.txt

Unattended.txt argument file contents:

gdma_target_server=demo1
gdma_username=gdma
gdma_protocol=http
gdma_autoregistration_username=gdma
gdma_autoregistration_password=xxxxxx
gdma_autoregistration_hostprofile=gdma-linux-host
gdma_service_start=yes