115 Auto Configuration Specification

Version 1.0

115.1 Introduction

The purpose of the Auto Configuration specification is to allow the configuration of bundles. These bundles can be embedded in Deployment Packages or bundles that are already present on the OSGi Framework. This specification defines the format and processing rules of a Autoconf Resource Processor. Resource processors are defined in Deployment Admin Specification.

An Auto Configuration Resource contains information to define Configuration objects for the Configuration Admin Service Specification.

115.1.1 Entities

  • Autoconf Resource - One or more resources in a Deployment Package that are processed by the Autoconf Processor.

  • Deployment Package - A named and versioned file that groups resources into a single management unit. Deployment packages are the unit of deployment and uninstallation. Deployment packages can contain bundles and associated deployment-time resources that are processed by Resource Processors.

  • Resource Processor - A deployment-time customizer that accepts a resource in a Deployment Package and turns it into a number of artifacts. A resource processor is a service that implements the ResourceProcessor interface.

  • Autoconf Resource Processor - The Resource Processor that processes the autoconf resources in a Deployment Package.

Figure 115.1 Autoconf Context Diagram

Autoconf Context Diagram

115.1.2 Synopsis

A Deployment Package can contain one or more Autoconf resources. The Manifest of the Deployment Package connects this resource to the Autoconf Resource Processor. When the Deployment Package is deployed, the Autoconf Resource Processor reads the information from the Autoconf resources and creates Configuration objects: both Managed Service as well as Managed Service Factory Configuration objects.

When the Deployment Package is updated or uninstalled, the Autoconf Resource Processor must delete the appropriate Configuration objects.

115.2 Configuration Data

Bundles usually require configuration data when they are deployed. For example, a bundle that has to contact a central server needs one or more server URLs. In practice, a complete application can consist of:

  • A number of bundles

  • Their configuration data

  • Other required resources

The Deployment Package allows such an application to be installed, updated, and uninstalled in a single operation. This specification extends the Deployment Package with a facility to create Configuration objects. The extension uses the Resource Processor mechanism to read one or more resources from the Deployment Package and create Configuration objects based on these resources.

For example, a Deployment Package contains a single bundle Chat. This bundle, when started, registers a Managed Service with a PID of com.acme.pid.Chat. The expected Configuration Dictionary contains a single property: serverurl.

The schema explanation for an Autoconf resource can be found in Metatype Service Specification. An Autoconf resource could look like:

<?xml version="1.0" encoding="UTF-8"?>

  <OCD id="ChatConfiguration">
    <AD id="server" type="String">

  <Designate pid="com.acme.pid.Chat" 
    <Object ocdref="ChatConfiguration">
        <Attribute adref="server" name="serverurl" 


The OCD element (an abbreviation of Object Class Definition) defines the type of the Configuration Dictionary. This typing is based on the Metatype Service Specification. The Designate element links the configuration data to a PID. This PID is the PID for the configuration object. The content is defined in an Object element. An Object element links to an OCD element and defines the values of the attributes in Attribute elements.

The Autoconf Resource Processor in the example is instructed by this resource to create a Managed Service Configuration object with a Dictionary object that contains serverurl="http://chat.acme.com".

An Autoconf resource can configure Managed Service configurations, as long as the bundle is contained in the same Deployment Package. For bundles that are not contained in the Deployment Package, a.k.a. foreign bundles, only Managed Service Factory configurations can be created. Configuring foreign bundles with a Managed Service configuration could create ownership conflicts and is therefore explicitly not allowed.

The Autoconf Resource Processor must be able to handle installations, updates, and uninstallations of Deployment Packages.

115.3 Processing

The Autoconf Resource Processor must register itself with the following PID to become available to the Deployment Admin service:


