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

By default, the HiveMQ Control Center supports TLSv1.2 and TLSv1.3. The specific JDK that you use can impact which TLS versions are available.
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>

                    <!-- Optional setting to explicitly define the accepted TLS version  -->
                    <!---
                    <protocols>
                        <protocol>TLSv1.3</protocol>
                    </protocols>
                    -->

                    <!-- Optional setting to explicitly define the accepted cipher suites -->
                    <!--
                    <cipher-suites>
                            <cipher-suite>TLS_RSA_WITH_AES_256_CBC_SHA256</cipher-suite>
                            <cipher-suite>TLS_RSA_WITH_AES_256_GCM_SHA384</cipher-suite>
                    </cipher-suites>
                    -->
                </tls>
            </https>
        </listeners>
        ...
    </control-center>
    ...
</hivemq>
Table 2. HTTPS Listener Configuration Options
Parameter Default Required Description

port

8080

The port on the local machine that listens for HiveMQ Control Center requests. The HTTPS port address can be changed.

bind-address

127.0.0.1

The address on the local machine that accepts HiveMQ Control Center requests. The HTTPS bind-address can be changed.

path

Location of the P12 or JKS certificates that the keystore uses to store entries.

password

The password to the associated keystore.

private-key-password

The password that protects the private key of the keystore.

protocol

Optional setting to manually specify the versions of the TLS protocol that can be used to secure communication to the HiveMQ Control CEnter. For example, you can configure the Control Center to only accept TLSv1.2. By default, the HiveMQ Control Center uses the default TLS version of your JDK.

cipher-suite

Optional setting to explicitly define cipher suites. If desired, you can define specific cipher suites to limit the number of suites that are enabled. If no cipher suites are specified in the cipher-suites tag or the tag is missing, the Control Center uses the default cipher suites of your JDK.
Make sure the port you configure for your HTTPS listener is not already in use by any other service.

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