© Copyright International Business Machines Corporation 2003. All rights reserved.

Introduction

IBM ® WebSphere® Application Server (hereafter called Application Server) Version 5.0 provides enhancements to scalability, reliability, Web services, J2EE^TM 1.3 certification, and many other areas. Version 5.0 also provides a completely rewritten infrastructure for you to manage and administer your servers and applications. An open standards-based management framework, Java^TM Management Extensions (JMX) is at the core of the 5.0 management capabilities. New administration tool sets built for Version 5.0 take advantage of this framework. Also, you can use the Version 5.0 administration tool capabilities for your own custom administration programs.

This system administration series will discuss a variety of ways to use the Application Server 5.0 management features. Part 1 introduces the basic system administration concepts needed to understand Version 5.0 features. The first important concept to grasp is the new packaging structure for Application Server 5.0. To understand Application Server administration, you also need to familiarize yourself with the following concepts: servers, nodes and node agents, cells, and the deployment manager. It is important that you understand the various processes in the administrative topology and the operating environment in which they apply.

Future articles in this series will delve into the details surrounding various administration topics, such as writing your own custom management program, extending the Application Server administration system, and using the powerful administrative scripting capabilities built into Version 5.0.

Back to top

WebSphere Application Server structure

Application Server 5.0 provides an entirely new packaging structure. Several installation images build on one another to incrementally expand the features available to you. Start with the base product installation, and then add features, for example, extended programming model enhancements or multi-node network deployment capabilities, as you need them. The two basic packages are Base Application Server and Network Deployment.

The Base Application Server package

A base WebSphere Application Server installation includes everything needed for a single Application Server process. Additional server processes can be logically grouped into nodes. A node can contain many servers, but cannot span multiple computer systems. A single computer system can have multiple nodes installed on it, each with multiple managed servers. For example, multiple nodes defined on a large multi-user enterprise server makes better use of the system resources, and can isolate projects from one another. Figure 1 depicts the base environment.

A limitation of this package on its own is that it does not support the coordination between application server processes. Administration is limited to a single process at a time. The Network Deployment package extends the base Application Server with capabilities for multi-process, multi-node configuration and control.

The Network Deployment package

A Network Deployment installation can support a network of computer systems that are configured to run collaborating instances of the base Application Server installation. The Network Deployment package provides centralized administration and workload management for a set of nodes, referred to as a cell. A cell has a master administrative repository that stores the configuration data for all of the nodes in the cell. Figure 2 depicts multiple systems in a Network Deployment cell, and shows that a base server can be added to a Network Deployment cell.

One computer is designated as the central deployment manager machine onto which the Network Deployment package is installed. The central deployment manager program that is included in this package manages all of the nodes in the cell. To add a Base Application Server installation to the cell, run the addNode program on the base installation. After this is completed, a separate node agent process is created that serves as an intermediary between the application servers on the node and the deployment manager. Administrative logic that runs in the node agent keeps the configuration data for a node synchronized with the master configuration data for the cell.

Besides grouping servers into nodes, another logical grouping of servers is the cluster. A cluster can contain servers on different nodes. All of the servers in a cluster must have the identical application deployment configuration, since the purpose of a cluster is to define servers that collaborate for workload balancing and failover capabilities.

Back to top

Comparison of the administration implementation in Versions 4.0 and 5.0

Before getting into the details of Application Server 5.0, it is useful to compare the implementation of system administration in Version 5.0 with Version 4.0. Those familiar with Version 4.0 administration, especially with 4.0 Advanced Edition, will be pleasantly surprised by all of the new management features in Version 5.0.

There are significant differences between how you would handle administration in both Application Server Versions 4.0 and 5.0. One of the main differences is that the Version 4.0 Advanced Edition (AE) requires a database to hold configuration data while no edition of Version 5.0 requires a database. Version 4.0 AE administration is based on EJBs and all of the Version 4.0 administrative programs are EJB client programs. Version 5.0 does not use EJBs to store configuration data; therefore, none of the Version 4.0 administration programs, such as the Swing console, WSCP, and XMLConfig, are compatible with Version 5.0. Instead, Version 5.0 relies on XML configuration files and industry-standard JMX components to handle management functions.

