HiveMQ Edge Configuration

HiveMQ Edge is preconfigured with default settings that are suitable to get started you started on many typical use cases.

HiveMQ Edge Configuration Files

All configuration files are located in the conf folder of the HiveMQ Edge directory.

HiveMQ Edge uses a simple but powerful XML based configuration.

HiveMQ Edge Default Configuration

HiveMQ Edge is designed to use sensible default values. The default and standard TCP listener binds to all interfaces and uses the standard MQTT port 1883.

Example HiveMQ Edge default TCP listener configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <mqtt-listeners>
        <tcp-listener>
            <port>1883</port>
            <bind-address>0.0.0.0</bind-address>
        </tcp-listener>
    </mqtt-listeners>
</hivemq>
Example HiveMQ Edge Configurations
HiveMQ Edge comes with many example configurations to get you started quickly. All example configurations reside in the conf/examples/configuration folder. If you want to use one of the example configurations, copy it to the conf folder and name it config.xml.

HiveMQ Edge Usage Tracking

HiveMQ Edge optionally sends data to servers to help us monitor usage patterns and continuously improve the HiveMQ Edge product. The following section explains the collected data for the backend and frontend of HiveMQ Edge.

To turn usage tracking off, disable usage-tracking in your config.xml file:

Example configuration to disable usage tracking
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <usage-tracking>
        <enabled>false</enabled>
    </usage-tracking>
</hivemq>

Data Collected in the HiveMQ Edge Application

The table below lists the specific usage events we track and all data sent. If desired, you can configure HiveMQ Edge to disable usage tracking.

Table 1. Collected usage tracking events and data
Name Data Description

EDGE_STARTED

Installation ID, Remote Address, Timestamp, Version, Session Token, VM Version, OS Architecture, OS Name, OS Version, Processor Count, VM Max Memory

Sent to signify an Edge instance coming online.

EDGE_PING

Installation ID, Remote Address, Timestamp, Version, Session Token

Sent periodically to demonstrate internet connectivity.

ADAPTER_STARTED

Installation ID, Remote Address, Timestamp, Version, Session Token, Adapter Type

Sent when an adapter starts.

ADAPTER_ERROR

Installation ID, Remote Address, Timestamp, Version, Session Token, Adapter Type, Nature Of Error

Sent when an adapter encounters an unforeseen error.

BRIDGE_STARTED

Installation ID, Remote Address, Timestamp, Version, Session Token, Adapter Type, Cloud Connection

Sent when a bridge starts. This event helps to determine if a bridge connects to HiveMQ Cloud.

BRIDGE_ERROR

Installation ID, Remote Address, Timestamp, Version, Session Token, Nature Of Error

Sent when a bridge encounters an unforeseen error.

Data collected in HiveMQ Edge web application

The HiveMQ Edge web application uses a limited number of tracking technologies. These technologies enable us to analyze usage behavior in the Edge product to measure and improve performance.

The following technologies are currently configured:

A consent form is displayed in the browser at first usage. Your selection to opt-in or opt-out is recorded in the local storage of your browser. Tracking is activated or not activated accordingly.

Manually set specific HiveMQ Edge folders

To simplify some maintenance use cases, HiveMQ Edge allows you to manually set specific folders.

To manually set a folder, add one or more of the following options to your bin/run.sh file.

JAVA_OPTS="$JAVA_OPTS -D...=/your/folder/here"

Alternatively, you can define environment variables.

export ...=/your/folder/here

If both a Java option and environment variable are set for the same folder, the value of the Java option is used.

Table 2. Folder Configuration Options
Java Option Environment Variable Affected folder

hivemq.home

HIVEMQ_HOME

Base folder (bin needs to be a sub folder of this folder)

hivemq.log.folder

HIVEMQ_LOG_FOLDER

Log files folder

hivemq.config.folder

HIVEMQ_CONFIG_FOLDER

Configuration files folder

hivemq.extensions.folder

HIVEMQ_EXTENSION_FOLDER

Extension binaries folder

hivemq.data.folder

HIVEMQ_DATA_FOLDER

HiveMQ data folder

Example for Java option:

JAVA_OPTS="$JAVA_OPTS -Dhivemq.home=/mqtt/broker/hivemq"

Example for environment variable:

export HIVEMQ_HOME=/mqtt/broker/hivemq

Sets the HiveMQ home folder to /mqtt/broker/hivemq.

HiveMQ Edge Offline Buffering

HiveMQ Edge provides offline buffering features to avoid data-loss for MQTT and HiveMQ Edge Bridge traffic.

MQTT In-memory Persistence

HiveMQ Edge stores data in-memory. This storage method is useful for systems with very limited disk space or when it is desirable to limit disk input/output (I/O).

Operations such as reading the config.xml file and writing logs always require disk I/O operations.

In-memory persistence stores the following persistent data in memory:

  • Client session information

  • Queued messages

  • Will messages

  • Retained messages

  • Subscriptions

HiveMQ Edge MQTT Bridge

You can persist the traffic transmitted through a HiveMQ Edge Bridge to a remote broker. Persistence can be configured on a per-bridge basis and is particularly advantageous when the network connection to the remote MQTT broker is unstable. As soon as the network regains full functionality, HiveMQ Edge forwards the buffered messages to the remote broker.

Only MQTT payloads with MQTT quality of service levels QoS 1 or QoS 2 are persisted.
Offline Buffering is a commercial feature for HiveMQ Edge. Feel free to reach out to our sales team to obtain a license.

Offline Buffering can be configured via the following settings to store on disc:

Example Offline Buffering configuration for disk persistence
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <persistence>
        <mode>file-native</mode>
    </persistence>
</hivemq>

The file-native mode indicates that the state of HiveMQ Edge is written to disc. When the file-native mode is selected, the state of HiveMQ Edge remains present and is immediately reloaded at startup even after a restart or hardware issue.

When HiveMQ Edge is stopped, data stored in-memory is not persisted to disk.
Example Offline Buffering for in-memory persistence only
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <persistence>
        <mode>in-memory</mode>
    </persistence>
</hivemq>
By default, the Offline Buffering persistence mode is set to in-memory. For production use, we recommend you set the persistence mode to file-native.

IPv6

IPv6 is an internet protocol standard and the successor of the established IPv4. Since standardization in 1998, IPv6 usage has continuously increased.

With some small adjustments HiveMQ Edge is able to operate using IPv6. Here is a guide to using IPv6 for our more experimental users.

Running HiveMQ Edge with IPv6 in a production environment is currently not supported.

Adjust HiveMQ Edge Configuration for IPv6

HiveMQ Edge uses IPv4 addresses by default. This setting can be changed in the run-script:

Example configuration to use IPv6 addresses
#Stop preferring IPv4 addresses
JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv4Stack=false"

#Prefer IPv6 addresses
JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv6Addresses=true"

The bind-address in your config.xml file needs to be configured with an IPv6 address.

Example IPv6 bind address configuration
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <listeners>
        <tcp-listener>
            <port>1883</port>
            <!-- '::' instead of 0.0.0.0 -->
            <bind-address>::</bind-address>
        </tcp-listener>
    </listeners>

</hivemq>

Available IPv6 Listeners

Listeners Status

TCP

TLS

[1]

WebSocket

Secure WebSocket

[1]

Special-use addresses for IPv6

Table 3. IPv6 special-use addresses
Special-use addresses IPv4 IPv6 counterpart

Any

0.0.0.0

::

Loopback

127.0.0.1

::1

Default multicast

228.8.8.8

ff0e::8:8:8


1. No MQTT client library available for testing this feature with IPv6