Segment Provisioning
- Sacha Parisot (Unlicensed)
| glp/0/:{MACID}/rq/discovery/provision |
When the CMS is authorized to provision the segment, it publishes a segment provision object to the edge server's segment provisioning topic glp/0/:{MACID}/rq/discovery/provision , where MACID is replaced by the edge server's designated MACID using the exact same format as found in the edge server object’s MACID property. See Segment Discovery for additional information on the MACID.
Most edge servers implement a connection to the CMS with an MQTT bridge, but simple native IAP devices, or network tools can implement a minimal edge server without a local broker, spawning direct MQTT client connections instead of bridges. An edge server provisioned using a CMS broker address that resolves to the localhost address (“localhost” or 127.0.0.1) also connects directly.
The edge server only listens for segment provisioning messages through the segment provisioning topic when it is unprovisioned. A provisioned edge server listens for the same messages at glp/0/{SID}/rq/discovery/provision.
Once an edge server, tool, or edge device is provisioned into a segment, the connection name must not change.
SmartServer IoT Scripts
Some components may require extra steps to be performed when the edge server is being provisioned or deprovisioned, or may need extra steps to return the unit to its factory default configuration.
These extra steps are supported by the following scripts, located in the sbin directory:
- apollo-provision
apollo-provision always executes all scripts within the$APOLLO_CONFD/scripts/provision.dfolder (where $APOLLO_CONFD is typically set to/var/apollo/conf.d). The apollo-provision script is automatically invoked with elevated permission when the corresponding event occurs. - apollo-deprovision
apollo-deprovision always executes all scripts within the$APOLLO_CONFD/scripts/deprovision.dfolder (where $APOLLO_CONFD is typically set to/var/apollo/conf.d). The apollo-deprovision script is automatically invoked with elevated permission when the corresponding event occurs. - apollo-reset
apollo-reset invokes apollo-deprovision. The apollo-reset script is executed when called upon by the system's web UI or is called explicitly from a service console
NOTE: It is not recommended to edit these scripts directly, as the changes might be lost after a subsequent system image upgrade.
Properties
The segment provision object has the following properties:
Field Name | Type | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
connection | string | The connection name. connection provides a name for the MQTT connection, if such a name is needed. The name must be a single word consisting of letters A-Z, a-z, or digits 0-9, and must begin with an uppercase letter. Connection names that start with lowercase letters are reserved for IAP use. Example: C12345678AABBCCDD | ||||||||||||||||||||
address | string | (Optional) The CMS address. address can be set to null or omitted from the message. The edge server, tool, or device uses the same credentials (address, port, and protocol) used when publishing the successful discovery object. Details provided with the provisioning message can override these “last known good” details. Examples: "123.45.67.89" or "cms.acme.com" | ||||||||||||||||||||
port | number | (Optional) The CMS port. port can be set to null or omitted from the message. If set to null, the edge server uses the same credentials as used with the discovery bridge connection in the configuration of its CMS bridge connection. Example: 8883 | ||||||||||||||||||||
protocol | string | (Optional) The CMS broker protocol. Either mqtt, mqtts, ws, or wss. protocol must be a mutually supported protocol with a preference of WSS over MQTTS, and MQTTS over MQTT. Example: "mqtts" | ||||||||||||||||||||
user | string | (Optional) MQTT user name. user can be set to null or omitted from the message. If set to null, the edge server uses the same credentials as used with the discovery bridge connection in the configuration of its CMS bridge connection. Example: "aas0d98qwe" | ||||||||||||||||||||
passwd | string | (Optional) MQTT password. passwd and can be set to null or omitted from the message. If set to null, the edge server uses the same credentials as used with the discovery bridge connection in the configuration of its CMS bridge connection. Example: "-0sd_!cl;k" | ||||||||||||||||||||
sid | string | (Required) The segment ID. sid must be unique within the provisioning CMS, and must follow the requirements detailed under SID in the IAP/MQ Topic Syntax table. The following table summarizes the valid cases. All other cases yield an error.
Example: "DT3" |
Referral Message
The built-in, default credentials can point the edge server, tool, or edge device to a CMS lookup service, a service that determines the edge server's designated CMS based on the edge server's location or MACID. If successful, this referral service provides a provisioning object just like the one discussed above, with these differences:
The sid is always null.
The connection name is always “referral” (starting with a lowercase letter). Receiving this referral message re-configures the discovery connection, presumably leading to successful CMS discovery.
It is possible that one look-up service refers to another. For example, a global lookup service might recognize an edge server’s manufacturer and refer to that manufacturer’s look-up service, which in turn appoints the CMS.
When an edge server is in discovery mode for more than twelve hours, it resets its discovery bridge or connection to its original built-in default preferences. Details of the last failed CMS discovery attempt are included with the discovery message’s error property. This restarts the process in case elements of the look-up and discovery chain were not yet available or accessible at the time the edge server was installed.