HiveMQ Edge on Siemens Industrial Edge

HiveMQ Edge is available as an application for Siemens Industrial Edge. You get the application from the Siemens Digital Exchange, the marketplace for Industrial Edge.

This page has two parts:

  • The Tutorial shows how you install the application and how you send a configuration.

  • The Reference describes the application in detail.

Tutorial

What This Is

This tutorial is about HiveMQ Edge as an application on Siemens Industrial Edge. You install, configure, and manage the application in Siemens Industrial Edge Management, as with every other application on an Industrial Edge Device.

HiveMQ Edge runs next to machines on a plant floor. It reads data points from these machines through multiple protocols, for example, OPC UA, Modbus, or S7, and publishes them as MQTT messages. It forwards these messages through a bridge to an MQTT broker. There are two applications. HiveMQ Edge is the standard product. HiveMQ Edge Licensed is the licensed product and also supports the connection to the HiveMQ Platform, Data Intelligence, Data Hub, and MQTT persistence.

The device applications in Industrial Edge Management
Figure 1. The device applications in Industrial Edge Management, with both products.

Industrial Edge Management has two designs. This tutorial uses the new design. If you still use the previous design, the steps look slightly different.

This tutorial is about how you install and configure HiveMQ Edge, and not about how you use it. It therefore applies to both products. The one exception is the section Install a License.

This tutorial is for an operator who has general knowledge of Siemens Industrial Edge Management and of HiveMQ Edge. For Industrial Edge Management, see the Siemens Industrial Edge documentation at https://docs.industrial-operations-x.siemens.cloud/p/industrial-edge. For HiveMQ Edge, see the HiveMQ Edge documentation. For the details of the application on Industrial Edge, see the Reference.

Get HiveMQ Edge Running

In this section, you install the application on a device. HiveMQ Edge then runs with the default configuration that ships with the application.

  1. In Industrial Edge Management, select Applications and then Device in the menu on the left.

  2. Click the tile HiveMQ Edge.

  3. Click Install on device.

  4. Select the check box of the device.

The page of the application
Figure 2. The page of the application, with Install on device.

After you select the device, the install screen shows the section Configuration. In this section, you configure the application. HiveMQ Edge is a product with many options, so one or more files describe its configuration: the general configuration file config.xml and, for example, certificates. You send these files through the inputs of the application: all files together as one ZIP archive, or config.xml alone as text, which you can edit in the editor. The inputs are the only way to send files to the application, because the Industrial Edge Device allows no direct access. You see the same inputs again later, when you change the configuration of the installed application.

Each input is a row. To open a row, click the row. An open row shows a description of the input and the control for the content.

The install screen of the standard product
Figure 3. The install screen of the standard product, with both rows open. No check box is selected.
Input Content Use For

Configuration_as_text

The configuration file config.xml as text, in an editor

A first try and small changes

Configuration_as_zip_archive

A ZIP archive with config.xml and the certificates

A real setup

License_file

A license file

The licensed product only

Industrial Edge Management sends an input only if you select the check box of the input. For the first start, you send no input:

  1. Under Configuration, select no check box.

  2. Click Install.

HiveMQ Edge starts with the default configuration that ships with the application. That configuration has one MQTT listener and keeps the login to the Console closed. The Console is the web interface of HiveMQ Edge. For the ports of the application on the device, see Ports.

To see that the installation is complete, open the page of the application again. The page lists the device under Device installations. To see the result on the device itself, see the section See What the Application Did.

Change the Configuration

In this section, you make a first change to the configuration. You add a user, so that you can log in to the Console. You also add an adapter that simulates a machine. Every second, the adapter publishes a random temperature between 15 and 25 to the topic tutorial/temperature.

For a small change, you use the text input. The editor of the text input shows an example configuration, which is the configuration that ships with the application. The example starts with a notice of three lines, and each line starts with #. To use the text, edit the text and delete every line of the notice. The application ignores a text that still starts with #. The application rejects a text that starts with neither < nor #.

The text replaces config.xml and no other file.

The Login to the Console

The default configuration keeps the login to the Console closed. The element <username-authentication> in config.xml controls the login. You have three choices:

  • Leave the login closed. If HiveMQ Edge runs without anyone who uses the Console, use this choice. Keep <enabled>false</enabled>.

  • Define your own user name and password. This tutorial uses this choice.

  • Connect HiveMQ Edge to an authentication service, for example, LDAP or OpenID Connect. See the HiveMQ Edge documentation.

Every config.xml that you send must contain <username-authentication>. Without that element, HiveMQ Edge opens the built-in account admin, whose password is publicly known. For the same reason, you must not use the user name and the password of the built-in account for your own user. For more information, see Write config.xml.

The password is in config.xml as plain text. Industrial Edge Management stores the text input encrypted. On the device, config.xml is not encrypted.

The Steps

  1. On the page of the application, click the three dots at the end of the row of the device. Then click Update configuration.

  2. Open the row Configuration_as_text.

  3. Delete the three lines of the notice at the top of the text. The text then starts with <?xml version="1.0"?>.

  4. In the element <username-authentication>, change <enabled>false</enabled> to <enabled>true</enabled>.

  5. Add the following block after the line </username-authentication>. Replace the user name and the password with your own:

    <users>
        <user>
            <username>your-admin</username>
            <password>a-strong-password</password>
            <roles><role>admin</role></roles>
        </user>
    </users>
  6. Add the following block before the last line of the text, </hivemq>:

    <protocol-adapters>
        <protocol-adapter>
            <adapterId>tutorial-simulation</adapterId>
            <protocolId>simulation</protocolId>
            <config>
                <simulationToMqtt>
                    <pollingIntervalMillis>1000</pollingIntervalMillis>
                </simulationToMqtt>
            </config>
            <northboundMappings>
                <northboundMapping>
                    <topic>tutorial/temperature</topic>
                    <tagName>temperature</tagName>
                </northboundMapping>
            </northboundMappings>
            <tags>
                <tag>
                    <name>temperature</name>
                    <description>A random temperature between 15 and 25</description>
                    <definition>
                        <randomValue>
                            <valueType>DOUBLE</valueType>
                            <minValue>15</minValue>
                            <maxValue>25</maxValue>
                        </randomValue>
                    </definition>
                </tag>
            </tags>
        </protocol-adapter>
    </protocol-adapters>
  7. Select the check box of the row.

  8. Select Restart application after update.

  9. Click Update.

The page of the application after the installation
Figure 4. The page of the application after the installation, and the menu of the device, with Update configuration.
Update configuration
Figure 5. Update configuration, with the edited text, the check box of the row selected, and Restart application after update selected.

The application applies the text and restarts HiveMQ Edge. The restart takes about one to two minutes. HiveMQ Edge then runs the adapter. The adapter alone needs no restart, and HiveMQ Edge restarts itself for the changed login. If you select the restart, both changes are certain to take effect. An MQTT client that subscribes to tutorial/temperature receives a random number between 15 and 25 every second.

Open the Console

  1. In Industrial Edge Management, enable remote access to the device, and open the web interface of the device.

  2. Select Apps, and click the tile HiveMQ Edge.

  3. Log in with your user name and your password.

