Kura Adapter Configuration

The Kura protocol adapter exposes an MQTT topic hierarchy allowing Eclipse Kura™ 3 based gateways to access Eclipse Hono™’s south bound Telemetry, Event and Command & Control APIs.

The adapter is implemented as a Spring Boot 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 Kura 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 Kura 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_KURA_KEYSTOREPATH and the HONO_KURA_KEYSTOREPASSWORD variables in order to load the key & certificate from a password protected key store, or
2. setting the HONO_KURA_KEYPATH and HONO_KURA_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_KURA_PORT variable.

The HONO_KURA_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_KURA_INSECUREPORT to a valid port number, or by
• implicitly configuring the default MQTT port (1883) by simply setting HONO_KURA_INSECUREPORTENABLED to true.

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

The HONO_KURA_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.