Configuring message hubs

You can configure messaging hubs either by using the Amlen WebUI or by using REST Administration APIs.

A message hub is an organizational object which groups endpoints, connection policies, and messaging policies that are associated with a specific goal.

Note: Special character input for a particular policy field does not apply to other fields or policy types unless explicitly stated otherwise.

You create message hubs, and the message hub components, in the following order:

Message hubs
Connection Policies
At least one type of messaging policy - topic policy, queue policy, or subscription policy.
Endpoints

Message hubs

Each message hub must have at least one endpoint.

When you create and edit a message hub, you must specify the following component:

Name: Specifies the name of the message hub.; The name must not have leading or trailing spaces and cannot contain control characters, commas, double quotation marks, backslashes, or equal signs. The first character must not be a number or any of the following special characters:
! # $ % & ' ( ) * + - . / : ; < > ? @

Connection policies

A connection policy is used to authorize a connection to Eclipse Amlen based on one or more connection level attributes.

When you create a connection policy, you must specify the following component:

Name: Specifies the name of the connection policy.; The name must not have leading or trailing spaces and cannot contain control characters, commas, double quotation marks, backslashes, or equal signs. The first character must not be a number or any of the following special characters:
! # $ % & ' ( ) * + - . / : ; < > ? @

You can also specify the following components:

Allow Durable: Specifies whether MQTT clients can connect using a setting of cleanSession=0.

Allow Persistent Messages: Specifies whether MQTT clients can publish messages with a QoS of 1 or 2 .

You must specify at least one of the following filters:

Client IP address: Specifies the client IP addresses that are allowed to connect to Eclipse Amlen.; The IP address can contain an asterisk (*), or a comma-separated list of IPv4 or IPv6 addresses or ranges. For example, 192.0.2.32, 192.0.0.0, 192.0.2.0-192.0.2.100. The range must be specified from low to high.; However, each IPv6 address must be enclosed in brackets [ ] either when expressed singly or in a range of addresses. IPv6 addresses cannot contain asterisks.; The maximum number of client addresses that you can specify is 20.
Client ID: Specifies the client ID that is allowed to connect to Eclipse Amlen by using the specified endpoint.; You can use an asterisk (*) at the end of the value to match 0 or more characters.; You can use variable substitution in the client ID to ensure that only clients with a client ID that matches the user ID or the certificate common name, can connect. The variable for user IDs is ${UserID}. The variable for certificate common name is ${CommonName}. You can specify extra characters along with the variable. For example, you can specify that the client ID must match myClient/${UserID}. In this case, a client with the user ID userA and the client ID myClient/userA can connect. A client with the user ID userB and the client ID myClient/userB can connect. However, a client with the user ID userB and the client ID notMyClient cannot connect.
User ID: Specifies the messaging user ID that is allowed to connect to Eclipse Amlen by using the specified endpoint.; You can use an asterisk (*) at the end of the value to match 0 or more characters.
Group Name: Specifies the messaging group that is allowed to connect to Eclipse Amlen by using the specified endpoint.; You can use an asterisk (*) at the end of the value to match 0 or more characters.
Certificate Common Name: Specifies the client certificate common name that must be used to connect to Eclipse Amlen by using the specified endpoint.; You can use an asterisk (*) at the end of the value to match 0 or more characters.
Protocol: Specifies which protocols are allowed to connect to Eclipse Amlen.; You can choose from JMS and MQTT protocols. If there are any protocol plug-ins installed on the Eclipse Amlen server, you can specify these as well. To specify more than one value, separate each value with a comma. To select all protocols, specify a null value for Protocol or omit the parameter from the command.; To specify more than one value, separate each value with a comma.
MaximumSessionExpiryInterval: Specifies the maximum time, in seconds, that a session is kept alive before expiring.; The value must be either unlimited, or in the range 1-2147483647.; The default value is unlimited and means that a session will not expire.
ExpectedMsgRate: Specifies the expected throughput of messages.; Valid values are Low, Default, High, Max.; The default value is Default.; A value of Low might be used for a throughput of less than 10 messages per second, a value of Max might be used for a throughput of more than a few thousand messages per second.; When selecting the value, consider factors such as the latency of the connection, and the size and number of devices. If you have many devices, you might want to use a lower setting in order to save memory.

Each filter is applied in combination. If you specify several filters, each condition must be met in order for the connection to be allowed. For each filter that you do not specify, all values for that filter are allowed.

For example, a connection policy is created that specifies:

