Create multiple Version 5 configuration instances

Multiple configuration instances, as it applies to WebSphere appserver products, is the ability to install the base WAS product once, and to use the wsinstance command to create multiple instances of the initial installation, all running on the same machine at the same time.

In contrast to multiple configuration instances is coexistence, which refers to multiple installations of WAS, running on the same machine at the same time. Both coexistence and multiple configuration instances of the base WAS product imply various combinations of Web server interaction.

You can find a description of coexistence

You can install the base WebSphere Application Server product one time and use the wsinstance tool in the $WAS_HOME\bin\wsinstance folder to create multiple configuration instances. 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 instance has the administrative console application to manage the configuration instance. The configuration instance shares all run-time scripts, libraries, the Software Development Kit, and other files with the initial Application Server.

You can configure and operate each configuration instance independently of other instances.

These limitations apply to multiple configuration instances...

Reasons to use configuration instances include...

Use the following procedure to create and configure multiple V5 instances...

  1. Install the base WAS product.

  2. Back up the $WAS_HOME/bin/wsinstance/configdefaults directory. In certain situations, it might become necessary to restore the following files from the backup to 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

    See the description of a possible error that can occur for more information.

  3. Use the wsinstance command in the WAS_HOME\bin\wsinstance folder, to create a configuration instance of the server you installed in step 1. Refer to the description of the wsinstance command to learn more about the command, and to see examples of use.

    You must specify a unique directory path and a unique node name for each configuration instance.

    You must also specify unique port numbers for each configuration instance. For example, on a Windows platform, specify ports beginning at 20002, for node shasti, in configuration instance_root G:\shasti\WebSphere, on the planetjava machine, by issuing this command

    wsinstance.bat -name shasti 
                      -path G:\shasti\WebSphere  
                      -host planetjava  
                      -startingPort 20002 

    This command creates a separate set of configuration and other data files.

  4. Run the setupCmdLine.bat (or script in the bin directory of the instance_root folder to set the WAS environment to the configuration instance.

    Or, you can set WAS_USER_SCRIPT to instance_root\bin\setupCmdLine.bat, which has the same effect as running the setupCmdLine command.

    On Linux and UNIX-based platforms, source the script to the parent shell to inherit the exported variables by running this command

    # . / (there is a space between the period and the slash)

    Or, you can set WAS_USER_SCRIPT to instance_root/bin/, which has the same effect as running the setupCmdLine command. For example

    # export WAS_USER_SCRIPT=/opt/inst1/bin/ 

    After completing this step, you can start the appserver configuration instance with the startManager or startServer command.

    If you are using the embedded messaging feature, and you are logging on as a non-root user on a UNIX-based or Linux platform, add the user to the mqm and mqbrkrs operating system groups.

  5. Associate a Web server with a configuration instance.

    If you create multiple configuration instances of the base WAS product, you can configure each instance to either share a Web server with other configuration instances, or to use a separate Web server.

    • Share the Web server

    1. Generate a plugin-cfg.xml configuration file for each appserver configuration instance that is to share a Web server.

    2. Manually merge all plugin-cfg.xml configuration files into one file of the same name, plugin-cfg.xml.

      Put the file in the default folder for the first configuration instance, such as


      If you use the same server name in multiple instances, (for example, suppose there are two server entries), the merged file has duplicate entries that address. All requests for either server instance are routed to the last one in the merged list.

      To correct the problem, change duplicate server name entries to make them unique in the PrimaryServers stanza

       <Server Name="server"/>
       <Server Name="servera"/> 
      Change each duplicate name in the merged file to match its unique name in the PrimaryServers stanza.

      Three tips to follow when merging the files are...

      • There should be only one instance of the tags Config and Log.

      • The properties "keyring" and "stashfile" should use the same location for all appservers in the merged file.

      • Combine all other tags from both files, so long as the tags do not have duplicate names.

    3. Edit the Web server configuration file on the Web server to point to the plugin-cfg.xml file.

    Repeat this process to add or remove a configuration instance from the configuration that shares the Web server, or when you regenerate a plug-in configuration file for any configuration instance in the group.

    • Use a separate Web server

    This configuration is simple. Each appserver configuration instance uses a different Web server.

    1. Use the Web server documentation to create a new Web server instance for each configuration instance.

      For example, to install multiple images of the IBM HTTP Server...

      1. Use the InstallIHS command script in the IHS directory on the product CD to install IBM HTTP Server for a second or later instance.

      2. Install the multiple installation instance to a new directory.

      3. Set a unique port for each multiple instance by editing the "port" directive in the conf/httpd.conf file in the IBM HTTP Server installation root.

      4. Apply any service to each multiple instance of the IBM HTTP Server using the silent interface of the WAS update installer

        updateSilent -ihsOnly -install -ihsInstallDir directory

      5. Copy the current binary plug-in from the $WAS_HOME\bin directory of the WAS product, to the HTTP Server machine and update the LoadModule directive in the httpd.conf file accordingly.

      6. Copy the plugin-cfg.xml file from the $WAS_HOME\config\cells directory of the WAS product, to the HTTP Server machine and update the WebSpherePluginConfig directive in the httpd.conf file accordingly.

    2. Modify the Web server configuration file to point to the configuration instance.

      1. Specify the location of the WAS plug-in binary program. For example, when you install a plug-in feature, the installation wizard installs the plug-in binary program in the $WAS_HOME/bin folder.

      2. Specify the location of the plugin-cfg.xml file of the configuration instance. This file is located in the config/cells or config\cells folder of the configuration instance root location.

  6. Create additional servers in a multiple instance or coexistence environment.

  7. Change port assignments in configuration files if you have a node that you cannot start because of port conflicts.

Refer to the description of the wsinstance command to learn more about the command, and to see examples of use.

Return to Install WAS to continue.


See Also

Install WAS
Configuring Web server plug-ins
wsinstance command