The Dashboard Gateway is an alternative to the Real-Time Dashboard Lua module and works with all versions of HAProxy. It collects metrics data from one or several HAProxy instances and exposes it for the Dashboard Gateway to use. By default, it runs an API at port 9020.

Enable metrics for a single instance

  1. Edit your HAProxy 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 instance, as follows:

    global
        stats socket ipv4@127.0.0.1:9024 level admin
  2. Restart HAProxy:

    $ sudo systemctl restart hapee-2.1-lb
  3. Install the dashboard-gateway package with apt or yum, depending on your operating system:

    $ sudo apt install hapee-2.1r1-lb-dashboard-gateway

    Attention!

    Currently, there is a bug in the Dashboard Gateway service. The file /lib/systemd/system/hapee-2.1-lb-dashboard-gateway.service has an ExecStart set to /opt/hapee-2.1/dashboard/dashboard-gateway/haproxy-dashboard-gateway, but it should be /opt/hapee-2.1/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-2.1/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-2.1-lb-dashboard-gateway
    $ sudo systemctl start hapee-2.1-lb-dashboard-gateway
  6. Open the Real-Time Dashboard in your browser and click the Settings 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 instance's socket. The port defaults to 9024, so you do not need to set it here.

  11. Click the Start button to complete setup.

Enable metrics for multiple instances

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

  1. On each HAProxy server, edit the HAProxy 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-2.1-lb
  4. Choose one server to be the "aggregation master" instance. On that server, install the dashboard-gateway package using apt or yum depending on your operating system:

    $ sudo apt install hapee-2.1r1-lb-dashboard-gateway
  5. Make a copy of the config.json.example configuration file and rename it config.json.

    $ cd /opt/hapee-2.1/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 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-2.1-lb-dashboard-gateway
    $ sudo systemctl start hapee-2.1-lb-dashboard-gateway
  8. Open the Real-Time Dashboard in your browser and click the Settings 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 Cluster button to display the Cluster Setup window. Check that all nodes are listed. Then, click Use Cluster to complete setup.

Enable metrics for multiple processes

  1. Edit the HAProxy 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-2.1r1-lb-dashboard-gateway
  5. Copy of the config.json.example configuration file and rename it config.json.

    $ cd /opt/hapee-2.1/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 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-2.1-lb-dashboard-gateway
    $ sudo systemctl start hapee-2.1-lb-dashboard-gateway
  8. Open the Real-Time Dashboard in your browser and click the Settings 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 Cluster button to display the Cluster Setup window. Check that all nodes are listed. Then, click Use Cluster to complete setup.

Configure the Dashboard Gateway

You can enable various settings for the Dashboard Gateway in the configuration file /opt/hapee-2.1/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:

Option

Description

apiRoot

URI path under which the /dashboard, /gateway, /cluster and other sub-paths are available. Default: /

authChallenge

Whether to show an HTTP Basic authentication challenge when accessing the API. Note that you can enable Basic authentication by setting skipBasicAuth to false, but not show a prompt. Default: false

authRealm

Realm for HTTP Basic authentication. Default: "HAProxy Enterprise Real-Time Dashboard Gateway"

defaultHandler

Default way for the gateway to connect to HAProxy. Either module or socket. Default: socket.

defaultHost

Default hostname or IP address the gateway uses to connect to HAProxy. Default: 127.0.0.1.

defaultHostPort

Default port the gateway uses to connect to HAProxy. Defaults to one of the following values:

Handler

Protocol

Port

module

HTTP

9022

module

HTTPS

9023

socket

TCP Plaintext

9024

socket

TCP with TLS

9025

defaultHostSSL

Whether to use encryption when communicating with HAProxy. Default: false.

defaultModulePassword

Default Lua module password to use when connecting to instances running the Dashboard Lua module.

defaultModuleUser

Default Lua module username to use when connecting to instances running the Dashboard Lua module.

disableHttp

Whether to disable serving the gateway API over HTTP. Default: false.

disableHttps

Whether to disable serving the gateway API over HTTPS. When set to false, you must also set httpsCertFile and httpsKeyFile. Default: true.

httpsCertFile

Path to the SSL certificate file when serving the gateway API over HTTPS. You must set disableHttps to false to enable HTTPS. If you use a relative path , ./ and ./cert will be searched. Default: cert.pem.

httpsKeyFile

Path to the SSL key file when serving the gateway API over HTTPS. You must set disableHttps to false to enable HTTPS. If you use a relative path, the API searches for ./ and ./cert. Default: key.pem.

httpPort

HTTP port where the gateway listens. Default: 9020.

httpsPort

HTTPS port where the gateway listens. Default: 9021.

isLogging

Whether to log to a file in addition to stdout/stderr. Default: false.

logFile

Path to the log file. Default: "".

tlsPassphrase

TLS passphrase for the certificate specified in httpsCertFile and httpsKeyFile. Default: "".

skipBasicAuth

Disable HTTP Basic authentication when accessing the gateway API. Default: false.

nodes

Collection of HAProxy instances that the gateway communicates with in order to get metrics.

The nodes collection has the following options:

Option

Description

host

The hostname or IP address the gateway uses to connect to HAProxy.

port

The port that the gateway uses to connect to HAProxy.

handler

The way in which the gateway connects to HAProxy. Either module or socket.

ssl

Whether to use encryption when communicating with HAProxy.

user

To use when connecting Gateway to instances running the Dashboard Lua module.

password

To use when connecting Gateway to instances running the Dashboard Lua module.

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-2.1/dashboard/dashboard-gateway/conf/htpasswd.json has the following format:

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

    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 Settings button to display the Settings window. Set the Username and Password values to match those you just configured.

Enable HTTPS between the aggregation master and child nodes

The aggregation master node fetches metrics from multiple HAProxy 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-2.1/certs.

  3. Edit the node's HAProxy 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-2.1/certs/ssl.pem
  4. On the aggregation master node, edit the file /opt/hapee-2.1/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-2.1-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 master 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-2.1/dashboard/dashboard-gateway. These should be made available before restarting the Dashboard Gateway.

  3. Edit the file /opt/hapee-2.1/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-2.1-lb-dashboard-gateway
  5. Restart the Dashboard Gateway:

    $ sudo systemctl restart hapee-2.1-lb-dashboard-gateway
  6. Open the Real-Time Dashboard in your browser and click the Settings 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.