Provisioning Service

A document on illustrating the provisioning features provided by the Initial Provisioning bundle.

Overview

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

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), implemented by a provisioning agent. 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, the service starts the provisioning.

The SDK implementation of provisioning agent is capable of contacting vendor-independent backend management systems and performing flexible initial provisioning according to a set of configuration properties.

More information about the OSGi initial provisioning concept is available in the OSGi Service Compendium Specification.

Registering Bundle

The service is registered by OSGi Provisioning Bundle.

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:

To be able to initiate the provisioning, at least the provisioning.reference property must be available in the provisioning Dictionary!

Provisioning Schemes

To be able to use a particular scheme for the provisioning URL, a URL stream handler for the scheme must be available. The JVM itself usually provides URL handlers for basic schemes like "http" and "file". Additionally, the set of supported provisioning schemes can be extended with custom ones by implementing URL handlers for them. For instance, providing URL handlers in an OSGi R3/R4 specific way may be achieved by implementing and registering an org.osgi.service.url.URLStreamHandlerService. For details on implementing OSGi URL Handlers see the URL Handlers Service Specification, part of OSGi Core Specification Release 5.0.

The Provisioning Service implementation supports three 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 HTTP protocol support of the JVM.
• HTTPS – Based on the HTTPS protocol support of the JVM.
• 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.

General SDK-Specific Provisioning Features

The OSGi Runtime of the SDK introduces additional features to the ones defined by the OSGi Alliance providing extra flexibility and integration capabilities with regard to both the device platform and the backend system.

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 implementation enables two ways of passing properties to the Provisioning Service:

• The backend establishes initial connection to the device and pushes a set of properties to it - The idea is that the backend can "urge" the device to initiate the provisioning. The backend can establish 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 "System Properties") and/or certificate chain (only for HTTPS initial transport). 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 initial connection, the backend actually pushes the provisioning properties through the HTTP Provisioning Info Provider, introduced again additionally in the SDK.

• The essential provisioning properties are set in 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, File (defined in the OSGi Initial Provisioning specification and implemented by the ready-to-use URL providers, see "Provisioning Schemes" above), or any other scheme provided in some way. If a secure scheme is chosen (for example, RSH), the device may have to be authenticated through the means used by the scheme (such as shared secret for RSH scheme). 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.

Providing and Storing 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 SDK-specific types of components: provisioning info providers and provisioning storage.

• SDK info providers - A provisioning info provider supplies provisioning properties to the 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 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. Thus, 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 smart card. See "SDK Provisioning Info Providers" for a list of ready-to-use providers.

  Provisioning info providers can be packed inside the provisioning agent bundle (see "Services"), or can be exported as services by other bundles (see "Creating a Provisioning Info Provider").

• SDK 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 Provisioning Service uses the first storage it finds inside its JAR or exported as 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.

The SDK OSGi Runtime 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.

SDK Provisioning Info Providers

There are four ready-to-use providers wrapped in the Initial Provisioning bundle:

• CM Provisioning Storage – This storage saves provisioning properties in the OSGi Configuration Admin service. It can act as an info provider as well though not a provisioning info provider in the meaning of the SDK providers but it can still be used to provide provisioning properties as a configuration in the OSGi Configuration Admin. See "Setting the Properties in the CM Provisioning Storage" for information about how to set properties in this provider.
• Environment Info Provider – This provider retrieves the provisioning properties from the system properties of the JVM, specified prior to provider's startup. It also retrieves properties available in its BundleContext, such as framework vendor, framework version, etc. See "Setting Properties in the Environment Provisioning Info Provider" for details about providing provisioning properties in the form of JVM system properties.
• HTTP Provisioning Info Provider – This provider loads properties sent as parameters of POST and GET requests to its servlet, available under the /rminit alias. See "Setting the Properties in the HTTP Provisioning Info Provider" for more information about specifying provisioning properties over HTTP.

To be able to use the HTTP Provisioning Info Provider, you must have an HTTP(s) 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.

SDK Provisioning Storages

The Initial Provisioning bundle has only one provisioning storage – CM Provisioning Storage. It 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 the OSGi Provisioning Bundle configuration.

Apart from provisioning storage, it serves for a provisioning info provider, that is, 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.

UDP Multicast Discovery of OSGi Devices

The 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 Provisioning Service accepts a set of system properties for tuning the behavior of SDK's ready provisioning info providers, UDP multicast discovery agent or the general specifics of the provisioning process. Refer to the system properties of the OSGi Provisioning Bundle for more information.

Provisioning Setup

To perform the initial provisioning of the device, the following sequence of steps must be taken:

1. Install and start the appropriate URL handler, if such is necessary for the scheme you intend to use.
2. Make sure the appropriate Initial Provisioning bundle is running in device's OSGi framework.
3. 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 as this scheme is considered to be supported by all JVMs.
• For HTTPS scheme – You need not install any URL handler bundle as this scheme is considered to be supported by most JVMs.

Setting Properties in the CM Provisioning Storage

These properties can be conveniently set in the prm.provisioning.pid configuration dictionary by using the runtime console or through the Web Admin Console. See the OSGi Provisioning Bundle from the Management via Web Console guide for details on the configurable provisioning properties through the CM storage.

Setting Properties in the File Provisioning Info Provider

By default, the File Provisioning Info Provider provides saved data to the Provisioning Service only when the provider is started for the first time (hence the Initial Provisioning bundle is started for the first time). The next time when the provider is started, it considers that provisioning data has been already delivered and is no longer needed, and the File Provisioning Info Provider is disabled. To have the File Provisioning Info Provider always available, set the prm.file.load.once system property to false.

Setting properties in the file provisioning info providers means modifying the props.txt file within the Initial Provisioning bundle JAR file.

The props.txt file 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.

  You can also use a props.txt file outside the Initial Provisioning bundle JAR file - specify its location as value of the prm.file.provider.specfile.location system property.

• 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=testdevice
provisioning.reference=http://localhost:80/prvsetup
# BINARY section contains properties that are to be load indirectly
# The format of lines is :
# <key>=<jar_entry>
[BINARY]
provisioning.rsh.secret=testbinaryprops

Setting 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.

The prm.env.provider.push.starting.with=prm. property is needed to activate a set of extra features in the initial registration such as prm.name=<display-name>.

• prm.name – setting this property provides a device name in Remote Manager tree.
• prm.parent.path – this property may need to be set in order to be able to connect to an Remote Manager server.

This is an exemplary POST request that the HTTP Provisioning Info Provider can read:

POST /rminit HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 51
user=admin&pass=admin&provisioning.spid=testOSGiDevice

In 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.

Setting Properties in the Environment Provisioning Info Provider

This provider maps the provisioning properties to system properties set in the JVM prior to the provider's startup (otherwise restart the Initial Provisioning bundle). The system properties should have the same keys as the provisioning ones. See the System Properties guide for more information about setting system properties in the framework's JVM.

The 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 system property (refer to the System Properties guide) are immediately passed to the provisioning dictionary.