Everyplace Active Session Table

This section contains an overview of the Active Session Table and its functional relationships. Tasks required for planning, migrating, configuring, and operating the Active Session Table from the remote operator interface are also covered.

• Overview
• Planning Information
• Installation
• Configuration
• Start and stop the AST server
• Remote Operator Interface
• Service
• Related Information

Overview

Everyplace Active Session Table (AST) replaces the function formerly provided by a component of Tivoli Internet Services Manager (TISM), which is part of Tivoli Personalized Services Manager. Everyplace Active Session Table provides a high speed specialized cache for information about users that are currently connected to the WebSphere Everyplace Server domain.

The AST servers are used by the Everyplace Wireless Gateways and WebSEAL-Lite servers. They must be able to communicate with the AST servers.

Planning Information

Before installing and configuring AST V2.1, you will need to estimate disk storage for the code, the cache data, and the log data. Minimum recommended values are:

You must also provide sufficient real memory for the AST server's indices. Allow 130 bytes for each active user entry, plus five megabytes for other information. Do not allow the real memory of the system on which the AST is installed to become so constrained that the AST's indices are paged out of real memory. If this occurs, performance may be impacted.

Note: The maximum number of active user entries is defined in the LDAP directory and may be changed via Everyplace Suite Manager.

Installation

Installation of Everyplace Active Session Table is handled through WebSphere Everyplace Setup Manager. Two AST servers should be installed on two different machines in the WebSphere Everyplace Server domain. The first AST server is the primary and the second is the backup.

Configuration

Under normal circumstances, the Active Session Table server configuration is performed by the Setup Manager at installation time using default values. Subsequent updates can then be made to the configuration values from the Everyplace Suite Manager. If, for some reason LDAP is not running, it is possible to configure the Active Session Table server outside of the Everyplace Suite Manager environment.

You can configure the AST Table server outside of the Everyplace Suite Manager environment by performing the following:

On AIX

• Copy the sample properties file /usr/IBMEPS/AST/Sample.AST.properties to /usr/IBMEPS/AST/AST.properties
  

• Edit the new file and define or change values, as appropriate.

On Sun Solaris

• Copy the sample properties file /opt/IBMEPS/AST/Sample.AST.properties to /opt/IBMEPS/AST/AST.properties
  

• Edit the new file and define or change values, as appropriate.

Go to Everyplace Active Session Table properties to view descriptions and possible values for the AST properties.

Start and stop the AST server

Normally, the Active Session Table (AST) is started from Everyplace Suite Manager, but you can also start it manually from the Unix command line.

To start the AST server manually:

1. Telnet to the system where AST is installed.
2. Enter nohup ASTServer &.

Using the no hangup command (nohup) when starting the server allows the server to continue running after you have logged off. Then you can log back on to the host and use the Remote Operator Interface to control the AST server.

Note: The Unix nohup command appends all ouput to stdout and stderr to a file called nohup.out. Over time, this file can grow quite large. Generally, it is a good practice to remove this file before starting the AST server with the nohup command.

To stop the AST server, use the Remote Operator Interface.

Remote Operator Interface

The AST server can be operated from two different user interfaces:

• Command line interface
• Everyplace Suite Manager

Both interfaces allow the operator to perform the following functions:

• Display cache statistics, for example the number of entries and the number of requests processed
• Stop the AST server
• Dynamically change the severity level of messages to be displayed in the AST logs
• Display current status, usage statistics and configuration parameters
• Query the contents of the cache by searching for entries that match a user-specified UserName@realm

To start the AST remote operator interface:

• Telnet to the machine were AST is running.
• Enter ASTConsole.

The main menu of the command line interface is displayed. At the top section of the main menu, the following fields are displayed:

Field	Description
Time	The time that the display was last refreshed
Ports	The ports that are in use by the AST
Log Level, File	The current severity threshold for messages logged to the log file
Log Level, stderr	The current severity threshold for messages logged to the stderr
Connections	The current number of connections between the AST and its clients
Entries, Auth Server	The number of cache entries created by WebSEAL-Lite servers
Entries, Gateway	The number of cache entries created by Everyplace Wireless Gateways
Requests	The number of requests processed since the AST was started
Errors	The number of requests containing errors
Inserts, Auth Server	The number of WebSEAL-Lite server inserts processed
Inserts, Gateway	The number of Everyplace Wireless Gateway inserts processed
Deletes	The number of deletions processed by the AST server
Queries (ID)	The number of ID Queries processed by the AST server
Queries (IP)	The number of IP Queries processed by the AST server
Cleanups	The number of cleanups processed by the AST server

From the main menu, you can choose from a set of options by typing a number and pressing Enter. The following options are available:

If option 1 is selected from the main menu, a confirmation panel is displayed asking for confirmation of the request to stop the AST server. Select 1 to stop the server or 0 to cancel the request.

If options 2 or 3 are selected from the main menu, the Set Log Level panel is displayed. The current log level is displayed along with a menu of message logging levels. Choose the level of messages to be logged to the log file by entering one of the following numbers:

If option 4 is selected from the main menu, the Properties panel is displayed. The current settings from the AST configuration file (AST.properties) are displayed at the top of the page. In addition the following options are available:

