Searching HAProxy Enterprise 1.9r1
Monitoring and Controlling HAProxy using Dashboard Gateway
HAProxy Enterprise Dashboard Gateway is a Web service that allows access to HAProxy functionalities that are only available through the administrative TCP socket interface, such as:
Retrieving cumulative/average instance information (i.e. 'show info')
Performing administrative actions (such as changing backend servers' state)
The purpose of Dashboard Gateway is to monitor and control multiple HAProxy instances from a secured and trusted server that is only accessible to authorized users and through TLS secured connections (i.e. a "bastion" host).
How Dashboard Gateway works
You connect to Dashboard Gateway using the Real-Time Dashboard Web application. You can use HTTP BASIC authentication, which is secure enough when going through a SSL encrypted channel.
The Dashboard Gateway connects to configured HAProxy instance(s) using either the Runtime API or the Dashboard Module running on the instance.
The Gateway transfers statistics and other data to your browser from the instances, and it also relays any administrative actions you send from the Web application to the instances.
Note
The Dashboard Gateway is capable of SSL termination so that it is completely self-hosted (i.e. it does not require additional Web servers or reverse proxies). We recommend that you secure the communication with the Dashboard Gateway's HTTP server with a proper and trusted SSL certificate.
Prerequisites
HAProxy Enterprise version 1.6 or higher
Linux with an x86-64 CPU
Recommendations
The HAProxy endpoints must expose the admin interface over a TCP socket. As this is a potential security issue, we strongly recommend the following security measures when deploying Dashboard Gateway:
The admin TCP socket is only exposed with a TLS encrypted socket connection.
The bastion host on which Dashboard Gateway runs is the only host that has access to the exposed TCP port. We strongly suggest that you enforce this practice at both the HAProxy TCP ACL level and through firewall rules.
Conventions
HTTP and HTTPS options and settings are generally used for this Web service, in order to serve data and accept commands via HTTP
The TCP and HAPROXY options are associated to the managed HAProxy endpoints
In all configuration examples, non-literal and user-defined values go within "{{ doublebrackets }}" with a descriptive name inside; explanations for the values go below the configuration example block.
Setting up HAProxy instances
Each HAProxy instance that the Dashboard Gateway must access requires an admin socket interface exposed on a TCP port that is additionally protected by TLS encryption and network access control rules.
-
Enable
stats socket
in theglobal
section, as follows:global stats socket {{ admin_unix_socket_path }} mode 660 level admin
The default for admin_unix_socket_path is /run/haproxy/admin.sock.
-
Add a listener:
listen admin_sock mode tcp bind {{ haproxy_ip }}:{{ admin_socket_port }} # additionally add: ssl crt {{ path_to_pem_file }} # for ACL add: acl allow_admin_sock src {{ gateway_host_ip }} # for ACL add: tcp-request connection rejectif !allow_admin_sock server admin_sock1 unix@{{ admin_unix_socket_path }}
where:
haproxy_ip
andadmin_socket_port
are the address and port where the admin socket listens for TCP socket connections from Dashboard Gateway. The 'pem' file is a concatenated certificate and key file (in that order).gateway_host_ip
is the IP address of the host running the node gateway as seen from the HAProxy server.admin_unix_socket_path
is the same socket path given in theglobal
section above.
Important
As mentioned previously, we strongly recommend that you limit access to the admin TCP port and to use firewall rules to the gateway host.
Installing Dashboard Gateway
You obtain the Dashboard Gateway through the HAProxy Enterprise package repositories. You can consult the installation instructions on: User Guide and browse to the User Guide and then the installation instructions for your Linux distribution. The Dashboard Gateway is in the hapee-plus
repository.
After you set up the repositories, you install hapee-1.9-lb-dashboard-gateway
.
Debian and Ubuntu:
$ apt-get install hapee-1.9-lb-dashboard-gateway
RedHat and CentOS:
$ yum install hapee-1.9-lb-dashboard-gateway
Installing from an archive
If you have a compressed archive (i.e. a .zip file):
Unzip the archive in a directory.
Copy the contents of the "dist" directory to where you want to install Dashboard Gateway.
Run the Dashboard Gateway from this directory:
$ unzip hapee-rt-dashboard-gateway-{{ version }}-{{ commit_hash }}.zip
$ cp -fr ./dist/* /some/directory/
The version
and commit_hash
depend on the package version you have.
Running Dashboard Gateway
Note
To run on privileged ports like 80 or 443, you must run the service as root. We recommend that you use the default ports 9020 for HTTP and 9021 for HTTPS access. The benefit of using default ports is that you do not have to specify port numbers when configuring the RT Dashboard UI.
After you install Dashboard Gateway, you can run it from the application directory (typically, it is installed into /opt/hapee-1.9/dashboard/dashboard-gateway):
$ ./haproxy-dashboard-gateway
Since Dashboard Gateway is not a daemon, you can run it as a systemd
service as shown below:
[Unit]
Description=HAProxy Enterprise Dashboard Gateway
After=network.target
[Service]
Type=simple
User=root
ExecStart=/opt/hapee-1.9/dashboard/dashboard-gateway/haproxy-dashboard-gateway
WorkingDirectory=/opt/hapee-1.9/dashboard/dashboard-gateway
Restart=on-failure
[Install]
WantedBy=multi-user.target
Note
Replace the user (root
) and installation directory ( /opt/hapee-1.9/dashboard/dashboard-gateway) with values for your environment.
Configuring Dashboard Gateway
You configure the main Dashboard Gateway instance in the 'conf/config.json' file.
Note
The configuration from the JSON file automatically overrides environment variables.
The file uses the standard JSON format, which means that JavaScript comments cause a parser error and Dashboard Gateway exits without starting. Hence, include comments or explanations only in documentation and not in the actual configuration file.
You can configure the following options:
Global options
| Whether or not the server is logging to a log file in addition to stdout/stderr. Default: false |
| Path of the file to log to. Default: "" |
Gateway HTTP Server
The HTTP server listens on both HTTP and HTTPS ports:
| HTTP port where the server listens on. Default: 9020 |
| HTTPS port where the server listens on. Default: 9021 |
| Whether to disable the non-TLS HTTP server. Default: false |
| Whether to disable HTTPS server. - When set to true, Dashboard Gateway does not look for or load an SSL certificate. - When set to false, the absence of a SSL certificate prevents Dashboard Gateway from starting. - Default: true |
| Path to the SSL Key file for the HTTPS server. Default: "key.pem" |
| Path to the SSL Certificate file for the HTTPS server. Default: "cert.pem" |
| TLS pass phrase for certificate/key, if required. Default: "" |
| URI path under which the /dashboard, /gateway, /cluster sub-paths are available. Default: / |
| Disable HTTP Basic authentication. We strongly recommend that you do not disable this option. Default: false |
| Challenge HTTP Basic Authentication. Default: false |
| Realm for HTTP Basic Authentication. Default: "HAProxy Enterprise Real-Time Dashboard Gateway" |
Handler options
Use the following options to define a default handler:
| Handler to use by default for requests. Default: "socket" |
| Always used in /dashboard requests. Default: 127.0.0.1 |
| Whether to use encryption for default host. Default: false |
| Default port to use for default handler. If not provided, a default comes from the table below. |
| Default user for Module handlers. Default: dashboard |
| Default password for Module user. Default: "test" |
The default port mappings are given with the following table:
Handler | Protocol | Port |
---|---|---|
module | HTTP | 9022 |
module | HTTPS | 9023 |
socket | TCP Plaintext | 9024 |
socket | TCP with TLS | 9025 |
Serving the Dashboard UI
HAProxy Enterprise Real-Time Dashboard is a static Web application that you can serve from any location. The Dashboard Gateway allows you to serve static files by defining a configuration option:
staticRoot
{ String } - Path from which static files are served.
Note
Defined API paths (/api_spec, /gateway, /dashboard, /cluster and /config) override any static files/directories with the same name.
Defining nodes
You can define multiple nodes and have Dashboard Gateway behave either as an Aggregation Cluster Master Node, or sample statistics and send administrative actions from multiple instances in Gateway Mode.
If there are multiple nodes in the configuration, Dashboard Gateway operates in cluster mode with the following characteristics:
Calls to /cluster/(info|stat|data) endpoints return data statistics from all nodes, in format compatible to Dashboard Module
Any request to a node not in the list of nodes results in a 404 error
GET
on cluster/nodes returns a list of currently active cluster nodes as a JSON array of strings in form of [host:port
, ... ]PUT
on cluster/nodes can be either a JSON array of strings or an array of JSON objectsGET
on /gateway/config?allNodes=true returns internal configuration object with all nodes defined on Dashboard Gateway
Gateway mode is similar to single-node mode, but with selectable host/instance:
GET
on gateway/(info|stat|data
) must have a host and port (at minimum) query parameters, in order for Dashboard Gateway to select the host from which statistics derive samples.PUT
on gateway/admin must have host parameter (a string inhost:port
format) set in JSON payload to select the host.
You define the nodes that Dashboard Gateway can connect to in an array of objects, as follows:
[
{
"host": "{{ hostname_or_ip }}",
"port": "{{ portnumber }}",
"handler": "module" | "socket"
"ssl": {{ true | false }},
"user": "{{ username }}",
"password": "{{ password }}"
},
...
]
Note
Each node must have a host. Dashboard Gateway discards any node without a host. Aside from host, when other values are not provided, they default to defaultXxxx values as documented previously.
Using environment variables as alternative configuration
Aside from editing the file 'config.json', you can also configure Dashboard Gateway using environment variables. Detailed explanation of available environment variables is given in the .env.example file.
There are several ways to set environment variables for a specific program on the system:
Important
To make the setup and administration of Dashboard Gateway maintainable, we strongly recommend that you use only one method of configuration: either the 'config.json' file or only one of the methods explained below. Regardless, the order of interpretation allow the .env file to override environment variables set by other means; and settings in 'config.json' override all other settings.
Note
You cannot configure nodes for Cluster Aggregation using environment variables or environment files.
Using the .env file
The file .env is a convention for storing deployment environment variables for a particular service.
To configure Dashboard Gateway with the .env file:
Copy the file ''.env.example' file to .env in the 'conf' directory:
$ cp conf/.env.example conf/.env
Edit it to suit your environment.
Using the command line
-
You can export each environment variable that you want to the Linux environment before you start the program:
$ export HANDLER=module $ ./hapee-dashboard-gateway
-
or simply set the variables in the command line when you start the service:
$ HANDLER=module ./hapee-dashboard-gateway
Setting the environment for a systemd
service
If you configured Dashboard Gateway to run as a systemd
service as above, you can also add environment variables to the [Service] section in the unit file, either:
-
As multiple environment variables:
Environment="HANDLER=module HTTP_PORT=9120"
-
or by pointing to an environment file:
EnvironmentFile=/some/environment/file
Note
some/environment/file
uses the same format as .env file mentioned above.
Authenticating Dashboard Gateway
You configure the HTTP BASIC authentication and authorization setup in the 'conf/htpasswd.json' file.
The 'htpasswd.json' file has the following options:
{
"{{ username_1 }}": {
"password": "{{ sha256_password_hash }}",
},
"{{ username_2 }}": {
// . . .
},
// . . .
}
The "username" defined in the RT Dashboard UI gives all access control options for a given user.
You can generate the password hash with the following command:
$ echo -n "{{ password }}" | sha256sum
Note
The hash must be a hexadecimal string. Letter characters in the hexadecimal string can be either lowercase or uppercase.