Discovery
- Sacha Parisot (Unlicensed)
The procedure detailed on this page allows an edge server, a network tool, or a native IAP edge device to discover its CMS and to be provisioned for use with that CMS.
1- Default Discovery Endpoint
The edge server has a pre-configured default endpoint to which it submits its discovery message when it is not configured. This endpoint can be a broker, local to the edge server where an embedded CMS shares the same local broker, it can be the well-known address of a remote CMS, or it can be the well-known address of a remote referral service.
The default endpoint information includes the broker’s network address or DNS name, the port and protocol. Where required, username and password can be included with these details.
2- Segment Discovery Publication
The edge server or tool begins the process by publishing a segment discovery message using its current set of address, port, protocol, username, and password, initially beginning with the default values indicated in step 1- Default Discovery Endpoint above.
3- Segment Approval and Provisioning
A CMS that receives a segment discovery message must determine whether to accept the segment, for example by validating the segment’s designated MACID, which is included with the discovery message, against a list of pre-registered MACID, or by seeking approval from an interactive user.
Network tools can request access to resources outside their own segment with an optional access request that is included with the segment discovery message. The CMS must grant access as requested, or refuse the request. A refused request produces no provisioning message. Once the CMS approves the segment discovery message with all details, it configures the targeted system, if necessary, then publishes a provisioning message to the segment or tool.
The provisioning message includes a connection name and segment identifier. Once assigned, neither connection name nor segment identifier must change unless the segment is deprovisioned.
The provisioning message can include the following optional properties: address, port, protocol, username, and password.
- address, if included with the provisioning message, includes the address of the broker that the segment (or tool) must connect with. This option is only set if the CMS has a well-known external address, or if the provisioning message is constructed by an IAP/MQ referral service. When the address is not specified, it is either not included the item with the provisioning message, or set to null.
- port, username, and password, if included with the provisioning message, are used by the provisioned segment in its connection to the specified broker. When port, username or password are not specified, the parameter is either not included with the provisioning message, or set to null.
- protocol, if included with the provisioning message, must be one of the protocols supported by both the CMS's broker and the segment. The segment indicates the list of supported protocols with the segment discovery message. The CMS selects MQTT over secure WebSockets (WSS) over secure MQTT (MQTTS), MQTTS over MQTT with plain WebSockets (WS), or WS over plain MQTT, in this descending order of preference.
4- Accepting the Provisioning Message
The segment or tool that receives the provisioning message combines its current set of address, port, protocol, username, and password details with those received with the provisioning message.
When the provisioning message connection name is “referral”, the tool or segment uses the resulting address and access details to publish another discovery message, returning to step 2- Segment Discovery Publication in this process. Otherwise, the segment or tool verifies that the connection name provided matches the current connection name. When no connection name is known, the connection name from the provisioning message is always accepted.
The merged address and access details are used to connect with the CMS.
When the address equates to “localhost” or 127.0.0.1, the connection is made directly. A network tool or native IAP application can always connect directly. An edge server bridges the CMS broker with the segment broker, unless a local address was specified.
5- Access Permissions
Once completed, the edge server has read access to the request channel, write access to the event and feedback channels, and read/write access to the binary channel within the segment into which it is provisioned.
Network tools sometimes require access to other segments, which they need to supervise or help manage. Such a tool requests access to the desired segments with the segment discovery message. The CMS either grants the requested permission or does not provision the tool.
6- Referral Services
It is possible that the default discovery endpoint described above points to a referral service. This service can identify the segment, tool, or device, perhaps from its description and designated MACID, and can direct the unit to its CMS or to another referral service.
The referral message publishes a provisioning message with the connection name “referral”, the SID, as received with the segment discovery message, and address, port, protocol, username, and password details, as required by the referred endpoint.
Upon receipt of a provisioning message marked as a “referral” message, the edge server, tool, or device re-directs its discovery message using address, port, protocol, username, and password, as merged from those preferences used in publishing the discovery message with those details received with the referral message.
7- Hand-over
After a CMS has provisioned the tool, device, or edge server, another management service can request that the segment be handed over. This process is outside IAP/MQ.
Once the handover request is approved by the present CMS, the present CMS re-provisions the segment using the same connection name and segment identifier, but includes address, port, protocol, username, and password details as required by the new CMS.
Upon receipt of such a re-provisioning message, the edge server, tool, or native IAP device reconfigures its connection to the CMS broker accordingly. This ends the connection to the initial CMS, but does not alter the edge server, tool, or device.
Discovery and Provisioning Details
The following topics provide information on discovery and provisioning: