HAProxy Enterprise Documentation 1.8r2
Dashboard Gateway
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 Enterprise 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
-
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
-
Restart HAProxy:
$ sudo systemctl restart hapee-1.8-lb
-
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.
-
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"
}
]
}
-
Start the Dashboard Gateway:
$ sudo systemctl enable hapee-1.8-lb-dashboard-gateway
$ sudo systemctl start hapee-1.8-lb-dashboard-gateway
Open the Real-Time Dashboard in your browser and click the
button to display the Settings window.
Set Data Source to Real Time Dashboard Gateway.
Set Data Source Mode to Single Node.
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.
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.
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:
On each HAProxy Enterprise server, edit the HAProxy Enterprise configuration file to add a stats socket
directive in the global
section.
-
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
-
Restart HAProxy:
$ sudo systemctl restart hapee-1.8-lb
-
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
-
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
-
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
}
]
}
-
Start or restart the Dashboard Gateway:
$ sudo systemctl enable hapee-1.8-lb-dashboard-gateway
$ sudo systemctl start hapee-1.8-lb-dashboard-gateway
Open the Real-Time Dashboard in your browser and click the
button to display the Settings window.
Set Data Source to Real Time Dashboard Gateway.
Set Data Source Mode to Cluster Aggregation.
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.
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
-
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:
-
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
-
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
-
Install the dashboard-gateway package:
$ sudo apt install hapee-1.8r2-lb-dashboard-gateway
-
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
-
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
}
]
}
-
Start the Dashboard Gateway:
$ sudo systemctl enable hapee-1.8-lb-dashboard-gateway
$ sudo systemctl start hapee-1.8-lb-dashboard-gateway
Open the Real-Time Dashboard in your browser and click the
button to display the Settings window.
Set Data Source to Real Time Dashboard Gateway.
Set Data Source Mode to Cluster Aggregation.
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.
Click the
button to display the Cluster Setup window. Check that all nodes are listed. Then, click
to complete setup.
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.
-
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.
-
Edit the file to change the existing username and password. Use the following command to create the encrypted password:
$ echo -n "YOUR_PASSWORD" | sha256sum
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.
Obtain a valid TLS certificate for each HAProxy Enterprise child node.
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.
-
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
-
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
}
]
}
-
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.
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.
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.
-
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
}
]
}
-
Restart the Dashboard Gateway:
$ sudo systemctl restart hapee-1.8-lb-dashboard-gateway
-
Restart the Dashboard Gateway:
$ sudo systemctl restart hapee-1.8-lb-dashboard-gateway
Open the Real-Time Dashboard in your browser and click the
button to display the Settings window.
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.
Click the padlock icon in the Real Time Dashboard Gateway URL box so that it turns green. Then, click Close.
Next up
Using the Dashboard