Creating and updating a connection policy by using REST Administration APIs

http://<admin-endpoint-IP:Port>/ima/v1/configuration/

{    
  "ConnectionPolicy": {
    "<NameOfConnectionPolicy>": {
      "Description": "string",
      "AllowDurable": true|false,
      "AllowPersistentMessages": true|false,
      "ClientID": "string",
      "ClientAddress": "string",
      "UserID": "string",
      "GroupID": "string",
      "CommonNames": "string",
      "Protocol": "string",
      "MaximumSessionExpiryInterval" : "string",
      "ExpectedMessageRate" : "string"
     }
   }
}

NameOfConnectionPolicy

Required.

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:

! # $ % & ' ( ) * + - . / : ; < > ? @

The maximum length of the name is 256 characters.

After the connection policy is created, you cannot change this name.

Description

Optional.

Specifies a description for the connection policy.

If you do not want a description, omit "Description":"description".

AllowDurable: true|false

Optional.

Specifies whether MQTT clients can connect using a setting of cleanSession=0 (true) or not (false).

The default value is true.

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

AllowPersistentMessages: true|false

Optional.

Specifies whether MQTT clients can publish messages with a QoS of 1 or 2 (true) or not (false).

The default value is true.

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

ClientID

Specifies the client ID that is allowed to connect to Eclipse Amlen.

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.

To use the default value, where all client ID values are allowed to connect, omit "ClientID": "clientID".

ClientAddress

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.

To use the default value, where all client IP addresses are allowed to connect, omit "ClientAddress": "IP_Address" or specify "ClientAddress":"*".

UserID

Specifies the messaging user ID that is allowed to connect to Eclipse Amlen.

You can use an asterisk (*) at the end of the value to match 0 or more characters.

To use the default value, where all user ID values are allowed to connect, omit "UserID": "UserID".

GroupID

Optional.

Specifies the messaging group that is allowed to connect to Eclipse Amlen.

You can use an asterisk (*) at the end of the value to match 0 or more characters.

To use the default value, where all groups are allowed to connect, omit "GroupID": "GroupID".

CommonNames

Specifies the client certificate common name that must be used to connect to Eclipse Amlen.

You can use an asterisk (*) at the end of the value to match 0 or more characters.

To use the default value, where all client certificates are allowed to connect, omit "CommonNames": "CommonNames".

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

Optional.

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.

ExpectedMessageRate

Optional.

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.