Create or update a connection policy

Purpose

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

URI

Use the Eclipse Amlen REST API POST method with the following Eclipse Amlen configuration URI:

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

Object configuration data

Provide ConnectionPolicy object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json:


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

Where:

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.

Specify at least one of the following filters:

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.
ExpectedMsgRate: 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.

Usage Notes®

Capitalization and double quotation marks must be used as shown.
Each of the filters, ClientAddress, ClientID, UserID, GroupID, CommonNames, and Protocol, is applied in combination. If you specify several filters, each condition must be met in order for the client to connect to Eclipse Amlen. For each filter that you do not specify, all values for that filter are allowed.
For example, a connection policy is created that specifies: "GroupID": "SILVER" "UserID": "SIL*" "Protocol": "JMS". A client with User ID SIL1, in group SILVER, that is using JMS can connect. A client with a User ID SIL2, in group GOLD, that is using JMS cannot connect because not all of the filter conditions are met.

Related REST Administration APIs

Example

Creates a connection policy called "MyConnectionPolicy" by using cURL:


curl -X POST \
   -H  'Content-Type: application/json'  \
   -d  '{                       
           "ConnectionPolicy": {   
             "MyConnectionPolicy": {
               "Description": "Connection policy to authorize connection from demo client.",
               "ClientID": "*"
              }
          }
      }
  '   \
http://127.0.0.1:9089/ima/v1/configuration/

An example response to the POST method:


{        
  "Version": "v1",
  "Code": "CWLNA6011",
  "Message": "The requested configuration change has completed successfully."
}