Welcome to the installation Instructions for GroundWork Monitor Enterprise Edition, version 7.1.1. These instructions are maintained in the GroundWork Knowledge Base (kb.groundworkopensource.com). If you are reading these in a PDF or other offline form, you should check the online form for the most recent version.
This document covers the installation of GWMEE 7.1.1 and supported upgrades from 7.1.0. For new installs, see the first section below. For upgrades, see the upgrade section here.
This document is supplemented by release notes, which contain details of issues fixed, new features, and items of interest to those users who have customized or significantly enhanced GroundWork Monitor Enterprise. You can view the release notes here: 7.1.1 Release Notes for EE
 | Read Me First Before performing an installation, please review the 7.1.1 Release Notes for EE, the System Requirements for 7.1.1, and any current Technical Bulletins for this version so you can prepare for any additional steps required either before or after the process. Technical Bulletins for this version of the product (if any) are listed in the Technical Bulletins for 7.1.1 page of the GroundWork Knowledge Base. |
If you need to have a new installation of GroundWork as opposed to an upgrade, use these instructions. Take a look at the options here, and then follow the steps below to install. The major installation decisions and steps are:
Transfer the GroundWork Monitor Enterprise software to the server it is being installed on.
As superuser (root), change the permissions of the binary to executable. For example:
chmod +x groundworkenterprise-7.1.1-br415-gw3089-linux-64-installer.run
You can then launch the installer with one of the methods described here. These instructions will assume you launched it in text mode, interactive, as root:
./groundworkenterprise-7.1.1-br415-gw3089-linux-64-installer.run
The installer asks questions that must be answered correctly for a successful install. Most of them are self-explanatory. Some of them are called out here so we can comment on them.
---------------------------------------------------------------------------- Select the components you want to install; clear the components you do not want to install. Click Next when you are ready to continue. PostgreSQL Database [Y/n] : GroundWork Monitoring Server [Y/n] : Is the selection above correct? [Y/n]:
If you are installing using a remote database that you have already set up with instructions here, decline the installation of the PostgreSQL Database. If you are installing an all-in-one server, where the PostgreSQL database will run locally on the GroundWork Monitor machine, enter "Y" for yes. Also enter yes for the GroundWork Monitoring Server, and yes if you selected correctly on confirmation.
---------------------------------------------------------------------------- Log Archiving Do you wish to have the installer enable a standard configuration of the log-archive capability? [Y/n]:
---------------------------------------------------------------------------- Dual JBoss Installation The GroundWork Monitor system capacity can be enhanced by enabling Dual JBoss configuration on the system. Do you want to enable Dual JBoss? [Y/n]:
 | Starting and Stopping GroundWork Monitor GroundWork Monitor includes all prerequisites and components within a single installation package. The software components of GroundWork Monitor are installed under /usr/local/groundwork, with the exception of the log rotation configuration and the start/stop script named /etc/init.d/groundwork. The start/stop script is used indirectly, as follows: service groundwork status service groundwork start service groundwork stop This script can also be used to stop, start, or restart individual services. For example: service groundwork restart nagios (The service command generally resides in the /sbin/ directory [/usr/sbin/, on Ubuntu]. That directory will normally be part of the root user's command-search path. If not, you can run the /etc/init.d/groundwork script directly, as in "/etc/init.d/groundwork start". The service command is preferred because it is easier to remember and type, however as of version 7.1.1 GroundWork has not supplied systemd compatible init scripts, so if you are running on a systemd-enabled distribution, you may have to use the init scripts directly. ) |
| Security adjustments here are paramount Documentation on changing passwords can be found in the How to change a user password page of the Bookshelf. Note that the root and admin users are special and should not be renamed or deleted without special configuration steps. |
There are 4 user-interface users defined in GroundWork by default:
Please be sure to adjust these user names and passwords according to your security policy, and do so quickly after the product is installed. You can use the encryption tool on the GroundWork License Administration page to generate secure hashes of passwords, which can be used as random passwords if you like. See Password Maintenance for details.
| An Associated File Adjustment Note that you will also need to update the portal.proxy.password in /usr/local/groundwork/config/foundation.properties if you change the user account password. See How to AD and LDAP configuration. |
GDMA
There is also a separate proxy user defined in GroundWork by default, that is used to support Automated Agent Registration. If you decide to use GDMA, we recommend you change this user's password as well. This user need have only very restricted permissions, as you will see if you set up GDMA.
Web Services API Token
On all new installs of GroundWork Monitor 7.1.1, the default Web Services API token is not randomized. You will want to reset it using the License Administration screen. See Password Maintenance for details. If you don't, it is possible that another system could use the default key to access your GroundWork installation via the API, which would be a security risk.
| External programs This password is also what is used in the ws_client.properties file, and some ancillary programs reference it (e.g., feeders, etc.). If you configure Cloud Hub connectors, you will need to use this password to connect to this GroundWork server. |
At first login, there is a default license for up to 50 monitored devices installed. Unless you plan to use only the Core edition, limited to 50 devices, you will need to log in as the admin user and copy-and-paste your license key into the portal application under the GroundWork Administration > GroundWork License menu. Don't forget to click on Validate to make it active. Each license is valid for the subscription duration purchased. Each GWOS installation has a single license file that controls access to the application user interface. The license file affects only user access to the GWOS portal; it does not affect the ability to start/stop application components or most of the data gathering, processing, or notification features of the solution.
License key validity is checked at user login and is affected by:
Please see this How-To on GroundWork Connect for more information: How-to Determine and adjust your device count
ntop is bundled into the GWMEE 7.1.1 release. It promiscuously analyzes the network traffic it can see on your GroundWork Monitor server. Because the data can be quite useful, ntop is enabled by default. It is, however, incompatible with SSL-enabled GroundWork systems, and can be considered a security risk (it is a sniffer, after all). If you decide you do not want to use this component, it can be (reversibly) disabled as follows.
service groundwork stop ntop
and then changing permissions on the control script:
cd /usr/local/groundwork/common/scripts chmod -x ctl-nms-ntop.sh
| To fully disable ntop, restrict the page Disabling the background daemon itself reduces the load it invokes by promiscuously examining your network traffic, but you will probably want to disable access to the page to avoid displaying an error message. See the GroundWork bookshelf under Portal Administration - memberships for details. |
Access to the database server is defined in configuration files like cacti_feeder.conf. The default (applicable to a local database) points to localhost. A known issue is that in the case of a remote database, the 7.1.1 installer fails to set the proper value in the cacti_feeder.conf file. So if you are using a remote database, you will need to edit that file to make sure the cactidbhost specification is the actual remote database server FQDN or IP address.
/usr/local/groundwork/config/cacti_feeder.conf:cactidbhost = localhost
After fixing that setting, you must bounce the Cacti feeder for it to pick up the new value. That will be done the next time you restart gwservices:
service groundwork restart gwservices
or you can bounce just the one process, more surgically:
kill `ps --no-headers -C .perl.bin -o pid,args | fgrep cacti_feeder.pl | awk '{print $1}'`
For comparision and completeness, we note the following places in the config files that are successfully modified by the installer:
/usr/local/groundwork/config/cacti.properties:cacti.1.dbhost=localhost /usr/local/groundwork/config/db.properties:collage.url=jdbc:postgresql://localhost:5432/gwcollagedb?prepareThreshold=1 /usr/local/groundwork/config/db.properties:collage.dbhost=localhost /usr/local/groundwork/config/db.properties:monarch.dbhost=localhost /usr/local/groundwork/config/db.properties:insightreports.dbhost=localhost /usr/local/groundwork/config/db.properties:slareport.dbhost=localhost /usr/local/groundwork/config/log-archive-receive.conf:archive_dbhost = "localhost" /usr/local/groundwork/config/log-archive-send.conf:runtime_dbhost = "localhost"
Upgrades to 7.1.1 are supported from version 7.1.0 ONLY. If you wish to do an upgrade, review this section. For a fresh installation, see New Install.
Please note that the 7.1.0 installation has a critical technical bulletin (GWME-7.1.0-2 - Archive Patch) that must be reviewed and applied prior to an upgrade to 7.1.1.
| If you are unsure if this has already been done or whether this applies to your installation, please contact GroundWork Support for assistance. |
Before you begin it is critically important that you test for each of these prerequisites and obtain them. For instance, getting partway into the process only to realize that you don't have the postgres user password and that no one can obtain it quickly means wasted time and disappointment, as well as the chance that the system may be down and require rolling back. Don't let this happen to you.
| Special Considerations
|
Checklist:
Make sure you have created a backup of the GroundWork Monitor installation using the provided backup tool. Download the latest version of the backup utility and make a full backup of your installed system, as described in the [Backup utility description].
| The latest version of the backup utility (gw-backup-br387-linux-64) includes several improvements to the backup process. Please follow the instructions in the [+Backup utility description+] before executing an upgrade. |
If any customizations have been applied, including additional scripts, plugins, etc., we recommend that for convenience you create a complete on-disk backup of /usr/local/groundwork directory, so that you can easily restore the files you added or changed. The installer will flag the files that are updated and that should be merged, but if you have the disk space available this step makes it easier to restore your customizations that the installer can't detect or anticipate. You should stop the GroundWork server and cron jobs, ensure you have adequate disk space, and make the copy like so (as root):
Check for space available:
df -h
Check for space used by GroundWork:
du -sh /usr/local/groundwork
Stop all GroundWork Processes and cron (called crond on some systems):
service groundwork stop service cron stop
Copy the directory (in this example to /tmp/gwbackup):
mkdir /tmp/gwbackup cp -a /usr/local/groundwork/* /tmp/gwbackup/
Start the services again (note: you don't need all the services to be running for an upgrade to work, only postgresql):
service cron start service groundwork start
(or)
service groundwork start postgresql
From the command line run the following:
find /usr/local/groundwork -type f -group root -exec ls -la '{}' \; |grep -E "root" |grep -Ev "\->" |grep -Ev "supervise"|grep -Ev "control" |grep -Ev "lock" |grep -Ev "status" |grep -Ev "mib_" |grep -Ev ".ctl" |grep -Ev "backup/" |grep -Ev "Catalina" |grep -Ev "/scripts/" |grep -Ev "/ntop/" |grep -Ev "apache2" |grep -Ev ".pid" |grep -Ev ".index" |grep -Ev ".log" |grep -Ev ".lck"
The result should not include any java libraries (.war, .jar, .ear) and configurations (.properties, .cfg). If any such files are found, change the user/owner to nagios.
If you are upgrading a Groundwork Installation that is installed on SLES you will need to run the following command, prior to running the installer, to verify that the postgres user is set up properly.
if mkdir ~postgres; then chown $(id -u postgres):$(id -g postgres) ~postgres; fi
If you are using GDMA and the GroundWork server version 7.1.0 you are upgrading from is using HTTPS, you will need to re-set most of the settings for HTTPS after upgrade. You will then be able to use the later version of GDMA (2.5.0) supplied with 7.1.1, and to transition the potentially large numbers of older agents without service interruptions. However, as of 7.1.1, the default SSL configuration uses only TLS 1.2, and will not accept connections from older GDMA agents without adjustment.
Please see the post-upgrade tasks section below for details. Be sure to plan for this activity after the upgrade is complete. You will eventually want to transition your GDMA agents one-by-one to the later versions (GDMA 2.5.0 or later) and eventually enable only the more secure settings of GroundWork Monitor Enterprise 7.1.1.
Distributed database configurations are supported. Therefore, a GroundWork Monitor single-server installation can be upgraded to a configuration where the GroundWork Monitor software and the database are installed on different servers. The new database instance needs to be installed before the upgrade of GroundWork Monitor can be started.
| Moving the PostgreSQL Database These instructions only describe an upgrade that keeps the database where it already is, either separated from the GroundWork Monitor server or on the same machine. Additional steps not documented here would be needed for an upgrade that would involve moving the PostgreSQL database to a separate machine as part of the upgrade. If you desire to run a separate database server, refer to the GroundWork Knowledge Base for further information, or contact GroundWork Support. |
The high-level upgrade steps for this transition are:
| Skip this step if you are running the PostgreSQL database directly on the GroundWork Monitor server. |
In order to upgrade a PostgreSQL database running on a remote machine:
chmod +x groundworkenterprise-7.1.1-br415-gw3089-linux-64-installer.run
service groundwork stop
./groundworkenterprise-7.1.1-br415-gw3089-linux-64-installer.run --mode text
Once you have a pre-upgrade backup, and (if necessary) the Remote PostgreSQL database upgraded, the remaining upgrade steps are as follows:
| The upgrade has a dependency on the curl package being installed on the system. The curl package can be installed using the system package manager.
Example RHEL/CentOS: yum install curl , apt-get install curl for Ubuntu or yast -i curl for SLES |
chmod +x groundworkenterprise-7.1.1-br415-gw3089-linux-64-installer.run
./groundworkenterprise-7.1.1-br415-gw3089-linux-64-installer.run --mode text
Export the display to user's IP address to see the installation wizard. You may exit the installation at this point or continue with the installation in text mode. Do you wish to Continue? [y/N]: y GroundWork is already installed. Do you want to upgrade? [Y/n]: y
Warning: During the upgrade procedure, the following files were detected to have modifications. They were backed up to this directory, /usr/local/groundwork/backup-2016-11-01. You will need to login in to this server and manually merge these files. Some files may appear in this list because you probably made local changes to certain options, and those changes should now be brought forward. Some files may appear in this list simply because the content of the file has changed between releases. If that is the case for a given file, and you had not changed any option values in the previous release, you should not need to do any work to merge the old and new copies at this time. Press [Enter] to continue : List of modified files: ----------------------- /usr/local/groundwork/config/cacti.properties /usr/local/groundwork/config/console.properties /usr/local/groundwork/config/db.properties /usr/local/groundwork/config/foundation.properties /usr/local/groundwork/config/perfdata.properties /usr/local/groundwork/config/status-feeder.properties /usr/local/groundwork/config/status-viewer.properties /usr/local/groundwork/config/ws_client.properties /var/spool/cron/nagios /usr/local/groundwork/apache2/conf/httpd.conf /usr/local/groundwork/common/etc/syslog-ng.conf /usr/local/groundwork/config/bronx.cfg /usr/local/groundwork/postgresql/data/postgresql.conf Press [Enter] to continue :
For easy reference after the fact, especially if some of that info has scrolled off your screen, that same information is available at this point in the upgrade report in the /usr/local/groundwork/upgrade-report.txt file.
Normally, old licenses that are still valid will continue to work after upgrade, but if you have been issued a new license file, this is a good time t install it. See: GroundWork License
Once the installer has completely finished, you must compare the new copies of these files with the backup copies, and merge any local customizations in the old files into the new files. In certain cases, the backup copy may live under a different name. For the example above, the new and old files would be found in the following locations. For simplicity of presentation, all the non-absolute pathnames in this table are specified relative to the /usr/local/groundwork/ directory. For example:
| New file | Backup copy of old file |
|---|---|
| apache2/conf/httpd.conf | backup-2016-11-01/apache2/conf/httpd.conf |
| common/etc/syslog-ng.conf | backup-2016-11-01/common/etc/syslog-ng.conf |
| config/bronx.cfg | backup-2016-11-01/config/bronx.cfg |
| config/cacti.properties | backup-2016-11-01/config/cacti.properties |
| config/console.properties | backup-2016-11-01/config/console.properties |
| config/db.properties | backup-2016-11-01/config/db.properties |
| config/foundation.properties | backup-2016-11-01/config/foundation.properties |
| config/perfdata.properties | backup-2016-11-01/config/perfdata.properties |
| config/status-feeder.properties | backup-2016-11-01/config/status-feeder.properties |
| config/status-viewer.properties | backup-2016-11-01/config/status-viewer.properties |
| config/ws_client.properties | backup-2016-11-01/config/ws_client.properties |
| postgresql/data/postgresql.conf | backup-2016-11-01/postgresql/data/postgresql.conf |
| /var/spool/cron/crontabs/nagios | backup-2016-11-01/crontab-nagios-2016-11-01 |
Often, the differences you find between the new copy and the old copy will be due to small differences in timestamps, commenting, or spacing, and can be safely ignored. Sometimes, new information will be present in the new copy that should be left alone. Only change those areas of the new files that you know you are responsible for.
| Understanding Installation Problems The installer leaves a log file in a filename like bitrock_installer_10602.log which contains a record of the install processing. In case of trouble during the installation phase, that's a primary place to look for clues. |
Once the upgrade process is complete, you must take the following steps to fully instantiate the changes:
service groundwork restart
| Troubleshooting Advice The most common reason we have seen in testing for a failure to access the monitoring system UI at this point is that the user's browser is retaining some data that is not automatically cleaned up by the new release. If you have trouble accessing the Configuration screens in the user interface, try logging out, clearing your browser cookies and cache, and logging back in again. |
After a successful upgrade to GroundWork Monitor Enterprise 7.1.1, some additional steps are necessary to finish the upgrade process. Please review the following notes and make sure that you apply the changes to your installation.
cp /usr/local/groundwork/backup-2016-12-02/config/cacti_feeder.conf /usr/local/groundwork/config/cacti_feeder.conf
cp /usr/local/groundwork/backup-2016-12-02/config/cacti_feeder_localhost.conf /usr/local/groundwork/config/cacti_feeder_localhost.conf
cp /usr/local/groundwork/backup-2016-12-02/config/ws_client.properties /usr/local/groundwork/config/ws_client.properties
chown nagios:nagios /usr/local/groundwork/config/cacti_feeder.conf chown nagios:nagios /usr/local/groundwork/config/cacti_feeder_localhost.conf chown nagios:nagios /usr/local/groundwork/config/ws_client.properties
/usr/local/groundwork/core/migration/migrate_RAPID_feeder_configs_711.sh
cp /usr/local/groundwork/backup-2016-12-02/config/gatein.properties /usr/local/groundwork/config/gatein.properties
/usr/local/groundwork/java/bin/java -cp /usr/local/groundwork/jpp/modules/com/groundwork/security/main/groundwork-jboss-security-7.1.1.jar com.groundwork.core.security.GateinConfigurationUtils -superuser svc_gwroot
| Note that as the certificates you had previously were preserved, there is no need to regenerate them (SSL steps 1 through 7) or to import them into the keystore (steps 15 and 16). |
If you are Using GDMA with HTTPS, once you upgrade to 7.1.1 the server-side SSL settings will restrict communications to use the TLS 1.2 protocol only, and strong ciphers. GDMA agent releases before 2.5.0, as supplied with GroundWork Monitor 7.1.0 and older versions, do not support TLS 1.2. As such, they will not be able to retrieve new configurations from the default GroundWork Monitor 7.1.1 server setup with HTTPS. A different channel is used to send data monitoring results to the server, and that will still be working, at least until the GDMA client's configured Poller_Pull_Failure_Interval expires (default is 1 day). You will want to act immediately to allow the old agents to pull configurations, and soon start to upgrade GDMA agents to the latest versions.
Until you have all your old GDMA agents upgraded, the best approach is to leave as much of the upgraded protocol and cipher-list support in place as possible, and only open a hole large enough for the old GDMA clients to still connect. Here are the steps for that. All of the changes are made to the /usr/local/groundwork/apache2/conf/extra/httpd-ssl.conf file. We leave comments in the config file as breadcrumbs pointing the way back to locking down security once you no longer have any older GDMA clients in play.
SSLProtocol -all +TLSv1.2
to this:
# SSLProtocol -all +TLSv1.2 # The preceding line should eventually be put back into play. # The following line is only in use until all GDMA clients have been converted to # run GDMA 2.5.0 or later, at which point the earlier line should be put back. SSLProtocol -all +TLSv1.2 +TLSv1
SSLCipherSuite ECDHE-RSA-AES128-GCM-SHA256: ... :!DES:!RC4:!3DES:!MD5:!PSK
then make an uncommented copy of it underneath that, and add comments and change the new line so the set of lines reads:
# SSLCipherSuite ECDHE-RSA-AES128-GCM-SHA256: ... :!DES:!RC4:!3DES:!MD5:!PSK # The preceding line should eventually be put back into play. # The following line is only in use until all GDMA clients have been converted to # run GDMA 2.5.0 or later, at which point the earlier line should be put back. SSLCipherSuite ECDHE-RSA-AES128-GCM-SHA256: ... :!DES:-RC4:!3DES:!MD5:!PSK:RC4-SHA
Which is to say, in the new uncommented line, change !RC4 to -RC4 and add :RC4-SHA at the end.
#SSLHonorCipherOrder on
to this:
SSLHonorCipherOrder on
so TLS 1.2 clients (browsers, and GDMA 2.5.0 clients) will prefer the modern set of ciphers over RC4-SHA.
service groundwork restart apache
Once you complete all the GDMA upgrades at your site, you can move the new (unaltered 7.1.1) settings of SSLProtocol and SSLCipherSuite back into place and restart Apache again. For more subtle configurations, and advice on managing this process, please contact GroundWork Support.
If you have upgraded an installation of GroundWork 7.1.0 with Log Bridge installed, please see the Post-upgrade tasks for Log Bridge installations page for additional post-upgrade tasks.
There is a new dashboard/portlet application that is not enabled on upgrade by default, see: Adding Hit List Dashboard