[Version 5.0.2 and later]wsinstance command

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

Overview

The wsinstance script creates multiple configuration instances of a base WebSphere Application Server.

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.

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:

-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. The instance name is also the name of the cell. 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.
-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 WebSphere Application Server or Network Deployment product 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, 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.

-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.
-buildfile
An optional parameter that specifies the name of the modified instance.xml file that you want to use. If you want to use a customized instance.xml file for a new instance environment, specify the instance file location. If you do not specify the instance file location, the wsinstance command will use the default instance.xml file.

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.

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.

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:

  1. Create the configuration instance:
    wsinstance.sh -name shasti
                  -path ~shasti/WebSphere
                  -host myhost
                  -startingPort 12000
                  -create
    
  2. Change the owner of the folder:
    chown -R shasti ~shasti/WebSphere
    
  3. 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.
  4. Give these folder permissions to user shasti:
    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=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

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:

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

    Windows systems:

    1. Open a command prompt window.
    2. Change directories to the config_instance_root\bin directory.
    3. Issue the setupCmdLine.bat command.

    Linux and UNIX systems:

    1. Open a command shell window.
    2. Change directories to the config_instance_root/bin directory.
    3. Issue the . ./setupCmdLine.sh command. Notice the space between the periods. The special format for this command sources the command to make the setting active for all processes started from the command shell.

    For example, issue the following command on a Linux platform:

    . ./setupCmdLine.sh

  4. In the same window, start server1 by changing directories to the install_root/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 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.

  5. 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
  6. 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 
  7. 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 server1 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 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:

  1. Back up the install_root/bin/wsinstance/configdefaults directory.
  2. Use the installation program to add the new features or to install Enterprise.
  3. Delete the following directories and their contents:
    • install_root/bin/wsinstance/configdefaults/backup
    • install_root/bin/wsinstance/configdefaults/temp
    • install_root/bin/wsinstance/configdefaults/$CELL_NAME/applications
  4. Restore the following files from the backup you made to their original locations in the install_root/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.

  1. Uninstall the product and the Enterprise product (if necessary).
  2. Reinstall the product, selecting all features that you intend to use.
  3. Back up the install_root/bin/wsinstance/configdefaults directory.
  4. Install the Enterprise product if necessary.
  5. Delete the following directories and their contents:
    • install_root/bin/wsinstance/configdefaults/backup
    • install_root/bin/wsinstance/configdefaults/temp
    • install_root/bin/wsinstance/configdefaults/$CELL_NAME/applications
  6. Restore the following files from the backup you made to their original locations in the install_root/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.


Related tasks
Creating multiple Version 5 configuration instances



Searchable topic ID:   rxml_wsinstance
Last updated: Jun 21, 2007 8:07:48 PM CDT    WebSphere Business Integration Server Foundation, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.wasee.doc/info/ee/ae/rxml_wsinstance.html

Library | Support | Terms of Use | Feedback