The Autoconf Resource Processor must process each Designate element in order of appearance. This element has the following information:

  • pid - The PID of the Configuration object. If the Configuration object is a factory configuration, the PID is actually an alias of the actual PID because a factory configuration PID is generated.

  • factoryPid - (String) Defines a factory PID when this Designate is a factory configuration; otherwise it is for a singleton configuration.

  • bundle - The location of the bundle. It must be used to set the location of the Configuration object. This attribute is mandatory for autoconf though it is not mandatory for the schema because other applications might not need a bundle location.

  • merge - (true|false) Indicates that the value of the contained Object definition replaces (merge=false) the configuration data, or only replaces properties (merge=true) that do not exist in the configuration data.

  • optional - (true|false) If true, then this Designate element is optional, and errors during processing must be ignored. Otherwise, errors during processing must abort the installation of the Deployment Package. This requires the undoing of any work done so far.

The content of a Designate element is an Object element. This element contains the value for the configuration Dictionary.

If the Designate element was marked optional, then any errors during these steps can be ignored and the next Designate element must be processed.

A factory configuration is processed differently from a singleton configuration. These two different processing methods are discussed in the following sections.

115.3.1 Factory Configurations

Factory configurations can be created and deleted any number of times. This concept of multiplicity makes it straightforward to associate factory configurations with a Deployment Package. Each Deployment Package can create its unique configurations that are independent of any other Deployment Packages. When the Deployment Package is uninstalled, the created configurations can be deleted without any concern for sharing.

A factory configuration is defined in a Designate element. The factoryPid must be set to the PID of the related Managed Service Factory service. For example:

 <Designate pid="a" factoryPid="com.acme.a"
    <Object ocdref="a">
        <Attribute adref="foo" content="Zaphod Beeblebrox"/>

The Autoconf resource cannot use the actual PID of the Configuration object because the Configuration Admin service automatically generates the PID of factory configurations. This created PID is called the actual PID.

The Autoconf resource author cannot know the actual PID ahead of time. The Autoconf resource must therefore specify a alias. The alias does not have to be globally unique; it must only be unique for a specific Autoconf resource. The Autoconf Processor must maintain the following association (per Autoconf resource):

 alias  actual PID

The alias can be viewed as an Autoconf resource local name for the factory configuration PID. The actual PID is generated when the Autoconf processor creates a new factory configuration. This mapping is identical to the mapping defined for the Configuration Admin Plugin.

The alias actual PID association must be used by the Autoconf Processor to decide what life cycle operation to execute.

  • Alias - This installation is a first-time installation of the factory configuration. The Autoconf resource specifies a factory configuration that was not part of a previous installation. The Autoconf Processor must therefore create a new factory configuration, set the configuration dictionary to the values in the Object element (see Assigning a Value ), and create the Alias Actual association.

  • Alias Actual - The factory configuration already exists from a previous Autoconf resource installation. The Autoconf Processor must merge or override (depending on the merge attribute) the Configuration object designated by the actual PID with the values in the Object element (see Assigning a Value ).

  • Actual - The Autoconf resource no longer contains an alias that it previously contained. The configuration identified by the actual PID must be deleted.

Uninstalling an Autoconf resource requires that the Autoconf Resource Processor deletes all Configuration objects associated with the resource.

115.3.2 Singleton Configuration

A singleton configuration is associated with a Managed Service. The Autoconf Resource Processor must only use singleton configurations for bundles that are contained in the same Deployment Package as the Autoconf resource. The target Deployment Package can provide a list of these bundles.

This ownership policy is required to prevent sharing conflicts. For this reason, the bundle attribute in the Designate element must be set to the location of the bundle so that this ownership is enforced by the Configuration Admin service. The location of the bundle is defined by the Bundle Symbolic Name of the given bundle prefixed with osgi-dp:.

The processing must abort with a fatal error if the bundle attribute is not set. The Autoconf Resource processor must bind the singleton configuration to the given bundle.

If a singleton configuration with a given PID already exists, it must be unbound or bound to the same location contained by the bundle attribute. Otherwise the processing must abort.

The singleton configuration must be merged with or replaced by the information in the Object element, depending on the merge attribute as described in Assigning a Value.

115.3.3 Example