The Version 4.0 administration program is a single AdminServer process that serves several functions simultaneously. In 4.0, the AdminServer runs on every node, and every instance of the AdminServer is equivalent to any other. In 5.0, the same functions that were combined in the 4.0 AdminServer have been separated into different specialized administrative programs. The node agent process discussed earlier runs on every node and is specialized to perform node-specific administration functions, such as server process monitoring, configuration synchronization, file transfer, and request routing. The single deployment manager process manages the entire cell, coordinating with the node agents for the various nodes in the cell.

Unlike Version 4.0, all administrative functions and programs are applicable to all editions of the product. The same scripting program, wsadmin, that works for the WebSphere Express edition also works for the full Enterprise package, even on the mainframe edition of Version 5.0. The same administrative console program, a J2EE Web application based on JSPs and the Jakarta struts framework, works for all editions of Application Server 5.0.

The table below provides summary comparisons of some of the administrative features between Version 4.0 AE and Version 5.0.

Back to top

Application Server 5.0 administration architecture

In Version 5.0, the architecture for Application Server system management has been redesigned. Every process in Version 5.0 contains an embedded JMX agent, the JMX MBeanServer component. For each process, additional administrative services are built around this central management component.

Each managed component of the run time is exposed as a JMX MBean, which is registered with the MBeanServer. These managed resources are available externally by using JMX connectors to the MBeanServer. Each MBean has a unique identifier called the ObjectName, which is used in scripting and Java APIs. Application Server 5.0 supports two JMX connectors: the RMI/IIOP connector and the SOAP/HTTP(S) connector. Additional connector protocols are planned for future releases. Documentation for each MBean is installed with the product in the web/mbeanDocs directory under the root installation directory. The documentation describes the operations, attributes, and notifications that each MBean provides. Figure 3 shows architectural details of how all of the pieces fit together.

When system security is enabled, all administrative connectors are secure. You must map all administrator userIDs to one of the administrative roles defined below. When an administrative client program, such as the console, scripting, command line, or custom program, attempts to perform an administrative function, the userID of the calling code is obtained and compared to the privileges granted to the role for that particular user. If the user does not have appropriate privileges, then the request will be rejected.

The following four roles separate the administrative functions into layers of privilege:

• Monitor. This role can view configuration and run-time settings, but cannot modify anything.
• Operator. This role can perform run-time operations, but cannot modify the persistent configuration. For example, an operator can start or stop a server but not change the configuration for that server.
• Configurator. This role can modify the persistent configuration for the system, but cannot perform run-time operations on live objects. For example, a configurator can install applications into the system, but cannot start or stop a server.
• Full Administrator. This role can perform all administrative functions.

In the base Application Server package, the administrative client programs attach directly to the server process and send administrative requests to that single process. In a Network Deployment environment, the administrative client programs can attach to any point in the topology (deployment manager, node agent, or managed process). Generally, administrative clients attach to the deployment manager because all servers can be controlled from that process. When a request for an MBean operation is submitted to the deployment manager, it is automatically routed to the server on which the target run-time component is executing.

In addition to operational requests (for example, stopping a server) and configuration requests (for example, changing an attribute), administrative programs in Version 5.0 can register as listeners for distributed event notification from any of the MBeans running in the network. Several MBeans generate an event notification when something significant occurs in their logic (for example, the Server MBean generates notifications when it starts and stops). Administrative clients can register to receive callbacks when these notifications are broadcast.

As described previously, configuration data is stored as a set of files that make up the master configuration repository. In a Base Application Server environment, all documents are stored on the same system as the server. In a Network Deployment environment, the deployment manager maintains the full set of configuration documents for the entire cell, and each node in the cell only gets a subset of the documents that apply specifically to that node. Since each node has the subset of configuration information required for processes defined on that node, you can start and control the servers even if the central deployment manager process is temporarily unavailable. Figure 4 depicts how administrative commands are routed between the processes in the cell, and how different servers read the various parts of the configuration data.

Back to top

Application Server 5.0 administration tool sets

System administration provides a variety of tools for managing WebSphere Application Server. These tools can be categorized into four general tool sets that are available with most editions of the product:

• Administrative Console
• Scripting tool
• Command line tools
• Java programming API

Administrative Console

The administrative console is a graphical interface that provides many features to guide you through deployment and systems administration tasks. It is extremely useful for helping you get started exploring the available management options. Various wizards guide you through the more complicated processes. The administration console program is documented in the Application Server 5.0 InfoCenter. Figure 5 shows the WebSphere Administrative Console home page.

The separation of run-time operations from configuration changes is an important concept in Version 5.0. Run-time requests are delivered to the running server components through JMX operations and take effect immediately. These run-time attribute changes are transient in nature and do not survive a server restart. Configuration changes, which are made in the XML configuration files for the server, are persistent across server restarts. Configuration changes do not take effect immediately; you must restart the server in order for the new values in the XML configuration files to be picked up.

Most run-time attributes have corresponding persistent configuration settings. However, there are considerably more configuration settings stored in the XML files than there are run-time attributes available for modification on live managed objects. Separating the two functions makes the distinction clear when you are changing something that will take effect immediately, but is transient as opposed to when you are making a persistent change. If you want both an immediate run-time change and a persistent configuration change, then you need to perform both operations. Figure 6 shows a server page in the Administrative Console displaying both the server Runtime and Configuration tab views.

The base Application Server version of the Administrative Console provides single server administration capabilities. This Web application runs in the same server that it manages in the base environment. In a Network Deployment environment, the Administrative Console executes in the deployment manager process. This lets the console create server clusters that span multiple nodes and manage any process configured on any node within the cell.

Use the Administrative Console client program to become familiar with the product and all of its capabilities. You can explore all of the various aspects of the environment in a graphical presentation. Once you have learned many of the details of Application Server 5.0 using the graphical console application, you might find that some of the other administrative tools provide faster access for day-to-day activities.

Scripting tool

The Application Server administrative scripting program, wsadmin, is a powerful, non-graphical command interpreter environment that lets you execute administrative operations interactively or in a script file. The wsadmin tool is intended for production environments and unattended operations. The wsadmin tool is documented in the Application Server 5.0 InfoCenter. It is built on top of the Bean Scripting Framework that is shipped with Version 5.0. This lets the program support several languages for scripting Application Server administrative functions. The initial release only supports the Tcl syntax, but additional scripting language support is already underway for future product updates.

The wsadmin scripting tool has three modes of operation:

• Interactive mode. This lets the user enter commands and view the response on a command line prompt. This mode is useful for learning the scripting tool and its capabilities. It is also useful for prototyping command syntax to verify the options before building a larger script.
• Batch mode. This lets the user supply a set of script commands in a file that the tool executes as a program.
• Command mode. This lets the user enter a single command from the regular operating system command window and executes this one command, returning control to the operating system command shell.

The wsadmin tool is most often executed as a client attached to a running server. You can also run it in a "local" execution mode where a running server is not required. In this mode, however, the function is limited to only configuration changes since a server run time is not available to receive operational requests.

Four Application Server administration scripting objects reflect the underlying product architecture:

• AdminControl. Exposes the operational aspects of the system so that you can invoke JMX operations on the live run-time components through the MBean interface.
• AdminConfig. Exposes the configuration for the system so that you can update the XML configuration files.
• AdminApp. Exposes the application deployment options for the system; this is essentially a specialized configuration object for installing and deploying applications.
• Help. Provides dynamic information about the operations, attributes, and notifications available on any JMX MBean in the system.

The wsadmin tool is primarily intended for rapidly assembling small control programs using the available Application Server administrative functions. You can develop more sophisticated administration programs using the Java API for Application Server administration (described below). However, the combination of full scripting language constructs, such as loops and variable evaluation, along with Application Server administration functions provides powerful capabilities.

Examples of wsadmin syntax for performing some common administrative functions:

 
# get the state and version info for a server 
set server [$AdminControl completeObjectName name=server1,type=Server,*] 
$AdminControl getAttribute $server state 
$AdminControl getAttribute $server serverVersion 
 
# get online help for the Server MBeans 
$Help all $server 
 