In the Console, select Protocol Adapters. The list shows the adapter tutorial-simulation with the status RUNNING.

The status Running of the application in Industrial Edge Management means that the container of HiveMQ Edge runs. It does not mean that HiveMQ Edge works correctly. After each update, open the Console.

The Console of HiveMQ Edge
Figure 6. The Console of HiveMQ Edge, Protocol Adapters, with the simulation adapter.

To see how the data flows, select Workspace. The Workspace shows the tag temperature, the adapter, and the topic tutorial/temperature.

The Workspace
Figure 7. The Workspace, with the simulated machine, the adapter, and HiveMQ Edge.

When a Restart Is Needed

Each update of the configuration offers Restart application after update. The following table shows when you need the restart:

What You Send Restart

A changed adapter or bridge in config.xml

Not needed. HiveMQ Edge applies the change within a few minutes.

Another change in config.xml, for example, to the login

Not needed. HiveMQ Edge restarts itself.

A new or changed certificate

Select the restart. HiveMQ Edge usually reads certificates only when HiveMQ Edge starts (Paths, Volumes, and Settings).

A license

Select the restart. Some licensed features, for example, Data Hub, start only when HiveMQ Edge starts.

If you are not sure

Select the restart. The restart takes about one to two minutes.

Send a Configuration with Certificates

In this section, you send a configuration that consists of more than one file. A real setup connects to a central broker and needs certificates. For such a setup, you use the ZIP input.

A ZIP archive holds the whole configuration. After the application applies a ZIP archive, the device holds the files that the ZIP archive contains. The application removes every certificate that the ZIP archive does not contain. To change a file later, change the file, build the ZIP archive again with all the files, and send the ZIP archive.

You keep the files in one folder:

config.xml
cert/edge-keystore.p12
cert/plant-truststore.p12

HiveMQ Edge reads a file in cert/ as /opt/hivemq/conf/cert/<file name>. Your config.xml must name each key store and each trust store by that path, for example, /opt/hivemq/conf/cert/edge-keystore.p12. To write the adapters and the bridges in config.xml, see the HiveMQ Edge documentation and Write config.xml.

  1. On a command line, build the ZIP archive from the folder that holds the files:

    zip site.zip config.xml cert/edge-keystore.p12 cert/plant-truststore.p12
  2. On the page of the application, click the three dots at the end of the row of the device. Then click Update configuration.

  3. Open the row Configuration_as_zip_archive.

  4. Click Browse, and select site.zip.

  5. Select the check box of the row.

  6. Select Restart application after update.

  7. Click Update.

Update configuration
Figure 8. Update configuration, with a ZIP archive attached, the check box of the row selected, and Restart application after update selected.

The application applies the ZIP archive and restarts HiveMQ Edge. The restart takes about one to two minutes.

If you send the text and a ZIP archive together, the application applies the ZIP archive first and then uses the text as config.xml.

Install a License

This section applies to the licensed product, HiveMQ Edge Licensed, only. In this section, you send a license file, so that HiveMQ Edge supports the licensed features.

The licensed product has one more input, License_file. The name of the license file must end in .edgelic. If necessary, rename the file before you send the file.

The install screen of the licensed product
Figure 9. The install screen of the licensed product, with the row of the license open.
  1. On the page of the application HiveMQ Edge Licensed, click the three dots at the end of the row of the device. Then click Update configuration.

  2. Open the row License_file.

  3. Click Browse, and select the license file.

  4. Select the check box of the row.

  5. Select Restart application after update.

  6. Click Update.

The application keeps the license until you send another license. A ZIP archive does not remove the license. To remove the license, send an empty file through the same input, with a restart. For more information, see The License.

See What the Application Did

In this section, you find out whether the application applied what you sent.

Industrial Edge Management reports an update as completed when the files are on the device. The application applies the files after that moment. You see the result on the device.

  1. In Industrial Edge Management, enable remote access to the device, and open the web interface of the device.

  2. Under Management, select HiveMQ Edge.

  3. In the list of volumes, find the volume hivemq_edge_m7u1h0a0_helper_state.

The volume holds one status file. The name of the status file is the result of the last installation or update:

The Name Starts With Meaning

APPLIED

The application applied the upload

UNCHANGED

The upload changed nothing. One cause is a ZIP archive that is identical to the ZIP archive that you sent before. Another cause is a text in which you did not delete every line of the notice at the top: the application ignores a text that starts with #.

REJECTED

The application rejected the upload and changed nothing. The file says what was wrong and what to do.

The web interface of the device
Figure 10. The web interface of the device, Management, with HiveMQ Edge selected.
Further down on the same page: the volumes. The status file is in the volume hivemq_edge_m7u1h0a0_helper_state.
Figure 11. Further down on the same page: the volumes. The status file is in the volume hivemq_edge_m7u1h0a0_helper_state.

Where to Go Next

The Reference covers the following topics:

Reference

This reference lists what you need to run HiveMQ Edge as an application on Siemens Industrial Edge:

  • The containers

  • The inputs and the ZIP archive

  • The rules by which the helper applies uploads

  • The paths, the volumes, and the settings

  • The installation, configuration changes, and config.xml

  • Certificates and the license

  • An update to a new version

  • The Console, the ports, and storage and memory

  • The status file and the logs

  • Troubleshooting

  • The limitations

The reference is for the person who installs the application, changes the configuration, or diagnoses the application. For the concepts, see the Tutorial.

The reference uses the following terms:

  • IEM: Industrial Edge Management, the Siemens system that installs and configures applications on devices.

  • Helper: The container of the application that applies uploads.

  • Console: The web interface of HiveMQ Edge.

  • Shipped file: A file that ships with the application, for example, the shipped config.xml. The helper log calls a shipped file "packaged".

  • Standard and licensed: The two products. Only the licensed product has an input for a license.

  • Batch: The uploads that arrive together. The helper applies or rejects a batch as a whole (How the Helper Applies Uploads).

  • Status file: A file on the volume of the helper. The name of the file is the result of the last installation or update (The Status File and the Logs).

What the Application Consists Of

The application contains the published hivemq/hivemq-edge image, unchanged, and a second container, the helper.

Container Image User Role

helper

hivemq/hivemq-edge-sie-helper, part of the package

Starts as root, continues as user 10000

Prepares the volumes, applies uploads, and reports that the helper is ready. Then applies uploads that arrive while HiveMQ Edge runs.

hivemq-edge

hivemq/hivemq-edge:2026.16

User 10000

The gateway. Starts when the helper is ready.

HiveMQ Edge waits for the helper at an installation and at a restart of the application. After a reboot of the device, or when HiveMQ Edge shuts down, the device starts HiveMQ Edge without waiting for the helper. In that case, HiveMQ Edge notices a new config.xml within about a minute after the helper applies the upload. A new key store and a new activation token take effect at the next restart of the application. Some features of a new license, for example, Data Hub, also start only at the next restart.

The helper needs root for one step. The device creates volumes and upload folders that root owns, and the helper gives the volumes and folders to user 10000. The helper changes to user 10000 before the helper reads an upload.

The following features are available in the licensed product only:

  • The connection to the HiveMQ Platform

  • Data Intelligence

  • Data Hub

  • MQTT persistence

