J2C activation specification

This topic provides an overview about the configuration and use of J2C activation specifications, used in the deployment of message-driven beans for JCA 1.5 resources.

J2C activation specifications are part of the configuration of inbound messaging support that can be part of a JCA 1.5 resource adapter. Each JCA 1.5 resource adapter that supports inbound messaging defines one or more types of message listener in its deployment descriptor (messagelistener in the ra.xml). The message listener is the interface that the resource adapter uses to communicate inbound messages to the message endpoint. A message-driven bean (MDB) is a message endpoint and implements one of the message listener interfaces provided by the resource adapter. By allowing multiple types of message listener, a resource adapter can support a variety of different protocols. For example, the interface javax.jms.MessageListener, is a type of message listener that supports JMS messaging. For each type of message listener that a resource adapter implements, the resource adapter defines an associated activation specification (activationspec in the ra.xml). The activation specification is used to set configuration properties for a particular use of the inbound support for the receiving endpoint.

When an application containing a message-driven bean is deployed, the deployer must select a resource adapter that supports the same type of message listener that the message-driven bean implements. As part of the message-driven bean deployment, the deployer needs to specify the properties to set on the J2C activation specification. Later, during application startup, a J2C activation specification instance is created, and these properties are set and used to activate the endpoint (that is, to configure the resource adapter’s inbound support for the specific message-driven bean).

Applications with message-driven beans can also specify all, some, or none of the configuration properties needed by the ActivationSpec class, to override those defined by the resource adapter-scoped definition. These properties, specified as activation-config properties in the application’s deployment descriptor, are configured when the application is assembled. To change any of these properties requires redeploying the application. These properties are unique to this applications use and are not shared with other message-driven beans. Any properties defined in the application's deployment descriptor take precedence over those defined by the resource adapter-scoped definition. This allows application developers to choose the best defaults for their applications.

Message driven beans

WebSphere Application Server supports the use of message-driven beans as asynchronous message consumers.

A client sends messages to the destination (or endpoint) for which the message-driven bean is deployed as the message listener. When a message arrives at the destination, the EJB container invokes the message-driven bean automatically without an application having to explicitly poll the destination. The message-driven bean implements some business logic to process incoming messages on the destination.

Message-driven beans can be configured as listeners on a Java EE Connector Architecture (JCA) 1.5 resource adapter or against a listener port (as for WebSphere Application Server Version 5). With a JCA 1.5 resource adapter, message-driven beans can handle generic message types, not just JMS messages. This makes message-driven beans suitable for handling generic requests inbound to WebSphere Application Server from enterprise information systems through the resource adapter. In the JCA 1.5 specification, such message-driven beans are commonly called message endpoints or simply endpoints.

All message-driven beans must implement the MessageDrivenBean interface. For JMS messaging, a message-driven bean must also implement the message listener interface, javax.jms.MessageListener.

A message driven bean can be registered with the EJB timer service for time-based event notifications if it implements the javax.ejb.TimedObject interface in addition to the message listener interface.

You are recommended to develop a message-driven bean to delegate the business processing of incoming messages to another enterprise bean, to provide clear separation of message handling and business processing. This also enables the business processing to be invoked by either the arrival of incoming messages or, for example, from a WebSphere J2EE client.

Messages arriving at a destination being processed by a message-driven bean have no client credentials associated with them; the messages are anonymous. Security depends on the role specified by the RunAs Identity for the message-driven bean as an EJB component. For more information about EJB security, see Securing enterprise bean applications.

For JMS messaging, message-driven beans can use a JMS provider that has a JCA 1.5 resource adapter, for example the default messaging provider that is part of WebSphere Application Server. With a JCA 1.5 resource adapter, you deploy EJB 2.1 message-driven beans as JCA 1.5-compliant resources, to use a J2C activation specification. If the JMS provider does not have a JCA 1.5 resource adapter, for example the V5 Default Messaging provider and the WebSphere MQ messaging provider, you must configure JMS message-driven beans against a listener port.

When to use activiation specification vs listener port

Guidelines, related to versions of WebSphere® Application Server, to help you choose when to configure your message-driven beans to work with listener ports rather than activation specifications.
You can configure the following resources for message-driven beans:

* Activation specifications for message-driven beans that comply with Java™ EE Connector Architecture (JCA) Version 1.5.
* The message listener service, listener ports, and listeners for any message-driven beans that you want to deploy against listener ports.

If you want to use message-driven beans with a messaging provider that does not have a JCA 1.5 resource adapter (for example the WebSphere MQ messaging provider or the V5 Default Messaging provider), you cannot use activation specifications and therefore you must configure your beans against a listener port. There are also a few scenarios in which, although you could use activation specifications, you might still choose to use listener ports. For example, for compatability with existing message-driven bean applications. Here are some guidelines, related to versions of WebSphere Application Server, to help you choose when to use listener ports rather than activation specifications:

* WebSphere Application Server Version 4 does not support message-driven beans, so listener ports and activation specifications are not applicable. WebSphere Application Server Version 4 does support message beans, but these are not message-driven beans.
* WebSphere Application Server Version 5 supports EJB 2.0 (JMS only) message-driven beans that are deployed using listener ports. This deployment technology is sometimes called application server facility (ASF).
* WebSphere Application Server Version 6 continues to support message-driven beans that are deployed using listener ports, and also supports JCA, which you can use to deploy message-driven beans using activation specifications. This gives you the following options for deploying message-driven beans on WebSphere Application Server Version 6:
o You must deploy default messaging (service integration bus) message-driven beans using activation specifications.
o You must deploy WebSphere MQ message-driven beans using listener ports.
o You can deploy third-party messaging message-driven beans using either listener ports or activation specifications, depending on the facilities available from your third-party messaging provider.

Entity bean extended deployment descriptor file

When you create a CMP Enterprise beans using either the WebSphere Application Server Toolkit or RAD, the META-INF folder of that bean will have set of files that map fields in the entity bean to columns in the DB. The Map.mapxmi file in the META-INF is WAS Specific

J2C ConnectionFactory security

The following security settings are deprecated for J2C connection factory security:

  • Container managed authentication alias

  • Authentication preference

  • Mapping configuration alias

EJB Container tuning

If you use applications that affect the size of the EJB Container Cache, it is possible that the performance of your applications can be impacted by an incorrect size setting. Monitoring Tivoli Performance Viewer (TPV) is a great way to diagnose if the EJB Container Cache size setting is tuned correctly for your application. If the application has filled the cache causing evictions to occur, TPV will show a very high rate of ejbStores() being called and probably a lower than expected CPU utilization on the application server machine

External cache groups

The dynamic cache can control caches outside of the application server, such as the Edge server, an IBM HTTP Server, or an HTTP Server ESI Fragment Processor plugin

When external cache groups are defined, the dynamic cache matches externally cacheable cache entries with those groups, and pushes cache entries and invalidations out to those groups. This allows WebSphere Application Server to manage dynamic content beyond the application server. The content can then be served from the external cache, instead of the application server, improving savings in performance.

Edget side caching

The Web server plug-in contains a built-in ESI processor. The ESI processor can cache whole pages, as well as fragments, providing a higher cache hit ratio. The cache implemented by the ESI processor is an in-memory cache, not a disk cache, therefore, the cache entries are not saved when the Web server is restarted.

When a request is received by the Web server plug-in, it is sent to the ESI processor, unless the ESI processor is disabled. It is enabled by default. If a cache miss occurs, a Surrogate-Capabilities header is added to the request and the request is forwarded to the WebSphere Application Server. If servlet caching is enabled in the application server, and the response is edge cacheable, the application server returns a Surrogate-Control header in response to the WebSphere Application Server plug-in.

