wsinstance command: WAS v5.1

wsinstance command

The wsinstance command creates multiple configuration instances of one initial installation of the product.

Overview

The wsinstance script is based on the base product ANT Utilities feature, which is required.
Each WAS configuration instance is a stand-alone instance with a unique name and its own set of configuration files and user data folders. Configuration folders include config, etc and properties. User data folders include installedApps, installableApps, temp, logs, tranlog and wstemp. Each configuration instance also has the administrative console application to manage the configuration instance. Each configuration instance shares all run-time scripts, libraries, the Software Development Kit, and other files with the initial Application Server.

Location of command file

The command file is located in the $WAS_HOME/bin/wsinstance directory. The command file is a script named wsinstance.sh for Linux and UNIX-based platforms or wsinstance.bat for Windows platforms.

wsinstance.sh command syntax for Linux and UNIX-based platforms

The command syntax is as follows
wsinstance.sh -name instanceName -path instanceLocation -host hostName [-startingPort startingPort] [-readOnly] -create|-delete [-debug]

wsinstance.sh command syntax for Windows platforms

wsinstance.bat -name instanceName -path instanceLocation -host hostName [-startingPort startingPort] [-readOnly] -create|-delete [ -debug]

Parameters

Supported arguments include...

-create|-delete A required parameter that specifies whether to create or delete the configuration instance.

-debug An optional parameter that turns on the debug function of the Ant utility, which the wsinstance tool uses.

-host hostname A required parameter that specifies the host name where you are creating the configuration instance. This should match the host name you specified during installation of the initial product.

-name instanceName A required parameter that specifies the name of the new configuration instance. Use a unique value. The wsinstance command uses this name to construct the node name, which is instanceName_hostname for the new configuration instance of an Application Server. It is important to have a unique name for each configuration instance, to provide a unique combination of host name and instance name, which together form the WAS_NODE name for the configuration instance.
The embedded messaging feature requires unique node names. The wsinstance tool cannot prevent reusing node names for configuration instances created from read-only partitions. Embedded messaging is not supported when you reuse a node name for a configuration instance. So use a unique name.

-path instanceLocation A required parameter that specifies the file path of the instance. All required folders for the instance are in this directory, which is unique to the configuration instance.

-readOnly An optional parameter. The wsinstance tool can detect whether you are creating an instance from the base WAS in a read-only partition.
The wsinstance tool registers a new wsinstance in the properties/wsinstance.properties file of the original installation, if write access to the original product is available. If the original installation is in a read-only partition or if you use the -readOnly option, the wsinstance tool does not register the wsinstance within the properties/wsinstance.properties file of the original installation.
Creating configuration instances from an original installation in a read-only partition has service implications. There is no mechanism in the original installation to identify and update a configuration instance that you create from a read-only partition. Normally, the registration file in the original installation provides the mechanism for updating configuration instances. When you apply a fix pack or an interim fix to the original installation, the update installer also updates the registered configuration instances. However, there is no registration entry for a configuration instance created from a read-only partition, where no entry is made in the registration file.
When you install a fix pack or interim fix to the original installation, use the wsinstance tool to delete the configuration instance and recreate it. A configuration instance must be at the same fix level as the product from which you create it. Otherwise, the configuration instance is unsupported.

-startingPort startingPort An optional parameter that specifies the starting port number for generating all ports for the configuration instance. If not specified, the wsinstance tool uses default ports, or custom-defined ports from a file that you can create.

Example of creating an instance on a Linux or UNIX-based platform
To create a configuration instance for user shasti
wsinstance.sh -name shasti -path ~/shasti/WebSphere -host planetaix -create

On a base WAS product installation, the command creates an Application Server configuration instance named shasti in location ~/shasti/WebSphere with a node name of shasti_planetaix. If user shasti is to use the embedded messaging feature, add the user (shasti) to the mqm and mqbrkrs operating system groups This is true for any non-root user on a Linux or UNIX-based platform.
Example of creating an instance on a Windows platform
To create a configuration instance for user shasti
wsinstance.bat -name shasti -path G:\shasti\WebSphere -host planetnt -create

