Chapter 1 Overview of Solaris System Tuning

This section provides overview information about the format of the tuning information in this manual. It also describes the different ways to tune a Solaris system.

• "Tuning a Solaris System"

• "Tuning Format"

• "Tuning the Solaris Kernel"

Tuning a Solaris System

Solaris is a multi-threaded, scalable UNIX^TM operating environment running on SPARC and Intel processors. It is self-adjusting to system load and demands minimal tuning. In some cases, however, tuning is necessary. This guide provides details about the officially supported kernel tuning options available for the Solaris environment.

The Solaris kernel is composed of a core portion, which is always loaded, and a number of loadable modules that are loaded as references are made to them. Many of the variables referred to in the kernel portion of this guide are in the core portion, but a few are located in loadable modules.

A key consideration in system tuning is that setting various system variables is often the least effective thing that can be done to improve performance. Changing the behavior of the application is generally the most effective tuning aid available. Adding more physical memory and balancing disk I/O patterns are also useful. In a few rare cases, changing one of the variables described in this guide will have a substantial effect on system performance.

Another thing to remember is that one system's /etc/system settings might not be applicable, either wholly or in part, to another environment. Carefully consider the values in the file with respect to the environment in which they will be applied. Make sure that you understand the behavior of a system before attempting to apply changes to the system variables described here.

The variables described here and their meanings can and do change from release to release. A release is either a Solaris Update release or a new version such as Solaris 8. Publication of these variables and their description does not preclude changes to the variables and descriptions without notice.

Tuning Format

The format for the description of each variable follows:

• Variable-Name

• Description

• Data Type

• Default

• Units

• Range

• Dynamic?

• Validation

• Implicit

• When to Change

• Commitment Level

• Change History

Variable-Name

Variable-Name is the exact name that would be typed in the /etc/system file, or found in the /etc/default/facility file.

Most names are of the form variable where the variable name does not contain a colon (:). These names refer to variables in the core portion of the kernel. If the name does contain a colon, the characters to the left of the colon reference the name of a loadable module. The name of the variable within the module consists of the characters to the right of the colon. For example:

module_name:variable

Description

This section briefly describes what the variable does or controls.

Data Type

Signed or unsigned short or long integer with the following distinctions:

• On a system running a 32-bit kernel, a long is the same size as an integer.

• On a system running a 64-bit kernel, a long is twice the width in bits as an integer. For example, an unsigned integer = 32 bits, an unsigned long = 64 bits.

Default

What the system uses as the default value.

Units

(Optional) Description of unit type.

Range

Possible range allowed by system validation or the bounds of the data type.

• MAXINT -- A shorthand description for the maximum value of a signed integer (2,147,483,647).

• MAXUINT -- A shorthand description for the maximum value of an unsigned integer (4,294,967,295).

Dynamic?

Yes, if it can be changed on a running system with the adb, mdb, or kadb debuggers. No, if it is a boot time initialization only.

Validation

Identifies checks the system applies to the value of the variable either as entered from the /etc/system file or the default value, as well as when the validation is applied.

Implicit

(Optional) Unstated constraints that might exist on the variable, especially in relation to other variables.

When to Change

Why someone might want to change this value including error messages or return codes.

Commitment Level

Identifies the stability of the interface. Many of the parameters in this manual are still evolving and are classified as unstable. See attributes(5) for more information.

Change History

(Optional) Contains a link to Change History appendix, if applicable.

Tuning the Solaris Kernel

The table below describes the different ways tuning parameters can be applied.

/etc/system File

The /etc/system file provides a static mechanism for adjusting the values of kernel variables. Values specified in this file are read at boot time and are applied. Any changes made to the file are not applied to the operating system until the system is rebooted.

Prior to the Solaris 8 release, /etc/system entries that set the values of system variables were applied in two phases:

• The first phase obtains various bootstrap variables (for example, maxusers) to initialize key system parameters.

• The second phase calculates the base configuration by using the bootstrap variables, and all values entered in the /etc/system file are applied. In the case of the bootstrap variables, reapplied values replace the values calculated or reset in the initialization phase.

The second phase sometimes caused confusion to users and administrators by setting variables to values that seem to be impermissible or assigning values to variables (for example, max_nprocs) that have a value overridden during the initial configuration.

In the Solaris 8 release, one pass is made to set all the values before the configuration parameters are calculated.

Example--Setting a Parameter in /etc/system

The following /etc/system entry sets the number of read-ahead blocks that are read for file systems mounted using NFS version 2 software.

set nfs:nfs_nra=4

Recovering From an Incorrect Value

Make a copy of /etc/system before modifying it so you can easily recover from incorrect value:

# cp /etc/system /etc/system.good

If a value entered in /etc/system causes the system to become unbootable, you can recover with the following command:

ok boot -a

This command causes the system to ask for the name of various files used in the boot process. Press the carriage return to accept the default values until the name of the /etc/system file is requested. When the Name of system file [/etc/system]: prompt is displayed, enter the name of the good /etc/system file or /dev/null:

Name of system file [/etc/system]: /etc/system.good

