Overview

This section reviews how to add and configure the Cloud Hub connector Icinga 2. Each connector requires a unique set of parameters (e.g. server url, credentials). You will need your GroundWork server and virtual environment connection parameters handy.

Prerequisites

• Enable the API
  
  The Icinga 2 system you run needs to have the API feature enabled. By default, it is not in the current version of Icinga 2 (2.5.4). It is installed, however, and it is a relatively simple matter to set it up. Please see the relevant documentation at http://docs.icinga.org.
  1. Assuming you have Icinga 2 installed properly, and the API is not enabled, the commands will guide you through the basics:

     # icinga2 api setup
     # service icinga2 restart

  2. The data you will need to connect to the API will be in the file:

     /etc/icinga2/conf.d/api-users.conf

  3. It will look something like this:

     object ApiUser "root" {
       password = "3393c21c662f1b42"
       // client_cn = ""
       permissions = [ "*" ]

  4. This defines a user (root) and password for connecting to the API, and technically this is all you really need. You can test with a curl command, like this:

     # curl -k -s -u root:3393c21c662f1b42 'https://{icinga2 server name here}:5665/v1/status'

  5. That should return some XML to the command line with a lot of metrics embedded in it. Note, however, that the data is retrieved over HTTPS, so an SSL certificate has been generated.
  6. If you want to simply trust this certificate, you can choose to do so in the connector, If you wish to import the certificate and not simply blindly trust it (which is a good idea), you will need to do a few more steps.

• Copy and import the certificate
  1. On the Icinga 2 server, suitable responsive to a curl command with username and password over HTTPS as illustrated above, find the ca.crt file and securely copy it to the GroundWork server. It is located here by default on the Icinga 2 server:

     /etc/icinga2/pki/ca.crt

  2. On the GroundWork server, create a new, empty directory in a secure location on the disk, accessible to user nagios. For example, as root, type:

     # mkdir /usr/local/groundwork/config/cloudhub/icinga2/
     # chown nagios.nagios /usr/local/groundwork/config/cloudhub/icinga2/
     # cd /usr/local/groundwork/config/cloudhub/icinga2/

  3. Copy the ca.crt file to that directory, and change directory to that location. Then type issue the following commands as root:

     # source /usr/local/groundwork/scripts/setenv.sh
     # keytool -genkeypair -alias private -keyalg RSA -keysize 2048 -dname "CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown" -keypass {password one} -keystore icinga2-keystore.jks -storepass {password two}

  4. Replace the password strings in the above command with passwords you maintain for this. Make sure they are unique, and that you record them securely.

     # keytool -importcert -trustcacerts -noprompt -alias root -file ca.crt -keystore icinga2-keystore.jks -storepass {password two}

  5. Then test that the certificate is in place with:

     # keytool -list -keystore icinga2-keystore.jks -storepass {password two}

1.0 Adding a New Connection

The initial Cloud Hub screen is used to add, start, stop, modify, or delete available connectors. Follow the steps below to add a connection. You will need to create a new connection in this way for each region to be monitored.

1. Log in to GroundWork Monitor as an Administrator.
2. Select GroundWork Administration > GroundWork Cloud Hub.
3. Click +Add corresponding to the Icinga connector icon. 
   
   Figure: Adding a connection
   

2.0 Configuring the Connection

In the configuration page you will need to enter both the GroundWork server and remote server parameters.

The data the GroundWork server receives comes from the remote virtualization server. The GroundWork server is where Cloud Hub will store the connectors metrics. The information is pulled from the API on a periodic basis based on the check interval that is set.

2.1 GroundWork Server Parameters

1. Here we enter the GroundWork server parameters, each described in the table below.
   
   Figure: GroundWork server values
   
   
   Table: GroundWork server values

   GroundWork Server Version	The GroundWork server version number which is set to the latest release installed. Cloud Hub can be configured to talk to versions from GroundWork Monitor version 7.0.
   Display Name	This is the configuration’s name displayed in the list of Cloud Hub connectors on the Cloud Hub home page.
   GroundWork Server Name	The host name or IP address of the GroundWork server that will integrate the Cloud Hub messages. A port number should not be entered here. If Cloud Hub is running on the same server as the portal the name can be localhost, or as preferred the server name. Often the GroundWork server is the same server where Cloud Hub is running however, Cloud Hub can also run in a distributed environment on its own node in a GroundWork cluster.
   Is SSL enabled on GroundWork Server?	Check this box if the GroundWork server is provisioned with a secure HTTPS transport.
   GroundWork Web Services Username	This is the provisioned user name granted API access on the GroundWork server. This value defaults to RESTAPIACCESS, and can be located by opening a tab to the GroundWork Administration > GroundWork License page. The value is under Webservices API Account Info in the Access field. For all systems, make sure the Web Services Username and Password match with the entries in the ws_client.properties file.
   GroundWork Web Services Password	This is the corresponding API Token (password) for the given user name on the GroundWork server. This is obtained by opening a tab to the GroundWork Administration > GroundWork License page. The value is under Webservices API Account Info in the Token (encrypted) field. For all systems, make sure the Web Services Username and Password match with the entries in the ws_client.properties file.
   Merge hosts on GroundWork Server?	If checked, this option combines all metrics of same named hosts under one host. For example, if there is a Nagios configured host named demo1 and a Cloud Hub discovered host named demo1, the services for both configured and discovered hosts will be combined under the hostname demo1 (case-sensitive).

2.2 Remote Server Parameters

1. Here we enter the remote server parameters, each described in the table below.
   
   Figure: Remote server values
   
   
   Table: Icinga server values

   Icinga 2 Server	This is the URL for the Icinga 2 virtualization server (e.g., icinga2host.yourdomain.com).
   Icinga 2 API Port	This is the API port, 5665 is the default.
   Icinga 2 API Username and Password	This is your username for the API on the Icinga 2 server which is stored in this file /etc/icinga2/conf.d/api-users.conf.
   Icinga 2 API Username and Password	This is your password for the API on the Icinga 2 server which is stored in this file /etc/icinga2/conf.d/api-users.conf.
   Trust SSL Certificate on Icinga 2 Server?	Check this box if the Icinga 2 server is configured for secure HTTPS.
   Icinga 2 Server SSL CA Certificate	If SSL, this is the ca.crt location.
   Icinga 2 Server SSL CA Certificate Keystore	If SSL, this is the icinga2-keystore.jks location.
   Icinga 2 Server SSL CA Certificate Keystore Password	If SSL, this is the keystore password.
   Graph Icinga 2 Service Metrics?	Select to include Icinga2 service metrics.
   Sync Interval (in mins)	This is the polling interval for collecting monitoring data from the virtual instance and sending it to the GroundWork server. The value is in minutes.
   Connection Retries (-1 infinite)	This entry is the number of retries for the connection and sets a limit on how many attempts are made after a failure. If you set this to -1, the retrying goes on forever. The number set indicates how many connections are attempted before the connection is left inactive (until you restart it).

2. After the remote server parameters have been entered, click SAVE which saves and writes the entries to an XML file in the GroundWork server /usr/local/groundwork/conifg/cloudhub directory. The Cloud Hub connector is assigned an agent ID and that in turn becomes a record locator in Foundation when you begin monitoring.
3. Next, validate the configuration by selecting TEST CONNECTION which will check if the connection is accessible with the given credentials. A dialog will be displayed with either a success message or, if the server cannot be contacted, an error message will be displayed with information describing why the connection failed.
4. The metrics are set within Icinga 2 and not within the GroundWork Monitoring Cloud Hub interface. After the credentials have been validated, click HOME to return to the main Cloud Hub panel.
5. Click START for the specific connector to begin the discovery and data collection process.

   At anytime, if you decide you do not want to monitor a particular region, simply navigate back to this point (GroundWork Administration > GroundWork Cloud Hub) and select STOP for the corresponding connector, the connectors configuration will be maintained for a subsequent START. To stop and completely delete a connection see How to delete GroundWork Hub hosts.

3.0 Determining Metrics To Be Monitored

The metrics are set within Icinga 2 and not within the GroundWork Monitoring Cloud Hub interface.