The value of the Surrogate-Control response header contains the list of rules that are used by the ESI processor to generate the cache ID. The response is then stored in the ESI cache, using the cache ID as the key. For each ESI include tag in the body of the response, a new request is processed so that each nested include results in either a cache hit or another request that forwards to the application server. When all nested includes have been processed, the page is assembled and returned to the client.
The ESI processor is configurable through the WebSphere Web server plug-in configuration file plugin-cfg.xml. The following is an example of the beginning of this file, which illustrates the ESI configuration options.

Speed WebSphere Apps with Edge Side Includes, has some information on WebSphere WebSphere APIs for Edge Side Includes (WESI) are a set of Java application programming interface (API) and JavaServer Page (JSP) custom tags for accelerating Web application delivery through distributed fragment caching and assembly with Edge Side Includes (ESI).

Profile Management Tool used by Installation factory

When you add any profile customization assets to your CIP, Installation Factory will generate what's called a profile template. The CIP will install this template when it installs WebSphere Application Server. These templates are what WebSphere Application Server uses to create profiles. They are also used by other WebSphere products to augment a WebSphere Application Server profile with the configuration for that product. Installation Factory uses profile templates to execute your profile customization actions as an integrated part of profile creation and augmentation.

A template contains a series of actions that can perform required configuration and application deployment steps during profile creation or augmentation. The template that is generated by Installation Factory contains actions that will process your profile customization assets in the specified order (for example, import a CAR, deploy an EAR, run a script, and so on). You can simply choose this template within the Profile Management Tool (PMT), or pass the template to the manageprofiles command, just as you would to create a standard WebSphere Application Server profile. The profile creation mechanism within WebSphere Application Server looks at the actions in the template and invokes them one after the other.

Using a profile template to execute configuration actions leverages WebSphere Application Server’s rich infrastructure, and provides a user experience that is tightly integrated with the standard profile creation tools.

Log levels

WebSphere application server lets you define what all logging messages should be logged to the trace.log file.

These are the log levels defined by WAS

  • Off: No events are logged.

  • Fatal: Task cannot continue and component cannot function.

  • Severe: Task cannot continue, but component can still function

  • Warning: Potential error or impending error

  • Audit: Significant event affecting server state or resources

  • Info: General information outlining overall task progress

  • Config: Configuration change or status

  • Detail: General information detailing subtask progress

  • Fine: Trace information - General trace + method entry / exit / return values

  • Finer: Trace information - Detailed trace

  • Finest: Trace information - A more detailed trace - Includes all the detail that is needed to debug problems

  • All: All events are logged. If you create custom levels, All includes your custom levels, and can provide a more detailed trace than Finest.

User Management using Federated repository

If your WAS server is configured to use the Federated repository then you can add or delete users and groups. You have following three options for doing that.

  • Programmatic User management APIs

  • The administrative console

  • wsadmin commands

Important Note: Federated user repository is the only option if you want ability to add, delete user and groups. The Standalone LDAP registry or local operating system user registry or custom user registry are readonly registries

What is proxy server

A proxy server seats between the client browser and the servers behind it, it intercepts the client request and then connects to the backend server using its own connection pool, forwards clients request to the server, gets response back from the back end server and then returns that response back to the client. A proxy server performs the same basic duties as a web server and in addition to that they perform following things

  • Proxy: Accepts requrest from the client, forwards that request to backend, gets response back and forwards that response to client. In doing so it hides the actual back end server information from the client

  • Content filtering: They are often used to filter access to internet. The proxy can be configured with rules to reject access to sites that contain objectionable material, preventing users from gaining access to those sites

  • Caching: Proxy servers can cache the results of common user requests and next time they get request for that resource, they can server the response from cache instead of sending to the actual backend server

  • Security: They terminate the user connection inside the DMZ, they hide server identities by providing thier own domain names in the URL instead of backend server name. Combined with authentication proxy such as TAM, proxies can authenticate the user before forwarding the request to backend

What is ws_ant command line tool

To support using Apache Ant with Java 2 Platform, Enterprise Edition (J2EE) applications running on the application server, the product provides a copy of the Ant tool and a set of Ant tasks that extend the capabilities of Ant to include product-specific functions.

ws_ant.sh/bat (or ws_ant on i5/OS) is a wrapper around Apache Ant that sets up a WebSphere specific environment and includes classpath, WebSphere Ant tasks, and environment variables. It allows the same command line options as Apache Ant. For example, a simple invocation of a build file named myBuildFile.xml could be called as: ws_ant.sh -f myBuildFile.xml. The following example uses a build file named build.xml by default: ./ws_ant.sh

By combining the following tasks with those provided by Ant, you can create build scripts that compile, package, install, and test your application on the application server:

  • Install and uninstall applications

  • Start and stop servers in a base configuration

  • Run administrative scripts or commands

  • Run the Enterprise JavaBeans (EJB) deployment tool

  • Run the JavaServer Pages (JSP) file precompilation tool

J2C notes

Java connection architecture defines standard for connecting to different EIS from the J2EE application.

EIS vendors wirte J2C resource adapater similar to JDBC providers written by database vendors. A resource adapter is a driver that connects at the system level to backend EIS.

In keeping with the J2EE packaging model, resource adapters are packaged as modules, in thsi case as RAR files, with an extension of .rar. You would typically have a .rar file for each type of EIS that you are connecting to. A RAR file is esentially a JAR file with some specific content - bascially code and XML deployment descriptor with the filename ra.xml. The RAR file may also contain utility classes, native binary files and documentation.
The adapter can be installed could also be installed as a part of application install, but this practice is discoraged in favor of installing resource adapters separately to the container.

You cannot install resource adapter at cell level. WAS cell contains a heterogeneous mixture of servers, such as combination of windows and Unix machines. Resource adapaters often contain binary shared libraries and there is no distribution mechanism at the cell level for this. The adapters use native path to locate these executables, which could be different on some nodes or platforms. Because of these problems, J2C resource adapters have to be installed to nodes directly and this is enforced by both wasadmin and admin console. When using resource adapater in a cell environment, you should install to the nodes and then configure them at the cell scope.

J2C resources provide connection factories similar to datasources provided by JDBC resources. They provide common configuration and pool of connection for improving performance. Application code obtains connection from connection factory and then releases the connection when done. THe container taks care of making actual connection, connection pooling,..etc

J2C can use both container managed and component managed security identity propagation.

SIP Misc notes

The Session Initiation protocol (SIP) servlets are packaged in SAR archive file

SIP is used for developing following types of applications

  • Chat instant messaging applications

  • Collaborative, entertainment and gaming applications

  • VIdeo conferencing and video over IP applications

The PortletServingServlet service

A simple portal framework is provided by the PortletServingServlet servlet. The PortletServingServlet servlet registers itself for each Web application that contains portlets. You can use the PortletServingServlet servlet to directly render a portlet into a full browser page by a URL request and invoke each portlet by its context root and name. See Portlet Uniform Resource Locator (URL) addressability for additional information. If you want to aggregate multiple portlets on the page, you need to use the aggregation tag library. The PortletServingServlet servlet can be disabled in an extended portlet deployment descriptor called the ibm-portlet-ext.xmi file.

Extensions for the portlet deployment descriptor are defined within a file called ibm-portlet-ext.xmi. This deployment descriptor is an optional descriptor that you can use to configure WebSphere extensions for the portlet application and its portlets. For example, you can disable the PortletServingServlet servlet for the portlet application in the extended portlet deployment descriptor.

The ibm-portlet-ext.xmi extension file is loaded during application startup. If there are no extension files specified with this setting, the portlet container’s default values are used.

The default for the portletServingEnabled attribute is true. The following is an example of how to configure that a PortletServingServlet servlet is not created for any portlet on the portlet application.

<?xml version="1.0" encoding="UTF-8"?>
<portletappext:PortletApplicationExtension xmi:version="1.0"
<portletappext:portletApplication href="WEB-INF/portlet.xml#myPortletApp"/>

SIP related articles

  1. IBM WebSphere Developer Technical Journal: Session Initiation Protocol in WebSphere Application Server V6.1 -- Part 1

  2. IBM WebSphere Developer Technical Journal: Session Initiation Protocol in WebSphere Application Server V6.1 -- Part 1

Transaction manager high availability

The WebSphere Application Server Transaction Manager writes to its transaction recovery logs when it handles global transactions that involve two or more resources. Transaction recovery logs are stored on disk and are used for recovering in-flight transactions from system crashes or process failures. To enable WebSphere application server transaction peer recovery, it is necessary to place the recovery logs on a highly available file system, such as IBM SAN FS or NAS, for all the application servers within the same cluster to access. All application servers must be able to read from and write to the logs.

For a peer server to recover in-flight transactions, any database locks associated with the failed transactions should be released prior to the recovery. You need to use the lease-based exclusive locking protocol, such as Common Internet File System (CIFS) or Network File System (NFS) Version4, to access remote recovery logs from WebSphere application server nodes. Without the lease-based locking support, if one of the nodes crashes, locks held by all the processes on that node will not automatically be released. As a result, the transactions cannot be completed, and database access can be impaired due to the unreleased locks

In the event of a server failure, the transaction service of the failed application server is out of service. Also, the in-flight transactions that have not be committed might leave locks in the database, which blocks the peer server from gaining access to the locked records. There are only two ways to complete the transactions and release the locks. One is to restart the failed server and the other is to start an application server process on another box that has access to the transaction logs. Using the new HAManager support, a highly available file system and a lease-based locking protocol, a recovery process will be started in a peer member of the cluster. The recovery locks are released and in-flight transactions are committed.

What is a core group

A core group is a high availability domain within a cell. It serves as a physical grouping of JVMs in a cell that are candidates to host singleton services. It can contain stand-alone servers, cluster members, Node Agents, or the Deployment Manager.

A cell must have at least one core group. The WebSphere Application Server creates a default core group, called DefaultCoreGroup, for each cell. Each JVM process can only be a member of one core group. Naturally, cluster members must belong to the same core group. At runtime, the core group and policy configurations are matched together to form high availability groups

A set of JVMs can work together as a group to host a highly available service. All JVMs with the potential to host the service join the group when they start. If the scope of the singleton (such as a Transaction Manager or a messaging engine) is a WebSphere cluster then all members of the cluster are part of such a group of JVMs that can host the service.

In a large-scale implementation with clusters spanning multiple geographies, you
can create multiple core groups in the cell and link them together with the core
group bridge to form flexible topologies. The most important thing is that every
JVM in a core group must be able to open a connection to all other members of
the core group.

A core group cannot extend beyond a cell, or overlap with other core groups. Core groups in the same cell or from different cells, however, can share workload management routing information using the core group bridge service

What is hamanager

IBM WebSphere Application Server Network Deployment V6 introduces a new feature called High Availability Manager (commonly called HAManager) that enhances the availability of WebSphere singleton services such as transaction or messaging services. It provides a peer recovery mechanism for in-flight transactions or messages among clustered WebSphere application servers.HAManager enhances teh availability of singleton services in WebSphere. THese singleton services include

  • Transaction service - Transaction log recovery

  • Messaging service - Messaging engine restarting

The HAManager runs as a service within each WebSphere process (Deployment Manager, Node Agents, or application servers) that monitors the health of WebSphere singleton services. In the event of a server failure, the HAManager will failover any singleton service that was running on the failed server to a peer server. Examples of such a failover include the recovery of any in-flight transactions or restarting any messaging engines that were running on the failed server.The HAManager runs as a service within each WebSphere process (Deployment Manager, Node Agents, or application servers) that monitors the health of WebSphere singleton services. In the event of a server failure, the HAManager will failover any singleton service that was running on the failed server to a peer server. Examples of such a failover include the recovery of any in-flight transactions or restarting any messaging engines that were running on the failed server.

EJB Container failover and WLM

The EJB client ORB plays same role in EJB world as that of HTTP Server plugin plays in the Web application world. Irrepective of if the client is a standalone Java client, another EJB or a servlet in a web application server in which the EJB is running, the EJB client ORB eliminates any one point of failure by dispatching requests among 1 to n application servers residing on multiple nodes. The EJB Client ORB will redirect EJB requests across cluster once a server is unavailable or not responding to response.

Installapp option during node federation

When you federate node to a cell, any existing installed enterprise applications are uninstalled as part of federation process. If you wish to federate any existing user-installed applications into the cell, you can specify the -installapp command line argument when invoking addNode or you can select the Include applications check box if using the WAS Admin console for adding new node. If selected an attempt will be made to copy the applications installed on the application server instance into the cell, but applications with same name as applications that are currently installed into the cell will not be federated into the cell configuration

WAS ND Architecture main components

Deployment Manager
The Deployment Manager process provides a centralized administration mechanism for all nodes in a cell, including all WAS processes on each nodes as well as the cell configuration repository for both WAS and installed applications. The Dmgr works in conjunction with each node agent to control processes on each node and to maintain the configuration for each node. By providing a central point for management, the Dmgr allows you to control cells consisting of numerous nodes and in turn nodes running one or more server.

Node agent

A node agent is a local administrative agent process running on every node in the cell. The node agent server acts as local proxy for deployment manager, providing capability to manage servers and the configuration for each servers defined on a node. The node agent is intended solely as an administative process, the node agent does not provide a J2EE application runtime.If you use wsadmin tool to directly connect to node agent then you will only get access to AdminControl functions, AdminConfig and AdminApp functions are not available to safeguard against accidental changing of the configuration data

Application server
Application server in ND environment is same as the application server in standalone environment, but the difference is that it does not have a Administrative console application, instead configuration for the application server is managed centerally by the Deployment Manager. If you use wsadmin tool to directly connect to application server then you will only get access to AdminControl functions, AdminConfig and AdminApp functions are not available to safeguard against accidental changing of the configuration data

JMS Server
This server hosts the WebSphere Embedded messaging service on a node. In WAS ND there can be one JMS server node.

Admin Client
WAS provides two different admin clients, one is Web based Admin console and other is wasadmin command which is a command line tool

Managed vs unmanaged processes

A node is a logical grouping of managed servers. A node usually corresponds to a logical or physical computer system with a distinct IP host address. Nodes cannot span multiple computers.

Nodes in the network deployment topology can be managed or unmanaged. A managed node has a node agent process that manages its configuration and servers. Unmanaged nodes do not have a node agent.

