Installing or Upgrading to GroundWork Monitor 7.1.0

h1. Installing GroundWork Monitor 7.1.0

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|7.1.0 Release Notes for EE]


{info}
Before starting the upgrade process make sure that your system is fully functional and that you went through the Upgrade preparation Checklist.
{info}

{toc}

{note:title=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|Technical Bulletins for 7.0.2] page of the [GroundWork Knowledge Base|https://kb.groundworkopensource.com/].
{note}

{contentbylabel:labels=tb 7-1-0|showLabels=false|showSpace=false|operator=AND|sort=title}

h2. Upgrade preparation Checklist

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.


h3. Backup

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

h3. Check list

# 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.

h3. Permission & Ownership check

From the command line run the following steps:

{noformat}
cd /usr/local/groundwork
find . -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"
{noformat}

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

h3. Duplicate Host entries

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 7.0.2.2|GWME-7.1.0-1 - Removing duplicate host entries in gwcollagedb database prior to upgrade from 7.0.2.2]



h3. JBoss portal memberships

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. 

h3. Installations with GDMA reporting to GroundWork Server

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.  

h3. Cloud Hub Connectors on GWME 7.0.2 SP02

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. 

h3. LDAP configured systems with non default portal root user

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:

{code}
source /usr/local/groundwork/scripts/setenv.sh
psql \-d jboss-idm
{code}

Change the password to any value (example below: pwdportal) for the root portal user (example below: root)
{code}
jboss-idm=# update jbid_io_creden set text = md5('pwdportal') where identity_object_id = (select identity_object_id from jbid_io u, jbid_io_creden c where u.id = c.identity_object_id and name = 'root');
{code}

When prompted by the installer provide the credentials set in the above command:

{code}
\---------------------------------------------------------------------------\-
GroundWork Portal Credentials

Please provide the login name and password for the GroundWork Portal root user.

Login [svc_gwroot|svc_gwroot]: svc_gwroot

Password :
Retype password :

{code}

h2. Prerequisites

