Dashboard Gateway

Enable metrics for a single instance

1. Edit your HAProxy Enterprise configuration file to add a stats socket directive in the global section. This enables the HAProxy Runtime API used to fetch metrics. The IP address is 127.0.0.1 and the port is 9024. You must set the level to admin so that the Dashboard Gateway can manage the HAProxy Enterprise instance, as follows:

   global
       stats socket ipv4@127.0.0.1:9024 level admin

2. Restart HAProxy:

   $ sudo systemctl restart hapee-1.8-lb

3. Install the dashboard-gateway package with apt or yum, depending on your operating system:

   $ sudo apt install hapee-1.8r2-lb-dashboard-gateway

   Attention!

   Currently, there is a bug in the Dashboard Gateway service. The file /lib/systemd/system/hapee-1.8-lb-dashboard-gateway.service has an ExecStart set to /opt/hapee-1.8/dashboard/dashboard-gateway/haproxy-dashboard-gateway, but it should be /opt/hapee-1.8/dashboard/dashboard-gateway/hapee-dashboard-gateway. Update this after installing.

4. Copy the config.json.example configuration file and rename it config.json. See Configure the Dashboard Gateway for more details.

   $ cd /opt/hapee-1.8/dashboard/dashboard-gateway/conf
   $ sudo cp config.json.example config.json

   By default, this file contains the following:

   {
     "isLogging": true,
     "logFile": "access.log",
     "defaultHandler": "socket",
     "defaultHostSSL": false,
     "nodes": [
     {
       "host": "127.0.0.1",
       "port": "9024"
     }
     ]
   }

5. Start the Dashboard Gateway:

   $ sudo systemctl enable hapee-1.8-lb-dashboard-gateway
   $ sudo systemctl start hapee-1.8-lb-dashboard-gateway

6. Open the Real-time Dashboard in your browser and click the button to display the Settings window.

7. Set Data Source to Real-time Dashboard Gateway.

8. Set Data Source Mode to Single Node.

9. Set Real-time Dashboard Gateway URL to the URL where the Dashboard Gateway is running. The port defaults to 9020. If you have configured it to use HTTPS, click the padlock icon to make it green, and close the window.

10. Change the URL in the header bar to the address of your HAProxy Enterprise instance's socket. The port defaults to 9024, so you do not need to set it here.

11. Click the button to complete setup.

Enable metrics for multiple instances

Optionally, you can connect to data feeds from multiple HAProxy Enterprise instances running on different servers:

1. On each HAProxy Enterprise server, edit the HAProxy Enterprise configuration file to add a stats socket directive in the global section.

2. Give an IP address that the server running Dashboard Gateway can reach, or an asterisk (*) to listen on all IP addresses:

   global
       stats socket ipv4@*:9024 level admin

3. Restart HAProxy:

   $ sudo systemctl restart hapee-1.8-lb

4. Choose one server to be the "aggregation primary" instance. On that server, install the dashboard-gateway package using apt or yum depending on your operating system:

   $ sudo apt install hapee-1.8r2-lb-dashboard-gateway

5. Make a copy of the config.json.example configuration file and rename it config.json.

   $ cd /opt/hapee-1.8/dashboard/dashboard-gateway/conf
   $ sudo cp config.json.example config.json

6. Update the file config.json so that its nodes section lists each HAProxy Enterprise instance's IP address and port. See Configure the Dashboard Gateway for more details.

   {
      "isLogging": true,
      "logFile": "access.log",
      "defaultHandler": "socket",
      "defaultHostSSL": false,
      "nodes": [
         {
            "host": "127.0.0.1",
            "port": 9024
         },
         {
            "host": "192.168.50.26",
            "port": 9024
         }
      ]
   }

7. Start or restart the Dashboard Gateway:

   $ sudo systemctl enable hapee-1.8-lb-dashboard-gateway
   $ sudo systemctl start hapee-1.8-lb-dashboard-gateway

8. Open the Real-time Dashboard in your browser and click the button to display the Settings window.

