GroundWork Monitor Enterprise 8.1.0

GroundWork Monitor Enterprise 8 utilizes Docker containers and a Continuous Integration/Continuous Deployment methodology. This means less waiting for feature development, security patches and bug fixes. You will get faster turnaround on bugs, feature enhancements, and security fixes, with little effort on your part to maintain your on-premises monitoring system. This document outlines the installation procedures for New, Update, Migrate installations and uninstalling GroundWork Monitor.

  • New Install is used for a fresh GroundWork Monitor installation. This install type will step you through an initial installation for GroundWork Monitor 8.1.0. The New Install uses the Install from Installer method which is an offline method, it does not require internet access other than for the initial download, and it uses a GroundWork Installer file to install. You will need to prepare your system, get the installer file, and run the installer. The installer will initially create a gw8 sub-directory of the directory where it runs, and will drop the configuration files into this subdirectory. The installation will take approximately 25 minutes to complete.
  • Update Install will update a previously installed version of GroundWork Monitor Enterprise 8. This install type steps through an update installation for GroundWork Monitor 8.1.0. The Update Install uses the Update from Installer method which is an offline method, it does not require internet access other than for the download, and it uses a GroundWork Installer file to install.
  • Migrate Install is considered a fresh GroundWork Monitor Enterprise installation plus a migration of your Monarch configuration from a previous version of GroundWork Monitor 7.x. This install type steps through the process for migrating Monarch to GroundWork Monitor 8. You will first need to refer to the New Install tab above to perform a new installation. After installation you can refer to the migration tasks on this page.
  • Uninstall is used to remove GroundWork Monitor Enterprise 8. This process completely removes GroundWork Monitor, removing volumes and containers and the Docker directory. It does not remove other Docker containers and volumes that may exist on the same host. 

Select the tab below for the installation type you wish to perform.

New Install

Fresh GroundWork Monitor Enterprise installation.

If your installation is an Update and not a New Install, please refer to Update Install.

  1. Read the Release Notes for GroundWork Monitor.
  2. Verify your system meets the System Requirements including a "/" partition of at least 200G which includes the /var/lib/docker directory.
  3. Gather the following information prior to running the installer, you will need to know:

    TimezoneThe timezone to be used for the crontab. It should be the timezone of those which have the most access to the system. This can be different from the server timezone, but ideally is not.
    GroundWork Monitor 8 web UI host nameThe fully qualified host name used to get to your GroundWork Monitor system UI. This is the name you will use to access the web interface as a user. We suggest you make it the FQDN, so that the certificates will validate correctly. 
    Type of installationThe type of installation to use for this GroundWork server. GroundWork Monitor can be installed as a standalone system (a single server in a single location) or installed to run Parent-child distributed monitoring implementing child GroundWork servers. The choices when running the Installer will be:
    • Standalone: GroundWork 8 server in a single location.
    • Parent: GroundWork 8 central server for GroundWork child servers. You will need the parent host name which needs to resolve to the parent server you are installing and be reachable by any associated child servers.
    • Parent Managed Child: GroundWork 8 child server managed from the GroundWork 8 parent. You will need the parent host name which must match the parent instance name on the parent server this child will connect and the child host name which must match the child's Monarch Group name, be reachable by the parent, and resolve to the server you are installing.
    • Child Managed Child: GroundWork 8 child server managed independently. You will need the parent host name which must match the parent instance name on the parent server the child will connect to.
    SubnetsA subnet to use for the Docker daemon and subnet for GroundWork Docker containers. The networking settings are designed to avoid conflicts in your networking setup. Make sure this subnet does not conflict with your own infrastructure. If you use the subnet anywhere internally, make sure that the subnet chosen by the installer does not conflict with your use of it elsewhere or you may not be able to use the system until you correct it. 
    LDAPYou will need to create a user for installation as well as running the application. We use gwos in our installation procedure below. If you use LDAP, an LDAP based user if fine, as long as it can be added to sudo and to docker group. For more information regarding LDAP in GroundWork Monitor, see LDAP Mapping and How to configure LDAP.
  4. Create a user to be used for the installation with the following commands:
    • Log in as root.
    • Add the gwos user, password:

      Create a user that will be used for installation as well as running the application. Any user name is fine, we use gwos as an example throughout this procedure, if you are not please adjust your commands.
      useradd gwos
      passwd gwos

      Exit as root.

    • Add the above user (e.g., gwos) user to sudo.
    • Login as root:

    • Add the following line, just below "root ALL=(ALL) ALL”:

      gwos ALL=(ALL) ALL

      Exit as root.

    • Login as gwos user:

      sudo yum update -y
  5. Install Docker CE and enable with systemd:

    This procedure is for Red Hat 7 or CentOS 7. If you are using Red Hat 8 or CentOS 8, please refer submit a ticket on GroundWork Support.

    You can refer to the Docker site for detailed installation instructions for most Linux variants, see

    • As gwos user, enter the following:

      sudo yum install -y yum-utils device-mapper-persistent-data lvm2
      sudo yum-config-manager --add-repo
      sudo yum install -y docker-ce docker-ce-cli
  6. Install Docker Compose:

    • As gwos user, enter the following:  

      sudo curl -L "$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
      sudo chmod +x /usr/local/bin/docker-compose
      sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
  7. Add gwos user to dockergroup:

    sudo usermod -a -G docker gwos
  8. Make sure you can access Docker with gwos by running the following commands:

  9. Configure Firewall settings before installation.

  10. Download and install GroundWork Monitor Enterprise 8.1.0.

    • Login as gwos user.

    • Change the directory to the root home directory:

    • Enter the following command to download the GroundWork Installer:


      Alternatively you can obtain the installer from the Downloads page and locate it to your server.

    • Check MD5 and compare with MD5 on the Downloads page:

    • Mark the file as executable:

      chmod +x
  11. Run the GroundWork Installer:

    Do not run the installer as the root.

    • As gwos user, enter the following:

    • As the install progresses, you will be asked about Timezone, web UI host name, installation type, and subnets which are all mentioned in step 3 above.

  12. After install completed, you can check container's status, or shutdown and start containers:

    • Check container's status:

      cd gw8
      docker-compose ps
    • Shutdown and start containers:

      docker-compose down
      docker-compose up -d
  13. Load certs, please refer to Adding certificates to HTTPS.
  14. When the Installation process completes, open a browser to the name of the host system to log in to GroundWork Monitor 8.1.0. The default Administrator login is admin/admin. Note it may take a few minutes for the availability calculations to complete and display, so you may see warnings about this on the relevant dashboards.
  15. A few post install recommended tasks and tips:
    • You'll need to put auto restart in-place in case of power outage. Add Restart script.
    • Also you'll need to your log settings, so the logs won't eat up your disk space. Adjust Log settings.
    • To access logs and navigate in Docker, see Docker commands.
    • To configure GroundWork Monitor users, see Users roles permissions
    • To customize the GroundWork menu options and access, see Menu Editor.

