DB2 Everyplace Installation in WebSphere Application Server Version 6

Prerequisites for Configuring DB2 Everyplace in WebSphere Application Server:

WebSphere Application Server 6.0.0.1 support is new as of DB2 Everyplace 8.2.1. WAS must be installed before installing the DB2 Everyplace Servlets into the application server. Refer to the WebSphere Application Server Infocenter for more information about installing these application servers.  If you are building a DB2 Everyplace cluster in WAS 6, WebSphere Application Server Network Deployment Version 6 (WAS ND 6) must also be installed.

Install DB2 Everyplace files. The DB2 Everyplace application server is created by the following steps, with the appropriate configuration parameters. If a copy of the DB2 Everyplace server is already running, stop the server before continuing.

1. Use the configuration wizard to perform a basic configuration of DB2 Everyplace. If you are creating a cluster, install using basic configuration on one node. Then use the cluster configuration option on every other node to catalog the DB2e databases on your database server.
2. Make sure the configured DB2 Everyplace Sync Server is not running. If the Sync Server is running, enter the following command to stop it:

Windows:
<DSYINSTDIR>\Server\bin\dsysyncstop.bat

Unix or Linux (as the db2 everyplace instance user).
<DSYINSTDIR>/Server/bin/dsysyncstop.sh

3. Create the DB2 Everyplace application server.

In the following document, keep the following placeholders in mind:

WAS_HOME refers to the the installation directory of the WebSphere Application Server Version 6.
WAS_PROFILE_NAME refers to the name of the profile created when a profile was created for WAS 6. A typical profile name created by default is "default". If there is more than one profile defined, you can use the script files of the corresponding profile.