On a base WAS product installation, the command creates an Application Server configuration instance named shasti in location G:\shasti\WebSphere with a node name of shasti_planetnt.
Example of a creating an instance in a multiuser environment on a Linux or UNIX platform
Follow these steps to create a configuration instance for user shasti in a multiuser environment...

Create the configuration instance
wsinstance.sh -name shasti -path ~shasti/WebSphere -host myhost -startingPort 12000 -create

Change the owner of the folder
chown -R shasti ~shasti/WebSphere

As a convenience, add a call to script ~shasti/WebSphere/bin/setupCmdLine.sh in the profile of user shasti to set the environment when user shasti logs in.
Give these folder permissions to user shasti
$WAS_HOME/bin --- rx (read and execute) $WAS_HOME/java --- rx $WAS_HOME/properties ----r (read) $WAS_HOME/deploytool ----r $WAS_HOME/config ----r $WAS_HOME/lib ----r $WAS_HOME/classes ----r $WAS_HOME/null ----r $WAS_HOME/samples ----r $WAS_HOME/Web ----r

Example of deleting a configuration instance
The following command is on more than one line for formatting purposes. Enter the command on one line to delete the configuration instance named shasti
wsinstance.sh -name shasti -host planetaix -delete

Using predefined port numbers

When you use the wsinstance tool without the -startingPort parameter, the tool attempts to examine a file named with the convention instanceName_portdef.props in the /bin/wsinstance directory of the installation root directory of the original product. You can create the file by copying the portdef.props template file and customizing the port numbers.

Example of using default port assignments

When a port definition file is not present, the wsinstance tool generates a hostname_instanceName_portdef.props file in the /bin/wsinstance directory of the installation root directory of the original product, using the portdef.props template file.
When using the wsinstance tool from a read-only partition, the tool cannot create the hostname_instanceName_portdef.props file in a directory of the original product. Therefore, the tool creates the file in the installation root directory of the new instance.
The wsinstance tool adds one (1) to the default port numbers for the base WebSphere Application Server product. If you create two configuration instances using default port assignments, both instances have the same, conflicting port numbers until you change them.

Incrementing default port numbers from a starting point

The wsinstance tool can assign port numbers based on a starting port value that you give on the command line, using the -startingPort parameter. The tool assigns port numbers sequentially from the starting port number value as it creates an hostname_instanceName_portdef.props file in the wsinstance subdirectory of the bin directory in the $WAS_HOME folder.
In the case of creating an instance from a read-only partition, the resulting hostname_instanceName_portdef.props file is in the installation root of the new instance.
For example, a hostname_instanceName_portdef.props file created with -startingPort 20002 would appear similar to this
HTTPS_TRANSPORT_ADMIN=20002 CSIV2_SSL_SERVERAUTH_LISTENER_ADDRESS=20004 HTTP_TRANSPORT_ADMIN=20003 HTTP_TRANSPORT=20005 HTTPS_TRANSPORT=20006 INTERNAL_JMS_SERVER=20007 BOOTSTRAP_ADDRESS=20008 SAS_SSL_SERVERAUTH_LISTENER_ADDRESS=20009 DRS_CLIENT_ADDRESS=20011 SOAP_CONNECTOR_ADDRESS=20010 CSIV2_SSL_MUTUALAUTH_LISTENER_ADDRESS=20012 JMSSERVER_QUEUED_ADDRESS=20013 JMSSERVER_DIRECT_ADDRESS=20014
The order of port assignments can be arbitrary. Predicting assignments is not possible.
Example of startingPort parameter use
The following example of using the wsinstance tool creates the shasti_portdef.props file with the content shown in the previous example
wsinstance.bat -name shasti -path G:\shasti\WebSphere -host planetnt -startingPort 20002 -create

