Chapter 2 Identity Server Tuning Scripts

This chapter describes the amtune tuning scripts for Sun Java™ System Identity Server 2004Q2 and contains the following sections:

The amtune Scripts

The amtune-env Configuration File Parameters



Note	For the 2004Q2 release, the amtune scripts are only fully functional on Solaris. The Linux and x86 versions of these scripts will function, but they are not as mature on these platforms.

The amtune Scripts

The amtune scripts allow you to tune the performance of Identity Server, as well as optimize the performance settings for various components of your Identity Server deployment.

The amtune scripts are non-interactive, meaning that before you run a script, you must edit the parameters in the amtune-env configuration file to specify the tuning you want to perform for your specific environment.

To edit tuning enhancements, modify the parameters in the amtune-env file and run the amtune script in the following format, where admin_password is the Identity Server Admin Client Utility password, and dirmanager_password is the Directory Manager (cn=Directory Manager) password:

If you wish to tune specific components, you can use the component scripts provided in the /amtune directory. The component scripts will use the relevant parameters in the amtune-env file. The available component scripts are:

amntune-as7 - This script tunes the Sun Java System Application Server 7 web container.

amtune-identity - This script tunes the installed instance of Identity Server.

amtune-os - This script tunes the Solaris operating system kernel and TCP/IP parameters.

amtune-prepareDSTuner - This script tunes the Directory Server instance that supports Identity Server. Tuning Directory Server requires extra levels of confirmation. Identity Server should use an existing Directory Server in non-exclusive mode. Regardless of where the Directory Server is installed (locally or remotely), Directory Server is not tuned when you run amtune. When you run the script, it creates a tar file named /tmp/amtune-directory.tar. By default, the extracted files will be placed in /tmp directory. You need to extract this file in the machine on which Directory Server is running on your system and then run the amtune-directory script.

amtune-ws61 - This script tunes the Sun Java System Web Server 6.1 web container.

For example, if you wish to tune the operating system, use the following format:

The amtune scripts and the associated amtune-env file can be found in the following directories:



Note	Throughout the rest of this chapter, only the Solaris directory information will be given. Please note that the directory structure for Linux is different.For more information, please see About This Guide.

amtune

The amtune script has two generation modes; one to generate a set of tuning suggestions for an Identity Server deployment and one to implement your tuning specifications. The following modes that can be specified are defined in the AMTUNE_MODE parameter in the amtune-env file:

Review Mode - When the Review mode is specified, the amtune script returns tuning suggestions, but does not make any changes to the deployment environment.

Change Mode - When the Change mode is specified amtune will make all of the tuning modifications that you have defined in amtune-env, with the exception of Directory Server tuning.



Note	Use caution when using the Change mode. After running the script, the web container will need to be restarted, and the amtune may recommend a system restart. Tuning is a very iterative process and can vary between different deployments. While the amtune utility tries to apply the best possible tuning parameters, every deployment is unique and might require further customization to suit the requirements for the deployment. It is important for the Identity Server administrator to understand, and review each of the tuning applied to the deployment.

In either mode, a list of tuning recommendations and current values are written to the amtune output file and displayed in the terminal window. The location of this file is based on the AMTUNE_DEBUG_FILE_PREFIX parameter in amtune-env.

The amtune-env Configuration File Parameters

The amtune-env configuration file contains parameters to define the tuning options for your Identity Server deployment. This section describes the amtune-env parameters.

amtune Parameters

AMTUNE_MODE

review - When the Review mode is specified, the amtune script returns tuning suggestions, but does not make any changes to the deployment environment.

change - When the Change mode is specified, amtune will make all of the tuning modifications that you have defined in amtune-env, with the exception of Directory Server tuning.

AMTUNE_MODE_OS

AMTUNE_MODE_DS

This parameter tunes the Directory Server instance that supports Identity Server. Tuning Directory Server requires extra levels of confirmation. Identity Server should use an existing Directory Server in non-exclusive mode. Regardless of where the Directory Server is installed (locally or remotely), Directory Server is not tuned when you run amtune. When you run the script, it creates a tar file named /tmp/amtune-directory.tar. By default, the extracted files will be placed in /tmp directory. You need to extract this file in the machine on which Directory Server is running on your system and then run the amtune-directory script.

AMTUNE_MODE_WEB_CONTAINER

AMTUNE_MODE_IDENTITY

AMTUNE_DEBUG_FILE_PREFIX

This parameter defines the debug filename 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 AMConfig.properties.

If no value is specified, debugging information is not recorded and all output is sent to the /dev/null directory.

AMTUNE_PCT_MEMORY_TO_USE

This parameter defines the amount of available memory used by Identity Server. Currently, Identity Server requires a minimum of 512MB of RAM and can use a maximum of 4 GB, which is the per-process address space limit for 32-bit applications. If you set this parameter to 0 (the lowest value), Identity Server is configured to use 512MB. Conversely, if you set this parameter to 100, the maximum space allowed for Identity Server would be the minimum amount between 4GB and 100% of the system’s available RAM. The following values are some of the files tuned based on this setting (for a complete list, see the debug file):