# perform a thread dump on the JVM 
set jvm [$AdminControl completeObjectName type=JVM,process=server1,*] 
$AdminControl invoke $jvm dumpThreads 
 
# turn on trace in a running server 
set ts [$AdminControl completeObjectName type=TraceService,process=server1,*] 
$AdminControl setAttribute $Ts traceSpecification com.ibm.*=all=enabled 
 
# install an application (myApplication) on server "serv2" 
$AdminApp install c:/MyStuff/myApplication.ear {-server serv2} 
 
# start the application 
set appManager [$AdminControl completeObjectName type=ApplicationManager,*] 
$AdminControl invoke $appManager startApplication myApplication 

Command line tools

Command line tools are simple programs that you run from a command prompt to perform specific tasks. Using the command line tools, you can start and stop application servers, check server status, add or remove nodes, and complete similar tasks. The command line tools provided with Application Server 5.0 are restricted for use on a single local node.

All of the command line tools are Java programs that use the same Application Server 5.0 administration APIs as the console and the wsadmin tool, which are discussed in the next section. The following is a partial list of some of the command line tools available with Application Server 5.0. A complete list of the command line tools is available in the Application Server 5.0 InfoCenter.

Most of the command line tools print a usage syntax statement if you invoke them with the help option (by entering either -? or -help as part of the command). Most command line tools also log their activity under the logs directory for the product. All command line tools require authentication data when product security is enabled.

Java programming API

Application Server 5.0 supports a Java programming interface for developing administrative programs. All of the administrative tools supplied with the product are written according to the API, which is based on the industry standard JMX specification.

Using the administrative programming API, you can:

• Write your own custom administration client to perform specific administration functions. The command line tools available with Application Server 5.0, including the wsadmin tool and the console, are client programs that use the public administration APIs to carry out their tasks. Custom administration client programs can be simple or extremely complex. For example, you could write a client that only lets you start and stop clusters. Or, you could write a specialized administration client program to monitor certain metrics in the server and adjust configuration settings if the metrics exceeded some threshold.
  
  
• Extend the basic Application Server administration system with your own custom MBeans that expose the management interface specifically aligned for your requirements. For example, your application might have its own run-time properties that you can adjust to tune the application while it is executing. Your application can implement a JMX MBean that exposes these attributes and other useful operational requests. Using the Version 5.0 administration programming interfaces, you can add your MBean to the set provided with Application Server, and control your application, along with the rest of the system, using the wsadmin scripting client. You can even write a custom server extension and expose its functionality to the Application Server administration system as a JMX MBean.