group name must be GOLD AND client IP address must be 192.0.2.0-192.0.2.50 AND the protocol must be MQTT

A client is allowed to connect with any client ID, any user ID, and any certificate common name. However, if the client does not have a group name of GOLD, or if the IP address of the client is not in the range 192.0.2.0-192.0.2.50, or if the client is not using MQTT, the connection is not allowed.

Messaging policies

There are three types of messaging policies: topic policies, subscription policies, and queue policies.

Topic policies are used to control which clients can publish or subscribe to a specified topic. Queue policies are used to control which clients can send to, receive from, or browse a specified queue. Subscription policies are used to control which clients can receive messages from a specified global-shared durable subscription. Subscription policies are also used to control which clients can control the creation and deletion of global-shared durable subscriptions on a specified subscription name.

Note: All messaging policies for an endpoint are checked for authorization, either until authorization is granted, or all messaging policies are checked. Therefore, you cannot create a messaging policy that restricts the authority of particular clients if another messaging policy grants more authority to those clients. For example, a subscription policy is created where all clients with a user ID that starts with example are allowed to control and receive messages. Another subscription policy is created such that the client with the user ID exampleUser is only allowed to receive messages from the subscription. The client with the user ID exampleUser is able to both control and receive messages, because of the first subscription policy.

When you create a messaging policy, you must specify the following components:

Name: Specifies the name that identifies the messaging policy.; The name must not have leading or trailing spaces and cannot contain control characters, commas, double quotation marks, backslashes, or equal signs. The first character must not be a number or any of the following special characters:
! # $ % & ' ( ) * + - . / : ; < > ? @
Topic: Applies to topic policies only.; Specifies the topic string that the topic policy applies to.
Subscription: Applies to subscription policies only.; Specifies the subscription name that the subscription policy applies to.
Queue: Applies to queue policies only.; Specifies the queue name that the queue policy applies to.
Actions: Specifies which messaging actions can be used by clients that connect to the endpoints associated with this messaging policy.; For topic policies, you can choose between publish and subscribe, or you can enable both.; For subscription policies, you can choose between control and receive, or you can enable both. Control allows a client to create or delete the global-shared durable subscription. To create or delete a global-shared durable subscription, a client must also be allowed to receive messages. Therefore, if you select control, you must also select receive within the same subscription policy.; For queue policies, you can choose between send, receive, and browse, or a combination of the three options.; When you use the Amlen WebUI, this component is called Authority. When you use the REST Administration APIs, this component is called ActionList.

You can also specify the following components:

Max Messages

Applies to topic policies and subscription policies only.

Specifies the maximum number of messages that are kept for a subscription. This value is a guideline, rather than an absolute limit. If the system is running under stress, then the number of buffered messages on a subscription might be slightly higher than the MaxMessages value.

This value must be in the range 1 - 20,000,000.

The Max Messages value for a global-shared durable subscription must be specified in the subscription policy. If a Max Messages value is also specified in the associated topic policy, the value from the subscription policy is used.

If you change the Max Messages value, the change is applied to all subscriptions that are using the policy.

If you lower the Max Messages value, existing subscriptions that have more messages in their buffer than the new Max Messages value cannot accept further messages until the number of messages in the buffer falls below the new value. The setting of Max Messages Behavior specifies the action that is to be taken when this situation arises.

Max Messages Behavior

Applies to topic policies and subscription policies only.

Specifies the behavior that is applied when the number of messages in the buffer for a subscription reaches the max messages value. That is, when the buffer for a subscription is full. The behavior is applied to both durable and non-durable subscriptions.

The behavior can be one of the following options:

Reject new messages
New messages are not accepted on the buffer for the subscription.
Discard old messages
A percentage of the old messages on the buffer for the subscription are discarded. If a retained message is one of the old messages, it is discarded. The quality of service, persistence, and priority of the message does not prevent a message from being discarded. Therefore, if all messages must be received in order for your applications to function correctly, you cannot set Max Messages Behavior to discard old messages.

The default behavior is to reject new messages.

If you change the Max Messages Behavior setting, the change is applied to all subscriptions that are using the policy.

Max Message Time To Live

Applies to topic policies and queue policies only.

Specifies the maximum time, in seconds, that a sent message that is associated with the messaging policy can exist for in Eclipse Amlen.

The value must be either unlimited or in the range 1-2147483647.

The default value is unlimited and means that messages will not expire unless the publishing application specifies a time for messages to exist for.