9. Set Data Source to Real-time Dashboard Gateway.

10. Set Data Source Mode to Cluster Aggregation.

11. Set Real-time Dashboard Gateway URL to the URL where the Dashboard Gateway is running. If you have configured it to use HTTPS, click the padlock icon to make it green. Then, close the window.

12. Click the button to display the Cluster Setup window. Check that all nodes are listed. Then, click to complete setup.

Enable metrics for multiple processes

1. Edit the HAProxy Enterprise configuration file to start multiple processes using the nbproc directive in the global section. Set the value to the number of processes to create, as in the following example:

   global
       nbproc 2

2. In the global section for each process, add a stats socket line to indicate which process to bind to which socket, using the process argument:

   global
     stats socket ipv4@127.0.0.1:9024 level admin process 1
     stats socket ipv4@127.0.0.1:9124 level admin process 2

3. Add a bind-process directive to one or several frontend or listen sections to associate them with a specific process. For example:

   frontend website
       bind :80
       bind-process 1
       default_backend webservers
   
   frontend api
       bind 8080
       bind-process 2
       default_backend apiservers

4. Install the dashboard-gateway package:

   $ sudo apt install hapee-1.8r2-lb-dashboard-gateway

5. Copy of the config.json.example configuration file and rename it config.json.

   $ cd /opt/hapee-1.8/dashboard/dashboard-gateway/conf
   $ sudo cp config.json.example config.json

6. Update the file config.json so that its nodes section lists each HAProxy Enterprise instance's IP address and port. See Configure the Dashboard Gateway for more details.

   {
      "isLogging": true,
      "logFile": "access.log",
      "defaultHandler": "socket",
      "defaultHostSSL": false,
      "nodes": [
         {
            "host": "127.0.0.1",
            "port": 9024
         },
         {
            "host": "127.0.0.1",
            "port": 9124
         }
      ]
   }

7. Start the Dashboard Gateway:

   $ sudo systemctl enable hapee-1.8-lb-dashboard-gateway
   $ sudo systemctl start hapee-1.8-lb-dashboard-gateway

8. Open the Real-time Dashboard in your browser and click the button to display the Settings window.

9. Set Data Source to Real-time Dashboard Gateway.

10. Set Data Source Mode to Cluster Aggregation.

11. Set Real-time Dashboard Gateway URL to the URL where the Dashboard Gateway is running. If you have configured it to use HTTPS, click the padlock icon to make it green. Then, close the window.

12. Click the button to display the Cluster Setup window. Check that all nodes are listed. Then, click to complete setup.

Configure the Dashboard Gateway

You can enable various settings for the Dashboard Gateway in the configuration file /opt/hapee-1.8/dashboard/dashboard-gateway/conf/config.json. Make sure you restart the Dashboard Gateway service after making any change to this file. This section describes the available options.

Here is an example configuration:

{
   "apiRoot": "/",
   "authChallenge": false,
   "authRealm": "HAProxy Enterprise Real-time Dashboard Gateway",
   "defaultHandler": "socket",
   "defaultHost": "127.0.0.1",
   "defaultHostPort": 9024,
   "defaultHostSSL": false,
   "defaultModulePassword": "test",
   "defaultModuleUser": "dashboard",
   "disableHttp": false,
   "disableHttps": true,
   "httpsCertFile": "cert.pem",
   "httpsKeyFile": "key.pem",
   "httpPort": 9020,
   "httpsPort": 9021,
   "isLogging": true,
   "logFile": "access.log",
   "tlsPassphrase": "mypassphrase",
   "skipBasicAuth": false,
   "nodes": [
      {
         "host": "127.0.0.1",
         "port": 9024,
         "handler": "socket",
         "ssl": false,
         "user": "dashboard",
         "password": "test"
      }
   ]
}

The following table describes these options:

The nodes collection has the following options:

Enable HTTP Basic authentication

When you enable HTTP Basic authentication in the file config.json and set authChallenge to true, you restrict the Dashboard Gateway API to certain users. You can set one or more usernames and passwords.

