test

Sun OpenSSO Enterprise 8.0 Performance Tuning Guide

Appendix A amtune-env.properties Reference

This appendix lists properties in the amtune-env.properties you must modify and verify before running the amtune tool. After you have modified the file to suit your deployment, you can run the amtune tool.

See Using the amtune Toolfor usage details.

Tuning Modes

AMTUNE_MODE

Description:

Based on this setting, the amtune tool will behave differently.

Required:

Yes

Sample Values:
REVIEW

Suggests tuning recommendations only. In this mode, the amtune tool suggests tuning recommendations, but will not make any changes to the deployment environment.

CHANGE

Implements tuning recommendations. In this mode, amtune implements all of the tuning recommendations that you have defined in here, except for Sun Directory Server. See the note below for Sun Directory Server tuning.

Default Value:

None

Additional Information:

Use extreme caution while using CHANGE mode. In CHANGE mode, the amtune tool may restart the web container on which OpenSSO is deployed. The amtune tool may also recommend a system restart when the operating systems kernel parameters are changed.

For Operating System kernel and TCP parameter tuning, the amtune tool tunes the operating system parameters only on Solaris and Linux. The amtune tool does not tune the operating system parameters on AIX, Windows, MacOS or BSD variants.

Sun Directory Server tuning requires extra levels of confirmation. The amtune tool assumes that OpenSSO Enterprise will use an existing Sun Directory Server in non-exclusive mode, although other applications may use Directory Server. If the Directory Server is installed on a remote machine, it will not be tuned automatically. If the amtune tool detects that the Directory server is installed on a remote machine, it creates an amtune.zip file for tuning the remote Directory Server. For more information, see To Tune a Remote Sun Directory Server in this document.

To selectively tune various components, see the section AMTUNE_TUNE_* section of this document.

On Windows, use a forward slash ( / ) for file separators. Example: c:/sun/webserver7

For tuning multiple data stores, execute amtune multiple times using different values for DS_* parameters and DIRMGR_PASSWORD.

Log Level Options

AMTUNE_LOG_LEVEL

Description:

Controls the logging of configuration data (calculated tuning values).

Required:

Yes

Sample Values:
TERM

The output is only displayed on the terminal.

FILE

The output is displayed on both terminal and in amtune-config.<time stamp>.log file.

Default Value:

None

Additional Information:

Check the <TOOLS_DIR>/<OPENSSO_URI>/logs/amtune-config.<time stamp>.log file for the tuning parameters and their recommended values from each run.

Components to be Tuned

AMTUNE_TUNE_*

Description:

Specifies components to be tuned by amtune.

These settings work in conjunction with the AMTUNE_MODE parameter setting. You can review or change recommended tunings of any set of these components.

Required:

Yes

Properties Details
AMTUNE_TUNE_OS=

Only Solaris and Linux kernel and TCP parameters are supported for tuning.

AMTUNE_TUNE_DS=

Only Sun Directory Server is supported for tuning.

AMTUNE_TUNE_WEB_CONTAINER=

Only Sun Application Server 9.1, GlassFish v2, or Sun Web Server 7 are supported for tuning.

AMTUNE_TUNE_OPENSSO=

OpenSSO tuning.

Other Containers

$WEB_CONTAINER and $CONTAINER_INSTANCE_DIR values do not have to be filled in.

Sample Values:

True or False

Default Value:

None

Additional Information

Even if only AMTUNE_TUNE_OPENSSO is set to true, if Web Server 7.0 or Application Server 9.1 is the web container for OpenSSO, you must specify values for the following:

  • $WEB_CONTAINER

  • $CONTAINER_ INSTANCE_DIR

  • $WSADMIN_* or $ASADMIN_*

The amtune tool determines whether these containers are running in 32- or 64-bit JRE mode. The amtune tool restarts the server to check its JRE mode and to determine how much heap size is available for setting OpenSSO cache and session entries. For other web containers, the amtune tool supports only 32-bit JRE. For other web containers, set $AMTUNE_TUNE_WEB_CONTAINER to false. Also note the following:

  • $WEB_CONTAINER must be set to other.

  • $CONTAINER_INSTANCE_DIR should be left blank.

  • OpenSSO parameters will be tuned if the value for AMTUNE_TUNE_OPENSSO is set to true.

By default, the amtune tool runs based on the assumption that the following amount of memory (megabytes) is available for tuning OpenSSO when the web container (both Sun and non-Sun) is running with 32-bit JRE:

  • (Sparc/x86/AIX) AMTUNE_MAX_MEMORY_TO_USE_IN_MB_SOLARIS=3584

  • (Linux) AMTUNE_MAX_MEMORY_TO_USE_IN_MB_X86=2341

  • (Windows)AMTUNE_MAX_MEMORY_TO_USE_IN_MB_DEFAULT=1536

