kctune(1M)

NAME

kctune — manage kernel tunable parameters

SYNOPSIS

kctune [-dghuvDS] [-b behavior] [-c config] [-C comment] [-F fmt]

[-m module] [-P fields] [arg]...

DESCRIPTION

kctune is the administrative command for HP-UX kernel tunable parameters. It gives information about tunable parameters and their values, and makes changes to tunable values.

This command can work with any saved kernel configuration, or with the currently running kernel configuration, depending on the use of the -c flag (see below). By default, changes to the currently running kernel configuration are applied immediately. Some changes cannot be applied without a reboot; if any such changes are requested, or the -h flag is given, all changes on the kctune command line will be held until next boot.

Only users with appropriate privileges can make changes to tunable values.

Options

-b behavior

Specifies whether or not to update the automatic backup configuration before the requested change. Also specifies the default backup behavior for future changes. See kconfig(5) for a description of the various backup behaviors. Not valid in combination with -c.

For compatibility with old releases, -B is accepted as an alias for -b yes, and -K is accepted as an alias for -b no. These aliases will be removed in a future release.

-c config

kctune will view or change tunables in the saved kernel configuration named config. If this option is not specified, kctune will view or change tunables in the currently running kernel configuration.

See kconfig(5) for more information on saved kernel configurations.

-C comment

The specified comment will be included in the kernel configuration log file entry made for this invocation of kctune. For more details on the kernel configuration log file, see kclog(1M). Note that it will usually be necessary to quote the comment in order to avoid interpretation by the shell.

-d

Adds the description of each tunable to the output.

-D

Restricts output to only those parameters which have changes being held until next boot. kctune will return 1 if there are any such parameters; see RETURN VALUE below. Not valid in combination with -c.

-F fmt

Formats all tunable values according to the specified format, which must be one of the characters d, u, o, or x, representing signed decimal, unsigned decimal, octal, or hexadecimal, respectively. In the absence of this option, kctune chooses an appropriate format for each tunable.

-g

Group related tunables. The tunables in the output will be grouped and sorted by the kernel modules that define them. Note: the set of tunables defined by each kernel module may change in future releases of HP-UX.

-h

Changes will be held until next boot, even if they could be applied immediately. Not valid in combination with -c.

-m module

Tells kctune to include in its output only those tunables which are defined by the specified module.

-P fields

Tells kctune to include only the specified fields in its output, and to print them in the machine-readable form described in kconfig(5). See the Developers Note, below. Not valid in combination with -d, -g, or -v.

-S

Only tunables with non-default values will be included in the output. Not valid in combination with -D.

-u

Allow the creation of user-defined tunables. Normally, kctune will not accept any tunable name that does not identify an existing tunable. When the -u option is given, kctune will accept an assignment to an unrecognized tunable name and use it to define a new user-defined tunable. This tunable will not directly affect the kernel, but may be used in expressions defining the values of other tunables. The -u option is not needed when changing the value of a user-defined tunable; it is needed only to create one.

To remove a user-defined tunable, set it to Default. A user-defined tunable cannot be removed if it is used in the expressions defining any other tunable values.

-v

Includes verbose information about the tunable parameters in the output listing. The information includes the name and value of the tunable, a short description, its allowed values, its dependencies on other tunables and restrictions on when the tunable values can be changed. Not valid in combination with -d, -g, or -P.

Operands

The operands to kctune may be any mixture of tunable queries and assignments. The operands must each take one of the forms listed below. No spaces are permitted within each operand. If no operands are given, kctune performs a query on all tunables (subject to the constraints of the -D or -S flags).

tunable: Reports the value of the tunable. No change is made.
tunable=: Sets the tunable to its default state.
tunable=Default: Sets the tunable to its default state. The word Default is not case sensitive.
tunable=expr: Sets the tunable to to the specified expression. See Expressions below for details.
tunable+=value: Increases the tunable by the specified value. value must be an integer constant (not an expression). C syntax for octal and hexadecimal constants is supported.
tunable>=value: Sets tunable's value to value, unless it is already greater. value must be an integer constant (not an expression). C syntax for octal and hexadecimal constants is supported. Note that the operand will probably need to be quoted to avoid interpretation by the shell.