Set up and using the configuration instance environment

Most tasks that you perform in a configuration instance are done from one shell or command window after you run the setupCmdLine.sh or setupCmdLine.bat script in the /bin directory of the configuration instance. Such a scenario might be...

Create the configuration instance using the /bin/wsinstance/wsinstance.sh (or wsinstance.bat) script from the original installation.
In that command window or in another, change directories to the /bin directory of the new configuration instance.
Establish a temporary override for the normal WAS environment by running the setupCmdLine.sh or setupCmdLine.bat script
setupCmdLine.sh

In the same window, start server by changing directories to the $WAS_HOME/bin directory of the original installation and issuing the command. There is no such command in the /bin directory of the configuration instance
startServer.sh server

This works because running the setupCmdLine script from the configuration instance reconfigures the WAS environment. Reconfiguring the environment lets you issue commands from the /bin directory of the original installation as if you were issuing them from the configuration instance. The configuration instance creates a virtual installation that includes the original installation /bin directory. The virtual environment lasts until you close the Linux or UNIX shell or the command window in a Windows environment.
Even after you close the shell or command window, the server you started is still running in a spawned process that retains the environment settings.
See how the environment has changed. Display all the environment variables. You can see one that points to the setupCmdLine.sh or setupCmdLine.bat file in the configuration instance. The name of the environment variable is WAS_USER_SCRIPT. For example, in a Linux bash shell or in the command window on a Windows platform, type
set

Notice the changes in the environment. Display all the ports for the machine to see the ports that you set for the configuration instance. For example, in a Linux bash shell or in the command window on a Windows platform, type
netstat -a

Open a browser window and point it at the port where you defined HTTP_TRANSPORT_ADMIN in the hostname_instanceName_portdef.props file in the installation root of the new instance. For example, suppose the setting is HTTP_TRANSPORT_ADMIN=20003. Open the administrative console for server by pointing your browser at
http://hostname_orIP_address:20003/admin/

By setting the WAS_USER_SCRIPT environment variable to point to itself, the setupCmdLine script of the configuration instance overrides the setupCmdLine script of the original installation and redirects scripts in the $WAS_HOME/bin directory of the original installation to work on configuration instance objects.

Backing up required files before installing additional features or before installing the V5.0.x Enterprise product

Creating a new WAS V5.x instance using the wsinstance utility can fail with an "adminconsole" already exists error after adding features or installing the V5.0.x Enterprise product. The new instance cannot be administered until the adminconsole.ear is successfully deployed, but the adminconsole.ear cannot be deployed on the new instance. The text of the problem is similar to the following example
WASX7022E: Problem running command "$AdminApp install adminconsole.ear {-node CELL_INSTANCE -configroot /WAS_HOME/config -copy.sessionmgr.servername server -appname adminconsole}" -- exception information: com.ibm.ws.scripting.ScriptingException: WASX7279E: An application with name "adminconsole" already exists. Select a different name.
The new instance of the Application Server might start successfully. However, the administrative console cannot start because of an error in the wsinstance template files caused by installing additional base features, additional Network Deployment features, or by installing Enterprise.
Use the following procedure to work around the problem...

Back up the $WAS_HOME/bin/wsinstance/configdefaults directory.
Use the installation program to add the new features or to install Enterprise.
Delete the following directories and their contents:

$WAS_HOME/bin/wsinstance/configdefaults/backup
$WAS_HOME/bin/wsinstance/configdefaults/temp
$WAS_HOME/bin/wsinstance/configdefaults/$CELL_NAME/applications

Restore the following files from the backup you made to their original locations in the $WAS_HOME/bin/wsinstance/configdefaults directory...

./security.xml"
./nodes/$NODE_NAME/resources.xml"
./nodes/$NODE_NAME/serverindex.xml
./nodes/$NODE_NAME/servers/$SERVER_NAME/resources.xml
Do not restore the entire backup you made. Restore only the files mentioned in this step.