The Application Server administration programming API is fully documented in the javadoc, which is provided with every installation (it is located in the web/apidocs directory under Application Server's root installation directory). The Application Server administration API is based on standard JMX interfaces and classes, and the JMX javadoc is also provided with each installation. The com.ibm.websphere.management package contains the public Application Server management interface.

Many helper classes and interface definitions are associated with the Version 5.0 administrative programming APIs. If you plan to create custom administration code, you should familiarize yourself with the public javadoc for the product. Future articles in this series will explore the details of how to use these administration programming APIs, and will provide detailed examples of custom administration programs and system extensions.

Back to top

Application Server 5.0 configuration data

As mentioned previously, Application Server's configuration data is stored in a set of XML documents. While you typically will not need to manually update or view these files, it is still useful to know the structure and content of these documents. Knowing the configuration repository structure will give you a better understanding of the overall system operation. You can modify the configuration files manually; however, unless you know the exact change to make, it is recommended that you use the administrative tools to modify the configuration files because they can validate changes made to the configuration.

Recall that in a Network Deployment environment, master copies of all documents are stored in the cell repository on the deployment manager node. When a change is made to one of these master documents, it is automatically replicated to any of the applicable nodes in the cell. The document on the node is automatically overwritten by the copy from the master repository. For this reason, when updating repository documents in a Network Deployment environment, you should only update documents in the master repository on the deployment manager node. The administration tools always update the master configuration files in a Network Deployment environment.

The repository documents are stored in a directory tree starting at the config directory under the product installation root. At the top of the hierarchy is the cells directory, which contains a subdirectory for each cell. The names of the cell subdirectories match the names of the cells. For example, a cell named mycell has its configuration documents in the directory, cells/mycell. In Application Server 5.0, there is always a single cell.

Each cell subdirectory has the following files and subdirectories:

• The cell.xml file, which provides configuration data for the cell.
• Files such as security.xml, virtualhosts.xml, resources.xml, and variables.xml, which provide configuration data that applies across every node in the cell.
• The clusters subdirectory, which holds a subdirectory for each cluster defined in the cell. The names of the subdirectories under clusters match the names of the clusters. Each cluster subdirectory holds a cluster.xml file, which provides configuration data specifically for that cluster.
• The applications subdirectory, which holds a subdirectory for each application deployed in the cell.
• The nodes subdirectory, which holds a subdirectory for each node in the cell. The names of the subdirectories under nodes match the names of the nodes.

Each node subdirectory contains files such as variables.xml and resources.xml, which provide configuration data that applies across the node. Recall that these files have the same name as those in the containing cell's directory. The configurations specified in these node-level documents override the configurations specified in cell-level documents that have the same name. For example, if a particular variable is in both cell- and node-level variables.xml files, all servers on the node use the variable definition in the node-level document and ignore the definition in the cell-level document.

Each node subdirectory also contains a serverindex.xml file that stores the definitions of all ports used by servers on that node. Keeping this information in one document makes it easier to find port conflicts between servers on a node.

Each node directory contains a subdirectory for each server defined on the node. The names of the subdirectories match the names of the servers. This directory always contains a server.xml file, which provides configuration data specific to that server. There might also be security.xml, resources.xml and variables.xml files, which provide configuration data that applies only to the server and overrides the configurations specified in the containing cell and node documents that have the same name.

The names of the applications subdirectories match the names of the deployed applications. The original EAR file for the application is stored in each application subdirectory. Also, under the application subdirectory is a deployments directory. You can deploy one application multiple times with different bindings for each deployment.

Each deployment subdirectory contains a deployment.xml file that contains configuration data about the application deployment. Each deployment subdirectory also contains a META-INF subdirectory that contains a J2EE application deployment descriptor file along with IBM deployment extensions and bindings files. Deployed application directories also have subdirectories for all WAR files and entity bean JAR files in the application. Only the metadata for the application is stored in the deployment subdirectories. The binary code for the application is stored in the location that the administrator specified when installing the application.

The following is an example file structure. The directories are highlighted in blue and files are highlighted in green:

 
cells/
  mycell/
     cell.xml resources.xml virtualhosts.xml variables.xml security.xml
     nodes/
        nodeX/
           node.xml variables.xml resources.xml serverindex.xml
           servers/
              serverA/  
                 server.xml variables.xml resources.xml
              nodeagent/
                 server.xml
        nodeY/
           node.xml variables.xml resources.xml serverindex.xml
           servers/
              nodeagent/
                 server.xml
     applications/
        sampleApp1.ear/
           deployments/
              sampleApp1/
                 deployment.xml
                 META-INF/
                    application.xml ibm-application-ext.xml
        myapp2.ear/
           deployments/
              myapp2/
                 deployment.xml
                 META-INF/
                    application.xml ibm-application-ext.xml ibm-application-bnd.xml

The Application Server 5.0 InfoCenter provides a table describing each configuration document in the repository.

Back to top

Conclusion

Part 1 gives you a good sense of what the WebSphere Application Server 5.0 system administration has to offer. Future articles in this series will explore Version 5.0 management and administration issues in-depth. In particular, future articles will cover:

• How to write your own administration programs using the Java API for administration
• How to extend the Application Server management system and create your own MBeans
• How to receive and send event notifications
• The ins and outs of Application Server configuration
• Application Server application management, custom configuration, and deployment

WebSphere Application Server is an innovative product with many capabilities to explore and exploit. This series will help you become more familiar with Application Server 5.0 administration issues. Stay tuned for much more information about how to do just that!

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• WebSphere Application Server structure
• Comparison of the administration implementation in Versions 4.0 and 5.0
• Application Server 5.0 administration architecture
• Application Server 5.0 administration tool sets
• Application Server 5.0 configuration data
• Conclusion
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers