kconfig(5)

NAME

kconfig — introduction to kernel configuration commands

DESCRIPTION

HP-UX contains a set of commands used to view and modify the configuration of the HP-UX kernel. The commands are:

kconfig: Operations on complete kernel configurations
kcmodule: Operations on kernel modules
kctune: Operations on kernel tunable parameters ("tunables")
kcpath: Retrieves pathnames of kernel files
kclog: Searches and displays the kernel configuration log file
mk_kernel: Builds a kernel configuration from a system file

KERNEL CONFIGURATIONS

The set of data that controls the behavior and content of the HP-UX kernel is called a kernel configuration. System administrators may save any number of kernel configurations, and may load any one of them at any time. A kernel configuration consists of module usage choices made using kcmodule and tunable values chosen using kctune.

By default, these commands affect the state of the currently running system. When these commands are given a -c config option, they instead affect the saved kernel configuration named config.

The currently running kernel configuration can be saved using kconfig -s. A saved configuration can be loaded using kconfig -l. This causes the state of the running system to be changed to match the saved configuration. A saved configuration can be marked for use when the system is next booted, by using kconfig -n. This makes no change to the state of the running system, but causes the specified saved configuration to be loaded when the system is rebooted. (See Boot Behavior below.)

Saved kernel configuration names must start with a letter; contain only letters, digits, and underscores (_); and be at most 32 characters in length. The names are case-distinct.

Backup Configuration

The system maintains a saved configuration called backup, which can be used to recover from configuration errors. Depending on the selected backup behavior, the system can automatically save the currently running configuration to backup immediately before making any requested change to the configuration. The backup behavior is set using the -b behavior option to the kconfig, kcmodule, or kctune commands. The recognized backup behaviors are:

yes

Always update the backup configuration before making a change.

once

Update the backup configuration before making the current change. For subsequent changes, ask whether to update it.

no

Do not update the backup configuration before making the current change. For subsequent changes, ask whether to update it.

disable

Never update backup configuration before changes.

These behaviors can be abbreviated to one letter. For compatibility with previous 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.

After each boot, the default backup behavior is to ask whether to update the backup configuration before each change. Changes made noninteractively assume a "no" response.

Dynamic and Static Changes

By default, the kernel configuration tools will apply configuration changes to the currently running system, causing an immediate change in their behavior. System administrators can override this default by specifying the -h option to changes made using the kconfig, kcmodule, or kctune commands. This option causes the change(s) to be held until the system is rebooted. HP recommends that this option be used only when the next reboot is expected to happen soon. If the reboot doesn't happen for months after the change, the change could come as an unwelcome surprise to an administrator who had forgotten the request.

Some configuration changes cannot be applied without a reboot. These changes will be held until the system is rebooted even if the -h option is not specified. In these cases, a warning message will be printed.

If multiple configuration changes are requested in a single invocation of one of the kernel configuration commands, and any one of those changes requires a reboot, all of the requested changes will be held until the system is rebooted. In particular, if a saved kernel configuration is loaded using kconfig -l, and that configuration cannot be used without a reboot, the state of the running system is not changed and the specified kernel configuration is marked to be used at next boot.

If a change to a configuration is being held until next boot, and a subsequent change to the same configuration setting is made with immediate effect, the immediate change will take precedence. The first change will not take effect at next boot. A warning will be printed in these situations.

Changes that replace the entire currently running configuration, such as kconfig -i (import), kconfig -l (load), or kconfig -n (nextboot), cause any changes being held for next boot to be discarded.

Changes that are made to the currently running system are retained when the system is rebooted. They remain in effect until changed, or until a saved kernel configuration is loaded.

Boot Behavior

When the system is booted, the administrator may specify the name of a saved kernel configuration on the boot command line (see hpux(1M) and hpux.efi(1M)). If so, that kernel configuration will be loaded during boot.

If no kernel configuration is specified on the boot command line, the system will look for any kernel configuration that had been marked for use at next boot (via a kconfig -n, kconfig -l, or kconfig -i command). If any such configuration is found, that configuration will be loaded during boot.

If no kernel configuration is specified on the boot command line, and none is marked for use at next boot, the system will boot using the same configuration that was in use before the reboot. If the configuration had any changes that were being held for reboot, either because they could not be applied without a reboot or because the -h option was used, those changes will be applied during the boot process.

