InfoCenter Home >
8: Problem determination
8: Problem determination
Whether you are a beginner or experienced user, the following problem determination
section leads you to resources and techniques to help you identify
and respond to problems.
Navigate through the problem
Resources for identifying problems
WebSphere Application Server topology
Bookmark the Problem Determination Quick
Reference table for a quick reference to the following
problem determination information and techniques.
The table is a collection of all the resources
included in
solving your problems.
The following list provides symptoms to identify problems and navigate to recovery. Choose
the symptom that best fits your problem - ask yourself What kind of
problem is it? and What component is causing the problem?
- Installation of WebSphere Application Server, or its components, was not successful
- The WebSphere administrative server will not start
- An application server will not start
- Cannot access any servlet, JSP file or HTML file from a browser
- Cannot access a specific servlet, JSP file or HTML file from a browser
- A servlet or JSP file displays an error or Java exception instead of the correct output
- JSP source code file shown by the Web server
- Cannot start the administrative console
- A Java client application will not start
- A Java client application cannot make an enterprise bean call
- An error occurs generating deployed code for an enterprise bean
- An error occurs when installing an enterprise application
- My servlet, JSP file or session enterprise bean cannot connect to
a third party software package
- Secured Socket Layer (SSL) encrypted requests ("https://...") do not
work
- Cannot access the administrative console after enabling security
- Authorized users cannot access the servlet, JSP file or HTML file when security is enabled
- Unauthorized users can access the servlet, JSP file or HTML file security is enabled
- Users have access problems even after entering valid log-in information
- Form-based login is not working
- Errors are displayed after configuring
general security
- When mapping users to security
roles, the lists of users and groups are empty
- HTTP sessions are not created,
or are dropped between Web requests in a session
- Cloned application server is never reached
- Cannot start the cloned application server, or load or start the cloned servlet or enterprise bean
Which component is causing the problem?
Choose the product components causing the problem:
You can perform problem determination at different levels within your system.
Several resources are available for identifying problems:
It is important to understand the topology of the system and how your application fits into this
topology. The following information explains how the components work together, and disusses the processes necessary
for proper function of WebSphere Application Server.
The following is the process and components involved in the WebSphere Application Server "plumbing." Each
corresponds to the topology picture below:
- The browser sends a URL request to the HTTP server.
- The WebSphere Application Server plug-in examines the URL and based on comparisons to the
product root/config/plugin-cgf.xml file, dispatches it to
the proper servlet (a user-defined servlet or one of the servlets provided).
- If the servlet class is not loaded, the dynamic class loader installs the servlet.
- Servlet init(), then doGet() or doPost.
- Methods are called to do application-specific work.
- When enterprise beans are needed, a create is done on a home interface. The home interface is
received during initialization from a JNDI lookup.
- The Web container instantiated the enterprise bean. If it is an entity bean, then data source
and JDBC drivers are used to find out what database URL to use. There is a connection from the
connection pool.
- Methods are called on the enterprise bean remote interface and executed by the enterprise bean.
- SQL is executed. Results are retrieved.
- Data beans are created and passed to JSP files.
- The JSP file generates the HTML that is sent back through the plug-in to the browser.
For WebSphere Application Server Versions 4.0 and above, use of a Web console is not supported as indicated in the image. You use a Java remote console in Versions 4.0 and above.
See the InfoCenter article 1.3: Prerequisites for information regarding prerequisite
information.
The administrative database contains configuration information for the
administrative server or servers. An application database contains customer application data.
database you choose.
During installation, the Web server that will interact with the WebSphere Application Server is identified. Depending on which Web server is identified, a different plug-in code is installed. The plug-in communicates via HTTP to the internal HTTP server, which then routes the requests to the Web container.
The application server also contains two subcomponents, the Web container and EJB container.
The Web container interfaces with the plug-in code to service HTTP requests from a Web browser.
The EJB container interfaces with the Web container or EJB clients to support access to enterprise beans.
Both the Web container or EJB container can access the customer application data.
Protocols- RMI/IIOP
This interface is provided by the CORBA component of the IBM-supplied Java 2 SDK
which is installed with WebSphere Application Server. This interface allows an application to transparently access Java objects
that are located either locally or remotely.
This interface is also used for interactions between the administrative server,
the administrative client and the application server.
- SSL
SSL encryption is used internally when security is enabled. Web servers can also be configured to use SSL
for secure communication with browsers. In addition, SSL can be used for secure communication with
browsers like https-type URLs.
- HTTP
This interface is the externally defined interface used by Web browsers. The Web server can service
the HTTP request or pass the request to the application server.
- JDBC
This interface is defined by Java and allows Java programs to access data within the supported databases.
- SOAP
The SOAP protocol is a lightweight protocol that supports the exchanged of
information in a decentralized, distributed environment. SOAP is an XML-based product consisting
of three parts:
- An envelope defining a framework for describing what is contained in a message and how it is processed.
- A set of encoding rules for expressing instances of application-defined data types.
- A convention for representing remote procedure calls and responses.
- SOAP is the key foundation for implementing Web services. SOAP is transported via HTTP.
Installation of WebSphere Application Server, or its components, was not successful
Does the installation process
Installation hangs
Check the wssetup.log.
Does it show any errors? Scan the entire installation log for "error."
"Total Errors: 0" at the end of the file indicates that the final step was successful, but the intermediate
steps might not have completed.
Look for errors indicating that the installation program was
unable to read from a file, write or overwrite a file. File
permission problems could have occurred.
If wssetup.log does not display errors, or ends in mid-process
with no errors, look at the command session from which the installation
was launched. In a Windows NT environment, this means executing setup.exe
from a DOS window instead of clicking it and clicking it again from within Windows NT Explorer.
When the installation hangs, look at the window. Does it display an operating
system error or Java exception?
If it does not display an error, or the error message
is not helpful for diagnosing the problem, record any messages displayed,
and obtain help from IBM.
Installation displays message dialog
What kind of problem does the installation program message dialog
indicate?
After installation, Informix IDS_2000 has a load libc_r.a problem on an AIX 4.3.3 platform even if the software installed without problems. If you run
Informix commands such as oninit -ivy, onstat -l or onmode, you receive error messages. To avoid error messages, do one of the following:
- Load the AIX driver using the System Management Interface Tool (SMIT).
- At the AIX command prompt, enter the following command to ensure that asynchronous IO is available after the next reboot: mkdev -1 aio0 ; chdev -P -l
aio0 -a autoconfig=available.
Installation -insufficient disk space
Does the system have the amount of disk space needed (as indicated by the dialog box)?
Windows NT/2000:
- Open Windows NT/2000 Explorer.
- Right-click the drive where you are installing WebSphere Application Server.
- Select Properties to view the amount of space available.
If the capacity is less than what is required, you cannot install
WebSphere Application Server on this drive. If the capacity is sufficient, but the available
space is not, delete enough files to provide the amount of space needed.
UNIX
- Use the df -k command to view the available space
in your WebSphere Application Server file system. If necessary, contact the system administrator to increase
the space.
If you have sufficient disk space and are receiving an insufficient space message, obtain help from
IBM.
Insufficient
software prerequisite level
Look for requirements for supporting software
in the InfoCenter article 1.3: Prerequisites.
If you find that you have the appropriate
prerequisites, obtain help from IBM.
Installation
finishes, but components are missing
If installation is complete, but the
product directories have not been created,
files are missing, or service panel entries
or Start menu icons
have not been added, check the file wssetup.log.
- Look for errors indicating that the installation
program was unable
to read from a file, write to a file, or
overwrite a file. File
permission problems could have occurred.
If wssetup.log does not display errors, or
ends in mid-process
with no errors, look at the command session
from which the installation
was launched (in a Windows NT environment,
this means executing setup.exe
from a DOS window instead of double-clicking
it from within Windows NT Explorer).
When the installation hangs, look at the
window -- does
it display an operating system error or Java
exception?
If it does not display an error, or the error
message
is not helpful for diagnosing the problem,
record any messages displayed,
and obtain help from IBM.
Installation -
File permission problem
Installation will be unsuccessful if:
- The user ID under which the installation
is running does not have
authority to read the installation files
or to write to (or overwrite files
in) the target installation directory.
- WebSphere Application Server and related
processes have not been stopped before
performing installation. Before installing
WebSphere Application Server, stop the related
processes. Here is how to stop the related processes:
- Unix
Stop all of the related processes identified
by running the
command ps -ef | grep java
- Windows NT/2000
Use the Task Manager to stop
all of the processes named java, jre or jrew
- Web servers and Web administrative servers
should also be
stopped
- Windows NT/2000
Stop the Web server and Web administrative
server in the
services panel
- UNIX
IHS can be stopped using the apachectl stop command.
Other Web servers come with similar start
and stop commands.
The
WebSphere administrative server will not
start
If the WebSphere Administrative server has
never started,
there might have been a problem with the
installation. If any of the
following conditions apply, check for installation
problems:
- The wssetup.log
displays errors
- The product root
directory has not been created
- The WebSphere Application Server Services panel entry
or WebSphere Application Server Start menu items are missing (Windows NT/2000)
Was the Nanny
process unsuccessful in starting the administrative server? (UNIX)
If the installation is complete, the following
are possible reasons why the
administrative server failed:
- The user ID under which WebSphere Application
Server is being started (specified
at installation time) lacks sufficient authority.
- Windows
The user ID should have administrative-level
authority.
If the serving machine is on a Windows NT
domain, the user ID should be defined
(as an administrative ID) both on the local
system and on the domain.
- UNIX
The user ID should have root-level authority.
If WebSphere Application Server is running as
a non-root ID, be
sure to follow the appropriate setup steps.
- During installation, the database specified
for WebSphere Application Server to use
as its repository has not been created. Review
the InfoCenter article
2: Installation, and select the link for your platform
and database.
- The repository has not had its database manager
started.
If you do not know how to start the database,
review the InfoCenter article
2: Installation, and select the link for your platform
and database, or contact
the database administrator.
- The user ID and password specified at installation for access to WebSphere Application Server's
database are incorrect.
The values for these fields can be found in product root.They are encrypted, but can be temporarily overtyped with new values (they will be overwritten with encrypted values when WebSphere Application Server starts successfully).
- An unsupported JDBC server configuration
has been specified in the admin.config file. This is the
case if the following error appears in the
tracefile:
F SMTL0026E: Failure to create a data source:
COM.ibm.db2.jdbc.DB2Exception: [IBM][JDBC
Driver] CLI0621E
Unsupported JDBC Server configuration
One known cause of this problem is having
a repository database type of DB2, and specifying
the
com.ibm.ejs.sm.adminServer.dbserverName and
com.ibm.ejs.sm.adminServer.dbportNumber properties
in the
admin.config file. In other words, using the "net" instead
of "app" driver is not supported for DB2. The supported method of accessing a remote
DB2 database as the WebSphere repository
is to use the DB2 catalog
utility to create a local alias for the remote
database. The dbserverName and adminServer
properties in the
admin.config file must be left blank if the database
type is DB2.
Use jdbctest to check the availability of the WebSphere
Application Server
repository database.
The jdbctest tool is available for download.
Follow the instructions for downloading and
installing the tool. When running the tool,
use the same user ID and
password to connect to your database as is
specified in the admin.config
file. Running jdbctest this way will indicate
whether WebSphere Application Server can
connect to its repository.
If these steps do not reveal problems, the
next step
is to check the file <product root>/logs/tracefile
for errors. If there is no tracefile file,
or it is empty, try to
diagnose the problem by launching the administrative
server from the command line
by executing adminservice.exe (Windows NT/2000) or startupServer.sh (UNIX) and
look for errors displayed in the command
window.
In general, if the tracefile or command window
does not display
errors, and the message open for e-business is displayed, WebSphere Application Server
is started
and running.
If open for e-business does not display, the tracefile or command
window will display errors
indicating repository database file permission
or authority problems. If there are
problems with the repository, review the
steps for installation
for your platform and database types. If WebSphere Application Server was able
to
create the file <product root>/logs/tracefile,
try running the Log Analyzer for any warnings
or errors that explain the problem.
If the administrative server does not start
(no "open for e-business"), and tracefile, command
window and Log Analyzer
display no errors, or the errors are not
helpful, obtain
help from IBM.
Nanny process
unsuccessful
On UNIX systems, a separate process called
"Nanny"
launches the administrative server and attempts
to launch it again if it fails.
There is rarely a problem with the Nanny
process, but the Nanny.trace
file should be checked. If the file displays
that the Nanny attempted
to start the administrative server multiple
times, this means that the Nanny process
is healthy,
but that the administrative
server cannot start. Therefore, proceed with diagnosing the
administrative server
problem.
If an error like
E Administrative server creation Error creating
new process. 001:
Not owner
is displayed, it might indicate that the
correct procedure
for running WebSphere Application Server as a
non-root user on
UNIX platforms has not been followed.
Here's where to look to verify security settings:
- Administrative console Security Center
- Global settings (authentication mechanism,
enabled versus disabled)
- Role-to-user bindings
- Enterprise bean "run-as" mappings
- Application Assembly Tool (AAT)
- Web application security roles (in Web module
"security roles" properties
within enterprise application)
- Enterprise bean security roles (enterprise
bean module "security roles" properties within
enterprise application)
- Enterprise bean role references, if any (enterprise
bean module "security roles" properties within
the
enterprise application)
- Enterprise bean method permissions (enterprise
bean module "security roles" properties within
enterprise application)
- Servlet security roles (Web module "security
roles" properties within enterprise application)
- Servlet role references, if any (Web module
"security roles" properties
within enterprise application)
- Servlet security constraints (Web module
"security constraints" properties
within enterprise application)
An application server will not start
There are two main reasons an application
server fails to
start.
- A subcomponent of the application
server, like an enterprise application or
enterprise bean will not load or start,
because it is configured improperly or depends
on a file, database or other
object which is missing or corrupted. This
is indicated by one or
more of the following symptoms:
- Dialog boxes that pop up while the administrative
server is attempting
to start, with messages like, Command <server name>.start Sub-command
error. Click Details in the dialog box displays
a Java exception indicating a problem with
a particular Web application
or enterprise bean, like a missing EAR file.
- Error messages signified by a red triangle
in the bottom pane of the administrative
console with text like Command <server name>.start Sub-command
error, following the normal starting application server message.
These messages will be followed by a Command <server name>.start Sub-command
error message. Selecting an error message and
then clicking
Details displays a Java exception indicating a problem
with a particular
Web application, like a missing EAR file.
- Messages in the tracefile like ADSM0104W: Failed to initialize
a server: <server name>, followed by Java exceptions indicating
problems
with specific components, like com.ibm.ejs.sm.exception.OpException:
file:product root/installedApps/Samples.ear does not
exist. These exceptions will be followed by a
message like, ActiveEJBServ
W ADSM0104W: Failed to initialize a server.
- The application server
is configured improperly so that it cannot start, for example, because
an
invalid Java option has been specified in
its startup command.
If there are no errors in the administrative
console or tracefile indicating the cause
of the problem, check to see if the
application server's standard output or error
file have been created.
If so, check them for clues about why the
application server did not start.
Try running the Log Analyzer
for any warnings or errors that explain the
problem.
If you cannot find any error messages, or
the error messages
are not helpful in diagnosing the problem,
gather the errors
and obtain help from IBM.
A subcomponent of the application
server like an enterprise application or
enterprise bean will not load or start
The following are reasons why a subcomponent
fails to load:
- The EAR file which is installed in an enterprise
application
is missing. This is indicated by an error
in the administrative console and
tracefile like com.ibm.ejs.sm.exception.OpException: file:product_installation_root/installedApps/Samples.ear does not exist. This message
corresponds to an existing enterprise application
found under the enterprise
applications folder in the administrative
console. If this happens, copy the
existing deployed EAR file to the indicated
directory. If no deployed
EAR file exists, or if you don't know if
the EAR file is deployed
or deployable, refer to installing
enterprise applications.
- The database upon which a persistent (CMP
or BMP) enterprise bean depends
does not exist, or the application server
does not have sufficient database authority
to access it. This kind of problem is indicated
in the application
server's standard output file by messages
beginning with Error creating CMP persister using data source... or Error
starting CMP bean. These messages indicate both the name of
the
enterprise bean and and data source upon
which it is based. When this happens,
click the installed EJB modules administrative console to examine the properties
of enterprise beans under the application
server. Click on the bean's General and CMP
data source tabs to verify the name of the enterprise
beans data source and database
user ID and password, and correct if necessary.
If there are no errors in the administrative
console
or tracefile that indicate the cause
of the problem, check if the application
server's standard output or error file have been created. If
so, check them for clues about why the application
server did not start.
You should also try running the Log Analyzer
for any warnings or errors that explain the
problem.
If there are other errors relating to starting
subcomponents
of an application server, but they are not
helpful or self-explanatory,
obtain
help from IBM.
The application server
is configured improperly
An application server can be configured improperly
in a way that will prevent it from starting.
Here are the ways:
- There is an invalid Java command-line argument. This can result in a
Critical Error dialog box appearing when attempting to
start an application
server, with a detailed error of com.ibm.ejs.sm.exception.StaleActiveObjectInvocationException.
Arguments to the Java command for an application server can be
viewed
by selecting the affected application server
in the administrative console, selecting
the JVM settings tab of its properties and then choosing
Advanced
JVM settings, and viewing the command line arguments field.
The offending argument will appear in the
application
server's standard error file; search on "Unrecognized option:". Correct
this field if necessary, apply the change,
and then stop and restart the
application server.
- There is an invalid trace specification argument.
From the application
server's perspective, this is also an invalid
command-line argument.
See tracing WebSphere Application Server components for
how to enable component tracing and for the
correct syntax.
Cannot access any servlet,
JSP file, or HTML file from a browser
If you are unable to access any Web resource
from a browser,
these are the possible causes:
- There is a problem with the Web server. This
is usually easy to detect. If you cannot
see the welcome page of
the HTTP server (entering a URL of "http://<server
name>"), this is
the case.
- The physical Web server is down or not available.
Can you see that the machine is running,
or run ping <hostname>
from the machine on which your browser is
running, to ensure that it is
available?
If the machine is started and running, but
you cannot ping
the machine, there might be network configuration
or firewall issues that prevent the browsing
machine from connecting to the Web server.
Contact the network administrator or system
administrator.
- The Web server and WebSphere Application
Server are running on separate machines,
but cannot communicate with each other.
- The Web server used to serve WebSphere Application
Server-bound requests has not been started.
On Windows NT/2000, look in Control Panel > Services to see if
the service has been started. On UNIX, look
for Web serving processes
by issuing the command ps -ef | grep | http. There should be one or
more processes displayed as output.
- If the Web server is running, and the machine
can be pinged, but you cannot see the welcome
page from a browser,
or if you cannot get the Web server to start,
contact the vendor of the
Web server for help. If the Web server is
IBM HTTP Server, obtain help from IBM.
- The plug-in has not been properly
installed or configured, causing the Web server communicating
improperly with WebSphere Application Server.
This is likely if the browser displays a
message like The page cannot be found or The requested URL /<app
context name>/<servlet or JSP file name>
was not found on this server.
- The application server in which the servlet
has been installed
was not started, or cannot start.
This can be the case if you are seeing a
message like Internal Server
Error - The server encountered an internal
error or misconfiguration and
was unable to complete your request in the browser. Check the administrative
console and verify that the resource's application
server state is indicated by
a green "+" next to it under nodes > <node name> > <Application Servers> > <app
server name>.
- The enterprise application, Web
module, or Web resource cannot be loaded for service by WebSphere Application Server.
This is indicated by an error in the browser
like Error 500: Failed
to load target servlet [<servlet name>]
, and an error in the WebSphere Application
Server
console like Servlet Error (Root + 1)-[<servlet name>]:
Failed to
load servlet: javax.servlet.ServletException:
Servlet [<servlet name>]:
Could not find required servlet class - <classname>.class.
If none of these conditions apply, examine
the following files for clues:
- The Web server error log (logs/error.log
in the Apache
or IHS directory structure)
- The plug-in log file (name and location specified
in the file
product root/config/plugin-cfg.xml, defaults to native.log)
Also, try accessing your resource
directly from WebSphere Application Server's
built-in HTTP server, bypassing the production
Web server. If this is successful, the problem
is with
the Web server or the Web server's WebSphere Application Server
plug-in.
If you cannot view the resource directly
from WebSphere's
HTTP server, there is a problem loading or serving
the Web resource.
The plug-in has not been
properly installed or configured
This could be the case if any of the following
are true:
- There were error dialog boxes during the
installation of
the Web server plug-in
- Errors indicating plug-in-related installation
problems in
wssetup.log
- The Web server's own plug-in configuration
file (httpd.conf
for Apache or IHS, obj.conf for iPlanet or
Netscape) displays no modifications
after the installation.
- There is no plugin-cfg.xml file in the product root/config directory of the Web server machine
- The Web server's own error log, like Apache's
/logs/error.log),
displays the Web server accessing its own
directory structure to
find resources, instead of forwarding the
request to WebSphere Application Server (for
example, "File
does not exist: f:/ibm http server/htdocs/servlet/snoop")
If this is true, repeat the
procedure for installing the plug-in. If
the Web server is remote
(not on the same machine as WebSphere Application
Server itself) make sure you are installing
the plug-in on the Web server machine, and
then copy the plugin-cfg.xml file
from the WebSphere Application Server server
machine to the Web server machine.
If the plug-in is properly installed, these
are the next steps:
If these steps do not yield results, gather
the HTTP server's
error.log, the plug-in log file (if any),
and the plugin-cfg.xml file, and
obtain
help from IBM.
When a specific servlet, JSP file or HTML
file cannot be accessed
from a browser, the first question to ask
is, what is the scope of the problem?
- The problem extends to all
of the resources served by WebSphere Application Server (no
servlet, JSP file or HTML page
is accessible), all resources served by the
same application server, or
all the resources in the same enterprise
application
- The problem is limited to a particular servlet.
If
this is true, some possible causes are:
- The class file which contains the
servlet code is missing, not in the right
location, or has a name which
does not match what WebSphere Application
Server is looking for.
- A supporting class (such as, EJB client
classes or third-party database access classes)
is missing or not on the
classpath. This is most likely the scenario if you
get a message like unable
to load servlet in the administrative console the first
time the servlet
is accessed. This can also happen when its
application server is started, and the application
server's standard
error file indicates a class other than the
servlet class itself.
- The URI being entered for the servlet
is not correct
- The servlet or JSP file is malfunctioning.
This might
be the case if the browser, tracefile, administrative
console, or activity log displays
Uncaught service() exception thrown by servlet (a generic exception indicating
application problems). Also, this might happen
if the class throwing an exception in these
files
is not a WebSphere Application Server class
(has a package name beginning "com.ibm").
If this is the case, discuss the problem
with the provider of
the servlet or JSP file. If necessary, follow
suggestions for debugging
a servlet or JSP file.
If none of these resolve the problem, look
for errors in
the following locations:
If none of these steps resolve the problem,
or yield error
messages or warnings which are not helpful,
obtain
help from IBM.
Cannot start the administrative console
If you attempt to start the administrative
client, and the interface is not displayed,
or if you see a dialog box or window briefly
and then shuts
down, verify these items:
- If you are running the console remotely (not
on the same machine as the
WebSphere administrative server)
- Do you have TCP/IP connectivity between the
machine that is
running the console and the machine that
is running WebSphere Application Server.
Can
you run the ping <hostname> command on the console machine, where
<hostname> is the IP address or hostname
of the WebSphere Application Server serving
machine?
If not:
- The WebSphere Application Server machine
might be down
- The console machine might not have access
to the server machine
If so, contact the network administrator
and ask these questions:
- What is the server machine's IP address or
hostname on the network's
name server?
- Is there is a firewall between the two machines?
If so, is the WebSphere Application Server
bootstrap port (default 900) opened in the firewall?
- Are you accessing the administrative console
indirectly through a display export utility
like Hummingbird Exceed? If so, install the
administrative client
locally (you can install just this piece
of WebSphere Application Server) and launch
it against
the server by executing the command adminclient <remote-host-name>.
- What happens if the console is run from a
different machine? If
that works, there is an issue particular
to the failing machine, like
network access to the WebSphere Application
Server machine.
- WebSphere Application Server might not be
listening for client requests on the default
port
(900). Ask the WebSphere Application Server
administrator if the bootstrap port has been changed from the default of 900.
- Is the version of WebSphere Application Server the same as
the version of the administrative client?
Different versions, revisions,
as well as different fix pack levels between
the two, can cause failure.
Typically, this results in a low-level Java
exception like ClassCastException
or NullPointerException in the window from which the client was
launched.
- If you Cannot access the administrative server after
enabling security,
ask these questions:
- Did a log-in prompt display when the console
was launched? If not,
the security was enabled since the console
was installed,
and the console does not know that the server
is secured. This
can happen, for example, if the console is
running remotely. Check
the file product root/properties/sas.client.props on the
client machine
if the client machine is different from the
server. Ensure the following properties match
the values in sas.server.props on the serving
machine:
- com.ibm.CORBA.securityEnabled
- com.ibm.CORBA.loginUserid
- com.ibm.CORBA.loginPassword
- If a log-in challenge appeared, but the user
ID and password were rejected,
check the file product root/properties/sas.client.props on
the client machine, if different from the
server. Ensure the
following properties match the values in
sas.server.props on the serving
machine:
- com.ibm.CORBA.loginUserid
- com.ibm.CORBA.loginPassword
If none of these tips help:
- Look at the window from which the console
was launched. There might be
errors or exceptions helping to explain the
cause of the problem.
- Look at WebSphere Application Server product root/logs/tracefile
file. If the console program contacted the
server and was rejected, there might be related errors.
- Run the Log Analyzer on the server machine
and look for warnings and errors
If none of these steps help, gather any error
messages and dialogs from
the client, Log Analyzer, and tracefile file,
and obtain help from IBM.
My servlet or JSP file cannot call or connect
to third party software
If the servlet or JSP file uses classes provided by a third party vendor, or connects with a running process external to WebSphere Application Server such as a database or CORBA server, the following are potential causes of problems:
- The JAR file or directory containing the
software's supporting
classes is not on the servlet or JSP files
classpath. This is
indicated by Missing class errors or java.lang.classNotFound exceptions
in the application server's standard error
or output files. These files also indicate
the missing class. Ensure supporting
classes are provided to the servlet or JSP file.
- The third party software depends on a release of the Java JDK that is not compatible with WebSphere Application Server JDK. If this happens,low-level errors or exceptions like java.lang.ClassCastException might occur.
Verify with the third party software vendor or its documentation that the software is compatible with the WebSphere Application
Server JDK level. See the InfoCenter article 1.3: Prerequisites for more information regarding prerequisite information.
A servlet or JSP file displays an error or
Java exception instead
of the correct output
What is the scope of the problem?
- If calling a servlet or JSP file results
only in an error message
in the browser, look at the hints for "Cannot access
a particular servlet from a browser".
- If the servlet is functioning, but
parts of the output are missing (for example,
the image files do not display), then the
servlet links to components incorrectly,
or the subcomponents are missing
or in the wrong directory. Check the resource
references to other resources.
- Do the files they refer to exist?
- Are the references correct?
- References that begin with "/" start from
the document root
of the current Web application. If the reference
does not start with a "/",
the current path of the host resource is
prepended to the called resource's
URI.
- If the servlet is functioning, but its output
does not appear to be correct (for example,
the output does not appear to match
a user's search criteria), then follow the
steps for debugging
a servlet or JSP file.
If none of these steps help in resolving
the problem, gather
the Web server error and access logs, WebSphere
Application Server's tracefile,
the application server's standard error and
output file, and the native.log
file, and obtain help from IBM.
If you share the document root of the WebSphere
Application Server within the Web server
document root, a security exposure can
result as the Web server might display the JSP
source
file as plain text.
You can use the WebSphere Web server plug-in
set of rules to determine whether a given
request will be handled by the WebSphere
Application Server. When an incoming request
fails to match those rules, the Web server
plug-in returns control to the Web server
so that the Web server can fulfill the
request.
In this case, the unknown host header causes
the Web server plug-in to return control
to the Web server because the rules do
not
indicate that the WebSphere Application
Server
should handle it. Therefore, the Web server
looks for the request in the Web server
document
root. Since the JSP source file is stored
in the document root of the Web server,
the
Web server finds the file and displays
it
as plain text.
To fix this problem, move the WebSphere Application Server JSP source file outside of the Web server document root. Then, when this request comes in with the unknown host header, the plug-in returns control to the Web server and the JSP source file is not found in the document root. Therefore, the Web server returns a 404 File Not Found error rather than the JSP source file.
Unauthorized users can
access servlet, JSP file, or HTML file when
security is enabled
If unauthorized users can access a secured
resource, these
are the steps to follow:
- Ensure that all of the steps
necessary to secure the resource have been followed. Enabling
security in the administrative console is
not enough. In summary, these steps
are:
- Enabling security and setting global security
properties
in the administrative console's Security
Center
- Defining security roles for the enterprise
application in
the AAT
- Mapping security roles to security role references,
if any,
established by enterprise beans or servlet
provider in the AAT
- Mapping enterprise bean methods to security
roles, if any, in the AAT
- Creating security constraints for servlets
in the AAT
- Mapping security roles to security constraints
in the AAT
- Create a Web resource collection under the
constraint to
map URLs and methods to the constraint
- Defining "run-as" roles for enterprise beans
at enterprise application
installation time or in the administrative
console's Security Center.
- Map roles to actual user or group IDs, at
enterprise application
installation time or in the administrative
console's Security Center.
- If security has been set up, verify
the settings. Specifically, for a servlet, verify that:
- At least one security role has been created
in the Web module
the affected servlet belongs in
- A security constraint has been created in
the Web module
where the affected servlet belongs, which
contains the role
- A Web resource collection has been created
in the security
constraints, which contains the affected
servlet's URL pattern and methods
- Verify that access to a resource's role has
not been granted
to all users in the Security Center in the
administrative console.
- If more than one logical URL name for a resource
has been
defined (for example, the same physical servlet
MyServlet.class can be
accessed as "http://<hostname>/myapp/servlet/MyServlet"
and "http://<hostname>/myapp/servlet/MyServlet2")
make sure that all URLs are mapped to a constraint
in the AAT.
- The process for verifying access to a JSP
file is the same as
that for a servlet
- HTML pages not served by WebSphere Application
Server, Advanced Edition 4.0.x, cannot be secured by WebSphere Application Server.
If an HTML file is to be secured, the URIs
and the
resources must be packaged in a Web application
archive.
- If the unauthorized access is to an enterprise
bean, also verify
the settings. Specifically, verify that:
- At least one security role was created in
the enterprise bean module
where the affected enterprise bean belongs
- A method permission object in the enterprise
bean module containing
the affected enterprise bean, was created
in the
security constraints. The security constraints
maps the security role to the affected
enterprise bean's remote and home interface
methods.
- Verify that access to the enterprise bean's
role has not been granted
to the authorized users, groups, "Everyone",
or "All authenticated
users" in the Security Center in the administrative
console.
- If unauthorized access to an enterprise bean
occurs when called from another
enterprise bean (such as, by a session enterprise
bean, which is a client of a CMP bean),
ensure that the client enterprise bean has
its "run-as" identity set appropriately.
If none of these steps reveal the source of the unauthorized access, run the Log Analyzer.
If the source of problem is still not apparent, gather the following files:
and obtain help from IBM.
Authorized users cannot access
the servlet, JSP file, or HTML file when
security is enabled
If Authorized users (that is, users entering
valid IDs and passwords)
cannot access a secured resource, follow
these tips:
- Ensure all of the steps
necessary to secure the resource have been followed. Enabling
security in the administrative console is
not enough. In summary, these steps
are:
- Enabling security and setting global security
properties
in the administrative console's Security
Center
- Defining security roles for the enterprise
application in
the AAT
- Mapping security roles to security role references,
if any,
established by enterprise bean or servlet
provider, in the AAT
- Mapping enterprise bean methods to security
roles, if any, in the AAT
- Creating security constraints for servlets
in the AAT
- Mapping security roles to security constraints
in the AAT
- Create a Web resource collection under the
constraint to
map URLs and methods to the constraint
- Defining "run-as" roles for enterprise beans
when the enterprise application
is installed or in the administrative console's
Security Center.
- Map roles to actual user or group IDs when
the enterprise application
is installed or in the administrative console's
Security Center.
- If security has been set up, verify
the settings. Specifically, for a servlet, verify that:
- At least one security role has been created
in the Web module where
the affected servlet belongs
- A security constraint has been created in
the Web module
where the affected servlet belongs, in which
contains the role
- A Web resource collection has been created
in the security
constraints which contains the affected servlet's
URL pattern and methods
- Verify that access to a resource's role has
been granted
to the affected user, a group the user is
in, to "Everyone" or to "All
authenticated users" in the Security Center
in the administrative console
- If more than one logical URL name for a resource
has been
defined (such as, the same physical servlet
MyServlet.class can be
accessed as "http://<hostname>/myapp/servlet/MyServlet"
and "http://<hostname>/myapp/servlet/MyServlet2")
make sure that all URLs are mapped to a constraint
in the AAT
- The process for verifying access to a JSP
file is the same as
that for a servlet
- If the unauthorized access is to an enterprise
bean, also verify
the settings. Specifically, verify that:
- At least one security role has been created
in the enterprise bean module
where the affected enterprise bean belongs
- A method permission object in the enterprise
bean module, which contains
the affected enterprise bean, has been created
in the
security constraints. The security constraints
map the security role to the affected enterprise
bean's
remote and home interface methods.
- Verify that access to the enterprise beans
role has been granted to
the authorized user ID's or groups, or to
"Everyone", or to "All authenticated
users" in the Security Center in the administrative
console
- If unauthorized access of an enterprise bean
occurs when it is called
from another enterprise bean (such as, by
a session enterprise bean which is a client
of a
CMP bean), ensure that the client enterprise
bean does not have its "run-as" identity
set inappropriately
- Look for authorization failed and authentication failed-type
messages in the tracefile. These will display
what user ID is being
used to authenticate and which resource it
is being checked against
when access fails.
- Authorization failures occur when WebSphere
Application Server finds the user ID
in its system, but it is not authorized to
access the resource
- Authentication failures occur when WebSphere
Application Server does not find
the user ID and password in its registry
(operating system, LTPA server, or
pluggable registry). This can happen because:
- The user ID is not in the system, because
it is missing
or a mistyped or intentionally bogus user
ID was entered
- An invalid password was entered by the user
- The settings for accessing and searching
the registry are
invalid or too narrow
If none of these steps reveal the source
of the access problem,
run the Log Analyzer.
If the source of problem is still not apparent,
gather
the following files:
and obtain help from IBM.
Users have access problems
even after entering valid log-in information
If users can successfully access a secured
Web session, but cannot access
another page in the same Web session, here
are some tips:
- Are the users going to a page in the same
Web application
that is not secured? If the user encounters
an unsecured resource
in their navigation path within the same
Web application, the credentials are lost.
The resolution is to secure everything that
the user in the Web application might
reasonably access in a session.
- If the application is cloned across multiple
servers, ensure
that single sign-on is enabled in the administrative
console's Security Center.
Also, make sure the domain and realm fields
are the same on all servers.
- If a host's short name is being used to access
the affected
resources, try using the full Internet domain
name in the URL.
If none of these steps reveal the source
of the problem,
run the Log Analyzer.
If the source of problem is still not apparent,
gather
the following files:
and obtain help from IBM.
Form-based login is not working
What kind of problem are you having with
form log-in?
- If the user is not redirected to the form
when accessing
a secured resource:
- Check the tips for unauthorized
access problems
- Temporarily switch from form log-in to basic
challenge in
the administrative console's Security Center.
If basic challenge works, the resource
has been secured correctly, but there is
something wrong with how the form
log-in implemented.
- Ensure the form's URI as entered in the Security
Center
is correct
- If the user is entering the WebSphere Application
Server's short name,
try entering the complete domain name in
the browser when accessing the
secured URI
- If the user is directed to the form, but
logging in with
a valid user Id and password does not work
(for example, a valid user is not granted
access to the resource)
If none of these steps reveal the source
of the problem,
run the Log Analyzer.
If the source of problem is still not apparent,
gather
the following files:
and obtain help from IBM.
Errors are displayed after configuring
general security
If you are unable to save the general security
settings in
the Security Center of the WebSphere Application
Server console, it is probably because the
values
are incorrectly specified on the Authentication tab. The values direct
WebSphere Application Server on how to communicate
with the system (operating system, LDAP server,
or classes that you provide), which then
verifies user IDs and passwords.
For details on these fields, see help on global
security settings.
If you are using LDAP, verify:
- The hostname has connectivity to the WebSphere
Application Server server
machine (for example, the hostname can be
pinged from a command window)
- The port is the one the LDAP server is listening
on (usually
389)
- The Security Server ID and password are valid
on the
target LDAP server
- The user filter is correct for the way that
the Security
Server ID and other user IDs are stored in
the system (for example, if a clause
in the filter specifies "inetOrgPerson:uid",
that users are stored in the
LDAP server with object type of inetOrgPerson,
and that the "uid" field
is filled in)
- The Bind Distinguished Name and password
are valid values
for binding to the LDAP server. Verify this
by manually
binding to the LDAP server using its own
administrative GUI, or by running
the "ldapsearch" utility provided with LDAP
servers.
If you are using the local operating system
as your user
registry system, verify that:
- The user ID has root-type authority (UNIX)
or
- The account is a member of the administrators
group and must have the rights to "Log on
as a service" and "Act as part
of the operating system."(Windows NT/2000)
If you are using a Windows NT domain,
the user ID must be an administrator in the
Windows NT domain.
If you are using the pluggable registry,
verify that:
- The class used to implement the CustomRegistry
interface
is on Classpath
If none of these steps help, try to save
the global security
settings, then run the Log Analyzer.
If the source of problem is still not apparent,
gather
the following files:
and obtain help from IBM.
When mapping users to security
roles, the lists of users and groups are
empty
If the list of available users and groups
is empty in the
Security Center, ensure that:
- If you are using LDAP server as the user
registry, it is started and running
- The filter settings specifying object type
and attribute
name, match the way users are stored in the
LDAP server
- The way you search for users ("*") is valid
when plugged into the
filter's placeholder ("%v"). Verify this
by using the ldapsearch utility
of the LDAP server.
- The Bind Domain Name and password are corrected.
Verify this by using the
ldapsearch utility of the LDAP server.
- The Base Domain Name is correct and at a
level in
the LDAP directory structure where it contains
the user IDs that you want to select
from. Verify this by using the ldapsearch
utility of the LDAP server.
- If you are using the operating system as
your registry, verify that:
- The user ID has root-type authority (UNIX)
or
- The account is a member of the administrators
group and must have the rights to "Log on
as a service" and "Act as part
of the operating system." (Windows NT/2000)
If the machine is a member of an Windows
NT domain,
the user ID must also be an administrator
in the Windows NT domain.
- If you are using a pluggable registry, verify
the class
used to implement the CustomRegistry interface
is on WebSphere
Application Server's classpath
- If none of these steps help, try to search
for users, then
run the Log Analyzer.
If the source of problem is still not apparent,
gather the
following files:
and obtain help from IBM.
Modifying and recompiling an existing servlet
Suppose you want to add trace code, a main()
method,
or make other changes to an existing servlet
source and recompile and
deploy it. Here are some tips:
If you have trouble finding the servlet source
(Java) file, follow
the procedure for finding the servlet .class file.
Typically, if the Java file exists, it will
reside in the same EAR file as the class
file. Then, an unzip utility
or the JAR command can be used to extract the Java
file.
The EARExpander tool is also available to
expand or collapse and enterprise application.
This tool will unjar all various archives
in an EAR file all at once versus individually.
The tool can be invoked as \bin\EARExpander.bat/sh.
Recreating run time classpath
You should try to reconstruct the classpath
under which the servlet
runs when recompiling the servlet. If there
are problems
with the classpath (like missing supporting
classes), repeating
the compile process might reveal the cause.
The classpath setting can be
duplicated at compile time by using the -extdirs
<one-or-more-directories>
option of the javac command, and giving it the same value as
the -Dws.ext.dirs
property in the admin.config file. The -extdirs option takes a list of
directories.
Subdirectories and JAR files in the -extdirs directories are automatically
added to the classpath. You do not need to
add them individually.
Any supporting JAR files specific to the
application are added by setting
up a classpath environment variable, or by
adding them to a temporary directory
and adding the directory to the -extdirs
option when you run javac. If you get
an error indicating that -extdirs is not
a valid javac option, you are probably
picking up an earlier javac version. Make
sure to run Java and javac from the [Websphere
install
directory] /java/bin directory. For simple
Java programs, it might be enough to add
-extdirs [webSphere install dir]/lib to the
javac command.
A servlet or JSP file displays an error or
Java exception instead of
the correct output
The following are techniques for diagnosing
problems in a servlet or JSP file.
These techniques are recommended for use
in a test environment only.
- Output statements can be added to the doGet(), doPost() or service()
method of the servlet Java class, or within
the Java code blocks of a
JSP file. System.out.println() and System.err.println()
statements write to the
containing application server's standard output
and standard error files, respectively. The String passed to
these statements can display variable contents
or indicate
a certain method has been reached. This requires
updating
the servlet source with the print statements,
recompiling the servlet
and restarting its application server.
- The servlet can be enhanced to run as a standalone
program.
To do this, create a public method main()
in the servlet Java file.
The main() method will have logic copied
from the servlet's existing
doGet(), doPost() or service() method. After
the class is recompiled,
it can be executed from a command line using
the command java <servlet-class-name>.
The Java command installed with WebSphere Application Server (in product root/java/bin>)can be used for this purpose. If the servlet can run as a main program,the problem is related to how it is deployed in WebSphere Application Server. This technique requires an update to the servlet source to add the main()method, and a recompilation of the servlet to pick up the change. If the problem involves a JSP file, see below for how to get it in servlet form.
- The OLT/Debugger tool, provided with WebSphere Application Server,
Advanced Edition, can be
used to step into a running servlet to examine
return codes and
variables during execution. In order to do
this, the servlet class
file must be compiled with the -g option,
if it was not originally created
this way, and the application server must
be set up to communicate with
the OLT client program. For details, see
the documentation on the
OLT and Debugger
tool.
- If the problem resides in a JSP file, the servlet
source created from the JSP file by WebSphere
Application Server can be captured using
the "keepgenerated"
option. After this has been done, the new Java file
can be deployed
and debugged as a servlet.
All of these procedures, (with the exception
of number three, if the source file
was already created with the -g option),
require the servlet source file
to be recompiled. The Java compiler utility
installed in
product root/java/bin can be used for this purpose.
Also, the classpath environment variable under
which the servlet has been running should
be duplicated when the servlet
is compiled.
Typically, the servlet source file, <servletclassname>.java, if
supplied by the developer, will be found
in the same EAR file
as the servlet class file. To find it, follow
the procedure for
verifying
a servlet class file.
Once you have recompiled the servlet, unless
you are running it as a standalone Java program,
follow the procedure for reloading a resource into
WebSphere Application Server.
If you have converted it into a main program,
launch it using the >product root/java/bin/java <javaclass> command. Again,
for a good test, replicate the WebSphere
Application Server classpath under which
the servlet ran.
Verifying the servlet URI, class file and
classpath
To determine if the URI you are entering
matches a servlet
served by WebSphere Application Server and
that the class file is in the right place,
check the following:
A servlet is contained within a Web application,
stored as a .war (Web
application archive). The Web application
is logically contained in an enterprise
application, which is physically stored in
an EAR file.
- Start the AAT, and use File > Menu to open
the EAR file, which contains the Web application
and servlet. (If you don't know which EAR
file contains
the servlet's Web application, use the administrative
console to examine the Web modules
under each enterprise application. If you
don't know the enterprise application,
EAR file, or Web application containing the
servlet,
step through all the EAR files in the AAT
until you find the right one.)
- In the AAT, expand the enterprise application's
Web modules
- Under Web modules, select the Web application
containing the servlet.
In the properties on the right, look at the
"context root" attribute. This
field corresponds to the "application path"
attribute of earlier versions of WebSphere
Application Server.
All the resources served by this Web application
must start with this path in the
URL.
- The classpath field represents JAR file(s)
containing any supporting
classes needed by the application's resources, like
enterprise bean client classes if
a servlet is an enterprise bean client.
- Now expand the application's Web Components,
then select the servlet you
are trying to access. The component name
reflects the logical
name of the resource as entered in the URL.
The servlet class name
represents the program WebSphere Application
Server needs to load when the URL is requested.
- If the servlet has been added to the application
by using the AAT,
its class or JAR file does not need to be
explicitly added to the
Web application's classpath.
- When an enterprise application is installed,
its EAR file and the
WAR files it contains are physically expanded
into a directory named after
the EAR file. Usually you will find this
directory under the product root/installedApps
directory. Servlet classes exist in the <earname>.ear\<warname>.war\WEB-INF\classes
directory or in a JAR file contained within
the WEB-INF\lib directory.
These items are automatically included in
the Web applications classpath
by the Web container.
Example: If the Web application's context
root is /webapp/examples, and it has
a servlet whose component name is "ping,"
and whose class name is "PingServlet",
then:
- The URL for accessing the servlet would be
http://<hostname>/webapp/examples/ping,
and
WebSphere Application Server would attempt
to find and load the class PingServlet the
first time it is invoked, or when the containing
application server is started,
if "load on startup" is checked.
Accessing the resource directly from
WebSphere Application Server's built-in HTTP
server
It can be useful to try accessing a servlet
or other Web resource directly
through an application server's built-in
HTTP server, bypassing the production
Web server. If successful, the problems serving
the resource are related to the Web server
or to its WebSphere Application Server plug-in,
which
it uses to communicate with WebSphere Application
Server.
If unsuccessful, WebSphere Application Server
has a problem loading or serving the resource,
like a missing
class file.
To access a resource through an application
server's HTTP server,
specify the application server's HTTP listener
port in the URI. For example, if
the resource you are looking for is normally
accessed as "http://myhostname.mydomain.com/servlet/snoop",
try instead "http://myhostname.mydomain.com:NNNN/servlet/snoop",
where NNNN is the port number used by the
application server under
which the enterprise application that contains
snoop is installed.
To find the right port number, look in the
product root/config/plugin-cfg.xml file. There should
be a block
similar to (this example uses an application
server named "default_server"):
<!-- Server groups provide a mechanism
of grouping
servers together. -->
<ServerGroup Name="default_group">
<Server Name="default_server">
<!--
The transport defines the hostname and port
value that the Web server
plug-in will use to communicate with the
application server. -->
<Transport
Hostname="localhost" Port="9080" Protocol="http"/>
</Server>
</ServerGroup>
The port attribute of the <Transport>
block indicates
the HTTP port of its application server,
in this case 9080.
Adding and verifying
supporting classes or JAR files to a Web
application's classpath
If an application server generated a java.lang.ClassNotFound
exception in trying to load a servlet, and
the indicated class is not the
servlet, a supporting class or JAR file
is missing from the application server's
classpath.
To view and update the classpath, use the
AAT.
- Start the AAT,
and use File > Menu to open the EAR
file containing the Web application which
has the servlet.
- In the AAT, expand the enterprise application's
Web modules.
- Under Web modules, select the Web application
containing
the servlet.
The classpath field represents JAR file(s)
containing
any supporting classes needed by the application's resources, like
EJB client
classes if a servlet is an EJB client. Add
any needed JAR files,
or directories containing individual classes
here.
Make sure WebSphere Application Server's
administrative
server is started and running
The best way to examine the state of the
WebSphere Application Server administrative
process
is to start the administrative console.
If you cannot access the console, any of
the
following steps can be used to verify that
WebSphere Application Server
is working:
- Access a resource served by WebSphere Application
Server, such as the sample servlet <hostname/servlet/snoop>.
If
the resource returns a Web page, WebSphere
Application Server is working.
If a Web page is not returned, this does
not necessarily mean WebSphere Application
Server
is not running; any number
of factors can cause a servlet not to return
output.
- Use the ps -ef | grep AdminServer command (UNIX only). If it returns
a process, WebSphere Application Server (or
some other process named AdminServer) is
running.
Run a WebSphere Application Server utility
like WSCP or xmlconfig. These utilities
are WebSphere Application Server client applications.
They will only work if WebSphere Application
Server
is started and running. It is mandatory that
you execute a task because entering
the command and getting the usage information
does not initiate contact with
the server.
- Check to see if the administrative server
is started and running by looking at the
Services panel
(Windows platforms only) to see if the status
"started"
HTTP sessions are not created,
or are dropped between Web requests in a
session
To view the sessions settings for an application
server,
see the InfoCenter article 6.6.11: Administering HTTP session support.
If HTTP sessions are not created, or appear
to get dropped
between one Web request and another within
the same session (multiple requests
within a short period of time from the same
browser on the same client
machine), here are some possible causes:
- In the sessions settings for the application
server, is sessions
management enabled?
- If the mechanism for storing and retrieving
session ID is
cookies, are cookies enabled on the affected
browser?
- If the mechanism for storing and retrieving
session ID is
URL rewriting, are there any static HTML
pages in the user's navigation
path? If so, the session will get dropped
since WebSphere Application Server cannot
update the URL link that the user clicked,
so that the next page will include
the session ID.
- Is data getting dropped when the user goes
from a page in
one Web application to another? With WebSphere
Application Server, Advanced Edition 4.0.x
and later, because
of the J2EE specification, sessions are not
shared across Web applications.
- Are persistent sessions turned on in the
application server?
If so, were correct values given for the
data source, user ID and password?
Is the specified database started and running?
- Is the application or some of its components
cloned across
multiple servers? If so, has session persistence
been enabled?
- Is security enabled? If so, is the user doing
anything
to lose their security log-in information
before going to the page where
session data is dropped (like visiting a
page that is not secured)?
If you are using both session management
and WebSphere Application Server security,
make sure that
all pages in your Web application are secured.
Try using the snoop sample servlet to diagnose
the problem.
Snoop displays all the elements in the current
HTTPSession, including session
ID. You can jump to snoop after a session
is started, then
go back to it in between other pages to see
when the session ID changes
or has been dropped. This technique will
work if the snoop servlet
is in the same Web application as your application.
If necessary,
deploy the snoop servlet (look for SnoopServlet.class
in product_installation_root/installedApps/sampleApp.ear/default_app.war/WEB-INF/classes).
Try using the Log Analyzer to see if there
are any relevant
errors or warnings. Files to look at are:
The application server standard output and
error files
The plug-in's native.log file
The Web server's error and access log files
If you still cannot track down the problem,
gather these
files and obtain help from IBM.
Verifying the Web server's configuration
file
See the InfoCenter article 6.6.45: Administering WebSphere plug-ins for Web servers for more information
on verifying the Web server's configuration file.
Determining the version of WebSphere Application Server
The easiest way to determine what version of WebSphere Application Server you have
installed is to launch the administrative console, then click the Help menu, and
select About.
Alternatively, you can browse the file, product root/properties/com/ibm/websphere/product.xml
and look for the block named "version".
Verifying the classpath for a servlet, JSP file, enterprise bean
or supporting classes
The following problems are indications that the right class or
classes are not available to your servlet, JSP file or enterprise bean:
- Missing class error or classNotFoundException
These errors might display in the administrative console,
browser output, Log Analyzer, or application server's standard output or
error file after the application server tries to load or execute a resource, or compile a JSP file.
This indicates that a needed application server is missing.
- No such method error or classCastException
These errors might display in the administrative console,
browser output, Log Analyzer, or application server's standard output or
error file after the class tries to load or execute a resource, or compile a JSP file.
This indicates that the wrong version of a supporting class
is being loaded.
When this happens:
- Search for the class indicated in the error
to verify that it exists somewhere
in WebSphere Application Server's directory,
and to determine if there are more
than one versions of the same class.
- In Windows NT/2000, open the Windows NT/2000
Explorer and select the product root.
- Use the Tools > Find > Files or Folders menu option to search for <missing
class name>.class
- Also, search for occurrences of the class
inside a JAR file by using the
Tools > Find > Files or Folders menu option.
Search for all files named *.jar, containing text (Advanced tab if Windows NT/2000)
<missing class name>.class
- On UNIX systems, open a command window in
the WebSphere Application Server installation
directory
(or the root directory if there is any chance
that the class might
exist elsewhere).
- Search for occurrences of the missing class
by executing find . -name
<missing class name>.class -print
- To find JAR files containing the class, create
a command or shell script that recursively
extracts the contents of each JAR file and
searches the results for the missing class.
The following sample, which searches JAR
files for a class file called Policy.class
can be saved and executed on a UNIX system:find
./ -type f -name '*jar'|
while read jfile
do
jar vtf $jfile|grep Policy.class
if [ "$?" = "0" ]
then
print found "Policy.class in $jfile"
fi
done
- If the class cannot be found, contact the enterprise bean, servlet or JSP file provider
and ask about the missing class.
- If the class exists, but is not getting loaded, or the wrong version is
getting loaded, review the information on setting classpaths
and on classloaders. Compare them to your
configuration. Use the Application Assembly
Tool to add the supporting class directory or JAR file to the dependent
Web application or enterprise bean container.
An error occurs generating deployed code for an
enterprise bean
If you receive error messages when trying to generate deployed code for
an enterprise bean in the AAT, here are some things to check:
- Does the input JAR file contain a specification
level 1.0 enterprise bean?
One way to tell is if the JAR file does not
contain the files required
to deploy a 1.1 enterprise bean:
- ejb-jar.xml
- ibm-ejb-jar-ext.xmi
- ibm-ejb-jar-bnd.xmi
If this is the case, convert the enterprise bean to
specification level 1.1.
-
Is the enterprise bean class part of a Java package? In other words, does its definition include a
package statement
class (you might need to verify this with the developer or provider of the
enterprise bean)? If not, its class must be changed to be part of a package.
This is to ensure uniqueness of class names across enterprise beans.
This is required in WebSphere Application Server, Advanced
Edition
4.0.x.
If these tips don't resolve the problem, gather any error messages displayed
by the AAT, and obtain help from
IBM.
An error occurs installing an enterprise application
If you receive errors in the administrative console while installing
an enterprise application, here are some items to check:
-
Does the enterprise application contain persistent (CMP or BMP) enterprise beans?
If so, has the data source referenced on the Bindings tab of the enterprise bean's
properties been defined?
-
Is the enterprise application you are installing already installed?
If so (you have made changes to the deployed code and are reinstalling
it), uninstall the enterprise application before reinstalling
it.
-
Is the EAR file that represents the application in a read-only state? If so,
change it to write state and install the application again.
Run the Log Analyzer for clues as to why
the client application is failing.
If these tips don't resolve the problem, gather the tracefile,
the activity log, and the
standard output and error files from the application server into which
you are trying to install the application, and obtain
help from IBM.
Converting 1.0 enterprise beans JAR files to 1.1
See the InfoCenter article 6.3: Assembling applications and generating deployment code
to review converting enterprise beans JAR files.
My servlet, JSP file or session enterprise bean cannot connect
to a third-party software package
If your servlet, JSP file or session enterprise bean cannot access a third-party software
package, here are some tips:
-
Have you made client classes provided by the vendor, available to the
servlet, enterprise bean or JSP file? For example, if the client process is a servlet
or JSP file, are the client class files or JAR added to the classpath property
of the containing Web module in the AAT?
-
Are the client class files and the third party software J2RE 1.3
compatible?
-
Is the third party software running on a different physical from WebSphere?
If so, can the WebSphere server communicate with the the other software's
machine? For example, can you run the ping <remote server's hostname>
command from one machine and get a valid response? If not, contact the network
administrator because there
might be name server or firewall issues involved.
-
It can be useful to run your servlet, JSP file or enterprise bean
as a standalone application, outside of WebSphere Application Server, to isolate
the problem.
Run the Log Analyzer for clues as to why
the client application is failing.
If these tips don't resolve the problem, gather the tracefile,
the activity log, and the
standard output and error files from the application server containing
the resource which is trying to connect to third-party software, and obtain
help from IBM.
If clients cannot make SSL-encrypted requests or receive SSL-encrypted responses, here are some things to check:
- Does basic SSL communication work between
clients and your Web server, independent from WebSphere Application Server? In other words, can you access the welcome page of your Web server using SSL (with a URL of "https://[hostname]")? If not, check the Web server documentation on how to configure the Web server for SSL. Some Web servers require configuration changes for SSL.
- The IBM HTTP Server (IHS) does require changes to be made to its
httpd.conf file. Documentation can be found at http://www.ibm.com/software/webservers/httpservers/doc/v1312/ihsfaq1.html#sslconf.
- Have you added aliases to the virtual host in the administrative console to include SSL-type "https://" requests?
- In the administrative console, select Virtual Hosts from the topology, then
select each virtual host from which you intend to serve SSL requests
- On the General Properties tab, review the list of host aliases,
and ensure that for each hostname a customer uses, ":[portNumber]" is appended, where portNumber is the SSL port. For example, if one host alias is "www.myCom.com", change it to "www.myCom.com:9443", if 9443 is your SSL port. Remove or replace the entry "www.myCom.com" if you do not want to allow non-SSL access to the site.
- If you have added ":[portNumber]" to the
host aliases, does the port number you specified match the SSL port specified for the application server(s)serving your resources? For each application server which you intend to serve SSL-encrypted resources, do the following:
- Select the Services tab of the application server's properties in the administrative console.
- Select the Web container service entry from the services list, then click Edit Properties.
- Select the Transport tab. The host alias port should match the transport port property here.
- Do the application servers have SSL enabled,
and have the certificates and keyring files to support it been created?
For each application server which you intend to serve SSL-encrypted resources, do the following:
- Select the Services tab of the application server's properties
in the administrative console.
- Select the Web container service entry from
the services list, then click Edit Properties.
- Select the Transport tab.
- For each entry in the HTTP transport list,
select it and click Edit....
- Verify that Enable SSL is selected
- If Use global SSL default configuration is selected go to the Console >
Security Center in the administrative console and click
Default SSL
Configuration.
- Validate the key file name and password.
You might need to consult with the person who created the file, or
person who works with the third-party certificate provider, to get this information.
If this file has not been created, review the documentation in the WebSphere Application Server InfoCenter on how to use the IKeyman utility (provided with WebSphere) to create SSL certificates and key files.
- Since enabling SSL, have you propagated the configuration to the Web server (and its WebSphere Application Server plug-in)?
If SLL setup is correct, collect the following:
Cloned application server is never reached If, based on log file output, Resource Analyzer output, or lack of any performance improvements, one or more clones are not getting reached (that is, are not participating in workload management), check these items:
-
If the immediate client of the cloned resource(s) is a Java
standalone application, have you defined the CORBA and workload management bootstrap hosts?
-
Is workload management enabled for all servers in the domain? "Enabled" is the default, but this is worth reviewing if there is any possibility workload management has been disabled.
- Are the cloned application servers started?
- Have the cloned enterprise beans successfully started?
-
If the problem involves an entity bean, do you have Option C caching enabled in the EJB container?
Cannot start the cloned application server, or load or start the cloned servlet or enterprise bean
- If you obtain errors in the administrative console starting an application server clone,
an enterprise bean in a cloned server, or when a servlet is loaded or accessed for the first time, here are some items to to check:
- If the application server is cloned horizontally (for example, on a machine different from that of the server
group on which it is based) ask these questions:
- Have all of the supporting directories and files been created on the clone-hosting servers, including EAR files and JAR files?
- Have directory-dependent properties been updated on each cloned application server to correctly reflect its environment? See the topic, Creating clones on machines with different WebSphere installation directories or operating systems. Conversely, have any of these properties (like, classpath entries added to a Web module)
been changed on the server group, causing incorrect, server-specific values to be rippled to clones?
- Are you having problems loading, starting or calling an enterprise bean
originally created to run under earlier versions of WebSphere Application Server? If so, was
the enterprise bean JAR file created using the wlmjar utility? If this happened,
remove it and replace it with the original, wmljar version of the enterprise JAR
file. For details, see Migrating workload-managed enterprise
beans from WebSphere Application Server Version 3.5 to WebSphere Application Server, Advanced
Edition 4.0.x.
- If the problem involves an entity bean, do you have Option
C caching enabled in the EJB container?
Classpath and dynamic classloading
If WebSphere throws a Class not found or No class definition error
or exception, and the referenced class is physically present,
it is likely that the problem is happening for one of the following reasons:
-
The class has not been placed on the administrative server, application server,
or web application classpath
-
The classpath on which the class has been placed is too low on the classpath
hierarchy to be visible to the class that needs it (for example, it is referenced
by a servlet, but it is on the classpath of a different web application
in the same application server, rather than at the application server level).
-
The JAR file name or directory as defined on the classpath is misspelled, or the directory of the class
does not start at the package root
If WebSphere Application Server loads a version of a class file different
from the one physically present, it is likely that the problem is happening
for one of the following reasons:
- The process loading the class (such as, the administrative server or an application
server) has not been restarted or has not yet reloaded the class
- A different version of the same class is on a classpath, higher in the
classpath hierarchy than the desired class file. For example, the
administrative server is loading a JAR file from directory A, so when a Web
application starts that has the same file name in directory B's classpath,
its reference to the JAR file is ignored since its classes are already
loaded
For a description of all of WebSphere Application Servers classpaths, the classpath
hierarchy, and when classes get reloaded, see the InfoCenter article 6.4.1:
Setting classpaths.
If you have reviewed your classpath settings, and the name and location
of your class file and the JAR file (if any) which contains it, gather
the following:
- <websphere install dir>/bin/admin.config file
- <websphere install dir>/config/server-cfg.xml file
- standard output and error files from application
server containing the problem resource
- Output of the XMLConfig command (full export
option)
- EAR file or contents of directory which contains the problem enterprise
application
- Listing of the WebSphere Application Server
directory structure (and any other directories
containing not-loaded classes)
- In Windows NT/2000 run "dir/s > dirlist.txt"
from a root directory
- On UNIX, run "ls -R > dirlist.txt" from a
root directory
and obtain help from IBM.
User profile
If problems arise when implementing user profiles, here are some things
to check:
Verify that you have set up all of the steps described in the InfoCenter article
Configuring
user profile support.
Have you:
- Placed the access bean com.ibm.servlet.personalization.userprofile.UserProfile,
or its JAR file, userprofile.jar, on a classpath
so that it is visible to any servlet(s) or JSP file(s) calling user profile
APIs?
- Created an enterprise application in which you have included EJB modules
with the user profile enterprise beans UP_ReadOnly and UP_ReadWrite, in userprofile.jar?
- Deployed and installed the enterprise application?
- Created a installation_root/properties/userprofile.xml containing
configurable properties for managing user profiles?
- Specified a valid data source in userprofile.xml file and verified its user ID
and password?
- If security is enabled, have you created roles for the user profile beans,
and assigned to them the user IDs or groups of those who will be accessing
the client servlets and JSP files?
If all of these steps appear to have been completed properly, and you are
still having run-time problems with storing or retrieving user profile data,
Virtual hosting
If you have problems accessing resources served by one of the virtual
hosts defined on your WebSphere Application Server domain, here are some things to check:
-
Is the address you are using correctly defined to your Web server?
Can you access the welcome page of your Web server using the
host part of the URI ("http://<host-name-or-ip-address>"), where the
host name you enter represents the virtual host you are having problems
with?
- If not, do you have multiple virtual hosts
(sometimes called virtual servers)
served by the same physical Web server? If
so, is your Web server
configured correctly? Check the documentation
for your Web server
product. These are links for multiple virtual
host configuration
for some vendors:
- If your virtual hosts appear to be correctly
configured for your Web server,
are they correctly configured in WebSphere
Application Server? View the properties of
your virtual host(s) in the administrative
console.
- Does the virtual host (for example, default
host) contain a host alias
which matches the host name used to access
your Web browser? View
the list of host aliases and add new entries
as needed.
- Does it include an entry for all forms of
the host name which can be used
to access the server (short name, fully qualified
domain name, IP address)?
- If the port your Web server is listening
on is other than 80, or if you
have URLs not on port 80, are these reflected
in your host aliases (for example,
do you have aliases of the form, "someHostName:nnnn",
where "nnnn" is the
port number)?
- If you have SSL enabled on your Web server,
do you have host aliases of
the form, "<host name>:443" (assuming
you are using the default SSL port
of 443)?
-
Is your Web server running remotely (on a different server than WebSphere Application Server)?
If so, have you copied the plugin-cfg.xml file to the Web server machine
since updating virtual host information?
Use the Log Analyzer to look for errors related to the virtual host
If the problem is still unclear, look at these files for clues:
- tracefile
- native.log file of the application
server which contains the resources not getting served
- standard output and error files of
the application server which contains the resources not getting served
- >error and access logs of your Web server
If you are still unable to resolve the problem, gather these files, plus
and obtain help from IBM.
Connection pooling
If you encounter problems deploying application
code that uses connection
pooling, or encounter errors or exceptions
when a Web application attempts
to create or use a connection, here are some
things to look at:
- Has the application code been ported from
a WebSphere Application Server 2.x or 3.0x
server?
If so, have deprecated or unsupported APIs
been converted to the currently
supported JDBC 2 APIs? If you are not sure,
refer to the InfoCenter article Migrating
to supported database connection APIs (and
JDBC).
- Is the connection to a DB2 database? If so,
has WebSphere Application Server's environment
been set up to use the DB2 JDBC 2 driver?
This might not have been done,
especially if WebSphere Application Server's
repository is not DB2. See "Tips for data
access programming" in the InfoCenter article,
Obtaining and
using database connections.
- Browse the InfoCenter article, Tips for using connection
pooling for best and worst practices regarding connection
pool development
and administration.
- If exceptions are being thrown when an application
attempts to obtain or
use a connection, browse the InfoCenter article
Handling
data access exceptions.
- Run the Log Analyzer to look for WebSphere-generated
warnings and errors related to data access.
Also look for errors
in the standard output and error files
of the application server which hosts the
relevant Web or EJB module.
If the warning or error messages are not
clear, look for more detailed
descriptions in the Messages section.
- Use the jdbctest tool to access the problem
data source outside of WebSphere Application
Server, using the same ID and password you
associated with the data source. If you cannot
access the database with jdbctest,
it's likely that WebSphere Application Server
cannot either.
- Contact your database administrator for help
in determining whether the
target database manager is running, there
are available connections, and
to monitor access from the database side
to see if client requests are
arriving.
If you are still not able to diagnose the
problem, gather
and obtain help from IBM.
Enterprise beans, EJB modules, and EJB containers
If you have problems deploying an EJB module,
loading an EJB module
into an application server, or accessing
enterprise bean methods from a client
Java application, servlet, or other enterprise
bean, here are some things to look at:
- In the AAT, open the EJB module and use the
"verify
archive" menu option to validate directory paths
- Browse the deployment descriptors of the
EJB module for correctness in
the AAT. Open the enterprise bean JAR file
in the AAT and review its properties.
- If you do not have access to the AAT, use
the command jar -xvf to extract the files
ejb-jar.xml and ibm-ejb-jar-bind.xmi from the EJB module's JAR file.
Browse the files in a text or XML editor
to verify classpaths, path and
file and binding names. Verify the name(s)
clients are
using to access the bean match either the
original JNDI bean name or one
of the bind names.
- If the enterprise bean was originally created
for a previous release of WebSphere Application
Server,
review the article Migrating to supported enterprise bean specification.
- Ensure that the enterprise bean name is in
a package (for example, "com.mycom.MyBean"
instead of "MyBean").
- If the enterprise bean is an entity bean,
use the jdbctest tool to access the database,
using the same password and ID specified
in the data source which the
bean is associated
- Use the Log Analyzer to look for related
warning and error messages
- Review the standard out and standard error
files of the application server in which the enterprise
bean is deployed
- Check the deployment descriptors of the EJB
module and any Web modules in which they
have clients
(like servlets) to ensure that the EJB references
match (for example, that bindings are correct)
If you are still unable to diagnose the problem,
gather
and obtain help from IBM.
Several EJBs using local JNDI lookups
for J2C connection factories are
configured to go to a different connetion factory,
but they are all going to the same connection factory
One reason why you are having this problem is that the res-ref bindings might not be
not set properly. Check ibm-application-bnd.xmi
in %WAS_HOME%\installedApps\[ApplicationName]\META-INF\.
Another possibility is that the enterprise bean references are
bound to the same instance of their home class. This
can happen when the enterprise beans have the same package and class
name. The result is that only one instance of the home
is created on the server, and only one res-ref
mapping takes effect. This can be checked through the
dumpnamespace tool, for example:
2 (top)/CICSAdapterLog
com.cna.im.CICS.Adapters._CICSAdapterLogHome_Stub
5 (top)/CICSTapAdapter
com.cna.im.CICS.Adapters._CICSTapAdapterHome_Stub
113 (top)/CH3.CICSAdapterLog
com.cna.im.CICS.Adapters._CICSAdapterLogHome_Stub
All three bean references are bound to com.cna.im.CICS.Adapters._CICSAdapterLogHome_Stub.
If you are having problems starting a client
of the administrative server,
like the administrative console, WSCP, or
xmlconfig, here are some things to
check:
- If the problem process is the administrative
console, see the topic Cannot
start the administrative console.
- Make sure WebSphere Application Server's
administrative server is started and running
- If you are running the client process remotely
(not on the same machine
as the WebSphere administrative server):
- Are you specifying the host name and port
(usually 900) of the WebSphere
server when you invoke the client program?
- Do you have TCP/IP connectivity between the
machine you are
running the client and the machine that is
running WebSphere Application Server?
Can you run the ping <hostname> command on the client machine,
where <hostname> is the IP address or
host name of the WebSphere Application
Server serving machine? If not:
- The WebSphere Application Server machine
machine might be down
- You might not have access from the client
machine to the serving machine
-- contact your network administrator
and ask
- What is the serving machine's IP address
or hostname on your network's
name server?
- If there is a firewall between the two boxes
- if so, is the WebSphere
Application Server bootstrap port (default
900) opened in the firewall?
- WebSphere Application Server might not be
listening for client requests on
the on the port the client is sending on
(usually 900). Ask your
WebSphere Application Server administrator
if the bootstrap port you are using is correct.
- Is the version of WebSphere Application Server
the same as the version
of the client program? Differences of version,
revision and sometimes even
fix pack level between the two can cause
failure. Typically, this results
in a low-level Java exception like ClassCastException
or NullPointerException
in the window from which the client was launched
- Is WebSphere Application Server security
enabled? If so,
- Did a log-in prompt come up when the client
was launched? If not, it could be that
security was enabled since the client was
installed, and
the client does not know that the server
is now secured. This can happen,
for example, if the client is running remotely.
Check the file <websphere
install dir>/properties/sas.client.props
on the client machine, if you are running
the client from
a remote machine. Ensure the following properties
match the values in sas.server.props
on the serving machine:
- com.ibm.CORBA.securityEnabled
- com.ibm.CORBA.loginUserid
- com.ibm.CORBA.loginPassword
- If a login challenge appeared, but the user
ID and password was rejected,
check the file <websphere install dir>/properties/sas.client.props
on
the client machine, if different from the
server. Ensure the following
properties match the values in sas.server.props
on the serving machine:
- com.ibm.CORBA.loginUserid
- com.ibm.CORBA.loginPassword
- If none of these tips help:
- Look at the window from which the client
was launched because there might be errors
or exceptions that will explain the cause
of the problem
- Look at WebSphere Application Server <websphere
install dir>/logs/tracefile
file. If the client program contacted the
WebSphere server and was rejected
for some reason, there could be related errors.
- Run the Log Analyzer on the serving
machine and look for warnings and errors
If none of these steps help, gather any error
messages and dialogs from
the client, Log Analyzer, and tracefile file,
and obtain
help from IBM.
|