Configuration

While the HiveMQ Web UI 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 Web UI 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 Web UI to listen on a public network interface.

The HiveMQ Web UI 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"
        xsi:noNamespaceSchemaLocation="../../hivemq-config.xsd">
    ...
    <web-ui>
        ...
        <users>
            <user>
                <name>yourUserName</name>
                <password>yourPassword</password>
            </user>
        </users>
        ...
    </web-ui>
    ...
</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"
        xsi:noNamespaceSchemaLocation="../../hivemq-config.xsd">

    ...
    <web-ui>
        ...
        <users>
            <user>
                <name>test</name>
                <password>9e2ee742214c2940b9e21149d4e1749d98d8d74e2b0f7453d190b1a7d73308b9</password>
            </user>
        </users>
        ...
    </web-ui>
    ...
</hivemq>

Listeners

The HiveMQ Web UI 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 Web UI 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 Web UI 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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../hivemq-config.xsd">
    ...
    <web-ui>
        <enabled>true</enabled>
        <listeners>
            <http>
                <port>8080</port>
                <bind-address>localhost</bind-address>
            </http>
        </listeners>
        ...
    </web-ui>
    ...
</hivemq>

For local testing purposes, no configuration of the HiveMQ Web UI 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 Web UI. 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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../hivemq-config.xsd">
    ...
    <web-ui>
        <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>
        ...
    </web-ui>
    ...
</hivemq>