HiveMQ Control Center v2 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.

HiveMQ Control Center V1 and V2 currently share the same configuration.

HiveMQ Control Center Access Control

The HiveMQ Control Center provides various ways to secure and limit access.

Configure HiveMQ Control Center Users

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> section of your <control-center> configuration.
Each <user> tag you add in the <users> section configures the name and password for one control center user.

Example HiveMQ Control Center user configuration

<?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 parameters
Parameter	Description
name	The name of the user.
password	The SHA256 hashed password of the user without iterations with the username as prepended salt. For more information, see Generate SHA256 Password.

The following example shows the default configuration:
Username: admin Password: hivemq SHA256 of adminhivemq = a68fc32fc49fc4d04c63724a1f6d0c90442209c46dba6975774cde5e5149caf8

Generate SHA256 Password

On Linux or macOS-based systems, a correctly salted and hashed password can be easily generated from your command line.

Choose a username and password in plain text. For example, Username: demo-example, Password: abc123.

Based on your operating system, enter one of the following commands on your command line:

macOS:

# SHA256 of <username><password>
echo -n demo_exampleabc123 | shasum -a 256

Linux:

# SHA256 of <username><password>
echo -n demo_exampleabc123 | sha256sum

The resulting output is similar to the following entry:

c93db5044138468e3baaeec38a4256998d23d64f24d186f1bd987cf31570b5a3

Use the output to configure a Control Center user in the config.xml of your HiveMQ deployment.

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>demo_example</name>
                <password>c93db5044138468e3baaeec38a4256998d23d64f24d186f1bd987cf31570b5a3</password>
            </user>
        </users>
        ...
    </control-center>
    ...
</hivemq>

Disable HiveMQ Control Center Default User

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 HiveMQ Control Center is enabled or disabled.

Example configuration to disable the 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 for Your HiveMQ Control Center

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, to 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. For more information, see ESE Control Center Access Control.

HiveMQ Control Center Listener

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 a bind address. The configuration of a secure TLS-encrypted listener requires the definition of additional <tls> configuration options.

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. To make your Control Center 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, the HiveMQ Control Center is automatically available on http://localhost:8080 (v1) and http://localhost:8080/v2/ (v2) with the default user credentials.

HTTPS Listener

HiveMQ offers the possibility to use a secure TLS-encrypted HTTPS listener to establish a 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. However, 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 Parameters
Parameter	Default	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`		The 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`		An 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-suites`		An 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.