Deploying Parent Child Configurations

The capabilities for distributed monitoring in GroundWork Monitor have long been available with the implementation of “Child” GroundWork servers. This capability has been added to GroundWork 8, starting with version 8.1.0.

The child server is simply another GroundWork server that monitors a subset of the infrastructure. Child servers report the monitoring state and performance metrics to a central, or "Parent" GroundWork server.

  Child servers can be deployed for a number of reasons. The main uses of Child servers are:

  • Offloading the central server for scaling reasons
  • Performing monitoring in a segment of the network not directly reachable from the Parent server
  • Monitoring from an alternate network perspective (e.g., outside a firewall, across a WAN link, etc.)

In GroundWork Monitor 8.1.0 (or later version), an additional use case is enabled:

  • Locally independent monitoring management

Child servers can do all the same monitoring that regular, standalone GroundWork servers can do. Nagios, NeDi, Cloud Hub, etc. can all run on a Child server. That server can forward these results to a Parent. How exactly this is done depends on the type of monitoring the Child server is doing, and what kind of connection it uses. 

connectors and connections

Cloud Hub

The GroundWork Cloud Hub connectors connect to a monitored service, like AWS, a VMware ESX server or vSphere host, etc. They forward the metrics and status information to a GroundWork server over HTTPS. While normally these connectors simply report to the same server on which they run, they can report to alternate reachable servers. 

There is resilience (the connections retry on failure, and re-establish in a limited time window), however there is no robustness. Data not sent due to a down connection, is lost.

TCG

The connection between GroundWork servers and monitoring data sources such as Nagios is facilitated by a new component called TCG, or the Transit Connection Generator.

Deploying Child Server Option 1: Parent Managed Child

Use this option for deploying Nagios Child servers that are managed from the Parent, with Nagios Monitoring configurations pushed out to the Child, and connections defined and managed on the Parent. 

In this configuration, the Child server UI is still active but the Nagios monitoring configuration menu is disabled. Other features remain accessible to authenticated users.

Requirements and considerations
  • Servers: (required) 2 servers 
  • Port connectivity: (required) Bidirectional connectivity between Parent and Child over port 443 TCP.
  • DNS: (required) DNS names for Parent and Child that are resolvable for both.

    While you can have 2 server names assigned to a single server in GroundWork 8.1.0 (or later version), there is an important concept to keep in mind when using Parent-child configurations: Instance names. One name for the Parent (Parent Instance Name) and one name for the Child (Child Instance Name) has to be reachable from both the Child and the Parent.

    Since port 443 uses certificates using DNS names vs IP addresses, you should also ensure each Parent and Child can resolve the other servers DNS name used in the certificates. If you use private root certificates, both Parent and Child will need to have the certificates added to each other. If you are using publicly signed certificate authorities, this is not required, as the Certificate Authority certificates are already loaded. 

  • Certificates and server namesGroundWork supplies a self-signed certificate for every GroundWork Monitor server out of the box, but this can be replaced with a certificate you generate and maintain. Any GroundWork 8.1.0 (or later version) server can support up to two certificates on two names. See Adding Certificates to HTTPS and Generating Let's Encrypt SSL Certificates.

  • Name validationBy default, GroundWork assigns your server a DNS name at install time. This is the GW8_INSTANCE_NAME you will see in the gw8.env file in the gw8 directory. If you set this to blank (or localhost) and restart GroundWork, server name validation will be disabled and you can access the GroundWork user interface with any valid URL (even the IP address). 

    If you leave the GW8_INSTANCE_NAME set to the hostname in the gw8.env file, or change it using the change server name procedure (see Adding Certificates to HTTPS), then that is no longer the case, and the server name will be validated. Attempts to access the server on other names will fail with an HTTP 421 error code. 

  • Certificate validation - The self-signed cert GroundWork supplies will work for encryption, but clients (e.g., browsers) will complain that the signing authority is not valid, and ask for exceptions. To secure the interface and access it without requiring this exception, you can add a CA certificate to your GroundWork server. 

    There is an issue that sometimes complicates the Parent-child setup when adding a CA certificate, however. CA certificates require domain name validation in order to be issued. That’s typically done by manipulating public DNS records. This means that you can’t generally issue CA certificates to internal DNS names (e.g., gwos01.management.local). This might make it necessary to configure at least one GroundWork server (typically the Parent, which is accessed by more users) with both an external and internal DNS name. The external name gets the CA certificate, and the internal name uses a self-signed certificate. You don't actually have to expose the GroundWork server  with the external domain name to the internet, of course, though you will have to ensure it resolves via DNS. The Child (also a client) can access the Parent using the internal name, and the users use browsers to access it on the web UI with the external name, no exception needed. 

    For example, if the Parent server has the name gwos01.external.corp.net to most users, and gwos01.management.local on the management network, you should use the gwos01.management.local name as the PARENT_INSTANCE_NAME. The Child instance name in this case is gwos02.management.local

    Part of the installation procedure below is to set the PARENT_INSTANCE_NAME in the gw8.env file. If the name you set there is not the same as the GW8_INSTANCE_NAME, then this alternative name will also need to work to access the server. This is the purpose of the support for the second name (and optionally the second certificate) in GroundWork 8. You can change the DNS names of your GroundWork server by following the steps listed in Adding Certificates to HTTPS under Load certificates.

    certificates

We recommend performing these next steps in order to avoid creating "orphan" hosts and services in the inventory on the Parent. Deleting orphans requires removing the connectors and starting over.

Install Child

The installer supports adding the Child instance and Parent instance names at install time, or you can add them to a running server. If you are just installing using the installer, choose the role  Parent Managed Child and enter the Parent Instance Name and the Child Instance Name when prompted. 

To add these parameters to an existing server, follow these steps:

  1. Delete all non-default inventory from Configuration > Nagios Monitoring. Make sure to commit your changes. You should have nothing other than the default GroundWork Servers hostgroup with ping checks to the gw8_ containers present.  

    This step is essential, since you will be unable to control Nagios from the Child in the future. If you want to be able to do so, see Child Managed Child below.

  2. From a command line, in the gw8 directory, edit the gw8.env file.
  3. Add/edit the following lines with your Parent and Child instance names:

    PARENT_INSTANCE_NAME=(your parent instance name)
    CHILD_INSTANCE_NAME=(your child instance name)
    INSTALLATION_MODE=PARENT_MANAGED_CHILD
  4. Save the file.
  5. Restart GroundWork:

    docker-compose down
    CODE
    docker-compose up -d 
    CODE
    • At this point, the user interface on the Child will no longer show the menus for configuring Nagios monitoring. 

Install Parent

Similarly to the Child server, when installing a new server the installer will prompt you for the role. Choose Parent, and enter the Parent instance name. As the on-screen instructions say, a Parent server should not have a Child instance name, so leave it blank. 

Similarly to a Child server, if you wish to enable a running server to be a Parent, follow these steps:

  1. From a command line, in the gw8 directory, edit the gw8.env file.
  2. Add/edit the following lines with your Parent and Child instance names:

    PARENT_INSTANCE_NAME=(your parent instance name)
    CHILD_INSTANCE_NAME= (leave this blank)
    INSTALLATION_MODE=PARENT
  3. Save the file.
  4. Restart GroundWork:

    docker-compose down
    CODE
    docker-compose up -d 
    CODE

Add Credentialed Users

The TCG program which connects Parent and Child servers uses user credentials to authenticate connections, so you need to set up identical users on both the Parent and Child servers. The username and password you use does not matter, but make sure they are the same, and that you assign them the Admin role. Also, make sure you check the box for a “credentialed user” in the dialog. 

There can be only one such "Credentialed user" in any GroundWork server, and it must be a local (not an LDAP-controlled) user account. 

edit user

Add Hosts and Services

Add the hosts and services to be monitored to the Parent Nagios monitoring configuration. There's no specific instructions here on how to add monitored resources to the Nagios configuration. There are a lot of ways to do so, of course, including Auto-Discovery, NeDi Import, and even using the New Host Wizard. As soon as you have added the hosts and services you want to monitor from the Child to the Parent, however, we recommend placing them in a hostgroup named for the Child instance (CHILD_INSTANCE_NAME above). This will simplify the next step. 

Add a Child Group

Add Child group to Nagios monitoring configuration.

  1. To set up a Child group go to Configuration > Nagios Monitoring > Groups and create a New group named the same as the CHILD_INSTANCE_NAME above.
  2. Select the Group type to be Child Instance.
  3. Select Profile type to be Standalone or None.
    Standalone will create self-monitoring hosts with the prefix of the Child server short name, along with a hostgroup similarly named. None will not create these self-monitoring hosts. We recommend None. 
  4. Further down, fill in the Build folder field with the path /usr/local/nagios/etc/<group name> where group name is the name of the group.
  5. Fill in the Nagios etc folder field as /usr/local/nagios/etc.
  6. For the active and passive options, it makes sense to use Inheritance for all of these, so we recommend leaving the remaining settings at the defaults. 

    Users of prior versions of GroundWork will notice that this is completely different from the past modality. In GroundWork 8, the Nagios instances are completely independent, and it is not necessary to force passive host and service checks on the Parent to be active on the Child. This is because Nagios on the Parent is not used at all for Child checks. 

  7. Save the group.
  8. Then, on the left hand menu under the group name, select Nagios cgi. At the bottom of the screen click the Sync with Main, followed by Save and Next. After one Save and Next, you can move on. 
    • Do the same for Nagios cfg - Notification. No need to save more than the first page.
    • Do the same for Resource cfg. You don’t need to save this one, Sync with Main is enough. 
  9. Next, navigate to the group Hosts tab, and add hosts and services to monitor on the Child.
    You can add them here at any point in the future as well. If you created the recommended hostgroup named for the Child instance name, you can simply add that whole hostgroup to the group. 
  10. When you have the inventory of hosts that you want to monitor on the Child added to the Child group Hosts tab, go to Build instances. It's the last option under Groups. Check the box for your group, and click Build and Deploy
    You should see a message like this one:

    Files for the "childserver" build were generated in /usr/local/nagios/etc/childserver.
    Warning: HTTPS certificate on deployment target is invalid.
    Retrying deployment request with SSL verification disabled.
    Starting nagios: done.
    Monarch deployment successful, ("childserver")

    The warning happens when the certificate on the Child is self-signed and can't be validated against a CA. This is pretty common, so it's not an error, just a warning. 

Set Up Connection

Do not perform this step until you are sure you have successfully completed the sending of Nagios configuration data to the Child, above. 

  1. To add a connection to the Nagios Child server, access the Parent server and go to Configuration > Connectors menu. 

  2. Click the Add + button.


    connection setup
  3. Click the Nagios child server button.


  4. Fill in the form: 

    • Connector Name: Enter an arbitrary name for this connection, e.g., gwos02 child or similar. 
    • Child Host Address: Enter the Child instance name.
    • Log Level: (Optional) You can adjust the logging level. This is only really useful if you are having issues connecting to the Child servers, you can leave this at Error unless you are debugging. 
  5. If everything is correct, clicking Save will result in the status icon in the upper right turning green. Any error messages will show on the screen, and will give you an idea of what needs to change. At this point, you should see hostgroups, hosts and services start to show up in the Status dashboard on the Parent server. They will change state as they are checked on the Child. Future configuration of Nagios monitoring must be performed on the Parent, and the Build and Deploy step for the Child group is necessary to push changes out to any Child servers (Configuration > Nagios Monitoring > Groups)

    The Child host will have a connector named Local Nagios by default. This connector is not used in this configuration, and will be disabled. Don't be alarmed if you browse to the Connections page and see that it shows "unreachable" status. It's only in case you need to make the Child a standalone system again at some later point. 

More Options

Editing the connections for this connector on the Parent server is possible by navigating to Configuration > Connectors, and selecting the connector name from the list. You can then select the Child Connections tab, where you will see two connections, one for the Child Nagios to the Child server, and another for the Child Nagios to the Parent Server. These are automatically created, however you can change the settings as described in Optional settings for connections, below. 

Deploying Child Server Option 2: Child Managed Child

Use this option for deploying Nagios Child servers that are managed from the Child server user interface. Once set up, a Child Managed Child server will forward all hosts, services, hostgroups, and servicegroups that are deployed in Nagios to the Parent. The administration of this server can therefore be considered autonomous, and the only administrative synchronization required with the Parent server is the "Credentialed User" username and password. 

Requirements and considerations
  • (required) 2 servers
  • (required) DNS names for Parent and Child that are resolvable for both

    While you can have 2 server names assigned to a single server in GroundWork 8.1.0 (or a later version), there is an important concept to keep in mind when using Parent-child configurations: Instance names. One name for the Parent (Parent Instance Name) and one name for the Child (Child Instance Name) has to be reachable from both the Child and the Parent.

  • You can deploy more than one Child server that reports to a given Parent, and these Child servers can be of either the Parent Managed or Child Managed types. The adding of hosts and services is done on the Child in the case of Child Managed Child, and the Parent server will receive all of the hosts and services it monitors in addition to any local (or other Child) monitoring it is doing. This means there's no central control point, and hosts can add up fast, so you will want to be sure to have sufficient overhead, both in compute resources and licenses, to handle these hosts. This is especially true on the Parent server where the hosts will aggregate, or if the Parent is doing significant other processing such as BSM, SLA, and/or Elastic Stack monitoring. 

