Sun Java System Access Manager 7.1 Performance Tuning and Troubleshooting Guide

Chapter 2 Access Manager Tuning Scripts

The Sun Java^TM System Access Manager 7.1 tuning scripts allow you to tune Access Manager and other components of your deployment, including Sun Java System Directory Server, the web container running Access Manager, and the operating system (OS) kernel and TCP/IP parameters.

This chapter includes the following topics:

Overview of the Access Manager Tuning Scripts

The Access Manager tuning scripts are non-interactive. To run a script, you first edit the parameters in the amtune-env configuration file to specify the tuning options you want to set for your specific environment. Then, you run either the amtune script, which calls other scripts as needed, or a specific script. For example, you might run only the amtune-identity script to tune only Access Manager.

The Access Manager tuning scripts and the amtune-env configuration file are installed in the following directory, depending on your platform:

Solaris systems: AccessManager-base/SUNWam/bin/amtune
Linux systems: AccessManager-base/identity/bin/amtune
Windows systems: javaes-install-directory\identity\bin\amtune

AccessManager-base is the Access Manager 7.1 base installation directory. The default base installation directory is /opt on Solaris systems and /opt/sun on Linux systems.

On Windows systems, the default value for javaes-install-directory is C:\Program Files\Sun\JavaES5.

The following table describes the tuning scripts that are available in the Access Manager 7.1 release. See also Tuning Scripts for Windows Systems.

Table 2–1 Access Manager Tuning Scripts