This value is applied only when the messaging policy is either:

A topic policy with an action of publish, or
A queue policy with an action of send.

If you change the Max Message Time To Live value, the change is applied to all publishers and senders that are using the policy but is effective only on messages that are sent after the change has been made.

Disconnected client notification

Applies to topic policies only.

Specifies whether notification messages are published for disconnected MQTT clients on arrival of a message.

This value is only applied when the protocol that is used is MQTT.

The notification messages are published to the reserved system topic $SYS/DisconnectedClientNotification.

If you change the Disconnected client notification setting, the change is applied to all subscriptions that are using the policy.

You must specify at least one of the following filters:

Client IP address: Specifies the client IP addresses that are allowed to use the messaging actions that are specified in the messaging policy.; The IP address can contain an asterisk (*), or a comma-separated list of IPv4 or IPv6 addresses or ranges. For example, 192.0.2.32, 192.0.0.0, 192.0.2.0-192.0.2.100. The range must be specified from low to high.; IPv6 addresses must be enclosed in brackets [ ].; The maximum number of client addresses that you can specify is 20.
Client ID: Specifies the client ID that is allowed to use the messaging actions that are specified in the messaging policy. The client ID is allowed to use the messaging actions only on the subscriptions that are specified in the policy.; You can use an asterisk (*) at the end of the value to match 0 or more characters.
User ID: Specifies the messaging user ID that is allowed to use the messaging actions that are specified in the messaging policy.; You can use an asterisk (*) at the end of the value to match 0 or more characters.
Group Name: Specifies the messaging group that is allowed to use the messaging actions that are specified in the messaging policy.; You can use an asterisk (*) at the end of the value to match 0 or more characters.
Common Names: Specifies the client certificate common name that must be used for a client to be allowed to use the actions that are specified in the messaging policy.; You can use an asterisk (*) at the end of the value to match 0 or more characters.
Protocol: Specifies which protocols are allowed to use the actions that are specified in the messaging policy on the topics or queues that are specified in the policy.; You must specify at least one protocol in order for clients to connect.

Each filter is applied in combination. If you specify several filters, each condition must be met in order for the actions that are specified in the messaging policy to be allowed. For each filter that you do not specify, all values for that filter are allowed.

For example, a messaging policy is created that specifies:

group name must be SILVER AND user ID must be *.com AND protocol must be JMS

A client is allowed to perform messaging actions from any IP address, with any client ID, and any certificate common name. However, if the client does not have a group name of SILVER, or if the user ID does not end with .com, or if the client is not using JMS, the messaging actions are not allowed.

Dynamic updates to messaging policies

When you update the following messaging policy parameters, the updates are applied dynamically to all the subscriptions and publishers that are using the messaging policy:

Max Messages
Max Messages Behavior
Max Message Time to Live
Disconnected client notification

Dynamic policy updates for the Max Messages, Max Messages Behavior, and Disconnected client notification parameters are immediately applied to all subscriptions that are using the messaging policy. Updates to the Max Message Time to Live parameter, which is a parameter on the publisher, apply to all messages that the publisher sends after the update.

The messaging policy that is associated with a subscription is determined when a subscription connects and can vary from connection to connection.

For durable subscriptions, the applicable messaging policy is always the last policy with which the client connected.
For non-durable subscriptions, the applicable messaging policy is the policy used by the client for the active connection.
For global-shared durable subscriptions, the applicable messaging policy is the subscription policy that was used by the client that originally created the global-shared durable subscription. Unlike other types of subscriptions, the messaging policy associated with a global-shared durable subscription does not change when a client reconnects.

When a client reconnects to Eclipse Amlen, the values of these parameters in the messaging policy that authorizes the client on re-connection are applied dynamically to the subscriptions being used by the client. The client might experience unexpected behavior if these values are different than the values that were in use the last time that the client was connected. There are a number of reasons for the values of these parameters to be different when a client reconnects:

If the client is authorized by the same messaging policy, the value of any of these parameters might have changed since the last time that the client application connected.
The client application might reconnect by using a different endpoint to the one it used the last time that it connected. The endpoint that the client now uses might have different messaging policies, or it might have the same messaging policies but specified in a different order.
There might have been a change to the order in which the messaging policies are listed in the policy list on the endpoint. For example, you might have added a messaging policy at a position which precedes the messaging policy that was being used when the client last connected. The new policy is then used to authorize the client.
The filters in the policy in the policy list might have changed and the changed policy is being used to authorize the client.
Changing the value of the Topic, Queue, or Subscription parameter of a policy can cause the client to be authorized by a different policy than on previous connections. For example, you might have changed the value of Topic in a topic policy and the changed topic policy is then used to authorize the client.
The messaging policy that was being used when the client was last connected might have been removed from the endpoint.
The client application might reconnect by using a different IP address to the one it was using when it was last connected, and the value of the ClientAddress filter results in the selection of a different messaging policy.

