Liberty feature manifest files
A Liberty feature consists of a feature manifest file and a collection of one or more OSGi bundles that provide classes and services corresponding to a particular capability in the Liberty runtime environment. You can find the introduction of the format of a feature manifest and the meaning of each header in the manifest file.
The feature manifest file in Liberty uses the Subsystem Service metadata format in the OSGi Enterprise R5 specification. A feature is defined by a feature manifest file (.mf file) that is stored in the lib/features directory, and must use a custom type of Subsystem: osgi.subsystem.feature. For more information on OSGi manifest syntax, see section 1.3.2 of the OSGi core specification.
Header | Description | Required? |
---|---|---|
Subsystem-ManifestVersion | The version format for the feature manifest file. Must be set to 1. | No |
Subsystem-SymbolicName | The symbolic name of the feature and any attributes or directives. | Yes |
Subsystem-Version | The version of the feature. See the OSGi core specification section 3.2.5 for the details of how this is defined. | No |
Subsystem-Type | The subsystem type for the feature. All features are currently of the same subsystem type: osgi.subsystem.feature. | Yes |
Subsystem-Content | The subsystem content of the feature. This is a comma separated list of bundles and subsystems that are required to run this feature. If you want to allow the auto feature to be configured in the server.xml file, you must have the capability header containing the required features, and also have them defined in the subsystem content. | Yes |
Subsystem-Localization | The location of the localization files for the feature. | No |
Subsystem-Name | A short, human readable name for the feature. This value can be localized. | No |
Subsystem-Description | A description of the feature. This value can be localized. | No |
IBM-Feature-Version | The version of this subsystem type. Must be set to 2. | Yes |
IBM-Provision-Capability | The capability header that describes whether a feature can be provisioned automatically. | No |
IBM-API-Package | The API packages that are exposed to applications by this feature, features in other product extensions, and the Liberty kernel. | No |
IBM-API-Service | The OSGi services that are exposed to OSGi applications by this feature. | No |
IBM-SPI-Package | The SPI packages that are exposed by this feature to features in other product extensions, and the Liberty kernel. | No |
IBM-ShortName | The short name of the feature. | No |
IBM-AppliesTo | The Liberty version that this feature applies to. | No |
Subsystem-License | The license type for this feature. | No |
IBM-License-Agreement | The prefix of the location of the license agreement files. | No |
IBM-License-Information | The prefix of the location of the license information files. | No |
IBM-App-ForceRestart | Specifies that applications are to be restarted when the feature is installed to, or uninstalled from, a running server. | No |
Subsystem-SymbolicName
The syntax for this header matches the Bundle-SymbolicName syntax for a bundle. It has a symbolic name that follows the package names style syntax, and can optionally take a set of attributes and directives.
- superseded. This attribute indicates whether
this feature is superseded by one or more features or items of functionality.
It takes one of the following values:
- true - The feature is superseded.
- false - The feature is not superseded.
For more information, see Superseded Liberty features.
- superseded-by. This attribute specifies a comma-separated list of the features that supersede this feature, if any, and is optional.
- visibility. This directive takes one of the
following values:
- public - Feature considered to be API. The feature is supported by the developer tools, for use in the server.xml file, and output in messages.
- protected - Feature considered to be SPI. The feature is not supported by the developer tools, for use in the server.xml file, or output in messages. The feature is provided so extenders can make use of it to build higher level features.
- private - (default) The feature is product internals. The feature is not supported for use in the server.xml file or to be referenced by extender features. The feature can be changed at any time, including between fix packs.
Subsystem-SymbolicName: com.ibm.example.feature-1.0;
visibility:=public; superseded=true; superseded-by="com.ibm.example.feature-2.0"
IBM-ShortName: appSecurity-1.0
Subsystem-SymbolicName: com.ibm.websphere.appserver.appSecurity-1.0; visibility:=public;
superseded=true; superseded-by="appSecurity-2.0, [servlet-3.0], [ldapRegistry-3.0]"
For
more information, see Separated
features.- singleton.
This directive takes one of the following values:
- True. The feature is a singleton.
- False. The feature is not a singleton.
The singleton directive is optional. The default value is False.
This directive is used to declare that a particular feature is a singleton. A singleton means that only one version of a given feature can be loaded into the runtime at a time. By default, features are not singletons. If the feature is a singleton and multiple versions of a given feature are required by the server configuration, then the runtime will attempt to find a common version that is tolerated by all requiring features. For more information on version toleration, see the ibm.tolerates directive under Subsystem-Content.
When a feature is a singleton, then the symbolic name value is in the form "<singleton feature name >-<singleton version>", where the name and version are separated by a hyphen. The singleton feature name can contain hyphens, but the characters following the last hyphen will be interpreted as the singleton version. If the characters following the last hyphen are not a valid version, then a singleton version of 0.0.0 is used and the complete symbolic name is used as the singleton name. The singleton version is used when processing "ibm.tolerates directives under Subsystem-Content; for example:Subsystem-SymbolicName: com.ibm.example.feature-1.0; visibility:=public; singleton:=true
Subsystem-Content
Subsystem-Content ::= content ( ',' content )*
content ::= unique-name ( ';' parameter )*
unique-name ::= unique-name (see OSGi core spec section 1.3.2)
- version - The range of versions to be matched when finding a bundle. Only bundles in this range are selected. A typical example of the version range is [1,1.0.100).
- type - The type of content to be provisioned.
You can specify any value to indicate the content type; some types
will result in bundles being installed and started in the OSGi framework
of a server that uses the feature, all types will cause the content
to be included in an installation package that includes the feature.
The following values are predefined:
- osgi.bundle - This is the default value and indicates an OSGi bundle that must be provisioned both into the OSGi framework of the server and an installation package.
- osgi.subsystem.feature - This value indicates that the feature must be provisioned both into the OSGi framework of the server and an installation package. These features need to use the name specified in Subsystem-SymbolicName header.
- jar - This value indicates that a JAR file must be included in an installation package and is selected by using a combination of a version range, a location value, or both.
- file - This value indicates that the file identified in the location attribute must be included in an installation package.
- location - The location of the bundle. For a bundle or JAR type, this value
can be a comma separated list of directories that is used to identify spec and API bundles in the
dev directory, or a single entry pointing directly to the JAR file. When the
type is file, only a single entry is allowed and it must
point directly to that file.For example:
Subsystem-Content: com.ibm.websphere.appserver.api.basics; version="[1,1.0.100)"; type=jar; location:="dev/api/ibm/,lib/", com.ibm.websphere.appserver.spi.application; location:="dev/spi/ibm/com.ibm.websphere.appserver.spi.application_1.0.0.jar"; type="jar", com.ibm.websphere.appserver.spi.application_1.0.0-javadoc.zip; location:="dev/spi/ibm/javadoc/com.ibm.websphere.appserver.spi.application_1.0.0-javadoc.zip"; type="file"
- start-phase - The start phase when the bundle must start during system
startup. The start-phase directive can take one of the following values:
- SERVICE - This value indicates the earliest phase. By default it maps to a start level of 9.
- CONTAINER - This is the default value if no start-phase is provided. It indicates the container phase when application containers are started. By default it maps to a start level of 12.
- APPLICATION - This value indicates the latest phase when applications are started.
- ibm.tolerates -
Specifies alternative singleton version or versions of a singleton
feature,type=osgi.subsystem.feature, to be provisioned into the system if there
are version conflicts.
The unique-name specifies the symbolic name of the preferred version of a singleton feature. If the including feature is known to work with other singleton versions of a given singleton feature, then these singleton versions can be specified using the ibm.tolerates directive. This gives greater compatibility to the defining feature in the case that other features define conflicting required version values of a given singleton feature.
Singleton versions listed in the ibm.tolerates directive are only used in the case of a version conflict. The ordering of versions listed in the ibm.tolerates directive is not significant - any version listed in the ibm.tolerates directive can be selected to satisfy dependency requirements.
The tolerated version or versions of a given singleton feature must be explicitly listed in the ibm.tolerates directive. Use commas to separate a list of tolerated versions. Specifying a version range is not supported.
For example:Subsystem-Content: com.ibm.websphere.appserver.example.featureA-1.1; ibm.tolerates:="1.2"; type="osgi.subsystem.feature", com.ibm.websphere.appserver.example.featureB-1.1; ibm.tolerates:="1.2, 1.4, 1.6"; type="osgi.subsystem.feature"
Note:Tolerated versions are not transitive. This prevents a feature that your feature depends on from being automatically opted in to supporting a later level of a feature, without having tested it.
For example: User feature featureC-1.1 includes sipServlet-1.1 in the Subsystem-Content header of its manifest file. sipServlet-1.1 includes servlet-3.0 and tolerates servlet 3.1. If featureC-1.1 was written before servlet-3.1 existed and then servlet-3.1 was added and tolerated by the feature used by it (sipServlet-1.1), featureC-1.1 should have a say on whether it also tolerated servlet-3.1.
If you configure the server.xml file to have the following two features:
You will see an error message resembling the following displayed:<feature>usr:featureC-1.1</feature> // includes: sipServlet-1.1 <feature>websocket-1.0</feature> // this feature requires servlet-3.1
CWWKF0033E: The singleton features servlet-3.0 and servlet-3.1 cannot be loaded at the same time. The configured features usr:featureC-1.1 and websocket-1.0 include one or more features that cause the conflict. Your configuration is not supported; update server.xml to remove incompatible features."
This error is reported because featureC-1.1 is not opted in to tolerating servlet-3.1, and so has to have servlet-3.0, and websocket-1.0 does not support servlet-3.0 and so has to have servlet-3.1.
The solution is for featureC-1.1 to also directly depend on servlet-3.0 and tolerate servlet-3.1.