A managed node has a node agent that manages all servers on a node, whether the servers are WebSphere Application Servers, Java Message Service (JMS) servers (on Version 5 nodes only), Web servers, or generic servers. The node agent represents the node in the management cell and keeps the configuration up to date.

  1. Managed node: A managed node has a node agent that manages all servers on a node, whether the servers are WebSphere Application Servers, Java Message Service (JMS) servers (on Version 5 nodes only), Web servers, or generic servers. The node agent represents the node in the management cell and keeps the configuration up to date. All WAS processes are called managed servers or managed processes, meaning that all are parto f a single administration domain (cell) and results can be centerally managed and monitored. In WAS following processes are managed process

    • Deployment Manager

    • Node Agent

    • Application Server

    • JMS Server

  2. Unmanaged nodes: An unmanaged node does not have a node agent to manage its servers. Unmanaged nodes in the Network Deployment environment can have server definitions such as Web servers, but not Application Server definitions. Unmanaged nodes in the Network Deployment environment cannot have a node agent added to it, and therefore cannot become a managed node. In the stand-alone Application Server environment, nodes do not have node agents and are also considered unmanaged nodes. The deployment manager cannot manage a stand-alone Application Server because it is not known to the cell. A stand-alone Application Server can be federated. When it is federated, a node agent is automatically created, and the node becomes a managed node in the cell.

A supported Web server can be on a managed node or an unmanaged node. You can define only one Web server to a stand-alone WebSphere Application Server node. This Web server is defined on an unmanaged node. You can define Web servers to the deployment manager. These Web servers can be defined on managed or unmanaged nodes.

Application Server component

WebSphere Application Server relies on following server components to provide enterprise level environment

  • Web Browser: The end user uses a Web browser to interact with the deployed applications. The administrator makes use of browser to access the WebSphere Application Server Administration Console

  • IP Sprayer: IP sprayer is normally a hardware unit that seats in front of your web server and distributes user requests among different HTTP server. If you dont use IP sprayer instead point the application URL to HTTP Server then that server becomes single point of failure also if you have a big user load then you might want to distribute users requests among different HTTP server which in turn would distribute user requests to different WAS server. The IP sprayer can either randomly distribute requests between different HTTP Servers or they can be sophisticated things like if the user request particular application then forward that request to high performance/ powerful server

  • Load balance: The end user of WAS, normally points to the load balance, which takes care of distributing the user requests between different HTTP servers. The load balancer makes sure that no individual server is overwhelemed with the requests while other servers are idel.

  • HTTP Server and Web Server Plugin: THe HTTP server is used for two things first is to server static content and in addition to that it also makes use of WebSPhere Plugin to distribute requests among different servers where the application is configured (Usually different servers in cluster). The HTTP server is normally configured to use either weighted round robin scheduling algorith, where the first request is distributed to a random application server, which servers as a starting point and then the subsequent requests are distributed according to the assigned weights of the application server. You can also configure plugin to use random system in which case the server weightage is not taken into consideration and the requests are distributed randomly. The HTTP server also takes care of session affinity, which makes sure that the request from the client goes to same server which served last request for that client

  • Firewall: A firewall is a hardware and software system that manages the flow of information between the Internet and your companies network. It takes care of things like blocking user access to only few predefined ports, it can block virus and denial of service attacks.

  • Database server: Most of the enterprise applications use RDBMS for data storage and retrieval functionality. The Application developers decide what database to use, there structure,.. The WebSPhere application server does not store any configuration data in db, that data is stored in .xml files on the file system

  • Websphere MQ: WebSPhere MQ is messaging backbone that is used for exchanging point-to-point message and publish-and-subscribe messaegs with applications that reside a WebSphere MQ network.

Procedure to enable SSL between web server and WebSphere Application Server

I wanted to try enabling SSL between my WebServer and WebSphere Application Server so i followed this process to do that

Exchanging public certificate

This section provides details and step-by-step instructions for exchanging public certificates between two key stores or trust (certificate) stores. You must perform the certificate exchange when you want to set up trust between two parties based on certificates. Usually you use this process with self-signed certificates because real certificates issued by well-known Certificate Authorities are already included in the key and trust stores.

  • Start ikeyman and open the file that you just C:\Cert\HTTPServer\conf\keys\WAS6PluginCertificates.kdb, whose public certificate you want to export

  • Now select the personal certificate that you created, in my case it is WASPluginCertificate and click on Extract Certificate button

  • ikeyman tool will display a dialog where you can set location where the public certificat should be exported. Export it to c:\temp\publiccertificate\WAS6PluginCertificates.arm

  • Now open the C:\Cert\WebSphere\AppServer\profiles\Dmgr01\config\cells\dmgrCell01\WAS6WebContainerCertificates.jks file in iKeyman tool

  • Switch to the Signer certificate view by selecting signer certificate in the key database content section

  • Now click on add, and it will show you the Add CA's certificate from file dialog, select the c:\temp\publiccertificate\WAS6PluginCertificates.arm file that you exported and click OK

  • It will ask you to enter a lable for the public certificate enter WAS6PluginCertificatesCertificate.

  • Now you should be able to see the certificate that you just imported in the list

Creating self signed certificate

IBM provides a ikeyman tool that you can use to create self signed certificate and manage keys by following these steps

  1. Go to the WAS_HOME/bin directory and execute ikeyman tool, it will open a GUI based tool like this

  2. Now click on Key Database File - New. It will open a dialog box, in that change Key Database type to CMS and enter file and path name. In my case i am creating WAS6PluginCertificates.kdb file in C:\Cert\HTTPServer\conf\keys\ directory and click OK

  3. It will ask you for the password for the Key database file, enter a password, then check Stash the password to a file checkbox.

  4. It will create a .kdb file and import bunch of keys for you by default and show a message like this

  5. Once the .kdb file is created next step is to create a Self Signed certificate so click on Create - New Self Signed Certificate like this

  6. Enter the details for self signed certificate such as, key label, Organizations,...

  7. Thats it your self signed certificate is created, you can check them by going to the directory where we saved it. You will see 4 different files for that certificate are created out of that .sth is the stash password file

Role Mapping in installed application

If you did not map application roles to users during installation you can map security roles to users and groups in installed application by following these rules

  • Go the WAS Admin COnsole, select the enterprise application in which you want to map roles, If your application defines roles, then you will see "Security role to user/group mapping" link in the Detail properties section, click on that link

  • When you click on that link you will get a "Security role to user/group mapping" page like this, which will list out all the roles in your application and let you map those roles

Role mapping during application installation

During the process of running the application installation, you see the Map
security roles to users or groups step. In this step, you have the option of
selecting any of the roles and assigning a user or a group from the user registry
using one of the lookups. You can also assign one of the special subjects
(Everyone or All authenticated) to the role.

Follow these steps to map roles during the installation.

  • In the enterprise application installation wizard, choose "Show me all installation options and parameters" radio box on the first screen. If you dont do that then the installation option wont show you option to Map security roles to users or groups page

  • Follow the installation wizard and then on the Map security roles to users or groups pages, you will get list of roles defined in your application and you could either assign them to roles all authenticated users or everyone or you can select the application role and click on Look up Users or Look up Groups button

  • If you want to select individual users that should be assigned particular application role, you will get a screen like this select the users

Enabling application security

By default, administrative security is enabled during installation, and application security is disabled. For application security to be enabled and take effect, you must enable administrative security.

After enabling application security synchronize your changes to all the nodes and restart everything, DMGR, Node Agents and server. Once server is restart try accessing /snoop servlet, it should prompt you for username and password

What is applicatioin security

Application security enables security for the applications in your environment.Application security provides application isolation and requirements for authenticating users for the applications in your environment. Application security must be enabled in case declarative security is used by any application that is deployed in the application server. However if your application relies only on programmatic secuirty, for example using the HttpServletRequest interface method getRemoteUser() wherer authentication is already done on the HTTP server side, your not required to enable application security

