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.
<?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:
<?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.
| Name | Data | Description |
|---|---|---|
|
|
Sent to signify an Edge instance coming online. |
|
|
Sent periodically to demonstrate internet connectivity. |
|
|
Sent when an adapter starts. |
|
|
Sent when an adapter encounters an unforeseen error. |
|
|
Sent when a bridge starts. This event helps to determine if a bridge connects to HiveMQ Cloud. |
|
|
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:
-
Heap Analytics: For more information on how Heap Analytics collects data, see the auto-capture configuration.
| 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.
| Java Option | Environment Variable | Affected 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:
<?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. |
<?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:
#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.
<?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>