The wsinstance command creates multiple configuration instances of one initial installation of the product.
Overview
The wsinstance script creates multiple configuration instances of either the base WebSphere Application Server or the deployment manager.
Each WebSphere Application Server 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.
Each deployment manager configuration instance is a different cell. You can federate Application Server installation instances into a deployment manager configuration instance.
Each configuration instance of the Network Deployment product is a stand-alone deployment manager (dmgr) with its own set of unique configuration files and user data folders for the cell. Configuration folders include config, etc and properties. User data folders include installedApps, installableApps, temp, logs, tranlog and wstemp. The dmgr configuration instance also includes the administrative console and the file transfer applications, to manage the configuration instance.
Location of command file
The command file is located in the install_root/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] [-buildfile]
wsinstance.sh command syntax for Windows platforms
wsinstance.bat -name instanceName -path instanceLocation -host hostName [-startingPort startingPort] [-readOnly] -create|-delete [ -debug] [-buildfile]
Parameters
Supported arguments include:
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, you must use the wsinstance command 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.
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 WebSphere Application Server 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, you must add the user (shasti) to the mqm and mqbrkrs operating system groups, as described in Installing WebSphere embedded messaging as the JMS provider. This is true for any non-root user on a Linux or UNIX-based platform.
On a Network Deployment product installation, the command creates a deployment manager configuration instance named shasti in a cell named shasti in location ~/shasti/WebSphere with a node name of shasti_planetaix.
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 WebSphere Application Server product installation, the command creates an Application Server configuration instance named shasti in location G:\shasti\WebSphere with a node name of shasti_planetnt.
On a Network Deployment product installation, the command creates a deployment manager configuration instance named shasti in a cell 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:
wsinstance.sh -name shasti -path ~shasti/WebSphere -host myhost -startingPort 12000 -create
chown -R shasti ~shasti/WebSphere
install_root/bin --- rx (read and execute) install_root/java --- rx install_root/properties ----r (read) install_root/deploytool ----r install_root/config ----r install_root/lib ----r install_root/classes ----r install_root/null ----r install_root/samples ----r install_root/Web ----r install_root/config/temp ----r-w
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.
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 install_root folder.
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=20014The 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
Setting 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:
Windows systems:
Linux and UNIX systems:
For example, issue the following command on a Linux platform:
. ./setupCmdLine.sh
startServer.sh server1
This works because running the setupCmdLine script from the configuration instance reconfigures the WebSphere Application Server 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.
set
netstat -a
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 install_root/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 WebSphere Application Server 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 server1 -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:
$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.
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.