The JDBC based Device Registry components provides an implementation of Eclipse Hono™'s Device Registration, Credentials and Tenant 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. In addition to the above, this Device Registry also provides an implementation of Device Registry Management APIs for managing tenants, registration information and credentials of devices.
The application is implemented as a Spring Boot application, and it uses a JDBC compliant database to persist data. In provides the following features:
Note: The provided container images contains only the H2 and PostgreSQL configuration and JDBC driver. While it is possible to use other JDBC compliant databases, database specific configuration and JDBC driver have to be provided by the user.
The following table provides an overview of the configuration variables and corresponding command line options for configuring the JDBC based Device Registry. In addition to the following options, this component also supports the options described in Common Configuration.
The configuration uses the section ADAPTER for configurations of the protocol adapter facing services, and the
section MANAGEMENT for management facing services. As adapters only require read-only operations, this can be
used to direct adapters to services instances, which are backed by read-only replicas. Which can improve performance
and availability.
| Environment Variable Command Line Option |
Mandatory | Default | Description |
|---|---|---|---|
HONO_REGISTRY_JDBC_ADAPTER_URL --hono.registry.jdbc.adapter.url |
yes | - | The JDBC URL to the database. |
HONO_REGISTRY_JDBC_ADAPTER_DRIVERCLASS --hono.registry.jdbc.adapter.driverClass |
no | The default driver registered for the JDBC URL. | The class name of the JDBC driver. |
HONO_REGISTRY_JDBC_ADAPTER_USERNAME --hono.registry.jdbc.adapter.username |
no | - | The username used to access the database. |
HONO_REGISTRY_JDBC_ADAPTER_PASSWORD --hono.registry.jdbc.adapter.password |
no | - | The password used to access the database. |
HONO_REGISTRY_JDBC_ADAPTER_MAXIMUMPOOLSIZE --hono.registry.jdbc.adapter.maximumPoolSize |
no | Depends on the connection pool implementation. 15 for C3P0. |
The maximum size of the connection pool. |
HONO_REGISTRY_JDBC_ADAPTER_TABLENAME --hono.registry.jdbc.adapter.tableName |
no | - | The name of the table the datastore uses. If the datastore requires multiple tables, this is the prefix. |
HONO_REGISTRY_JDBC_MANAGEMENT_URL --hono.registry.jdbc.management.url |
yes | - | The JDBC URL to the database. |
HONO_REGISTRY_JDBC_MANAGEMENT_DRIVERCLASS --hono.registry.jdbc.management.driverClass |
no | The default driver registered for the JDBC URL. | The class name of the JDBC driver. |
HONO_REGISTRY_JDBC_MANAGEMENT_USERNAME --hono.registry.jdbc.management.username |
no | - | The username used to access the database. |
HONO_REGISTRY_JDBC_MANAGEMENT_PASSWORD --hono.registry.jdbc.management.password |
no | - | The password used to access the database. |
HONO_REGISTRY_JDBC_MANAGEMENT_MAXIMUMPOOLSIZE --hono.registry.jdbc.management.maximumPoolSize |
no | Depends on the connection pool implementation. 15 for C3P0. |
The maximum size of the connection pool. |
HONO_REGISTRY_JDBC_MANAGEMENT_TABLENAME --hono.registry.jdbc.management |
no | - | The name of the table the datastore uses. If the datastore requires multiple tables, this is the prefix. |
HONO_REGISTRY_SVC_TASKEXECUTORQUEUESIZE --hono.registry.svc.taskExecutorQueueSize |
no | 1024 |
The size of the executor queue for hashing passwords. |
HONO_REGISTRY_SVC_CREDENTIALSTTL --hono.registry.svc.credentialsTtl |
no | 1m |
The TTL for credentials responses. |
HONO_REGISTRY_SVC_REGISTRATIONTTL --hono.registry.svc.registrationTtl |
no | 1m |
The TTL for registrations responses. |
HONO_REGISTRY_SVC_MAXBCRYPTITERATIONS --hono.registry.svc.maxBcryptIterations |
no | 10 |
The maximum number of allowed bcrypt iterations. |
HONO_TENANT_JDBC_ADAPTER_URL --hono.tenant.jdbc.adapter.url |
yes | - | The JDBC URL to the database. |
HONO_TENANT_JDBC_ADAPTER_DRIVERCLASS --hono.tenant.jdbc.adapter.driverClass |
no | The default driver registered for the JDBC URL. | The class name of the JDBC driver. |
HONO_TENANT_JDBC_ADAPTER_USERNAME --hono.tenant.jdbc.adapter.username |
no | - | The username used to access the database. |
HONO_TENANT_JDBC_ADAPTER_PASSWORD --hono.tenant.jdbc.adapter.password |
no | - | The password used to access the database. |
HONO_TENANT_JDBC_ADAPTER_MAXIMUMPOOLSIZE --hono.tenant.jdbc.adapter.maximumPoolSize |
no | Depends on the connection pool implementation. 15 for C3P0. |
The maximum size of the connection pool. |
HONO_TENANT_JDBC_ADAPTER_TABLENAME --hono.tenant.jdbc.adapter.tableName |
no | - | The name of the table the datastore uses. If the datastore requires multiple tables, this is the prefix. |
HONO_TENANT_JDBC_MANAGEMENT_URL --hono.tenant.jdbc.management.url |
yes | - | The JDBC URL to the database. |
HONO_TENANT_JDBC_MANAGEMENT_DRIVERCLASS --hono.tenant.jdbc.management.driverClass |
no | The default driver registered for the JDBC URL. | The class name of the JDBC driver. |
HONO_TENANT_JDBC_MANAGEMENT_USERNAME --hono.tenant.jdbc.management.username |
no | - | The username used to access the database. |
HONO_TENANT_JDBC_MANAGEMENT_PASSWORD --hono.tenant.jdbc.management.password |
no | - | The password used to access the database. |
HONO_TENANT_JDBC_MANAGEMENT_MAXIMUMPOOLSIZE --hono.tenant.jdbc.management.maximumPoolSize |
no | Depends on the connection pool implementation. 15 for C3P0. |
The maximum size of the connection pool. |
HONO_TENANT_JDBC_MANAGEMENT_TABLENAME --hono.tenant.jdbc.management.tableName |
no | - | The name of the table the datastore uses. If the datastore requires multiple tables, this is the prefix. |
HONO_TENANT_SVC_TENANTTTL --hono.tenant.service.tenantTtl |
no | 1m |
The TTL for tenant responses. |
HONO_REGISTRY_AMQP_BIND_ADDRESS--hono.registry.amqp.bindAddress |
no | 127.0.0.1 |
The IP address of the network interface that the secure AMQP port should be bound to. See Port Configuration below for details. |
HONO_REGISTRY_AMQP_CERT_PATH--hono.registry.amqp.certPath |
no | - | The absolute path to the PEM file containing the certificate that the server should use for authenticating to clients. This option must be used in conjunction with HONO_REGISTRY_AMQP_KEY_PATH.Alternatively, the HONO_REGISTRY_AMQP_KEY_STORE_PATH option can be used to configure a key store containing both the key as well as the certificate. |
HONO_REGISTRY_AMQP_INSECURE_PORT--hono.registry.amqp.insecurePort |
no | - | The insecure port the server should listen on for AMQP 1.0 connections. See Port Configuration below for details. |
HONO_REGISTRY_AMQP_INSECURE_PORT_BIND_ADDRESS--hono.registry.amqp.insecurePortBindAddress |
no | 127.0.0.1 |
The IP address of the network interface that the insecure AMQP port should be bound to. See Port Configuration below for details. |
HONO_REGISTRY_AMQP_INSECURE_PORT_ENABLED--hono.registry.amqp.insecurePortEnabled |
no | false |
If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_REGISTRY_AMQP_INSECURE_PORT or the default AMQP port number (5672) if not set explicitly.See Port Configuration below for details. |
HONO_REGISTRY_AMQP_KEY_PATH--hono.registry.amqp.keyPath |
no | - | The absolute path to the (PKCS8) PEM file containing the private key that the server should use for authenticating to clients. This option must be used in conjunction with HONO_REGISTRY_AMQP_CERT_PATH. Alternatively, the HONO_REGISTRY_AMQP_KEY_STORE_PATH option can be used to configure a key store containing both the key as well as the certificate. |
HONO_REGISTRY_AMQP_KEY_STORE_PASSWORD--hono.registry.amqp.keyStorePassword |
no | - | The password required to read the contents of the key store. |
HONO_REGISTRY_AMQP_KEY_STORE_PATH--hono.registry.amqp.keyStorePath |
no | - | The absolute path to the Java key store containing the private key and certificate that the server should use for authenticating to clients. Either this option or the HONO_REGISTRY_AMQP_KEY_PATH and HONO_REGISTRY_AMQP_CERT_PATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. |
HONO_REGISTRY_AMQP_NATIVE_TLS_REQUIRED--hono.registry.amqp.nativeTlsRequired |
no | false |
The server will probe for OpenSLL on startup if a secure port is configured. By default, the server will fall back to the JVM’s default SSL engine if not available. However, if set to true, the server will fail to start at all in this case. |
HONO_REGISTRY_AMQP_PORT--hono.registry.amqp.port |
no | 5671 |
The secure port that the server should listen on for AMQP 1.0 connections. See Port Configuration below for details. |
HONO_REGISTRY_AMQP_SECUREPROTOCOLS--hono.registry.amqp.secureProtocols |
no | TLSv1.3,TLSv1.2 |
A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. |
HONO_REGISTRY_AMQP_SUPPORTEDCIPHERSUITES--hono.registry.amqp.supportedCipherSuites |
no | - | A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. |
HONO_REGISTRY_HTTP_AUTHENTICATION_REQUIRED--hono.registry.http.authenticationRequired |
no | true |
If set to true the HTTP endpoint of the Device Registry requires clients to authenticate when connecting to the Device Registry. The JDBC based Device Registry currently supports basic authentication and the user credentials are to be stored in the database. For more information on how to manage users please refer to JDBC Auth Provider. |
HONO_REGISTRY_HTTP_BIND_ADDRESS--hono.registry.http.bindAddress |
no | 127.0.0.1 |
The IP address of the network interface that the secure HTTP port should be bound to. See Port Configuration below for details. |
HONO_REGISTRY_HTTP_CERT_PATH--hono.registry.http.certPath |
no | - | The absolute path to the PEM file containing the certificate that the server should use for authenticating to clients. This option must be used in conjunction with HONO_REGISTRY_HTTP_KEY_PATH.Alternatively, the HONO_REGISTRY_HTTP_KEY_STORE_PATH option can be used to configure a key store containing both the key as well as the certificate. |
HONO_REGISTRY_HTTP_DEVICE_ID_REGEX--hono.registry.http.deviceIdRegex |
no | ^[a-zA-Z0-9-_]+$ |
The regular expression to use to validate device ID. Please refer to the java pattern documentation. |
HONO_REGISTRY_HTTP_INSECURE_PORT--hono.registry.http.insecurePort |
no | - | The insecure port the server should listen on for HTTP requests. See Port Configuration below for details. |
HONO_REGISTRY_HTTP_INSECURE_PORT_BIND_ADDRESS--hono.registry.http.insecurePortBindAddress |
no | 127.0.0.1 |
The IP address of the network interface that the insecure HTTP port should be bound to. See Port Configuration below for details. |
HONO_REGISTRY_HTTP_INSECURE_PORT_ENABLED--hono.registry.http.insecurePortEnabled |
no | false |
If set to true the server will open an insecure port (not secured by TLS) using either the port number set via HONO_REGISTRY_HTTP_INSECURE_PORT or the default AMQP port number (5672) if not set explicitly.See Port Configuration below for details. |
HONO_REGISTRY_HTTP_KEY_PATH--hono.registry.http.keyPath |
no | - | The absolute path to the (PKCS8) PEM file containing the private key that the server should use for authenticating to clients. This option must be used in conjunction with HONO_REGISTRY_HTTP_CERT_PATH. Alternatively, the HONO_REGISTRY_HTTP_KEY_STORE_PATH option can be used to configure a key store containing both the key as well as the certificate. |
HONO_REGISTRY_HTTP_KEY_STORE_PASSWORD--hono.registry.http.keyStorePassword |
no | - | The password required to read the contents of the key store. |
HONO_REGISTRY_HTTP_KEY_STORE_PATH--hono.registry.http.keyStorePath |
no | - | The absolute path to the Java key store containing the private key and certificate that the server should use for authenticating to clients. Either this option or the HONO_REGISTRY_HTTP_KEY_PATH and HONO_REGISTRY_HTTP_CERT_PATH options need to be set in order to enable TLS secured connections with clients. The key store format can be either JKS or PKCS12 indicated by a .jks or .p12 file suffix respectively. |
HONO_REGISTRY_HTTP_MAXPAYLOADSIZE--hono.registry.http.maxPayloadSize |
no | 16000 |
The maximum size of an HTTP request body in bytes that is accepted by the registry. |
HONO_REGISTRY_HTTP_PORT--hono.registry.http.port |
no | 5671 |
The secure port that the server should listen on for HTTP requests. See Port Configuration below for details. |
HONO_REGISTRY_HTTP_SECUREPROTOCOLS--hono.registry.http.secureProtocols |
no | TLSv1.3,TLSv1.2 |
A (comma separated) list of secure protocols (in order of preference) that are supported when negotiating TLS sessions. Please refer to the vert.x documentation for a list of supported protocol names. |
HONO_REGISTRY_HTTP_SUPPORTEDCIPHERSUITES--hono.registry.http.supportedCipherSuites |
no | - | A (comma separated) list of names of cipher suites (in order of preference) that are supported when negotiating TLS sessions. Please refer to JSSE Cipher Suite Names for a list of supported names. |
HONO_REGISTRY_HTTP_TENANT_ID_REGEX--hono.registry.http.tenantIdRegex |
no | ^[a-zA-Z0-9-_.]+$ |
The regular expression to use to validate tenant ID. Please refer to the java pattern documentation. |
The variables only need to be set if the default value does not match your environment.
The Device Registry supports configuration of both, an AMQP based endpoint and an HTTP based endpoint proving RESTful resources for managing registration information and credentials. Both endpoints can be configured to listen for connections on:
See Port Configuration for more information.
_AMQP_ with _HTTP_.See Authentication Service Connection Configuration for more information.
See Monitoring & Tracing Admin Guide for details on how to configure the reporting of metrics.