kctune(1M) kctune(1M)
NAME [Toc] [Back]
kctune - manage kernel tunable parameters
SYNOPSIS [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
-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.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
kctune(1M) kctune(1M)
-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
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
kctune(1M) kctune(1M)
-d, -g, or -P.
Arguments [Toc] [Back]
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 any tunable name.
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.
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 [Toc] [Back]
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
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
kctune(1M) kctune(1M)
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.
bootvalue The value of the tunable at the time the system last
booted.
current The current value of the tunable. 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 the value was specified using an expression,
this field contains the result of evaluating that
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
kctune(1M) kctune(1M)
expression. This field is present only if -c is not
specified.
before The value that was in use for the tunable before the
change that was just made. 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.
default This field contains a 'y' if the tunable is set to its
default value, or an 'n' otherwise. If both 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 omitted from the output if -c is specified.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
kctune(1M) kctune(1M)
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, 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 [Toc] [Back]
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 [Toc] [Back]
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.
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
kctune(1M) kctune(1M)
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.
EXAMPLES [Toc] [Back]
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
SEE ALSO [Toc] [Back]
kclog(1M), kconfig(5), gettune(2), settune(2), settune_txn(2),
tuneinfo2(2), Managing Kernel Configurations White Paper available on
docs.hp.com.
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003 [ Back ] |