The package runs on x86-64 processors only.

The Inputs

IEM calls the inputs app configurations. IEM shows one row per input under Configuration, on the install screen and under Update configuration. To open a row, click the row. An open row shows the description of the input and the control for the content.

IEM has two designs. This reference uses the names of the new design, as in the tutorial.

Input Control Product Purpose

Configuration_as_text

Text editor that IEM fills

Both

Small changes and experiments

Configuration_as_zip_archive

File upload

Both

A ZIP archive that holds the whole configuration (The ZIP Archive)

License_file

File upload

Licensed

A license file. An empty file removes the license (The License).

Every input is marked as secure, so IEM stores the input encrypted. According to the Siemens documentation, secure does not cover the transmission to the device or the storage on the device.

The Names of the Inputs

Identify an input by its name. IEM orders the inputs by an internal ID that changes with every version of the application. The order therefore differs between versions.

An Input Needs a Selected Check Box

IEM sends an input only if you select the check box of the input. The install screen and Update configuration behave in the same way:

  • When the screen opens, no check box is selected.

  • You cannot select the check box of a file upload before you attach a file. After you attach a file, select the check box. IEM does not select the check box for you.

  • The text input has its own check box. If the check box is not selected, IEM writes no text to the device.

  • The screen does not keep the selections of the previous update.

  • The button Install or Update shows the number of selected inputs. Update is available only if at least one check box is selected.

The Text in the Editor

The text in the editor belongs to IEM, not to the device. The editor shows an example configuration that IEM keeps as the template of the text input. The editor does not show the active configuration on the device.

The example starts with a notice of three lines:

# THIS IS AN EXAMPLE CONFIGURATION for config.xml.
# TO USE IT, YOU MUST EDIT IT AND DELETE THESE LINES.
# IF YOU DO NOT DELETE THESE LINES, IT WILL BE IGNORED.

To send the text, edit the text and delete every line of the notice. The first character of the text decides what the helper does with the text:

The Text Starts With What the Helper Does

<

Installs the text as config.xml. The text also replaces the config.xml of a ZIP archive that you send together with the text (How the Helper Applies Uploads).

#

Ignores the text. The text still starts with the notice, so a selected check box without an edit changes nothing.

Another character, or the text is empty

Rejects the batch (How the Helper Applies Uploads)

The description of the text input in IEM ends with the release whose example the editor shows, for example, "Default field text is for release 2026.16.11."

The ZIP Archive

A ZIP archive holds the whole configuration. The helper accepts only the following files from a ZIP archive:

Path in the ZIP Archive Destination Notes

config.xml

/opt/hivemq/conf/config.xml

Required, unless the text arrives in the same batch (How the Helper Applies Uploads)

logback.xml

/opt/hivemq/conf/logback.xml

cert/<file name>

/opt/hivemq/conf/cert/<file name>

One level only. Any file name.

fragment/<file name>

/opt/hivemq/conf/fragment/<file name>

One level only. A piece of configuration that config.xml includes (Write config.xml).

pulsetoken/tokenbase64.jwt

/opt/hivemq/data/pulsetoken/tokenbase64.jwt

The activation token for the HiveMQ Platform (licensed product)

The following rules apply to a ZIP archive:

  • The paths are exact. config.xml must be at the top level of the ZIP archive, not in a folder. If you compress a folder, the content is one level down, and the helper rejects the ZIP archive.

  • The helper skips other files. The helper installs only the files in the table and writes one WARNING line per skipped file to the helper log. The helper still applies the rest of the ZIP archive.

  • The helper never accepts a license from a ZIP archive. The helper skips a file with the suffix .edgelic and every file in a license folder, at every position in the ZIP archive. Send a license through License_file.

  • The helper skips file names that start with a dot. The helper also skips folders below cert/ and below fragment/.

  • The helper skips the entries that archive tools add, without a warning: __MACOSX/, .DS_Store, and Thumbs.db.

  • The helper rejects a ZIP archive with none of the accepted files, because such a ZIP archive changes nothing.

  • The helper rejects a ZIP archive in which an accepted file is encrypted or is a symbolic link.

  • The names are case-sensitive. The helper skips Config.xml and a file in Cert/.

  • The helper rejects an upload that exceeds a size limit.

Upload Limit

A ZIP archive, as uploaded

5 MB

The accepted files of one ZIP archive, unpacked, in total

20 MB

The text

20 MB

A license file

1 MB

Files that the helper skips do not count toward the 20 MB. The helper has no limit per file beyond the total.

What a ZIP Archive Removes

After the helper applies a ZIP archive, the device holds what the ZIP archive contains, plus the license:

  • The helper removes every file in cert/ and in fragment/ that the ZIP archive does not contain.

  • If the ZIP archive contains no activation token, the helper removes the activation token.

  • If the ZIP archive contains no logback.xml, the helper installs the shipped logback.xml (Paths, Volumes, and Settings).

  • The helper keeps the license, because the license has its own input.

To change one file, send the whole ZIP archive again with the changed file in it. If you leave out a file by mistake, the helper removes the file, and the helper log names every removed file (The Status File and the Logs). To restore the file, send the whole ZIP archive again.

How the Helper Applies Uploads

A Batch

The device writes each input into a separate folder. All uploads that are in the folders when the helper reads the folders are one batch. The helper applies a batch as a whole or rejects the batch as a whole.

When the Helper Applies a Batch

The helper treats a batch as complete when nothing in the upload folders changes for 30 seconds.

The helper has two phases. The start phase runs before HiveMQ Edge starts. The watch phase runs while HiveMQ Edge runs.

Situation Phase of the Helper That Applies the Batch

Installation, or update with Restart application after update selected

The start phase, before HiveMQ Edge starts

Update with Restart application after update not selected

The watch phase, while HiveMQ Edge runs

The Text and a ZIP Archive Together

If a batch holds the text and a ZIP archive, the helper applies the ZIP archive first and then installs the text as config.xml. The helper logs the following line:

the text and a zip arrived together: the zip is applied first, then the text as config.xml

The text replaces the config.xml of the ZIP archive, so the ZIP archive can lack config.xml in such a batch. A text that still starts with the notice of the example does not count. The helper ignores that text (The Inputs), and the ZIP archive must then contain config.xml. A text that starts with neither < nor # causes the helper to reject the batch, and the ZIP archive with it. The helper applies a license in the batch together with the other uploads. The helper rejects a license in a rejected batch together with the batch.

What Each Input Does

Input Installs Removes

ZIP archive

Every accepted file that the ZIP archive contains. If the ZIP archive contains no logback.xml, the shipped logback.xml.

What the ZIP archive does not contain (The ZIP Archive)

Text

config.xml

Nothing

License

The license file

Every other *.edgelic file in the license folder

License, empty file

Nothing

Every *.edgelic file in the license folder

What the Helper Tests

Before the helper changes anything, the helper tests the following conditions:

  • Each upload is within its size limit (The ZIP Archive).

  • A ZIP archive is readable as a ZIP archive.

  • No accepted file in a ZIP archive is encrypted or is a symbolic link.

  • A ZIP archive unpacks to no more than the limit.

  • A ZIP archive contains at least one accepted file.

  • A ZIP archive contains config.xml, unless an edited text arrives in the same batch.

  • The text starts with < or with # (The Inputs).

  • The name of a license file that is not empty has the suffix .edgelic.

