MQTT Adapter Configuration

The MQTT protocol adapter exposes an MQTT topic hierarchy for Eclipse Hono™’s south bound Telemetry, Event and Command & Control APIs.

The adapter is implemented as a Quarkus application. It can be run either directly from the command line or by means of starting the corresponding Docker image created from it.

Service Configuration

The following table provides an overview of the configuration variables and corresponding system properties for configuring the MQTT adapter.

The variables only need to be set if the default values do not match your environment.

In addition to the options described in the table above, this component supports the following standard configuration options:

• Common Java VM Options
• Common vert.x Options
• Common Protocol Adapter Options
• Monitoring Options

Port Configuration

The MQTT protocol adapter can be configured to listen for connections on

• a secure port only (default) or
• an insecure port only or
• both a secure and an insecure port (dual port configuration)

The MQTT protocol adapter will fail to start if none of the ports is configured properly.

Secure Port Only

The protocol adapter needs to be configured with a private key and certificate in order to open a TLS secured port.

There are two alternative ways for doing so:

1. either setting the HONO_MQTT_KEYSTOREPATH and the HONO_MQTT_KEYSTOREPASSWORD variables in order to load the key & certificate from a password protected key store, or
2. setting the HONO_MQTT_KEYPATH and HONO_MQTT_CERTPATH variables in order to load the key and certificate from two separate PEM files in PKCS8 format.

When starting up, the protocol adapter will bind a TLS secured socket to the default secure MQTT port 8883. The port number can also be set explicitly using the HONO_MQTT_PORT variable.

The HONO_MQTT_BINDADDRESS variable can be used to specify the network interface that the port should be exposed on. By default the port is bound to the loopback device only, i.e. the port will only be accessible from the local host. Setting this variable to 0.0.0.0 will let the port being bound to all network interfaces (be careful not to expose the port unintentionally to the outside world).

Insecure Port Only

The secure port will mostly be required for production scenarios. However, it might be desirable to expose a non-TLS secured port instead, e.g. for testing purposes. In any case, the non-secure port needs to be explicitly enabled either by

• explicitly setting HONO_MQTT_INSECUREPORT to a valid port number, or by
• implicitly configuring the default MQTT port (1883) by simply setting HONO_MQTT_INSECUREPORTENABLED to true.

The protocol adapter issues a warning on the console if HONO_MQTT_INSECUREPORT is set to the default secure MQTT port (8883).

The HONO_MQTT_INSECUREPORTBINDADDRESS variable can be used to specify the network interface that the port should be exposed on. By default the port is bound to the loopback device only, i.e. the port will only be accessible from the local host. This variable might be used to e.g. expose the non-TLS secured port on a local interface only, thus providing easy access from within the local network, while still requiring encrypted communication when accessed from the outside over public network infrastructure.

Setting this variable to 0.0.0.0 will let the port being bound to all network interfaces (be careful not to expose the port unintentionally to the outside world).

Dual Port

The protocol adapter may be configured to open both a secure and a non-secure port at the same time simply by configuring both ports as described above. For this to work, both ports must be configured to use different port numbers, otherwise startup will fail.

Ephemeral Ports

Both the secure as well as the insecure port numbers may be explicitly set to 0. The protocol adapter will then use arbitrary (unused) port numbers determined by the operating system during startup.

Custom Message Mapping

This protocol adapter supports transformation of messages that have been uploaded by devices before forwarding them to downstream consumers. This message mapping can be used to overwrite the deviceID, add additional properties and change the payload.

The following table provides an overview of the configuration variables and corresponding system properties for configuring the external service endpoint(s) for transforming messages:

Implementation

An implementation of the mapper needs to be provided. Following data will be provided to the mapper:

• HTTP headers:
  • orig_address
  • content-type
  • tenant_id
  • all strings configured during registration
• Body
  • The payload of the message is provided in the body of the mapping request

When the mapper responds successfully(=200), the adapter will map the returning values as follows:

• The header with key device_id will overwrite the current deviceID.
• The remaining HTTP headers will be added to the downstream message as additional properties.
• The returned body will be used to replace the payload.