Welcome to the installation Instructions for GroundWork Monitor Enterprise Edition, version 7.1.0. 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.0 and supported upgrades from earlier versions.
This document is supplemented by the 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.0 Release Notes for EE
|Before starting the upgrade process make sure that your system is fully functional and that you went through the Upgrade preparation Checklist.|
- Installing GroundWork Monitor 7.1.0
- Upgrade preparation Checklist
- Check list
- Permission & Ownership check
- Duplicate Host entries
- JBoss portal memberships
- Installations with GDMA reporting to GroundWork Server
- Cloud Hub Connectors on GWME 7.0.2 SP02
- LDAP configured systems with non default portal root user
- System Requirements
- Platform Requirements
- System Configurations and Operating System Settings
- Java Compatibility
- Externally Defined User Nagios
- PostgreSQL Database Location
- Distributed Database Installation Overview
- Remote Database Install
- Fresh Installation
- Disk Layout
- Software Preparation
- Installation Methods
- Post-Install Configuration
- Upgrade to 7.1.0 from a Previous Version
- Supported Upgrade Paths
- Upgrade Options
- PostgreSQL-to-PostgreSQL Release Upgrade Procedure
- Upgrade a Remote PostgreSQL Database
- Upgrade of GWMEE Components in PostgreSQL-to-PostgreSQL Upgrade
- Final Steps in PostgreSQL-to-PostgreSQL Upgrade
- Post Upgrade Tasks
- Verify Schema Version
- Cloud Hub
- LDAP (Microsoft Active Directory (AD) Server or openLDAP)
- Systems with root user changed
- Replace "foundation-webapp.war" to resolve token management issues
- Replace "nms-rstools.war" and associated yii directory and files
- Nagios Downtimes scheduled before upgrade (GWME 7.0.2 SP02 systems only)
- GDMA agents reporting to the GroundWork server
- GroundWork Monitor Enterprise Virtual Appliances for VMWare
|Read Me First|
Before performing an installation, please review all curfourent 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 are listed in the Technical Bulletins for 7.1.0 page of the GroundWork Knowledge Base.
Before you begin it is critically important that you test for each of these prerequisites and obtain them. Getting partway in to 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, too.
Make sure you have created a backup of the GroundWork Monitor installation using the provided backup tool.
If many customization were applied including additional scripts, plugins etc it is recommended to create a complete backup of /usr/local/groundwork directory:
Remember to use the "p" flag and the "-acls" flags to preserve owner and permissions
- Is Portal Admin User still "root"?
- Try logging in to portal as "root"
- If Portal Admin was changed, what is the new name?
- What is Portal Admin User Password?
- Try logging in to portal as "root"
- What is the "postgres" user Password?
- Try accessing psql i.e. "psql -U postgres"
- Make sure that the portal and other services are running before you start the upgrade since the installer verifies credentials duting the upgrade process.
From the command line run the following steps:
The result should not include any java libraries (.war, .jar, .ear) and configurations (.properties, .cfg). If there any files that match this category are found the permission would need to be changed to user/owner nagios
The Host Aliasing feature introduced with GWME 7.1.0 requires unique host identities. It previous versions duplicate host entries (differing by case only) could be inserted into the GWCollage database which is no longer allowed. Before doing the upgrade, please check if you have any duplicate entries and run the cleanup script before updating.
Details about the check and cleanup are located at this page: GWME-7.1.0-1 - Removing duplicate host entries in gwcollagedb database prior to upgrade from 184.108.40.206
In GroundWork Monitor 7.1.0 access control to third party application are managed through portal memberships. The new implementation is not backwards compatible which requires that the custom memberships are deleted before the upgrade and re-created after a successful upgrade to GWME 7.1.0. The build in memberships (GWAdmin, GWOperator, GWUser, GWRoot) are converted to the new memberships: gw-monitoring-administrator, gw-monitoring-operator, gw-portal-user an gw-portal-user and no action is necessary for user linked to these memberships.
In GroundWork Monitor Enterprise 7.1.0 the REST API uses token based authentication which requires an update of all clients connecting to the API. This would require to update all deployed GDMA agents for Auto Registration and plugin updates. To guarantee backwards compatibility with existing GDMA deployments GWME 7.1.0 uses a legacy API for GDMA's that still accepts the credentials. On the GroundWork Monitor Server the user that is used by the deployed GDMA's needs to be added to the JBoss credential store. The steps are described in the Post Install instructions.
The GroundWork REST API authentication changed between GWME 7.0.2 SP02 and GWME 7.1.0 and is now Token Based Authentication and no longer user based authentication (requiring a valid portal user). After the upgrade the credentials need to be adjusted for each connector. To avoid login failures (errors in the log files) during the upgrade process it is recommended to stop all configured Cloud Hub connectors and starting them again after the credentials have been updated (Post Upgrade Tasks below).
Note: If you are upgrading from a GWME 7.0.2 SP03 this step is not necessary since the version already uses Token Based Authentication.
During the upgrade of systems with LDAP configured the validation of the portal root user would be run against the local database and not LDAP.
Before starting the upgrade set the password for the Portal root user (default root) to a value that will be used for the upgrade (prompted during the upgrade). Once the installation is complete the local account will no longer be used since the credentials from the LDAP/AD store are used.
To set the Portal root user password execute the following steps:
Open a terminal and ssh to the GroundWork server. Get root access and then execute the following commands:
Change the password to any value (example below: pwdportal) for the root portal user (example below: root)
When prompted by the installer provide the credentials set in the above command:
The system requirements are unchanged from the prior release. GroundWork recommends the following minimum hardware specification for correct operation in production:
- 64-bit CPU (required)
- 2 CPU, 3 GHz P4 or equivalent
- 4 GB RAM
- 160 GB disk
Recommended hardware specification
- Quad Core 2 class CPU
- 16 GB RAM
- 200 GB disk for system
- 500 GB disk for application
For smaller environments and evaluations, GroundWork Monitor Enterprise Edition requires a minimum of 4GB of RAM and 10GB of disk for correct operation.
|Performance on Small Systems|
If GroundWork Monitor is installed on a system with less than 4 GB of RAM, it will be configured to operate within the limited resources. The system will have lower monitoring throughput and will only support a few concurrent users as a result.
GroundWork Monitor Enterprise Edition has been tested on the following platforms:
- Red Hat Enterprise Linux 6 Server and 7 Server, 64-bit.
- CentOS 6 and 7, 64-bit.
- SuSE Linux Enterprise Server 11sp4 and 12 64-bit. SuSE has ended support for SLES 10 and GroundWork no longer supports new installation (7.0.2 or newer) on SLES 10.
- Ubuntu Server 12.04 LTS, 14.04 LTS 64-bit. Ubuntu 8.04 LTS and 10.04 LTS have reached end-of-life and GroundWork no longer supports new installations (7.0.2 or newer) on these versions.
|Special Considerations for Virtualized Environments|
Monitoring inherently has a continuous high-load resource profile. This must be taken into account when deciding whether to run in a virtualized environment, and if so, when allocating resources to a virtual host running the monitoring. If you try to install on a virtual host which has too much contention from other VMs on the same box, results are likely to be disappointing.
If you are installing in a virtualized environment, particularly VMware ESX, using a single virtual CPU is generally recommended. As with a standalone machine, a 64-bit virtual machine is required for the GWMEE 7.1.0release. Installation of VMware tools and configuration of host time synchronization is highly recommended in all VMware environments. VMware appliances downloaded from GroundWork already have VMware tools installed, and it should not be necessary to re-install or update VMware tools for proper operation.
Please read the following requirements carefully before you install GWMEE packages:
- GWMEE 7.1.0 must be installed on a 64-bit system. Note that GroundWork has dropped support for 32-bit systems as of the 6.6.0 release.
- The GroundWork installer must be able to install into the /usr/local/groundwork/ file tree.
- The uid and gid of the root user must both be 0.
- The default group for the root user must be root.
- The nagios user and group must be local to the system and not provided via directory services. Ideally, for a fresh install, these user/group names do not already exist on the system.
- If the nagios user exists (not necessary), the default group for nagios must be nagios.
- Make sure that the system you install to does not have a pre-installed Apache server or PostgreSQL database.
- The partition that GroundWork Monitor is installed to must allow setuid execution.
- If SELinux is installed, disable it prior to installation. The permissive setting is insufficient; it must be set to disabled.
Disable it immediately, prior to running the GroundWork binary installer:
Special Configuration for Virtualized Environments
- If GWMEE is deployed under VMware, resource allocation is critical to performant operation of the monitoring. For a small-to-medium installation, only allocate 1 CPU to the virtual machine; allocating more CPUs can sometimes result in worse performance. For large installations, the situation is more complex, and testing is required to get optimal settings. (A full discussion of VMware configuration is beyond the scope of this install guide.)
- In a virtualized environment, a memory reservation of 4 GB should be considered the absolute minimum. A memory reservation of 8 GB or larger is generally recommended. A memory allocation of 8 GB or more should be applied to the VM.
- If GWMEE is deployed under VMware, running X Windows on that VM is strongly discouraged. High rates of interrupts from the windowing system can have a significant negative effect on performance in a virtualized environment, due to the extra overhead of switching CPUs between VM guest hosts.
GroundWork Monitor specifically requires Sun Microsystems' Java SDK version 1.7 Update 45. This software is included in the GroundWork installation bundle. Under some circumstances, other Java packages can interfere with the Sun provided software. For Support to troubleshoot any reported issues with your system, other Java packages must be removed prior to installation by following these steps, or equivalent steps on Ubuntu-based systems.
Query for existing Java packages:
Remove the RPMs using:
Examples of conflicting Java packages include:
GroundWork Monitor uses the user account named nagios for access control to several components in the system. For this reason we prefer that the nagios user NOT exist prior to installation; the installer will then create the user and group, its home directory, and its dot-file setup in the manner we require. If you have any of the following conditions:
- The nagios user is already defined on the system.
- You have modified /etc/nsswitch.conf to support maintaining this user in some place other than local password/shadow/group files.
- You are using external authentication of another kind (e.g., LDAP) with the nagios user defined in a way that will inhibit the GroundWork installer from creating this user and its home directory.
then you must disable and remove all traces of the nagios user before the installation. To reenable such prior setup after the installation, you must take whatever steps are necessary to ensure that the user number is the same as that used by the GroundWork-installed user nagios. Also note that if the nagios user already exists before the installation, the nagios home directory is assumed to exist, and reside at /usr/local/groundwork/users/nagios.
In a simple install, the PostgreSQL databases will reside on the GroundWork Monitor system itself. But some customers might prefer to run the databases on a separate machine. If that is the case for your installation, some special instructions must be followed.
The separate database install supports the same Operating Systems as GroundWork Monitor, which are:
- Red Hat Enterprise Linux 5 Server and 6 Server, 64-bit.
- CentOS 5 and 6, 64-bit.
- Novell SuSE Linux Enterprise Server 10 and 11, 64-bit.
- Ubuntu Server 8.04 LTS, 9.10, 10.04, 12.04, 64-bit. Releases before Ubuntu 12.04 are not recommended, because starting and stopping ntop on the earlier releases is broken.
The minimal system requirements for a separate database install are:
- 64-bit CPU (required)
- 2 CPU, 3 GHz P4 or equivalent
- 4 GB RAM
- 80 GB disk
To install a separate database, the same installer package (e.g., groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run) can be used. In general, the procedure to install GroundWork Monitor 7.1.0 with a separated database is the following:
- Download the installation package to the database server which matches the requirements and specifications described above.
- Make sure you know the fully-qualified hostname and IP address of the GroundWork Monitor server which will access this database.
- Run the installer on the database server and select the database installation only (details are provided in the next section). Don't install the GroundWork Monitor component. Make sure the database is installed and running before installing GroundWork Monitor on a different server.
- Download the installation package to the server where GroundWork Monitor will run.
- Run the installer on the GroundWork Monitor server and just install the GroundWork Monitor component. Do not install PostgreSQL, since it is running on a different server.
- When prompted, enter the location and password for the remote PostgreSQL install, and complete the installation.
More details on the installation steps can be found in the following chapters describing fresh installations or upgrades.
Having a separate database instance on a different machine than the GroundWork Monitor installation is supported in GWMEE 7.1.0. The installation of a separate database instance is the same for new installations or upgrades of GroundWork Monitor. As outlined above, the remote database instance must be installed prior to installing a new instance or upgrading from a previous release of GroundWork Monitor.
|Controlling GroundWork Monitor Components|
In a remote-database configuration, probing for current status of the GroundWork Monitor system only reflects the components which are operating on the system where the probe is run. Thus, on the remote database server, you will see:
while on the GroundWork Monitor server, you will see the rest of the monitoring components:
In the current release, stopping and starting these components can only be carried out directly on their respective machines. The GroundWork Monitor server does not remotely control starting and stopping of the PostgreSQL database in this type of installation.
|With Rights Come Responsibilities|
In an all-in-one GroundWork Monitor server, where the database runs locally, the component control scripting logic ensures that when you stop and start the whole system, the database is always started first and stopped last. That way, it should always be up when other components reach out to read or store information in it.
In a remote-database setup, the two sides are independently managed; there is no logic that will automatically start the database simply because you wanted all the other components to be running. So if you choose to install a remote database, you will also be assuming the responsibility for always starting it up before all other components, and shutting it down only after all other components are down. Any violation of this practice will risk damaging the database content. If you do sometimes get things out of order, it may be necessary to shut down all the components on the GroundWork Monitor server, ensure that the database is up, and bring the GroundWork Monitor components back up again. That might be the only way to get them once again properly initialized in synchrony with the database content.
If you want to separate your PostgreSQL database from the GroundWork Monitor server, now is the time to get the PostgreSQL server set up. The PostgreSQL database must be up and running when the installer is later run on the GroundWork Monitor server, even in the first phase of an upgrade from an older MySQL-based release just to install the cleanup scripts there. If you will run the PostgreSQL database on the GroundWork Monitor machine as an all-in-one server, skip these steps.
- While installing the database, if you wish to specify the GroundWork Monitor server as a hostname instead of an IP address, you will need to know how the database server resolves the IP address of the GroundWork Monitor server into a hostname. You will need to specify that form of the hostname (fully qualified, or unqualified) in response to a question below, if you don't specify the IP address. An easy way to find the proper form is to run a ping command on the database server, trying to sense the GroundWork Monitor server:
The form of the hostname that shows up in the PING line (fully qualified, or unqualified, as shown in these examples) is what you will need below.
- On your database machine, look at the /etc/hosts file. Make sure that the database-machine name(s), qualified and/or unqualified as will be known by the GroundWork Monitor server, are defined using an IP address accessible from the GroundWork Monitor server, and not something like 127.0.1.1 instead.
- Download the installer (e.g., groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run) to the database machine.
- Make the installer executable:
- Run the installer on the database machine in either text or GUI mode. An unattended-mode install won't work, because you need to answer certain questions to get the remote database configured properly.
- After some preliminaries, the installer will ask what parts of the GroundWork Monitor product should be installed. For a remote database server, you want only the PostgreSQL database component. Do not select the GroundWork Monitoring server.
- The installer will ask a couple of questions so it can set up remote access by the GroundWork Monitor server to the PostgreSQL database. Read the questions carefully before answering. For the second question, if you want to specify a hostname, use the unqualified or fully qualified form determined above.
- Specify the power-user password for the PostgreSQL database. Remember what you type here, as this password will be needed for future database maintenance.
- Answer the remaining questions, and allow the installation of the database components to complete.
- You may have a firewall surrounding your database server. This might be either iptables(8) running on the database server itself, or some external network equipment that serves the same purpose. If such a firewall is in play, you must configure it to allow access to port 5432 on the database server from the GroundWork Monitor server.
Setup for an iptables Firewall
See [How to determine ports used by GroundWork] in the GroundWork Knowledge Base for some clues as to how to configure an iptables firewall with regard to a remote PostgreSQL server.
After these configuration steps are completed, the database component will be installed and started. You can now continue and install or upgrade GroundWork Monitor Enterprise on a different server pointing to the database server.
|First Things First|
If you want to use GroundWork Monitor with a remote database, first carry out the Remote Database Install procedure in the section above, before taking the steps in this section for a fresh installation of GroundWork Monitor.
First, decide which disk the GroundWork Monitor install will reside on. It will be placed in the /usr/local/groundwork/ directory, which by default will usually reside on the system disk. If you wish to relocate the installation to a different drive, that is most easily done by setup before the installation proper. Your choices are:
- Ignore the /usr/local/groundwork/ directory. The GroundWork installer will create it and set its ownership and permissions as needed, on whatever disk/partition the /usr/local/ directory resides on.
- Leave a symlink at /usr/local/groundwork to point elsewhere. For instance, if I wanted to install the software under /tmp/local/groundwork/ (not that that's a good place to put it), I could create:
and then install the software. You need not create the nagios user or group beforehand; the installer will do so as needed, and change the ownership of the target directory accordingly. Regardless, the target directory should start with 755 permissions, as shown above.
- Create the /usr/local/groundwork/ directory and mount some disk partition on that directory. After the mount, check the ownership and permissions of the mount point:
As before, the installer will adjust the ownership of the root of the mounted partition as needed during the installation process.
Transfer the GroundWork Monitor Enterprise software to the server it is being installed on.
Change the permissions of the binary to executable. For example, with the 64-bit installer binary:
The installer package supports 3 modes: GUI, text, and unattended. The default is GUI if an X server is running; otherwise, text mode will be used. GroundWork does not recommend running the X server in a production deployment, due to the unnecessary overhead.
From a system with X server running, simply double-click on the run file. Alternatively, go to the command shell and execute the downloaded file:
From a command shell, execute the binary with the text-mode installation selected:
From a command shell, execute the binary with the unattended-mode installation selected:
This will perform an unattended installation that will not prompt the user for any information.
|Unattended Mode Constraints|
If you run the installer using the command just displayed, the installation will fail because it tries to install the PostgreSQL database without a password for the postgres user. An installation like that is inherently insecure, and is not supported. For an unattended install, you must use the "--postgres_password password" option, either on the command line or in an option file as described below.
Also, an unattended install will reference a local database only.
Passing the "--optionfile optionfile" command line option lets you specify installation options in a separate file. The option file should contain one line per option, using the format key=value. You can use any of the options accepted by the installer. For information on valid options, execute the binary with the --help switch. For example, to use a PostgreSQL password specified in the options, you could use:
where the gwinstall.ini file contains:
Using SSH, access a remote server and use the text based install (see above). This is the most common way to install GroundWork Monitor remotely. If you perform the remote install from a machine that runs an X server, you can use SSH with the -X option and run the install with the GUI mode. For example:
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.
- Questions about the components to install:
If you are installing using a remote database, you must decline the installation of the PostgreSQL Database when you run the installer on the GroundWork Monitor machine. Conversely, if you are installing an all-in-one server, where the PostgreSQL database will run locally on the GroundWork monitor machine, specify instead that you want this component installed. In either case, the GroundWork Monitoring Server component must be installed on this machine.
- The next question is about Log Archiving. You can either enable the Log Archiving capability (default) or disable it. For details on what this is all about, see the [GroundWork Archive Server] page. (That page is currently undergoing revision, and will be available shortly.)
- End-stage activity:
It says it has finished installing, but in fact it still has some work to do. Don't interrupt at this point; let it finish on its own. Meanwhile, the first character on that last line will keep spinning. This will take several minutes; don't panic.
|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:
This script can also be used to stop, start, or restart individual services. For example:
(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.)
There are 4 user-interface users defined in GroundWork by default:
- root (password: root)
- admin (password: admin)
- operator (password: operator)
- user (password: user)
|Security adjustments here are paramount|
Please be sure to adjust these user names and passwords according to your security policy, and do so quickly after the product is installed. 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.
|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 LDAP (Microsoft Active Directory (AD) Server or openLDAP).
There is also a user account defined for use with various web-services calls:
|Another Associated File Adjustment|
Note that you will also need to update the webservices_password in /usr/local/groundwork/config/ws_client.properties if you change the wsuser account password.
Starting with the 6.7.0 release, there is also a separate proxy user defined in GroundWork by default, that is used to support Automated Agent Registration.
Please be sure to adjust the user name and password for this user according to your security policy. This user must have only very restricted permissions, as you will see set up for the gdma user immediately after installing the product.
At first login, the admin user must copy-and-paste their license key into the portal application under the GroundWork Administration > GroundWork License menu item. 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:
- The subscription start and end dates.
- The number of monitored devices configured.
- Whether the Network Service is enabled.
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.0 release. It promiscuously analyzes the network traffic it can see on your GroundWork Monitor server. Because the data can be quite revealing, ntop is enabled by default. If a site decides it does not want to accept the system load imposed by this component, it can be (reversibly) disabled as follows.
- If the config/ntop.properties file is renamed before the gwservices component (or all of GroundWork Monitor) is started, the ntop UI will not be accessible under the Advanced > Protocol Analyzer menu item.
- The ntop daemon itself can be disabled by first stopping it:
and then renaming the control script:
|To fully disable ntop, both adjustments are needed|
These two actions (disabling UI access through GroundWork Monitor, and disabling the daemon) are in fact independent. Disabling access via the UI has little to do with the background daemon itself, so if you want to avoid the load it invokes by promiscuously examining your network traffic, you must take both steps.
GroundWork Monitor Enterprise 7.1.0 supports inplace uprades from the following versions:
- GroundWork Monitor 7.0.2 with ServicePack 2 (SP02)
- GroundWork Monitor 7.0.2 with ServicePack 3 (SP03)
Any prior versions need to be upgraded to GWME 7.0.2. After the upgrade SP02 needs to be applied. After the complete upgrade to GroundWork Monitor Enterprise 7.0.2 /SP02 make sure that all components are functioning correctly and now errors occur.
A lot of changes have occurred in the GWMEE product over time. The upgrade paths listed in the table below are designed to minimize the chances of error by using standard upgrade procedures between releases to accommodate those changes, and to provide safe pause points at which you can verify the system is operating correctly, instead of trying to accomplish everything at once.
|Current GWMEE Release||Current Architecture||Required Upgrade Path|
|5.x, 6.0, or 6.0.1|| 32-bit or 64-bit
||Contact GroundWork Support. These releases have been previously EOL'd.|
|6.1, 6.1.1, or 6.2||32-bit||
|6.1, 6.1.1, 6.2, 6.3,6.4||64-bit||
|6.3, 6.4 or 6.5||32-bit||
|6.4 or 6.5||64-bit||
|6.6, 6.6.1, 6.7.0, 7.0.0 or 7.0.1||64-bit||
|Special handling of the Cacti database access credentials|
If you originally had the NMS version of Cacti installed, you must make sure the cacti_db_host, cacti_db_user, and cacti_db_pass values from the original install (the /usr/local/groundwork/common/etc/check_cacti.conf file, which was backed up during the upgrade to 6.5 in a file such as /usr/local/groundwork/backup-2012-02-08/common/etc/check_cacti.conf) have been copied into the cacti.1.dbhost, cacti.1.dbuser, and cacti.1.dbpass fields of the /usr/local/groundwork/config/cacti.properties file, so migration of the cacti database content to PostgreSQL will work smoothly.
|Special handling of the NeDi database access credentials|
If you originally had the NMS version of NeDi installed, you must make sure the dbuser, dbpass, and dbhost information from the original install (the /usr/local/groundwork/nms/applications/nedi/nedi.conf file, which was backed up during the upgrade to 6.5 in a file such as /usr/local/groundwork/backup-2012-02-06/nedi/nedi.conf) has been copied into the /usr/local/groundwork/nedi/nedi.conf file, so migration of the nedi database content to PostgreSQL will work smoothly. Do not replace the entire content of the nedi.conf file, as many other details of the configuration data have changed between the respective NeDi releases.
Starting with GWMEE 6.6.1, distributed database configurations are supported. Therefore, a GWMEE 6.1 - 6.5 single-server installation can be upgraded to a configuration where the GroundWork Monitor and the database are installed on different servers. The database instance needs to be installed before the upgrade of GroundWork Monitor can be started.
Upgrading from a GroundWork Monitor release which is already using PostgreSQL (release 6.6, 6.6.1, 6.7.0, or 7.0.0) is much simpler. No database cleanup is necessary.
|Moving the PostgreSQL Database|
This process only describes 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. If you desire to run a separate database server, refer to the GroundWork Knowledge Base for further information.
The high-level upgrade steps for this transition are:
- Final Pre-Upgrade Backup — 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-br339-linux-64) includes several improvements to the backup process. Please follow the instructions in the before executing an upgrade.
- Upgrade a Remote PostgreSQL Database — If you were previously running a Remote PostgreSQL database, that component must be migrated first.
- Upgrade of GWMEE components — All GroundWork components must be upgraded to the latest version.
- *Final Steps — The installation is not complete until the license key is installed and monitoring is restarted to use the new software.
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, you must:
- Download the latest version of the Backup utility [Backup utility description].
- Make backup utility executable:
- If you have enough space in the /tmp directory, this version of the backup tool should normally be run this way when operated during an upgrade situation, substituting your own database password for the postgres user:
That command will deposit the resulting tarball in the /tmp directory, in a timestamped file such as the following:
- Download the installer (e.g., groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run) to the Remote PostgreSQL database server.
- Make the installer executable:
- Back on the GroundWork Monitor server, stop the software for the duration of this part of the upgrade:
- Run the installer on the Remote PostgreSQL database machine, and answer the prompts in the obvious ways.
- As usual, you will find the upgrade report in the /usr/local/groundwork/upgrade-report.txt file. For the upgrade to 7.1.0, the upgrade report will list the postgresql.conf file as one that has been changed in the upgrade. If for no other reason, that will be true because we modified certain logging parameters (logging_collector, log_filename, and log_rotation_age) in the 7.1.0 release to properly implement log file rotation. Those changes are expected. You'll have to handle any other differences between the installed copy and the backed-up copy on a case-by-case basis.
Once you have a pre-upgrade backup, and (if necessary) the Remote PostgreSQL database upgraded, the remaining upgrade steps are as follows:
|If you are upgrading from a GWME 7.x system the CURL package needs to be present 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
- Download the installer (e.g.,groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run) to the GroundWork system that needs to be upgraded.
- Make the installer executable:
- The following action applies if you are running an older Ubuntu release (before 12.04, which is not recommended, as stated earlier in these instructions). You must stop the ntop process before running the installer, because having it run while the installer runs can potentially interfere with operation of the installer. Since the ntop scripting for stopping this process does not work correctly under these older Ubuntu releases, you will need to find and kill any such process manually.
- Execute the installer. You may run in unattended mode (--mode unattended) if desired. Here, we will show the interaction that would occur in text mode.
- The installer detects an upgrade. Choose yes to continue.
- The rest of the questions should also be self-explanatory; answer them in the obvious ways (backup, database user verification).
- If you are upgrading from a GWME 7.x system you'll be prompted to provide the Portal root user credentials. The credentials are used to add new administrative portlets to the portal. Please note that the portal root user is generally different than the admin user or the linux root user. The credentials will be verified before continuing and if the validation fails the upgrade will not continue.
It is important to note that the root password needed here is the JBoss jbid_io_creden root password. This is the password stored within GroundWork Monitor itself, not a password which may have been subsequently defined in LDAP or AD. See the following note for additional detail. GroundWork Monitor 7.0.1 introduced the root user. The main purpose of this user is portal administration and by default the root user's password is root. If this password has been changed to a more secure password you will need to use the following command to reset the root password before performing an upgrade:
update jbid_io_creden set text = md5('changeme') from jbid_io u, jbid_io_creden c where u.name = 'root' and u.id = c.identity_object_id;
- Allow the installer to complete on its own; don't interrupt it. In our testing on medium-grade equipment, this part ran for 15 minutes.
- Right before the end of the upgrade, a list of files you need to deal with manually will have been displayed:
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.
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.
New file Backup copy of old file apache2/conf/httpd.conf backup-2013-11-19/apache2/conf/httpd.conf common/etc/syslog-ng.conf backup-2013-11-19/common/etc/syslog-ng.conf config/bronx.cfg backup-2013-11-19/config/bronx.cfg config/cacti.properties backup-2013-11-19/config/cacti.properties config/console.properties backup-2013-11-19/config/console.properties config/db.properties backup-2013-11-19/config/db.properties config/foundation.properties backup-2013-11-19/config/foundation.properties config/perfdata.properties backup-2013-11-19/config/perfdata.properties config/status-feeder.properties backup-2013-11-19/config/status-feeder.properties config/status-viewer.properties backup-2013-11-19/config/status-viewer.properties config/ws_client.properties backup-2013-11-19/config/ws_client.properties postgresql/data/postgresql.conf backup-2013-11-19/postgresql/data/postgresql.conf /var/spool/cron/crontabs/nagios backup-2013-11-19/crontab-nagios-2013-11-19
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 component installation is complete, you must take the following steps to complete the upgrade:
- If you had to modify any files just above after the installer finished, you should bounce the entire system to make sure all components are restarted with the revised configurations.
- Download and run the upgrade_gwcollage_plugin_tables.pl script provided in TB 7.0.1-1. See the instructions in that Technical Bulletin for details.
- Log in to the UI as an administrative user.
- Run a Configuration > Control > Commit operation to put the upgraded configuration data fully into production. This will establish that all of the database configuration and connections are working as intended, and that all areas of the monitoring configuration are fully synchronized.
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.
- Establish non-default passwords for all of the standard GroundWork-supplied user accounts listed in the [Default Login Information|#default_login_information|||||||||||||||||||||||||||||||||||||||||||||||\||] subsection above.
- Configuration of enabling SSL and integration with LDAP has changed in the 7.0.1 release. See the SSL instructions and the LDAP instructions for details. If either of these situations applies to you, take care of those setups now.
- If you have GroundWork Distributed Monitoring Agents (GDMA) in play, the GDMA clients periodically refresh their externals files from the server. But immediately after the upgrade, those externals files are now effectively gone from the server. (They were backed up, but they're not in the production directories at this time.) To regenerate the externals files so you don't get stale check results from GDMA clients, run a "Configuration > Control > Build externals" operation.
After a successful upgrade to GroundWork Monitor Enterprise 7.1.0 some additional steps, depending on your setup are necessary to finish the upgrade process. Please review the following notes and make sure that you apply the changes to your installation.
In some cases the schema is not migrated because duplicates records were not cleaned up. GWME-7.1.0-1 - Removing duplicate host entries in gwcollagedb database prior to upgrade from 220.127.116.11 covers that cleanup but to be sure run the following command:
- If you see "7.1.1" you database schema is current and you can skip the rest of this section
- If you see "7.0.2" you will need to stop groundwork, start postgresql and go through the steps in the 7.1.0-1 technical bulletin linked above and then migrate the schema to bring it current:
- If you see an number older than "7.0.2" please open a support ticket to get help in doing the database cleanup.
- The REST API authentication has changed from user based to token based authentication. For this reason the GroundWork WebServices Username: needs to be changed to RESTAPIACCESS. The GroundWork WebServices Password is now encrypted and can be obtained from the License page:
Starting with GWME 7.1.0 the password in the LDAP configuration file is as well encrypted. When running an upgrade the ldap configuration files are restored. Before users can login with their LDAP credentials the following file needs to be updated as following:
The encrypted password can be obtained by running the following command from the command line providing the un-encrypted password as argument:
The handling of the portal root user has been simplified in GroundWork Monitor 7.1.0 and is incompatible with previous versions. For this reason if the default portal user (root) has been changed in previous versions it needs to be set after the upgrade.
From the command line:
The following section needs to be added to /usr/local/groundwork/config/gatein.properties
- portal-configuration.xml setting for org.exoplatform.portal.config.UserACL
- super.user init parameter value. This setting and portal-configuration.xml
- synchronization is done on startup and when this file is modified. Once
- set, portal must be restarted for value to take effect.
After updating the gatein.properties the following needs to be executed
Some applications or customer code which use the REST API do not always logout and release their authorization tokens. Eventually the number of available tokens is exhausted and subsequent token requests fail causing the UI to become unavailable or applications to display errors.
This issue was tracked in GWMON-12686
TB7.1.0-3 should be applied to resolve this issue
GWME-7.1.0-3 - Token management
The downtime scheduling tools deny access to users who are in more than one membership.
This issue was tracked in GWMON-12486.
TB7.1.0-4 should be applied to resolve this issue
GWME-7.1.0-4 - Downtime scheduling patch
If you have scheduled any downtimes for Nagios Hosts/Services before the upgrade the following scripts need to be executed from the command line so that the Downtime Scheduling database is populated with data from the Nagios retention file.
'List Downtimes' gets populated with Downtimes applied before upgrade.
Recurring Downtimes require an additional step per GWMON-12710
The credentials used by the deployed GDMA agents needs to be added to the JBoss AS so that calls to the legacy REST API succeed. By default the server is configured to use gdma/gdma but it is recommended to change the password regularly.
The following steps on the GroundWork Monitor Server are necessary to add the credentials to the authentication store.
And change the value for the user gdma as following:
By default is gdma/gdma (gdma=8ae0d35b1f513c066178c3eaf805a0fa)
To change the gdma password a user has to create a MD5 Hex using the following command:
echo -n "USER:ApplicationRealm:PWD" |md5sum
Example user: gdma password:#changeME
echo -n "gdma:ApplicationRealm:#changeME" |md5sum would produce: 6f46676d7c793eaae2ed13f5bb676a46
In the application-users.properties the entry would look like this:
Here is another note, in case the USER or PWD part of the string to be hashed contains a '\' character. For example the customer might use the netbios naming convention 'domain\username' with a password like 'A\gjhjhg'. The '\' characters must be properly escaped before piping to md5sum. Use the string \u005c in every place that you have a '\'
To be precise, '\' -> '\u005c'
Example user: domain\username password:A\gjhjhg
echo -n "domain\u005cusername:ApplicationRealm:A\u005cgjhjhg" |md5sum would produce: 29aecce20dfaf39c0050696d5d9b9589
So the entry in application-users.properties the entry would look like this:
Save the file and from this point on the requests through the legacy REST API will succeed.
GroundWork offers pre-built VMware (VMDK) virtual appliance of GroundWork Monitor Enterprise running on Ubuntu Server 12.04 64-bit and CentOS 6.2 64-bit.
The appliances are delivered as ZIP files that need to be unpacked before they can be used in different VMware virtualization products including VMware Player, Workstation, Fusion ,and ESX server. The virtual machine package is useful for testing, development, training, and can be used in production in smaller environments. In distributed environments, virtualized GroundWork servers make excellent child servers. Starting with GroundWork Monitor 7.0.2 a Core license is included that allows to start monitoring right after installation.
|After unpacking the zip file the vmx files can be loaded directly with VMWare Player, Workstation and Fusion. If you plan to import the VMWare GroundWork appliance into ESXi the vmx and vmdk files need to be converted using VMware's Converter utility before loading into the ESXi instance. The conversion process is described in more detail in the Install instructions below.|
The following documents include more details on installation and configuration of the Virtual Appliances:
- Installing GroundWork Monitor 7.0.2 CentOS Virtual Appliance
- Installing GroundWork Monitor 7.0.2 Ubuntu Virtual Appliance