How to install GDMA
CONTENTS
RELATED RESOURCES
-
GDMA advanced (Knowledge Base)
-
GDMA configuration reference (Knowledge Base)
-
GDMA (Documentation)
-
How to run Windows GDMA as non-admin user (Knowledge Base)
-
Release Notes for GDMA 2.7.1 (Documentation)
Pre-configuration checklist
This page outlines GDMA 2.7.1 installation for both Linux and Windows.
Please start by reviewing this Pre-configuration checklist which lists important links to supporting documentation.
GDMA | For an introduction to the GroundWork Distributed Monitoring Agent (GDMA) please review read this document. | GDMA |
---|---|---|
GDMA Release Notes | GDMA release notes for version 2.7.1. Contains new features, important updates, and pre-configuration considerations. Please read this document before installation. | Release Notes for GDMA 2.7.1 |
Back up the monarch database | Monarch is the configuration database. It is highly recommended in a production environment to back up the Monarch database before beginning a GDMA configuration. | System Back up Restore |
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. | How to manage GDMA accounts |
GDMA as HTTPS | Some customers prefer the security of HTTPS when GDMA clients contact the GroundWork Monitor server to auto-register the client, and to download configuration files and plugins from the server to the client. | How to use GDMA with HTTPS |
Windows GDMA as non-admin user | 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 link in the next column. | How to run Windows GDMA as non-admin user |
Non-Windows GDMA UNIX user account must be local | To avoid any dependencies that might disrupt the monitoring, the 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 | 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. | How can I find the local timezone |
GDMA target server configuration
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. The next two sections outline Linux GDMA and Windows GDMA client server configurations.
GDMA client server configuration (Linux)
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
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
- 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
Launch the agent (example shown, please use the current .run file):
./groundworkagent-2.7.1-127-linux-64-installer.run
- During the installation process you will be prompted with a series of questions outlined here:
- 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 - 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].
- 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]: - 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). - 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.
- 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.
- 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.
- 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.
- 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. - 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: - 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. - 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.
- 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.
GDMA client server configuration (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:
- 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 - Installation directory
Installation directory: c:\Program Files (x86)\groundwork
- 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].
- 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:
far fa-square 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.
- Protocol
Please select which protocol will be used to transmit configuration dat between the GDMA client and the GroundWork server.
far fa-circle HTTP: This option is no longer recommended, because it is insecure.
far fa-dot-circle HTTPS: If you choose HTTPS, you must set up TLS certificates (see the following options). - TLS certificates
How should TLS certificates be installed when HTTPS is being used?
far fa-circle Download certs automatically: The GDMA client will download certs from the GroundWork server.
far fa-dot-circle 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.
- Auto download self-signed TLS certificate
How should automatically-downloaded TLS certificates be treated if they are self-signed?
far fa-circle Install downloaded self-signed certs: Accept such certs (not recommended; insecure).
far fa-dot-circle 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.
- 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?
far fa-circle Install downloaded certs with bad server names: Accept such certs (not recommended; insecure).
far fa-dot-circle 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.
- 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: - Type of auto-configuration
Please select what type of auto-configuration will be run to establish the setup for this GDMA client.
far fa-dot-circle Auto-Registration: Initial setup is based on profile names configured on the client.
far fa-circle Auto-Setup: Initial setup is based on discovery instructions managed on the server.
far fa-circle None: The GDMA client will not invoke any automated configuration. - 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: - Check result protocol
Please select which protocol will be used to send check results to the GroundWork server.
far fa-circle NSCA: Use the legacy NSCA protocol for check-result transport.
far fa-dot-circle HTTP: Use either HTTP or HTTPS, as selected earlier, also for check-result transport. - 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?
far fa-circle Yes
far fa-dot-circle 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.
Log into your GroundWork server.
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
Run WinSCP
$YOUR_FQDN$_self-public
-cert.crt
to your windows boxc:\Program Files (x86)\groundwork\gdma\certs
directory, runcmd
as administrator, then:cd c:\Program Files (x86)\groundwork\gdma\certs
And now
c_rehash
the cert from above directory:..\..\common\bin\c_rehash
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.