To administer WAS, you have to connect to the Administration Console on the node using a Web browser. The default URL will be http://hostname:9090/admin/. (Use the app server hostname directly; do not go via the Web server.)
You’ll be prompted to enter your user name. When WebSphere Security isn’t enabled, this user name has no special meaning and a password isn’t required. You can use any name, but pick something unique to you so different console users can be identified.
The normal admin console display contains four frames: a top banner; a left-hand-side menu of options each of which be expanded; a main frame showing the current task; and a bottom bar showing a status summary.
The left-hand expanding menu lists the various aspects of WebSphere that can be configured. Configuration dialogues appear in the main frame. After changing any values, remember to select Apply or OK before proceeding.
After making a set of configuration changes to WAS using the console, you must save these changes to the repository for them to have any effect. A warning dialogue appears in the main frame to remind you of this; it contains a link to the save screen. Unsaved changes are lost when you leave the console. WAS application servers usually have to be restarted to pick up changes.
The administration console can only be used to control the default server1 application server in a base installation, although it can configure any server. If you create other application server instances, you have to start and stop them manually using the command scripts.
Information from the DevelopersBefore proceeding, you must gather some information about your application(s) from the developers:
- Database(s) required: schema; purpose; initial contents; etc.
- Any JNDI resource names used by the application to access databases or other external data sources, e.g. jdbc/MyAppDataSource.
- Any additional external resources required by the application including remote Web Services, mainframe access, or other remote data servers. Ensure that your WAS hosts have access to these resources.
- Any aspect of the application configuration that may differ in a production environment compared to a development or test environment. (Note that developers often fail to recognize such issues since they lie outside their experience.) Absolute URLs and other information that may differ between environments shouldn’t be hardcoded into the application; put them in a database, a Java properties file, a WebSphere variable, or URL Provider.
PreparationCreate and initialize any databases needed for the application. Configure any database client software on your application server so it can connect to the database server if it’s remote.
Although it’s possible to install your application in the default server1 application server, we’re going to create a separate server to enforce isolation from the administration console application.
It’s helpful to develop a consistent naming strategy for the following elements in advance:
- J2C authentication aliases for JDBC resources (e.g.. MyDatabaseAuth)
- Data sources (e.g., MyDatabaseDataSource)
- Application servers (e.g. MyAppServer)
Names should be single or combined words with no whitespaces, using underscores or upper case letters as word delimiters. Administration console configuration:
- Using the left-hand bar menu, go to Environment -> Manage WebSphere Variables. Make sure that the current scope is at node level in the dialogue box at the top of the main frame.
- If you are using a database with a recognised JDBC driver, set the path to the driver in the relevant variable. For example, if you are using DB2 V7, set DB2_JDBC_DRIVER_PATH to the path to your DB2 Java directory (e.g. /opt/IBMdb2/V7.1/java12).
- Examine the other defined variables, noting which ones have default values. Set any empty variables that appear relevant to your installation. Note that variable listings can spread across multiple pages as indicated at the top of the frame.
- Remember to click Apply after entering a value.
- Go to Environment -> Virtual Hosts. Select default_host, then Host Aliases. Add the aliases in Table 1. (Adding port 443 lets SSL/HTTPS be used to access the application.)
- JDBC resources usually require authentication details for access. These are configured under Security -> JAAS Configuration -> J2C Authentication Data. For each set of authentication values, you have to supply an alias (name), user ID, password, and optionally a description.
- For example, for the DB2 CLI legacy client driver, the user name would be the DB2 client instance user, such as db2inst1.
- To create the actual JDBC resources, go to Resources -> JDBC Providers. WebSphere knows about many common driver types and provides templates for them, such as ‘DB2 Legacy CLI-based Type 2 JDBC Driver’ for DB2 V7. Otherwise, you may have to create a driver entry from scratch; consult the driver documentation for the required class path, environment, libraries, and any other settings.
- For each configured driver, create the necessary Data Sources. (Don’t create version 4-compatible data sources unless you’ll be running a legacy app that predates the J2EE 1.3 standard.)
- Each data source has to have a name and a JNDI name. The JNDI name should match the name used by the application (e.g., jdbc/UserDataSource). Set the Alias fields to the appropriate access alias defined under the J2C Authentication Data. Mapping-Configuration Alias should usually be left as DefaultPrincipalMapping.
- Many data sources need certain Custom Properties. For example, a DB2 V7 CLI-based client data source requires the databaseName defining.
- After saving the configuration, return to the data source, select the checkbox next to it, and click Test Connection. Note: Testing the connection may fail if the local database client isn’t configured or all of the required environment variables weren’t defined when WAS was started.
- Go to Servers -> Application Servers. Create a new application server and give it a unique name. Use the default/server1 template.
- Select the new application server. Go to Web Container, then HTTP Transport. Confirm that there are entries for *:9081 and *:9444 only. If the entries differ, edit and correct them. Make sure there’s no conflict with an existing application server or other program.
- There are several items under Process Definition that you may want to alter. Under Logging & Tracing -> JVM Logs, you can increase the number of Backup files (old logs) retained and change the log rotation schedule. Under Java Virtual Machine, you can set the class path and heap sizes for the application server JVM (Java Virtual Machine). The class path may need setting if you need to use other libraries and properties files that are local to the server (i.e., not installed with the application). The JVM Working Directory is set to the WebSphere install directory by default; this is an extremely poor choice and should be changed immediately. Use either a new dedicated directory or the WebSphere ${USER_INSTALL_ROOT}/temp/ subdirectory.
After making all your changes, remember to Save the configuration to the repository.
Deploying an ApplicationComplete WAS applications are normally supplied as a single Enterprise Application Repository (EAR) file. EAR files are actually in the standard ZIP archive format and can be unpacked manually using unzip(1) if necessary. Normally, the administration console unpacks the files in the correct location during deployment.
Before proceeding, copy the EAR file to the application server host.
- Ideally, stop the relevant application server before deploying a new version of an existing application. (It can be left running, but you may see some odd behaviour when the updated configuration is saved.) WAS also provides a facility to update a running application; consult the Infocenter for details.
- In the administration console, go to Applications -> Install New Application.
- Select Server path and enter the path to the EAR file on the application server. Click Next.
- If the application’s been built correctly to match the details outlined by the developers (e.g., JNDI names, etc.), you should be able to select Generate default bindings and have most of the settings configured correctly.
- The rest of the installation steps are described in section 8.6.6 of the System Configuration Redbook and in the Infocenter. The most likely places where intervention will be required are:
- Provide options to do the installation: Make sure the Deploy EJBs option is selected. Enter a unique Application Name.
- Map virtual hosts for Web modules: Select default_host for all modules.
- Map modules to application servers: Select your dedicated application server for all modules (use the Module checkbox), rather than the default server1.
- Provide options to do the EJB Deploy: Select the correct database type and schema.
- Otherwise, the defaults can be accepted. You will have an opportunity to verify your selections on the final Summary page.
- Save the updated configuration to the repository. This activates the new application code.
- Restart the application server.
Don’t install multiple copies of the same application on the same application server, since naming conflicts are likely to occur.
Automated EAR InstallationBecause installing an application using the console is time-consuming and error-prone, it’s better to develop a JACL script instead. This reduces the number of steps involved to a single command and ensures that the procedure is always executed consistently.
The following example shows you how to install an application contained in an EAR file called myapp.ear on an application server called MyAppServer. The application uses DB2 V7.2 for the EJB data sources.
puts “Installing MyApp on MyAppServer ...”
$AdminApp install myapp.ear MyAppServer [list -appname MyApp
-usedefaultbindings -defaultbinding.virtual.host default_host
-distributeApp -deployejb -deployejb.dbtype DB2UDB_V72
-createMBeansForResources]
puts “Saving configuration ...”
$AdminConfig save
If this script is put into a file called ear_install.jacl and the EAR file is in the current directory, it can be run using:
# wsadmin.sh -f /path/to/ear_install.jacl
Generating the Plug-in ConfigurationAfter installing a new or modified application, you have to update the HTTP plug-in configuration file. In the administration console, go to Environment -> Update Web Server Plugin. Click OK.
If the Web server is installed on the same host as the application server, this is usually all that’s needed. The plug-in configuration file path will be set correctly in the Web server configuration.
However, if the Web server is separate, then the plug-in configuration file has to be copied to it (and to any other identical Web servers configured for redundancy or load balancing).
The file is in /opt/WebSphere/AppServer/config/cells/plugin-cfg.xml. For simplicity, it’s best to use the same path on the Web server.
It’s common practice to customize the plug-in configuration to suit local needs. For example, any mention of the adminconsole application or other sample applications should be removed from production systems. There are also some parameters, such as connection settings, that can only be edited manually. The file is XML-based and care should be taken when editing to make sure that its structure is preserved and the syntax remains correct. Be especially careful when copying and pasting lines from another file that spurious line breaks aren’t introduced.
If you’ve edited the plug-in configuration, you may find it easier to compare your current file with a newly regenerated one and make any changes to it manually to preserve your own edits.
The plug-in configuration should be regenerated and/or edited when:
- a new application is installed;
- the structure of an existing application changes (i.e., new Web application module or URI path);
- the network details of the cell are changed (new addresses or port numbers);
- an application server is added to or removed from a distributed cell.
Starting the ApplicationIt should now be sufficient to start the application server in which the application was installed:
# startServer.sh MyAppServer
Tail the SystemOut.log file for the server under the WAS logs/ directory and watch for any errors. If the application writes its own log file examine that too. Typical problems are:
- Libraries not found (not installed or not in the JVM class path) resulting in ClassNotFound exceptions.
- Data sources fail to bind correctly due to wrong configuration or environment leading to further application failures.
- Database connections fail due to incorrect database client or server configuration. Such errors may have secondary effects if the application has to retrieve data during initialization.
- Insufficient JVM heap space configured for application requirements (possibly a sign of a poorly written application!).
If all goes well, you should be able to enter the application Web URL into a browser and get a page back.
Debugging a ProblemFirst, check the fundamentals:
- Can your browser connect to the Web server? (View Web server logs.)
- Is WebSphere running?
- Are all the backend services up? (Database, etc.)
- •Has the updated plug-in configuration file been copied to the Web server?
Check the WebSphere server logs and any application logs for obvious errors or failures. For example, the Web server or application server TCP ports may not be included in the virtual host definition (commonly indicated by the error message ‘Virtual Host/WebGroup Not Found’).
If there’s no evidence that the application is getting requests, verify the network connectivity between systems using tools like telnet(1) (with a port number) and curl(1). That last utility is especially useful for debugging Web apps, since it lets you formulate arbitrary URL requests and view the full server responses, including cookies. You can use it to send HTTP requests to the Web server or from the Web server to the application server. For example:
$ curl -vi http://appserver:9081/MyAppURL/file.jsp
If locally made requests on the application server host work, it may indicate a problem on the Web server (perhaps with the plug-in configuration) or between the Web server and the application server.
Remember that requests to the Web server via HTTPS are forwarded to the application server via HTTPS on the alternate port (e.g. 9444).
lsof(8)is a useful utility for discovering applications that have a connection or file descriptor leak. Used against the application server JVM process, it will show all the open files and connections to JDBC resources, etc.
If the application appears to be malfunctioning, developers may find it useful to view a stack trace from the JVM running the application. The following command will write a trace to to the server’s native_stdout.log file (without stopping the process):
# kill -QUIT `cat /opt/WebSphere/AppServer/
logs/MyAppServer/MyAppServer.pid`
WAS contains a number of utilities to assist with application debugging, including the Log Analyzer and Trace facility. You can also enable performance monitoring (PMI) in the application server and use the supplied Tivoli Performance Viewer application (which can be installed separately on a remote host such as a PC) to view the data. Consult the Infocenter for more details. IBM also has a number of downloadable utilities available, such as ThreadAnalyzer.
Part 3 of this article covering monitoring, WAS scripting, and security will appear in the July 2005 issue of WebSphere Journal.
ResourcesReferences- Roland Barcia, Bill Hines, Tom Alcott, and Keys Botzum. IBM WebSphere Deployment and Advanced Configuration. IBM Press/Prentice Hall PTR, 2004.
- Lavena Chan, Roger Cundiff, Shaun Lauzon, Christopher Mitchell, and Leigh Williamson. IBM WebSphere System Administation. IBM Press/Prentice Hall PTR, 2004.
- Kovari et al. IBM WebSphere V5.0 Security. Technical report, IBM, 2002. sg246573.
- Roehm et al. IBM WebSphere V5.1 Performance, Scalability, and High Availability. Technical report, IBM, 2004. sg246198.
- Sadtler et al. IBM WebSphere Application Server V5.1 System Management and Configuration. Technical report, IBM, 2004. sg246195.
- Sadtler et al. Installing WebSphere Application Server Version 5.1 on Red Hat Enterprise Linux Advanced Server Version 3.0. Technical report, IBM
Subscribe to WebSphere Journal Email News Alerts
Subscribe via RSS
