Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Access Manager 6 2005Q1 Performance Tuning Guide 

Chapter 2
Access Manager Tuning Scripts

The 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 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 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:

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.

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, use CHANGE mode only after you have reviewed and understand the tuning changes that will be applied to your deployment.

Tuning Scripts Syntax

To run a tuning script, use the following syntax:

amtune-script admin_password dirmanager_password [ as8_admin_password ]

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

  1. Log in as or become superuser (root).
  2. 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.
  3. Edit other parameters in the amtune-env file, depending on the components you want to tune:
  4. 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.
  5. Review the tuning recommendations in the debug log file, and if needed, make changes to the amtune-env file based on this run.
  6. If you are satisfied with the tuning recommendations from the REVIEW mode run, set AMTUNE_MODE to CHANGE in the amtune-env file.
  7. 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.

    8. For example, to tune the Solaris OS, run amtune-os:

    # ./amtune-os admin_password dirmanager_password

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

    9. Note

    In CHANGE mode, amtune might need to restart the web container and Access Manager. Also, amtune might recommend a system restart.

Access Manager amtune-env File Parameters

The 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.purgedelay

AMTUNE_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

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_CONFIG_DIR

Specifies the Access Manager configuration directory.

Default: /etc/opt/SUNWam/config.

Note: Do not change this parameter.

WEB_CONTAINER

Specifies the name of the web container on which Access Manager is deployed, as follows:

  • WS61 specifies Web Server 6.1 as the web container.
  • AS8 specifies Application Server 8.x as the web container
  • AS7 specifies Application Server 7.x as the web container.

Any other value returns a validation error.

Default: AS8

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.

Defaults:

  • Web Server 6.1 or later: /opt/SUNWwbsvr
  • Application Server 7.x: /var/opt/SUNWappserver7
  • Application Server 8.x: /var/opt/SUNWappserver

WEB_CONTAINER_INSTANCE_NAME

Specifies the instance name of the Access Manager web container.

Defaults:

  • Web Server 6.1 or later: ${HOSTNAME}
  • Application Server 7.x: domains/server1
  • Application Server 8.x: domains/domain1

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.

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

Multiple instances of Access Manager can be deployed in the same machine, but generally, there is one set of properties files per 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 web container.

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 Instances

Multiple instances will have different names. For example, if there ate three instances of Web Server, the Web Server instances might be server.example.com-instance1, server.example.com-instance2, and 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:

  1. AMConfig-IS_INSTANCE_NAME
  2. AMConfig-WEB_CONTAINER_INSTANCE_NAME
  3. 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.

Defaults:

  • Web Server 6.1 or later:
    $CONTAINER_BASE_DIR/https-${WEB_CONTAINER_INSTANCE_NAME}
  • Application Server 7.0 or later:
    $CONTAINER_BASE_DIR/${WEB_CONTAINER_INSTANCE_NAME}

 

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.

Table 2-4  Application Server 8.x Web Container Tuning Parameters

Parameter

Description

ASADMIN

Specifies the Application Server 8.x admin utility location.

Default: $CONTAINER_BASE_DIR/bin/asadmin

ASADMIN_USER

Specifies the Application Server 8.x 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.x admin host name.

Default: localhost

ASADMIN_PORT

Specifies the Application Server 8.x admin port.

Default: 4848

Note: Application Server Enterprise Edition might use port 4949.

ASADMIN_SECURE

Specifies whether the ASADMIN_PORT is secure”

  • --secure specifies that ASADMIN_PORT is secure.
  • Blank specifies that Application Server 8.xASADMIN_PORT is not secure.

Default: ""

ASADMIN_TARGET

Specifies whether this Application Server 8.x installation is exclusively used for Access Manager/Portal Server.

Default: server, indicating that Application Server 8.x installation is exclusively used for Access Manager/Portal Server

ASADMIN_INTERACTIVE

Specifies whether Application Server 8.x admin operates interactively.

Default: false

Caution: Do not change this parameter.

AMTUNE_WEB_CONTAINER_JAVA_POLICY

Specifies whether Application Server 8.x 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.

Directory Server Tuning

You 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.

Caution

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.

After you run the amtune-directory script in REVIEW mode, review the tuning recommendations and apply them manually, if they meet your deployment needs.

Also, make sure you back up both your Directory Server data and configuration before you make any changes.

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.

Table 2-5  Directory Server Tuning Parameters 

Parameter

Description

AMTUNE_TUNE_DS

Generates a script to tune the Directory Server that supports Access Manager.

Default: true

DIRMGR_UID

Specifies the user ID of the Directory Manager. If your deployment uses a user ID other than the default value (cn=Directory Manager), you must set this parameter with that value.

Default: cn=Directory Manager

RAM_DISK

Specifies the location of the RAM disk.

Default: /tmp

DEFAULT_ORG_PEOPLE_CONTAINER

Specifies the Access Manager instance’s default people container location below the top-level organization.

This value is used to tune the search base for the LDAP authentication service. The search scope is also modified to the object level and the default search scope is in the subtree level. This parameter is useful when there are no suborganizations in the default organization. If no value is specified, the tuning is skipped.

Default: none

 

To Tune Directory Server

  1. Log in as or become superuser (root).
  2. Make sure that the following parameter is set in the amtune-env file:

    3. AMTUNE_TUNE_DS=true

  3. Run the amtune script or amtune-prepareDSTuner script. The script generates the following tar file:

    4. /tmp/amtune-directory.tar

  4. Copy the amtune-directory.tar file to a temporary location on the server that is running Directory Server.
  5. Untar the amtune-directory.tar file in the temporary location.
  6. In the amtune-directory script, make REVIEW mode is set:

    7. AMTUNE_MODE="REVIEW"

  7. 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.
  8. Run the amtune-directory script in REVIEW mode. For example:

    9. # ./amtune-directory dirmanager_password

    where dirmanager_password is the Directory Manager password.

  9. 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/debug

    10. Caution: 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:

  1. Back up both your Directory Server data and configuration.
  2. Set the following parameter in the amtune-directory script:

    3. AMTUNE_MODE="CHANGE"

  3. Run the amtune-directory script in CHANGE mode. For example:

    4. # ./amtune-directory dirmanager_password

    where dirmanager_password is the Directory Manager password.

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


Previous      Contents      Index      Next     

Part No: 817-7646-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.