Web container values

heap size settings

<JVMOPTIONS>-XX:PermSize and <JVMOPTIONS>-XX:MaxNewSize

<JVMPTIONS>-XX:Permsize and <JVMOPTIONS>-XX:MaxPermSize

Identity Server AMConfig.properties values

com.iplanet.am.notification.threadpool.size

com.iplanet.am.notification.threadpool.threshold

com.iplanet.am.sdk.cache.maxsize

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

This parameter sets the available stack spaces per thread. The per thread stack size is used to tune various thread-related parameters in Identity Server and the web container. The default value is 128KB. This value should not be changed.

AMTUNE_SESSION_MAX_SESSION_TIME_IN_MTS

This parameter sets the maximum session time in minutes. The default is 60, however this value may 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 Identity Server 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

This parameter sets the maximum idle time for a session in minutes. The default is 10, however this value may 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 Identity Server 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

This parameter sets the maximum session cache time in minutes. The default is 2, however this value may 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 Identity Server 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 Parameters

HOSTNAME

This parameter defines the host name of the system on which Identity Server is deployed. If the host name for your environment cannot be obtained using the hostname command, comment the following line:

DOMAINNAME

This parameter defines the domain name of the system on which Identity Server is deployed. If the domain name for your environment cannot be obtained using the domainname command, comment the following line:

IS_CONFIG_DIR

This parameter defines the configuration directory for Identity Server. The default location is IdentityServer_base/SUNWam/config. Do not change this parameter.

WEB_CONTAINER

This parameter defines the name of the web container on which Identity Server is deployed. It accepts the following values:

WS61- specifies Web Server 6.1 as the web container.

AS7 - specifies Application Server 7 as the web container.

CONTAINER_BASE_DIR

This parameter defines the base directory for the web container on which Identity Server is deployed. If you installed the web container in a non-default location, change this value before running amtune.

WEB_CONTAINER_INSTANCE_NAME

This parameter defines the instance of the name of the web container where Identity Server is deployed.

For Java System Web Server web container, the instance name is normally the host name of the Identity Server. If the instance name is different from the hostname, you will need to specify the correct instance name here. For example:

If the Web Server installation location is other than the typical value, for example, /opt/SUNWwbsrvr/https-instance1, the instance name would be instance1.


Note	You will need to drop the "https-" from the directory name of the install location of JSWS.

For the Application Server web container, the instance name is normally server1. For example:

In this case, the instance name is the last part of the install location and is server1.

If the Application Server install location is other than the typical value, lets say, if the install location is /var/opt/SUNWappserver7/domains/domain1/server-identity-ssl, the instance name would be server-identity-ssl:



Note	You will need to specify the complete instance name for Application Server, typically, the leaf directory in the install path.

IS_INSTANCE_NAME

This parameter is used in determining the property filenames for the Identity Server install. Multiple instances of Identity Server could be deployed in the same machine, but generally, there will be one set of property files per Identity Server instance and the instance name will be appended to the file names.

If there is only one instance of Identity Server on a machine, then the instance name will not be appended to the file names.

For example, there may be a single instance of Identity Sever running under the default instance of Web Server:

If your Identity Server is installed on a machine named server.example.com, typically your first instance of Web Server will be https-server.example.com. The property files for the first Identity Server instance will not have the instance name appended (for example, AMConfig.properties).

In the case of multiple instances, there will be different names. For example, there may be three instances of Web Server. The Web Server instances could be server.example.com-instance1, server.example.com-instance2, server.example.com-instance3. If three instances of Identity Server are deployed (one per container instance), then the primary property file names for Identity Server (typically, AMConfig.properties) may look like the following:

AMConfig-instance1.properties

AMConfig-instance2.properties

AMConfig-instance3.properties.

You can specify IS_INSTANCE_NAME=instance1. amtune will resolve the property file names in the following order:

AMConfig-IS_INSTANCE_NAME

AMConfig-WEB_CONTAINER_INSTANCE_NAME

AMConfig.properties


Note	The web container and the amadmin tool should point to the correct instance of Identity Server as well.

For web containers, you will have to explicitly specify the instance name in the server.xml configuration file of the web container instance configuration as well. For example:

CONTAINER_INSTANCE_DIR


Note	amadmin tool should also point to the correct server name (java option -Dserver.name=instance1).

This parameter defines the base directory for the container instance to which Identity Server is deployed. If you have installed the web container in a non-default location, change this value before running amtune.

Directory Server Parameters

DIRMGR_UID

This parameter defines the user ID of the Directory Manager. If you change the user ID from the default value (cn=Directory Manager), then you must change the value of this parameter.

DEFALUT_ORG_PEOPLE_CONTAINER

This parameter defines the Identity Server 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 values are specified, the tuning is skipped.

Previous Contents Index Next
Sun Java System Identity Server 2004Q2 Administration Guide