Script	Description
`amtune`	Wrapper script that calls other scripts based on values in the `amtune-env` file.
`amtune-identity`	Tunes the installed instance of Access Manager. Before you run the `amtune-identity` tuning script, it is recommended that you add the following property set to `false` to the `AMConfig.properties` file: `com.sun.identity.log.resolveHostName=false` A value of `false` minimizes the impact of resolving host names and thus can improve performance. (However, if you want the client machine's hostname to be printed in the `amAuthentication.access` log, set the value to `true`.) This script supports Web Server in JVM 64-bit mode. If Web Server 7.0 is the web container, it determines if Web Server 7.0 is running in 64-bit or 32-bit mode and then calculates the tuning parameters accordingly.
`amtune-os` Not available on Windows systems	Tunes the operating system kernel and TCP/IP parameters for both the Solaris OS and Linux OS. The script determines the OS type from the `uname -s` command. The `amtune-os`will not run if the wrapper `amtune` script is run in a global zone on Solaris 10 or higher.
`amtune-ws7`	Tunes the Sun Java System Web Server 7.0 web container. This script supports Web Server in JVM 64-bit mode. It determines if Web Server 7.0 is running in 64-bit or 32-bit mode and then calculates the tuning parameters accordingly.
`amtune-ws61`	Tunes the Sun Java System Web Server 6.1 2005Q4 SP5 web container.
`amtune-as8`	Tunes the Sun Java System Application Server Enterprise Edition 8.2 Web container.
`amtune-as7`	Tunes the Sun Java System Application Server 7 Web container.
`amtune-prepareDSTuner`	Generates the `amtune-directory` script, which you can use to tune the Directory Server that supports Access Manager. For more information, see Chapter 3, Directory Server Tuning.

Tuning Scripts for Windows Systems

Access Manager 7.1 includes tuning scripts for Microsoft Windows systems. Running the tuning scripts on a Windows system is similar to running the scripts on a Solaris system or Linux system, with these differences:

The Windows scripts are written in Perl and require Active Perl 5.8 to run.
A script to tune the Windows operating system is not available.
Before running a script, you must set the $BASEDIR parameter in the amtune-env.pl file to the Access Manager installation directory.
If you are tuning Directory Server, after running the amtune-prepareDSTuner.pl script, you must copy the amtune-utils.pl, amtune-directory.pl, and amtune-samplepasswordfile files to the Directory Server system.
Support for zones is not provided.

Tuning Modes

The Access Manager tuning scripts can run in the following modes, as determined by the AMTUNE_MODE parameter in the amtune-env file.

REVIEW mode (default). The scripts return tuning recommendations for an Access Manager deployment, but they do not make any actual changes to the environment.
CHANGE mode. The scripts make all of the tuning modifications that are defined in the amtune-env file, except for Directory Server. For information, see Chapter 3, Directory Server Tuning.

In either mode, the scripts return a list of tuning recommendations to the amtune debug log file and the terminal window. The location of the log file is determined by the com.iplanet.services.debug.directory parameter in the AMConfig.properties file. The default debug directory depends on your platform:

Solaris systems: /var/opt/SUNWam/debug
Linux and HP-UX systems: /var/opt/sun/identity/debug
Windows systems: javaes-install-directory\identity\debug where the default value for javaes-install-directory is C:\Program Files\Sun\JavaES5.

Caution –

Tuning is an iterative process that can vary for different deployments. The Access Manager tuning scripts try to apply the optimal tuning parameter settings. However, each deployment is unique and might require further customization to suit specific requirements.

Therefore, it is recommended that you first run a script in REVIEW mode and check the recommended changes in the amtune debug log file. Run the scripts in CHANGE mode only after you have reviewed the recommended tuning changes that will be applied to your deployment.

Running an Access Manager Tuning Script

To run a tuning script, use the following syntax:

amtune-script admin_password dirmanager_password [ as8_admin_password ]

The tuning script parameters are:

amtune-script is one of the tuning scripts: amtune, amtune-identity, amtune-os, amtune-ws61, amtune-as7, amtune-as8, or amtune-prepareDSTuner.
admin_password is the Access Manager Administrator password.
dirmanager_password is the Directory Manager (cn=Directory Manager) password.
as8_admin_password is the Administrator password that is required if you are tuning Application Server 8 (WEB_CONTAINER=AS8).

To run a tuning script:

Follow these basic steps to run an Access Manager Tuning script.

If you have not run the script in REVIEW mode, ensure that AMTUNE_MODE=REVIEW (which is the default value) in the amtune-env file.

Edit other parameters in the amtune-env file, depending on the components you want to tune and the requirements for your deployment:
- Access Manager Tuning Parameters
- Installation Environment Tuning Parameters
- Web Server 7.0 Tuning Parameters, if Web Server 7.0 is the web container
- Application Server 8 Tuning Parameters, if Application Server 8 is the web container
To tune the Directory Server that supports Access Manager, see Chapter 3, Directory Server Tuning.

In REVIEW mode, run either the amtune script or one of the component scripts.

Review the tuning recommendations in the debug log file. If needed, make changes to the amtune-env file based on this run.

If you are satisfied with the tuning recommendations from the REVIEW mode run, set AMTUNE_MODE=CHANGE in the amtune-env file.

In CHANGE mode, run either the amtune script or one of the component scripts.

For example, to tune the Solaris OS, run the amtune-os script, as follows:
# ./amtune-os admin_password dirmanager_password
Note –
In CHANGE mode, the amtune script might need to restart the web container and Access Manager. In some instances, amtune might also recommend a system restart.

Check the debug log file for the results of the run.

Consideration for the `com.iplanet.am.session.purgedelay` Property

This property specifies the number of minutes to delay the purge session operation. The value recommended by amtune is 0 or 1, depending upon the Access Manager version you're using. For clients such as Sun Java System Portal Server, a higher value may be needed. You must manually set the property after you run the amtune script:

In the AMConfig.properties file, set the property to the new value. For example:
```
com.iplanet.am.session.purgedelay=5
```
Restart the Access Manager web container for the new value to take effect.

Access Manager `amtune-env` File Parameters

The amtune-env file contains the parameters to define the tuning options for an Access Manager deployment, including:

For a description of the Directory Server parameters, see Chapter 3, Directory Server Tuning.

Access Manager Tuning Parameters

The following table describes the specific parameters for tuning Access Manager.

Table 2–2 Access Manager Tuning Parameters


Parameter	Description
`AMTUNE_MODE`	Sets the tuning mode to one of the following: REVIEW– The scripts return tuning recommendations for an Access Manager deployment but do not make any actual changes to the deployment environment. CHANGE– The scripts make all of the tuning modifications that you have defined in the `amtune-env` file, except for Directory Server. For more information, see Chapter 3, Directory Server Tuning. Default: REVIEW
`AMTUNE_TUNE_OS`	Tunes the operating system kernel and TCP/IP settings. Default: true
`AMTUNE_TUNE_DS`	Generates a script to tune the Directory Server that supports Access Manager. Default: true
`AMTUNE_TUNE_WEB_CONTAINER`	Tunes the Access Manager web container, which can be either Web Server or Application Server. Default: true
`AMTUNE_TUNE_IDENTITY`	Tunes the installed instance of Access Manager. Default: true
`AMTUNE_LOG_LEVEL`	Specifies the log level for the output of the run: `NONE` — No results will be logged or displayed. `TERM` — Display results on the terminal only. `FILE` — Display the results and log in the debug log file. Default: `FILE`
`AMTUNE_DEBUG_FILE_PREFIX`	Identifies the prefix for the `amtune` log file. If this parameter is set, all operations performed by the `amtune` scripts are logged. The location of the log file is determined by the `com.iplanet.services.debug.directory` parameter in the `AMConfig.properties` file. If Access Manager is not installed on the server, the debug log file is written to the directory when the tuning scripts exist. For example, if a Distributed Authentication UI server is deployed from a WAR file. Default: `amtune`
`AMTUNE_PCT_MEMORY_TO_USE`	Specifies the percent of available memory used by Access Manager. Currently, Access Manager can use a maximum of 4 GB, which is the per process address space limit for 32-bit applications. Access Manager requires a minimum of 256 MB RAM. When you set AMTUNE_PCT_MEMORY_TO_USE to 100, the maximum space allocated for Access Manager is the minimum between 4 GB and 100% of available RAM. When you set AMTUNE_PCT_MEMORY_TO_USE to 0, Access Manager is configured to use 256 MB RAM Default: 75 The following values are derived from this parameter setting: JVM memory usage - Heap sizes, NewSizes, PermSizes Thread pool sizes - Web Server RqThrottle, Authentication LDAP connection pool, SM LDAP connection pool, Notification thread pools Access Manager caches - SDK caches and session caches Maximum sizes - Maximum number of sessions and maximum number of cache entries AMConfig.properties File Settings Notification thread pool settings: `com.iplanet.am.notification.threadpool.size` `com.iplanet.am.notification.threadpool.threshold` SDK cache maximum size setting: `com.iplanet.am.sdk.cache.maxsize` Session settings: `com.iplanet.am.session.httpSession.enabled` `com.iplanet.am.session.maxSessions` `com.iplanet.am.session.invalidsessionmaxtime` `com.iplanet.am.session.purgedelay`
`AMTUNE_PER_THREAD_STACK_SIZE_IN_KB`	Sets the available stack space per thread in Java (Web container). The per thread stack size is used to tune various thread-related parameters in Access Manager and the Web container. Default: 128 KB Caution: Do not change this value unless absolutely necessary.
`AMTUNE_PER_THREAD_STACK_SIZE_IN_KB_64_BIT`	Sets the available stack space per thread in Java (Web container) when the script detects Web Server 7.0 is running as a 64-bit process. Default: 512 KB
`AMTUNE_MEM_MAX_HEAP_SIZE_RATIO`	Specifies the maximum heap size ratio that is used to calculate the maximum and minimum heap sizes. Default: `7/8` Note: If you are running the `amtune-ws7` script with 64-bit enabled and the system has a large memory, the script displays the current value of `AMTUNE_MEM_MAX_HEAP_SIZE_RATIO` and the maximum and minimum heap sizes calculated from this value. If these values are sufficient, you do not need to make any changes. However, in some situations, you might need to modify the value of `AMTUNE_MEM_MAX_HEAP_SIZE_RATIO`.
`AMTUNE_MIN_MEMORY_TO_USE_IN_MB` `AMTUNE_MAX_MEMORY_TO_USE_IN_MB`	Specifies the minimum and maximum memory in MB that should not be exceeded. Defaults: 512 and 3584 If Web Server 7.0 is running in a 64-bit process, the `AMTUNE_MAX_MEMORY_TO_USE_IN_MB` parameter is not used. It is recommended that you use the default values.
`AMTUNE_DONT_TOUCH_SESSION_PARAMETERS`	Specifies whether session time-out tuning using the next three parameters is enabled. To enable, set to false. Default: true
`AMTUNE_SESSION_MAX_SESSION_TIME_IN_MTS`	Sets the maximum session time in minutes. Default: 60 However, the default value might be different for your installation. If the session service is registered and customized at the any other level, the tuning will not apply. Setting this parameter to very high or very low values affects the number of active user sessions an Access Manager deployment can support, so this parameter is optional for tuning purposes. To use this parameter, AM_TUNE_DONT_TOUCH_SESSION_PARAMETERS must be set to false.
`AMTUNE_SESSION_MAX_IDLE_TIME_IN_MTS`	Sets the maximum idle time for a session in minutes. Default: 10 However, the default value might be different for your installation. If the Session service is registered and customized at the any other level, the tuning will not apply. Setting this parameter to very high or very low values affects the number of active user sessions an Access Manager deployment can support, so this parameter is optional for tuning purposes. To use this parameter, AM_TUNE_DONT_TOUCH_SESSION_PARAMETERS must be set to false.
`AMTUNE_SESSION_MAX_CACHING_TIME_IN_MTS`	Sets the maximum session cache time in minutes. Default: 2 However, the default value might be different for your installation. If the Session service is registered and customized at the any other level, the tuning will not apply. Setting this parameter to very high or very low values affects the number of active use sessions an Access Manager deployment can support, so this parameter is optional for tuning purposes. To use this parameter, `AM_TUNE_DONT_TOUCH_SESSION_PARAMETERS` must be set to false.

Installation Environment Tuning Parameters

The following table describes the Access Manager installation environment tuning parameters.

Note –

The OSTYPE, OSPLATFORM, and HWPLATFORM parameters are used to construct other parameters, so you should not need to change their values.

Table 2–3 Installation Environment Tuning Parameters


Parameter	Description
`HOSTNAME`	Specifies the host name of the system where Access Manager is deployed. If the host name for your environment cannot be obtained using the `hostname` command, comment the following line: `HOSTNAME=`’`/bin/hostname \| /bin/cut -f1 -d"."`’ Then, add a line setting the correct host name. For example: `HOSTNAME=myhost`
`DOMAINNAME`	Specifies the domain name of the system where Access Manager is deployed. If the domain name for your environment cannot be obtained using the `domainname` command, comment the following line: `DOMAINAME=’/bin/domainname’` Then, add a line setting the correct domain name. For example: `DOMAINNAME=example.com`
`IS_INSTALL_DIR`	Specifies the Access Manager installation directory. Default: blank. The tuning scripts determine the default Access Manager installation directory dynamically by the `pkginfo` or `rpm` command. If the `pkginfo` or `rpm` command fails, values are `/opt/SUNWam` on Solaris systems or `opt/sun/identity` on Linux systems. For an Access Manager WAR file deployment, the value should be blank. The `IS_INSTALL_DIR` and `IS_CONFIG_DIR` parameters are then replaced by WAR file deployment setup script.
`AMTUNE_BIN_DIR`	Specifies the location of the tuning scripts. Set this variable only if the tuning scripts are not installed in the default location. Otherwise, leave it blank. Default: `AccessManager-base/bin/amtune`
`WEB_CONTAINER`	Specifies the name of the Web container on which Access Manager is deployed: `WS7` — Web Server 7.0 `WS61` — Web Server 6.1 `AS8` — Application Server 8 `AS7` — Application Server 7 Default: `WS7` Any other value returns a validation error.
`CONTAINER_BASE_DIR`	Specifies the base directory for the Web container that is running Access Manager. If you installed the Web container in a non-default location, change this value before running `amtune`. Default values: Web Server 7.0: `/opt/SUNWwbsvr7` Web Server 6.1: `/opt/SUNWwbsvr` Application Server 7: `/var/opt/SUNWappserver7` Application Server 8 on Solaris systems `/var/opt/SUNWappserver` Application Server 8 on Linux systems `/var/opt/sun/appserver`
`WEB_CONTAINER_INSTANCE_NAME`	Specifies the instance name of the Access Manager web container. Typically, this value is the host name where Access Manager is deployed. If you have multiple instances for the Web container, this value might be different from the host name, and you must set it to the correct instance name. Defaults: Web Server 6.1 or Web Server 7.0: `hostname` (`${HOSTNAME}`) Application Server 7: `domains/server1` Application Server 8: `domains/domain1`
`IS_INSTANCE_NAME`	Specifies the Access Manager instance names. IS_INSTANCE_NAME is used to determine the properties file names for the Access Manager installation. Default: none You can deploy multiple instances of Access Manager on the same machine, but generally, there is one set of properties files for each Access Manager instance, and the instance name is appended to the file names. If there is only one instance of Access Manager on a machine, the instance name is not appended to the file name. For example, there might be a single instance of Access Manager running under the default instance of Web Server. If Access Manager is installed on a machine named `server.example.com`, typically the first instance of Web Server is `https-server.example.com`. The properties files for the first Access Manager instance will not have the instance name appended (for example, `AMConfig.properties`). Multiple Access Manager Instances Multiple instances will have different names. For example, if there are three instances of Web Server, the Web Server instances might be: `server.example.com-instance1` `server.example.com-instance2` `server.example.com-instance3` If three instances of Access Manager are deployed (one per web container instance), the primary properties file names for Access Manager (typically, `AMConfig.properties`) might be named as: `AMConfig-instance1.properties` `AMConfig-instance2.properties` `AMConfig-instance3.properties`
`IS_INSTANCE_NAME` (continued)	You can specify IS_INSTANCE_NAME=`instance1`. The `amtune` script resolves the properties file names in the following order: AMConfig-IS_INSTANCE_NAME AMConfig-WEB_CONTAINER_INSTANCE_NAME `AMConfig.properties` The script uses the first available properties file in the list. The `amadmin` utility should also point to the correct server name. Java option: `-Dserver.name=`IS_INSTANCE_NAME `amtune` automatically tries to associate the instance names with the Access Manager properties files using this parameter. Currently, only these files are based on this instance name: `AMConfig.properties` `serverconfig.xml`
`CONTAINER_INSTANCE_DIR`	Specifies the base directory for the Access Manager web container instance. If you have installed the web container in a non-default location, change this value before running `amtune`. Default values are: Web Server 6.1 or Web Server 7.0: `$CONTAINER_BASE_DIR/https-${WEB_CONTAINER_INSTANCE_NAME}` Application Server 7 or Application Server 8: `$CONTAINER_BASE_DIR/${WEB_CONTAINER_INSTANCE_NAME}`

Web Server 7.0 Tuning Parameters

The following table describes the tuning parameters that you can set when you are running Web Server 7.0 as the Access Manager web container.

Table 2–4 Web Server 7.0 Tuning Parameters


Parameter	Description
`WSADMIN`	Specifies the location of the `wsadmin` utility. Default: Solaris systems: `/opt/SUNWwbsvr7/bin/wadm` Linux systems: `/opt/sun/webserver7/bin/wadm`
`WSADMIN_USER`	Specifies the Web Server 7.0 administrator. Default: `admin`
`WSADMIN_PASSFILE`	Specifies the Web Server 7.0 temporary password file used by the `wsadmin` utility. Default: `/tmp/passfile`
`WSADMIN_HOST`	Specifies the Web Server 7.0 admin host name. Default: localhost (`$HOSTNAME`)
`WSADMIN_PORT`	Specifies the Web Server 7.0 admin port. Default: 8989
`WSADMIN_DIR`	Specifies the Web Server 7.0 installation directory.
`WSADMIN_SECURE`	Specifies whether `WSADMIN_PORT` is a secure port. `"--ssl=true"` indicates a secure port. `"--ssl=false"` indicates the port is not secure. Default: `"--ssl=true"`
`WSADMIN_CONFIG`	Specifies the Web Server 7.0 instance name. Default: `$WEB_CONTAINER_INSTANCE_NAME`
`WSADMIN_HTTPLISTENER`	Specifies the Web Server 7.0 HTTP listener name. Default: `http-listener-1`

Application Server 8 Tuning Parameters

The following table describes the tuning parameters that you can set when you are using Application Server 8 as the Access Manager web container.

Table 2–5 Application Server 8 Web Container Tuning Parameters


Parameter	Description
`ASADMIN`	Specifies the Application Server 8 `asadmin` utility location. Default values: Solaris systems: `/opt/SUNWappserver/appserver/bin/asadmin` Linux systems: `/opt/sun/appserver/bin/asadmin`
`ASADMIN_USER`	Specifies the Application Server 8 administrator user account. Default: `admin`
`ASADMIN_PASSFILE`	Specifies the temporary password file location used by the `asadmin` utility. The `amtune-as8` script creates this file and then deletes it after use. Default: `/tmp/passfile`
`ASADMIN_HOST`	Specifies the Application Server 8 `admin` host name. Default: `$HOSTNAME`
`ASADMIN_PORT`	Specifies the Application Server 8 `admin` port. Default: 4849
`ASADMIN_DIR`	Specifies the Application Server 8 installation directory.
`ASADMIN_SECURE`	Specifies whether the ASADMIN_PORT is secure: `"--secure"` specifies the port is secure. Blank specifies that the port is not secure. Default: `"--secure"`
`ASADMIN_TARGET`	Specifies whether this Application Server 8 installation is used exclusively for Access Manager and Portal Server. Default: `server`, indicating that Application Server 8 installation is exclusively used for Access Manager and Portal Server.
`ASADMIN_HTTPLISTENER`	Specifies the HTTP Application Server 8 listener name. Default: `http-listener-1`
`ASADMIN_INTERACTIVE`	Specifies whether Application Server 8 administrator operates interactively. Default: false Caution: Do not change this parameter.
`AMTUNE_WEB_CONTAINER_JAVA_POLICY`	Specifies whether Application Server 8 evaluates Java security descriptors, as specified in the `server.policy` file. Default: false Caution: Do not change this parameter. Evaluating Java security descriptors can add a significant performance overhead.