kctune(1M)

NAME

kctune — manage kernel tunable parameters

SYNOPSIS

kctune [-dghuvBDKS] [-c config] [-C comment] [-P fields] [args...]

args are:

tunable: (query tunable)
tunable=: (set tunable to default)
tunable=Default: (set tunable to default)
tunable=expr: (set tunable to expression)
tunable+=value: (increase tunable by value)
tunable>=value: (set tunable to value if currently less)

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.

Super-user permissions are required when making changes to tunable values.

Options

-B

Forces a backup of the currently running configuration before making the requested change. For more information on backup configurations, see kconfig(5). Not valid in combination with -c.

-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.

-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.

-K

Prevents a backup of the currently running configuration before making the requested change. For more information on backup configurations, see kconfig(5). Not valid in combination with -c.

-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 may not 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.

Arguments

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

tunable

The value of the tunable will be reported. No change is made.

tunable=

The tunable will be set to its default state.

tunable=Default

The tunable will be set to its default state.

tunable=expr

The tunable will be set to the specified expression. expr must be an integer expression following the expression syntax of the C programming language. Like 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.

The expression may make use of the names of other tunables. (Some tunables cannot be used in expressions.) Tunable names may be specified in all upper case letters, for backward compatibility, but this usage is deprecated and will be removed in a future release. Note that the argument may need to be quoted to avoid interpretation by the shell.

Expressions are evaluated only when one of the KC commands is running. If a tunable's value changes under other circumstances, these expressions 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(2) or settune_txn(2), or when a tunable is reset to its default value during boot because of a validation failure.

tunable+=value

The tunable's value will be increased by value. value must be an integer constant (not an expression). C syntax for octal and hexadecimal constants is supported.

tunable>=value

The tunable's value will be set 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 argument will probably need to be quoted to avoid interpretation by the shell.

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:

name: The name of the tunable.
module: The name of the module supplying the tunable, if any; otherwise, this field will be omitted from the output.
desc: A short description of the tunable.
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.)
bootvalue: The value of the tunable at the time the system last booted.
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.
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.
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.
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.
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.
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.
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.
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.
dynamic: This field contains a 'y' if the tunable can be changed without a reboot, or an 'n' otherwise.
canauto: This field contains a 'y' if the tunable is capable of being automatically tuned, or an 'n' otherwise.
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.
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.
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 saved configurations.
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.
signed: This field contains a 'y' if the tunable values should be treated as signed integers, or an 'n' otherwise.
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.

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 changes. 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 for parsable output.

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 