Technical Note Overview This document summarizes the steps of deploying ActiveVOS on the IBM WebSphere Platform. Legal Notice The information in this document is preliminary and is subject to change without notice and should not be construed as a commitment by Active Endpoints. Active Endpoints is providing the planned functionality information contained herein for informational purposes only. Future product releases may differ materially from these plans in functionality and/or timing. Active Endpoints makes no representations or commitments that certain functionality will in fact be released and Active Endpoints assumes no duty to update this information. Copyright (c) 2011 Active Endpoints Incorporated. Document Revision History Revision Date Author Changes 1.0 9 February 2011 AEI First Release Technical Note 1/23
Table of Contents IBM WebSphere Terminology... 3 Installation Checklist... 4 Install IBM WebSphere for Standalone... 4 Starting IBM WebSphere... 4 Database Configuration for IBM WebSphere... 5 Configuring IBM WebSphere to use MySQL JDBC Connector... 5 Configuring IBM WebSphere to use DB2 JDBC Connector... 6 Configuring IBM WebSphere to use Oracle database... 7 Configuring a IBM WebSphere Work Manager... 8 Configuring a IBM WebSphere Timer Manager... 8 Update/Install the ActiveVOS Enterprise Installation... 9 Changing the IBM WebSphere Port Assignments... 10 Installing IBM WebSphere Clustered version... 11 Installing the Network Deployment profile... 11 Installing the Application Server profile on same machine as Network Deployment... 11 Installing cluster members on nodes not located on Network Deployment machine... 12 Creating the cluster... 12 Configuring the NodeAgent to start as a Windows Service... 12 Updating the Deployment Manager Windows Service... 13 Adding an LDAP User Registry... 14 Setting up JAAS Application Logins... 15 Update/Install the ActiveVOS Enterprise Installation in a Cluster... 16 Setting up JMS Resources... 16 Part A. Create a service bus... 16 Part B. Create JMS resources mapped to bus destinations... 17 Appendix Sample Installation Screenshots... 18 Technical Note 2/23
IBM WebSphere Terminology During the WebSphere installation, you may encounter a mix of standard and non- standard technical terms from the Application Server technology space. IBM WebSphere currently offers three versions of their application server product. IBM WebSphere Express is a slimmed down version of the product which offers no EJB container, embedded messaging support or JCA resource adapters. Also, there is no central administration or workload management. A mid-level offering is the IBM WebSphere Application Server product which contains an EJB container, embedded messaging and JCA resource adapter. However it still does not contain a central administration or workload management facility. The third offering is a Network Deployment Application Server which contains a central administration and workload management facility. It also contains a Web Services UDDI Registry and Web Services Gateway. The following is a list of some of the terms you may encounter as well as well as an explanation of each: Cell - a grouping of nodes into a single administrative domain. In the Base and Express configurations, a cell contains one node. That node may have multiple servers, but the configuration files for each server are stored and maintained individually. In a Network Deployment version the configuration and application files for all nodes in the cell are centralized into a cell master configuration repository. Network Deployment - configuration offers central administration and workload management. A Network Deployment environment consists of one or more Base installations and a Deployment Manager installation. The Base application servers are added to the cell and managed by the Deployment Manager. Node Agent - As you move up through the more advanced IBM WebSphere Application Server configurations, the concepts of configuring multiple nodes from one common administration server and workload distribution among nodes are introduced. In these centralized management configurations, each node has a node agent that works with a Deployment Manager to manage administration processes. Nodes - A node is a logical grouping of IBM WebSphere-managed server processes that share common configuration and operational control. A node is generally associated with one physical installation of IBM WebSphere Application Server. Cluster - A cluster is a logical collection of application server processes, with the sole purpose of providing workload balancing. Application servers that belong to a cluster are "members" of Technical Note 3/23
that cluster and must all have identical application components deployed on them. Other than the applications configured to run on them, cluster members do not have to share any other configuration data. Application Servers - provide the runtime environment for application code. They provide containers and services that specialize in enabling the execution of specific Java application components. Installation Checklist Please refer to the latest installation checklist at http://infocenter.activevos.com/infocenter/activevos/v80/topic/com.activee.rtbpeladmin.ente rprise.help.install_config_deploy_guide/websphere/html/install_checklist.html. Also, for screenshots of a typical installation, please refer to the appendix at the end of this technote. Install IBM WebSphere for Standalone 1. If you plan on installing IBM WebSphere to run as a service, you must logon to the target machine using an account which has the following rights: Act as part of the operating system Log on as a service 2. Install IBM WebSphere 3. Perform a custom installation. Note that you may change the port assignment for the HTTP transport during installation from the default 9080 to 8080 to make testing of ActiveVOS easier. 4. During install, you may choose to install the application as a service. If so make sure you change the settings from Control Panel->Services from Manual to Automatic if you want the server to start automatically. Starting IBM WebSphere If you have configured IBM WebSphere to start as a service and have not specified it to start automatically. Go to Control Panel->Services and start the service named IBM WebSphere Application Server - server1 (where server1 is the name of the application server which was created). If you did not install IBM WebSphere as a service, you may manually start the application server by navigating to the IBM WebSphere install directory and then into the bin directory. From there enter the following command on the command line to start the server, substitute the appropriate <profile> created during installation. startserver -profilename <profile> Technical Note 4/23
Database Configuration for IBM WebSphere Below are sample configurations for MySQL and DB2. You only need to configure the one you intend on using for persistence. Please make sure to copy the appropriate database libraries to a directory available to IBM WebSphere. Oracle support libraries o ojdbc14.jar DB2 support libraries o db2jcc.jar o db2jcc_license_cu.jar Configuring IBM WebSphere to use MySQL JDBC Connector 1. Make sure that IBM WebSphere was successfully started, and navigate using a web browser to the admin console at http://localhost:9060/ibm/console 2. From admin console navigate to Environment->Manage WebSphere Variables 3. Create a new variable called "MYSQL_JDBC_DRIVER_PATH" and set its value to the directory where mysql-connector-java-3.1.11-bin.jar is located on the local drive. Save your changes. 4. Navigate to Resources->JDBC Providers and create a new "User-defined JDBC Provider". The following values should be used for the provider: Name => MySQL JDBC Provider Description => MySQL Provider configuration Classpath => ${MYSQL_JDBC_DRIVER_PATH}/mysql-connector-java-3.1.11-bin.jar Implementation Classname => com.mysql.jdbc.jdbc2.optional.mysqlconnectionpooldatasource 5. Apply changes and select "Data Sources" link under additional properties. 6. Create a new data source with the following properties Name => ActiveVOS Enterprise DataSource JNDI Name => jdbc/activevos 7. Leave remaining properties at their default and press apply. 8. Under "Additional Properties" select "Connection Pool" and change the Min Connections to 10 and the Max Connections to 50. 9. Select the link "J2EE Connector Architecture (J2C) authentication data entries" from the DataSource definition page. From here you should create a database authorization alias to be used during EAR deployment. You may use ActiveVOSDBAlias as the name of the alias. The username will be 'bpeluser' and the password will be 'bpel'. Technical Note 5/23
10. Press Ok which will bring you back to the Data Source config page. 11. Select "Custom Properties" and add the following property/value pairs (not they can all be strings) databasename => activevos servername => localhost portnumber => 3306 user => bpeluser password => bpel useunicode => true characterencoding => UTF-8 charactersetresults => utf8 12. Save your changes and test the connection which was just created. Configuring IBM WebSphere to use DB2 JDBC Connector 1. Make sure that IBM WebSphere was successfully started, and navigate using a web browser to the admin console at http://localhost:9060/ibm/console 2. From admin console navigate to Resources->JDBC Providers 3. For Step 1 choose the following options Database Type => DB2 Provider Type => DB2 Universal JDBC Provider Implementation Type => Connection pool data source Name => DB2 JDBC Provider (or another appropriate name) 4. For Step 2 enter the path or IBM WebSphere variable of the location where you will place the db2jcc.jar and db2jcc_license_cu.jar library files. 5. Finish and save DB2 JDBC Provider 6. From admin console navigate to Resources->Data sources 7. Choose option to create New datasource 8. For Step 1 make following entries Data source name => ActiveVOS Datasource JNDI Name => jdbc/activevos 9. For Step 2 choose option to "Select existing JDBC provider" and choose provide which you previously had defined 10. For Step 3 enter connection information appropriate to database location (for example) Database name => ABPEL Driver type => 4 Server name => AELOAD2 Port number => 50000 11. Finish and save DB2 JDBC Data source 12. After saving, edit the newly defined data source to set parameter information 13. Under "Additional Properties" select "Connection Pool" and change the Min Connections to 25 and the Max Connections to 100. Technical Note 6/23
14. Press Ok which will bring you back to the Data Source config page. 15. Select "Custom Properties" and add/modify the following property/value pairs user => bpeluser password => bpel 16. Save your changes and test the connection which was just created. Configuring IBM WebSphere to use Oracle database 1. Make sure that IBM WebSphere was successfully started, and navigate using a web browser to the admin console at http://localhost:9060/ibm/console 2. From admin console navigate to Resources->Data Sources. Set the scope as Cluster0. Add a data source with JNDI Name as jdbc/activevos. Under Data store helper class name, select 11g data store helper. Under Container-managed authentication alias, select Node Name/ActiveBPELDBAlias. Make sure you set up schema username and password for ActiveBpelDBAlias in Data Sources > Active Bpel Enterprise Data Source > Jaas Authentication data > Node Name/ActiveBPELDBAlias > enter database username and PW. 3. For the classpath,enter the path or IBM WebSphere variable of the location where you will place the ojdbc6.jar. Typically this location is $(WAS_INSTALL_ROOT)/lib where the value of the variable $(WAS_INSTALL_ROOT) is C:\WebSphere7.0\AppServer. Also add the driver url, for example, jdbc:oracle:thin:@localhost:1521/orcl. Here is how a typical JDBC datasource appears in WAS admin console: Technical Note 7/23
4. Save your changes and test the connection. Configuring a IBM WebSphere Work Manager 1. From the admin console navigate to Resources->Asynchronous beans->work managers 2. Create a new work manager with the following properties Name => ActiveVOS Enterprise Work Manager JNDI name => wm/activevos Minimum number of threads => 10 Maximum number of threads => 50 select all security service check box 3. Save your changes. Configuring a IBM WebSphere Timer Manager 1. From the admin console navigate to Resources->Asynchronous beans->timer managers 2. Create a new timer manager with the following properties Name => ActiveVOS Enterprise Timer Manager JNDI name => tm/activevos Number of alarm threads => 2 select all security service check box. Technical Note 8/23
3. Save your changes. Update/Install the ActiveVOS Enterprise Installation 1. Using the admin console at http://localhost:9060/ibm/console you should navigate to Applications->Enterprise Applications to install/update the EAR. Once completed, you must navigate to Applications->Enterprise Applications->ActiveVOS Enterprise to set a startup option if this is the initial install of the application. The startup option of 'Enable background application' MUST be checked. 2. During application installation, you will be prompted to map the resources references for the database connection and work manager to concrete resources. 3. You should map the Work Manager to the JNDI reference of 'wm/activevos'. 4. The DataSource requires two mapping to be set. First select the reference binding checkbox for 'jdbc/activevos'. You should select the JNDI mapping of 'jdbc/activevos' press apply. Next re-select the checkbox for the reference binding 'jdbc/activevos'. Under the "specify authentication methods" section choose the 'use default method' radio button and select the database alias which was previously defined. Press Apply and continue. Note you may receive some mapping warnings, which can be ignored. 5. If this is the initial install of the EAR, remember to start the application. 6. Another way to update/install ActiveVOS server and ActiveVOS central is to run the installer utility config_deploy.bat. 7. After you have installed ActiveVOS server and central, here are a couple of steps you would need to perform to get ActiveVOS server up and running: A. Stop the ActiveVOS server, ActiveVOS central and the managed server. In Applications > Application Types > WebSphere Enterprise Application > ActiveVOS Server > Security role to user/group mapping > select abadmin > Click Map users > Add admin user to abadmin role. B. Add custom groups and users to AbTaskClient. C. Start the managed server and ActiveVOS server and the central. Navigate to one of the ActiveVOS consoles using the URL - http://server_name:port/activevos. D. Login using a user credentials who is a member of abadmin role. Navigate to Admin > License. Add the license. Navigate to Admin > Server Status and start the server. Make sure it starts without any errors. E. Navigate to Admin > Identity Service and configure the identity service and test for a couple of users. You may also want to configure the Email service. F. Navigate to ActiveVOS central using the URL - http://server_name:port/activevoscentral. Login using a user credentials who is a member of abtaskclient. Technical Note 9/23
Changing the IBM WebSphere Port Assignments By default, IBM WebSphere installs itself to listen for HTTP requests on Port 9080. If you did not make this change during installation, you may do so at any time by performing the following operations. 1. From admin console navigate to Servers->Application Servers and select the server you wish to modify. 2. Navigate to the 'Web container transport chains' section from the Web container settings group. 3. Select the hyperlink for WCInboundDefault and change the port from 9080 to 8080. Save your changes. 4. Now navigate to Environment->Virtual Hosts and select the hyperlink for default_host. 5. From the "Addition Properties" section choose "Host Aliases" 6. Select the hyperlink which corresponds to 9080 and change the port assignment to 8080. Save your changes. Technical Note 10/23
Installing IBM WebSphere Clustered version The following section describes the steps necessary to setup a clustered version of IBM WebSphere. While some of the steps may be similar to the standalone version setup, the setup procedure is a bit more complicated. A clustered deployment of IBM WebSphere consists of multiple component installations. The primary "Network Deployment" installation module coordinates all cluster activity. Additionally, one or more "Application Server" installations are performed which will become part of the cluster. This process will be detailed later, but at a high level, the node of the application server install will "federate" itself to the network deployment module which will then have the ability to control it. Installing the Network Deployment profile 1. If you plan on installing IBM WebSphere to run as a service, you must logon to the target machine using an account which has the following rights: Act as part of the operating system Log on as a service 2. Install IBM WebSphere Network Deployment 3. Once installation is complete, you will be prompted to setup profiles for the IBM WebSphere installation, which you should run at this time. 4. Choose to setup a profile for the Network Deployment first. You may accept the name defaults for the deployment manager and cells, or optionally change them if you desire. 5. You will be prompted for port assignments, which you can leave at their default settings. 6. Next you will be prompted to setup the deployment manager as a service, which you may choose to do at this time. 7. Once the profile has been created, choose to run the "First Steps" program to verify that the Deployment Manager is installed properly. This program allows you to start the Network Deployment Manager and run the Installation Verification Test. 8. Assuming all is well with the installation, leave the Deployment Manager running. Installing the Application Server profile on same machine as Network Deployment 1. Using the "First Steps" program, run the "Profile Creation Wizard", and select the "Create a custom profile" option. 2. The default host and port assignments may be used, and the checkbox to federate the node later should be unchecked. 3. (Optional) If for some reason you did need to federate the node later, you may do so as follows. Open a command prompt in the WebSphere\AppServer\bin directory, and execute the following command: Technical Note 11/23
addnode <host name> -profilename <profile> where: <host name> is the name of host of the Deployment Manager <profile> is the Application Server profile which was created Installing cluster members on nodes not located on Network Deployment machine 1. Install IBM WebSphere Network Deployment 2. Once installation is complete, you will be prompted to setup profiles for the IBM WebSphere installation, which you should run at this time. 3. Choose to setup a "Custom Profile". You may accept the name defaults for the node being created, or optionally change them if you desire. 4. You will be prompted for port assignments, which you can leave at their default settings. 5. The node agent for the newly created node should be running at this time. You may need to start this at a later date when the machine is rebooted. To do so, execute the following command from the WebSphere\AppServer\bin directory startnode -profilename <profile> Creating the cluster 1. From the administrative console, navigate to Servers->Clusters and create a new cluster. 2. Select the newly created cluster and select the link to Cluster Members. 3. Select New cluster member and enter the name of the member to be created. Make sure to press the Apply button, or nothing will happen. 4. Press the Next button then the Finish button and save your changes. Configuring the NodeAgent to start as a Windows Service By default, a Network Deployment installation creates a Windows service for the deployment manager but not the node agent. A Network Deployment application server profile is not fully functional until the NodeAgent for the application server has been started. Starting this manually is not very desirable. We have the ability to create a Windows Service to automatically start the NodeAgent. 1. Open a command prompt window 2. Change the current directory to \WebSphere\AppServer\profiles\AppSrv01\bin 3. Execute the following command to create the NodeAgent service. Note: you should replace 'AppSrv01' with your cell application server name. Also make sure WASService.exe and WASServiceMsg.dll exist in this directory. WASService -add nodeagent -servername nodeagent -profilepath "C:\WebSphere\AppServer\profiles\AppSrv01" Technical Note 12/23
-washome "C:\WebSphere\AppServer" -stopargs "-username <user> -password <pwd>" -logfile "C:\WebSphere\AppServer\profiles\AppSrv01\logs\nodeagent\startNode.log" -logroot "C:\WebSphere\AppServer\profiles\AppSrv01\logs\nodeagent" -restart true -starttype automatic Updating the Deployment Manager Windows Service By default, a Network Deployment installation creates a Windows service for the deployment manager. However when Global Security is enabled you will have permission to start the service, but may not have permission to stop the service. By updating the Deployment Manager profile with parameters for the stopargs of a valid console user you will then be able to stop the Deployment Manager form the services program. 1. Open a command prompt window 2. Change the current directory to \WebSphere\AppServer\profiles\Dmgr01\bin 3. Execute the following command to update the deployment Manager service. Note: you should replace 'aedevcellmanager' with your appropriate cell manager name and servername 'dmgr' with the name of the deployment manager profile you created. Also make sure WASService.exe and WASServiceMsg.dll exist in this directory. WASService -add aedevcellmanager -servername dmgr -profilepath "C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01" -stopargs -username <user> -password <pwd> -encodeparams Technical Note 13/23
Adding an LDAP User Registry 1. From the Admin console go to Global Security 2. Set the Active authentication mechanism to "LTPA" 3. From the Admin console go to Global Security->LTPA 4. Enter password for LTPA 5. From the Admin console go to Global Security->LDAP User Registry 6. Enter the following values: Server user ID => {user} Server user password => {password} Type => ActiveDirectory Host => {server} Port => 389 Base distinguished name (DN) => DC=aedomain,DC=active-endpoints,DC=local Bind distinguished name (DN) => CN=aeadmin, CN=Users, DC=aedomain,DC=activeendpoints,DC=local Bind password => {password} Search timeout => 120 Technical Note 14/23
Setting up JAAS Application Logins AEI s cluster implementation on IBM WebSphere uses mbeans. During execution of a deployment, routing requests between servers when processes are locked and in other locations we use this cluster mbean s methods. In order to execute these methods when global security is turned on the current thread needs to have access to the mbean. Here how the two options work: ActiveVOSIdentityAssertion re-asserts the current identity this is a workaround to a work manager issue on IBM WebSphere where even when you say to inherit security on work manager setup you need to reassert it in order for the credentials to be processed correctly. When using this by default (if you don t override the cluster mbean security) all abserviceconsumers users must have monitor rights on the server. ActiveVOS Provided User says given a username/password we will use that anytime we need to use the mbean regardless of what the subject was on the executing thread. This user will need monitor rights (if you don t override the cluster mbean security). 1. From the Admin console go to Global Security, under JAAS Configurations select "Application login configuration" 2. Add new application login for "ActiveBPELIdentityAssertion" 3. Go to JAAS login module section and add following entries in following order com.activee.rt.websphere.trustvalidation.aeidentityassertionloginmodule com.ibm.wsspi.security.common.auth.module.identityassertionloginmodule 4. Save changes 5. Add new application login for "ActiveBPELProvidedUser" 6. Go to JAAS login module section and add following entry com.activee.rt.websphere.trustvalidation.aebasicloginmodule 7. Add custom properties for this module to specify username => {user} password => {password} 8. Save changes When using "ActiveBPELProvidedUser" the user defined in custom properties must have Monitor role assigned in IBM WebSphere admin console. This is set under Security->Secure administration, applications, and infrastructure. From there, under Administrative Security you can configure "Administrative User Roles" and assign the Monitor role. Also, none of the application roles abadmin, abdeveloper, etc. need be assigned to this user, UNLESS you will also like to allow this user to login to the ActiveVOS admin console Technical Note 15/23
Update/Install the ActiveVOS Enterprise Installation in a Cluster After you have setup the cluster and the datasource, you can install ActiveVOS EAR or run the installer utility to deploy ActiveVOS server and the central. Here are a couple of steps you would need to perform to get ActiveVOS server up and running: A. Stop the ActiveVOS server, ActiveVOS central and the managed servers. In Applications > Application Types > WebSphere Enterprise Application > ActiveVOS Server > Security role to user/group mapping > select Abadmin > Click Map users > Add admin user to abadmin role. B. Add custom groups and users to AbTaskClient. C. Start the managed servers and ActiveVOS server and the central. Navigate to one of the ActiveVOS consoles using the URL - http://server_name:port/activevos. D. Login using a user credentials who is a member of abadmin role. Navigate to Admin > License.Add the license. Navigate to Admin > Server Status and start the server. Make sure it starts without any errors. E. Navigate to Admin > Cluster. Make sure both the nodes are started. In case, one of the nodes is not started, click on the node > Start Engine. F. Navigate to Admin > Identity Service and configure the identity service and test for a couple of users. You may also want to configure the Email service. G. Navigate to the ActiveVOS central using the URL - http://server_name:port/activevos-central. Login using a user credentials who is a member of abtaskclient. Setting up JMS Resources Part A. Create a service bus 1. From the Admin console, go to Service Integration. 2. Under Buses choose New and give the bus a name like 'AeServiceBus' and 'Apply' 3. Create a new Bus member and target to your server or cluster (as appropriate). Cluster bus members will require a datasource that has rights to create tables and only one messaging engine may use a single datasource. 4. Under 'Destinations', Choose 'New' and select 'Queue'. Give it a name like 'AeWsrmInvokerQueue'. Assign it to the bus member. 5. Create another queue destination and call it 'AeWsrmSenderQueue'. Assign it to the bus member. 6. Create a topic space destination and call it 'AeWsrmReplyTopic'. Technical Note 16/23
Part B. Create JMS resources mapped to bus destinations 1. From the Admin console, navigate to Resources/JMS Providers/Default Messaging 2. Create a JMS Connection Factory with a JNDI name of 'AeJMSConnectionFactory'. 3. If the JMS Connection factory is to be accessible from external hosts, you may need to set the Provider endpoint field to hostname:7276:bootstrapbasicmessaging. See this support article[1] Assign the factory to the bus and set the Durable Subscription Client Identifier to 'AeJmsClient' Set the durable subscription home to the name of the messaging engine which was previously created for your bus. This can be found under Buses->AeServiceBus->Bus members->messaging engines. (An example would be aedevcluster.000- AeServiceBus) 4. Create a queue with a JNDI name of 'queue/com.activee.wsrm.invoker.queue' mapped to the 'AeWsrmInvokerQueue' bus destination 5. Create a queue with a JNDI name of 'queue/com.activee.wsrm.sender.queue' mapped to the 'AeWsrmSenderQueue' bus destination 6. Create a topic with a JNDI name of 'topic/com.activee.wsrm.reply.topic' mapped to the 'AeWsrmReplyTopic' bus destination 7. Create a JMS activation spec with a JNDI name of 'eis/aewsrmjmsinvokerspec' mapped to the 'queue/com.activee.wsrm.invoker.queue' queue and the bus you created. 8. Create a JMS activation spec with a JNDI name of 'eis/aewsrmjmssenderspec' mapped to the 'queue/com.activee.wsrm.sender.queue' queue and the bus you created. Technical Note 17/23
Appendix Sample Installation Screenshots After you have configured your IBM WebSphere environment, you can run the installer utility config_deploy.bat (usually located in..server\server-enterprise\websphere_config\bin) to install ActiveVOS Server and ActiveVOS Central. Here are screenshots of a typical installation (assuming an IBM WebSphere cluster with Oracle database): Technical Note 18/23
Technical Note 19/23
Technical Note 20/23
Technical Note 21/23
Technical Note 22/23
Technical Note 23/23