This document describes the specifics of the Initial Provisioning mechanism implementation for RM.
The mechanism is realized according to the requirements of the OSGi Service Platform Specification release 4.2, chapter "Initial Provisioning" but with added specific features. It provides a light OSGi device provisioning and configuration mechanism, enabling full customization on behalf of system integrators.
OSGi-Specified Initial Provisioning
The term initial provisioning is specified by OSGi. It describes the procedure for supplying a device with all necessary components for its management through a backend system, such as Bosch IoT Remote Manager. More specifically, these components are management agent bundles and configuration properties. Without such components, there cannot be unified communication between a backend system and a device. Hence, if an OSGi device will be managed through RM or any other system, it must be provisioned with the necessary components first.
The OSGi defines a special service that has the goal to enable the initial provisioning of a device: the Provisioning Service (org.osgi.service.provisioning.ProvisioningService). This service must be available on the OSGi device in advance. This service is given a set of provisioning data (also referred to as provisioning properties or provisioning Dictionary) describing the URL of its backend, communication scheme, and any other information. When it receives the URL of its backend, which is the least information necessary, it starts the provisioning.
OSGi Provisioning Properties
OSGi defines a set of vendor-independent provisioning properties that can be passed to the Provisioning Service. They are available as constants in the org.osgi.service.provisioning.ProvisioningService interface:
Provisioning Property | Constant of ProvisioningService | Description |
|---|---|---|
| PROVISIONING_SPID | The key to the provisioning information that uniquely identifies the Service Platform. |
| PROVISIONING_REFERENCE | The key to the provisioning information that contains the location of the provisioning data provider. Its value must contain the URL pointing to the backend server. To establish connection to the RM backend, the format of the provisioning URL must be: <provisioning_scheme>://<rm_host>:<port>/prvsetup Where <provisioning_scheme> is the scheme used for provisioning (see Provisioning Schemes). <rm_host> is the RM backend host (with MS role) which will be contacted as provisioning data provider. <port> is the RM remote port used for the scheme (set the port only in case its number is different from 80 for http and rsh and from 443 for https). |
| PROVISIONING_AGENT_CONFIG | The key to the provisioning information that contains the initial configuration information of the Management Agent. |
| PROVISIONING_START_BUNDLE | The key to the provisioning information that contains the location of the bundle to start with java.security.AllPermission. The bundle must have been previously installed for this entry to have any effect. |
| PROVISIONING_ROOTX509 | The key to the provisioning information that contains the root X509 certificate used to establish trust with the operator when using secure scheme. |
| PROVISIONING_RSH_SECRET | The key to the provisioning information that contains the shared secret used in conjunction with the RSH protocol. |
To be able to initiate provisioning, at least the provisioning.reference property must be set in the provisioning Dictionary!
Provisioning Schemes
To be able to use a particular scheme for the provisioning URL, a special application, called URL stream handler, must be available for the scheme. The JVM usually provides URL stream handlers for basic schemes as "http", "https" and "file". Additionally, custom provisioning schemes may be provided by implementing such URL stream handlers (URL stream handlers can be developed in OSGi R3/R4 specific way by implementing and registering an org.osgi.service.url.URLStreamHandlerService service. For details on implementing OSGi URL Handlers see the URL Handlers Service Specification, part of OSGi Core Specification Release 4.
The Provisioning Service implementation supports four provisioning schemes, based on the protocol support in the JVM and on proprietary URL handlers:
- File – Based on the standard file access.
- HTTP – Based on the standard HTTP protocol.
- HTTPS – Based on HTTPS, i.e. supports a security layer with encryption and optional certificate authentication.
- RSH – Defined by OSGi. Based on a shared-secret security mechanism.
Refer to the "Installing URL Handlers to Enable Provisioning Schemes" section below for more information about installing the provisioning schemes in the OSGi framework.
Bosch Digital Specific Provisioning Features
The Bosch Digital implementation of initial provisioning follows the OSGi specification, adding useful features to it.
The process of initial provisioning, according to the OSGi Specification, involves contacting the backend management system and downloading the appropriate Management Agent (the bundle that enables remote management) from it. The Bosch Digital implementation of the provisioning, however, is separated into two procedures: initial provisioning and actual provisioning. The first part, the initial provisioning, follows the OSGi specification. However, the initial provisioning in terms of Remote Manager involves downloading an MA Loader Agent bundle (osgidm.provisioning.maloader.agent.jar), whose only task is to select the management agent which is most suitable for the particular OSGi device among the management agents available on the backend.
The download of the actual management agent plus the transport provider bundles is called Actual Provisioning. It is handled by the MA Loader Agent. This procedure is Bosch Digital-specific and is out of the scope of the OSGi Initial Provisioning specification.
The implementation of a provisioning agent is capable of contacting vendor-independent backend management systems (i.e. not only Remote Manager) and performing flexible initial provisioning according to a set of configuration properties.
Provisioning Scenarios
The OSGi specification defines that the provisioning is initiated when the Provisioning Service is supplied with enough properties for it, but it doesn't specify the way in which the properties should be set.
The Bosch Digital implementation enables two ways of passing properties to the Provisioning Service:
- The RM backend establishes initial connection to the device and pushes a set of properties to it – The idea is that the RM "urges" the device to initiate the provisioning. The backend establishes initial connection to the device over HTTP or HTTPS, authenticating itself with an administration user account existing on the device (only if the prm.require.auth system property is not set to false on the device, see "Provisioning Properties" below) and/or certificate chain (only if HTTPS initial transport is chosen). After the connection is successfully accepted, the backend pushes the initial provisioning properties for the device's further management. This enables the device to begin the execution of the initial provisioning and actual provisioning procedures.
During the established initial connection, the RM backend actually pushes the provisioning properties through the HTTP Provisioning Info Provider (see section "Providing and Storing the Provisioning Properties").
- The essential provisioning properties are set in a non-RM way on the device – In this scenario the device takes the initiative for the provisioning. The device establishes connection to the provisioning URL on the backend. The connection can be over HTTP, HTTPS, RSH (implemented by a ready-to-use Bosch Digital URL handler, see "Provisioning Schemes" above) or any other scheme provided in some way. If a secure scheme is chosen, the device may have to be authenticated through the means used by the scheme (such as shared secret for RSH scheme, or, optionally, digital certificate for HTTPS). After the contact is successful, the device requests a set of provisioning properties from the backend, and continues with the rest of the phases of the provisioning.
The basic difference between the two scenarios is that in the backend-initiated case, the backend establishes connection to the device before it starts the provisioning. Note, however, that the very provisioning always begins on the device.
Bosch Digital-Specific Provisioning Properties
Bosch Digital defines a set of provisioning properties that can be added to the provisioning Dictionary along with the OSGi-specified properties. The Bosch Digital-specific properties, however, are not used only during the initial provisioning process. Some of them are used during the subsequent management sessions between the device and the RM backend to provide information about the URL of the backend MS, communication transport, ports, etc.
The available Bosch Digital-specific provisioning properties are:
Provisioning Property | Description | Default Value |
|---|---|---|
| The URL(s) of the RM management server (MS) host(s) responsible for the management of this device. This property is usually set by the RM backend after the device has established connection to it, but in some cases you might have to specify it by yourself. The format of this URL is: <comm_scheme>:<rm_host>:<rm_port> where: | - |
| The transport used for the management sessions between the RM backend and the device. See section "Transport Service" under OSGi Network Connectivity for more information. | - |
| The DNS name of the MS host. | - |
| The communication port for the prm.transport scheme. See section "Configuration of the Backend Device Communication Components" under OSGi Network Connectivity. | - |
| The IP address of the MS host. | - |
| ||
| The location in the device management tree where the device will be placed when it is registered in the RM system. | - |
| The name with which the device will appear in the device management tree. | - |
| This property specifies local port which will be used for UDP/TCP communication with the MS. If the property is not set, then the default value 1502 is used. If the property has value 0, then the UDP/TCP port is bound to an arbitrary free local port. | 1502 |
| The HTTP URL to which the provisioning agent will send provisioning log messages to RM. For sending log information to RM, use the URL: http://<rm_host>[:<http_port>]/prmprvlog | - |
| Defines if secure communication transport will be used for the management sessions with the RM backend. | false |
| Defines if certificate authentication of the RM management server will be required on each established management session. This property makes sense only if secure transport is chosen. | false |
| All system properties that begin with this prefix (prm.platform.capability.) will be included in the platform profile of the device. The name of the capability defined in this way is the key of the system property without this prefix, and the value is the value of the system property. More than one capability values can be specified by separating them with commas. | - |
| This property specifies the name of of the defined platform profile of this device. | - |
Properties for Enabling the Optional Administration Features of RM
There are two ways to enable the installation of desired optional features on the managed OSGi device:
- By using the console UI – At the time of registering new OSGi device, in the Optional Administration Features dialog of the Registering New OSGi Devices wizard, check the preferred optional features to be enabled.
- By adding to the provisioning Dictionary (locally on the device or by pushing them from the backend):
- Programmatically – By including the feature keys as properties in the provisioning Dictionary and:
- On the backend – passing it to the OSGi Device Manager Service (com.prosyst.mprm.admin.osgi.OSGiDeviceManager) or to the "$create.register.device" constructor action of the "mprm.osgi.device" control unit.
- On the device – passing it to the OSGi Provisioning Service.
- On the device by using the provisioning info providers – For example, you can define the optional features as system properties (note that in this case the system property prm.env.provider.push.starting.with should be set to "prm").
- Programmatically – By including the feature keys as properties in the provisioning Dictionary and:
Optional Feature Key | Optional Feature Name | Description |
|---|---|---|
| Alert Service | Enables OSGi device bundles to fire alert messages about problems requiring urgent human actions. See the OSGi Device Alert document. |
| Alert Pluggable Commands | Enables alert board agent dashboard pluggable commands |
| Application Management Agent | Enables support of service packages. |
| Backup and Restore Agent | Provides a possibility to store the full set or a subset of the user and system configuration both on the device and on the RM |
| File Transfer Service | Enables backup files transfer to the RM |
| Functional Item Management Agent | Enables Functional Item to Control Unit Management from the RM |
| Backup Provider for Service Applications | Enables Service Applications Restore |
| Conditional Permission Agent | Provides control unit representation of Conditional Permissions Managing Permissions on OSGi Devices state and management. |
| Connection Scheduler | Ensures the mechanism for closing the unused connections with the managed OSGi device. |
| Control Unit Management Agent | Enables the remote management of control units available on the OSGi device. See the Managing Device-Side Control Units document. |
| CU Application Remote Management Interface | This agent enables the management of control units provided by the service applications. |
| HTTP Tunnel | Enables support of HTTP Tunnel. |
| JSON-RPC Agent | Enables support for JSON-RPC Tunneling |
| RM JMS Service | Provides an RM/JMS bridge on the device. See the J2EE Integration package's documentation for details. |
| OS Commands Support | Enables firing OS-specific commands on the device through the RM Management Script. |
| Preferences Support | Enables storing the user and system preferences of devices on the RM backend. See the documentation of the User Management package for details. |
| Remote Driver Locator | Allows the system to automatically detect the suitable driver bundles according to the OSGi Device Access Specification. See RM Driver Locator. |
| Remote Log Extension Service | Enables device-related log messages stored in a log file to be retrieved from the RM backend. |
| Remote Log Service | Enables device-related log messages to be reviewed through the RM backend. See OSGi Device Remote Log Service. |
| Log Monitor | Makes the monitoring information in the OSGi Monitor Admin accessible from the RM backend. |
| Monitoring Agent | Provides Control Units-based presentation over OSGi Monitor Admin service, thus allowing remote monitoring of the custom status variables through the RM. |
| Resumable Bundle Install Support | Enables resuming the download of a bundle being installed onto the OSGi device framework in case of interrupted connection. |
| OSGi Bundle Component Plug-in | Allows the (un)installation, starting and stopping of OSGi bundles included in service applications on OSGi frameworks. |
| Subscription Deployment Package Plug-in | Enables the management of deployment packages included in service applications on client devices. |
| SW Admin Application Agent | Enables the management of software components by using the Software Admin. For details, please refer to the Managing Software Components conceptual guide. |
| Linux System Agent | Provides management features over the device on a level of its operating system – that is Linux in the current case. The agent allows you to perform process management, system monitoring (CPU, RAM) and Storage monitoring. See OS System Management conceptual guide. |
| ZIP Package Management | Provides ZIP Package Management functionality. |
| WebSocket Remote Events Agent | Enables remote events push mechanism |
Supplying Custom Optional Administration Features
RM allows you to create custom applications that will be treated as optional RM features and can be enabled on the device by adding them to the provisioning Dictionary. To be able to add such a custom feature, you need to add three headers to the manifest of the custom bundle:
OptionalFeature: true
OptionalFeature-Key: <feature_key>
OptionalFeature-Name: <feature_name>
Where <feature_key> indicates the name of the provisioning property that will enable the custom feature. This property can be passed to the provisioning Dictionary of the device. <feature_name> defines the user-friendly name with which the feature will be displayed in the Registering New OSGi Devices wizard in case the relevant bundle has been added to the Software Repository.
Providing and Storing the Provisioning Properties
The OSGi specification does not define the way in which the provisioning properties should be provided and stored persistently. It is up to the implementation to provide such mechanisms. The implementation works with two Bosch Digital-specific component types: provisioning info providers and provisioning storage.
- Provisioning info providers – A provisioning info provider supplies provisioning properties to the Bosch Digital Provisioning Service. There may be zero, one or more provisioning info providers available in the framework. Every provider could load a different set of properties. If a property is set by more than one provider, then the Bosch Digital Provisioning Service uses the property value set by the provider with highest ranking (the "service.ranking" property of OSGi services with which the provider is registered). The provider ranking is the "weight" of the provider service. It determines the priority with which a given provisioning info provider can set provisioning properties. For providers installed before the Provisioning Service, the rule is this: the values of the properties provided by the provider with the higher ranking override the values of those exported by a provider with lower ranking. After the installation of the Provisioning Agent, the values available in a newly installed provider override the ones available in older ones. Therefore, each new provider overrides the property values of the previously installed providers, no matter their ranking.
The properties may be obtained in various ways, and it is up to the implementation of the provider. For example, one provider could provide the identifier of the service platform by retrieving the serial number of the hardware box, while another provider could provide the provisioning URL obtained from an issued by the operator SIM card. See "Provisioning Info Providers" below for a list of ready-to-use providers.
Provisioning info providers can be packed inside the provisioning agent bundle, or can be exported as services by other bundles. Refer to Developing a Custom Transport Service from RM Provisioning APIs (Programmer's Guide).
- Bosch Digital Provisioning Storages – These components take care for the persistent storing of the properties so that the properties and their values can be retrieved even after restart of the device. Only one storage at a time can be used for persistent storage of the properties. The Bosch Digital Provisioning Service uses the first storage it finds inside its JAR or exported as a service by other bundles in the framework. First it searches for storages inside its JAR and, if it doesn't find any, searches for storage services in the framework.
Bosch Digital provides ready-to-use provisioning info providers and storage wrapped in the Provisioning Agent but the system integrator is free to develop and install customized implementations suitable for the specifics of the business model and hardware configuration of the service platform.
Provisioning Info Providers
There are four ready-to-use providers wrapped in the Provisioning Agent bundle:
- CM Provisioning Storage – This provider is not a provisioning info provider in the meaning of the Bosch Digital providers but it can still be used to provide provisioning properties as a configuration in the OSGi Configuration Admin. It also serves as a provisioning storage. See "Setting the Properties in the CM Provisioning Storage" in the "Provisioning Setup and Configuration" section below for information about how to set properties in this provider.
- Environment Info Provider – This provider maps the provisioning properties to system properties set in the JVM prior to the provider's startup. The system properties should have the same keys as the provisioning ones.
Environment Info Provider does not immediately add the retrieved system properties to the provisioning Dictionary. It waits for the Provisioning Service to query about the value of a particular property in order to pass it. Only the properties defined as value to the prm.env.provider.push.starting.with property (see the "Bosch Digital-Specific Provisioning Properties" above) are immediately passed to the provisioning Dictionary.
- HTTP Provisioning Info Provider – This provider loads properties sent as parameters of POST and GET requests to the /rminit alias. See "Setting the Properties in the HTTP Provisioning Info Provider" in the "Provisioning Setup and Configuration" section below.
To be able to use the HTTP Provisioning Info Provider, you must have an HTTP server running in the OSGi device's framework
- File Provisioning Info Provider – This provider loads its properties in the form of a file named props.txt, available in the main directory of the bundle's JAR file. The syntax of the props.txt file is described in the Setting the Properties in the File Provisioning Info Provider part of this document in the "Provisioning Setup and Configuration" section below.
Provisioning Storages
CM Provisioning Storage
The CM Provisioning Storage uses the OSGi Configuration Admin Service as a means for persistent storage of the provisioning properties. It registers a configuration with PID prm.provisioning.pid. All provisioning properties passed to it are stored in this configuration.
Apart from provisioning storage it serves for a provisioning info provider, i.e. changing the configuration in the Configuration Admin propagates it to the Provisioning Service.
The provisioning storage requires the OSGi Configuration Admin service to be available on the target OSGi device.
File Provisioning Storage
The file provisioning storage is used for persistent storage of the provisioning properties of those devices, that comply with version 1.0 of the OSGi specification. This release of the OSGi specification does not support the Configuration Admin service. This storage persists provisioning info into a data file.
UDP Multicast Discovery of OSGi Devices
The Bosch Digital Provisioning Service supports a convenience feature allowing the backend to discover devices joined to a specified multicast host and port. The advantage of using this utility is that, first, it allows easy discovery of available devices in the network, and, second, it allows you to register multiple discovered devices simultaneously.
The adjustment of the multicast host and port is done by using a couple of system properties on the device: mbs.multicast.host for the host (default value: 225.0.0.0), and mbs.multicast.port for the port (default value: 7777).
Provisioning System Properties
The following list of system properties can be set to the Provisioning Agent for tuning the behavior of Bosch Digital's ready provisioning info providers, UDP multicast discovery agent or the general specifics of the provisioning process:
Property | Description | Default Value |
|---|---|---|
General Provisioning Properties | ||
| This system property determines if provisioning must wait until the framework is started. | true |
| This system property determines if the provisioning agent should try to make provisioning on every start. Otherwise, once the device is provisioned, the provisioning process will not be repeated. | false |
| This system property determines if provisioning agent should print debug and error information on the console. | false |
| This system property determines if provisioning agent should send debug and error information to the RM Log Service on the backend. | false |
For the UDP Multicast Discovery Agent | ||
| This system property determines the multicast host for the UDP multicast discovery. | 255.0.0.0 |
| This system property determines multicast port for the UDP multicast discovery. | 7777 |
For the HTTP Info Provider | ||
| Defines if the Provisioning Service should use the HTTP Info Provider, that is, if provisioning properties can be pushed to the service over HTTP, as described in the "Setting Properties in the HTTP Provisioning Info Provider" section below. | true |
| If set to true, the initial connection for pushing provisioning properties (by the RM backend or in any other way) must be over HTTPS, and no HTTP connections will be accepted. | false |
| Defines if authentication through an administrator account will be requested from the backend. | true |
For the File Info Provider | ||
| Defines if the Provisioning Service should use the File Info Provider, that is, if provisioning properties can be defined in a text file within the Initial Provisioning bundle JAR file, as described in the "Setting Properties in the File Provisioning Info Provider" section below. | true |
| Defines if the file provider will load provisioning properties only the first time it is started. | true |
For the Environment Info Provider | ||
| Defines if the Provisioning Service should use the Environment Info Provider, that is, if provisioning properties can be defined as system properties to the JVM, as described in the "Provisioning Info Providers" section above. | true |
| If you set a value to this property, all provisioning properties set as system properties starting with the defined value will be added to the provisioning Dictionary. For example, if you set this property with value "prm.support", all set properties such as "prm.support.cuagent", "prm.support.accounting", "prm.support.user.manager" , etc. will be added to the provisioning Dictionary. If you set this property with wildcard ("*") value, all set system properties will be set to the provisioning Dictionary in the Provisioning Service. | - |
Provisioning Agents
Provisioning Agents for Bosch Digital OSGi Frameworks
There are two bundles providing an implementation of the OSGi Provisioning Service meant to run on OSGi frameworks developed by Bosch Digital (their JARs are available at the initial provisioning directory – <RM_HOME>/initial_provisioning):
- Provisioning Agent (prvagent.jar) – This provisioning agent is suitable for devices based on release 4.0 of the OSGi Service Platform Specification.
- Provisioning Agent (prvagent_fs.jar) – This provisioning agent is suitable for devices based on release 4.0 of the OSGi Service Platform Specification, which do not have Configuration Admin service (e.g. mBS Equinox Edition). It is like prvagent.jar but uses the File Storage instead the CM Storage.
The Bosch Digital Provisioning Agents support customizing the contents of their JARs, i.e. adding/removing provisioning info providers, storage and URL handler components. When a new component is added/removed, this must be indicated in the value of specific manifest headers. See Provisioning APIs for more information.
Provisioning Agents for Non-Bosch Digital OSGi Frameworks
The RM can manage devices based on non-Bosch Digital OSGi frameworks, however those devices must be properly provisioned at first. For this purpose, Bosch Digital provides the Provisioning Bundle with Dependencies which is meant to equip the non-Bosch Digital OSGi frameworks with all the Gateway Software-specific basic packages and services used by the RM Management Agent bundle. The bundle's JAR file is prvagent_with_dep.jar located at the <RM_HOME>/initial_provisioning directory.
Inside the Provisioning Agent Bundles
The current section summarizes the provisioning agent bundles, that refers to devices based on the OSGi Service Platform Specification 4.
Each Provisioning Agent bundle wraps in itself a set of components enabling the initiation of the provisioning procedure, the providing and storing of provisioning properties, and providing means of multicast discovery of devices. Such a bundle contains in itself the following components:
- Provisioning Service
- Provisioning Info Providers:
- Environment Info Provider
- HTTP Provisioning Info Provider
- File Provisioning Info Provider
- Provisioning Storage – The CM Storage is included in the prvagent.jar bundle. The File storage is delivered by the prvagent_fs.jar file.
- Multicast Discovery Agent
Custom Provisioning Agents
The custom provisioning agent may provide a suitable set of transport and security settings for the specifics of the managed device, and all additional settings for its further management (Optional RM features, Platform Profile, etc.). The custom provisioning agent may be stored locally on the RM backend, and uploaded on the device in some (non-RM) way. After the agent is transferred on the device, it will initiate the provisioning procedure to the RM backend from the device.
Provisioning Setup and Configuration
To perform the initial provisioning of the device, the following sequence of steps must be taken:
- Install and start the appropriate URL handler (if such is necessary) for the scheme you intend to use.
Install and start the appropriate Provisioning Agent bundle on the device.
JAR files of the provisioning agent bundles and URL handler bundles are located at the <RM_HOME>/initial_provisioning directory.
- Set the initial provisioning properties in the suitable way for the provisioning info provider(s) you intend to use.
Installing URL Handlers to Enable Provisioning Schemes
- For File scheme – You can use the URL handler available in the JVM itself.
- For HTTP scheme – You need not install any URL handler bundle because this scheme is considered to be supported by all JVMs.
- For HTTPS scheme – Install and start the HTTPS URL Handler bundle (httpshdlr.jar). It uses TLS/SSL provided by the JVM via JSSE. JVMs that have legacy HTTPS handling, such as JDK 1.7, do not need to install httpshdlr.jar.
- For RSH scheme – Install and start the RSH URL Handler bundle (rshhdlr.jar). The bundle uses the cryptographic algorithms provided by the JVM via JCA. Before starting this bundle, you need to provide the following prerequisites:
- The value of the provisioning.rsh.secret property must be set in the provisioning Dictionary to the RSH shared secret between the OSGi platform and the backend. You can do this in one of the following ways:
Use the OSGi Provisioning Service registered by the relevant Provisioning Agent.
Set the RSH shared secret as a value to the provisioning.rsh.secret property in the prm.provisioning.pid configuration, if the Provisioning Agent with CM storage is used (prvagent.jar).
Set the RSH shared secret via File Provisioning Info Provider (see "Setting the Properties in the HTTP Provisioning Info Provider" below). - The shared secret should be available on the backend system as well – specify the file holding it in one of the following ways:
Prior to registration in the node setting "RSH Shared Secret" for the group within the device management tree that will hold the device
At registration time in the Device Node Properties Settings section of the Register OSGi Device wizard shown in the console.
Setting the Properties in the CM Provisioning Storage
These properties can be conveniently set in the prm.provisioning.pid configuration dictionary by using the Gateway Software runtime console or through the Web Admin Console.
Setting the Properties in the File Provisioning Info Provider
The props.txt file available in the File Provisioning Info Provider consists of two parts:
Text properties – These properties are available directly in the props.txt, and must have the <key>=<value> syntax. They are listed after the [TEXT] line of the .txt file.
Binary properties – These are not available in the props.txt but are to be loaded additionally from a ZIP file included in the bundle’s JAR file. The format of lines is: <key>=<jar_entry_where_value_is_stored_as_byte_array>. These properties are listed after the [BINARY] line.
The lines started with "#" are comments. By default, all contents of the props.txt file are commented. To add text properties, uncomment the [TEXT] line. To add binary properties, uncomment the [BINARY] line.
For example, the content of the props.txt file can be:
# TEXT section contains properties that are to be load directly at load phase# The format of lines is :# <key>=<value>[TEXT]provisioning.spid=testdeviceprovisioning.reference=http://localhost:80/prvsetupprm.maloader.url=http://localhost:80/maloader# BINARY section contains properties that are to be load indirectly# The format of lines is :# <key>=<jar_entry>[BINARY]provisioning.rsh.secret=testbinarypropsFor example, when using the RSH provisioning scheme, you can embed the RSH secret shared between the device and the backend into the Provisioning Agent bundle you are about to use. To do this, save the RSH shared secret into a file and add this file as an entry in the Provisioning Agent bundle. Then, set this entry as a value to the provisioning.rsh.secret property in the binary section of the props.txt file.
Setting the Properties in the HTTP Provisioning Info Provider
This service loads properties sent as parameters of POST and GET requests to the /rminit servlet. This service uses a system property which must be set in advance (or left with default value): the prm.require.auth. If its value is false, no user authentication is done. If true, "user" and "pass" parameters must also be included as parameters of the request.
Example: This is an exemplary POST request that the HTTP Provisioning Info Provider can read.
POST /rminit HTTP/1.1Content-Type: application/x-www-form-urlencodedContent-Length: 51user=admin&pass=admin&provisioning.spid=testOSGiDeviceIn some cases, a GET request will not result in setting provisioning properties. If a GET request contains the Get-Id header, no provisioning properties will be set and the response will contain the device ID in the Gw-Id header.
Register Devices Without Initial Provisioning
Additionally you are allowed to register a device without performing initial provisioning. This can be done in two ways:
- Skip the initial provisioning and perform only actual provisioning – To skip the initial provisioning and to perform only actual provisioning, you have to set MA Loader Agent bundle URL <http(s)>://<rm_host with MS role>:<http(s) port>/maloader in the prm.maloader.url property of the provisioning dictionary. For example as a system property. Then you have to install manually the MA Loader Agent bundle JAR file. This procedure is not highly optimized as only the MA Loader Agent bundle data transfer is economized, but all other of the required components (real management agent and the transport provider bundles) are transferred over the network.
- Register a device without getting initial provisioning data – In this case, you have to set the prm.manager.url provisioning property explicitly. The appropriate management agent, communication service and transports must be installed on the OSGi platform. Performing this procedure will decrease the network traffic as there is no data transfer over the network. The shortcomings are that you have to set the provisioning property manually, and when bundles on the backend have been updated, you are supposed to tune manually the managed device framework.
Access Rights for Discovery and Custom Provisioning Agent Generation
The RM allows only users implying specific roles to perform discovery of OSGi devices or create custom provisioning agents.
- Only users participating in the Permission - Provisioning - Create Agent group can create provisioning agents for particular OSGi devices.
- Only users participating in the Permission - Provisioning - Discovery group can launch discovery of OSGi devices.
User Interface for Registering OSGi Devices
You can perform all steps described in this document by using the Register New OSGi Devices wizard in the console. See the Registering New OSGi Devices from the User's Guide.
Initial Provisioning APIs
The Initial Provisioning APIs allow you to develop custom provisioning info providers and/or storages, or to discover devices from the backend. See RM Provisioning APIs from the Programmer's Guide.