In previous releases of WebSphere Application Server, when a user enabled global security, both administrative and application security were enabled. In WebSphere Application Server Version 6.1, the previous notion of global security is split into administrative security and application security, each of which you can enable separately.

As a result of this split, WebSphere Application Server clients must know whether application security is disabled at the target server. Administrative security is enabled, by default. Application security is disabled, by default. Before you can enable application security, you must verify that administrative security is enabled. Application security is in effect only when administrative security is enabled.

For Web resources, when application security is enabled, security constraints on those resources in web.xml are enforced. When accessing a protected resource, a web client is prompted for authentication.

For enterprise bean resources, when application security is disabled, the client Common Secure Interoperability version 2 (CSIv2) code ignores the CSIv2 security tags for objects that are unknown system objects. When pure clients see that application security is disabled, these clients prompt for naming lookups, but do not prompt for enterprise bean operations.

Administrative user roles

The WAS Administration console application uses the J2EE role-based authorization concept. It has following roles

  • Monitor: Least privileged. Allows a user to view the WebSphere
    configuration and current application server state.A monitor can complete the following tasks:

    • View the WebSphere Application Server configuration.

    • View the current state of the Application Server.

  • Configurator: An individual or group that uses the configurator role has the monitor privilege plus the ability to change the WebSphere Application Server configuration. The configurator can perform all the day-to-day configuration tasks. For example, a configurator can complete the following tasks:

    • Create a resource.

    • Map an application server

    • Install and uninstall an application.

    • Deploy an application.

    • Assign users and groups-to-role mapping for applications.

    • Set up Java 2 security permissions for applications.

    • Customize the Common Secure Interoperability Version 2 (CSIv2), Secure Authentication Service (SAS), and Secure Sockets Layer (SSL) configurations..

  • Operator: Monitor privilege in addition to the ability to change runtime state, such as starting or stopping server, also check server status.

  • Deployer: Only available for wsadmin users (not administration console). Allows a user to change configuration and runtime state on applications using wsadmin.

  • Admin Security Manager: Allows a user to map users and groups to administrative roles through the administrative console, or through wsadmin for fine-grained security. Also, when fine grained administrative security is used, users granted this role can manage authorization groups

  • iscadmins: Only available for administration console users. Allows a user to manage users and groups in the Federated repositories.

  • Administrator: Operator, configurator, and iscadmins privilege, in addition to additional privileges granted solely to the administrator role, such as:

    1. Modifying the primary administrative user and password

    2. Create, update, and delete users and groups

    3. Enabling or disabling administrative and Java 2 security

The primary administrative user specified when enabling administrative security is automatically mapped to the Administrator and AdminSecurityManager roles. Therefore, it is not necessary to manually add this identity to either of these administrative roles.

Disabling admin security

You might want to disable administrative security in few situations, such as

  • You forgo the WAS Admin User

  • There is some problem with the security configuration and your not able to start server

You can disable security using wsadmin command line tool like this. Start the wsadmin tool with wsadmin -conntype NONE, once the wsadmin prompt is displayed execute securityoff command and restart the server.

Or you can open the WebSphere\AppServer\profiles\Dmgr01\config\cells\dmgrCell01\security.xml and search for enable word, change value of the enabled attribute to false

<security:Security xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:orb.securityprotocol="http://www.ibm.com/websphere/appserver/schemas/5.0/orb.securityprotocol.xmi" xmlns:security="http://www.ibm.com/websphere/appserver/schemas/5.0/security.xmi" xmi:id="Security_1" useLocalSecurityServer="true" useDomainQualifiedUserNames="false" enabled="false" cacheTimeout="600" issuePermissionWarning="false" activeProtocol="BOTH" enforceJava2Security="false" enforceFineGrainedJCASecurity="false" appEnabled="true" dynamicallyUpdateSSLConfig="true" activeAuthMechanism="LTPA_1" activeUserRegistry="WIMUserRegistry_1" defaultSSLSettings="SSLConfig_1">

Easiest way of disabling security if you know the admin user id and password is using the WAS Admin Console

What is Server User Identity

WebSphere Application Server V6.1 separates the server user identity from the primary administrative user. The primary administrative user is any valid user in the user account repository that you choose to give default administrative privileges. The server user identity is used for server to server communication. By selecting the automatically generated server identity, WebSphere creates an identity for internal communications that is not stored in the repository and does not have a password. LDAP directories still require a bind DN for successful communications.

WAS will ask you for the sever user identity while configuring user repository

Main components of WebSphere security

WAS 6.1 Security has three main components

  • Authentication protocol: The authentication protocol is used for Remote Method Invocation (RMI) over the Internet InterORB Protocol (IIOP) requests when security is enabled. WebSphere Application Server is configured to use Common Secure Interoperability Version 2 (CSIV2) by default. Secure Authentication Service has been deprecated and will be removed from future WebSphere releases. The CSIV2 is defined by the Object Management Group (OMG) as a standard authentication protocol for vendors to interoperate securely.

  • Authentication mechanism: The WebSphere Application Server uses Lightweight Third Party Authentication (LTPA) as the default authentication mechanism.LTPA supports forwardable credentials and, for security reasons, a configurable expiration time is set on the credentials. The use of LTPA allows you to enable single sign-on (SSO) for your security domain

  • User account repository: The WAS 6.1 server supports 4 different types of user repository

Enablign administrative security

When your installing WebSphere Application Server 6.1, the installation process will ask you if you want to enable the administrative security, if you say yes it will let you specify the username password for the admin user. When you enable security during the Installation process, the WAS server will be configured to use file based federated repository

If you dont enable the administrative security at the time of installation, or if you have to disable it for some other reason, then you can re-enable the admin security from WAS Admin console by going to Security - Secure administration, applications, and infrastructure, page and then checking "Enable administrative security" checkbox saving your changes, synchronizing those changes to all the nodes and then restarting all the servers, node agents and DMGR

What does admin security protect

The configuration of administrative security for a security domain involves configuring the following technologies:

  • Authentication of HTTP clients

  • Authentication of IIOP clients

  • Administrative console security

  • Naming security

  • Use of SSL transports

  • Role-based authorization checks of servlets, enterprise beans, and mbeans

  • Propagation of identities (RunAs)

  • The common user registry

  • The authentication mechanism

  • Other security information that defines the behavior of a security domain includes:

    1. The authentication protocol (Remote Method Invocation over the Internet Inter-ORB Protocol (RMI/IIOP) security)

    2. Other miscellaneous attributes

What is administrative security

Administrative security represents the security configuration that is effective for the entire security domain. A security domain consists of all of the servers that are configured with the same user registry realm name. In some cases, the realm can be the machine name of a local operating system registry. In this case, all of the application servers must reside on the same physical machine. In other cases, the realm can be the machine name of a standalone Lightweight Directory Access Protocol (LDAP) registry.

A multiple node configuration is supported because you can access remotely user registries that support the LDAP protocol. Therefore, you can enable authentication from anywhere.

The basic requirement for a security domain is that the access ID that is returned by the registry or repository from one server within the security domain is the same access ID as that returned from the registry or repository on any other server within the same security domain. The access ID is the unique identification of a user and is used during authorization to determine if access is permitted to the resource. The administrative security configuration applies to every server within the security domain.

Enabling administrative security activates a wide variety of security settings for WebSphere Application Server. While the values of these settings can be specified they take effect only when administrative security is activated. These settings include authentication of users, the use of Secured Socket Layer(SSL), the choice of user account repository and application security

In WAS 6.1, the global security has been split into administrative and application security, each of which can be enabled separately. However, in order for application security to take effect administrative security must be enabled.

Implementing Federated repository

I used information in Expand your user registry options with a federated repository in WebSphere Application Server V6.1 article for configuring federated repository

Limitations of federated repository

  • Only one user repository can be configured to be the target for creating users/groups from the administration console. By default, this is the file repository, but this can be changed, as you will see later. You can use the user and group management wsadmin commands to create users/groups in other repositories, or use native tools for those repositories.

  • The username (for example, LDAP uid) must be unique across the different repositories. For example, users cannot have the same uid in different LDAP directories, even under different org structures.

  • If one or more repository in the federation is down, you will not be able to authenticate (even as an admin), regardless of which repository your particular ID is stored in. The VMM component always checks all repositories before letting an authentication to succeed.

  • Although VMM has the capability to support multiple realms, WebSphere Application Server only supports a single realm at this time. This is defined at the cell level and is shared by all applications.

What is virtual memeber manager

The Virtual Member Manager is a new component that incorporates some of the existing capabilities in the WebSphere registry, the WebSphere Member Manager (from WebSphere Portal), and a subset of the secure administrations functions. The goals of the VMM are to:

  • Provide a repository-independent programming interface.

  • Support various pluggable repositories.

  • Provide the ability for users to achieve a single view of their own multiple repositories in a federated model.

Important Note: custom repository is not included in the list of what can make up a federated repository realm. As it exists today, VMM does not support custom repositories. Therefore, if you need a custom repository, you cannot use VMM. Instead, you must write a custom user registry, the same as you needed to do in previous releases.

A federated repository contains a realm that can consist of identities in:

  • The file-based repository that is built into the system.

  • One or more external LDAP repositories.

  • A JDBC accessible database repository.

Unlike with the local operating system, standalone LDAP directory, or custom registry options, federated repositories provide user and group management with read and write capabilities. When you configure federated repositories, you can add, create, and delete users and groups using one of these:

  • User/group management application programming interfaces (API).

  • Administrative console.

  • wsadmin commands.

What is federated repository

Before now, the support in IBM WebSphere Application Server for environments where user information was stored in multiple independent user registries was somewhat limited. Prior to Version 6.1, the only registry options available were:

  • Local operating system registry.

  • A single, standalone Lightweight Directory Access Protocol (LDAP) registry.

  • A single implementation of the Custom User Registry interface.

It is possible to implement a Custom User Registry that enables access to multiple other registries, but this can involve a significant development effort that ultimately would only support read-only operations.

WebSphere Application Server V6.1 provides a new option: a federated user repository. This feature makes it much simpler to use multiple repositories, since this capability is achieved through configuration -- rather than development -- with the use of the new Virtual Member Manager (VMM).

In essence, this feature provides the ability to map entries from multiple individual user repositories into a single virtual repository. The federated repository consists of a single named realm, which is a set of independent user repositories. Each repository may be an entire external repository or, in the case of LDAP, a subtree within that repository. The root of each repository is mapped to something called a base entry within the federated repository, which is basically a starting point within the hierarchical namespace of the virtual realm.

What we are discussing here is the idea of one logical registry containing users from multiple underlying repositories. To the WebSphere Application Server runtime, there is still only one registry, and thus, all applications in the cell still share this one single registry

A federated repository enables you to use multiple repositories with WebSphere Application Server V6.1. These repositories, which can be file-based repositories, LDAP repositories, or a sub-tree of an LDAP repository, are defined and theoretically combined under single realm. All of the user repositories that are configured under the federated repository functionality are transparent to WebSphere Application Server.

Tips for multiple user repositories: The user ID and the DN for an LDAP repository must be unique in multiple user repositories that are configured under the same federated repository configuration. In addition, the federated repositories functionality in WebSphere Application Server supports the logical joining of entries across multiple user repositories when the application server searches and retrieves entries from the repositories.

Not able to login with users short name

When i was trying to setup the Stand-alone LDAP Registry, i was able to setup the registry but i was not able to login into WAS with Users short name. Ex. I was able to login with uid=wasadmin,cn=users,dc=webspherenotes,dc=com but not with wasadmin as user name.

So i did some investigation it seems that the value of User Filter field on "Advanced Lightweight Directory Access Protocol(LDAP) user registry settings" page was not correct the value of objectclass was ePerson. When i changed it to inetOrgPerson it worked.

I think now i understand how to figure out what value to use for both User Filter, Group Filter and DN and how to verify those values.

Basic idea is that the value of DN should be equal to the context at which you want to start executing the search Ex. In my case i am using dc=webspherenotes,dc=com as base DN and (&(uid=%v)(objectclass=inetOrgPerson)) as User filter and as group filter.

Now when i try to login into WAS with say wasadmin user, WAS will take the DN and start search at that location, it will take the user name that i used for login replace the %v in the user filter with that and search for (&(uid=wasadmin)(objectclass=inetOrgPerson)). If the search is able to return one record then the password will be verified. You can try this manually using the LDAP browser like this.

You should be able to locate the wasadmin user record like this

Similarly when WAS wants to search for the groups it will take the group filter replace %v with the group name and search for it.

WebSphere Application Server - Setting up stand-alone LDAP registry

I wanted to try setting up Stand-alone LDAP registry. So i did install both WAS ND and IBM Tivoli directory server on my VMWare, then i did setup test data in my LDAP server

After that i followed these steps to setup the Standalone LDAP user registry

  • Login into the WAS Admin Console and go to Security - Security Administration, application and infrastructure. I did select enable security while installing the WAS server, so by default is configured with federated file based repository, change the value of Available realm definitions to Standalone LDAP Registry and click on Configure

  • On the next page configure the LDAP details. In my case the LDAP server is on same machine so host name is localhost, it is listening on 389 port so thats the port name and then i used WebSphereNotesUsers.ldif for setting up LDAP data so that takes care of the Base distinguished name, Binding distinguished name, Bind Password,...

  • Go to Advanced Lightweight Directory Access protocol and change value of User Filter to use objectclass=inetOrgPerson, that is because if you check WebSphereNotesUsers.ldif, you will notice that all the users that we are creating have inetOrgPerson as object class

  • Save your changes, come back to main page and make sure that Standalone LDAP Registry as Available realm choice, then click on Set as current.

  • Save your changes, synchronize them to nodes, stop every thing and restart it.

  • Once the server is restarted you should be able to login with wasadmin/wasadmin username and password. You should also be able to see the users from LDAP in Manage Users in WAS Admin Console

Starting/Stopping LDAP Server

I have IBM Tivoli directory server V6.1 setup on my local machine and i use following commands to administer it

  • Starting server: /opt/ibm/ldap/V6.1/sbin/idssldap -I idsinst

  • Starting Web Admin server: /opt/ibm/ldap/V6.1/appserver/bin/startServer.sh server1

  • Stopping server /opt/ibm/ldap/V6.1/sbin/idssldap -I idsinst -k

  • Stopping Web Admin server: /opt/ibm/ldap/V6.1/appserver/bin/stopServer.sh server1

ONce the web admin server is started go to http://localhost:12100/IDSWebApp/IDSjsp/Login.jsp page, and the default login is cn=root and password is "secret" or superadmin/secret

You can change the password for the cn=root user using idsxcfg tool

WAS -Setting up stand-alone LDAP Server