The amtune tool also tunes OpenSSO Enterprise when it is deployed on WebSphere 6.1 and 7, and on AIX, although it does not tune AIX system parameters or WebSphere container parameters.

Web Container Options

WEB_CONTAINER

Description:

Specifies OpenSSO web container name and version.

Required:

Yes

Sample Values:
Sun Web Server 7

WS7

Sun Application Server 9.1 or GlassFish v2

AS91

Other Web Containers

other

Default Value:

None

Additional Information:

For Web Server 7 and Application Server 9.1, the amtune tool tunes JRE heap and per-thread stack sizes, JVM garbage collection algorithms, container worker or acceptor thread, and queue sizes.

For other web containers, the amtune tool does not change JVM or container-specific parameters.

$WEB_CONTAINER must be set to other. It is impossible to detect whether a null value is mistakenly set for Web Server 7 or Application Server 9.1, or is intentionally set for other web containers.

CONTAINER_INSTANCE_DIR

Description:

Specifies the OpenSSO web container instance directory.

Required:

If the you are using Sun Web Server 7 or Sun application Server 9.1, then this parameter is required.

Sample Values:
Sun Web Server 7

/sun/webserver7/https-localhost

Sun Application Server 9.1

/sun/appserver/domains/domain1

Default Value:

None

Additional Information:

If you have installed Sun Web Server or Sun Application Server in a non-default location, then change this value before running amtune.

On Windows, if a directory name has spaces, then use a short form such as E:/PROGRA~1/GLASSF~1.

Sun Web Server Settings

The following parameters are required for tuning JVM options and container parameters of Sun Web Server 7.0.

WSADMIN_*

Set the following parameters when $WEB_CONTAINER= WS7.

WSADMIN_DIR

Description:

Specifies Sun Web Server 7 installation location.

Required:

Yes, when $WEB_CONTAINER=WS7

Sample Values:
Solaris

/opt/SUNWwbsvr7/bin

Linux

/opt/sun/webserver7/bin

Windows

E:/Progra~1/webserver7/bin

Default Value:

None

WSADMIN_USER

Description:

Specifies Sun Web Server administrator.

Required:

Yes

Sample Values:

admin ( Sun Web Server default)

Default Value:

None

WSADMIN_HOST

Description:

Specifies Sun Web Server administrative host name.

Required:

Yes

Sample Values:

localhost

Default Value:

None

WSADMIN_PORT

Description:

Specifies Sun Web Server 7 administration port.

Required:

Yes

Sample Values:

8888

8989 (Sun Web Server default)

Default Value:

None

Additional Information:

If this port is a secure port, set the $WSADMIN_SECURE value to --ssl=true.

If this port is not a secure port, set the $WSADMIN_SECURE value to --ssl=false.

WSADMIN_SECURE

Description:

Flag to indicate whether or not $WSADMIN_PORT is in SSL mode.

Required:

Yes

Sample Values:
If the port is a secure port

--ssl=true

If the port is not a secure port

--ssl=false

Default Value:

None

WSADMIN_CONFIG

Description:

Specifies Sun Web Server instance name.

Required:

Yes

Sample Values:

hostname.domain.com

This sample value is the config-name for the default instance https-hostname.domain.com

Default Value:

None

Additional Information

If you have non-default config-name instances, for example https-test1, enter its config-name test1 here.

WSADMIN_HTTPLISTENER

Description:

Specifies HTTP listener name.

Required:

Yes

Sample Values:

http-listener-1 (Sun Web Server default)

Default Value:

None

Sun Application Server 9.1 and GlassFish v2 Settings

These following parameters are required for tuning JVM options and container parameters of Sun Application Server 9.1 and GlassFish v2.

ASADMIN_*

Set these parameters when $WEB_CONTAINER= AS91.

ASADMIN_DIR

Description:

Specifies Sun Application Server 9.1 or GlassFish v2 installation location.

Required:

Yes

Sample Values:
Solaris

/opt/SUNWappserver/bin

Linux

/opt/sun/appserver/bin

Windows

E:/Progra~1/glassfish-v2/bin

Default Value:

None

ASADMIN_USER

Description:

Specifies Sun Application Server 9.1 or GlassFish v2 administrator.

Required:

Yes

Sample Values:

admin (Sun Application Server or GlassFish default)

Default Value:

None

ASADMIN_HOST

Description:

Specifies Sun Application Server or GlassFish administrative host name.

Required:

Yes

Sample Values:

localhost

Default Value:

None

ASADMIN_PORT

Description:

Specifies Sun Application Server or GlassFish administrative port.

Required:

Yes

Sample Values:

4848

4849 (Sun Application Server or GlassFish default)

Default Value:

None

Additional Information:

If this port is a secure port, set $ASADMIN_SECURE value to --secure.

If this port is not a secure port, leave the $ASADMIN_SECURE value blank.

ASADMIN_SECURE

Description:

Flag that indicates whether or not Sun Application Server or GlassFish is in SSL mode.

Required:

Yes

Sample Values:
If the port is a secure port

--secure (Application Server 9.1 or GlassFish v2 default)

If the port is not a secure port

Leave this value blank.

Default Value:

None

ASADMIN_TARGET

Description:

This value is usually set to server with the assumption that this Application Server 9.1 or GlassFish v2 installation is used exclusively for OpenSSO Enterprise

Required:

Yes

Sample Values:

server (Default in Application Server 9.1 or GlassFish v2)

Default Value:

None

ASADMIN_HTTPLISTENER

Description:

Specifies Sun Application Server HTTP listener name.

Required:

Yes

Sample Values:

http-listener-1 (Default in Sun Application Server 9.1 or GlassFish v2)

Default Value:

None

AMTUNE_WEB_CONTAINER_JAVA_POLICY

Description:

Specifies whether Sun Application Server or GlassFish evaluates java security policies listed in the Application Server server.policy file.

Required:

Yes

Sample Values:

false (Application Server or GlassFish default)

Default Value:

false

Additional Information:

Do not modify this parameter setting unless it is a unique deployment requirement. Evaluating Java security policies can add a significant performance overhead.

OpenSSO Enterprise Settings

SSOADM_LOCATION

Description:

Specifies the directory where the ssoadm command-line interface is located.

Required:

Yes

Sample Values:

<TOOLS_DIR>/<OPENSSO_URI>/bin

where <TOOLS_DIR> is the directory in which amtune.zip is unzipped, and <OPENSSO_URI> is the deployment URI of OpenSSO.

Default Value:

<TOOLS_DIR>/<OPENSSO_URI>/bin

OPENSSOADMIN_USER

Description:

Specifies administrator of OpenSSO 8.x.

Required:

Yes,

Sample Values:

amadmin (Default in OpenSSO)

Default Value:

None

OPENSSOSERVER_URL

Description:

Specifies OpenSSO URL.

Required:

Yes

Sample Values:

http://<HOST_NAME>:<PORT>/<OPENSSO_URI> (OpenSSO Enterprise default)

Default Value:

None

REALM_NAME

Description:

Realm names for which user data store LDAP connection pool need to be modified.

Use the pipe ( | ) character as a delimiter for multiple realms.

Required:

Yes

Sample Values:
Top_Level_Realm

/

Top_Level_Realm and its sub-realm, subrealm1

/|subrealm1

Top_Level_Realm and two sub-realms

/|subrealm1|subrealm2

Default Value:

None

Additional Information:

For all the data stores under each realm, minimum and maximum LDAP connection pool sizes will be tuned.

Sun Directory Server Settings

The parameters in this section are for tuning a Sun Directory Server instance where a user management or service management and configuration data store is installed. When the Directory Server instance is on a remote computer system, after amtune.zip is copied over and unzipped, amtune validates parameter values only on that remote computer system.

DS_HOST

Description:

Specifies Sun Directory Server fully qualified domain name (FQDN ).

Required:

Yes

Sample Values:

hostname.domain.com

Default Value:

None

Enter the official host name; do not enter an alias.

DS_PORT

Description:

Specifies Sun Directory Server port.

Required:

Yes

Default Value:

None

ROOT_SUFFIX

Description:

Specifies the root suffix of the organization.

Required:

Yes

Default Value:

None

DS_INSTANCE_DIR

Description:

Specifies Sun Directory Server instance location

Required:

Yes

Default Value:

None

Additional Information:

Use a forward slash (/) for file separators on Windows Systems.

DS_TOOLS_DIR

Description:

Sun Directory Server dsadm/dsconf tools bin directory.

Required:

Yes

Default Value:

None

Additional Information:

Use a forward slash (/) for file separators on Windows Systems.

DS_VERSION

Description:

Sun Directory Server version.

Required:

Yes

Sample Values:

5.2 or 6.3

Default Value:

None

Additional Information:

Sun Directory Server 6.2 is not supported for tuning due to its data corruption issues.

DIRMGR_BIND_DN

Description:

Directory Manager BIND DN for $DS_INSTANCE_DIR.

Required:

Yes

Sample Values:

cn=Directory Manager (Directory Server default)

Default Value:

None

Special Performance Settings

The following parameters mainly are used internally by amtune.

Caution – Caution –

Do not modify these parameters unless tests show significant improvement in performance.

AMTUNE_PCT_MEMORY_TO_USE

Description:

Specifies a percentage value how much of the machine's available memory will be used by OpenSSO Enterprise.

Required:

Yes

Sample Values:

0 to 100

Default Value:

75

Additional Information:

Do not modify this percentage unless tests show significant improvement in performance.

OpenSSO Enterprise currently recommends at least 1 GB of RAM in deployment. OpenSSO can use a maximum of 4GB for 32-bit JRE. This is the per-process address space limit for 32-bit applications.

When you set AMTUNE_PCT_MEMORY_TO_USE to 100, the maximum space allocated for OpenSSO is the lesser of 4GB and 100% of available RAM for 32-bit JRE.

When you set AMTUNE_PCT_MEMORY_TO_USE to 0, OpenSSO is configured to use 256MB RAM.

This value is the driving force in tuning OpenSSO. The following values are derived from this setting:

JVM memory use

Heap and new generation sizes.

Thread pool sizes

Web Server thread pool and OpenSSO Enterprise authentication, user and service/configuration data store LDAP connection pools and session notification thread pool.

Session entries

Maximum number of session entries.

For 64-bit JRE, the amtune tool limits the initial heap size (-Xms) to 12 GB for Web Server 7 and Application Server 9.1/Glassfish v2, although it can be increased manually to a bigger heap size, if the Solaris operating system has at least twice as much virtual memory (swap space) as the desired initial JRE heap size. There is no limit for the maximum heap size (-Xmx).

Using 64-bit JRE, the user session cache size and number of sessionsare calculated by the amtune tool, and can be many times of those calculated in case for 32-bit JRE, depending on the available memory. Be sure to review these numbers and determine whether or not they are appropriate .

AMTUNE_MEM_MAX_HEAP_SIZE_RATIO

Description:

These parameters are used to calculate the maximum and minimum heap sizes. Options include:

  • AMTUNE_MEM_MAX_HEAP_SIZE_RATIO

  • AMTUNE_MEM_MIN_HEAP_SIZE_RATIO

Required:

Yes

Sample Values:
Maximum heap size ratio

7/8

Minimum heap size ratio

1/2

Additional Information:

Do not modify these ratios unless tests show significant improvement in performance.

Web Server 7, Application Server 9.1 and GlassFish v2 use about 1/8 of the OpenSSO Enterprise JRE process heap size, leaving about 7/8 for OpenSSO Enterprise. You should change these ratios only for 64-bit JRE. For 32-bit JRE, keep the default values.

AMTUNE_PER_THREAD_STACK_SIZE

Description:

Specifies available stack space per thread in JVM. Per-thread stack size is used to tune various thread-related parameters in OpenSSO Enterprise and its web container. Options include:

  • AMTUNE_PER_THREAD_STACK_SIZE_IN_KB

  • AMTUNE_PER_THREAD_STACK_SIZE_IN_KB_64_BIT

Required:

Yes

Sample Values:
32–bit JRE

128KB

64–bit JRE

512KB

Default Value:

None

Additional Information:

Do not modify these values.

AMTUNE_*_MEMORY_TO_USE_IN_MB_*

Description:

Maximum amount of memory that should not be exceeded for 32-bit JRE on different platforms. AMTUNE_MAX_MEMORY_TO_USE_IN_MB_X86 is used to limit the maximum JRE heap size on Linux installed on x86 hardware due to limitations on how much JRE heap size can be allowed even with 32-bit JRE.

Options include:

  • AMTUNE_MIN_MEMORY_TO_USE_IN_MB

  • AMTUNE_MAX_MEMORY_TO_USE_IN_MB_SOLARIS

  • AMTUNE_MAX_MEMORY_TO_USE_IN_MB_X86

  • AMTUNE_MAX_MEMORY_TO_USE_IN_MB_DEFAULT (for Windows)

Required:

Yes

Default Values

AMTUNE_MIN_MEMORY_TO_USE_IN_MB=512

AMTUNE_MAX_MEMORY_TO_USE_IN_MB_SOLARIS=3584 (Sparc/x86/AIX)

AMTUNE_MAX_MEMORY_TO_USE_IN_MB_X86=2341 (Linux)

AMTUNE_MAX_MEMORY_TO_USE_IN_MB_DEFAULT=1536 (Windows)

Additional Information:

Do not modify these values. If the maximum values are changed to higher numbers, the web container will not start on these platforms due to a JRE crash.