What the Helper Does Not Test

Apart from the first character of the text, the helper does not check the content of a file:

  • The helper does not parse config.xml or logback.xml.

  • The helper does not test that config.xml and logback.xml are XML.

  • The helper does not test that logback.xml, or the config.xml of a ZIP archive, has content.

  • The helper does not check the content of a key store, a fragment, or the activation token.

HiveMQ Edge decides whether a file is usable, and says so in the HiveMQ Edge log (The Status File and the Logs). A config.xml that includes fragments is not necessarily XML before HiveMQ Edge inserts the fragments.

"Applied" therefore means that the files are on the device.

When a config.xml That HiveMQ Edge Cannot Use Arrives What Happens

Without a restart, while HiveMQ Edge runs

The helper installs the file and reports the batch as applied. Within about a minute, HiveMQ Edge rejects the file, logs Configuration reload rejected, and keeps the active configuration. The file stays on the volume.

With a restart, at an installation, or at a later start

HiveMQ Edge does not run with the file. Send a corrected configuration with a restart.

Check a configuration before you send the configuration (Write config.xml).

A Rejected Batch

If a batch fails a test, the helper does the following:

  • The helper changes nothing.

  • The helper deletes the uploads of the batch.

  • The helper writes one line that starts with REJECTED per fault to the helper log.

  • The helper writes a status file whose name starts with REJECTED (The Status File and the Logs).

Rejected Batch HiveMQ Edge

An update

Continues to run, or starts, with the active configuration

An installation

Does not start, because HiveMQ Edge has no configuration to keep. IEM reports the installation as failed.

An installation is the first start on a new configuration volume. After an installation has its configuration, every later rejection is a rejected update and does not stop HiveMQ Edge.

IEM reports an update job as completed when the files are on the device. The helper processes the files after that moment. IEM reports the job as completed even if the helper rejects the files. For an installation, IEM waits until the application starts. IEM therefore reports a rejected installation as failed.

The status Running of the application in IEM means that the container of HiveMQ Edge runs. It does not mean that HiveMQ Edge works correctly. If HiveMQ Edge cannot start with a configuration, IEM still shows Running while the device starts HiveMQ Edge again and again. After each update, open the Console.

A Rejected Installation

The helper writes the REJECTED lines and the status file REJECTED_INSTALL_AT_<time>_README.txt. The helper then logs the installation was rejected; ending with an error so that the device reports it as failed and ends with an error. The helper does not wait for a corrected input. HiveMQ Edge never starts.

Look for the result in IEM first:

  • The install job shows Executing for several minutes. During that time, you cannot correct anything.

  • The job then changes to Failed, typically with the message "Unable to start application".

  • Sometimes, the device does not list the application during the attempt or afterward. In that case, you cannot read the status file or the helper log on the device.

The cause of the message is an upload that the helper rejects.

To recover, do the following:

  1. In IEM, select Job Status in the menu on the left.

  2. On the failed install job, click Rollback.

  3. Wait for the message "Rollback completed for failed install job."

  4. Install the application again with a corrected upload, or with none.

Without the rollback, IEM skips a new installation of the same version. The message is "Installation job already exists in 'failed' state for 'HiveMQ Edge' version - '', please rollback old job and submit again". You cannot use Update configuration instead, because IEM does not offer Update configuration for an application whose installation is not finished.

The rollback takes a few minutes. A failed installation followed by a rollback removes the volumes of the application. A later installation therefore starts on new volumes.

The Helper Deletes Each Processed Upload

The helper deletes each upload after the helper processes the upload. The device writes an input only when you send the input. The device does not write an input again at a restart or at an update to a new version. The volumes hold the active files.

Interruptions

The helper replaces each file in one step, so HiveMQ Edge never reads a file that is half written. The helper installs key stores and fragments before config.xml. If the application stops in the middle of a batch, the helper finishes that batch at the next start.

A New Configuration Volume

At the first start on a configuration volume, the helper installs the shipped config.xml. The helper does so before the helper applies an upload. The helper installs the shipped config.xml only once per volume.

Paths, Volumes, and Settings

Volumes

The volume names are fixed. The names do not depend on the product, so the standard product and the licensed product use the same three volumes.

Volume Mount Point Contents

hivemq_edge_m7u1h0a0_configuration

/opt/hivemq/conf

config.xml, logback.xml, cert/, fragment/, license/

hivemq_edge_m7u1h0a0_data

/opt/hivemq/data

Queues, retained messages, MQTT persistence, pulsetoken/

hivemq_edge_m7u1h0a0_helper_state

/helper/state (helper only)

The status file, apply.log, and the batch that the helper processes

All three volumes remain at a restart and at an update to a new version. For an update from a version before 2026.16, see Update to a New Version. If you uninstall the application, the device removes all three volumes. A failed installation followed by a rollback also removes all three volumes (How the Helper Applies Uploads).

The web interface of the device lists every file on the three volumes, with a download button per file. To get the active configuration, download config.xml from the volume hivemq_edge_m7u1h0a0_configuration.

Anyone with access to the web interface of the device can download config.xml and the key stores. config.xml contains the passwords of the key stores.

Paths inside the HiveMQ Edge Container

Path Persistent Contents

/opt/hivemq/conf/config.xml

Yes

The active configuration

/opt/hivemq/conf/logback.xml

Yes

The active logging configuration

/opt/hivemq/conf/cert/

Yes

Key stores and trust stores

/opt/hivemq/conf/fragment/

Yes

Fragments

/opt/hivemq/conf/license/

Yes

The license (licensed product)

/opt/hivemq/data/

Yes

Queues, persistence, pulsetoken/tokenbase64.jwt

/opt/hivemq/log/

No

Log files. A new container starts with an empty log folder.

/opt/hivemq/modules/

Part of the image

Commercial modules

Every file that you supply is below /opt/hivemq/conf, except the activation token. HiveMQ Edge expects the activation token in the data folder.

Settings of the HiveMQ Edge Container

Variable Value Effect

HIVEMQ_CONFIG_WRITEABLE

false

The Console cannot write config.xml

HIVEMQ_LICENSE_FOLDER

/opt/hivemq/conf/license

HiveMQ Edge reads the license from the persistent volume

HIVEMQ_CONFIG_REFRESHINTERVAL

60000

Every 60 seconds, HiveMQ Edge checks whether config.xml changed

What HiveMQ Edge Does with a Changed File

Change What HiveMQ Edge Does

An adapter or a bridge that you add, change, or remove

Applies the change while HiveMQ Edge runs. No restart.

Another change to config.xml, for example, to an MQTT listener or to <admin-api>

Logs Restarting because new config can't be hot-reloaded and shuts down. The device starts HiveMQ Edge again with the new file.

A config.xml that HiveMQ Edge cannot use

Logs Configuration reload rejected because the new configuration is invalid; keeping the previously applied configuration. HiveMQ Edge continues to run and continues to check for a corrected file.

