Liberty: featureManager command

Use the featureManager command to install features packaged as a subsystem archive (ESA file). Unless we are installing ESA files, use the installUtility command instead. With installUtility, we can manage more asset types and install, find, or download assets from multiple repositories.

We can access the Liberty Repository using the featureManager command through a proxy server. The syntax is...

    featureManager action [options]


Actions

    install Stabilized. Use the installUtility uninstall command instead. Use the featureManager command to install an .esa file to the runtime environment. The featureManager command can download assets from the Liberty Repository.
    uninstall Stabilized. Use the installUtility uninstall command instead.

    Uninstall features using either the feature short name or the feature symbolic name. Ensure that all server processes are stopped before uninstalling a feature. The uninstall action cannot uninstall user features; for example: webCacheMonitor-1.0.

    featureList Generate an XML file containing a report that details all the features installed.
    find Stabilized. Use the installUtility find command instead.

    Generate a list of all assets in the Liberty Repository, find assets in the Liberty Repository that are applicable to the configuration, or view detailed information.

    classpath Generate a JAR file that can be added to a compiler classpath in order to use APIs from a list of features. This action enables us to compile build scripts against the API JARs included in the product without referencing specific JAR names, which can change when a fixpack is applied. The output JAR contains relative paths to the API JARs in the product. We must not move the output JAR to another directory. Note that the --features option must be specified with this action.
    help Display help information for a specified action.


Options

The following options are available for the featureManager install command:

    --acceptLicense Automatically indicate acceptance of license terms and conditions.
    --downloadOnly=[all|required*|none] Download the requested feature to a local directory without installing the feature. This option can be configured to download all the dependent features, the dependent features required for this runtime, or none of the dependent features. The default is to download the required dependent features. Specify the directory with the --location option.

    Note that we cannot use this option if we specify the subsystem archive location with a file name or URL.

    --location=directoryPath When installing a feature, this option specifies a local source directory from which we can install features. When used with the --downloadOnly option, this option specifies a destination directory for downloaded features. This option is required when using the --downloadOnly and --offlineOnly options. Note that we cannot use this option if we specify the subsystem archive location with a file name or URL.
    --offlineOnly Use this option if we do not want to connect to the Liberty Repository. Instead, the command only installs features from the local directory. The local directory is specified with the --location option. Note that we cannot use this option if we specify the subsystem archive location with a file name or URL.
    --to=install_option
    • usr: The feature is installed as a user feature. This is the default value.
    • extension: The location to which we want to install the feature. We can install the feature to any configured product extension location.
    --viewLicenseAgreement View the license agreement.
    --viewLicenseInfo View the license information.
    --when-file-exists=action Action to take if a file to be installed already exists.

    • fail: Cancel the installation.
    • ignore: Continue the installation and ignore the file that exists.
    • replace: Overwrite the existing file.
    --verbose Display any available additional information while the action runs.
    name Features we want to install, separated by a space or comma.

    Feature IDs
    • Short name of the feature, such as adminCenter-1.0
    • Symbolic name of the feature, such as com.ibm.websphere.appserver.adminCenter-1.0

    .esa file

    • Specify a file name, such as my_feature.esa
    • Specify a URL, such as http://myhost.ibm.com/liberty/assets/my_feature.esa

    This action uses the OSGI-INF/SUBSYTEM.MF file from the ESA file as a new feature manifest that can be copied into...

    ...or product extension directory if a value is specified for the --to property) being renamed after the symbolic name of the subsystem. All of the bundles for the subsystem will be extracted into...

    ...and renamed as {bundle symbolic name}_{bundle version}.jar. License files, checksum files, localization files, and other subsystem content will also be extracted to the location defined in the subsystem manifest.

featureManager uninstall command options:

    --noPrompts Uninstall features without any user interaction or confirmation messages.
    --verbose Display any available additional information while the action runs.
    name Specify one or more features to uninstall, separating the names by a space or comma. We can specify the following options:

    • The short name of the subsystem archive (ESA file), such as adminCenter-1.0.
    • The symbolic name of the subsystem archive (ESA file), such as com.ibm.websphere.appserver.adminCenter-1.0.