If the kernel configuration fails to boot properly, recovery can be attempted by booting the backup configuration and/or booting with the "failsafe boot" flag (-tm on Itanium®-based systems, -f0x40000 on PA-RISC systems). See hpux(1M) and hpux.efi(1M) for details.

SYSTEM FILES

Users of past releases of HP-UX may be used to keeping kernel configuration choices in a text file called /stand/system. Such a file is known as a "system file". A system file is automatically maintained for the currently running kernel configuration. This file can be found at /stand/system. System files are also automatically maintained for each saved kernel configuration. These files can be found at /stand/config/system, where config is the name of the saved configuration. Any time a kernel configuration (saved or current) is changed using one of the kernel configuration commands, the corresponding system file automatically gets rewritten to reflect the change. System files can also be generated on demand for any configuration using kconfig -e. The format of a system file is described in system(4).

It is possible to make configuration changes by modifying a system file in a text editor and then running kconfig -i. This command will read the system file and modify the appropriate kernel configuration to match the contents of the system file. mk_kernel can also read a system file and modify a kernel configuration. It is retained for compatibility with previous releases of HP-UX.

Note:: Some configuration changes can be made without using one of the kernel configuration commands (for example, by calling the settune() or modload() system calls directly). In these cases, the system files are not automatically updated. Be sure to update them manually, or re-create them using kconfig -e before using them.
Note:: Avoid putting comments in a system file. System files get re-created every time a kernel configuration change is made, and comments are not preserved in this process.

System files can be useful for propagating kernel configurations to other systems. To do so, use kconfig -e to export a configuration to a system file on a source machine. Move the file to one or more target machines and use kconfig -i to import the system file into a configuration on the target. The target machines must have the same kernel filesets installed, or the import operation may fail. The -V flag can be used to ensure that the target machine has exactly the same versions of kernel filesets installed.

If there are changes to the currently running kernel configuration that are being held for reboot, those changes are reflected in the system file /stand/system.

LOG FILE

The kernel configuration commands maintain a log file that describes all kernel configuration changes. This log file is located at /var/adm/kc.log. The kclog command can be used to search and view the log file, or to make entries that don't correspond to configuration changes.

When making a configuration change using any of the commands, you can specify a -C comment option. The commands will include the specified comment in the log file entry describing the change. Note that the comment usually must be quoted to avoid interpretation by the shell.

Some configuration changes can be made without using the kernel configuration commands. No log file entries are made for such changes.

The format of the log file may be changed without notice. Programs must use the kclog command to retrieve entries from the file rather than attempting to parse the file format.

DIAGNOSTICS

All error, warning, and note messages printed by the kernel configuration commands are numbered. For aesthetic reasons, the message numbers are not usually displayed. To enable display of the message numbers, set the environment variable KC_SHOW_MSGIDS to 1.

PARSING OUTPUT

Most of the kernel configuration commands produce tabular output describing the details of a configuration. Such output may be attractive for humans, but can be difficult for scripts and applications to parse. Also, the tabular output format can change at any time: for example, between different types of systems or between releases of HP-UX.

For these reasons, each of the kernel configuration commands that produce such output accept a -P option, which changes the output format. The -P format is designed to be easy to parse, and is guaranteed not to change. HP will not support applications and scripts which parse the output of the kernel configuration commands unless they use the -P option.

The -P option must be followed by a comma-separated list of field names. Each kernel configuration command supports a different set of field names; refer to the man page for the command for a list. The field names must appear in a single argument, so there should be no spaces anywhere in the list. For example,

kcmodule -P name,state,desc 

The kernel configuration command will produce output that consists of a series of lines describing one object, a blank line, a series of lines describing the next object, a blank line, and so on until all objects are described. Each line in the series consists of a field name, a single tab character (ASCII 9), and the value of that field for the object being described. The lines occur in the same order as requested. So the above command might produce this output:

name    module1 
state   loaded 
desc    This is the first sample module. 

name    module2 
state   unused 
desc    This is a different sample module. 

Some fields may occur multiple times within an object, or may not occur at all. This will be noted in the description of the field. For example, the command

kcmodule -P name,state,depend 

might produce this output:

name    module1 
state   loaded 

name    module2 
state   unused 
depend  module1 
depend  module4 

This shows that module1 has no dependencies, but module2 is dependent on two other modules.

New fields may be added at any time, but they will not be included in the output unless specified in a -P option. Fields will not be removed. In rare cases, future developments may render a field meaningless. In these cases, the field name will still be accepted but the corresponding lines will be omitted from the output.