• If the value of the properties file name or the cache_dir entries is too long to be displayed in the space available, it is displayed with an ellipses in the middle. You can see the entire path name by choosing options 1 or 2 from the Properties panel, as appropriate.

• If the list of many acceptable hosts is too long to be displayed in the space available, choose option 3 from the Properties panel to display the entire list.

If option 5 is selected from the main menu, the Query UserName panel is displayed. This panel allows you to enter a search string pattern to select cache entries containing a UserName@Realm pattern. You can enter a simple string or a modified regular expression. The pattern you enter can contain '*' and '?' characters.

• The '*' pattern character matches zero or more of any character. For example, *@myco.com will search for all UserNames from the myco.com realm.
• The '?' pattern character matches any single character. For example, ?Smith@myco.com will search for all users in the myco.com realm with a last name of Smith and any first initial.

All cache entries matching the search criteria are displayed in the Query Results panel. The entries are displayed two at a time starting with the oldest for a maximum of 500 entries.

• Press Enter to display the next two entries.
• Repeat the process until all the entries have been displayed.

Service

In support of problem determination, the AST server logs messages to two destinations:

1. stderr: Logging to stderr is useful only when installing and configuring the AST and its associated clients. This allows the installer to observe the activity that is occurring in real time. To see the output of stderr, you must start the AST server in the foreground (enter ASTServer at the command line). Once all the WebSphere Everyplace Server components are installed and configured properly, the AST server will usually be run in the background and the log written to stderr is no longer of value.
2. xxxxxxxx.log: This file will be placed in the same directory as the cache data files. The default directory is /var/IBMEPS/AST. The log directory and the maximum log size are defined by configuration parameters in the AST.properties file. For more information on these configuration parameters, see Everyplace Active Session Table properties. Once the log file reaches its maximum log size (as defined in the max_log_file_size parameter), the AST server will start writing at the beginning of the log file and will overwrite the oldest message in the file.

   Each time the AST server starts, it opens a new log file; therefore, you can have more than one log file in the directory. The name of the log file is the decimal representation of the Universal Coordinate Time at which the log file was created. Use the GMT time and date to find the earliest and latest entries in the log. Each time the AST server is started it will automatically erase all but the five most recent log files from the directory.

Active Session Table log message format

Each entry in the Everyplace Active Session Table log contains the following information read from left to right:

Field description	Comments
GMT date, time and sequence number	The AST logs wrap; use the GMT date and time fields to find the earliest and latest entries.
Thread number
Function issuing the message	For IBM developer use only.
Severity	See Active Session Table log message severities for more information.
Category	See Active Session Table message categories for more information.
Message text and parameters

Active Session Table log message severities

The Active Session Table classifies log messages into seven severity categories, from most severe (1) to least severe (7). Each of the log levels has a separate and independent severity threshold. These thresholds are used to determine which messages will be logged. For example, setting the log threshold to 4 will log all messages in categories 1 through 4. In normal operation, the thresholds should not be set higher than the default of 2. Higher threshold levels are typically used when more information is needed to troubleshoot a problem.

The following table illustrates the AST message severities and their descriptions:

1 -	Terminal Errors	Show errors that cause the AST server to end (ABEND).
2 -	Procedural Errors	Show errors that prevent the AST server from completing a request.
3 -	Progress Messages	Record each request processed.
4 -	Warnings	Record events which may not be errors but could be the subsequent cause of an error.
5 -	Requests/Responses	Show the raw data of each request received and each response sent.
6 -	Trace Messages	Show the major events in the processing of each request.
7 -	Internal Program Flow	Shows the internal program flow details.

Active Session Table message categories

Everyplace Active Session Table messages are grouped into categories according to the type of problem or the type of the response to be taken by the customer.

The following message categories are defined for the Active session Table messages:

Category	Description
Configuration error	Indicates an error in the AST.properties file or the LDAP directory. The administrator should correct the statement or entry in error.
User error	Indicates that the operator entered an invalid search pattern at the operator's console. The operator should correct the error.
File error	Indicates that either the disk is full or the AST server does not have the necessary authority to perform the operation. The administrator should verify that there is sufficient disk space and that the AST server has the necessary authority for the operation that failed.
Security error	Indicates that an unauthorized host tried to connect to the AST server. All hosts, including hosts used to access operator functions, must be defined in an accept statement in either the AST.properties file or the LDAP directory.
System error	Indicates that system resources are running low. When this occurs, it is usually necessary to restart the AST server and, possibly, reboot the host system. It may be necessary to provide additional memory, increase the page file size, or limit the load on the Active Session Table.
Socket error	Indicates a problem in the network or the host system. If the message is "Could not bind a socket", then the administrator should verify the port keyword in the AST.properties file or the LDAP directory. Make sure that there are no other servers using the port number specified in the error message. The AST server uses three consecutive port numbers, starting with the port number specified in the AST.properties or LDAP directory. By default, these port numbers are 8017, 8018 and 8019.
Message error	Indicates a problem with an AST client, such as WebSEAL-Lite or the Everyplace Wireless Gateway. Report this problem to the appropriate IBM service representative.
HTTP error	May indicate that someone is trying to access the AST server without using the AST provided Web pages. If this problem persists, temporarily increase the logging level to level 3 (Progress messages) to determine who is attempting to access the AST server.
Program error	Indicates an error in the AST server code. Report this problem to the appropriate IBM service representative.