Control Center Configuration

The HiveMQ Control Center works out of the box without any additional installation or configuration.
However, we highly recommend that you fine-tune your control center configuration to match your individual use case.

Access Control

The following information shows you how to enable access to the HiveMQ Control Center and how to securely configure this access.

User Configuration

The default login name for the HiveMQ Control Center is admin and the default password is hivemq.
The default credentials are only active when no custom user is configured.

If you configure the HiveMQ Control Center to listen on a public network interface, we highly recommend that you configure a custom user and password.

You can configure multiple users for your HiveMQ Control Center.

To create one or more control center users, add credentials in the <users> tag.
Each <user> tag you add to the <users> tag configures the name and password for one control center user.

Example user configuration for the HiveMQ Control Center

<?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 systems, generating a correctly salted and hashed password can easily be achieved from your 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 is similar to the following entry:

9e2ee742214c2940b9e21149d4e1749d98d8d74e2b0f7453d190b1a7d73308b9

Next, configure your control center user in the config.xml accordingly.

Example custom HiveMQ Control Center user configuration

<?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>

HiveMQ automatically generates a default user that can be used until a custom control center user is specified.
If desired, the default user can be disabled for security reasons. The <default-user-enabled> configuration allows you to define whether the default user for your control center is enabled or disabled.

Example configuration to disable default HiveMQ Control Center user

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

Control Center Listeners

The HiveMQ Control Center is accessible via the use of a web browser. To allow access, HiveMQ opens an HTTP or HTTPS listener. Similar to other HiveMQ Listener Configuration Options, the configuration of a regular control center listener only requires the definition of a port and bind address.
The configuration of a secure TLS encrypted listener requires the definition of additional <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 for the HiveMQ Control Center on port 8080 and binds to the local interface on 127.0.0.1.
If you want the Control Center to be externally reachable, you can bind the listener to another interface.
If you use port 8080 for other purposes, it is also possible to change the listener port.

Example HTTP listener configuration for the HiveMQ Control Center

<?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. By default, your HiveMQ Control Center is automatically available on http://localhost:8080, with the default user credentials.

HTTPS Listener

HiveMQ offers the possibility to use a secure TLS encrypted HTTPS listener to establish connection with the Control Center. If your use case requires TLS encryption, you can configure HTTPS listeners for your HiveMQ Control Center.

Example HTTPS listener configuration for the HiveMQ Control Center

<?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>

Client Event History

To simplify the analysis and monitoring of your MQTT client behavior, HiveMQ provides access to the event history of each client. The detailed event history can provide valuable insights into the performance of your system. For example, to review the effect of overload protection on client connection or diagnose client behavior during topology changes. It is also possible to access the events in the client history through an extension API to trigger event-based actions or export event data to a third-party-system for futher analysis.

By default, the client event history is enabled and records the previous seven days of events for each client. You can adjust the time period as desired to suit your use case.

Example client event history configuration

<?xml version="1.0"?>
<hivemq>
    ...
    <control-center>
        ...
	    <client-event-history>
		    <enabled>true</enabled>
		    <lifetime>604800</lifetime> <!-- 7 days -->
	    </client-event-history>
        ...
    </control-center>
    ...
</hivemq>

For more information, see Event History.