For example, bundle A uses a factory configuration with the factory PID com.acme.a and bundle B uses a singleton configuration with PID com.acme.b. They define the following configuration properties:

gear            Integer
ratio           Vector of Float

foo             String
bar             Short[]

For proper operation, a Deployment Package P needs a configuration for com.acme.a and com.acme.b with the following values:

    gear        = 3
    ratio       = {3.14159,  1.41421356, 6.022E23}
    foo         = "Zaphod Beeblebrox"
    bar         = {1,2,3,4,5}

The corresponding autoconf.xml resource associated with Deployment Package P would look like:

<?xml version="1.0" encoding="UTF-8"?>

  <OCD id="a">
    <AD id="gear"  type="Integer" cardinality="0" />
    <AD id="ratio" type="Float" cardinality="-3" />

  <OCD id="b">
    <AD id="foo"   type="String" cardinality="0"/>
    <AD id="bar"   type="Short" cardinality="5"/>

  <Designate pid="x" factoryPid="com.acme.a" 
    <Object ocdref="a">
        <Attribute adref="gear" content="3" />
        <Attribute adref="ratio">

  <Designate pid="com.acme.b"        
    <Object ocdref="b">
        <Attribute adref="foo" content="Zaphod Beeblebrox"/>
        <Attribute adref="bar">

115.3.4 Assigning a Value

The Autoconf resources share a scheme and can cooperate with the Metatype Service Specification. An Autoconf resource primarily contains a number of values for configuration objects in the Designate elements. Designate elements:

  • Are for a factory or singleton configuration (factoryPid attribute)

  • Are bound to a bundle location (bundle attribute)

  • Are meant to be merged with an existing value or replace an existing value (merge attribute). Merging means only setting the values for which the existing Configuration object has no value.

  • Provide a value for the Configuration object with the Object element.

Designate elements contain an Object element that contains the actual value. Object elements refer to an OCD element by name. The OCD elements act as a descriptor of the properties.

The OCD elements that are referred from an Object element can be contained in the Autoconf resource, or they can come from the Meta Type service. The reference takes place through the ocdref attribute of the Object element. The Autoconf Resource Processor must first match this name to any OCD elements in the Autoconf resources. If the reference cannot be found in this file, it must consult the Meta Type service (if present) for the bundle that is associated with the PID that is configured.

115.3.5 Process Ordering

The Autoconf Processor must create any factory and singleton configurations when it is called with an Autoconf resource. This phase should perform as much validation as possible. The configurations must be created in the order of appearance in the Autoconf resource.

In the commit method, the Autoconf Resource Processor must first delete all Configuration objects that were uninstalled. Thereafter, it must set or update the appropriate Configuration objects.

This ordering implies that a customizer bundle cannot receive configuration parameters from an Autoconf resource.

115.4 Security Considerations

Allowing a deployment package's Autoconf resources to (re)configure arbitrary configurations creates security threats. The possible threats are discussed in the following sections.

115.4.1 Location Binding

As described in Configuration Admin Service Specification, it is possible for a malicious bundle to register a Managed Service under a PID used by another (legitimate) bundle. This activity essentially hijacks the Managed Service PID, and constitutes a denial of service attack on the legitimate bundle (as it never receives the configuration information it needs). The Configuration Admin specification describes a location binding technique that can be used to prevent this attack. The Autoconf Resource Processor must bind Configuration objects to locations specified in the Autoconf resources using the mandatory bundle attribute.

115.4.2 Autoconf Resource Permissions

The capabilities of an Autoconf Resource Processor must be limited to the permissions that are granted to the signer of a Deployment Package. This is the specified way for the Deployment Admin service to act. The Autoconf Resource Processor does not have to take any special actions; all its actions are automatically scoped by the signer of the Deployment Package.

This restriction implies, however, that the Autoconf Resource Processor must do a doPrivileged method for any actions that should not be scoped: for example, when it persists the associations of the alias actual PID.

A Deployment Package that requires any activity from the Autoconf Resource processor must at least provide ConfigurationPermission[*,CONFIGURE].