$CELL_NAME refers to the name of the cell defined during the initial product installation.
$NODE_NAME refers to the name chosen for the node.
$SERVER_NAME refers to each of the servers present. Perform the procedure on each server.
See the technote Creating a new V5 instance using the wsinstance command fails with "adminconsole" already exists error for more information.

Correcting a WASX7022E error

If you did not back up the wsinstance template files before installing additional features or before installing the V5.0.x Enterprise product, you can recover from the resulting WASX7022E error described in the preceding section with the following procedure.

Uninstall the product and the Enterprise product (if necessary).
Reinstall the product, selecting all features that you intend to use.
Back up the $WAS_HOME/bin/wsinstance/configdefaults directory.
Install the Enterprise product if necessary.
Delete the following directories and their contents:

$WAS_HOME/bin/wsinstance/configdefaults/backup
$WAS_HOME/bin/wsinstance/configdefaults/temp
$WAS_HOME/bin/wsinstance/configdefaults/$CELL_NAME/applications

Restore the following files from the backup you made to their original locations in the $WAS_HOME/bin/wsinstance/configdefaults directory...

./security.xml"
./nodes/$NODE_NAME/resources.xml"
./nodes/$NODE_NAME/serverindex.xml
./nodes/$NODE_NAME/servers/$SERVER_NAME/resources.xml
Do not restore the entire backup you made. Restore only the files mentioned in this step.

If you cannot afford to reinstall the product on this system: Do not use the wsinstance utility on this system. The corrupt templates will not affect functionality of the product other than the wsinstance utility.

See Also
Creating multiple Version 5 configuration instances

-create\|-delete	A required parameter that specifies whether to create or delete the configuration instance.
-debug	An optional parameter that turns on the debug function of the Ant utility, which the wsinstance tool uses.
-host hostname	A required parameter that specifies the host name where you are creating the configuration instance. This should match the host name you specified during installation of the initial product.
-name instanceName	A required parameter that specifies the name of the new configuration instance. Use a unique value. The wsinstance command uses this name to construct the node name, which is instanceName_hostname for the new configuration instance of an Application Server. It is important to have a unique name for each configuration instance, to provide a unique combination of host name and instance name, which together form the WAS_NODE name for the configuration instance. The embedded messaging feature requires unique node names. The wsinstance tool cannot prevent reusing node names for configuration instances created from read-only partitions. Embedded messaging is not supported when you reuse a node name for a configuration instance. So use a unique name.
-path instanceLocation	A required parameter that specifies the file path of the instance. All required folders for the instance are in this directory, which is unique to the configuration instance.
-readOnly	An optional parameter. The wsinstance tool can detect whether you are creating an instance from the base WAS in a read-only partition. The wsinstance tool registers a new wsinstance in the properties/wsinstance.properties file of the original installation, if write access to the original product is available. If the original installation is in a read-only partition or if you use the -readOnly option, the wsinstance tool does not register the wsinstance within the properties/wsinstance.properties file of the original installation. Creating configuration instances from an original installation in a read-only partition has service implications. There is no mechanism in the original installation to identify and update a configuration instance that you create from a read-only partition. Normally, the registration file in the original installation provides the mechanism for updating configuration instances. When you apply a fix pack or an interim fix to the original installation, the update installer also updates the registered configuration instances. However, there is no registration entry for a configuration instance created from a read-only partition, where no entry is made in the registration file. When you install a fix pack or interim fix to the original installation, use the wsinstance tool to delete the configuration instance and recreate it. A configuration instance must be at the same fix level as the product from which you create it. Otherwise, the configuration instance is unsupported.
-startingPort startingPort	An optional parameter that specifies the starting port number for generating all ports for the configuration instance. If not specified, the wsinstance tool uses default ports, or custom-defined ports from a file that you can create.