Chapter 1 Tuning Components in the OpenSSO Enterprise Deployment

This chapter provides instructions for installing and using the amtune tool to tune OpenSSO Enterprise and related components. The following topics are contained in this chapter:

• About the amtune Tool

• Using the amtune Tool

About the amtune Tool

• Using a Password File

• Using amtune Modes

• Tuning the Operating System

• Tuning Third-Party Containers

The OpenSSO Enterprise amtune tool enables you to tune the major components of your deployment. In previous versions of the product (known as Sun Java System Access Manager), a collection of amtune shell scripts was used to do the tunings. In OpenSSO Enterprise, the amtune tool is a Java application. Before you can use the amtune tool, the following conditions must be met:

• OpenSSO Enterprise must be deployed on a supported web container.

  The following are supported web containers: Geronimo 2.x, JBoss 4.2.x, Oracle Application Server 10g, Tomcat 5.5.x or 6.x, WebLogic 9.2, MP2/10, WebSphere 6.1, Sun Web Server 7, and Sun Application Server 9.1 or GlassFish v2.

• The host computer must be running a supported operating system.

  The following are supported operating systems: Solaris 9 or 10, Red Hat Enterprise 4 or 5, Windows 2003 or Vista, Ubuntu 8.04 for some containers, or AIX 5.3 for only WebSphere 6.1

The following table lists the components tuned by the amtunetool.

The amtune tool relies on a list of DO NOT MODIFY parameters in the last section of the amtune-env.properties file. The parameters in that section are mainly for internal use by amtune. Do not modify the parameters in the DO NOT MODIFY list unless user tests show significant improvement in performance.

Using a Password File

Execute amtune or amtune.bat with a file that contains passwords for the servers in your deployment. Use the following strings:

For sample entries, see the sample passwords file. The file amtune-samplepasswordfile is located in the directory:

TOOLS_DIR\OPENSSO_URI\bin\amtune,

where amtune/amtune.bat and amtune-env.properties are also located.

On Solaris, Linux, and AIX, the password file must be inaccessible to non-owners and only readable by its owner . For example, you can change the permissions mode of the password file by running the following command:

chmod 400

On Windows, amtune.bat does not check the permission on the password file.

Tuning operating system parameters does not require a password file.

Using amtune Modes

You can run the amtune tool in REVIEW mode (the default) or in CHANGE mode, as determined by the AMTUNE_MODE parameter in the amtune-env.properties file.

REVIEW

This is the default value. Returns tuning recommendations for an OpenSSO Enterprise deployment, but does not make any actual changes to the environment.

CHANGE

Makes all tuning modifications defined in the amtune-env.properties file. Use CHANGE mode only after you have reviewed and understand the tuning changes that will be applied to your deployment.

In either mode, the tool returns a list of tuning recommendations to the terminal window and to the following log file: <TOOLS_DIR>\<OPENSSO_URI>\logs\amtune-config.<timestamp>.log

Any error messages due to missing or invalid data in the amtune-env.properties file are displayed in the terminal window and written to the following file: <TOOLS_DIR>\<OPENSSO_URI>\logs\amtune-errors. All other error messages triggered by underlying components such as OpenSSO Enterprise or Sun Web Server are also written to the amtune-errors file.

Tuning the Operating System

The amtune tool tunes the operating system parameters only on Solaris and Linux. It does not tune the operating system parameters on AIX, Windows, MacOS or BSD variants.

Linux OS

To tune for maximum performance on Linux systems, make tuning adjustments to the following items:

• File Descriptors

• Virtual Memory

• Disk I/O Settings

• TCP/IP Settings

For detailed information on tuning Linux operating system parameters, see the IBM Linux Performance and Tuning Guidelines.

File Descriptors

You might need to increase the number of file descriptors from the default. A higher number of file descriptors ensures that the server can open sockets under high load and not abort requests coming in from clients. Start by checking system limits for file descriptors with this command:

cat /proc/sys/fs/file-max
8192

The current limit shown is 8192. To increase it to 65535, use the following command (as root):

echo "65535" > /proc/sys/fs/file-max

To make this value survive a system reboot, add it to /etc/sysctl.conf and specify the maximum number of open files permitted:

fs.file-max = 65535

The parameter is not proc.sys.fs.file-max, as you might expect.

To list the available parameters that can be modified using sysctl:

sysctl -a

To load new values from the sysctl.conf file:

sysctl -p /etc/sysctl.conf

To check and modify limits per shell, use the following command:

ulimit -a

The output will look something like this:

cputime         unlimited
filesize        unlimit
datasize        unlimited
stacksize       8192 kbytes
coredumpsize    0 kbytes
memoryuse       unlimited
descriptors     1024
memorylocked    unlimited
maxproc         8146
openfiles       1024

The open files and descriptors show a limit of 1024. To increase the limit to 65535 for all users, edit /etc/security/limits.conf as root, and modify or add the nofile setting (number of file) entries:

*         soft    nofile                     65535
*         hard    nofile                     65535

The asterisk (*) is a wildcard that identifies all users. You can also specify a user ID instead.

Then edit /etc/pam.d/login and add the line:

session required /lib/security/pam_limits.so

On Red Hat Linux, edit /etc/pam.d/sshdand add the following line:

session required /lib/security/pam_limits.so

On many systems, this procedure will be sufficient. Log in as a regular user and try it before performing the remaining steps. The remaining steps might not be required, depending on how pluggable authentication modules (PAM) and secure shell (SSH) are configured.

Virtual Memory

OpenSSO 8 supports only Linux kernel 2. 6 systems such as Red Hat Enterprise Linux 4 and 5, and Ubuntu 8.0.4. For more information, see "Chapter 4: Tuning the VM” in the documenthttp://people.redhat.com/nhorman/papers/rhel4_vm.pdf.

To ensure that the network interface is operating in full duplex mode, add the following entry into /etc/rc.local:

mii-tool -F 100baseTx-FD eth0

where eth0 is the name of the network interface card (NIC).

Disk I/O Settings

To tune disk I/O performance for a non-SCSI disk, follow these steps:

1. Test the disk speed with this command:

   /sbin/hdparm -t /dev/hdX

2. Enable direct memory access (DMA) with this command:

   /sbin/hdparm -d1 /dev/hdX

3. Check the speed again using the hdparm command. Given that DMA is not enabled by default, the transfer rate might have improved considerably. In order to do this at every reboot, add the /sbin/hdparm -d1 /dev/hdX line to /etc/conf.d/local.start, /etc/init.d/rc.local, or whatever the startup script is called.

TCP/IP Settings

To tune the TCP/IP settings, follow these steps:

1. Add the following entry to /etc/rc.local:

   echo 30 > /proc/sys/net/ipv4/tcp_fin_timeout echo 60 > /proc/sys/net/ipv4/tcp_keepalive_time echo 75 > /proc/sys/net/ipv4/tcp_keepalive_intvl echo 0 > /proc/sys/net/ipv4/tcp_window_scaling

2. Add the following to /etc/sysctl.conf:

   # Disables packet forwarding net.ipv4.ip_forward = 0 # Enables source route verification net.ipv4.conf.default.rp_filter = 1 # Disables the magic-sysrq key kernel.sysrq = 0 net.ipv4.ip_local_port_range = 1204 65000 net.core.rmem_max = 8388608 net.ipv4.tcp_rmem = 4096 131072 8388608 net.ipv4.tcp_wmem = 4096 131072 8388608 net.ipv4.tcp_sack = 0 net.ipv4.tcp_timestamps = 0 net.ipv4.tcp_window_scaling = 0 net.ipv4.tcp_keepalive_time = 60 net.ipv4.tcp_keepalive_intvl = 75 net.ipv4.tcp_fin_timeout = 30

3. Add the following as the last entry in /etc/rc.local:

   sysctl -p /etc/sysctl.conf

4. Reboot the system.

5. Use this command to increase the size of the transmit buffer:

   tcp_recv_hiwat ndd /dev/tcp 8129 32768

Tuning JVM Heap Sizes

The amtune tool restarts the server to check its JVM 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 JVM. For other web containers, $WEB_CONTAINER and $CONTAINER_INSTANCE_DIR values are not required.

Although the amtune tool does not tune non-Sun web containers, it will tune OpenSSO parameters if $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 JVM:

• (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 AIX, although it does not tune AIX system parameters or WebSphere container parameters.

For 64-bit JVM, amtune 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 JVM heap size. There is no limit for the maximum heap size (-Xmx).

Using 64–bit JVM, the user session cache size, number of sessions, and number of SDK cache entries are calculated by amtune. The results can be many times more than those calculated for 32–bit JVM, depending upon available memory. Be sure to review these numbers and determine whether or not they are apropriate.

Tuning Third-Party Containers

For 32-bit Sun JVM on Solaris 10 (both Sparc and x86), the following JVM options can be used as an example. The actual heap sizes should be adjusted based on the available physical memory, other processes running and the presence of any other active web applications running in the same JVM as OpenSSO.

-server
-XX:+UseParNewGC
-XX:+UseConcMarkSweepGC
-Xms3136M 
-Xmx3136M
-XX:NewSize=392M
-XX:MaxNewSize=392M
-Xss128k

For more information on JVM tuning and use of 64-bit JVM, please go to Java Performance Portal:

http://java.sun.com/javase/technologies/performance.jsp.

For WebLogic Application Servers, increase the MaxPermSize from the default value of 128m to 256m in setDomainEnv.sh as shown below:

"if [ "${JAVA_VENDOR}" = "Sun" ] ; then
       MEM_ARGS="${MEM_ARGS} ${MEM_DEV_ARGS} -XX:MaxPermSize=256m"
       export MEM_ARGS
fi"

Otherwise, WebLogic Server may not start up with OpenSSO 8 deployed.

Using the amtune Tool

• To Install the amtune Tool

• To Tune the Operating System, Web Container, and OpenSSO Enterprise

• To Tune a Remote Sun Directory Server

To Install the amtune Tool

1. In the directory where you want to install the tuning tool, unzip the amtune.zip file.

2. In the directory which has the unzipped ssoAdminTools file, run the following command:

   UNIX

   ./setup

   Windows

   setup

3. When prompted, enter the configuration directory.

   Example: /opensso_config/opensso

   Once installation is complete, you can use the command-line interface under the following directory:

   <TOOLS_DIR>/<OPENSSO_INSTANCE_NAME>/bin

   where <TOOLS_DIR> is the directory which has the unzipped amtune.zip file, and <OPENSSO_INSTANCE_NAME> is the OpenSSO Enterprise deployment URI.

   The amtune tool is now in the <TOOLS_DIR>/<OPENSSO_URI>/bin/amtune directory.

To Tune the Operating System, Web Container, and OpenSSO Enterprise

1. Log in as or change to superuser.

2. If you have not run the tool in REVIEW mode, ensure that AMTUNE_MODE is set to REVIEW in the following file:

   <TOOLS_DIR>\<OPENSSO_URI>\bin\amtune\amtune-env.properties file

3. Edit other parameters in the amtune-env.properties file, depending upon the components you want to tune.

   See the Appendix for detailed information about the properties.

4. In REVIEW mode, run the amtune tool with a password file.

   See the section Using a Password File in this document.

   Solaris or Linux

   <TOOLS_DIR>/<OPENSSO_URI>/bin/amtune/amtune

   Windows

   <TOOLS_DIR>\<OPENSSO_URI>\bin\amtune\amtune.bat

   Review the tuning recommendations in the terminal or in the <TOOLS_DIR>/OPENSSO_URI/logs/amtune-config.<timestamp>.log file. If necessary, make changes to the amtune-env.properties file based on the tuning recommendations.

5. When you are satisfied with the tuning recommendations from running amtune in REVIEW mode, set AMTUNE_MODE to CHANGE in the amtune-env.properties file.

6. Check the debug log file for the results.

   In CHANGE mode, the amtune tool might need to restart the web container and OpenSSO Enterprise. When the operating system kernel parameters are changed, the amtune tool will recommend a system restart.

To Tune a Remote Sun Directory Server

1. FTP or copy amtune.zip to the remote Sun Directory Server host.

2. Unzip amtune.zip.

3. Set values for TOOL_HOME and JAVA_HOME.

   Solaris, Linux, and AIX

   <TOOLS_DIR>/bin/unix/amtune

   Windows

   <TOOLS_DIR>\bin\windows\amtune.bat

4. Edit the amtune-env.properties file to include Directory Server information.

5. Run the amtune tool with a password file for the Sun Directory Server Directory Manager.

   The Directory Server Directory Manager password must be inaccessible to non-owners and only readable by its owner . For example, you can run change the permissions mode of the password file by running the following command:

   chmod 400

   UNIX or Linux

   amtune

   Windows

   amtune.bat

   On Windows, you must also execute amtune.bat with a password file. But amtune.bat does not check its file permission on Windows.

   In CHANGE mode, if AMTUNE_TUNE_DS=true, then the amtune tool will restart the Sun Directory Server instance.

   If AMTUNE_TUNE_OS=true, then the amtune tool will tune the operating system kernel parameters and will recommend a system restart.