Sun Java System Access Manager 6 2005Q1 Performance Tuning Guide |
Chapter 2
Access Manager Tuning ScriptsThe Sun Java System Access Manager 6 2005Q1 tuning scripts allow you to tune Access Manager as well as other components of your deployment, including Directory Server, the web container running Access Manager, and the Solaris Operating System.
Topics in this chapter include:
Access Manager Tuning ScriptsThe 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 you want to perform for your specific environment. Then, you run either the amtune script, which calls other scripts as needed, or a specific script (for example, amtune-os to tune only the Solaris Operating System).
The Access Manager tuning scripts and amtune-env file are installed in the following directory, depending on your platform:
where AccessManager-base is the Access Manager 6 2005Q1 base installation directory. The default base installation directory is /opt on Solaris systems and /opt/sun on Linux systems.
Table 2-1 describes the tuning scripts available in the Access Manager 6 2005Q1 release.
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.
amtune-os
Tunes the Solaris Operating System kernel and TCP/IP parameters.
amtune-ws61
Tunes the Sun Java System Web Server 2005Q1 (6.1) web container.
amtune-as8
Tunes the Sun Java System Application Server Enterprise Edition 8 2004Q4 (8.1) web container.
amtune-as7
Tunes the Sun Java System Application Server 7 web container.
amtune-prepareDSTuner
Generates the amtune-directory script, which tunes the Directory Server that supports Access Manager. For information see Directory Server Tuning.
Tuning Modes
You can run the Access Manager tuning scripts in two 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 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. On Solaris systems, the default directory is /var/opt/SUNWam/debug.
Tuning Scripts Syntax
To run a tuning script, use the following syntax:
where:
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 Admin password.
dirmanager_password is the Directory Manager (cn=Directory Manager) password.
as8_admin_password is the admin password that is required if you are tuning Application Server 8 2004Q4 (WEB_CONTAINER = AS8).
To run a tuning script
- Log in as or become superuser (root).
- If you have not run the scripts in REVIEW mode, make sure that AMTUNE_MODE is set to 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:
- Application Server 8.x Tuning Parameters (if Application Server 8.x is the web container)
To tune the Directory Server that supports Access Manager, see Directory Server Tuning.
- In REVIEW mode, run either the amtune script, which calls other scripts based on values in the amtune-env file or one of the component scripts shown in Access Manager Tuning Scripts.
- Review the tuning recommendations in the debug log file, and 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 to CHANGE in the amtune-env file.
- In CHANGE mode, run either the amtune script, which calls other scripts based on values in the amtune-env file or one of the component scripts.
For example, to tune the Solaris OS, run amtune-os:
# ./amtune-os admin_password dirmanager_password
- Check the debug log file for the results of the run.
Access Manager amtune-env File ParametersThe amtune-env file contains the following parameters to define the tuning options for an Access Manager deployment:
For the Directory Server parameters, see Directory Server Tuning.
Access Manager Tuning Parameters
Table 2-2 describes the specific parameters for tuning Access Manager.
Table 2-2 Access Manager Tuning Parameters
Parameter
Description
AMTUNE_MODE
Sets the tuning mode:
- 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 Tuning.
Default: REVIEW
AMTUNE_TUNE_OS
Tunes the Solaris OS 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: Web Server or Application Server.
Default: true
AMTUNE_TUNE_IDENTITY
Tunes the installed instance of Access Manager.
Default: true
AMTUNE_DEBUG_FILE_PREFIX
Identifies the debug file-name prefix. If this is set to a non-empty value, then all of the operations performed by the amtune scripts are logged. The location of the log file is set in the com.iplanet.services.debug.directory parameter in the AMConfig.properties file.
If no value is specified, debugging information is not recorded and all output is sent to the /dev/null directory.
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 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.purgedelayAMTUNE_PER_THREAD_STACK_SIZE
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
Note: Do not change this value unless absolutely necessary.
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.
In order to use this parameter, you must ensure that AM_TUNE_DONT_TOUCH_SESSION_PARAMETERS is 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.
In order to use this parameter, you must ensure that AM_TUNE_DONT_TOUCH_SESSION_PARAMETERS is 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.
In order to use this parameter, you must ensure that AM_TUNE_DONT_TOUCH_SESSION_PARAMETERS is set to false.
Installation Environment Tuning Parameters
Application Server 8.x Tuning Parameters
Table 2-4 describes the tuning parameters that you can set when you are using Application Server 8.x as the Access Manager web container.
Directory Server TuningYou can run the tuning scripts to tune the Directory Server that supports Access Manager for your deployment. Access Manager should use an existing Directory Server (local or remote) in non-exclusive mode.
The amtune script and amtune-prepareDSTuner scripts do not actually tune Directory Server. However, you must run one of these scripts to generate the amtune-directory script, which you can then use to tune Directory Server.
Before making the tuning changes, the amtune-directory script stops and backs up Directory Server.
Table 2-5 describes the Directory Server tuning parameters in the amtune-env file.
To Tune Directory Server
- Log in as or become superuser (root).
- Make sure that the following parameter is set in the amtune-env file:
AMTUNE_TUNE_DS=true
- Run the amtune script or amtune-prepareDSTuner script. The script generates the following tar file:
/tmp/amtune-directory.tar
- Copy the amtune-directory.tar file to a temporary location on the server that is running Directory Server.
- Untar the amtune-directory.tar file in the temporary location.
- In the amtune-directory script, make REVIEW mode is set:
AMTUNE_MODE="REVIEW"
- Set these parameters, if you prefer values other than the default (amtune):
- DEBUG_FILE_PREFIX is a prefix that will be suffixed with the timestamp to specify the filename of the log file where the script writes the recommended tuning changes.
- DB_BACKUP_DIR_PREFIX is a prefix that will be suffixed with the timestamp to specify the name of the Directory Server backup directory.
- Run the amtune-directory script in REVIEW mode. For example:
# ./amtune-directory dirmanager_password
where dirmanager_password is the Directory Manager password.
- Review the recommended tuning settings for Directory Server in the debug log file. The script creates the log file automatically in the debug directory based on the com.iplanet.services.debug.directory attribute in the AMConfig.properties file. On Solaris systems, the default debug log file directory is:
/var/opt/SUNWam/debugCaution: If you are working with a production Directory Server or a Directory Server that has not been adequately backed up (both the data and the configuration), it is recommended that you do not run the amtune-directory script in CHANGE mode to apply to the tuning changes. Review the tuning recommendations from REVIEW mode and apply the changes manually, if they meet your deployment needs.
To have the amtune-directory script make the tuning changes, see the following steps.
CHANGE Mode
If you are working with a pilot or prototype Directory Server and you are sure you want to apply the tuning changes, follow these steps:
- Back up both your Directory Server data and configuration.
- Set the following parameter in the amtune-directory script:
AMTUNE_MODE="CHANGE"
- Run the amtune-directory script in CHANGE mode. For example:
# ./amtune-directory dirmanager_password
where dirmanager_password is the Directory Manager password.
- Check the debug log file for the results of the run.