- ibm.executable - Adds the execute permission
to the associated file, according to the current umask setting, when
the value is set to "true". Any other value will
result in no action taken. The following table shows the current umask
and which class gets the execute permission.
Table 2. Examples of umask values and classes with execute permissions set by ibm.executable Umask Execute permissions granted to class 022 owner, group, other 023 owner, group 055 owner
Subsystem-Localization
This header specifies the location of the localization files for the feature.
Subsystem-Localization: OSGI-INF/l10n/loc
Subsystem-Name
Use this header to supply a short, human readable name for the feature. You can specify either a literal string or a property name. If you a specify a property name, the value can be localized.
Subsystem-Name: %name
where the value of name
is defined in a properties file at the location specified by the
Subsystem-Localization header (loc.properties in the previous example), in the
following format:name=feature_name
Subsystem-Description
Use this header to supply a description for the feature. You can specify either a literal string or a property name. If you a specify a property name, the value can be localized.
Subsystem-Description: %desc
where the value of
desc is defined in a properties file at the location specified by the
Subsystem-Localization header (loc.properties in the previous example), in the
following format:desc=feature_description
IBM-Provision-Capability
Automatically provisioned features are features that have the IBM-Provision-Capability header in the manifest. This header describes other features that must be provisioned for this feature to be automatically provisioned. When listing the other features, use the Subsystem-SymbolicName header of the feature. When any features are configured in the server.xml file, the runtime checks to see whether any automatically provisioned features have had their capabilities satisfied, and if any have, they are automatically provisioned.
The format of the IBM-Provision-Capability header uses standard OSGi LDAP filters.
IBM-API-Package
This header is used to indicate which API packages are visible to applications. It matches the Export-Package header syntax. This means it is a comma separated list of API packages, but each API package can have some attributes.
- type - The type of API package. The type attribute
takes one of the following values:
- spec - Indicates an API provided by a standard body, such as javax.servlet or org.osgi.framework.
- ibm-api - Indicates a value-add API provided by IBM®.
- api - Indicates a user-defined API. This is the default value.
- third-party - Indicates an API that is visible, but not controlled by IBM. Typically, these are open source packages.
- internal - Indicates non-API packages that must be exposed to applications for them to function. This might be used if Java™ code is bytecode enhanced, or weaved, to add references to internal code at run time.
IBM-API-Package: javax.servlet; type="spec",
com.ibm.websphere.servlet.session; type="ibm-api",
com.ibm.wsspi.webcontainer.annotation; type="internal"
IBM-API-Service
This header is used to indicate which services from the feature are visible to OSGi applications. The feature must also register the service in the OSGi service registry.
IBM-API-Service ::= service ( ',' service )*
service ::= service-name ( ';' attribute )*
service-name ::= unique-name
The service-name is
the Java class or interface
name of the service. The attributes are interpreted as the service
properties for the services.IBM-API-Service: com.ibm.example.service.FeatureServiceOne;
myServiceAttribute=myAttributeValue,
com.ibm.example.service.FeatureServiceTwo
If an OSGi application want to use the services provided by the IBM-API-Service header, the application must include a blueprint reference to the service in order for the service to be provisioned into the application.
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
<reference id="FeatureServiceOneRef"
interface="com.ibm.example.service.FeatureServiceOne" />
</blueprint>
In order for a service to be usable by a bundle in an OSGi application, the interface package must be available to that bundle, which means the interface package must be specified by an Import-Package header in the manifest file of the consuming bundle. The interface package must also be specified by an Export-Package header in a feature bundle and specified in the IBM-API-Package header of the feature manifest file. The service provided by a feature must be registered in the OSGi service registry by using the OSGi BundleContext interface or any other mechanism such as Declarative Services or Blueprint. For more information, see Developing an OSGi bundle with simple activation and Composing advanced features by using OSGi Declarative Services.
IBM-SPI-Package
When you create your own Liberty feature, you install it into the user product extension. All the packages in your feature can be accessed by any other feature that is installed into the user product extension. However, if you want a package in your feature to be accessed by a feature that is installed into another product extension, you must list the package name in the IBM-SPI-Package header.
Any package listed in the IBM-SPI-Package header must be exported by a bundle in the Liberty feature, by being listed in the Export-Package header of the bundle manifest file.
IBM-ShortName
This header is a short name for a feature that you can use to specify a feature in the server.xml file. If there is no IBM-ShortName header in the manifest file, then the Subsystem-SymbolicName is used by default. The IBM-ShortName header is only valid for public features.
IBM-AppliesTo
product_id; productVersion=product_version; productInstallType=product_install_type; productEdition=product_editions
If you supply more than one item, the value of product_id must be different for each one.
The value of productVersion can be either an exact version, such as 8.5.5.7, or a minimum version, denoted by the version ending with a plus sign, +, such as 8.5.5.7+.
The value of productEdition can be either a single edition or a comma-separated list of editions enclosed in quotation marks.
IBM-AppliesTo: com.ibm.websphere.appserver; productVersion=8.5.5.6; productInstallType=Archive; productEdition="BASE,DEVELOPERS,ND"
Subsystem-License
This header defines the license type for this feature. If you supply a value for the Subsystem-License header, and do not supply values for the IBM-License-Agreement and IBM-License-Information headers, then the Subsystem-License header value is displayed to the user for acceptance during installation.
If there is a feature already installed with the same Subsystem-License header value, then the license is not displayed, and license approval is not sought, during the installation. If dependencies in the Subsystem-Content header mean that there are two or more features being installed that have the same Subsystem-License header value, the user has only to accept the license once during installation.
Subsystem-License: L-JTHS-93TMHH
Subsystem-License: http://www.apache.org/licenses/LICENSE-2.0.html
IBM-License-Agreement
This header specifies the prefix of the location of the license agreement files. Supply the file path in the subsystem archive to the LA_language files, up to, but not including, the "_" character (the language code is appended by the installation tool). If this license has not been accepted, the user must accept the license when installing the feature. The license files are copied to the Liberty installation directory.
IBM-License-Agreement: lafiles/LA
IBM-License-Information
This header specifies the prefix of the location of the license information files. Supply the file path in the subsystem archive to the LI_language files, up to, but not including, the "_" character (the language code is appended by the installation tool). If this license has not been accepted, the user must accept the license when installing the feature. The license files are copied to the Liberty installation directory.
IBM-License-Information: lafiles/LI
IBM-App-ForceRestart
- install - restart applications when the feature is installed.
- uninstall - restart applications when the feature is uninstalled.
- install,uninstall - restart applications when the feature is installed or uninstalled.
Example feature manifest file
<featureManager>
<feature>usr:example-1.0</feature>
</featureManager>
Configuration of this feature in a
server will result in the specified bundle, com.ibm.example.bundle1,
being installed and started in the OSGi framework of the server runtime
environment. The single API package, com.ibm.example.publicapi,
will be visible to all applications in that server, except for Java EE applications that are configured
to not have visibility to the api package type.
OSGi applications must explicitly import the package if they wish
to use it. The two SPI packages, com.ibm.example.spi.utils and com.acme.spi.spiservices,
will be visible to all feature code in the server, as will the API
package.IBM-Feature-Version: 2
Subsystem-ManifestVersion: 1.0
Subsystem-SymbolicName: com.ibm.example-1.0; visibility:=public
Subsystem-Version: 1.0.0.qualifier
Subsystem-Type: osgi.subsystem.feature
Subsystem-Content: com.ibm.example.bundle1; version="1.0.0"
Subsystem-Localization: OSGI-INF/l10n/loc
Manifest-Version: 1.0
Subsystem-Name: %name
Subsystem-Description: %desc
IBM-API-Package: com.ibm.example.publicapi; type="api"
IBM-SPI-Package: com.ibm.example.spi.utils, com.ibm.example.spi.spiservices
IBM-ShortName: example-1.0