Overview

An RM system allows configuration of the backend bundles it contains through the control center and remote access servers. Backend bundle configuration comprises deployment of new bundles and bundle packages, update of already deployed ones, as well as changing the configuration properties and permissions of separate bundles.

Definitions

Configuration of the bundles running on the RM backend comprises management of backend bundle packages, standalone backend bundles, bundle configuration properties, and bundle security permissions.

A backend bundle is an OSGi compliant bundle, intended for deployment on the various RM host roles.

A package is a set of backend bundles, which together deliver a relatively independent feature or functionality to RM. RM itself is distributed in the form of such packages.

Deployment target denotes the types of hosts on which the backend bundle (either in a package or as a standalone bundle) should be deployed - control center, management servers, remote access servers, managed devices, and console. Refer to Backend Infrastructure for more information about backend host roles.

Basic Principles

The RM backend bundle inventory running on the control center and remote access servers handles the maintenance of backend bundles - their deployment on the target hosts, update, removal, bundle configuration and permission assignment.

After a bundle is installed on the designated backend host, it becomes a deployed bundle. The runtime properties (bundle state, registered services, etc.) of deployed bundles can then be monitored. Deployed backend bundles on a particular host can also be remotely started or stopped.

Every deployed bundle must have a unique pair of Bundle-Name and Bundle-Vendor manifest headers within the scope of an RM system.

The information about loaded packages and bundles is kept in the system database, and persists across system and host restarts.

Managing Packages

The configuration of a package includes its deployment, update and removal from the RM system. Operations on packages can be performed only in system configuration mode.

Package Deployment

A package is packed in a JAR file with extension .pack. This JAR holds the JARs of the package's bundles and a package descriptor, which provides basic deployment information to the RM system.

It is also possible to deploy packages not archived in .pack files. Such packages should be stored on the RM control center and their descriptors must be placed in the packages directory of RM's installation. On control center reboot, the configuration manager inspects the packages directory, locates the package descriptors there and deploys the packages the descriptors are for.

Package Descriptor

The package descriptor is an XML file (with extension .xml), which contains the meta data of the package, and is placed in the META-INF directory of the package JAR or in the packages directory of the RM control center.

The package descriptor contains the following information:

• Package Name
• Package Version
• Dependencies on other backend bundle packages
  
  A list of the names and versions of the packages the current one depends on.

• Startup order on the RM backend host
  
  The order, in which the set of the package's bundles is started during backend host startup in the context of the bundle sets of other packages. Possible values and their semantics are compatible with the "Framework Startup and Shutdown" section of the Framework specification from the OSGi Service Platform Specification Release 3.

• Bundles
  • Locations of the package's bundles
  • Bundle deployment targets
    
    The role(s) of backend hosts, on which each package bundle is to be deployed. Possible values are CC (Control Center), MS (Management Server), RAS (Remote Access Server), MC (console), and MD (Managed Device). For more information about these components of RM, refer to the Backend Infrastructure document.

• • Optional flag
    
    Marks a backend bundle as optional if it does not implement some basic functionality of the package, but is an optional extension, which can be installed on demand. By default such a bundle is not deployed runtime, unless deployment is explicitly specified by the bundle's start flag.

• • Start flag
    
    Specifies if the relevant optional bundle should be automatically activated when deployed.

• • Startup order of package bundles
    
    Defines the order in which the package's bundles are started within the package.

• • Package dependence
    
    Defines the dependence of the bundle on one or more packages.

Package Descriptor DTD:

Following is an example descriptor for package "ExamplePack", which contains two bundles - foo1.jar, which is required, and foo2.jar, which is optional. foo1.jar is to be deployed on the control center, management servers and remote access servers participating in the RM system, while foo2.jar is intended to run on management servers only.

Example package descriptor:

Package Activation/Deactivation

After being deployed, packages can be explicitly activated (done by default) or deactivated. When a package is inactive, its bundles are uninstalled from the backend hosts. Then, if activated again, the package bundles are taken from the system database and reinstalled on the specified deployment targets.

The system administrator can also explicitly enable and disable the package bundles indicated as optional.

Package Update

The RM system allows updating of already installed packages with a newer version. There are two options to do this - by providing the whole package containing updated bundles, or by applying a package patch containing only those bundles of the package, which are new or have changed since the previous version.

To update a package, the system administrator can also use the RM static mechanism for package deployment - replace the package descriptor XML and bundles with the new ones on the control center and restart it. On startup, the new package version(s) will be detected and uploaded to all backend hosts.

A package patch is a JAR file with extension .patch, which holds only the JARs of the bundles that should be updated.

Each package patch contains a patch descriptor, which is placed in the META-INF directory of the patch JAR. The patch descriptor contains tags, which specify the previous package version(s), which the patch is applicable for, and the new version, which will become valid after the patch is applied.

Patch Descriptor

The patch descriptor has a structure similar to the package descriptor (see above).

Following is the DTD of the patch descriptor, which has root tag mprm-patch, and defines the previous-version and package-version tags indicating the old version(s) and the new version of the package, respectively.

Patch descriptor DTD:

Following is a descriptor of an example patch for the package as defined above in "Example package descriptor". This patch updates the second bundle - foo2.jar, from the "ExamplePack" package version 1.0.0, and sets the package version to 2.0.0.

Example patch descriptor:

Managing Standalone Backend Bundles

Standalone backend bundles can be associated with the same set of roles as package bundles - control center, management servers, remote access servers, managed devices, and console. In addition, a standalone backend bundle can be deployed on a specific management server. The high-level notion of deploying a bundle on a management server maps physically to deployment of the bundle on every host participating in the management server.

The administration of standalone backend bundles is among the allowed runtime configuration operations. It does not require entering system configuration mode and can be performed over a connection to a remote access server (not only to the control center).

Monitoring Backend Bundles

RM allows monitoring of current backend bundle states on every backend server host. The RM configuration manager presumes that the normal state of every backend bundle is active (started), and always attempts to start all bundles configured for a certain host during the host bootup process. If a startup error occurs with some bundle, the configuration manager will raise an alert. The alert contains information about the specific host, on which the error occurred, and the nature of the error. The system administrator can then locate the host, take appropriate actions, and manually restart the bundle after the cause of the error is corrected.

Managing Backend Bundle Configurations

A backend bundle, either in a package or as a standalone bundle, can declare its own configuration properties in terms of the OSGi Configuration Admin Service Specification. The OSGi Configuration Admin service offers support of XML-structured configuration meta data. For more information about bundle configuration properties, refer to the documentation of the Bosch IoT Gateway Software Framework package (accessible after login).

The RM backend introduces another logical extension to bundle configurations. Every backend bundle configuration is associated with a configuration scope, reflecting the host roles to which the configuration is targeted. The scope can refer to all backend hosts (default scope), or to a distinct host role, including a specific management server.

RM defines role priorities for setting backend bundle configurations on a host with more than one role. Let's consider a host that has simultaneously two roles - A and B. The configuration setting rules are as follows:

• For singleton configurations
  
  Let's have a bundle configuration with instance config1 for role A and instance config2 for role B, and role A is with higher priority than role B. As a result, the config1 configuration instance for role A will be set on the host.

• For factory configurations
  
  Let's have a bundle configuration factory and the following singleton configurations, generated from it:

• On role A - configurations with PIDs pid1 and pid1.2
• On role B - configurations with PIDs pid1 and pid2.2
  
  Again, role A is with higher priority than role B.
  
  The difference from singleton configurations is that factory configurations are merged for different configuration PIDs. The similarity is that configurations with equals PIDs are overridden exactly as in the singleton case. Therefore, the resulting configurations on the host will be pid1 as defined for role A, pid 1.2 and pid 2.2.

The role (scope) priorities in regard to backend bundle configurations are (in descending order):

1. Control center
2. Specific management server
3. Management servers
4. Remote access servers
5. Default scope
   
   The default scope is not a valid host role, but is interpreted in a special way by the configuration setting algorithm. Configurations with the default scope (if they are defined) are always included in the algorithm's calculations with a priority lower than the priority of all valid roles. Therefore, if a role configuration is defined, the algorithm will prefer it, and reversely: if no role configurations exist, the default configuration will be set.

Overwriting Configuration Property Values

Remote Manager grants the possibility to overwrite the pre-configured backend-bundle property values in the default.prs file, so that they are applied even after a system re-install.

When defining a new property value please follow the format:

<backend.bundle.config.pid>.<property-name>=<property-value>

For example:

mprm.ms.gm.gm.cluster.external_distribution=true

Keep in mind that changed property values in the deafult.prs will be applied ONLY on the first system start and are superseded by any other configuration changes.

Managing Backend Bundle Permissions

When the backend hosts participating in an RM system are run with Java security on, the backend bundles should have specific permissions to be able to function properly. Permissions to grant to bundles depend on the security restrictions imposed by the used security model and by the corresponding module. For example, if a backend bundle stores data in a file, it needs file access permissions.

Every permission is defined by its name (its full Java class name), target and actions. These attributes can have only specific values, which are defined by the relevant permission class. For more information about Java permissions, refer to the Java 2 Security Architecture.

Security permissions of a backend bundle can be different on hosts with different roles (control center, remote access servers, management servers, or a particular management server if needed).

It is also possible to assign permissions to a bundle on a specific host at runtime, but the information will not persist over a restart of the host.

RM introduces permission scopes and role priorities for setting backend bundle permissions, in the same way as for backend bundle configurations. Let's have a host that has role A and role B simultaneously, defined bundle permission sets for role A and for role B, and role A is with higher priority than role B. As a result, the bundle permission set for role A will be set on the host.

The role (scope) priorities in regard to backend bundle permissions and the interpretation of the default scope are the same as for backend bundle configurations.

User Interface

By using the console with the appropriate user rights, or the Setup program on the machine running the RM control center, you can configure the packages and backend bundles of the system. You can also manage single host bundles and configurations with commands in a backend host's console. For more information on using these applications for backend bundle management, refer to 

User Guide.

Backend Bundle Configuration API

RM provides an API for using the mechanism for configuring backend bundles.

Refer to Developer Guide for more details on the API usage.