I tried setting up Stand-alone LDAP Server as user registry/repository on my WAS 6.1 Server. These are the steps that i followed for that

  • I did install IBM's Tivoli Directory Server in my VMWare machine

  • Next step is to setup the LDAP Server, with correct data. I used the idsxcfg tool for that.

  • Add dc=webspherenotes,dc=com as suffix

  • Download the WebSphereNotesUsers.ldif file, it has set of users and groups that will need in order to setup the LDAP server

  • Import WebSphereNotesUsers.ldif file in the LDAP server using the idsxcfg tool

  • Now start your LDAP server and LDAP Web Admin tool

  • Login into the LDAP server and verify data that we imported from the WebSphereNotesUser.ldif file

What is custom user registry

The supported registries such as LDAP, Operating system, federated repositories are good enough for most of the requirements but there could be cases where you might want to implement custom user registry either for better control or because you have some special situation.

The UserRegistry interface is used to implement both the custom registry and the federated repository options for the user account repository. The interface is helpful in situations where the current user and group information exists in some other format. The UserRegistry interface is also used for LocalOS and LDAP registries, for example, all our registries.

WebSphere Application Server V6.1 also provides a plug-in to support any registry by using the custom registry feature. With the custom registry feature, you can configure any user registry that is not made available through the security configuration panels of the WebSphere Application Server V6.1

Load balancing options

You can specify the load balancing option that the plug-in uses when sending requests to the various application servers associated with that Web server

This field corresponds to the LoadBalanceWeight element in the plugin-cfg.xml file. We have two options to choose from for the load balancing

  • Round robin (default): When using this algorithm, the plug-in selects, at random, a cluster member from which to start. The first successful browser request will be routed to this cluster member and then its weight is decremented by one. New browser requests are then sent round robin to the other application servers and, subsequently, the weight for each application server is decremented by one. The spreading of the load is equal between application servers until one application server reaches a weight of zero. From then on, only application servers without a weight higher than zero will receive routed requests. The only exception to this pattern is when a cluster member is added or restarted.

  • RandomRequests are passed to cluster members randomly. Weights are not taken into account as in the round robin algorithm. The only time the application servers are not chosen randomly is when there are requests with associated sessions. When the random setting is used, cluster member election does not take into account where the last request was handled. This means that a new request could be handled by the same cluster member as the last request.

Automatically propagating the plugin-cfg.xml

The Web server plug-in configuration service by default propagates the plugin-cfg.xml file automatically

In my local environment both automatic regeneration and propagation of plugin is truned on so when i install application it automatically regenerates the plugin-cfg.xml and then copies it to the C:\Cert\HTTPServer\Plugins/config/webserver1 directory

Manually propagating the plug-in configuration file

After a plug-in configuration file is regenerated, it needs to be propagated to the Web server. The configuration service can automatically propagate the plugin-cfg.xml file to a Web server machine if it is configured on a managed node, and to an IBM HTTP Server if it is configured on an unmanaged node. For other scenarios, you must manually copy the file to the Web server machines. You can manually propagate the file by copying it from the application server machine to the Web server machine, or you can do it from the administrative console.

I tried propagating the plugin-cfg.xml file manually using the WAS Admin console by selecting the server and clicking on Propageate Plug-in button

Important: The Web server binary plug-in module checks for a new configuration file every 60 seconds. You can wait for the plug-in to find the changes, or you can restart the Web sever to invoke the changes immediately

Automatic regeneation of plugin-cfg.xml

The Web server plug-in configuration service by default regenerates the
plugin-cfg.xml file automatically. You can check the setting from WAS Admin console

When selected, the Web server plug-in configuration service automatically generates the plug-in configuration file whenever the Web server environment changes. For example, the plug-in configuration file is regenerated whenever one of the following activities occurs:

  • A new application is deployed on an associated application server.

  • The Web server definition is saved.

  • An application is removed from an associated application server.

  • A new virtual host is defined.

Whenever a virtual host definition is updated, the plug-in configuration file
is automatically regenerated for all of the Web servers.

In my local environment i tried installing a new web application and after installation was completed i checked the plugin-cfg.xml file and it had a entry for newly installed application. Also i could see this in my DMGR's SystemOut.log file

[9/14/09 21:29:23:290 PDT] 00000052 DeploymentMan A ADMS0208I: The configuration synchronization complete for cell.
[9/14/09 21:29:29:540 PDT] 00000048 FileRepositor A ADMR0016I: User defaultWIMFileBasedRealm/server:dmgrCell01_dmgrCellManager01_dmgr modified document cells/dmgrCell01/nodes/dmgrNode01/servers/webserver2/plugin-cfg.xml.
[9/14/09 21:29:29:540 PDT] 00000048 SystemOut O
[9/14/09 21:29:29:540 PDT] 00000048 SystemOut O
[9/14/09 21:29:29:540 PDT] 00000048 SystemOut O PLGC0005I: Plug-in configuration file = C:\Cert\WebSphere\AppServer\profiles\Dmgr01\config\cells\dmgrCell01\nodes\dmgrNode01\servers\webserver2\plugin-cfg.xml
[9/14/09 21:29:29:540 PDT] 00000048 SystemOut O
[9/14/09 21:29:29:540 PDT] 00000048 SystemOut O PLGC0052I: Plug-in configuration file generation is complete for the Web server dmgrCell01.dmgrNode01.webserver2.
[9/14/09 21:29:29:540 PDT] 00000048 SystemOut O PLGC0052I: Plug-in configuration file generation is complete for the Web server dmgrCell01.dmgrNode01.webserver2.
[9/14/09 21:29:29:556 PDT] 00000048 SystemOut O PLGC0051I: Plug-in configuration file generation started for the Web server dmgrCell01.dmgrNode01.webserver1.
[9/14/09 21:29:30:150 PDT] 00000048 FileRepositor A ADMR0016I: User defaultWIMFileBasedRealm/server:dmgrCell01_dmgrCellManager01_dmgr modified document cells/dmgrCell01/nodes/dmgrNode01/servers/webserver1/plugin-cfg.xml.
[9/14/09 21:29:30:150 PDT] 00000048 SystemOut O
[9/14/09 21:29:30:150 PDT] 00000048 SystemOut O
[9/14/09 21:29:30:150 PDT] 00000048 SystemOut O PLGC0005I: Plug-in configuration file = C:\Cert\WebSphere\AppServer\profiles\Dmgr01\config\cells\dmgrCell01\nodes\dmgrNode01\servers\webserver1\plugin-cfg.xml
[9/14/09 21:29:30:150 PDT] 00000048 SystemOut O
[9/14/09 21:29:30:150 PDT] 00000048 SystemOut O PLGC0052I: Plug-in configuration file generation is complete for the Web server dmgrCell01.dmgrNode01.webserver1.
[9/14/09 21:29:30:150 PDT] 00000048 SystemOut O PLGC0052I: Plug-in configuration file generation is complete for the Web server dmgrCell01.dmgrNode01.webserver1.
[9/14/09 21:29:56:775 PDT] 00000055 SystemOut O
[9/14/09 21:29:56:775 PDT] 00000055 SystemOut O PLGC0062I: The plug-in configuration file is propagated from C:\Cert\WebSphere\AppServer\profiles\AppSrv01\config\cells\dmgrCell01\nodes\dmgrNode01\servers\webserver2\plugin-cfg.xml to C:\Cert\HTTPServer\Plugins\config\webserver2\plugin-cfg.xml on the Web server computer.
[9/14/09 21:29:56:775 PDT] 0000001f SystemOut O
[9/14/09 21:29:56:775 PDT] 0000001f SystemOut O PLGC0048I: The propagation of the plug-in configuration file is complete for the Web server dmgrCell01.dmgrNode01.webserver2.
[9/14/09 21:29:56:853 PDT] 00000055 SystemOut O
[9/14/09 21:29:56:853 PDT] 00000055 SystemOut O PLGC0062I: The plug-in configuration file is propagated from C:\Cert\WebSphere\AppServer\profiles\AppSrv01\config\cells\dmgrCell01\nodes\dmgrNode01\servers\webserver1\plugin-cfg.xml to C:\Cert\HTTPServer\Plugins/config/webserver1/plugin-cfg.xml on the Web server computer.
[9/14/09 21:29:56:869 PDT] 0000001f SystemOut O
[9/14/09 21:29:56:869 PDT] 0000001f SystemOut O PLGC0048I: The propagation of the plug-in configuration file is complete for the Web server dmgrCell01.dmgrNode01.

