Administrator's Guide

CHAPTER 7

Maintaining the Server

This chapter describes how to perform some typical maintenance tasks on the Novell exteNd Application Server. It has sections on:

Administering an application server remotely

You can use the SMC to remotely administer servers. You can administer as many servers as you want from one SMC console. If you are running a server in a cluster, you can choose additional server clusters to administer.

For more information about server clusters, see Server clustering.

Procedure To administer a server:

Make sure the server you want to administer is up and running.
Start the SMC.
Select the Choose (server) icon.

The Add Server dialog displays:

Specify server:port, where:

Parameter	Description
server	The name of the server (such as localhost or http://hostname).
port	The administration port. You need to specify the port only if it is not the default port for your operating system. For more information about ports used by the server, see Setting up separate ports.

Parameter

Description

server

The name of the server (such as localhost or http://hostname).

port

The administration port. You need to specify the port only if it is not the default port for your operating system.

For more information about ports used by the server, see Setting up separate ports.

Click OK.
Use the SMC to administer the server.

Setting the AGCLASSPATH variable

The application server supports an environment variable called AGCLASSPATH, which allows you to extend the Java classes available to your applications. You can use AGCLASSPATH, for example, when you want to include third-party elements such as database drivers with your application. Use this variable instead of the +cp Java class path option described in Starting the application server. The application server overrides the CLASSPATH variable.

Operating system	Description
NetWare	The application server starts via an NLM, so you must set AGCLASSPATH using the setenv environment with semicolon-separated components; for example: setenv AGCLASSPATH=path1;path2;path3;...;pathx
UNIX	Set the environment variable AGCLASSPATH following the appropriate procedure for the shell you are using.
Windows	Set the AGCLASSPATH environment variable using the System settings tool available via the Control Panel.

Operating system

Description

NetWare

The application server starts via an NLM, so you must set AGCLASSPATH using the setenv environment with semicolon-separated components; for example:

  setenv AGCLASSPATH=path1;path2;path3;...;pathx

UNIX

Set the environment variable AGCLASSPATH following the appropriate procedure for the shell you are using.

Windows

Set the AGCLASSPATH environment variable using the System settings tool available via the Control Panel.

Maintaining deployed J2EE objects

The Deployment Options section of the SMC provides access to information about the J2EE objects that have been deployed on the server:

deploymentoptions

The following table describes the functionality for each of the panels:

Use this panel	To perform this function
Deployed Objects	Manage J2EE deployed applications like EARs, WARs, EJB JARs, application client JARs, and RARs.
JNDI tree	View the RMI JNDI (Java Naming and Directory Interface) tree for any application server currently managed by the SMC or to view the InitialContext of any server available to the SMC via the network.
Manage URLs	Use this panel to specify a default page for a database or server. Database URL—The page that displays when the user requests the URL for the database, such as http://localhost/MyApp/. If there is no default database page defined, the user sees a directory listing for the database (if this is allowed by the administrator). Server URL—The page that displays when the user requests the URL for the server, such as http://localhost/. If there is no default server page defined, the user sees a directory listing for the server (if this is allowed by the administrator).
Resource Adapters	View information about deployed resource adapters and their settings.

Using the Deployed Objects panel

The Deployed Objects panel lists:

EJB JAR files containing EJBs
WAR files containing JSP pages and servlets
EAR files that package other archive files into a full application
J2EE application-client deployments

For more information, see the J2EE deployment chapter in the Facilities Guide.

Procedure To manage deployed J2EE objects:

Start the SMC.
Select the Deployment icon from the toolbar.
Select Deployed Objects.
Expand the database containing the deployed objects you want to manage:

You can Undeploy WARs, EARs, CARs, and RARs.

You can Enable, Disable, Shutdown, and Undeploy EJB JARs.

Select a deployed object and perform one of the following actions.

Action	Description
Enable	For EJB JARs only. Enables a disabled EJB JAR. If a JAR is enabled, the beans in the JAR are available.
Disable	For EJB JARs only. Disables an enabled EJB JAR. If a JAR is disabled, none of the beans in the JAR is available. Disabling a JAR stops any running EJBs in the JAR. A disabled JAR remains disabled until it is explicitly enabled.
Shut Down	For EJB JARs only. Shuts down the JAR and all its beans for the current server session. When a JAR is shut down, none of the beans in the JAR is available. When the server is restarted, enabled JARs that had been shut down in the previous server session are again available.
Undeploy	Shuts down and removes deployed objects from the server.

Procedure To view deployed RARs:

Start the SMC.
Select the Deployment icon from the toolbar.
Select Resource Adapters.

The deployed resource adapters are displayed in the dropdown.
Select a resource adapter from the list to display the adapter's settings.

Procedure To view the JNDI tree:

Start the SMC.
Select the Deployment icon from the toolbar.
Select JNDI tree.

Choose the radio button for the function you want to perform:

Radio button	Description
RMI	Displays the RMI JNDI tree on the selected server.
Specify URL	Displays the InitialContext for any server available to the SMC via the network. To view the InitialContext for an LDAP server named beetle, you would enter the following: ldap://beetle/dc=novell.com

Radio button

Description

RMI

Displays the RMI JNDI tree on the selected server.

Specify URL

Displays the InitialContext for any server available to the SMC via the network. To view the InitialContext for an LDAP server named beetle, you would enter the following:

  ldap://beetle/dc=novell.com

If you chose Specify URL, click Submit.

Procedure To specify the default database URL:

Start the SMC.
Select the Deployment icon from the toolbar.
Select Manage URLs.
Select the Database URL radio button.
Choose the database whose default page you want to set from the Database dropdown.
Enter an URL in the URL text box and click set Default URL.

The URL should be a database-relative URL.

Procedure To specify the default server URL:

Start the SMC.
Select the Deployment icon from the toolbar.
Select Manage URLs.
Select the Server URL radio button (it is selected by default).
Enter an URL in the URL text box and click set Default URL.

The URL should be a server-relative URL and should include the database name (the same database you chose from the Database dropdown in the procedure above).

If your applications are deployed to the SilverMaster database, you do not need to include a database name.

Managing J2EE transactions

The application server supports J2EE transactions via the Novell exteNd Transaction Manager (TM), which is part of the Novell exteNd Messaging Platform. The TM is the transaction service for the ORB. It provides an implementation of the JTA TransactionManager and UserTransaction interfaces. These interfaces represent the contract between the transaction manager and the application server, and between the transaction manager and user applications.

You can use the SMC to specify settings for the TM transaction log, the resources the TM uses to recover transactions, and so on.

How the TM recovers transactions Transactions need to be recovered when the server suffers a catastrophic error and needs to be restarted. Here is the process the TM performs at server restart:

The TM reads the transaction log file.
The TM determines that a transaction needs to be recovered when items in the log have been prepared for a transaction but the transaction did not complete (in other words, the transaction did not commit or roll back).
The TM creates a number of worker threads (you specify the number via the SMC, as described in the procedure below). These worker threads are used to recover the incomplete transactions.
If a transaction includes access to a remote resource (like a CORBA resource), the worker threads will attempt to access those same resources. If the worker threads are unable to locate a remote resource, the worker thread will sleep for a specified length of time (the Resource recovery retry time limit specified in the SMC) before it attempts to access the resource again. In the meantime, the other recovery worker threads work on other incomplete transactions in the log.

Procedure To specify Transaction Manager settings:

Start the SMC.
Select the Configuration icon from the toolbar.
Select Advanced.
Select the Transactions tab:

Specify the settings as follows:

Field	Description
Preallocate log files when creating	Specifies whether to preallocate the transaction log file.
Log file max size (kb)	The maximum size of the transaction log file in KB. When the maximum file size is reached, the TM attempts to create a new log file.
Transaction timeout (seconds)	The amount of time allowed for all transactions managed by the TM to complete. The timer begins when the transaction starts. If the transaction does not complete before the transaction timeout period ends, the TM rolls back the transaction. Developers can override this value for specific transactions using the UserTransaction interface.
Resource recovery retry time limit (minutes)	Specifies the amount of time a worker thread will sleep before it attempts to access the remote resource again after a worker thread is unable to obtain a remote resource during a transaction recovery.
Recovery worker threads	The number of threads the TM should create to process a log file during a recovery. The higher the number of recovery worker threads the faster the recovery. However, since there is unlikely to be a large number of transactions to recover, the recovery will probably not take a lot of time. These threads are destroyed after the recovery completes.
JTS log file directory	The disk location for the transaction log file.

Click Update.
To activate the new settings, click the Restart button.

Monitoring server activity

The SMC provides several options that allow you to monitor server activity easily. These options are described in the following sections:

Displaying charts of server activity

You can display real-time charts of various server statistics.

Procedure To display a chart of server activity:

Select the server or cluster you are administering.
Select the Monitor icon from the toolbar.
Select Charts.

An empty chart displays:
Click Add Plot.

The Add Plot dialog displays, allowing you to choose which statistics you want to chart. The statistics are divided into categories.
Select a statistic you want to chart and click Add. Statistics marked with are count values; statistics marked with record changes in values.

The statistic is added to the table below the chart. The current value of the statistic is shown, as is the color of the plot line that will be generated.
(Optional) Select additional statistics, clicking Add after each one.
When you have selected all the statistics you are interested in, click Close.

What happens The application server plots all statistics you have specified and displays the exact values in the table below the chart. By default, the values are refreshed every five seconds. (To change this, enter a new number in the Refresh Interval box.)

Saving statistics settings for automatic reload

By default, the statistics you are plotting are not saved and reloaded between sessions of the SMC.

Procedure To save statistics settings:

Click the Reload current chart on start button at the bottom of the Charts panel.

The Reload Statistics dialog displays:
Check the Reload chart on start check box.
Specify a file name or choose the ellipsis to choose a file from the file system.
Click OK.

The charting data is saved to an XML file that is read each time you restart the SMC.

Saving chart data

By default, the statistics you chart are not saved.

Procedure To save chart data:

Click the Log chart data to file button at the bottom of the Charts panel.

The Log Chart Data dialog displays:
Check the Log chart data to file check box.
Specify a file name or choose the ellipsis to choose a file from the file system.
Specify the log file size or specify 0.

If you specify a log file size: when that file size is reached, the data is dumped to a file of the same name—but with the timestamp appended (to make the files unique).

If you specify 0: there is no limit on how large this file may grow (except the limits imposed by the file system).
Click OK.

The data is saved to a tab-delimited file.

Changing the scale and refresh rate

You can change the scale of the Y-axis by specifying a new value in the Scale field (the default is 100). You can also change how often the application server updates the values by changing the value in the Refresh interval field (the default is every five seconds).

Removing a plot

Procedure To remove a plot:

Select a plot and click Remove plot.

Editing a plot

It may be that you are plotting different statistics with very different scales but want them to appear clearly in the chart. To do this, you can change the multiplier for particular plots to equalize the values and make the chart easier to read.

Procedure To edit a plot:

Select the multiplier column in the row of the statistics you want to edit.
Select a multiplier value from the dropdown.

Saving a statistics set

Once you have charted a set of statistics that you are interested in, you can save the specification of the statistics set in a file so that you can easily view the set of statistics later.

NOTE: The file stores the list of statistics that are plotted but does not store the statistics' values.

Procedure To save a statistics set:

Display the statistics you want to save as a set.
Click Save.

The Save dialog displays.
Specify the file you want to save the statistics set in. The default extension is XML.
Click Save.

You can view the statistics set later by clicking Load, as described next.

Viewing a statistics set

Procedure To view a statistics set you have saved:

Click Load.

The Open dialog displays.
Select the file that defines the statistics set you want to view and click Open.

Displaying logs

If you have enabled server logging and are using the built-in logging class to log to the database, you can display the log(s) in real time in the SMC. (If you are logging to a file or using a custom class to do the logging, you can't display the log in the SMC.) As an alternative, you can use the PrintLog SilverCmd.

For more information about server logging, see Using server logging.

Procedure To display a log:

Select the server or cluster you are administering.
Select Monitor options.
Select the Logs panel.
Select the tab corresponding to the logging you have enabled and want to view.

What you can do You can:

Update the log by clicking Refresh (the log does not update automatically)
Sort the log by clicking a column header
Resize a column by placing the mouse pointer on the column's right border and dragging the mouse
View the message by double-clicking on the row or clicking Log Detail

Displaying views of server statistics

You can display in the SMC tabular views of server statistics related to individual sessions and threads, as well as a summary of server activity.

Procedure To access server statistics in a view:

Select the server or cluster you are administering.
Select the Monitor icon from the toolbar.
Select Statistics.
Select the tab for the category you want.

Statistics are updated dynamically.

What you can do You can:

Force an update by clicking Refresh
Resize a column by placing the mouse pointer on the column's right border and dragging the mouse

About the statistics The sections that follow describe the statistics that are displayed.

Session statistics

This tab displays statistics for each current client session:

Session statistic	Description
ID	Displays the session ID returned by a call to the AgiSession internal system table.
User name	Displays the user name of the person or entity logged on to this session. If unknown, displays Anonymous.
State	Displays the state of the connection.
Logged in	Displays true (checked) if the user has logged in (for example, from the browser's login). Otherwise, displays false (unchecked).
Host	Displays the host of the client source, if known.
Idle time	Displays the time elapsed (in seconds) since the last client connection on this session ended.
Protocol version	Displays the application server protocol used for the session.

Viewing statistics in a browser You can also display these statistics in a browser. Point your browser to http://server/SilverStream/Sessions.

Thread statistics

This tab displays statistics for each server thread:

statisticsThreadsTab

Following is a description of each of the fields:

Thread statistic	Description
Name	Nonclient threads are used for various internal tasks (such as cleaning up server data structures). Client threads handle incoming requests. There should be at least as many client threads as there are Maximum number of client connections listed in the SMC Connections panel (see Client connection parameters).
State	A brief description of the current state of the thread.
Start date	The start date for the thread. In many cases this date is the same as when the server was started. But for dynamically allocated threads this value will be different.
Busy time	The elapsed time (in seconds) since the thread has been actively working, as opposed to waiting. This value reflects how busy the server is in general.
Session	An internal session ID for this thread. See the Sessions tab to determine user/host information.

Transactions statistics

This tab provides statistics for transactions managed by the Novell exteNd Transaction Manager (TM):

StatisticsTransactionsTab

Following is a description of each of the fields:

Transactions statistic	Description
Active	The number of active transactions this server is responsible for managing.
Completed	The number of completed transactions.
Committed	The number of committed transactions.
Rolled back	The number of transactions rolled back.
Timed out	The number of transactions timed out.
Total	The sum of the active, rolled back, and completed transactions (excludes foreign transactions).
Active foreign	The number of active foreign transactions. A foreign transaction is a transaction that was started in another process (such as a different server or client application) that was propagated to this server via call to an EJB. The foreign transaction is controlled by the other process.
Total foreign	The sum of the active, rolled back, and completed foreign transactions.

Summary statistics

This tab provides access to different types of category summaries. The following describes the items for each tab selection:

Server statistics

Server statistic	Description
Server load	Provides a scaled value based on overall server activity.
Total number of hits since server was last started	The number of HTTP message requests the server has received since it was started.
Date/time server was started	The date and time the server was started.
Number of bytes emitted by server	The number of bytes returned by the server since it was started.

Request time statistics The statistics for this tab are enabled only when HTTP logging is enabled. For a description of HTTP logging, see Using server logging.

Request time statistic	Description
Minimum request processing time	The minimum elapsed time to process any HTTP request, from when the server receives the header until it transfers the reply.
Minimum request URL	The URL of the request that took the least amount of processing time.
Maximum request processing time	The maximum elapsed time to process any HTTP request, from when the server receives the header until it transfers the reply.
Maximum request URL	The URL of the request that took the most processing time (see previous row).
Mean request processing time	The mean (average) of the processing times for all requests received by the server.

Memory statistics The statistics for this option apply to the Java Virtual Machine (JVM).

Memory statistic	Description
Free memory	The result for the Java call Runtime.freeMemory().
Total memory	The result of the Java call RunTime.totalMemory().
GC count	The total number of times the Java Garbage Collector has run since the server was started. This number indicates how hard the server is being hit, how many objects are allocated, and how much memory pressure the server is under.

Memory statistic

Description

Free memory

The result for the Java call Runtime.freeMemory().

Total memory

The result of the Java call RunTime.totalMemory().

GC count

The total number of times the Java Garbage Collector has run since the server was started.

This number indicates how hard the server is being hit, how many objects are allocated, and how much memory pressure the server is under.

Thread statistics This option provides statistics about client threads that handle incoming client connections.

Thread statistic	Description
Free thread count	The current number of threads not associated with a client connection and available for immediate use.
Idle thread count	The number of threads associated with a client connection but not currently handling a user request.
Total thread count	The total number of client threads allocated. This number should be equal to the Maximum number of client connections in the SMC Connections panel (see Client connection parameters).

Thread statistic

Description

Free thread count

The current number of threads not associated with a client connection and available for immediate use.

Idle thread count

The number of threads associated with a client connection but not currently handling a user request.

Total thread count

The total number of client threads allocated.

This number should be equal to the Maximum number of client connections in the SMC Connections panel (see Client connection parameters).

Viewing statistics in a browser You can also display most of these summary statistics in a browser. Point your browser at http://server:port/SilverStream/Statistics. The page updates itself automatically every five seconds.

Integrating with existing Web servers

The application server provides Web server integration (WSI) modules that allow you to redirect requests for selected pages served by your Web server to an application server. You can use these WSI modules to integrate a Novell exteNd Application Server with your Web server.

For more information, see Using the Web Server Integration Modules.