Install Child

The installer supports adding the Child instance and Parent instance names at install time, or you can add them to a running server. If you are just installing using the installer, choose the role Child Managed Child and enter the Parent Instance Name when prompted.

Do not enter a Child Instance Name. 

To add these parameters to an existing server, follow these steps:

  1. From a command line, in the gw8 directory, edit the gw8.env file.
  2. Add/edit the following lines with your Parent and Child instance names:

    PARENT_INSTANCE_NAME=(your parent instance name)
    CHILD_INSTANCE_NAME=(leave this blank)
    INSTALLATION_MODE=CHILD_MANAGED_CHILD
  3. Save the file.
  4. Restart GroundWork:

    docker-compose down
    CODE
    docker-compose up -d 
    CODE

Install Parent

Similarly to the Child server, when installing a new server the installer will prompt you for the role. Choose Parent, and then enter the Parent instance name. As the on-screen instructions say, a Parent server should not have a Child instance name, so leave it blank. 

Similarly to a Child server, if you wish to enable a running server to be a Parent, follow these steps:

  1. From a command line, in the gw8 directory, edit the gw8.env file.
  2. Add/edit the following lines with your Parent and Child instance names:

    PARENT_INSTANCE_NAME=(your parent instance name)
    CHILD_INSTANCE_NAME= (leave this blank)
    INSTALLATION_MODE=PARENT
  3. Save the file
  4. Restart GroundWork:

    docker-compose down
    CODE
    docker-compose up -d 
    CODE

Add Credentialed Users

The Transit Connection Generator (TCG) program which connects Parent and Child servers uses user credentials to authenticate connections, so you need to set up identical users on both the Parent and Child servers. The username and password you use does not matter, but make sure they are the same, and that you assign them the Admin role. Also, make sure you check the box for a “credentialed user” in the dialog. 

There can be only one such "Credentialed user" in any GroundWork Server, and it must be a local (not an LDAP-controlled) user account. 

edit user credential user

Set Up Connection

  1. To add a connection to the Parent server, access the Child server's Configuration > Connectors menu. 
  2. Click the Local Nagios link. 

    Local Nagios link
  3. Click the GroundWork Connections tab.

    GroundWork Connections
  4. Click the Connect to Parent button.

    Connect to Parent

  5. Fill in the form:

    • Connection NameEnter an arbitrary name for this connection, e.g., gwos02 Child or similar. 
    • Configure options as necessary: Defaults are usually best, but see below for details
  6. Optionally, click the add prefix link to bring up the prefix dialog. Adding a prefix is a good idea if you want to track which Child server is monitoring which host automatically via the hostname.

    • Whatever you type in the Connection prefix is prepended to the hostname on the Parent server. 

      Changing or adding the prefix after the hosts are already populated on the Parent server will result in the newly-renamed hosts being in a pending state briefly.

  7. If everything is correct, clicking Save will result in the status icon in the upper right staying green. Any error messages will show on the screen, and will give you an idea of what needs to change. At this point, you should see hostgroups, hosts and services start to show up in the Status dashboard on the Parent server. They will change state as they are checked on the Child. Future configuration of the Nagios monitoring for this Child must be done on the Child.

More Options

  • Active?This option is useful if you want to configure a connection but leave it inactive, for example if you are not ready to forward results to a Parent server yet, but want to be ready when the time comes. You can also temporarily halt the forwarding of results by deactivating a running connection. Note that it requires a Save to take effect. 

  • Merge Hosts: This option has the same effect as it does when using Cloud Hub, that is if there are existing hosts with the same name aside from letter case in the name at the other end of the connection, the services will be added to those hosts. Note that this just makes the matching ignore case; exact matches are always merged. 

  • OwnershipHosts are "owned" by applications in GroundWork, as part of unified monitoring. If you are connecting to a server where there are already hosts that have the same name as hosts you monitor here, those hosts may already be owned by a different application, such as Cloud Hub (application type VEMA). Services are always owned by the application that generated them, but hosts can change owners. Only an owner can delete a host. See Ownership Options.

    Host owners set the host status. If status from multiple sources conflict, the owner's state wins. Non-owners host status reporting messages appear appended to the status text in the Status Summary dashboard.


    more options

Related Resources