File Based Device Registry Configuration

The File based Device Registry component provides an exemplary implementation of Eclipse Hono™’s Device Registration, Credentials, Tenant and Device Connection APIs.

Protocol adapters use these APIs to determine a device’s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it.

There is no particular technical reason to implement these three APIs in one component, so for production scenarios there might be up to three different components each implementing one of the APIs.

The Device Registry component also exposes HTTP based resources for managing tenants and the registration information and credentials of devices.

The Device Registry 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 Device Registry.

The variables only need to be set if the default value does 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
• Monitoring Options

Port Configuration

The file based Device Registry supports configuration of both an AMQP based endpoint exposing the Tenant, Device Registration and Credentials APIs as well as an HTTP based endpoint providing resources for managing tenants, registration information and credentials as defined by the Registry Management API. Both endpoints 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 registry will fail to start if none of the ports is configured properly.

The following sections apply to configuring both the AMQP and the HTTP endpoint. The environment variables to use for configuring the HTTP endpoint are the same as the ones for the AMQP endpoint, substituting _AMQP_ with _HTTP_, e.g. HONO_REGISTRY_HTTP_KEYPATH instead of HONO_REGISTRY_AMQP_KEYPATH.

Secure Port Only

The server 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. Setting the HONO_REGISTRY_AMQP_KEYSTOREPATH and the HONO_REGISTRY_AMQP_KEYSTOREPASSWORD variables in order to load the key & certificate from a password protected key store, or
2. setting the HONO_REGISTRY_AMQP_KEYPATH and HONO_REGISTRY_AMQP_CERTPATH variables in order to load the key and certificate from two separate PEM files in PKCS8 format.

When starting up, the server will bind a TLS secured socket to the default secure port (5671 for AMQP and 8443 for HTTP). The port number can also be set explicitly using the HONO_REGISTRY_AMQP_PORT variable.

The HONO_REGISTRY_AMQP_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_REGISTRY_AMQP_INSECUREPORT to a valid port number, or by
• implicitly configuring the default port (5672 for AMQP and 8080 for HTTP) to be used by setting HONO_REGISTRY_AMQP_INSECUREPORTENABLED to true.

The server issues a warning on the console if one of the insecure ports is set to the corresponding default secure port.

The HONO_REGISTRY_AMQP_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

In test setups and some production scenarios Hono server may be configured to open one secure and one insecure port at the same time.

This is achieved by configuring both ports correctly (see above). The server will fail to start if both ports are configured to use the same port number.

Since the secure port may need different visibility in the network setup compared to the secure port, it has its own binding address HONO_REGISTRY_AMQP_INSECUREPORTBINDADDRESS. This can be used to narrow the visibility of the insecure port to a local network e.g., while the secure port may be visible worldwide.

Ephemeral Ports

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

Authentication Service Connection Configuration

The Device Registry requires a connection to an implementation of Hono’s Authentication API in order to authenticate and authorize client requests.

The connection is configured according to the Hono Client Configuration where the ${PREFIX} is set to HONO_AUTH. Since Hono’s Authentication Service does not allow caching of the responses, the cache properties can be ignored.

In addition to the standard client configuration properties, following properties may be set for the connection:

Metrics Configuration

See Monitoring & Tracing Admin Guide for details on how to configure the reporting of metrics.

Device Identities File Format

The Device Registry supports persisting the device identities and their registration information to a JSON file in the local file system. The source repository contains an example configuration which illustrates the file format used. The configuration file’s location is $HONO/services/device-registry-file/src/test/resources/device-identities.json.

Credentials File Format

The Device Registry supports persisting the devices’ credentials to a JSON file in the local file system. The source repository contains an example configuration which illustrates the file format used. The configuration file’s location is $HONO/services/device-registry-file/src/test/resources/credentials.json.

Tenants File Format

The Device Registry supports persisting tenants to a JSON file in the local file system. The source repository contains an example configuration which illustrates the file format used. The configuration file’s location is $HONO/services/device-registry-file/src/test/resources/tenants.json.

Configuring Gateway Devices

The Device Registry supports devices to act on behalf of other devices. This is particularly useful for cases where a device does not connect directly to a Hono protocol adapter but is connected to a gateway component that is usually specific to the device’s communication protocol. It is the gateway component which then connects to a Hono protocol adapter and publishes data on behalf of the device(s). Examples of such a set up include devices using SigFox or LoRa for communication.

In these cases the protocol adapter will authenticate the gateway component instead of the device for which it wants to publish data. In order to verify that the gateway is authorized to publish data on behalf of the particular device, the protocol adapter should include the gateway’s device identifier (as determined during the authentication process) in its invocation of the Device Registration API’s assert Device Registration operation.

The Device Registry will then do the following:

1. Verify that the device exists and is enabled.
2. Verify that the gateway exists and is enabled.
3. Verify that the device’s registration information contains a property called via and that its value is either the gateway’s device identifier or a JSON array which contains the gateway’s device identifier as one of its values.

Only if all conditions are met, the Device Registry returns an assertion of the device’s registration status. The protocol adapter can then forward the published data to the AMQP Messaging Network in the same way as for any device that connects directly to the adapter.

The example configuration file (located at $HONO/services/device-registry-file/src/test/resources/device-identities.json) includes a device and a corresponding gateway configured in this way.

Messaging Configuration

The Device Registry uses a connection to an AMQP 1.0 Messaging Network, an Apache Kafka cluster and/or Google Pub/Sub to

• send Device Provisioning Notification event messages to convey provisioning related changes regarding a device, to be received by downstream applications,
• send notification messages about changes to tenant/device/credentials data, to be processed by other Hono components.

For the event messages a connection to a Apache Kafka cluster is used by default, if configured. If more than one kind of messaging is configured, the decision which one to use is done according to the Tenant Configuration.

For notification messages, the Kafka connection is used by default, if configured. Otherwise the AMQP messaging network or Google Pub/Sub is used.

AMQP 1.0 Messaging Network Connection Configuration

The connection to the AMQP 1.0 Messaging Network is configured according to the Hono Client Configuration with HONO_MESSAGING being used as ${PREFIX}. Since there are no responses being received, the properties for configuring response caching can be ignored.

Kafka based Messaging Configuration

The connection to an Apache Kafka cluster can be configured according to the Hono Kafka Client Configuration.

The following table shows the prefixes to be used to individually configure the Kafka clients used by the Device Registry. The individual client configuration is optional, a minimal configuration may only contain a common client configuration consisting of properties prefixed with HONO_KAFKA_COMMONCLIENTCONFIG_ and hono.kafka.commonClientConfig. respectively.

Google Pub/Sub Messaging Configuration

The connection to Google Pub/Sub is configured according to the Google Pub/Sub Messaging Configuration.