installUtility command

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

Asset sources

The installUtility command can access assets in the following repositories:
  • The Liberty Repository, a public IBM®-hosted repository that is accessible through the internet. For more information, see Liberty Repository.
  • The Liberty Asset Repository Service, an open source service that you can use to create an on-premises repository that is remotely accessible behind the firewall of an enterprise. For more information, see the WASdev/tool.lars project on GitHub.
  • Local directory-based repositories, which you create by using the installUtility download action or by downloading the wlp-featureRepo-<version>.zip file, which contains all applicable features and addons. For more information, see Downloading assets using the installUtility command.

You can use the installUtility command to work with directory-based repository assets directly from compressed repositories, such as wlp-featureRepo-<version>.zip, without extracting the archives. For more information about the wlp-featureRepo-<version>.zip file, see Downloading assets using the installUtility command.

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 your 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. You can specify multiple features that are separated by a space.
Note: Ensure that all server processes are stopped before you uninstall a feature.
viewSettings
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

The following options are available for the installUtility download command:
--acceptLicense
Accepts 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 WebSphere® Application Server Network Deployment Liberty to WebSphere Application Server 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
Use this option to overwrite the existing files when downloading to the local directory. The default behavior without the option is to ignore all the existing files.
--verbose
Use this option to 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

The following options are available for the installUtility find command:
--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, you must configure the repositories in the repositories.properties file. For more information, see Configuring repositories and proxy settings for the installUtility command.

--showDescriptions
Displays the description for each of the features that are found by the search.
--type=[feature|sample|opensource|addon|all*]
Searches for the specified type of assets.
--name
Searches the asset name for the specified searchString.
--verbose
Use this option to display any available additional information while the action runs.
searchString
Finds assets that are applicable to your configuration. If you do not specify a search string, the command searches for all applicable assets.

The following options are available for the installUtility install command:
--to=install_option
The install_option option can take one of the following values:
  • usr: The feature is installed as a user feature. This value is the default value.
  • extension: The location to install the feature. You can install the feature to any configured product extension location.
--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 install assets from multiple directory-based repositories, you must configure the repositories in the repositories.properties file. For more information, see Configuring repositories and proxy settings for the installUtility command.

--acceptLicense
Indicate acceptance of license terms and conditions.
--viewLicenseAgreement
View the license agreement.
--viewLicenseInfo
View the license information.
--verbose
Use this option to display any available additional information while the action runs.
name
Specify one or more assets that you want to install. You can specify the assets in the following ways:
Asset IDs
You can specify asset IDs to install one or more of the following assets, separating multiple asset IDs with a space:
  • Features
  • Addons
  • Open source integrations
  • Samples
Server name
You can install features based on an existing server in the same Liberty environment by specifying the server name. The command installs any applicable features that are defined in the server.xml file of that server that are not already installed in the Liberty environment.
Server package
You can specify a server package that you created by using the server package --include=usr command. The server package deploys, and the required features, which are defined in the server.xml file, are installed from the repositories.
server.xml file
To install features based on a server configuration file, you can specify a path to any local server.xml file, such as C:\localDir\server.xml. The command installs any applicable features that are defined in the server.xml file that are not already installed in the Liberty environment.
.esa file
Install a feature from an .esa file on your local file system. This action uses the OSGI-INF/SUBSYTEM.MF manifest file from the .esa file as a new feature manifest. The manifest file specifies the name, contents, and dependencies of a feature. If you specify the --to option, installUtility copies the manifest file into the ${wlp.user.dir}/extensions/lib/features directory, or the product extension directory. All of the bundles for the subsystem are extracted into the ${wlp.user.dir}/extensions/lib directory 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.

The following option is available for the installUtility testConnection command:
repoName
Specifies the name of the repository to be tested. If not specified, all repositories that are specified in the repositories.properties file are tested.

The following option is available for the installUtility uninstall command:
--force
Uninstall the specified feature regardless of whether other installed features have dependencies on it.
Note: Uninstalling a feature that is required by other installed features might cause those features to stop working and might prevent servers from running correctly.
--noPrompts
Uninstalls the feature without prompts. The default is false.
--verbose
Use this option to display additional information during the uninstallation.
name
Specify one or more features to uninstall, separating multiple names with a space. You 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.

You can uninstall user features and product extensions by prefixing the feature name with the extension followed by a colon, such as usr:webCacheMonitor-1.0.


The following option is available for the installUtility viewSettings command:
--viewValidationMessages
Use this option to 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

Use the following example to display help information for the install action:
installUtility help install
Use the following example to install a user feature:
installUtility install my_feature --to=usr
Use the following example to install a user feature to the my_extension product extension location:
installUtility install my_feature --to=my_extension
Use the following example to install multiple features:
installUtility install feature1 feature2 feature3
Use the following example to install a sample:
installUtility install JDBCSample
Use the following example to install a feature bundle addon from a single local directory-based repository:
installUtility install  --from=c:\download\wlp-featureRepo-16.0.0.2
Use the following example to install a feature bundle addon from a single compressed directory-based repository archive:
installUtility install  --from=c:\download\wlp-featureRepo-16.0.0.2.zip
Use the following example to install a server:
installUtility install myServer
Use the following example to install a server package compressed .jar file:
installUtility install c:\temp\myServer.jar
Use the following example to install a local .esa file:
installUtility install c:\temp\myFeature.esa
Use the following example to install a server package compressed file:
installUtility install c:\temp\myServer.zip
Use the following example to find assets that are applicable to your configuration: 
installUtility find searchString
Use the following example to find samples that are applicable to your configuration: 
installUtility find searchString --type=sample
Use the following example to find a particular feature that is applicable to your configuration: 
installUtility find webCacheMonitor-1.0 --name --type=feature
Use the following example to list detailed information: 
installUtility find searchstring --showDescriptions
Use the following example to download required dependencies from the repositories to a local directory:
installUtility download feature_shortName --location=c:\temp\download --acceptLicense
Use the following example to test the connection to the Liberty Repository: 
installUtility testConnection default
Use the following example to uninstall a feature:
installUtility uninstall adminCenter-1.0
Use the following example to uninstall a user feature or product extension:
installUtility uninstall usr:webCacheMonitor-1.0
Use the following example to uninstall multiple features:
installUtility uninstall feature1 feature2 feature3
Use the following example to uninstall multiple features without prompts:
installUtility uninstall --noPrompts feature1 feature2 feature3

Return codes

Table 1. Return codes and explanations
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 that contains 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 .