1. The configuration file /opt/hapee-1.8/dashboard/dashboard-gateway/conf/htpasswd.json has the following format:

   {
      "username_1": {
         "password": "sha256_password_hash",
         "accessAll": "true"
      },
      "username_2": {
         // . . .
      },
      // . . .
   }

   For example, the default configuration is shown:

   {
      "dashboard": {
         "password": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
         "accessAll": true
      }
   }

   This adds the username dashboard with a password of test.

2. Edit the file to change the existing username and password. Use the following command to create the encrypted password:

   $ echo -n "YOUR_PASSWORD" | sha256sum

3. Open the Real-time Dashboard in your browser and click the button to display the Settings window. Set the Username and Password values to match those you just configured.

Enable HTTPS between the aggregation primary and child nodes

The aggregation primary node fetches metrics from multiple HAProxy Enterprise instances. In order to encrypt this communication, you must enable HTTPS.

1. Obtain a valid TLS certificate for each HAProxy Enterprise child node.

2. Make sure that the certificate is in PEM format. Then, combine the private key and the public certificate into a single PEM file. Copy it to the node under the path /etc/hapee-1.8/certs.

3. Edit the node's HAProxy Enterprise configuration file. In the global section, add an ssl and crt parameter to the stats socket directive. Also, change its port to 9025:

   global
       stats socket ipv4@*:9025 level admin ssl crt /etc/hapee-1.8/certs/ssl.pem

4. On the aggregation primary node, edit the file /opt/hapee-1.8/dashboard/dashboard-gateway/conf/config.json. For each node where you want to enable TLS, set host to the node's FQDN so that it matches the certificate; Set port to 9025; Set ssl set to true.

   {
      "isLogging": true,
      "logFile": "access.log",
      "defaultHandler": "socket",
      "defaultHostSSL": false,
      "nodes": [
         {
            "host": "127.0.0.1",
            "port": 9024
         },
         {
            "host": "lb2.test.com",
            "port": 9025,
            "ssl": true
         }
      ]
   }

5. Restart the Dashboard Gateway:

   $ sudo systemctl restart hapee-1.8-lb-dashboard-gateway

Enable HTTPS between the Dashboard UI and the Dashboard Gateway

The UI fetches metrics from the Dashboard Gateway. In order to encrypt this communication, you must enable HTTPS.

1. Obtain a valid TLS certificate for the node where you are running the Dashboard Gateway. This will be the aggregation primary node if running multiple instances of HAProxy Enterprise.

2. Make sure that the certificate and private key files are in PEM format. Copy both the certificate and key files to the path /opt/hapee-1.8/dashboard/dashboard-gateway. These should be made available before restarting the Dashboard Gateway.

3. Edit the file /opt/hapee-1.8/dashboard/dashboard-gateway/conf/config.json.

   • Set disableHttps to false

   • Set httpsCertFile to the path to the certificate file

   • Set httpsKeyFile to the path to the key file.

   {
      "isLogging": true,
      "logFile": "access.log",
      "defaultHandler": "socket",
      "defaultHostSSL": false,
      "disableHttps": false
      "httpsCertFile": "cert.pem",
      "httpsKeyFile": "key.pem",
      "nodes": [
         {
            "host": "127.0.0.1",
            "port": 9024
         },
         {
            "host": "lb2.test.com",
            "port": 9025,
            "ssl": true
         }
      ]
   }

4. Restart the Dashboard Gateway:

   $ sudo systemctl restart hapee-1.8-lb-dashboard-gateway

5. Restart the Dashboard Gateway:

   $ sudo systemctl restart hapee-1.8-lb-dashboard-gateway

6. Open the Real-time Dashboard in your browser and click the button to display the Settings window.

7. Set Real-time Dashboard Gateway URL to the FQDN of the Dashboard Gateway so that it matches the TLS certificate (e.g. dashboard-gateway.test.com:9021). Its port defaults to 9021, so you do not need to set it here.

8. Click the padlock icon in the Real-time Dashboard Gateway URL box so that it turns green. Then, click Close.