A fragment that config.xml includes, changed alone

Logs Restarting because a required file was updated and shuts down. The device starts HiveMQ Edge again with the new fragment.

HiveMQ Edge reads key stores and trust stores when HiveMQ Edge starts. If a bridge uses a key store or a trust store that changes, HiveMQ Edge can log Restarting because a required file was updated and shut down. To make the restart certain, send a key store or a trust store with a restart.

HiveMQ Edge reads the activation token for the HiveMQ Platform only once, when HiveMQ Edge starts.

The Shipped logback.xml

The shipped logback.xml is the logback.xml of the HiveMQ Edge image plus one line:

<logger name="com.hivemq.configuration.reader.ConfigFileWatcher" level="ERROR"/>

Without the line, HiveMQ Edge writes the warning No fragment found, checking the full config, only used for testing at every check, 1,440 times a day. The line keeps the errors of the watcher and drops the other warnings of the watcher. A logback.xml that you send does not have the line unless you add the line.

At the start, the helper replaces a logback.xml that is identical to the logback.xml of the HiveMQ Edge image with the shipped logback.xml. The helper leaves every other logback.xml unchanged.

Install the Application

Get the Application

You get the application from the Siemens Digital Exchange, the marketplace for Industrial Edge.

Product App ID Name in IEM

Standard

rTqkZNxShlhbNkwnCpxqVbDKosrB5Lkh

HiveMQ Edge

Licensed

iYMYtlMtWwWBIHtgHbuMeANB0GzcoNVx

HiveMQ Edge Licensed

Install on a Device

  1. In IEM, select Applications and then Device in the menu on the left.

  2. Click the tile of the product, and click Install on device.

  3. Select the check box of the device.

  4. Under Configuration, supply the configuration, or send nothing. To send a ZIP archive, open the row Configuration_as_zip_archive, click Browse, and select the ZIP archive. To send the text, open the row Configuration_as_text, edit the text in the editor, and delete every line of the notice at the top. Then select the check box of each row that you send.

  5. Click Install.

The configuration with which HiveMQ Edge starts depends on what you send:

Sent at the Installation Result Status File

Nothing

The shipped config.xml

APPLIED_INSTALL_AT_...

The text

The text as config.xml

APPLIED_INSTALL_AT_.... If the text equals the shipped config.xml, UNCHANGED_INSTALL_AT_....

The text, with the notice of the example still at the top

The shipped config.xml. The helper ignores the text (The Inputs).

UNCHANGED_INSTALL_AT_...

A ZIP archive

The config.xml, the key stores, and the fragments of the ZIP archive

APPLIED_INSTALL_AT_...

The text and a ZIP archive

The key stores and the fragments of the ZIP archive, and the text as config.xml

APPLIED_INSTALL_AT_...

A faulty upload

HiveMQ Edge does not start, and IEM reports the installation as failed (How the Helper Applies Uploads)

REJECTED_INSTALL_AT_..._README. In some cases, you cannot read the file on the device.

The shipped config.xml has one MQTT listener on port 1883, the Console on port 8080 with the login closed, and no adapter or bridge.

You cannot install the two products side by side on one device. Both products name their container hivemq-edge and publish the same ports.

The standard product and the licensed product use the same volume names. To move from one product to the other, you uninstall the first product. The device then removes the volumes (Paths, Volumes, and Settings), so the second product starts on new volumes.

Change the Configuration after the Installation

  1. In IEM, open the page of the application: select Applications and then Device, and click the tile of the product.

  2. Click the three dots at the end of the row of the device. Then click Update configuration.

  3. To send a ZIP archive, open the row Configuration_as_zip_archive, click Browse, and select the ZIP archive. To send the text, open the row Configuration_as_text, edit the text in the editor, and delete every line of the notice at the top. Then select the check box of each row that you send.

  4. Select Restart application after update, or leave the check box not selected.

  5. Click Update.

  6. After a few minutes, read the name of the status file on the device (The Status File and the Logs).

Restart application after update Effect

Selected

The device writes the files, stops the application, and starts the application again. The helper starts first, and HiveMQ Edge starts when the helper is ready. The time from Update to a started HiveMQ Edge is about one to two minutes.

Not selected

The helper applies the batch while HiveMQ Edge runs, within a few minutes after Update. After the helper applies the batch, HiveMQ Edge notices a new config.xml within about a minute (Paths, Volumes, and Settings). HiveMQ Edge does not notice a new activation token. For a new key store or a new trust store, see Paths, Volumes, and Settings.

In this reference, "with a restart" means an update with Restart application after update selected.

After an update without a restart, the helper log and the status file name the changed files in two groups. The first group holds the files that HiveMQ Edge notices by itself. The second group holds the files that HiveMQ Edge reads only at the start. For the second group, restart the application from IEM:

  1. Select Devices, and open the page of the device.

  2. Click the three dots at the end of the row of the application.

  3. Click Restart.

A license appears in neither group, although some licensed features, for example, Data Hub, start only after a restart (The License).

The following table shows the input for each change. Every ZIP archive holds the whole configuration, including the files that do not change (The ZIP Archive).

Change Input Restart Needed

Replace one certificate

ZIP archive with the new file as cert/<same file name>

Yes

Add, change, or remove an adapter or a bridge

ZIP archive with the changed config.xml, or with the changed fragment that holds the adapter or the bridge

No. A changed fragment makes HiveMQ Edge shut down, and the device starts HiveMQ Edge again (Paths, Volumes, and Settings).

Move a device to a different site configuration

ZIP archive

Yes, if a key store or the activation token changes

Remove a key store or a fragment

ZIP archive without the key store or the fragment

For a key store, yes

Try a setting

Text

No

Supply or replace the activation token for the HiveMQ Platform

ZIP archive with pulsetoken/tokenbase64.jwt

Yes

Remove the activation token

ZIP archive without an activation token

Yes

Supply or replace the license

License input

Yes, for some licensed features, for example, Data Hub

The text editor in IEM does not show the active configuration. The editor shows the example that IEM keeps (The Inputs). IEM has no knowledge of a config.xml that arrived in a ZIP archive. If you send an edited text, the text that you send replaces config.xml exactly.

Write config.xml

config.xml is one XML document.

Listeners

The MQTT listener uses port 1883 inside the container.

<mqtt-listeners>
    <tcp-listener>
        <port>1883</port>
        <bind-address>0.0.0.0</bind-address>
    </tcp-listener>
</mqtt-listeners>

The Console and the Login

The shipped configuration contains no user and closes the login:

<admin-api>
    <listeners>
        <http-listener>
            <port>8080</port>
            <bind-address>0.0.0.0</bind-address>
        </http-listener>
    </listeners>
    <username-authentication>
        <enabled>false</enabled>
    </username-authentication>
</admin-api>
Every config.xml that you send must contain <username-authentication>. Without that element, HiveMQ Edge opens the built-in account admin, whose password is publicly known, within about a minute, even if you select no restart. Anyone who logs in with the account can read the passwords of your key stores.

To keep the login to the Console closed, keep <enabled>false</enabled>. If <enabled> is false, the built-in account is closed.