If /dev/null is entered, this path causes the system to attempt to read from /dev/null for its configuration information and because it is empty, the system uses the default values. After the system is booted, the /etc/system file can be corrected.

For more information on system recovery, see System Administration Guide, Volume 1.

adb

adb is a runtime debugger. Superuser can run adb with the -k option to see variables in the running kernel. If -w is specified with the -k option, superuser can change the in-memory values of the running kernel. Any changes made in this manner are lost when the system reboots.

Example--Using adb to Change a Value

To change the value of the integer variable maxusers from its current value to 0x200, do the following:

# adb -kw
physmem f7c6
maxusers/D
maxusers:
maxusers:       495
maxusers/W 200
maxusers:       0x1ef           =       0x200
$q

Replace maxusers with the actual address of the item to be changed as well as the value the variable is to be set to.

See adb(1) for information on using the adb command.

kadb

kadb is a bootable kernel debugger with the same general syntax as adb. See kadb(1M) for the exceptions. One advantage of kadb is that the user can set breakpoints and when the breakpoint is reached, examine data or step through the execution of kernel code.

If the system is booted with kadb -d, values for variables in the core kernel can be set, but values for loadable modules would have to be set when the module was actually loaded.

See "Debugging" in Writing Device Drivers for a brief tutorial on using the kadb command.

mdb

New to the Solaris 8 release is the modular debugger, mdb(1), which is unique among available Solaris debuggers because it is easily extensible. Those who have attempted to create adb macros are aware of the pain involved in that task. A programming API is available that allows compilation of modules to perform desired tasks within the context of the debugger. mdb provides backward compatibility with both adb(1) and crash(1M).

mdb(1) also includes a number of desirable usability features including command-line editing, command history, built-in output pager, syntax checking, and command pipelining. This is the recommended post-mortem debugger for the kernel.

Example--Using mdb to Change a Value

To change the value of the integer variable maxusers from 5 to 6, do the following:

# mdb -kw
Loading modules: [ unix krtld genunix ip logindmux ptm nfs ipc lofs ]
> maxusers/D
maxusers:
maxusers:       495
> maxusers/W 200
maxusers:       0x1ef           =       0x200
> $q

Replace maxusers with the actual address of the item to be changed as well as the value the variable is to be set to.

See the Solaris Modular Debugger Guide for more information on using the modular debugger.

When using adb, kadb, and mdb, the module name prefix is not required because after a module is loaded, its symbols form a common name space with the core kernel symbols and any other previously loaded module symbols.

For example, ufs:ufs_WRITES would be accessed as ufs_WRITES in each of the debuggers (assuming the UFS module is loaded), but would require the ufs: prefix when set in the /etc/system file. Including the module name prefix using adb or kadb results in an undefined symbol message.

Special Structures

Solaris tuning variables come in a variety of forms. The tune structure defined in /usr/include/sys/tuneable.h is the runtime representation of tune_t_gpgslo, tune_t_fsflushr, tune_t_minarmem, tune_t_minasmem, and tune_t_flkrec. After the kernel is initialized, all references to values of these variables are found in the appropriate field of the tune structure.

Various documents (for example, previous versions of Solaris System Administration Guide, Volume 2) have stated that the proper way to set variables in the tune structure is to use the syntax, tune:field-name where field name is replaced by the actual variable name listed above. This process silently fails. The proper way to set variables for this structure at boot time is to initialize the special variable corresponding to the desired field name. The system initialization process then loads these values into the tune structure.

A second structure into which various tuning parameters are placed is the var structure named v. You can find the definition of a var struct in /usr/include/sys/var.h. The runtime representation of variables such as autoup and bufhwm is stored here.

Do not change either the tune or v structure on a running system. Changing any of the fields of these structures on a running system might cause the system to panic.

Viewing System Configuration Information

Several tools are available to examine system configuration. Some require root privilege, others can be run by a non-privileged user. Every structure and data item can be examined with the kernel debugger (adb on a running system, booting under kadb, or mdb).

sysdef

The sysdef(1M) command provides the values of System V IPC settings, STREAMS tunables, process resource limits, and portions of the tune and v structures. For example, the sysdef "Tunable Parameters" section from on a 512 Mbyte Ultra^TM 80 system is:

10387456        maximum memory allowed in buffer cache (bufhwm)
    7930        maximum number of processes (v.v_proc)
      99        maximum global priority in sys class (MAXCLSYSPRI)
    7925        maximum processes per user id (v.v_maxup)
      30        auto update time limit in seconds (NAUTOUP)
      25        page stealing low water mark (GPGSLO)
       5        fsflush run rate (FSFLUSHR)
      25        minimum resident memory for avoiding deadlock (MINARMEM)
      25        minimum swapable memory for avoiding deadlock (MINASMEM)

kstats

kstats are data structures maintained by various kernel subsystems and drivers. They provide a mechanism for exporting data from the kernel to user programs without requiring that the program read kernel memory or have root privilege. See kstat(3KSTAT) for more information.

In the Solaris 8 release, a new command, kstat(1M), is available that enables selection and display of kstats with a command-line interface. A Perl module, kstat(3EXT), is also available to process kstat information.