installUtility command

Use the installUtility command to find, obtain information about, and install assets in a directory-based repository, an instance of the Liberty Asset Repository Service, or the Liberty Repository.

    Liberty Repository Public IBM-hosted repository accessible through the internet.
    Liberty Asset Repository Service Open source service used to create an on-premises repository remotely accessible behind the firewall of an enterprise.
    Local directory-based repositories Created using the installUtility download action or by downloading...

    ...which contains all applicable features and addons. We can work with directory-based repository assets directly from this zip file without extracting the archives.


Syntax

The command syntax is as follows:

    installUtility action [options]

The action variable can take one of the following values:

    download Download assets from the repositories.
    find Find assets in the repositories that are applicable to the configuration, or view detailed information about assets.
    install Install assets or an enterprise subsystem archive (ESA) file to the run time, or deploy a server package and install the required features of the package.
    testConnection Test the repository connection.
    uninstall Uninstall features by specifying either the feature short name or the feature symbolic name. Specify multiple features that are separated by a space. Ensure that all server processes are stopped uninstalling a feature.
    viewSets View a template for configuring repositories or a proxy, or view and validate the settings for the configured repositories or proxy.
    help Display help information for a specified action.


Options

installUtility download

    --acceptLicense Accept the license agreement. Users are not prompted to accept a license and the --acceptLicense option is not required when installing Liberty features from Liberty Repository. Users are still prompted to accept the license or the --acceptLicense option is still required when:

    1. Installing user features which carry the license to any Liberty installations
    2. Installing Liberty features for WAS Network Deployment Liberty to WAS Liberty (ILAN) installation
    --viewLicenseAgreement View the license agreement.
    --viewLicenseInfo View the license agreement.
    --location=directoryPath Specify the destination directory for the downloaded assets. This option is required.
    --overwrite Overwrite the existing files when downloading to the local directory. The default behavior without the option is to ignore all the existing files.
    --verbose Display additional information during the download.
    name Specify asset IDs to download one or more of the following assets, separating multiple asset IDs with a space:

    • Features
    • Addons
    • Open source integrations
    • Samples


installUtility find

    --from=directory-based repository Specify a single directory-based repository as the source of the assets for the installUtility command. The directory-based repository can be an uncompressed folder or a compressed archive file. To search for assets in multiple directory-based repositories, configure the repositories in the repositories.properties file.
    --showDescriptions Display the description for each of the features that are found by the search.
    --type=[feature|sample|opensource|addon|all*] Search for the specified type of assets.
    --name Search the asset name for the specified searchString.
    --verbose Display any available additional information while the action runs.
    searchString Finds assets that are applicable to the configuration. If we do not specify a search string, the command searches for all applicable assets.


installUtility install

    --to=install_option
    usr: The feature is installed as a user feature. Default value.
    extension: The product extension location to install the feature.

    Example: installUtility install my_feature --to=usr

    --from=directory-based Specify a single directory-based repository as the source of the assets for the installUtility command. The directory-based repository can be an uncompressed folder or a compressed archive file. To install assets from multiple directory-based repositories, configure the repositories in the repositories.properties file.
    --acceptLicense Indicate acceptance of license terms and conditions.
    --viewLicenseAgreement View the license agreement.
    --viewLicenseInfo View the license information.
    --verbose Display any available additional information while the action runs.
    name
    Asset IDs

    Separate multiple asset IDs with a space:

    • Features
    • Addons
    • Open source integrations
    • Samples

    For example: installUtility install feature1 feature2 feature3

    Server name Install features based on an existing server in the same Liberty environment. Installs applicable features defined in the server.xml file of that server that are not already installed in the Liberty environment.
    Server package Server package created using server package --include=usr. Package deploys and features, defined in server.xml, are installed from the repositories.
    /path/to/server.xml Install any applicable features defined in the server.xml file that are not already installed in the Liberty environment.
    .esa Install a feature from an .esa file on the local file system. Uses the .esa file's OSGI-INF/SUBSYTEM.MF which specifies the name, contents, and dependencies. If --to is specified, the manifest file is copied to...

    ...or the product extension directory. Bundles for the subsystem are extracted into...

    and renamed as...

      {bundle symbolic name}_{bundle version}.jar.

    License files, checksum files, localization files, and other subsystem content are extracted to the location defined in the subsystem manifest.


installUtility testConnection

    repoName Name of the repository to be tested. If not specified, all repositories specified in the repositories.properties file are tested.


installUtility uninstall

    --force Uninstall the specified feature regardless of whether other installed features have dependencies on it. Uninstall a feature that is required by other installed features might cause those features to stop working and might prevent servers from running correctly.
    --noPrompts Uninstall the feature without prompts. The default is false.

    installUtility uninstall --noPrompts feature1 feature2 feature3

    --verbose Display additional information during the uninstallation.
    name Specify features to uninstall. Separate multiple names with a space.

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

      installUtility uninstall adminCenter-1.0

    To uninstall user features and product extensions, prefix the feature name with the extension followed by a colon.

      installUtility uninstall usr:webCacheMonitor-1.0


installUtility viewSets options

    --viewValidationMessages Display the detailed messages from the validation of the configured repositories.properties file. Each message contains an error code, the line number where the error was found, and the cause of the error.


Usage examples

Display help information for the install action:

    installUtility help install

Install a user feature:

    installUtility install my_feature --to=usr

Install a user feature to the my_extension product extension location:

    installUtility install my_feature --to=my_extension

Install multiple features:

    installUtility install feature1 feature2 feature3

Install a sample:

    installUtility install JDBCSample

Install a feature bundle addon from a single local directory-based repository:

    installUtility install ndMemberBundle --from=c:\download\wlp-featureRepo-16.0.0.2

Install a feature bundle addon from a single compressed directory-based repository archive:

    installUtility install ndMemberBundle --from=c:\download\wlp-featureRepo-16.0.0.2.zip

Install a server:

    installUtility install myServer

Install a server package compressed .jar file:

    installUtility install c:\temp\myServer.jar

Install a local .esa file:

    installUtility install c:\temp\myFeature.esa

Install a server package compressed file:

    installUtility install c:\temp\myServer.zip

Find assets that are applicable to the configuration:

    installUtility find searchString

Find samples that are applicable to the configuration:

    installUtility find searchString --type=sample

Find a particular feature that is applicable to the configuration:

    installUtility find webCacheMonitor-1.0 --name --type=feature

List detailed information:

    installUtility find searchstring --showDescriptions

Download required dependencies from the repositories to a local directory:

    installUtility download feature_shortName --location=c:\temp\download --acceptLicense

Test the connection to the Liberty Repository:

    installUtility testConnection default

Uninstall a feature:

    installUtility uninstall adminCenter-1.0

Uninstall a user feature or product extension:

    installUtility uninstall usr:webCacheMonitor-1.0

Uninstall multiple features:

    installUtility uninstall feature1 feature2 feature3

Uninstall multiple features without prompts:

    installUtility uninstall --noPrompts feature1 feature2 feature3


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 during the installation of the .esa subsystem archive file.
  • A license is not accepted or acknowledged.

  • The .esa subsystem archive file did not extract correctly.
22 The feature to be installed 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 to be installed exists.
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.
30 The repositories.properties file failed the validation.
33 The connection to the repository failed.
34 The repository name is not found. The provided repository name does not exist in the configuration file.
35 The action was canceled by the user.
36 Installation of a user feature is invalid for the extension specified: --to=core .