The config.xml of version 2025.18 of the application defines the user admin with the publicly known password. If you send a configuration from that version, you must remove that user. A configuration from an older version of the application can lack <username-authentication>.

To open the login to the Console, set <enabled> to true and add a user source directly inside <admin-api>, beside <username-authentication>. You must not use the user name and the password of the built-in account for your own user. The user source is a <users> element or an <ldap> element:

<users>
    <user>
        <username>your-admin</username>
        <password>a-strong-password</password>
        <roles><role>admin</role></roles>
    </user>
</users>

If <enabled> is true and the configuration has no user source, HiveMQ Edge does not run.

HiveMQ Edge logs that <users> is deprecated in favor of <username-roles-source>. Use <users>. HiveMQ Edge 2026.16 rejects <username-roles-source> at the schema validation.

Protocol Adapters

Each machine or group of machines has one block. The block contains the connection, the tags to read, and the MQTT topic for each tag.

Bridges

The element for bridges is <mqtt-bridges>. The address, the connection settings, and the Transport Layer Security (TLS) block are inside <remote-broker>:

<mqtt-bridges>
    <mqtt-bridge>
        <id>to-central</id>
        <remote-broker>
            <host>broker.example.com</host>
            <port>8883</port>
            <mqtt>
                <client-id>hivemq-edge-plant-4</client-id>
                <clean-start>true</clean-start>
                <session-expiry>3600</session-expiry>
                <keep-alive>60</keep-alive>
            </mqtt>
            <tls>
                <enabled>true</enabled>
                <keystore>
                    <path>/opt/hivemq/conf/cert/edge-keystore.p12</path>
                    <password>...</password>
                    <private-key-password>...</private-key-password>
                </keystore>
                <truststore>
                    <path>/opt/hivemq/conf/cert/plant-truststore.p12</path>
                    <password>...</password>
                </truststore>
            </tls>
        </remote-broker>
        <forwarded-topics>
            <forwarded-topic>
                <filters>
                    <mqtt-topic-filter>plant/#</mqtt-topic-filter>
                </filters>
            </forwarded-topic>
        </forwarded-topics>
    </mqtt-bridge>
</mqtt-bridges>

<private-key-password> is required, even if the value equals the key store password.

MQTT Persistence

<persistence><mode>file-native</mode></persistence> needs a license. Without a license, HiveMQ Edge does not run, and the device restarts HiveMQ Edge in a loop.

Fragments

A fragment is a file with a piece of the configuration. config.xml includes the fragment with a placeholder. Before HiveMQ Edge reads the configuration, HiveMQ Edge replaces the placeholder with the text of the file:

<protocol-adapters>
    ${FRAGMENT:/opt/hivemq/conf/fragment/line-4.xml}
    ${FRAGMENT:/opt/hivemq/conf/fragment/line-5.xml}
</protocol-adapters>

The following rules apply to fragments:

  • Put a fragment into a ZIP archive as fragment/<file name>. The helper installs the fragment at /opt/hivemq/conf/fragment/<file name>. The placeholder names that full path.

  • Write one placeholder per line. Two placeholders on one line do not work.

  • A fragment can contain placeholders for environment variables. HiveMQ Edge inserts fragments first.

  • If the file of a placeholder is missing, HiveMQ Edge rejects the configuration. The helper does not notice the missing file, so the name of the status file still starts with APPLIED. If HiveMQ Edge runs, HiveMQ Edge keeps the active configuration. At the next start, HiveMQ Edge does not run. To recover, send a ZIP archive that contains every fragment that config.xml names, with a restart.

  • The helper installs fragments before config.xml.

  • A ZIP archive removes the fragments that the ZIP archive does not contain (The ZIP Archive).

Check a Configuration before the Upload

Apart from the first character of the text, the helper does not check the content of a file. HiveMQ Edge checks config.xml against the HiveMQ Edge schema and rejects the file on a violation. The schema is in the image:

docker run --rm --entrypoint sh hivemq/hivemq-edge:2026.16 -c 'cat /opt/hivemq/conf/config.xsd' > /tmp/config.xsd
xmllint --noout --schema /tmp/config.xsd config.xml

The schema accepts any content inside <protocol-adapters>. HiveMQ Edge checks adapters at runtime. An adapter block with errors therefore passes xmllint. HiveMQ Edge can still reject the whole configuration because of such a block. To check a config.xml with fragment placeholders, first insert the fragments.

For the full description of the configuration, see the HiveMQ Edge documentation.

Certificates

HiveMQ Edge reads key stores and trust stores as files from a path. HiveMQ Edge has no upload interface for key stores and trust stores, on any platform.

  1. Produce a key store with the certificate and the private key of HiveMQ Edge. Produce a trust store with the certificate authority of the broker. Use the JKS format or the PKCS#12 format.

  2. Put the key store and the trust store into a ZIP archive under cert/.

  3. Name the key store and the trust store in config.xml as /opt/hivemq/conf/cert/<file name>.

Replace a Certificate

Send the ZIP archive again with the new file under the same name, with a restart. The new key store must have the passwords that config.xml names. If the passwords differ, change config.xml in the same ZIP archive.

Remove a Certificate

A ZIP archive removes every file in cert/ that the ZIP archive does not contain, key stores and trust stores alike (The ZIP Archive).

The License

Only the licensed product has a license input.

  • The file name must have the suffix .edgelic. IEM keeps the name of the uploaded file, so, if necessary, rename the file before the upload. The helper rejects every other name, and logs the reason.

  • A license file can be up to 1 MB. A license is a few kilobytes.

  • A new license replaces the previous license.

  • An empty file removes the license. The name of the empty file does not matter. Send the empty file with a restart.

  • Send a license with a restart. HiveMQ Edge watches the license folder and recognizes a new license immediately (Using valid license). Some licensed features, for example, Data Hub, start only at the next start of HiveMQ Edge.

  • A ZIP archive does not remove the license (The ZIP Archive).

  • The helper never accepts a license from a ZIP archive.

Update to a New Version

Get the new version from the Siemens Digital Exchange (Install the Application), and install the new version over the version that runs.

  • You cannot install the same version twice on one device. IEM reports the job as skipped.

  • The volumes remain. The volumes hold the following items:

    • The configuration

    • The certificates

    • The license

    • The message queues

    • The enrollment with the HiveMQ Platform

  • The device does not write the inputs again. The helper finds no upload and leaves the volumes unchanged. The status file stays unchanged.

  • logback.xml on the volume stays the logback.xml of the previous version.

  • According to the Siemens documentation, IEM deletes stored inputs that the new version does not declare.

Update from a Version before 2026.16

An update from a version before 2026.16 starts on empty volumes. Versions before 2026.16 used volumes with other names (hivemq_configuration, hivemq_data), and the device does not rename a volume. The message queues and the enrollment with the HiveMQ Platform do not carry over. After such an update, send the configuration again as a ZIP archive.

The Console

The Console is reachable in two ways:

  • Through the reverse proxy of the device, at the entry of the application in the web interface of the device

  • Directly on port 58080