Endpoints

An endpoint allows a client to connect to Eclipse Amlen.

Each endpoint must have at least one connection policy, and at least one messaging policy.

When you create an endpoint, you can specify the following components:

Name: Specifies the name that identifies the endpoint.; The name must not have leading or trailing spaces and cannot contain control characters, commas, double quotation marks, backslashes, or equal signs. The first character must not be a number or any of the following special characters: ! # $ % & ' ( ) * + - . / : ; < > ? @
Port: Specifies the port that clients connect to.; The port number must be in the range 1 - 32767, 61001 - 65535.
Interface: Specifies one, or all, of the available IP addresses for the client to connect to.
Protocol: Specifies the protocols that the clients can use to connect to Eclipse Amlen.
Enabled: Specifies whether the endpoint is enabled.
Max Message Size: Specifies the maximum size that a message can be when sent to Eclipse Amlen through this endpoint.; The size is specified in KB, and must be in the range 1 - 262,144.
Security Profile: Specifies the security profile to apply to the endpoint. The security profile defines the Transport Layer Security for the endpoint. The security profile must exist before it can be applied to the endpoint.
Connection Policies: Specifies one or more connection policies to apply to the endpoint.; You can use the same connection policy with more than one endpoint within a message hub.; When Eclipse Amlen checks whether a client is authorized to connect, each connection policy is checked in the order that the policies are specified on the endpoint. The policies are checked until either authorization is granted, or all connection policies on the endpoint are checked. You can view the order that connection policies are specified on an endpoint by using the Amlen WebUI, or by using the REST API GET method. You can change the order by using the Amlen WebUI, or by using the REST API POST method.
Topic Policies: Specifies the topic policies to apply to this endpoint. The policies must exist. These policies must be specified in a comma-separated list.; When Eclipse Amlen checks whether a client is authorized to perform topic messaging actions, each topic policy is checked in the order that the policies are specified on the endpoint. The policies are checked until either authorization is granted, or all topic policies on the endpoint are checked. Therefore, the order of the comma-separated list is important.
Subscription Policies: Specifies the subscription policies to apply to this endpoint. The policies must exist. These policies must be specified in a comma-separated list.; When Eclipse Amlen checks whether a client is authorized to perform subscription messaging actions, each subscription policy is checked in the order that the policies are specified on the endpoint. The policies are checked until either authorization is granted, or all subscription policies on the endpoint are checked. Therefore, the order of the comma-separated list is important.
Queue Policies: Specifies the queue policies to apply to this endpoint. The policies must exist. These policies must be specified in a comma-separated list.; When Eclipse Amlen checks whether a client is authorized to perform queue messaging actions, each queue policy is checked in the order that the policies are specified on the endpoint. The policies are checked until either authorization is granted, or all queue policies on the endpoint are checked. Therefore, the order of the comma-separated list is important.
Max Send Size: Specifies the maximum size that part of a message can be when it is sent.; The size is specified in bytes, and must be in the range 128 - 65536.; You might want to use this option in environments where resource-constrained devices are used; set a low value for Max Send Size, for example 256 bytes, and disable the batching of messages by setting Batch Messages to False.; The default value is 16384 bytes.
Batch Messages: Specifies whether messages can be sent in batches or must be sent singly.; You might want to set this option to False in environments where resource-constrained devices are used to ensure that single messages are sent; ensure that you also set a low value for Max Send Size, for example 256 bytes.; The default value is true.
Enable About Eclipse Amlen panel: Specifies whether the About Eclipse Amlen panel for this endpoint can be reached.; The default value is false which means that the panel for this endpoint cannot be reached.; In production environments, it is best practice to specify a value of false.

When you configure an endpoint by using the REST Administration APIs, you must also specify the following component:

MessageHubName: Specifies the name of the message hub that the endpoint belongs to.

For more information about configuring message hubs by using the Amlen WebUI, see Configuring message hubs by using the Amlen WebUI.

For more information about configuring message hubs by using REST Administration APIs, see Creating and updating a message hub by using REST Administration APIs.