config(1M)

NAME

config — configure and build an HP-UX system

SYNOPSIS

/usr/sbin/config [-c c_file] [-l m_file] [-m master] [-r path] [-s|-u] [-S] [-t] system_file

/usr/sbin/config -M module_name [[-M module_name]...] [-m master] [-u]

DESCRIPTION

config is used to configure the following parts of the operating system:

an entire new kernel and associated components
individual kernel modules (including device drivers)
swap and dump devices
tunable system parameters

config supports the following forms of kernel configurations:

whole kernel configuration (first form)
Both the static portion of the kernel and the dynamically loadable kernel module images are generated. A system update and reboot are necessary to run the newly generated kernel.
loadable module configuration (second form, also referred to as kernel module configuration)
Specified dynamically loadable kernel module images are generated. If an update of the current system with the newly configured modules is successful, new services can be made available immediately, without requiring a system reboot.

Kernel modules are portions of the kernel responsible for supporting a specific feature (e.g. device drivers, file system types). Kernel modules can either be statically linked to the kernel (static modules) or dynamically linked to the kernel at run time (dynamically loadable kernel modules, or DLKM modules). Not all modules have DLKM capability.

To generate kernels and loadable module images, config takes as input a set of kernel archive libraries (traditional), a set of kernel module object files (modular), and a set of distributed kernel configuration files describing the kernel modules installed on the system. config also reads additional system-wide information maintained in the HP-UX system description file (also known as the traditional system file).

Modularly packaged kernel modules are maintained in individual object files. The configuration information associated to modularly packaged modules is described in individual configuration files, including a modular system file and a modular master file per kernel module. Modularly packaged modules must be installed on the system using the kminstall(1M) command. Dynamically loadable kernel modules must be modularly packaged.

Traditionally packaged kernel modules are maintained in archive library files. Configuration information about traditionally packaged modules is maintained in several traditional master files in the /usr/conf/master.d directory, and the single traditional system file.

The set of traditional and modular master files describe configuration information supplied by kernel developers as part of the HP-UX operating system, and should not be modified by system administrators.

The traditional system file and modular system files contain configurable attribute values used to tailor the system and kernel before a call to config. The kmsystem(1M) administration command must be used to plan the configuration of a kernel module in or out of the kernel, or to modify any kernel module related information, prior to a whole kernel or loadable module configuration. The kmtune(1M) system administration command must be used to modify any kernel tunable parameters prior to a whole kernel or loadable module configuration. Such information should not be modified by editing the system files, since the format and location of such information is subject to change.

See master(4) and system(4) for more information about kernel configuration file formats. See the Managing Systems and Workgroups manual for information on how to tailor the kernel or system (set planned configuration values) before a whole kernel or module configuration, how to update the kernel, and how to boot the system.

WHOLE KERNEL CONFIGURATION (First Form)

When generating a whole kernel, based on the input configuration information, config generates the following output files and directories:

C program source files conf.c and space.h, which define the configuration tables for various parts of the system.
C program header file tune.h, which defines tunable parameters of the system required by kernel and kernel modules.
C program source files (mod_conf.c) used to generate dynamically loadable images of kernel modules.
If a space.h header file is provided with a module, it is included by the mod_conf.c source file.
a makefile, config.mk, used to generate the static portion of the newly configured kernel into the resulting main kernel file (vmunix_test), and to generate the kernel symbol table (symtab).
another makefile, config.mod, used to generate all dynamically loadable module images scheduled to be configured.
config.mod is not generated if there are no dynamically loadable modules scheduled for configuration.
a directory /stand/dlkm.KIS to store dynamically loadable images and other DLKM information
a kernel registry (KRS) file /stand/krs/KIS.p0 to store module registration information and other kernel-specific persistent information.

After the above files are created, config executes the make(1) command using the config.mk and config.mod makefiles. The make command creates several files in a working directory whose location depends on the name of the specified traditional system file. See the sections below on options.

Upon successful completion of the make(1) command, the following files are generated:

main kernel file
This is the kernel file vmunix_test, which contains the kernel image corresponding to the static portion of the kernel.
associated kernel component set
This is the distributed set of associated kernel files required to boot and run the generated kernel. The files in the kernel component set are associated to each other via a unique kernel ID string (KIS). Among other files, the files under /stand/dlkm.KIS are generated, including the loadable kernel module images, and the kernel symbol table.

If the -u option is specified, the kmupdate(1M) command is executed automatically to schedule the update of the system with the newly generated kernel. This makes the newly generated kernel the new default boot kernel. Note that this option must be used (or alternately, kmupdate(1M) must be executed directly) in order to ensure that all the components of the newly generated kernel are in place for the boot process. [See kmupdate(1M).]

