Migrate Monarch to GroundWork 8

A Migrate Install is considered a fresh GroundWork Monitor 8 installation plus a migration of your Monarch configuration from a previous version of GroundWork Monitor 7.x. 

This page steps through the process for migrating Monarch to GroundWork Monitor 8. You will first need to refer to the New Install document to perform a new installation. After installation you can refer to the migration tasks on this page. 

Important Notes

  • Local Host and Custom Services: The migration to GroundWork Monitor 8 is not quite exact, since the way we do self-monitoring in GroundWork Monitor changes significantly. Therefore you can expect that the "localhost" host in GroundWork Monitor 7.x configurations will vanish in GroundWork Monitor 8 after migration. If you have any particular custom services assigned to localhost that you wish to preserve, we suggest you move them to another host first. 

  • Added Hosts: Also, you will see several added hosts in GroundWork Monitor 8 for the containers that run the system. Nagios™ ping checks of the containers will be automatically added after migration, and will show in the default Status Summary. These hosts and services are necessary, and any license will be increased to include them at no charge. They have names like "gw8-dockergw8_elasticsearch_1", and have several services from the Docker Cloud Hub connector as well. 

  • Notifications Known Issue: Monarch migration from GroundWork 7 to GroundWork 8 can require modification to some notification commands, if you decide to use Nagios for notifications. As of 8.2.0, we highly recommend you switch notifications to GroundWork Messenger, but if you need Nagios to still work for notifications for now, here's what you need to do:

    GroundWork 8 uses an updated /usr/bin/sendEmail which behaves slightly differently from previous versions, in that it requires a -t flag before the recipient address. This can cause the notification command to fail until the command definition is adjusted.

    If the migrated command is:

    /usr/bin/printf "%b" "some notification text in email body | /usr/bin/sendEmail -q -f $ADMINEMAIL$ -u "email subject" $CONTACTEMAIL$

    The -t flag needs to be added, like this:

    usr/bin/printf "%b" "some notification text in email body | /usr/bin/sendEmail -q -f $ADMINEMAIL$ -u "email subject" -t $CONTACTEMAIL$
    CODE
  • General Overview: Read the section below titled High Level Migration Plan: GroundWork Monitor 7.2.1 to GroundWork Monitor 8.x.

GroundWork Monitor 7.x

The following steps can be used to capture your existing GroundWork Monitor 7.x Nagios configuration database from your latest backup.

  1. Access the command line on your Groundwork 7.x server, for example via SSH. We assume you are using a user that is not root, but has sudo access. If you use root, then you can omit the sudo part. 

  2. Copy and paste the following command and run it:

    sudo tar -C /usr/local/groundwork/core/monarch/backup \
    -czf /tmp/$(ls /usr/local/groundwork/core/monarch/backup | tail -1).tar.gz \
    $(ls /usr/local/groundwork/core/monarch/backup | tail -1)
    CODE


    This will produce a file such as /tmp/2018-12-26_16-44-47.tar.gz. This is the backup to be transferred. Note the date portion of the filename as the timestamp for the next steps, e.g., "2018-12-26_16-44-47" in this example. 

GroundWork Monitor 8

  1. Transfer the backup you made above to the GroundWork 8 server. Place it in the gw8 directory. Use any secure method of transferring files you like, e.g., SCP. 

  2. From the command line on the GroundWork 8 server, change to the gw8 directory:

    cd gw8
    CODE

  3. Substitute the appropriate timestamp from your captured filename and set it as the timestamp variable. For example (you will need to use your own timestamp):

    timestamp=2018-12-26_16-44-47

  4. Copy and paste the following two commands to set the TAG variable and load the configuration:

    TAG=$(grep '^TAG=' .env | sed 's/^TAG=//')
docker run --rm \
    -v ${PWD}/$timestamp.tar.gz:/$timestamp.tar.gz \
    -v dockergw8_monarch-backup:/usr/local/groundwork/monarch/backup \
    --name gw8 groundworkdevelopment/gw8:${TAG} \
    /src/docker_cmd.sh loadMonarchBackup $timestamp.tar.gz
    CODE

  5. In GroundWork Monitor 8, go to Configuration > Nagios Monitoring > Control > Back up and restore and proceed to restore the GroundWork Monitor 7.x backup with the noted timestamp.

    You should disable notifications before committing the imported configuration. This will allow to identify any unforeseen problems without creating a notification storm. 


    Notifications are configured in GroundWork Messenger and optionally in Nagios as well. To disable notifications for GroundWork Messenger go to Configuration > Notifications > Configuration and check each notification rule that is currently active (green checkmark) to be disabled (grey checkmark). For Nagios go to Configuration > Nagios Monitoring > Control > Nagios main configuration > Notification and uncheck Enable notifications.

High Level Migration Plan: GroundWork Monitor 7.2.1 to GroundWork Monitor 8.x

This section is being provided as a general overview of the effort required to migrate from GroundWork Monitor 7 to GroundWork Monitor 8. Detailed migration plans can be developed by providing GroundWork Support with additional data, and we can help guide you through the details.

  1. Obtain a GroundWork Monitor 8 license. Existing customers are allowed to run GroundWork Monitor 7 and GroundWork Monitor 8 concurrently during a migration at no additional cost.
  2. Build a Linux server which meets at least the minimum requirements for GroundWork Monitor 8, and install GroundWork Monitor 8 on that system. Sizing is dependent on the role of the server (Parent or Child) and the size and rate of the dataset to be processed. Ensure all system requirements are met, including partitioning, and functional DNS and NTP. If a Standby Notification Server or Parent/Child server architecture is required, install the additional servers.
  3. Ensure firewall rules and VPN tunnels required for v7 system(s) are in place on the v8 system(s).
  4. Migrate configuration:
    1. Migrate the configuration database, any custom plugins, and any dashboards (NagVis and Grafana dashboards will need to be converted manually).
    2. Configure any GDMA agents to report to both systems concurrently, and if any active checks require adjustment (credentials or certificates on the clients or servers), make those adjustments as well.
    3. Migrate any Cacti checks to use the new TCG-SNMP connector.
    4. Migrate any other customizations made to GroundWork Monitor 7. Customizations may include custom database schema changes, modifications made for reporting purposes. Keep in mind that some customizations may not need to be carried over, and instead are replaced by more modern solutions (such as the APM connector).
    5. Migrate any notifications from NoMa to GroundWork Messenger. If only using Nagios notifications, you may still use only Nagios notifications, however you should consider migrating to GroundWork Messenger at this point. 
    6. Create new reports in GroundWork 8 if required. Data structure and reporting engines are new in GroundWork 8, so new reports may need to be created. 
  5. Start a defined period of monitoring from both GroundWork 7 and 8. Once the functionality of the GroundWork 8 system has been confirmed and the 7 installation is no longer needed, shut down the GroundWork 7 system, adjust any GDMA systems to send only to the new GroundWork 8 system, and archive any desired historical data from GroundWork 7 to long-term storage.
  6. Switch production reporting to the GroundWork 8 systems archive and reportdb databases (if required). 

Related Resources