Update Install

This section steps through an update installation for GroundWork Monitor 8.1.0. The Update Install uses the Update from Installer method which is an offline method, it does not require internet access other than for the download, and it uses a GroundWork Installer file to install.


  1. First, verify your running GroundWork 8.0.0 or 8.0.1 system is up to date as described in System Requirements. It most likely is, but it's a good time to update and patch the OS. 
  2. Review the Release Notes for 8.1.0, which contain details of issues fixed, new features, and items of interest to those users who have customized or significantly enhanced a previous version of GroundWork Monitor. 
  3. You may need to obtain a new license for 8.1.0 from GroundWork Support. This version will not work with licenses that are specifically for 8.0.x (like the default 50-host core licenses issued with 8.0.x), and you don't want to go all the way through an upgrade just to wait for a license to be generated before you can use the system. Existing customers are welcome to equivalent 8.1.0 licenses at no extra cost, and many existing customers have been issued licenses that are for 8.x.x, so you may just want to check with support to be sure.
  4. Running the Installer will update an existing GroundWork Monitor installation without any changes to configuration or license.

    It is recommended you perform a backup before updating your installation. 

  5. Open a command line to the directory where you installed GroundWork Monitor 8. This is the directory above the gw8 directory. Check with an ls command to be sure. You should see the gw8 directory listed. 
  6. Next, go to the Downloads page, navigate to and select the Installer file for the new version and place it in this directory.
  7. Change the installer mode:

    chmod +x
  8. If you are running the optional NeDi netflow or nfpcapd containers, stop them manually: 

    docker ps |grep nfcapd
    docker ps |grep nfpcapd

    This will give you the container name as the last column in the output, for example: 

    e5a971431d05      groundworkdevelopment/nedi:8.0.1-GA     "nfpcapd -i eth0 -T …"   49 minutes ago      Up 49 minutes (health: healthy)      nfpcapd_capture  

    Usually, these are nfcapd_collector (for NetFlow) and nfpcapd_capture (for packet capture). For each of these containers, type: 

    docker stop <name>

    where <name> is the name of the container, e.g., nfcapd_collector.


After completing the Prepare steps above, you can proceed by running the installer:

  1. Run the installer: 

  2. The installer will function much as it does during a New Install, with the exception that it will not prompt for a host name or installation type. The installer will shut down GroundWork, extract all the new containers, update the system and restart it.
  3. If you want to run the optional NeDi netflow or nfpcapd containers again, start them with the following: 

    docker start nfcapd_collector
    docker start nfpcapd_capture

    or re-create them with this procedure NeDi Flowi NetFlow sFlow and packet capture.

  4. Log in as an administrative user and apply your new license to use 8.1.0.

Migrate Install

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

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. 

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. 

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)

    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
  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):

  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/ loadMonarchBackup $timestamp.tar.gz
  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 automatic in NoMa as well as Nagios. To disable notifications, for NoMa go to Configuration > Notifications and check each notification rule that is currently active (green checkmark) to be disabled (grey checkmark), and for Nagios go to Configuration > Nagios Monitoring > Control > Nagios main configuration > Notification and uncheck Enable notifications.


This uninstall process completely removes GroundWork Monitor 8, removing volumes and containers and the docker directory. It does not remove other docker containers and volumes that may exist on the same host. 

  1. Go to the Docker directory you created when you installed GroundWork Monitor 8.
  2. Go to the gw8 directory:

    cd gw8
  3. Shut down the existing containers:

    docker-compose down
  4. Remove GroundWork Monitor 8 volumes and containers:

    docker volume ls | grep "$(grep COMPOSE_PROJECT_NAME .env | sed -e 's/^[^=]*=//')_" | \
        awk '{print $2}' | xargs docker volume rm
    docker images -a | grep "groundworkdevelopment/" | \
        awk '{print $3}' | xargs docker rmi
  5. Remove the docker directory:

    cd ..
    rm -rf gw8

Related articles