Expressions

Tunables can be set to expressions following the expression syntax of the C programming language, with the following adjustments:

All constants must be integers, following the C language syntax for integer constants. Hexadecimal constants must be prefixed with 0x and octal constants with 0. For convenience, the following symbols can be added to the end of an integer constant:
k
Multiplies the constant by 1000 (10^3).
kB
Multiplies the constant by 1024 (2^10).
M
Multiplies the constant by 1,000,000 (10^6).
MB
Multiplies the constant by 1,048,576 (2^20).
GB
Multiplies the constant by 1,073,741,824 (2^30).
Identifiers in the expression must be the names of other tunables. Some tunables cannot be used in expressions.
Some tunables accept expressions in the form of a constant followed by a percent sign (%). Such expressions indicate that the tunable should be set to a percentage of some system resource; when the resource grows or shrinks, the effective value of the tunable changes to maintain the specified percentage. Consult the man pages for specific tunables to determine whether they support percentage values and how they are used.

As in the C programming language, expression evaluation is subject to rollover, overflow and underflow. Setting unsigned tunables to an expression that evaluates to a negative quantity will have unpredictable results.

When passed on a command line, expressions may need to be quoted to avoid interpretation by the shell.

Expressions are evaluated only when one of the kernal configuration commands is running. If a tunable's value changes under other circumstances, expressions involving this tunable are not re-evaluated and the tunable values dependent on those expressions are not updated. For example, this can happen when tunables are changed using a direct call to settune() or settune_txn(), or when a tunable is reset to its default value during boot because of a validation failure.

Default State for Tunables

The default value for a tunable is not necessarily fixed. Default values can change between HP-UX releases, or in patches. Some tunables have default values that are re-computed at boot time, or when there is a change to the hardware configuration of the system. Some tunables change their default values in response to changing system workloads. These tunables are called "Automatic" tunables and are marked in kctune output.

When a tunable is set to Default, its value is controlled by the HP-UX kernel, and will be changed whenever the default value for the tunable is re-computed. Specific behavior of each tunable is described in each tunable's man page. HP recommends that all tunables be set to Default unless the default value is known to be unsatisfactory.

Setting a tunable to its default value is not the same as setting it to Default. If the current default value of a tunable example is 4000,

kctune example=4000 

will set the tunable's value to 4000 and prevent it from changing when the default value is re-computed.

kctune example=Default 

will set the tunable's value to 4000, and automatically change it whenever the default value is re-computed.

Developer's Note

The layout and content of kctune's output may change without notice, except when -P fields is specified. Scripts or applications that need to parse the output of kctune are expected to use the -P fields option. See kconfig(5) for details.

The fields supported in a kctune request are:

auto_default: This field contains a y if the tunable's default value is automatically computed by the system (and can therefore change over time), or an n otherwise.
before: The value that was in use for the tunable before the change that was just made, if known. For saved configurations, the previous value of some tunables may not be known. If the value was specified using an expression, this field contains the result of evaluating that expression. This field is present only for tunables for which an immediate value change has been made during the current invocation of kctune.
before_default: This field contains a y if the tunable was set to its default value before this invocation of kctune, or an n otherwise. This field is present only for tunables for which an immediate value change has been made during the current invocation of kctune.
before_expr: The expression for the tunable's value before the change that was just made, if any. If the tunable was set to default, this field contains the word Default. This field is present only for tunables for which an immediate value change has been made during the current invocation of kctune.
bootvalue: The value of the tunable at the time the system last booted. This field is not printed for saved configurations.
canauto: This field contains a y if the tunable is capable of being automatically tuned, or an n otherwise.
constraint: This field contains the constraints between this tunable and others. There may be zero or more values of this field for any tunable.
current: The current value of the tunable, if known. For saved configurations, the current value of some tunables may not be known until the configuration is in use. If the value was specified using an expression, this field contains the result of evaluating that expression. If the tunable is being automatically tuned, this field contains the value the kernel is currently using.
desc: A short description of the tunable.
default: This field contains a y if the tunable is set to its default value, or an n otherwise. If all three of default, auto_default, and canauto are y, the tunable is being automatically tuned.
defvalue: The default value of the tunable, if known. For saved configurations, the default values of some tunables may not be known until the configuration is in use.
dynamic: This field contains a y if the tunable can be changed without a reboot, or an n otherwise.
expr: The expression used to set the value of the tunable, if any. If the tunable is set to default, this field contains the word Default.
flags: This field contains a hexadecimal representation of the bitmask containing the dynamic, canauto, default, auto_default, and signed flags, among others. See /usr/include/sys/dyntune.h for definitions of flag values. Additional flag values may be defined in future releases or patches.
max: The maximum value of the tunable. This is an absolute maximum; the currently running system may not be able to support values this high. If there is no maximum value, this field will be omitted from the output.
min: The minimum value of the tunable. This is an absolute minimum; the currently running system may not be able to support values this low. If there is no minimum value, this field will be omitted from the output.
module: The name of the module supplying the tunable, if any; otherwise, this field will be omitted from the output.
name: The name of the tunable.
next_boot: The value that will be used for the tunable at next boot, if known. The next boot value of some tunables may not be known until the boot completes. If the value was specified using an expression, this field contains the result of evaluating that expression. This field is not printed for saved configurations.
next_default: This field contains a y if the tunable is set to its default value at next boot, or an n otherwise. This field is not printed for
next_expr: The expression for the tunable's value at next boot, if any. If the tunable is set to default, this field contains the word Default. If -c is specified, this field is omitted from the output. saved configurations.
signed: This field contains a y if the tunable values should be treated as signed integers, or an n otherwise.

The special field name ALL may be specified to indicate that all defined fields should be included in the output. The output may include fields not listed in this man page. The fields will be listed in unspecified order.

Additional fields may be added in future releases or patches.

Default Output

When kctune is called with no options, it shows all tunables associated with the kernel modules (as well as the user-defined tunables), their current values, expressions used to compute those values, and when changes can be made to these tunables. If there are changes that are being held for nextboot, they will be shown as well.

On a typical system, the expression for most tunables are marked Default meaning that the administrator is allowing the system to choose the tunable value. The changes column shows the restrictions on when the tunable value can be changed. Tunables whose value can be changed immediately are marked Immed. Tunables whose values are being automatically tuned by the system are marked Auto. If the administrator has disabled the automatic tuning by the system the tunable is marked Imm (auto disabled). The tunables which have nothing in the changes column can only be changed with a reboot.

The layout and content of the default output may change in future releases or patches of HP-UX. Scripts or applications which need to parse the output of kctune must use the -P option to obtain output that can be parsed.

RETURN VALUE

kctune returns one of the following values:

0

kctune was successful. If -D was specified, this return value indicates that there are no tunable changes being held for next boot.

1

kctune was successful. However, there were changes requested to the currently running system which cannot be applied until the system reboots. Therefore, all of the requested changes are being held until next boot.

If -D was specified, this return value indicates that there are tunable changes being held for next boot.

2

kctune was not successful.

WARNINGS

kctune always checks the validity of tunable values before applying them to the running system. When tunable value changes are held for next boot, or made to a saved configuration, some of the validity checks are not performed until the changed configuration is booted. If any tunable values are found to be invalid, messages will be printed to the system console during the boot process, and the default values for any affected tunables will be used instead.

EXAMPLES

To see all tunables and their current values:

$ kctune 

To see which tunables have new values being held until next boot:

$ kctune -D 

To see verbose information about a tunable:

$ kctune -v tunablename 

To set a tunable value on the running system:

$ kctune tunable=12 

To set a tunable value to be used when the system reboots:

$ kctune -h tunable=12 

To increase a tunable's value by 100:

$ kctune tunable+=100 