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.

  1. Enable stats socket in the global 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.

  2. 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 and admin_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 the global 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):

  1. Unzip the archive in a directory.

  2. Copy the contents of the "dist" directory to where you want to install Dashboard Gateway.

  3. 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

Option | Type |

isLogging { true|false }

Whether or not the server is logging to a log file in addition to stdout/stderr. Default: false

logFile { String }

Path of the file to log to. Default: ""

Gateway HTTP Server

The HTTP server listens on both HTTP and HTTPS ports:

httpPort { Number }

HTTP port where the server listens on. Default: 9020

httpsPort { Number }

HTTPS port where the server listens on. Default: 9021

disableHttp { true|false }

Whether to disable the non-TLS HTTP server. Default: false

disableHttps { true|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

httpsKeyFile { String }

Path to the SSL Key file for the HTTPS server. Default: "key.pem"

httpsCertFile { String }

Path to the SSL Certificate file for the HTTPS server. Default: "cert.pem"

tlsPassphrase { String }

TLS pass phrase for certificate/key, if required. Default: ""

apiRoot { String }

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

skipBasicAuth { true|false }

Disable HTTP Basic authentication. We strongly recommend that you do not disable this option. Default: false

authChallenge { true|false }

Challenge HTTP Basic Authentication. Default: false

authRealm { String }

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

Handler options

Use the following options to define a default handler:

defaultHandler { String }

Handler to use by default for requests. Default: "socket"

defaultHost { String } Default hostname/IP.

Always used in /dashboard requests. Default: 127.0.0.1

defaultHostSSL { true|false }

Whether to use encryption for default host. Default: false

defaultHostPort { Number }

Default port to use for default handler. If not provided, a default comes from the table below.

defaultModuleUser { String }

Default user for Module handlers. Default: dashboard

defaultModulePassword { String }

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 objects

  • GET 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 in host: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:

  1. Copy the file ''.env.example' file to .env in the 'conf' directory:

$ cp conf/.env.example conf/.env
  1. 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.