h3. System Requirements

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
* {color:#000000}200 GB disk for system{color}
* 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.

{note:title=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.
{note}

h3. Platform Requirements

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.

{note:title=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.
{note}

h3. System Configurations and Operating System Settings

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.
{code:title=/etc/selinux/config}
SELINUX=disabled
{code}
Disable it immediately, prior to running the GroundWork binary installer:
{code}
setenforce 0
{code}
{note:title=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.
{note}

h3. Java Compatibility

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:
{noformat}
rpm -qa | grep -i java
rpm -qa | grep -i jdk
{noformat}

Remove the RPMs using:
{noformat}
rpm -e <name of RPM package>
{noformat}

Examples of conflicting Java packages include:
{noformat}
java-1.4.2-gcj-compat-1.4.2.0-27jpp
gcc-java-3.4.6-3
{noformat}

h3. Externally Defined User Nagios

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}}.

h3. PostgreSQL Database Location

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

h3. Distributed Database Installation Overview

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.

h2. Remote Database Install

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.

{tip:title=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:
{noformat}
# service groundwork status
postgresql already running
{noformat}
while on the GroundWork Monitor server, you will see the rest of the monitoring components:
{noformat}
# service groundwork status
noma is already running
Checking for GroundWork Services:
GroundWork Services: [ running ]
syslog-ng already running
ntop is already running
snmptrapd already running
snmptt already running
nagios is already running
apache already running
{noformat}
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.
{tip}

{warning:title=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.
{warning}

h3. Installing A Remote Database

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:
{noformat}
# ping mygwservername | head -1
PING mygwservername.localdomain.mycompany.com (192.168.115.52) 56(84) bytes of data.
# ping anotherserver | head -1
PING anotherserver (192.168.115.60) 56(84) bytes of data.
{noformat}
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:
{noformat}
chmod +x groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run
{noformat}
# 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.
{noformat}
# ./groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run
{noformat}
# 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.
{noformat}
----------------------------------------------------------------------------
Welcome to the GroundWork Monitor Enterprise Setup Wizard.

----------------------------------------------------------------------------
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] :y

GroundWork Monitoring Server [Y/n] :n

Is the selection above correct? [Y/n]: y
{noformat}
# 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.
{noformat}
----------------------------------------------------------------------------
Database Server Parameters

Please enter the IP address or hostname of the database server as visible by the
GroundWork Monitor server.

Note:
For remote database installs, the IP/Hostname must be a name or an address other
than localhost.

IP / Hostname []: 192.168.0.68

----------------------------------------------------------------------------
Database Server External connection permissions

Please enter the IP address or hostname of the GroundWork Monitor server

IP / Hostname []: 192.168.0.23
{noformat}
# Specify the power-user password for the PostgreSQL database. *Remember what you type here, as this password will be needed for future database maintenance*.
{noformat}
----------------------------------------------------------------------------
Please enter your database 'postgres' user password.

PostgreSQL postgres user password :
Re-enter password :
{noformat}
# 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.
{tip:title=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.
{tip}

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.

h2. Fresh Installation

{note:title=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.
{note}

h3. Disk Layout

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:
{noformat}
drwxr-xr-x 2 root root 4096 Feb 8 00:35 /tmp/local/groundwork
lrwxrwxrwx 1 root root 21 Feb 7 23:34 /usr/local/groundwork -> /tmp/local/groundwork
{noformat}
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:
{noformat}
drwxr-xr-x 2 root root 4096 Feb 5 19:45 /usr/local/groundwork
{noformat}
As before, the installer will adjust the ownership of the root of the mounted partition as needed during the installation process.

h3. Software Preparation

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:
{noformat}
chmod +x groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run
{noformat}

h3. Installation Methods

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.

h4. GUI Install

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:
{noformat}
./groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run
{noformat}

h4. Text Based Install

From a command shell, execute the binary with the text-mode installation selected:
{noformat}
./groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run --mode text
{noformat}

h4. Unattended Install

From a command shell, execute the binary with the unattended-mode installation selected:
{noformat}
./groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run --mode unattended
{noformat}

This will perform an unattended installation that will not prompt the user for any information.

{note:title=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.
{note}

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:
{noformat}
./groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run --mode unattended --optionfile gwinstall.ini
{noformat}
where the {{gwinstall.ini}} file contains:
{noformat}
postgresql_password=your_passwd
{noformat}

h4. Remote Install

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:
{noformat}
ssh -XC -l root target-machine ./groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run
{noformat}

h4. Install Questions

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:
{noformat}
----------------------------------------------------------------------------
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]:
{noformat}
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|GroundWork Archive Server] page. (That page is currently undergoing revision, and will be available shortly.)
{noformat}
----------------------------------------------------------------------------
Log Archiving



Do you wish to have the installer enable a standard configuration of the
log-archive capability? [Y/n]:
{noformat}
* End-stage activity:
{noformat}
----------------------------------------------------------------------------
Setup has finished installing GroundWork Monitoring Server component on your
computer.

Starting servers ...
/
{noformat}
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.

h3. Post-Install Configuration
{tip:title=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:
{noformat}
service groundwork status
service groundwork start
service groundwork stop
{noformat}
This script can also be used to stop, start, or restart individual services. For example:
{noformat}
service groundwork restart nagios
{noformat}
(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.)
{tip}

{anchor:default_login_information}

h4. Default Login Information

There are 4 user-interface users defined in GroundWork by default:
* root (password: root)
* admin (password: admin)
* operator (password: operator)
* user (password: user)

{warning:title=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|DOC70: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.
{warning}

{note:title=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)|#upgradepw].{note}

There is also a user account defined for use with various web-services calls:
* wsuser

{note:title=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.
{note}

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.
* gdma

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.

h4. License Required for Login

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|How-to Determine and adjust your device count]\\

h4. Optionally Disabling ntop

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:
{noformat}
service groundwork stop ntop
{noformat}
and then renaming the control script:
{noformat}
cd /usr/local/groundwork/common/scripts
mv ctl-nms-ntop.sh ctl-nms-ntop.sh.disabled
{noformat}

{note:title=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.
{note}

h2. Upgrade to 7.1.0 from a Previous Version


h3. Supported Upgrade Paths

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.
{note:title=Special Considerations}
* Because GWMEE 7.1.0 is only supported on 64-bit platforms, upgrades from 32-bit installs will require use of a different machine for the new release.
* Migration to a different machine may be required even on a 64-bit platform, if your current operating system version is no longer supported by GroundWork Monitor. See the Platform Requirements section earlier in this document.
* If you migrate to a different machine, you might wish to decide beforehand what the disk layout on the new machine will be, as described under *Disk Layout* in the *Fresh Installation* section above.

|| 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 | # migrate to 64-bit of the same release, on a separate machine
#* see [6.1 Release and Install Notes|https://kb.groundworkopensource.com/download/attachments/1475960/6.1_EE_release_notes.pdf]
#* see [6.1.1 Release and Install Notes|https://kb.groundworkopensource.com/download/attachments/950646/6.1.1_EE_release_notes.pdf]
#* see [6.2 Release and Install Notes|FILES:6.2 EE Release Notes]
#* see [6.3 Release and Install Notes|FILES:6.3 README and Release Notes for GWMEE]
# pause to verify that monitoring is fully operational as on the old machine
# upgrade to 64-bit GWMEE 6.5 (see [6.5 Release Notes for EE]; [6.5 Install Notes|Installing or Upgrading to GroundWork Monitor 6.5])
# pause to verify that monitoring is fully operational
# if you originally had the NMS version of Cacti installed, see special instructions provided by GroundWork Support for database schema adjustments
# if you originally had the NMS version of Cacti installed, see the special note below on handling the database credentials
# if you originally had the NMS version of NeDi installed, see the special note below on handling the database credentials
# clean up the databases, per instructions below
# upgrade to 64-bit GWMEE 7.1.0 (will involve migrating databases to PostgreSQL) |
| 6.1, 6.1.1, 6.2, 6.3,6.4 | 64-bit | # upgrade to 64-bit GWMEE 6.5 (see [6.5 Release Notes for EE]; [6.5 Install Notes|Installing or Upgrading to GroundWork Monitor 6.5])
# pause to verify that monitoring is fully operational
# if you originally had the NMS version of Cacti installed, see special instructions provided by GroundWork Support for database schema adjustments
# if you originally had the NMS version of Cacti installed, see the special note below on handling the database credentials
# if you originally had the NMS version of NeDi installed, see the special note below on handling the database credentials
# clean up the databases, per instructions below
# upgrade to 64-bit GWMEE 7.1.0 (will involve migrating databases to PostgreSQL) |
| 6.3, 6.4 or 6.5 | 32-bit | # migrate to 64-bit of the same release, on a separate machine
#* see [6.4 Release Notes for EE]; [6.4 Install Notes|Installing or Upgrading to GroundWork Monitor 6.4]
#* see [6.5 Release Notes for EE]; [6.5 Install Notes|Installing or Upgrading to GroundWork Monitor 6.5]
# pause to verify that monitoring is fully operational as on the old machine
# clean up the databases, per instructions below
# upgrade to 64-bit GWMEE 7.1.0 (will involve migrating databases to PostgreSQL) |
| 6.4 or 6.5 | 64-bit | # clean up the databases, per instructions below
# upgrade to 64-bit GWMEE 7.1.0 (will involve migrating databases to PostgreSQL) |
| 6.6, 6.6.1, 6.7.0, 7.0.0 or 7.0.1 | 64-bit | # If the 6.6.1 installation had been previously, upgraded from a MySQL version of GroundWork (6.2, 6.3, 6.4, or 6.5), then the {{/usr/local/groundwork/PostgreSQL-Info.txt}} file must be deleted prior to upgrading to 7.1.0. Failure to delete this file prior to running the installer will result in a non-functional installation that will require restoration to the back-up of GroundWork 6.6.1. So execute this command, to be safe in any case:
{noformat}
rm -f /usr/local/groundwork/PostgreSQL-Info.txt
{noformat}
# upgrade to 64-bit GWMEE 7.1.0 |
{note:title=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.
{note}
{note:title=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.
{note}

h3. Upgrade Options

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.

h3. PostgreSQL-to-PostgreSQL Release Upgrade Procedure

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.
{note:title=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.{note}
The high-level upgrade steps for this transition are:

# *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.

h4. Upgrade a Remote PostgreSQL Database

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|DOCDEV:How to perform a full system backup].
# Make backup utility executable:
{noformat}
chmod +x gw-backup-br339-linux-64
{noformat}
# 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:
{noformat}
./gw-backup-br339-linux-64 --action backupdb --password xxxxx
{noformat}
That command will deposit the resulting tarball in the {{/tmp}} directory, in a timestamped file such as the following:
{noformat}
/tmp/gw-backup-20140521155425.tar.gz
{noformat}
# 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:
{noformat}
chmod +x groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run
{noformat}
\\
# Back on the GroundWork Monitor server, stop the software for the duration of this part of the upgrade:
{noformat}
service groundwork stop
{noformat}
\\
# Run the installer on the Remote PostgreSQL database machine, and answer the prompts in the obvious ways.
{noformat}
./groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run --mode text
{noformat}
\\
# 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.

h4. Upgrade of GWMEE Components in PostgreSQL-to-PostgreSQL Upgrade

Once you have a pre-upgrade backup, and (if necessary) the Remote PostgreSQL database upgraded, the remaining upgrade steps are as follows:

{note}

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


{note}
# 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:
{noformat}
chmod +x groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run
{noformat}
\\
# 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.
{noformat}
./groundworkenterprise-7.1.0-br389-gw2833-linux-64-installer.run --mode text
{noformat}
\\
# The installer detects an upgrade. Choose yes to continue.
{noformat}
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
{noformat}
\\
# 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.
{warning}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.{warning}
{warning}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;*{}}}{warning}
{noformat}
GroundWork Portal Credentials

Please provide the login name and password for the GroundWork Portal root user.

Login []:
{noformat}
# 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:
{noformat}
Warning: During the upgrade procedure, the following files were detected to have
modifications. They were backed up to this directory,
/usr/local/groundwork/backup-2013-11-19. 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 :
{noformat}
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.

{info:title=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.{info}

h4. Final Steps in PostgreSQL-to-PostgreSQL Upgrade

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.
{noformat}
service groundwork restart
{noformat}
\\
* Download and run the {{upgrade_gwcollage_plugin_tables.pl}} script provided in [TB 7.0.1-1|7.0.1 Plugin Tables May Need Repair After Migration from MySQL to PostgreSQL]. 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.

h3. Post Upgrade Tasks

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.

h4. Verify Schema Version

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 7.0.2.2|GWME-7.1.0-1 - Removing duplicate host entries in gwcollagedb database prior to upgrade from 7.0.2.2] covers that cleanup but to be sure run the following command:
{noformat:title=run as nagios}
/usr/local/groundwork/postgresql/bin/psql -U collage -c "select value from schemainfo where name = 'CurrentSchemaVersion';" gwcollagedb
{noformat}
* 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:
{noformat}
/usr/local/groundwork/postgresql/bin/psql -U postgres -d gwcollagedb -f /usr/local/groundwork/core/migration/postgresql/pg_migrate_gwcollagedb.sql
{noformat}
* If you see an number older than "7.0.2" please [open a support ticket|https://cases.groundworkopensource.com/secure/CreateIssue!default.jspa] to get help in doing the database cleanup.

h4. Cloud Hub

* 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:
\\
\\ !GWME-710-LicensePageSmall.png|border=1!

{anchor:upgradepw}

h4. LDAP (Microsoft Active Directory (AD) Server or openLDAP)

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:

File: /usr/local/groundwork/config/josso-gateway-ldap-stores.xml

Property: securityCredential

The encrypted password can be obtained by running the following command from the command line providing the un-encrypted password as argument:

{code} /usr/local/groundwork/java/bin/java -cp /usr/local/groundwork/jpp/modules/org/jasypt/main/jasypt-1.9.2.jar:/usr/local/groundwork/jpp/modules/org/apache/commons/codec/main/commons-codec-1.4-redhat-2.jar:/usr/local/groundwork/jpp/modules/com/groundwork/collage/main/collage-api-7.1.0.jar:/usr/local/groundwork/josso-1.8.4/lib/commons-logging-1.1.1.jar:/usr/local/groundwork/jpp/modules/org/apache/commons/configuration/main/commons-configuration-1.6-redhat-2.jar:/usr/local/groundwork/jpp/modules/org/apache/commons/lang/main/commons-lang-2.6-redhat-2.jar:/usr/local/groundwork/jpp/modules/org/apache/commons/collections/main/commons-collections-3.2.1-redhat-2.jar:/usr/local/groundwork/jpp/modules/org/apache/commons/lang3/main/commons-lang3-3.2.jar:/usr/local/groundwork/jpp/modules/com/chrylis/base58-codec/main/base58-codec-1.2.0.jar org.groundwork.foundation.ws.impl.JasyptUtils --encrypt PASSWORD{code}

h4. Systems with root user changed

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.
super.user=PORTAL-USER_NAME

After updating the gatein.properties the following needs to be executed{code}service groundwork stop gwservices
source /usr/local/groundwork/scripts/setenv.sh
java -cp /usr/local/groundwork/jpp/modules/com/groundwork/security/main/groundwork-jboss-security-7.1.0.jar com.groundwork.core.security.GateinConfigurationUtils [-superuser PORTAL-USER_NAME]
service groundwork start gwservices
{code}

h4. Replace "foundation-webapp.war" to resolve token management issues

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|GWME-7.1.0-3 - Token management]


h4. Replace "nms-rstools.war" and associated yii directory and files

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|GWME-7.1.0-4 - Downtime scheduling patch]

h4. Nagios Downtimes scheduled before upgrade (GWME 7.0.2 SP02 systems only)

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.

{code:title=run as nagios}
/usr/local/groundwork/foundation/container/rstools/php/bsmCheck/protected/yiic migrate mark 151111_111101 --interactive=0
/usr/local/groundwork/foundation/container/rstools/php/bsmCheck/protected/yiic migrate up 1 --interactive=0
/usr/local/groundwork/foundation/container/rstools/php/bsmCheck/protected/yiic migrate mark 151216_114455 --interactive=0
{code}

'List Downtimes' gets populated with Downtimes applied before upgrade.

Recurring Downtimes require an additional step per GWMON-12710

{code:title=run as nagios}
cp "/usr/local/groundwork/backup-$(date -I)/nagios/var/downtime_schedule.cfg" \
/usr/local/groundwork/nagios/var/downtime_schedule.cfg
/usr/local/groundwork/foundation/container/rstools/php/bsmCheck/protected/yiic migrate mark 000000_000000 --interactive=0
/usr/local/groundwork/foundation/container/rstools/php/bsmCheck/protected/yiic migrate up 1 --interactive=0
/usr/local/groundwork/foundation/container/rstools/php/bsmCheck/protected/yiic migrate mark 151216_114455 --interactive=0
{code}

h4. GDMA agents reporting to the GroundWork server

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.
Edit: /usr/local/groundwork/jpp/standalone/configuration/application-users.properties

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:
gdma=6f46676d7c793eaae2ed13f5bb676a46

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:
domain\username=29aecce20dfaf39c0050696d5d9b9589

Save the file and from this point on the requests through the legacy REST API will succeed.


h1. GroundWork Monitor Enterprise Virtual Appliances for VMWare


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.
{info}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.{info}

The following documents include more details on installation and configuration of the Virtual Appliances:

Installation instructions:

* [SUPPORT:Installing GroundWork Monitor 7.0.2 CentOS Virtual Appliance]
* [SUPPORT:Installing GroundWork Monitor 7.0.2 Ubuntu Virtual Appliance]

Configuration instructions:

* [SUPPORT:Configuring GWME 7.0.2 Virtual Appliance for VMWare Fusion or Workstation]