Options for Whole Kernel Configuration

When configuring a whole kernel, the config command recognizes the following arguments:

-c c_file: Specify the name of the C program source file produced by config. The default file name is conf.c.
-l m_file: Specify the name of the makefile which is generated by config. This is the makefile which will be used by config to compile the C program source file and make the new kernel. The default file name is config.mk.
-m master: Specify the name of the master kernel configuration file or directory that config should use in creating source files and makefiles. If master is a directory, config reads all files in that directory to create its data structures. If master is a file, only that file is read for creating data structures for config. By default, config reads the files in the directory /usr/conf/master.d.
-r path: Search path for the directory structure containing the libraries and header files needed for making the kernel. By default, config uses the directory structure under /usr/conf.
-S: This option will force all modules that are scheduled for configuration to be statically linked into the main kernel file, including the kernel modules with planned linkage set to dynamic. [See kmsystem(1M)].
-s: Stop after generating source files and makefiles. make(1) is not executed and no kernel (vmunix_test) or kernel modules are created. The -s option cannot be used with the -u option.
-t: Give a short table of major device numbers for the character and block devices, the card drivers, the streams drivers and modules that require link routines, the streams devices and the streams modules named in system_file. These tables may be useful when creating special device files.
-u: Invoke the kmupdate(1M) command after successfully configuring the new kernel environment. This will make the newly generated kernel the new default boot kernel. The -u option cannot be used together with the -s option.
system_file: The HP-UX system description file (traditional system file) containing system-wide configuration information. The default system file is /stand/system, and when this file is used as input to config, the resulting output is placed in the directory /stand/build. If a file other than /stand/system is used for system_file, config places its output files in the current directory.

LOADABLE MODULE CONFIGURATION (Second Form)

Based on the input configuration information, config -M generates the following output files:

C program source file mod_conf.c for each kernel module.
C program header file tune.h that defines tunable parameters of the system.
a makefile, config.mod, used to generate dynamically loadable module images for the specified modules.
kernel module registration information for the specified modules.

After the above files have been generated, config executes the make(1) command with config.mod. With a successful make, the module loadable image and related components required by the DLKM loader are generated.

If the -u option is specified in conjunction with the -M option, then config calls kmupdate(1M) to update the running kernel with the new loadable image of the specified module. Updating the loadable image implies replacing the existing loadable image(if any) with the newly created loadable image, registering the new module with the running kernel, and performing any type-specific initialization; e.g. recreating the special device file, if needed. After a successful module update, the module is ready to be automatically loaded by the running kernel (auto-load), or demand-loaded by the administrator.

Options for Loadable Module Configuration

For loadable module configuration, config recognizes the following options:

-M module_name

Configure the specified loadable module. A main kernel file is not generated in this case. If successful, the module's loadable image and related components required by the DLKM loader are generated.

If the specified module requires a kernel stub (see master(4)), config prints a message and fails. A whole kernel configuration is required to configure stub modules.

-m master

Specify the name of the master kernel configuration information file or directory that config should use in creating source files and makefiles. If master is a directory, config reads all files in that directory to create its data structures. If master is a file, only that file is read for creating data structures for config. By default, config reads the files in the directory /usr/conf/master.d.

-u

Invoke kmupdate(1M) to update the running kernel with the new module.

EXTERNAL INFLUENCES

Environment Variables

PATH determines the location of commands invoked by config.

RETURN VALUE

config returns 0 upon successful completion. If an error occurs, a non-zero value is returned.

DIAGNOSTICS

All error messages and warning messages of config are sent to stderr. Status report messages are sent to stdout. These messages are self-explanatory. Some messages are generated by make(1) or commands called from the makefiles.

FILES

/usr/conf/master.d/*: Default input master configuration files
/usr/conf/gen/config.sys: Skeleton makefile for whole kernel configuration
/usr/conf/gen/config.lm: Skeleton makefile for kernel modules
/stand/system: Default traditional system file
/stand/system.d/*: Modular system files
/stand/build/conf.c: Default output configuration table
/stand/build/tune.h: Default output system parameter table
/stand/build/config.mk: Default output whole kernel make(1) script
/stand/build/config.mod: Default kernel module make(1) script
/stand/build/vmunix_test: Default main kernel file generated by config
/stand/dlkm.KIS/symtab: Kernel symbol table (KIS is the kernel ID string that uniquely identifies the generated kernel).
/stand/dlkm.KIS/mod.d/*: Kernel module loadable images (KIS is the kernel ID string that uniquely identifies the generated kernel).
/stand/krs/KIS.p0: Default kernel-specific registry file generated by config