Create a configuration file:

  1. Windows: Change to the <DSYINSTDIR>\config\work\was directory.
    Unix or Linux: Change to the <DSYINSTDIR>\config\work\was directory.
  2. Create a new jacl script file containing the environment needed to install DB2 Everyplace into WebSphere 6. Copy and paste the following into a new text file:
    ## Start of file.
    ##############################
    # Start Configuration Section
    ##############################

    ###
    # Variables for DB2e Application Server configuration
    # virtualHost, cellName, and nodeName are system specific, and must already exist.
    ###
    set virtualHost default_host
    set cellName yourCellName
    set nodeName yourNodeName

    ##
    # serverName can be any valid server name. The server name cannot be "server1".
    #    default value: DB2e1
    ##
    set serverName DB2e1

    ##
    # If creating a WAS 6 ND cluster, this is the name to give the server cluster.
    #    default value: DB2e_Cluster1
    ##
    set clusterName DB2e_Cluster1

    ##
    # hostName: The hostname of this websphere Node. If there are multiple IP addresses for this
    # node, you may need an IP address specified here.
    ##

    set hostName hostname_or_ip_address

    ##
    # dsyinstdir: The DB2 Everyplace Installation Directory:
    #    ex: Unix/Linux: /home/db2admin/db2everyplace82
    #    ex: Windows: "c:/PROGRA~1/IBM/DB2Everyplace"
    # For windows, use the short names if the directory has white space characters.
    ##
    set dsyinstdir "c:/PROGRA~1/IBM/DB2Everyplace"

    ##
    # dsysqllibinstdir: The sqllib directory of your particular UDB instance:
    #    ex: Unix/Linux: /home/db2admin/sqllib
    #    ex: Windows: "c:/PROGRA~1/IBM/SQLLIB"
    ##
    set dsysqllibinstdir "c:/PROGRA~1/IBM/SQLLIB"

    ##
    # userName: The db2 instance that the DB2 Everyplace instance will run as:
    ##
    set userName db2admin

    ##
    # groupName: The group that the DB2 Everyplace instance will run as:
    #    default: "" (this means no value).
    ##
    set groupName ""

    ##
    # Application Server JVM Heap sizes:
    ##
    set jvmHeapMin 256
    set jvmHeapMax 512


    ##
    # External classpath for DB2 Everyplace. This must be set if there are non-UDB database source subscriptions
    # in DB2 Everyplace.
    ##


    set db2ejdbcdrivercp ""

    ###
    # DB2 Everyplace Enterprise Application and Security Settings:
    ###
    set appName DB2eApp1
    set contextRoot db2e
    set DB2eAllRoleMapToEveryone No
    set DB2eAllRoleMapToAllAuthenticatedUsers Yes
    set DB2eAllRoleMapToUsers ""
    set DB2eAllRoleMapToGroups ""

    set DB2eAdminRoleMapToEveryone No
    set DB2eAdminRoleMapToAllAuthenticatedUsers No
    set DB2eAdminRoleMapToUsers "wpsadmin"
    set DB2eAdminRoleMapToGroups ""



    ##############################
    # End Configuration Section
    ##############################

    set osname $env(os.name)
    regsub -all {\\} ${dsyinstdir} {/} dsyinstdir
    regsub -all {\\} ${dsysqllibinstdir} {/} dsysqllibinstdir

    # check inputs:
    if {![info exists db2ejdbcdrivercp]} {
       puts "No external application classpath specified..."
       set db2ejdbcdrivercp ""
    }

    # check for directory existance:
    if { ! [file isdirectory "${dsyinstdir}"] } {
        puts "Specified DB2 Everyplace Install directory $dsyinstdir does not exist"
        exit 1
    }
    if { ! [file isdirectory "${dsysqllibinstdir}"] } {
        puts "Specified DB2 installation directory $dsysqllibinstdir does not exist"
        exit 2
    }

    # Determine script extensions
    if { "${osname}" == "Linux" } {
       set ext sh
    } elseif { "${osname}" == "SunOS" } {
       set ext sh
    } elseif { "${osname}" == "AIX" } {
       set ext sh
    } else {
        set ext bat
    }

    # Proc to get the DB2e classpath:
    proc getClasspath {DSYINSTDIR DSYSQLLIBINSTDIR} {
        set psep ";"

        set db2ecp "${DSYINSTDIR}/Server/properties"

        set db2ecp "${db2ecp}${psep}${DSYSQLLIBINSTDIR}/java/db2java.zip"
        set db2ecp "${db2ecp}${psep}${DSYINSTDIR}/Server/lib/udbfp7_8.zip"
        set db2ecp "${db2ecp}${psep}${DSYINSTDIR}/Server/lib/udbv72cc.zip"

        return $db2ecp
    }


    set AllRoleSec [list "All Role" "${DB2eAllRoleMapToEveryone}" "${DB2eAllRoleMapToAllAuthenticatedUsers}" "${DB2eAllRoleMapToUsers}" "${DB2eAllRoleMapToGroups}" ]
    set AdminRoleSec [list "AdminRole" "${DB2eAdminRoleMapToEveryone}" "${DB2eAdminRoleMapToAllAuthenticatedUsers}" "${DB2eAdminRoleMapToUsers}" "${DB2eAdminRoleMapToGroups}"]

    # Build the DB2e Classpath:
    set db2ecp [getClasspath "${dsyinstdir}" "${dsysqllibinstdir}"]

    ## End of file
  3. Modify each entry must be modified to match your environment. Save the file in two locations: <DSYINSTDIR>/config/template/was/db2e_was6_profile1.jacl <DSYINSTDIR>/config/work/was/db2e_was6_profile1.jacl.

Install DB2 Everyplace into WebSphere:

Start the administration server before continuing if it has not already been started.


Windows:
"<WAS_HOME>\profiles\<WAS_PROFILE_NAME>\bin\startServer.bat server1"

Unix or Linux:
"<WAS_HOME>/profiles/<WAS_PROFILE_NAME>/bin/startServer.sh server1"


Run the following command to create a DB2 Everyplace Application Server in WebSphere. While still in the <DSYINSTDIR>/config/work/was directory, do the following steps:
  1. Start the wsadmin command line as a root or admistrative user:


    Windows:
    "<WAS_HOME>\profiles\<WAS_PROFILE_NAME>\bin\wsadmin.bat" -profile db2e_was6_profile1.jacl  -profile dsyFunctions_was_v6.jacl

    Unix or Linux:
    "<WAS_HOME>/profiles/<WAS_PROFILE_NAME>/bin/wsadmin.sh" -profile db2e_was6_profile1.jacl  -profile dsyFunctions_was_v6.jacl


    After the command shell  loads, the prompt "wsadmin>" appears.

  2. Create a DB2 Everyplace Server.

    Type the following on one line and press enter:



    createDB2eServer "${virtualHost}" "${cellName}" "${nodeName}" "${serverName}" "${hostName}" "${dsyinstdir}" "${db2ecp}" "${db2ejdbcdrivercp}" "${jvmHeapMin}" "${jvmHeapMax}" "${userName}" "${groupName}"

  3. Install the DB2 Everyplace Enterprise Application. Remember to perform this step whenever any server side code for DB2 Everyplace is updated to ensure the server is running with the latest code.

    Type the following on one line and press enter:

    installWar "${virtualHost}" "${cellName}" "${nodeName}" "${serverName}" "${dsyinstdir}/config/work/was/IBM_DB2_Everyplace.war" "${appName}" "${contextRoot}" $AllRoleSec $AdminRoleSec

  4. Make sure you did not see any errors at each step. If installation is complete and successful, save the configuration by typing:

    $AdminConfig save

  5. Type "exit" to exit the wsadmin command line.

Associate the DB2 Everyplace Enterprise Application to a Configured Web Server:

The WebSphere Application Server configuration has been updated with the addition of a new server, and a new application.Update the webserver plugin configuration. Note that in WAS 6, a application must also be installed into a configured web server. There are many ways to do this task. One way is from a command line. If you are running the HTTP Server and the webserver was configured using default values, execute the following command as a root or admistrative user. The actual Plugin install directory depends on where it was installed.


Windows:
"<WebSphere Installation Directory>\Plugins\bin\configurewebserver1.bat"

Unix or Linux:
"<WebSphere Installation Directory>/Plugins/bin/configurewebserver1.sh"


The command above associates the applications installed in WebSphere to the configured webserver. Refer to the WebSphere Application Server Infocenter for more details on how to do the same task for distributed WebSphere environments.

Generate the new plugin-cfg.xml file for the configured web server:

The plugin-cfg.xml file is read by the web server to determine how to route requests to WebSphere. To update this file, execute the following command:


Windows:
"<WAS_HOME>\profiles\<WAS_PROFILE_NAME>\bin\GenPluginCfg.bat"

Unix or Linux:
"<WAS_HOME>/profiles/<WAS_PROFILE_NAME>/bin/GenPluginCfg.sh"


Be sure to review the location of the plugin file as necessary to ensure the generated plugin-cfg.xml file is updated to match the configuration that the HTTP server is reading.

If you are using the IBM HTTP Server, the configuration file is located in the following directory:
<IBM HTTP Server Install Directory>\conf\httpd.conf

Look for the WebSphere Directive: WebSpherePluginConfig, and make sure the file referenced is updated. If you are using the default context root, look for the URI "/db2e" under the application server name you selected for your application server.

Make sure your configured web server is running before the next step.

Start the DB2 Everyplace Application Server:

After everything is installed in the previous steps, start the server. Remember to start, or restart any configured DB2 Everyplace Application Servers whenever the configuration changes, even if only the DB2 Everyplace Application was updated.


If running under Unix or Linux, as the root user, be sure to source the db2 instance profile before starting the server. NOTE: You must have a dot and a space in front of the command to source the user profile file. Leaving them out will cause the server to be unable to acquire the user's database environment variables, resulting in a server that is unable to connect to the database.

Unix: . ~<DB2 INSTANCE NAME>/.profile
Linux:  . ~<DB2 INSTANCE NAME>/.bashrc

Also note that WebSphere is installed as root, but DB2 Everyplace runs as non-root. You will need to alter some directory permissions. Execute as root on your commad line (substitute the correct value for WAS_HOME for each node runing DB2 Everyplace). Review your site security policies before making these changes.
wkspace="<WAS_HOME>/profiles/<WAS_PROFILE_NAME>/wstemp/advisor/workspace"
userName=<your DB2 Everyplace instance name>
mkdir $wkspace
chmod -R $userName $wkspace
chown $userName <WAS_HOME>/profiles/<WAS_PROFILE_NAME>/config/cells/<yourCellName>/nodes/preadNode01/perftuners.xml


Now, start the server:


Windows:
<WAS_HOME>\profiles\<WAS_PROFILE_NAME>\bin\startServer.bat <serverName>

Unix or Linux:
<WAS_HOME>/profiles/<WAS_PROFILE_NAME>/bin/startServer.bat <serverName>


If your web server is running, open a web browser, and try to see the DB2 Everyplace status page by going to the following URL:


http://<yourhostname.domain>/db2e/db2erdb


You should see "DB2e SyncServer" followed by the current time of the server.




Configuring a DB2 Everyplace Cluster in WebSphere Application Server

WebSphere Network Deployment Version 6 is required to create a server. Before beginning, decide the topology of your cluster, and nodes you want to add to the WAS ND server. The nodes will become "managed" servers, meaning the deployment manager can manage the nodes from the GUI, instead of the command line for standalone WAS 6 servers.

Refer to your WAS 6 Documentation on how to add nodes to the WAS ND deployment manager configuration. Refer to the DB2 Everyplace documentation to see how to install DB2 Everyplace with a "Cluster" configuration.

On each node, execute:

Windows:
<WAS_HOME>\profiles\<WAS_PROFILE_NAME>\bin\addNode.bat dmgr_host <dmgr_port> -includeapps

Unix or Linux:
<WAS_HOME>/profiles/<WAS_PROFILE_NAME>/bin/addNode.sh dmgr_host <dmgr_port> -includeapps


where:
   dmgr_host is the tcp hostname of the deployment manager.
   dmgr_host is the tcp server port number the deployment manager is running on if it is not the default (normally 8880)

Note: If your nodes are running Unix or Linux, be sure to source the environment variable of the DB2 Everyplace instance profile prior to starting the node agent for each server. If the nodes are already started, stop the node with "<WAS_HOME>/profiles/<WAS_PROFILE_NAME>/bin/stopNode.[bat/sh]", and restart them with the correct environment using "startNode.[bat/sh]"

If you have JDBC datasources that are non-UDB, be sure to also install the JDBC drivers to each node.

Create a configuration file:

See the instructions in the single server case on how to create a profile script. Copy them to each node in the locations indicated. You must update the settings for each node. In particular, the nodeName must be different on each node, and the serverName must be unique.

Install DB2 Everyplace into WebSphere Application Server Network Deployment:

Start the WebSphere Deployment Manager before continuing if it has not already been started. Here, WAS_ND_HOME refers to the installation directory for WebSphere Network Deployment.


Windows:
"<WAS_ND_HOME>\profiles\<WAS_ND_PROFILE_NAME>\bin\startManager.bat"

Unix or Linux:
"<WAS_ND_HOME>/profiles/<WAS_ND_PROFILE_NAME>/bin/startManager.sh"


Run the following command to create a DB2 Everyplace Application Server in WebSphere. While still in the <DSYINSTDIR>/config/work/was directory, do the following steps:
  1. Start the wsadmin command line as a root or admistrative user:


    Windows:
    "<WAS_HOME>\profiles\<WAS_PROFILE_NAME>\bin\wsadmin.bat" -profile db2e_was6_profile1.jacl  -profile dsyFunctions_was_v6.jacl

    Unix or Linux:
    "<WAS_HOME>/profiles/<WAS_PROFILE_NAME>/bin/wsadmin.sh" -profile db2e_was6_profile1.jacl  -profile dsyFunctions_was_v6.jacl


    After the command shell  loads, the prompt "wsadmin>" appears.

  2. Create a DB2 Everyplace Server. Log on to each Websphere 6 node:
    Type the following on one line and press enter:

    createDB2eServer "${virtualHost}" "${cellName}" "${nodeName}" "${serverName}" "${hostName}" "${dsyinstdir}" "${db2ecp}" "${db2ejdbcdrivercp}" "${jvmHeapMin}" "${jvmHeapMax}" "${userName}" "${groupName}"

  3. Convert the server you just created into a ClusterMember belonging to the configured cluster:

    convertToCluster "${cellName}" "${nodeName}" "${serverName}" "${clusterName}"

  4. Create additional ClusterMembers as desired by logging onto each node, and starting a new wsadmin command line just like in step 1.

    Set a new unique server name and node name if you haven't already.

    set nodeName myNode
    set serverName DB2e2


    Create a new ClusterMember:

    createDB2eClusterMember "${virtualHost}" "${cellName}" "${nodeName}" "${serverName}" "${clusterName}" "${hostName}" "${dsyinstdir}" "${db2ecp}" "${db2ejdbcdrivercp}" "${jvmHeapMin}" "${jvmHeapMax}" "${userName}" "${groupName}"

  5. Install the DB2 Everyplace Enterprise Application. Remember to perform this step whenever any server side code for DB2 Everyplace is updated to ensure the server is running with the latest code.

    Type the following on one line and press enter:

    installWarCluster "${virtualHost}" "${cellName}" "${clusterName}" "${dsyinstdir}/config/work/was/IBM_DB2_Everyplace.war" "${appName}" "${contextRoot}" $AllRoleSec $AdminRoleSec


  6. Make sure you did not see any errors at each step. If installation is complete and successful, save the configuration by typing:
    $AdminConfig save
  7. Type "exit" to exit the wsadmin command line.