The Console shows the state of adapters, tags, and bridges. The Console cannot change the configuration, because HIVEMQ_CONFIG_WRITEABLE is false. The restriction is deliberate. You supply the entire configuration as one unit through Industrial Edge Management. Industrial Edge Management is therefore the single source of truth for the configuration. A second place to change the configuration makes it unclear which configuration is the actual one. The result is lost changes, or older changes that HiveMQ Edge applies again. The import of device tags is the one exception: the import changes the configuration. The exception is a defect of HiveMQ Edge.

The login to the Console is closed until you send a configuration that opens the login (Write config.xml).

Ports

Container Port Port on the Device Purpose

1883

51883

MQTT

8883

58883

MQTT over TLS, if the configuration defines such a listener

8080

58080, and through the reverse proxy

Console and REST API

The package attaches HiveMQ Edge to the proxy-redirect network of the device. The reverse proxy uses that network, and other applications can join that network.

Storage and Memory

The package limits memory: 2,000 MB for HiveMQ Edge and 100 MB for the helper. The size limits for uploads (The ZIP Archive) follow from the 100 MB of the helper.

The application declares no storage limit. The device sets the limit. The default limits of a device are as follows:

"Limits": {
  "MaxInstalledApplications": 20,
  "MaxRunningApplications": 10,
  "MaxMemoryUsageInGB": 8.0,
  "MaxStorageUsageInGB": 20.0,
  "MaxCpuUsagePercentage": 100
}

The Status File and the Logs

The status file and the helper log are on the volume of the helper. The web interface of the device lists the volumes of the application under Management. The list shows every file by name, with a download button per file. The files are under hivemq_edge_m7u1h0a0_helper_state/_data/.

To open the web interface of the device, do the following:

  1. In IEM, select Devices, and open the page of the device.

  2. Click Enable remote access.

  3. Click Remote connect. If Remote connect reports that no tunnel exists, click Disable remote access, click Enable remote access again, and then click Remote connect.

The Status File

The name of the status file is the result of the last installation or update. You read the result in the list of files and do not need to download a file. After the first start of the application, the volume holds exactly one status file. The helper writes the new status file and then deletes the older ones.

<result>_<operation>_AT_<time>[_README].txt
Part Values

Result

APPLIED: The helper applied the batch. UNCHANGED: Every file of the batch was already in place. REJECTED: The helper rejected the batch and changed nothing.

Operation

INSTALL: The first batch on a new configuration volume. LAST_UPDATE: Every later batch.

Time

Coordinated Universal Time (UTC), in the format 20261112T184500Z

_README

Present on REJECTED only. The file says what was wrong and what to do.

Name Meaning

APPLIED_INSTALL_AT_<time>.txt

The installation has its configuration, and the helper let HiveMQ Edge start. The helper also writes this name for an installation without an input.

UNCHANGED_INSTALL_AT_<time>.txt

The input of the installation was equal to the files already in place, for example, a text equal to the shipped config.xml. The helper let HiveMQ Edge start.

REJECTED_INSTALL_AT_<time>_README.txt

The helper rejected the installation. HiveMQ Edge does not start, and IEM reports the installation as failed (How the Helper Applies Uploads). In some cases, you cannot read this file on the device.

APPLIED_LAST_UPDATE_AT_<time>.txt

The helper applied the last update

UNCHANGED_LAST_UPDATE_AT_<time>.txt

The last update changed nothing, for example, a text that still starts with the notice of the example

REJECTED_LAST_UPDATE_AT_<time>_README.txt

The helper rejected the last update. HiveMQ Edge keeps the active configuration.

The text of the status file names the operation, the result, and the time, and then repeats the log lines of the batch. The following example shows a rejected installation:

HiveMQ Edge on Siemens Industrial Edge: result of the installation
Result: REJECTED
Time:   2026-11-12 17:56:20 UTC

batch: zip='site.zip'
REJECTED zip upload 'site.zip': has no config.xml; a zip holds the whole configuration and must bring one
the batch was rejected as a whole; nothing was changed
HiveMQ Edge is not started, and the device reports the installation as failed ("Unable to start application"). In Industrial Edge Management, roll back the failed install job, then install again with a corrected upload.

The full history is in apply.log, beside this file.

APPLIED says that the files are on the device. APPLIED does not say that HiveMQ Edge accepted the files (How the Helper Applies Uploads).

A restart or an update to a new version without an upload leaves the status file unchanged.

The Helper Log

The helper writes every line to the container log of the helper and to apply.log. Each line has a UTC time and the phase, [start] or [watch].

Line Meaning

volumes and upload folders belong to user 10000; continuing as that user

Start of the helper

new configuration volume: installed the packaged config.xml

First start on this volume

the installation was rejected; ending with an error so that the device reports it as failed

Start phase: The helper rejected an installation, now or at an earlier start. The helper ends with an error.

uploads are still arriving; waiting until the device has finished writing

The helper waits for 30 seconds without a change

batch: text='...', zip='...'

The uploads of this batch, by input

the text still starts with the notice of the example configuration and was ignored; to use the text, edit it and delete every line of the notice

The text starts with # (The Inputs)

text upload: the text starts neither with '<', as a configuration does, nor with '#', as the notice of the example does; if you deleted the notice in part, delete every line of it

The text starts with another character, or the text is empty (The Inputs). The helper rejects the batch.

the text and a zip arrived together: the zip is applied first, then the text as config.xml

The batch holds the text and a ZIP archive (How the Helper Applies Uploads)

license upload '<name>': the file is empty, so the license is removed

The license file arrived empty. The helper removes the license (The License).

installed <file> / removed <file> / unchanged <file>

The effect of the batch on one file

WARNING ... skipped '<path>'; it is not one of the accepted files

A file in a ZIP archive that is not an accepted file

WARNING ... skipped '<path>'; a license is not accepted in a zip

A license in a ZIP archive

REJECTED <reason>

One fault. The helper rejects the batch. The next table lists the reasons.

the batch was rejected as a whole; nothing was changed

Follows the REJECTED lines

HiveMQ Edge keeps the configuration it had. Correct the upload and send it again.

Follows a rejected update

HiveMQ Edge is not started, and the device reports the installation as failed ("Unable to start application"). In Industrial Edge Management, roll back the failed install job, then install again with a corrected upload.

Follows a rejected installation

the batch was applied / the batch changed nothing

End of a batch

HiveMQ Edge notices these by itself within about a minute, and restarts itself if it cannot apply them while it runs: ...

Watch phase only: config.xml, fragments, and a logback.xml that says scan="true"

HiveMQ Edge reads these only when it starts; restart the app for them to take effect: ...

Watch phase only: Key stores, the activation token (installed or removed), and a logback.xml without scan="true"

logback.xml was HiveMQ Edge's own; installed the packaged one

Start phase: The volume held the unchanged logback.xml of the HiveMQ Edge image

ready; HiveMQ Edge can start

End of the start phase

watching the upload folders

Start of the watch phase

finishing a round that was interrupted

The helper finishes a batch that an interruption stopped

<input>: '<name>' was superseded by a newer upload

Two uploads were present for one input, and the helper used the newer upload

installed the packaged <file>; none was present

config.xml or logback.xml was missing at the end of the start phase

could not write the status file <name>: <error>

The helper was unable to replace the status file

round failed, will retry: <error>

