Configuration

While the HiveMQ Control Center works out of the box with no necessity for any installation or configuration, it is possible and recommended to tailor the configuration to your specific needs.


Access Control

The following chapters explain, how to enable access to the HiveMQ Control Center and how to best configure this access in a secure manner.


User Configuration

The default login has the name admin and the password hivemq. This login only is active, if no custom user is configured.

Please manually configure a user, if you configured the HiveMQ Control Center to listen on a public network interface.

The HiveMQ Control Center can be configured with multiple users.

The users are configured inside the <users> tag. Each user is configured inside a <user> tag therein.

Configuring users
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <control-center>
        ...
        <users>
            <user>
                <name>yourUserName</name>
                <password>yourPassword</password>
            </user>
        </users>
        ...
    </control-center>
    ...
</hivemq>
Table 1. User configuration options
Property Name Description

name

The name of the user.

password

The password of the user as a SHA256 hash without iterations and with the user name as prepended salt. See Generate SHA256 Password, here

This is the default configuration:

Username: admin
Password: hivemq
SHA256 of adminhivemq = a68fc32fc49fc4d04c63724a1f6d0c90442209c46dba6975774cde5e5149caf8


Generate SHA256 Password

On Linux or OS X based system, generating a correctly salted and hashed password can be easily achieved via the use of the command line.

First choose a username and a password in plain text.

Username: test
Password: abc123

Then type the following into your command line.

MAC OSX:

echo -n testabc123 | shasum -a 256

LINUX:

echo -n testabc123 | sha256sum

The resulting prompt will look like the following.

9e2ee742214c2940b9e21149d4e1749d98d8d74e2b0f7453d190b1a7d73308b9

Then configure your user in the config.xml accordingly.

User Configuration Example
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <control-center>
        ...
        <users>
            <user>
                <name>test</name>
                <password>9e2ee742214c2940b9e21149d4e1749d98d8d74e2b0f7453d190b1a7d73308b9</password>
            </user>
        </users>
        ...
    </control-center>
    ...
</hivemq>


The automatic default user that is used when no custom user is specified, can be disabled for security reasons. The <default-user-enabled> configuration defines if the default user is enabled or disabled.

Disable Default User Example
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <control-center>
        ...
        <default-user-enabled>false</default-user-enabled>
        ...
    </control-center>
    ...
</hivemq>

Role Based Access Control

This is a HiveMQ Enterprise Edition feature. Find out more about HiveMQ Editions.

The HiveMQ Enterprise Edition supports Role Based Access Control (RBAC) for Control Center users. RBAC allows you to restrict user permissions and precisely control which users can view, access, and modify data. Use RBAC to create fine-grained access management for your HiveMQ system.

In environments with multiple administrators, legal reasons can require you to disable Control Center functionality for some or all users. For example, prevent the display of IP addresses. The HiveMQ Enterprise Edition allows you to restrict user access according to corporate compliance policies while providing best-in class monitoring and debug capabilities for production environments.

To support RBAC functionality for the Control Center, the HiveMQ Enterprise Security Extension enables the use of permissions that are stored in data sources such as SQL databases.


Listeners

The HiveMQ Control Center is accessible via the use of a web browser. In order to allow that access HiveMQ opens up an HTTP or HTTPS listener. Similar to other HiveMQ Listener Configuration Options, the regular configuration is complete by providing a port and bind address.
The configuration of a secure, TLS encrypted listener additionally requires <tls> configuration options.

Read this chapter when planning on using the HiveMQ Control Center with a load balancer.


HTTP Listener

By default HiveMQ opens the HTTP listener on port 8080 and binds it to the local interface on 127.0.0.1.
In case you want the Control Center to be externally reachable you can bind the listener to another interface. Likewise you can change the port, if 8080 is already in use on your machine or other reasons, why you need to use a different port, apply.

Example HTTP listener
<?xml version="1.0"?>
<hivemq>
    ...
    <control-center>
        <enabled>true</enabled>
        <listeners>
            <http>
                <port>8080</port>
                <bind-address>localhost</bind-address>
            </http>
        </listeners>
        ...
    </control-center>
    ...
</hivemq>
For local testing purposes, no configuration of the HiveMQ Control Center is necessary. It will be reachable at http://localhost:8080, using the default user credentials.


HTTPS Listener

HiveMQ offers the possibility to use a secure, TLS encrypted HTTPS listener for connection establishment with the Control Center. In case TLS encryption is a requirement you have to meet, configure an HTTPS listeners as listed below.

Example HTTPS listener
<?xml version="1.0"?>
<hivemq>
    ...
    <control-center>
        <enabled>true</enabled>
        <listeners>
            <https>
                <port>8443</port>
                <bind-address>0.0.0.0</bind-address>
                <tls>
                    <keystore>
                        <path>/path/to/key/store/store.jks</path>
                        <password>changeme</password>
                        <private-key-password>changeme</private-key-password>
                    </keystore>
                </tls>
            </https>
        </listeners>
        ...
    </control-center>
    ...
</hivemq>