The following options are available for the featureManager featureList command:

    --encoding=charset where charset is the character set to use when creating the XML report file.
    --locale=language where language specifies the language to use when creating the XML report file. This consists of the ISO-639 two-letter lowercase language code, optionally followed by an underscore and the ISO-3166 uppercase two-letter country code.
    --productExtension=name where name is the product extension name whose features are to be listed. If the product extension is installed in the default user location, use the keyword: usr. If this option is not specified, the action is taken on WebSphere Application Server Liberty Core.
    XML_report_file_name Name of the XML report file we want to create.
    --verbose Display any available additional information while the action runs.

The following options are available for the featureManager find command:

    --viewInfo Displays detailed information.
    --verbose Display any available additional information while the action runs.
    searchString Generates a list of Liberty Repository assets that are applicable to the configuration.

The following options are available for the featureManager classpath command:

    --features=feature1,feature2,... The list of features containing the list of API JAR files. This option is required for the classpath action.
    fileName The name of the generated JAR file.


Usage examples

Install the subsystem archive my_feature.esa as a user feature:

    featureManager install my_feature.esa --to=usr

Install the subsystem archive my_feature.esa to the my_extension product extension location:

    featureManager install my_feature.esa --to=my_extension

Generate a report for all installed features; the report is written to the file my_feature_report.xml using the Brazilian Portuguese language:

    featureManager featureList my_feature_report.xml --locale=pt_BR

Generate a report containing all installed features defined in the product extension installed in the default user location wlp/usr/extension, which is known by the runtime environment as the usr product extension. The report is written to the file my_feature_report.xml:

    featureManager featureList --productExtension=usr my_feature_report.xml

Generate a report containing all features defined in the product extension installed in the location pointed to by the content in the productExtensionName.properties file in the product installation's etc/extensions directory. The report is written to the file my_feature_report.xml:

    featureManager featureList --productExtension=productExtensionName my_feature_report.xml

Display help information for the install action:

    featureManager help install

Install a feature and includes additional information:

    featureManager install extendedPackage-1.0 --verbose

Find assets that are applicable to the configuration:

    featureManager find searchString

List detailed information:

    featureManager find searchstring --viewInfo

Find a feature and includes additional information:

    featureManager find "adminCenter-1.0" --verbose

Download required dependencies from the Liberty Repository to a local directory and do not install them:

    featureManager install feature_shortName --downloadOnly --location=c:\temp\download --acceptLicense

Download all dependencies from the Liberty Repository:

    featureManager install feature_shortName --downloadOnly=all --location=c:\temp\download --acceptLicense

Install features located in a local directory. If there are missing dependencies, they are installed from the Liberty Repository:

    featureManager install feature_shortName --location=c:\temp\download --acceptLicense

Install assets from a local directory without downloading missing dependencies from the Liberty Repository:

    featureManager install feature_shortName --location=c:\temp\download --offlineOnly

Create a classpath JAR file and compiles an application class that uses it:

    featureManager classpath --features=servlet-3.0 classpath.jar javac -cp classpath.jar TestServlet.java

Uninstall a feature:

    featureManager uninstall adminCenter-1.0


Return codes

Return code Explanation
0 The command successfully completed the requested operation.
20 One or more arguments are not valid.
21 A runtime exception occurred because of one or more of the following conditions:

  • A runtime exception occurred while installing the .esa subsystem archive file.
  • A license is not accepted or acknowledged.
  • The .esa subsystem archive file did not extract correctly.

22 The feature that we wanted to install already exists.
23 The feature definition was not valid for one or more of the following reasons:

  • The feature does not have a valid manifest file.
  • The version of the feature is not supported in this Liberty environment.
  • The .zip or .jar file containing the feature files does not exist.

24 The .esa subsystem archive file is missing content.
25 A file that we wanted to install already exists, and you specified the when-file-exists=fail option.
26 The product is not a core product, and the product extension files cannot be found.
27 The product is not a core product, and the product extension is not defined in the ${wlp.install.dir}/etc/extensions/extension_name.properties file.
28 The manifest files for the feature in the product extension cannot be found.
29 The feature is not valid for the current product.
36 Installation of a user feature is invalid for the extension specified: --to=core .