Watch phase only: An error such as a full disk

The following table lists the reasons after REJECTED:

Reason Cause

<input> upload '<name>': is <size>, more than the <limit> allowed

An upload over its size limit

... is not a readable zip file (...)

Not a ZIP archive, or a damaged ZIP archive

... entry '<path>' is encrypted / ... is a symbolic link

An entry that the helper does not accept

... its accepted files unpack to <size>, more than the 20 MB allowed

The unpacked total is over the limit

... entry '<path>' cannot be unpacked (...)

A damaged entry, or a ZIP archive that contains more than the ZIP archive declares

... contains none of the accepted files (...)

No accepted file, usually because the files are one level down

... has no config.xml; a zip holds the whole configuration and must bring one

A ZIP archive without config.xml, in a batch without the text

license upload '<name>': the file name must end in .edgelic

A license with a wrong file name

If you download the same file twice from the web interface of the device, the browser can return a stale copy. If a file looks unchanged, reload the page without the cache. The stale copy does not affect the name of the status file, because the name is part of the file list.

The Container Logs

The device keeps the output of both containers. The output of the HiveMQ Edge container is the HiveMQ Edge log. To download the container logs, do the following:

  1. In the web interface of the device, open the Apps view.

  2. Open the menu on the HiveMQ Edge tile.

  3. Click Download Logs.

The device delivers a ZIP archive with one folder per container. Each folder holds the standard output and the standard error output of the container.

IEM offers log archives of the device. In IEM, select Devices, open the page of the device, and select the tab Log files. The tab lists one archive per day. According to the Siemens documentation, you need the DeviceOwner role, or you must be the creator of the device.

Troubleshooting

A Change Had No Effect

Read the name of the status file:

  • REJECTED_...: The helper did not apply the batch. The status file names the fault.

  • APPLIED_LAST_UPDATE_..., after an update without a restart: The files are in place. If the batch held a key store, an activation token, or a license, restart the application. If the batch held config.xml or a fragment, read the HiveMQ Edge log (The Status File and the Logs). Configuration reload rejected means that HiveMQ Edge rejected the configuration and runs with the active configuration.

  • UNCHANGED_...: The files that you sent equal the files on the device. Or you sent the text with the notice still at the top, and the application ignored the text.

  • The time in the name is older than the update: The check box of the input was not selected, or the update is not on the device yet. The helper processes a batch 30 seconds after the last file arrived.

The Helper Rejected a ZIP Archive with "contains none of the accepted files"

The files are not at the top level of the ZIP archive. Compress the files, not the folder that holds the files.

The Helper Rejected an Upload with "more than the …​ allowed"

The upload is over its size limit (The ZIP Archive).

An Installation Stays at "Executing" and Then Fails with "Unable to start application"

The install job stays at Executing for several minutes before the job fails. The helper rejected the installation because of a faulty upload. In IEM, select Job Status, and click Rollback on the failed install job. Then install again with a corrected upload, or with none (How the Helper Applies Uploads).

IEM Skips a New Installation with "Installation job already exists in 'failed' state"

The failed install job has no rollback yet. Click Rollback on the failed install job, and then install again.

An Update Job Fails, and IEM Skips Every Later Update

An update with a restart fails if the helper fails at the start of the application. IEM shows the update job as Failed and the application as Stopped. IEM skips every later update until the failed job has a rollback. In IEM, select Job Status, and click Rollback on the failed update job. The rollback changes nothing on the device. Then send a ZIP archive with the whole configuration, with Restart application after update selected.

The Login to the Console Is Open, or the Configuration Is Not the One That You Sent

If the login is open with the built-in account, the active config.xml lacks <username-authentication> (Write config.xml). A possible cause is a text or a ZIP archive whose config.xml does not contain the element. Send the intended configuration.

The Application Restarts in a Loop

HiveMQ Edge rejects its config.xml. The HiveMQ Edge log names the element and the line. Frequent causes are a schema violation, a missing fragment, and MQTT persistence without a license. Send a corrected configuration with a restart. The helper continues to run during the loop and applies the corrected configuration.

The Application Does Not Start after an Update

If the helper cannot finish its start phase, the helper does not become ready, and HiveMQ Edge does not start. The container log of the helper shows the cause (The Status File and the Logs).

You Cannot Log In to the Console

The login to the Console is closed in the shipped configuration (Write config.xml).

The Console Rejects a Change

HIVEMQ_CONFIG_WRITEABLE is false, so the Console cannot write the configuration (The Console).

The Bridge Does Not Connect with TLS

The causes are as follows:

  • The path in config.xml differs from the file name in the ZIP archive.

  • A password is wrong.

  • The trust store lacks the certificate authority of the broker.

The HiveMQ Edge log shows which cause applies.

A License Has No Effect

The causes are as follows:

  • The file name does not have the suffix .edgelic. The status file names this fault.

  • You sent the license without a restart (The License).

  • The product is the standard product, which has no license input.

HiveMQ Edge Does Not Start after You Sent an Activation Token

HiveMQ Edge cannot use the activation token on the device, or cannot reach the HiveMQ Platform. The log of HiveMQ Edge shows one of the following:

  • "Configured pulse connection string is not valid": The activation token is not valid.

  • "blocking the Edge startup", repeated: HiveMQ Edge waits for the HiveMQ Platform. The HiveMQ Platform is unreachable, or does not accept the activation token.

The device does not restart HiveMQ Edge in either case.

  • If the HiveMQ Platform was unreachable, restart the application when the HiveMQ Platform is reachable.

  • Otherwise, send a ZIP archive with a correct activation token, with a restart.

  • To run HiveMQ Edge without the HiveMQ Platform, send a ZIP archive without an activation token, with a restart.

The ZIP archive must contain every other file that you want to keep (The ZIP Archive). The helper does not check the content of the activation token.

Limitations

  • You make every change per device. No mechanism sends one change to many devices.

  • A ZIP archive replaces the whole configuration. To change one key store or one fragment, you send the whole ZIP archive again.

  • Uploads have size limits (The ZIP Archive).

  • A change to a key store, a trust store, or the activation token takes effect at a restart. Some features of a new license, for example, Data Hub, also start only at a restart.

  • A change to config.xml takes effect without a restart, within about a minute after the helper applies the change.

  • HiveMQ Edge can shut down although you selected no restart. If HiveMQ Edge cannot apply a config.xml change while HiveMQ Edge runs, HiveMQ Edge shuts down, and the device starts HiveMQ Edge again. A changed fragment has the same effect, and so can a changed key store or trust store of a bridge.

  • IEM does not report a rejected update, and the application does not report into IEM. The status file on the device reports a rejected update.

  • Apart from the first character of the text, the helper does not check the content of a file. "Applied" means that the files are on the device. HiveMQ Edge can still reject the files.

  • A rejected installation does not start HiveMQ Edge. IEM reports the installation as failed with "Unable to start application", without the cause, several minutes after you click Install. You must roll back the failed job before a new installation.

  • The application has no high availability. One instance runs per device, with storage on that device.

  • The package runs on x86-64 processors only.

  • You cannot install the same version twice on one device.

  • The two products cannot run on one device at the same time.