Manually regenerating plugin-cfg.xml

You can regenerate the plugin-cfg.xml file manually in two ways

Using WAS Admin Console

Login into the WAS Admin console, select the web server for which you want to regenerate plugin and click on Generate Plug-in button. The new plugin-cfg.xml file will be created in the config directory of the web server like this

Using GenPluginCfg command

You can also regenerate plugin using the GenPluginCfg command line tool by going to dmgr_profile_home/bin directory and executing GenPluginCfg command like this

Regenerating plugin configuration file

The plug-in configuration file (i.e. plugin-cfg.xml), has information on how to route a request from browser to the correct application on the application server. So you will have to regenerate this file in case of there is any changes in websphere application server that affects how the request is routed from the web server to the application server.

The plugin-cfg.xml should be regenerated in following situations

  • Installing or removing application

  • Creating or changing virtual host

  • Creating or changing cluster

  • Creating a new server

  • Modifying HTTP transport settings

You can manually regenerate plugin using either the GetPluginCfg command, or using the WAS Admin console, or you can also setup the plug-in properties of the web server to enable automatic generation of the file, whenever relevant changes are made

Plugin configuration file

The plug-in configuration file (plugin-cfg.xml) contains routing information for all applications mapped to the Web server. This file is read by a binary plug-in module loaded in the Web server. An example of a binary plug-in module is the mod_ibm_app_server_http.dll file for IBM HTTP Server on the Windows platform. This is how the location of plugin-cfg.xml is defined in httpd.conf file

LoadModule was_ap20_module "C:\Cert\HTTPServer\Plugins\bin\32bits\mod_was_ap20_http.dll"
WebSpherePluginConfig "C:\Cert\HTTPServer\Plugins\config\webserver1\plugin-cfg.xml"

The binary plug-in module does not change. However, the plug-in configuration file for the binary module needs to be regenerated and propagated to the Web server whenever a change is made to the configuration of applications mapped to the Web server. The binary module reads the XML file to adjust settings and to locate deployed applications for the Web server.

This is how the sample plugin-cfg.xml file on my machine looks like

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--HTTP server plugin config file for the webserver dmgrCell01.dmgrNode01.webserver1 generated on 2009.09.13 at 06:50:03 PM PDT-->
<Config ASDisableNagle="false" AcceptAllContent="false" AppServerPortPreference="HostHeader" ChunkedResponse="false" FIPSEnable="false" HTTPMaxHeaders="300" IISDisableNagle="false" IISPluginPriority="High" IgnoreDNSFailures="false" RefreshInterval="60" ResponseChunkSize="64" SSLConsolidate="false" TrustedProxyEnable="false" VHostMatchingCompat="false">
<Log LogLevel="Error" Name="C:\Cert\HTTPServer\Plugins/logs/webserver1/http_plugin.log"/>
<Property Name="ESIEnable" Value="true"/>
<Property Name="ESIMaxCacheSize" Value="1024"/>
<Property Name="ESIInvalidationMonitor" Value="false"/>
<Property Name="ESIEnableToPassCookies" Value="false"/>
<VirtualHostGroup Name="default_host">
<VirtualHost Name="*:9080"/>
<VirtualHost Name="*:80"/>
<VirtualHost Name="*:9443"/>
<VirtualHost Name="*:5060"/>
<VirtualHost Name="*:5061"/>
<VirtualHost Name="*:443"/>
<VirtualHost Name="*:9081"/>
<VirtualHost Name="*:9082"/>
<ServerCluster CloneSeparatorChange="false" GetDWLMTable="false" IgnoreAffinityRequests="true" LoadBalance="Round Robin" Name="cluster1" PostBufferSize="64" PostSizeLimit="-1" RemoveSpecialHeaders="true" RetryInterval="60">
<Server CloneID="14dtuu8g3" ConnectTimeout="0" ExtendedHandshake="false" LoadBalanceWeight="2" MaxConnections="-1" Name="dmgrNode01_server2" ServerIOTimeout="0" WaitForContinue="false">
<Transport Hostname="dmgr.webspherenotes.com" Port="9081" Protocol="http"/>
<Transport Hostname="dmgr.webspherenotes.com" Port="9444" Protocol="https">
<Property Name="keyring" Value="C:\Cert\HTTPServer\Plugins/config/webserver1/plugin-key.kdb"/>
<Property Name="stashfile" Value="C:\Cert\HTTPServer\Plugins/config/webserver1/plugin-key.sth"/>
<Server CloneID="14dtuueci" ConnectTimeout="0" ExtendedHandshake="false" LoadBalanceWeight="2" MaxConnections="-1" Name="dmgrNode01_server4" ServerIOTimeout="0" WaitForContinue="false">
<Transport Hostname="dmgr.webspherenotes.com" Port="9082" Protocol="http"/>
<Transport Hostname="dmgr.webspherenotes.com" Port="9445" Protocol="https">
<Property Name="keyring" Value="C:\Cert\HTTPServer\Plugins/config/webserver1/plugin-key.kdb"/>
<Property Name="stashfile" Value="C:\Cert\HTTPServer\Plugins/config/webserver1/plugin-key.sth"/>
<Server Name="dmgrNode01_server2"/>
<Server Name="dmgrNode01_server4"/>
<UriGroup Name="default_host_cluster1_URIs">
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/dynasession/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/dynacachereplication/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/cachemonitor/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/HelloWorldWeb/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/helloworldportlet/HelloWorldPortlet/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/helloworldportlet/HelloWorldPortlet2/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/helloworldportlet/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/NameSpaceWeb/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/webappext/*"/>
<Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/sessionaffinity/*"/>
<Route ServerCluster="cluster1" UriGroup="default_host_cluster1_URIs" VirtualHostGroup="default_host"/>
<RequestMetrics armEnabled="false" loggingEnabled="true" rmEnabled="true" traceLevel="HOPS">
<filters enable="false" type="URI">
<filterValues enable="false" value="/snoop"/>
<filterValues enable="false" value="/hitcount"/>
<filters enable="false" type="SOURCE_IP">
<filterValues enable="false" value=""/>
<filterValues enable="false" value=""/>
<filters enable="false" type="JMS">
<filterValues enable="false" value="destination=aaa"/>
<filters enable="false" type="WEB_SERVICES">
<filterValues enable="false" value="wsdlPort=aaa:op=bbb:nameSpace=ccc"/>

Important Note When the plug-in configuration file is generated, it does not include admin_host in the list of virtual hosts.