Associate the DB2 Everyplace Enterprise Application to a Configured Web Server:

If you are running the HTTP Server and the webserver was configured using default values, execute the following command as a root or admistrative user. The actual Plugin install directory depends on where it was installed.


Windows:
"<Plugin Installation Directory>\Plugins\bin\configurewebserver1.bat"

Unix or Linux:
"<Plugin Installation Directory>/Plugins/bin/configurewebserver1.sh"


The command above associates the applications installed in WebSphere to the configured webserver.

Refer to the WAS ND 6 InforCenter instructions for details on how to configure the application servers to sync through a WebServer in a Network deployment environment.

Generate the new plugin-cfg.xml file for the configured web server:

The plugin-cfg.xml file is read by the web server to determine how to route requests to WebSphere. To update this file, execute the following command. Note this is the WebSphere Network Deployment command, not the WAS GenPluginCfg command.


Windows:
"<WAS_ND_HOME>\profiles\<WAS_ND_PROFILE_NAME>\bin\GenPluginCfg.bat"

Unix or Linux:
"<WAS_ND_HOME>/profiles/<WAS_ND_PROFILE_NAME>/bin/GenPluginCfg.sh"


Be sure to review the location of the plugin file as necessary to ensure the generated plugin-cfg.xml file is updated to match the configuration that the HTTP server is reading.

If you are using the IBM HTTP Server, the configuration file is located in the following directory:
<IBM HTTP Server Install Directory>\conf\httpd.conf

Look for the WebSphere Directive: WebSpherePluginConfig, and make sure the file referenced is updated. If you are using the default context root, look for the URI "/db2e" under the application server name you selected for your application server.

Make sure your configured web server is running before the next step.

Start the DB2 Everyplace WebSphere Cluster:

The WAS ND environment will allow you to start a server from a web GUI, via the WebSphere Administration Console for the Deployment Manager. Refer to the WAS 6 ND InfoCenter for details on how to access the web console.


If running under Unix or Linux, as the root user, be sure to source the db2 instance profile before starting the server. NOTE: You must have a dot and a space in front of the command to source the user profile file. Leaving them out will cause the server to be unable to acquire the user's database environment variables, resulting in a server that is unable to connect to the database.

Unix: . ~<DB2 INSTANCE NAME>/.profile
Linux:  . ~<DB2 INSTANCE NAME>/.bashrc

Also note that WebSphere is installed as root, but DB2 Everyplace runs as non-root. You will need to alter some directory permissions. Execute as root on your commad line (substitute the correct value for WAS_HOME for each node runing DB2 Everyplace). Review your site security policies before making these changes.
wkspace="<WAS_HOME>/profiles/<WAS_PROFILE_NAME>/wstemp/advisor/workspace"
userName=<your DB2 Everyplace instance name>
mkdir $wkspace
chmod -R $userName $wkspace
chown $userName <WAS_HOME>/profiles/<WAS_PROFILE_NAME>/config/cells/<yourCellName>/nodes/<yourNodeName>/perftuners.xml


Otherwise, simply follow the same instructions for starting a single server.
If your web server is running, open a web browser, and try to see the DB2 Everyplace status page by going to the following URL. If the server has not started yet, you may get an HTTP error code 500.


http://<yourhostname.domain>/db2e/db2erdb


You should see "DB2e SyncServer" followed by the current time of the server. You can enter individual application server ports to directly check the status of each DB2e application server running behind the WebSphere frontend web server. For example, if one of your DB2e Servers is running on port 9081, type this into your browser:


http://<yourhostname.domain>:9081/db2e/db2erdb