4    Configuring the Kernel

The operating system kernel is a memory-resident executable image that handles all the system services - hardware interrupts, memory management, interprocess communication, process scheduling - and makes all other work on the operating system possible. In addition to the code that supports these core services, the kernel contains a number of subsystems.

A subsystem is a kernel module that extends the kernel beyond the core kernel services. File systems, network protocol families, and physical and pseudodevice drivers are all examples of supported subsystems. Some subsystems are required in the kernel, and others are optional. You configure your kernel by adding and removing these optional subsystems, either during installation or later when you need to change the system.

You also configure your kernel by tuning certain values stored in it. For example, the kernel contains values that you can adjust to make disk access faster. Modifying values to optimize disk access can improve your system's performance, however it can also affect performance in other areas. Detailed information on system tuning and the interaction of attributes is included in the System Configuration and Tuning guide.

The system provides two methods of configuring your kernel: the dynamic method and the static method. Dynamic system configuration entails using commands to configure the kernel. Static system configuration entails modifying system files and rebuilding the kernel. Modifying system files and rebuilding the kernel is often a difficult process, so use dynamic kernel configuration whenever possible. You cannot make all modifications dynamically, and dynamic changes may not always be preserved across reboots.

This chapter contains the following information:

4.1    Related Documentation and Utilities

The following information sources provide information on system attributes, configuration tools and utilities, and detailed reference information on configuration options:

4.2    System Configuration at Installation Time

When you install the operating system, the installation program initially copies a kernel image to the root partition of your system disk. This kernel image, known as the generic kernel, supports all processors and hardware options that are available for use with the current version of the operating system. In this way, the installation program ensures that you can boot your system regardless of its configuration. The file for the generic kernel is /genvmunix.

Toward the end of the installation, after all the subsets you selected have been written to disk and verified, the installation program calls the /usr/sbin/doconfig program. When it runs, the /usr/sbin/doconfig program calls another program, known as the sizer program. The sizer program determines what hardware and software options are installed on your system and builds a target configuration file specific to your system. (The configuration file is the system file that controls what hardware and software support is linked into the kernel.) The /usr/sbin/doconfig program then builds your custom /vmunix kernel from this target configuration file. This kernel is built using the default values for all subsystem attributes.

Unlike the generic kernel copied to the system at installation time, the target kernel is tailored to your system. Only the hardware and software options available on your system are compiled into the target kernel. As a result, the target kernel is much smaller and more efficient than the generic kernel.

When the installation is complete, the target kernel resides either in the root partition of your system disk or in memory, depending upon how your system was built. (See Section 4.5 for information about the different ways in which you can build a kernel.) If the appropriate console boot variables are set, your system always boots the target kernel automatically. For information about setting and using console boot variables, see Chapter 2 and the Owner's Manual for your system.

4.3    Deciding When and How to Reconfigure Your Kernel

After your target kernel is built and started by the installation procedure, you can use it without modifications, unless one of the following occurs:

Most devices are automatically recognized by the system and configured into the kernel at boot time. (See Chapter 5 for information on adding devices.) However, some devices, such as third-party disk drives, older types of drives, or products such as scanners and PCMCIA cards must be added manually. For these devices, you must reconfigure your kernel, either dynamically or statically, when one of these situations occurs. The method you use to reconfigure your kernel depends upon the support provided by the subsystem or subsystem attributes.

Some kernel subsystems, such as the envmon environmental monitoring subsystem, are dynamically loadable, meaning that you can add the subsystem to or remove the subsystem from the kernel without rebuilding the kernel. Often, subsystems that are dynamically loadable also allow you to dynamically configure the value of their attributes. Therefore, you can tune the performance of these subsystems without rebuilding the kernel. To determine whether an attribute is dynamically configurable, use the -m with the sysconfig and search for the dynamic identifier as follows: 


# sysconfig -m | grep dynamic
lat: dynamic
envmon: dynamic
hwautoconfig: dynamic
 
 

If you decide to add or remove these subsystems from the kernel or configure the value of their attributes, use the procedures described in Section 4.4.

Some subsystems, such as required subsystems, are not dynamically loadable. However, these subsystems might allow you to dynamically configure the value of attributes. If so, you can configure the value of these subsystem attributes without rebuilding the kernel.

You can dynamically configure attributes using the following methods:

If you decide to configure attributes of these subsystems, use the procedures described in Section 4.4.8. It is recommended that you do not manually edit system files such as /etc/sysconfigtab. Instead, use a command or utility such as dxkerneltuner to make any changes.

If you purchase a device driver or other kernel subsystem from a third party company, that product might also be dynamically loadable or allow you to dynamically configure attribute values. For information about dynamically configuring your kernel when working with products from other vendors, see the documentation for the product and refer to Section 4.4.

If the subsystem you want to add, remove, or configure does not support dynamic configuration, you must use the static configuration method. You must also use this method to configure system parameters that do not support dynamic configuration. For information about the static configuration method, see Section 4.5.

4.4    Dynamic System Configuration

When you need to load, unload, or modify a dynamic subsystem, you use the /sbin/sysconfig command. This command has the following syntax:

/sbin/sysconfig [-h hostname ] [-i index [ -v | -c | -d | -m | -o | -q | -Q | -r | -s | -u ] ] [subsystem-name] [attribute-list | opcode]

You must be the superuser to load and unload subsystems. You must also know the name of the subsystem you want to manage. Determine the name of a subsystem by looking in the documentation that accompanies the subsystem or in the directories into which the subsystem is installed. Subsystems are installed in either the /subsys directory or the /var/subsys directory. When a subsystem is installed, a file named subsystem-name.mod appears in one of those two directories. You use that subsystem name as input to the /sbin/sysconfig command. The following sections describe the commands that you use to manage subsystems.

You can load and unload subsystems on a local system or a remote system. For information about adding and removing subsystems on remote systems, see Section 4.4.7

If you are writing a loadable device driver or other loadable subsystem, refer to the device driver documentation and the Programmer's Guide. The device driver documentation describes the tasks performed by the system when you install a loadable device driver. These manuals also describe how to write and package loadable device drivers. The Programmer's Guide provides general information about creating subsystems that are dynamically configurable and discusses the framework that supports dynamic configuration of subsystems and attributes.

4.4.1    Configuring Subsystems

To configure (load) a subsystem, enter the sysconfig command using the -c option. Use this command whether you are configuring a newly installed subsystem or one that was removed using the /sbin/sysconfig -u (unconfigure) command option. For example, to configure the environmental monitoring envmon subsystem, enter the following command: 


# /sbin/sysconfig -c envmon

4.4.2    Listing the Configured Subsystems

Subsystems can be known to the kernel, but not available for use. To determine which subsystems are available for use, use the /sbin/sysconfig -s command. This command displays the state of all subsystems. Subsystems can have the following states:

If you use the /etc/sysconfig -s command without specifying a subsystem name, a list of all the configured subsystems is displayed. For example: 

# /sbin/sysconfig -s
cm: loaded and configured
hs: loaded and configured
ksm: loaded and configured
generic: loaded and configured
io: loaded and configured
ipc: loaded and configured
proc: loaded and configured
sec: loaded and configured
socket: loaded and configured
rt: loaded and configured
advfs: loaded and configured
.
.
.
envmon: unloaded
 
 

This list (which is truncated) includes both statically linked subsystems and dynamically loaded subsystems.

To get information about the state of a single subsystem, include the name of the subsystem on the command line: 


# /sbin/sysconfig -s lsm
lsm: unloaded

4.4.3    Determining the Subsystem Type

You can determine whether a subsystem is dynamically loadable or static by using the /sbin/sysconfig -m command, as shown: 

# /sbin/sysconfig -m kinfo lat
kinfo: static
lat: dynamic

The output from this command indicates that the kinfo subsystem is static, meaning that you must rebuild the kernel to add or remove that subsystem from the kernel. The lat subsystem is dynamic, meaning that you can use the sysconfig -c command to configure the subsystem and the sysconfig -u command to unconfigure it.

4.4.4    Unloading a Subsystem

To unconfigure (and possibly unload) a subsystem, use the /sbin/sysconfig -u command, as shown: 


# /sbin/sysconfig -u hwautoconfig

If you frequently configure and unconfigure device drivers you might notice that the device special files associated with a particular device driver differ from time to time. This behavior is normal. When you configure a device driver using the /sbin/sysconfig command, the system creates device special files. If you unload that device driver and load another one that uses the same cdev or bdev major numbers, the system removes the device special files for the unloaded device driver. Therefore, it must create new device special files the next time you configure the device. See Chapter 5 and the dsfmgr(8) reference page for more information on device special files.

4.4.5    Maintaining the List of Automatically Configured Subsystems

The system determines which subsystems to configure into the kernel at system reboot time by checking the list of automatically configured subsystems. The system configures each subsystem on the list, using the sysconfig -c command at each system reboot.

You maintain the list of automatically configured subsystems by using the /sbin/init.d/autosysconfig command.

This command has the following syntax:

/sbin/init.d/autosysconfig [list] [add subsystem-name] [delete subsystem-name]

Use the /sbin/init.d/autosysconfig list command to see a list of the loadable subsystems that the system automatically configures at each reboot.

To add a subsystem to the list, use the /sbin/init.d/autosysconfig add command. For example to add the lat subsystem, enter the following command: 

# /sbin/init.d/autosysconfig add lat

If you unload a subsystem that is on the automatically configured subsystem list, you should remove that subsystem from the list. Otherwise, the system will configure the subsystem back into the kernel at the next system reboot. To remove the subsystem from the automatically configured subsystems list, use the /sbin/init.d/autosysconfig delete command. For example, to delete the lat subsystem, enter the following command: 


# /sbin/init.d/autosysconfig delete lat

4.4.6    Managing Subsystem Attributes

To improve the performance or behavior of a subsystem, or of the system as a whole, you might modify the values of subsystem attributes. You can make such modifications using sysconfig, sysconfigdb, or the Kernel Tuner (dxkerneltuner). Under certain circumstances, such as recovering a crashed system, you may also need to use the debugger dbx to examine and change the attributes in a damaged kernel. Refer to the Kernel Debugging guide for information on this procedure.

If you modify an attribute at run time, the modification persists only during the current run session. If you shut down and reboot the system, the modification is lost. To modify subsystem attributes so that changes persist across reboots, you must store the attribute's modified value in the /etc/sysconfigtab database, as described in Section 4.4.8. The persistence of a modified attribute value depends on what command or utility option you use, according to the following guidelines:

Note

In previous releases of the operating system, the /etc/sysconfigtab file was documented as a system file that you could modify with a text editor, such as vi. In recent releases, maintenance of the subsystem stanzas has become important for update installations and for the kernel to recognize changes. To maintain the correct structure of /etc/sysconfigtab, you should only use the sysconfigdb command or the dxkerneltuner interface to make changes.

See the sysconfig(8), sysconfigdb(8), sysconfigtab(4), and dxkerneltuner(8) reference pages for information.

The system parameters that are set in the system configuration file define the system tables, and should be viewed as establishing default values in the kernel. You can override these values by using the /sbin/sysconfig command or by storing a value in the /etc/sysconfigtab database. For more information about the configuration file (and the param.c file), see Section 4.5.

You can manage dynamic subsystem attributes either locally or remotely. For information on how to use the /sbin/sysconfig command remotely, see Section 4.4.7.

4.4.6.1    Determining the Current Value of Subsystem Attributes

Use the /sbin/sysconfig -q command or dxkerneltuner to determine the value assigned to subsystem attributes. When you enter the /sbin/sysconfig -q command, the subsystem you specify on the command line must be loaded and configured. For information about getting a list of the loaded and configured subsystems, see Section 4.4.2.

The following example shows how to use this command to determine which attributes belong to the generic subsystem: 


# /sbin/sysconfig -q generic
generic:
booted_kernel = vmunix
booted_args = vmunix
lockmode = 0
lockdebug = 0
locktimeout = 15
max_lock_per_thread = 16
lockmaxcycles = 0
rt_preempt_opt = 0
cpu_enable_mask = 0x1
binlog_buffer_size = 0
msgbuf_size = 32768
dump_sp_threshold = 4096
use_faulty_fpe_traps = 0
partial_dump = 1
make_partial_dumps = 1
compressed_dump = 1
make_compressed_dumps = 1
expected_dump_compression = 500
expect_1000b_to_compress_to = 500
dump_to_memory = 0
dump_allow_full_to_memory = 0
leave_dumps_in_memory = 0
dump_user_pte_pages = 0
live_dump_zero_suppress = 1
live_dump_dir_name = /var/adm/crash
include_user_ptes_in_dumps = 0
lite_system = 0
physio_max_coalescing = 65536
kmem_percent = 25
kmemreserve_percent = 0
kmem_debug = 0
kmem_debug_size_mask = 0
kmem_protected_size = 0
kmem_protected_lowat = 1000
kmem_protected_hiwat = 0
kmem_protected_kmempercent = 75
kmem_audit_count = 1024
kmemhighwater_16 = 4
.
.
.
kmemhighwater_12k = 4
old_obreak = 1
user_cfg_pt = 45000
memstr_buf_size = 0
memstr_start_addr = 0
memstr_end_addr = 0
memlimit = 0
insecure_bind = 0
memberid = 0
memberseq = 0
clu_configured = 0
clu_active_member = 0
old_vers_high = 0
old_vers_low = 0
act_vers_high = 1441151880873377792
act_vers_low = 15044
new_vers_high = 1441151880873377792
new_vers_low = 15044
versw_switch = 0
versw_transition = 0
rolls_ver_lookup = 0
login_name_max = 12
enable_async_printf = 1
 
 

(This display output has been truncated.)

4.4.6.2    Identifying Run-time Configurable Subsystem Attributes

You can identify which of a subsystem's attributes are configurable at run time using the /sbin/sysconfig -Q command: 

# /sbin/sysconfig -Q vfs max-vnodes
vfs:
max-vnodes -    type=INT op=CRQ min_val=0 max_val=1717986918
 
 

This example shows using the -Q option to get information about the max-vnodes attribute of the vfs subsystem. The max-vnodes attribute has the integer datatype, a minimum value of zero (0), and a maximum value of 1717986918. The op field indicates the operations that you can performed on the max-vnodes attribute. The following list describes the values that can appear in this field:

4.4.6.3    Modifying Attribute Values at Run Time

You can modify the value of an attribute at run time using the /sbin/sysconfig -r command, dxkerneltuner or the source level debugger dbx. The modification you make persists until the next time the system is rebooted. When the system reboots, any changes made with the /sbin/sysconfig -r command are lost because the new value is not stored. The -r option to the /sbin/sysconfig command is useful for testing a new subsystem attribute value. If the new value causes the system to perform as expected, you can later store it in the subsystem attribute database as described in Section 4.4.8. (Refer to the dbx(1) reference page and the System Configuration and Tuning guide for information on using dbx.)

When you use the /sbin/sysconfig -r command you specify the attribute, its new value, and the subsystem name on the command line. For example, to modify the dump-sp-threshold attribute for the generic subsystem, enter a command similar to the following: 

# /sbin/sysconfig -r generic dump-sp-threshold=20480

To modify the value of more than one attribute at a time, include a list on the /sbin/sysconfig command line. For example, to modify the dump-sp-threshold attribute and the locktimeout attribute, enter a command similar to the following: 


# /sbin/sysconfig -r generic dump-sp-threshold=20480 \
locktimeout=20

You do not include a comma between the two attribute specifications.

To make the attribute value permanent, you must add it to the /etc/sysconfigtab file using the appropriate method, for example, by specifying it as a boot time value using dxkerneltuner.

4.4.7    Managing Subsystems and Attributes Remotely

You can use the /sbin/sysconfig -h command to administer configurable subsystems and dynamic subsystem attributes remotely on a local area network (LAN). This ability allows you to administer several systems from a single machine.

Each system you want to administer remotely must have an /etc/cfgmgr.auth file that contains the full domain name of the local system. The name in the /etc/cfgmgr.auth file should be identical to the name in either the /etc/hosts file or in the Berkeley Internet Domain (BIND) or Network Information Service (NIS) hosts databases, if you are using BIND or NIS. You must create the /etc/cfgmgr.auth file; it is not on your system by default. The following shows an example cfgmgr.auth file: 

salmon.zk3.dec.com
trout.zk3.dec.com
bluefish.zk3.dec.com

To manage subsystems and attributes on remote systems, you include the -h option and a host name with the /sbin/sysconfig command. For example, to load the environmental monitoring lat subsystem on a remote host named MYSYS, enter the following command: 

# /sbin/sysconfig -h MYSYS -c lat

In this example, a lat.mod file must exist in either the /subsys directory or the /var/subsys directory on the remote system before you can load the specified subsystem. If the loadable subsystem subset is kitted correctly, the subsystem-name.mod file is installed on the remote system when you use the setld command to install the loadable subsystem.

4.4.8    Managing the Subsystem Attributes Database

Information about dynamically configurable subsystem attributes is stored in the /etc/sysconfigtab database. This database records the values assigned to subsystem attributes each time the system is rebooted or a subsystem is configured. No attributes are set automatically in this database. You must be the superuser to modify the /etc/sysconfigtab database and you must use the sysconfigdb command line utility or dxkerneltuner graphical utility to make the change. Refer to the online help for dxkerneltuner for more information on using that method.

Note

The /etc/sysconfigtab database might contain stanza entries from a configurable subsystem's stanza.loadable file. This file and the entry in the /etc/sysconfigtab database are created automatically when you install certain configurable subsystems. You should not modify these entries in the database.

There are multiple numbered versions of the sysconfigtab.* file in the /etc directory, but only the /etc/sysconfigtab version is used during normal operations. The versions are present to support the dynamic linking of modules to create a /vmunix kernel. This feature is called bootlinking and is documented in Guide to Preparing Product Kits. You may not be able to use bootlinking if you delete any copies of the sysconfigtab.* file.

To add, update, or remove entries in the database, you create a stanza-format file containing names and values for attributes you want to modify. (For information about stanza-format files, see stanza(4)). For example, suppose you want to set the lockmode attribute in the generic subsystem to 1. To set this attribute, create a file named, for example, generic_attrs that has the following contents: 

generic:
         lockmode = 1

After you create the stanza-format file, you use the /sbin/sysconfigdb command to update the /etc/sysconfigtab database. You name the stanza-format file on the command line using the -f option. The sysconfigdb command reads the specified file and updates both the on-disk and in-memory copy of the database. However, the running kernel is not updated. (Use the sysconfig -r command to update the running kernel, as described in Section 4.4.6.3.)

The sysconfigdb command has the following syntax options:

/sbin/sysconfigdb {-s}

/sbin/sysconfigdb -toutfile [-f infile -a | -usubsystem-name]

/sbin/sysconfigdb -toutfile [-f infile -m | -rsubsystem-name]

/sbin/sysconfigdb -toutfile [-f infile -d subsystem-name]

/sbin/sysconfigdb -toutfile [-f infile -l [ subsystem-name... ] ]

The following sections explain how to use the /sbin/sysconfigdb command to manage entries in the /etc/sysconfigtab database.

4.4.8.1    Listing Attributes in the Database

To list the entries in the /etc/sysconfigtab database, use the /sbin/sysconfigdb -l command. If you specify a subsystem name on the command line, the attributes of that subsystem are listed. Otherwise, all attributes defined in the database are listed.

For example, to list the attribute settings for the generic subsystem, enter the following command: 


# /sbin/sysconfigdb -l generic
generic:
        memberid = 0
        new_vers_high = 1441151880873377792
        new_vers_low = 15044
 
 

4.4.8.2    Adding Attributes to the Database

To add subsystem attributes to the /etc/sysconfigtab database, enter the sysconfigdb -a command.

For example, to add the entries stored in a file named add_attrs to the database, enter the following command: 


# /sbin/sysconfigdb -a -f add_attrs generic

4.4.8.3    Merging New Definitions into Existing Database Entries

To merge new definitions for attributes into an existing entry in the /etc/sysconfigtab database, enter the sysconfigdb -m command.

The sysconfigdb command merges the new definitions into the existing database entry as follows:

For example, assume that the following entry for the generic subsystem already exists in the /etc/sysconfigtab database: 

generic:
   lockmode = 4
   dump-sp-threshold = 6000

You then create a file named merge_attrs for updating this entry, which contains the following information: 

generic:
  lockmode = 0
  lockmaxcycles = 4294967295

To merge the information in the merge_attrs file into the /etc/sysconfigtab database, enter the following command: 

# /sbin/sysconfigdb -m -f merge_attrs generic

After the command finishes, the entry for the generic subsystem in the database appears as follows: 

generic:
   lockmode = 0
   lockmaxcycles = 4294967295
   dump-sp-threshold = 6000

You can merge definitions for more than one subsystem into the /etc/sysconfigtab database with a single sysconfigdb -m command. For example, the merge_attrs file could contain new definitions for attributes in the lsm and generic subsystems. If you include more than one subsystem name in the merge_attrs file, you omit the subsystem name from the command line, as shown: 

# /sbin/sysconfigdb -m -f merge_attrs

4.4.8.4    Updating Attributes in the Database

To update the entire definition of a subsystem that is already in the /etc/sysconfigtab database, enter the /sbin/sysconfigdb -u command.

For example, suppose the generic subsystem is defined as follows in the /etc/sysconfigtab file: 

generic:
   lockmode = 4
   dump-sp-threshold = 6000

Suppose that you create a file named update_attrs for updating this entry, which contains the following information: 

generic:
  lockmode = 0
  lockmaxcycles = 4294967295

To update the attributes, you enter the sysconfigdb command, as follows: 

# /sbin/sysconfigdb -u -f update_attrs generic

After the command finishes, the entry for the generic subsystem in the database appears as follows: 

generic:
   lockmode = 0
   lockmaxcycles = 4294967295

4.4.8.5    Removing Attribute Definitions from the Database

To remove the definitions of selected attributes from the /etc/sysconfigtab database, enter the /sbin/sysconfigdb -r command. The -r option specifies that you want to remove the attribute definitions stored in a file from the database.

For example, suppose the generic subsystem is defined as follows in the /etc/sysconfigtab database: 

generic:
  lockmode = 4
  dump-sp-threshold = 6000

To remove the definition of the dump-sp-threshold attribute, first create a file named remove_attrs that contains the following information: 

generic:
   dump-sp-threshold = 6000

Then, enter the following command: 

# /sbin/sysconfigdb -r -f remove_attrs generic

After the command finishes, the entry for the generic subsystem in the database appears as follows: 

generic:
   lockmode = 4

The /sbin/sysconfigdb command removes only identical entries. In other words, the entries must have the same attribute name and value to be removed.

You can remove definitions of more than one attribute and for attributes in more than one subsystem from /etc/sysconfigtab database with a single sysconfigdb -r command. For example, the remove_attrs file could contain attribute definitions that you want to remove for the lsm and generic subsystems. If you include more than one subsystem in the remove_attrs file, you omit the subsystem name from the command line, as shown: 

# /sbin/sysconfigdb -r -f remove_attrs

4.4.8.6    Deleting Subsystem Entries from the Database

To delete the definition of a subsystem from the /etc/sysconfigtab database enter the /sbin/sysconfigdb -d command.

For example, to delete the generic subsystem entry in the database, enter the following command: 


# /sbin/sysconfigdb -d generic

The generic subsystem receives its default values the next time it is configured.

4.5    Static System Configuration

Static system configuration refers to the commands and files used to build and boot a new kernel and its static subsystems. The subsystems are viewed as static because they are linked directly into the kernel at build time. The steps you take to build a statically linked kernel vary depending upon why you want to modify the kernel.

If you modify the kernel to add a device driver, you follow these general steps:

If you modify the kernel to add support for certain kernel options, you can build the new kernel by running the /usr/sbin/doconfig program and choosing the kernel option from a menu displayed during processing. You then shut down and reboot your system.

To determine which kernel options you can configure in this way, enter the /usr/sbin/kopt command. The command displays a list of kernel options and prompts you for kernel options selections. To exit from the /usr/sbin/kopt command without choosing options, press the Return key. For information about running the /usr/sbin/doconfig program to add kernel options using a menu, see Section 4.5.2.

If you build a new static kernel for any other reason, you must modify one or more system files as part of rebuilding the kernel. The system files you modify depend upon the change you want to make to the kernel:

For information about running the /usr/sbin/doconfig program to build a kernel after editing system files, see Section 4.5.3.

For examples of adding and configuring devices, refer to Chapter 5.

4.5.1    Building the Kernel to Add Support for a New Device

When you add a new device to the system and the device installation includes no SCP, you must edit the target configuration file to allow the operating system to support the new device. You include the device definition keyword in the target configuration file. Because the operating system supports many devices, determining which keyword to add to your target configuration file can be difficult.

The following procedure explains how to determine which device definition keyword to add to your target configuration file. It also explains how to rebuild the kernel once you have edited the target configuration file. The procedure assumes that you do not know the appropriate keyword to add. In some cases, you might be able to determine the appropriate keyword by looking at documentation supplied with the hardware or with a new version of the operating system. Another source of this information is an existing configuration file on another system that already has the device connected to it. If you know what keyword you need to add to your system, use a utility to add that keyword to your target configuration file and rebuild the kernel as described in Section 4.5.3.

Warning

This procedure is risky and you should ensure that you have a copy of your custom /vmunix kernel file, a copy of the generic kernel /genvmunix, and copies of the current configuration files. You may need the copies to revert to your previous configuration.

If you are unsure of the keyword you need to add to the target configuration file for your system, connect the new device to the system as directed in the hardware manual and use the following procedure:

  1. Check that you have a copy of the generic kernel, /genvmunix , as you will need to boot it later in the procedure. If the /genvmunix file does not exist on your system, or the generic kernel fails to recognize the device you are adding, copy the generic kernel from the software distribution media. Refer to the Installation Guide for information on the location of the generic kernel on the distribution CD-ROM.

    In rare cases, you may need to rebuild the generic kernel. However, you cannot rebuild the generic kernel if you have installed any layered applications or a third-party device driver. In this case, if the original /genvmunix is corrupt or has been deleted, and you have no distribution media you should contact your technical support organization and obtain a copy of the generic kernel /genvmunix.

    To verify whether layered applications have been installed, check the contents of the usr/sys/conf directory for a file named .product.list.

    To rebuild the generic kernel, you must have installed all the required and optional kernel subsets. You can get a list of the kernel build subsets, including information about whether or not they are installed, by issuing the following command: 

    # /usr/sbin/setld -i | grep Kernel Build

    After all kernel subsets are installed, enter the following command: 

    
# doconfig -c GENERIC

    The -c option specifies that you want to build a kernel using an existing configuration file, in this case the GENERIC configuration file. For more information about building a kernel from an existing configuration file, see Section 4.5.3.

    After the generic kernel is running and recognizes the new device, continue with step 5. When the build ends, consider using the strip command to reduce the size of the kernel. See the strip(1) reference page.

  2. Log in as root or become the superuser and set your default directory to the /usr/sys/conf directory.

  3. Save a copy of the existing /vmunix file. If possible, save the file in the root (/) directory, as follows: 

    # cp /vmunix /vmunix.save

    If there are disk space constraints, you can save the kernel file in a file system other than root. For example: 

    # cp /vmunix /usr/vmunix.save

  4. Shut down and halt the system as follows: 

    
# shutdown -h now

  5. At the console prompt, boot the generic kernel, /genvmunix. The generic kernel contains support for all valid devices, so if you boot it during the process of adding a new device to your target kernel, the generic kernel aleady knows the new device.

    To boot the generic kernel, enter the following command: 

    
>>> boot -fi "genvmunix"

  6. At the single-user mode prompt, check and mount local file systems by issuing the following command, unless you are using the Logical Storage Manager software (LSM): 

    # /sbin/bcheckrc

    If you are using the Logical Storage Manager (LSM) software, check local file systems and start LSM by issuing the following command: 

    # /sbin/lsmbstartup

  7. Run the sizer program to size your system hardware and create a new target configuration file that includes the new device: 

    # sizer -n MYSYS

    The sizer -n command creates a new target configuration file for your system that includes the appropriate device definition keyword for the new device. (This process is similar to the process that occurs at system installation time. For more information, see Section 4.2.) The sizer program stores the new target configuration file in the /tmp directory.

  8. Compare the new target configuration file created by sizer with the existing target configuration file for your system: 

    # diff /tmp/MYSYS MYSYS

    Check the differences between these files until you find the new device definition keyword. (The two files might differ in other ways if you have customized your existing configuration file, such as by specifying a nondefault value for the maxusers option.)

  9. Use the text editor of your choice to add the new device definition keyword to your existing configuration file (in this case, MYSYS). Adding the new keyword allows your existing configuration file to support the new device, without losing any changes you made to that file in the past.

    Note

    If you add or remove communications devices from your configuration file, you must edit the /etc/inittab file and the /etc/securettys file to match your new configuration; that is, to match the /dev/ttynn special device files. For more information, see inittab(4) and securettys(4).

  10. Build a new kernel by issuing the following /usr/sbin/doconfig command: 

    # /usr/sbin/doconfig -c MYSYS
 
*** KERNEL CONFIGURATION AND BUILD PROCEDURE ***
 
Saving /usr/sys/conf/MYSYS as /usr/sys/conf/MYSYS.bck
 
 

    Answer the following prompt to indicate that you do not want to edit the configuration file: 

    Do you want to edit the configuration file? (y/n) [n]: n
 
*** PERFORMING KERNEL BUILD ***

    .
    .
    .
    The new kernel is /usr/sys/MYSYS/vmunix
 
 

  11. When the kernel configuration and build process completes without errors, copy the new vmunix file to /vmunix. On a system named MYSYS, enter the following command: 

    # cp /usr/sys/MYSYS/vmunix /vmunix

    Always use copy (cp) instead of move (mv) to preserve the context dependent symbolic link (CDSL). Refer to Chapter 6 for more information on CDSLs.

  12. Reboot the system as follows: 

    
# /usr/sbin/shutdown -r now

If the new /vmunix file fails to boot, boot using the kernel you saved at the beginning of the procedure. To use the saved kernel, follow these steps:

  1. Check all local file systems by using the fsck -p command as follows: 

    # fsck -p

  2. Write-enable the root file system by using the mount -u command as follows: 

    
# mount -u /

  3. If necessary, mount the file system where the /vmunix.save file is stored. For example, if you copied the /vmunix file to the /usr file system, enter the following command: 

    # mount /usr

  4. Restore the saved copy. For example, if you saved your running kernel in the /vmunix.save file, enter the following command: 

    # mv /vmunix.save /vmunix

  5. Shut down and reboot the system, as follows: 

    
# shutdown -r now

After your system is running again, you can modify the target configuration file as needed and rebuild the kernel starting at step 3.

4.5.2    Building the Kernel to Add Selected Kernel Options

If you invoke the /usr/sbin/doconfig program without using options, you are given the opportunity to modify the kernel using a menu. To modify the kernel using a menu, follow these steps:

  1. Log in as root or become the superuser and set your default directory to the /usr/sys/conf directory.

  2. Save a copy of the existing /vmunix file. If possible, save the file in the root (/) directory, as follows: 

    # cp /vmunix /vmunix.save

    If there are disk space constraints, you can save the kernel file in a file system other than root. For example: 

    # cp /vmunix /usr/vmunix.save

  3. Run the /usr/sbin/doconfig program using no options, as follows: 

    # /usr/sbin/doconfig
 
*** KERNEL CONFIGURATION AND BUILD PROCEDURE ***
 
Saving /usr/sys/conf/MYSYS as /usr/sys/conf/MYSYS.bck

  4. Enter the name of the configuration file at the following prompt: 

    Enter a name for the kernel configuration \
file. [MYSYS]: MYSYS

    The kernel configuration processes convert the system name to uppercase when determining what name to supply as the default configuration file name. For example, on a system named mysys, the default configuration file is named MYSYS.

    If the configuration file name you specify does not currently exist, the /usr/sbin/doconfig program builds one with that name. Continue this process by selecting the kernel options in step 10.

  5. If the configuration file name you specify exists, answer the following prompt to indicate that you want to overwrite it: 

    
A configuration file with the name MYSYS already exists.
Do you want to replace it? (y/n) [n]: y

  6. Select kernel options from a menu similar to the following one: 

    *** KERNEL OPTION SELECTION ***
-----------------------------------------------------------
 
  Selection  Kernel Option
-----------------------------------------------------------
     1     System V Devices
     2     NTP V3 Kernel Phase Lock Loop (NTP_TIME)
     3     Kernel Breakpoint Debugger (KDEBUG)
     4     Packetfilter driver (PACKETFILTER)
     5     Point-to-Point Protocol (PPP)
     6     STREAMS pckt module (PCKT)
     7     Data Link Bridge (DLPI V2.0 Service Class 1)
     8     X/Open Transport Interface (XTISO, TIMOD, TIRDWR)
     9     ISO 9660 Compact Disc File System (CDFS)
     10    Audit Subsystem
     11    Alpha CPU performance/profiler (/dev/pfcntr)
     12    ACL Subsystem
     13    Logical Storage Manager (LSM)
     14    ATM UNI 3.0/3.1 ILMI (ATMILMI3X)
     15    IP Switching over ATM (ATMIFMP)
     16    LAN Emulation over ATM (LANE)
     17     Classical IP over ATM (ATMIP)
     18    ATM UNI 3.0/3.1 Signalling for SVCs (UNI3X)
     19    Asynchronous Transfer Mode (ATM)
     20    All of the above
     21    None of the above
     22    Help
     23    Display all options again
-----------------------------------------------------------
 
Enter the selection number for each kernel option you want.
For example, 1 3 [18]:

  7. Answer the following prompt to indicate whether or not you want to edit the configuration file: 

    Do you want to edit the configuration file? (y/n) [n]:
 

    You need not edit the configuration file unless you have changes other than adding one or more of the subsystems in the menu to the kernel.

    If you choose to edit the configuration file, the /usr/sbin/doconfig program invokes the editor specified by the EDITOR environment variable.

    For information about the configuration file, see Section 4.6

    After you finish editing the configuration file, the /usr/sbin/doconfig program builds a new kernel.

  8. When the kernel configuration and build process is completed without errors, move the new vmunix file to /vmunix. On a system named MYSYS, enter the following command: 

    # mv /usr/sys/MYSYS/vmunix /vmunix

  9. Reboot the system as follows: 

    
# /usr/sbin/shutdown -r now

If the new /vmunix file fails to boot, boot using the kernel you saved at the beginning of the procedure. To use the saved kernel, follow these steps:

  1. Check all local file systems by using the fsck -p command as follows: 

    # fsck -p

  2. Write-enable the root file system using the mount -u command as follows: 

    
# mount -u /

  3. If necessary, mount the file system where the /vmunix.save file is stored. For example, if you copied the /vmunix file to the /usr file system, enter the following command: 

    # mount /usr

  4. Restore the saved copy. For example, if you saved your running kernel in the /vmunix.save file, enter the following command: 

    # mv /vmunix.save /vmunix

  5. Shut down and reboot the system, as follows: 

    
# shutdown -r now

After your system is running again, you can modify the target configuration file as needed and rebuild the kernel starting at step 3.

4.5.3    Building a Kernel After Modifying System Files

If you or an SCP modify system files, such as the target configuration file, you can rebuild your kernel using the /usr/sbin/doconfig -c command. The -c option allows you to name an existing configuration file, which the /usr/sbin/doconfig program uses to build the kernel. To build a new kernel using an existing configuration file, follow these steps:

  1. Log in as root or become the superuser and set your default directory to the /usr/sys/conf directory.

  2. Save a copy of the existing /vmunix file. If possible, save the file in the root (/) directory, as follows: 

    # cp /vmunix /vmunix.save

    If there are disk space constraints, you can save the kernel file in a file system other than root. For example: 

    # cp /vmunix /usr/vmunix.save

  3. Run the /usr/sbin/doconfig program specifying the name of the target configuration file with the -c option. For example on a system named MYSYS, enter the following command: 

    # /usr/sbin/doconfig -c MYSYS 
 
*** KERNEL CONFIGURATION AND BUILD PROCEDURE ***
 
Saving /usr/sys/conf/MYSYS as /usr/sys/conf/MYSYS.bck

  4. Answer the following prompt to indicate whether or not you want to edit the configuration file: 

    Do you want to edit the configuration file? (y/n) [n]:
 

    If you modified the configuration file before you started this procedure, indicate that you do not want to edit the configuration file.

    If you choose to edit the configuration file, the /usr/sbin/doconfig program invokes the editor specified by the EDITOR environment variable.

    For information about the configuration file, see Section 4.6

    After you finish editing the configuration file, the /usr/sbin/doconfig program builds a new kernel.

  5. When the kernel configuration and build are completed without errors, move the new vmunix file to /vmunix. On a system named MYSYS, enter the following command: 

    # mv /usr/sys/MYSYS/vmunix /vmunix

  6. Reboot the system as follows: 

    
# /usr/sbin/shutdown -r now

If the new /vmunix file fails to boot, boot using the kernel you saved at the beginning of the procedure. To use the saved kernel, follow these steps:

  1. Check all local file systems by using the fsck -p command as follows: 

    # fsck -p

  2. Write-enable the root file system using the mount -u command as follows: 

    
# mount -u /

  3. If necessary, mount the file system where the /vmunix.save file is stored. For example, if you copied the /vmunix file to the /usr file system, enter the following command: 

    # mount /usr

  4. Restore the saved copy. For example, if you saved your running kernel in the /vmunix.save file, enter the following command: 

    # mv /vmunix.save /vmunix

  5. Shut down and reboot the system, as follows: 

    
# shutdown -r now

After your system is running again, you can modify the target configuration file as needed and rebuild the kernel starting at step 3.

4.6    Configuration Files

To build and run a working kernel, the system depends on the presence of specific directories under the /usr/sys directory. Figure 4-1 shows the directory structure of the system configuration files. The dotted lines indicate optional directories and files for third-party static subsystems.

Figure 4-1:  Configuration Files Directory Hierarchy

As shown in Figure 4-1, the /usr/sys/conf directory contains files that define the kernel configuration for the generic and target kernels. These files represent the configuration of the static portion of the kernel. When you work with the system files to reconfigure the kernel, you are interested primarily in five files:

The following sections provide more information about these files.

4.6.1    Configuration Files in /usr/sys/conf

The /usr/sys/conf directory contains two important system configuration files:

4.6.2    Extensions to the Target Configuration File

The /usr/sys/conf directory contains two optional configuration files that describe extensions to the target configuration file. These are the /usr/sys/conf/.product.list file and the /usr/sys/conf/NAME file. These files store information about static kernel subsystems, sometimes called kernel layered products.

When you install a static subsystem, its SCP normally edits the /usr/sys/conf/.product.list file and adds an entry for the subsystem. After the SCP has completed, run the /usr/sbin/doconfig program to configure the new subsystem into the kernel.

The /usr/sbin/doconfig program creates the NAME.list file. The NAME variable is the same as the target configuration file, and by convention is your system name in capital letters. For example, the NAME.list file for a system named MYSYS is MYSYS.list.

If you need to modify your system because of a third-party layered product (for example, to remove a layered product from the kernel being built), make the necessary modifications to the NAME.list file and build a new kernel.

Each entry in the NAME.list file consists of six fields separated by a colon ( : ). The following example is part of a NAME.list file and shows an entry for a static kernel subsystem that has been loaded into the /usr/sys/opt/ESB100 directory: 

/usr/sys/opt/ESB100:UNXDASH100:920310100739:DASH Systems:controlsys:100
     [1]           [2]       [3]        [4]       [5]     [6]

The fields in this entry contain the following information:

  1. The full pathname where the system configuration tools will find extensions to input data. This location can contain files such as:

    [Return to example]

  2. The setld subset identifier. [Return to example]

  3. The date and time that the product is ready for distribution. [Return to example]

  4. The name of the company that provided the subsystem. [Return to example]

  5. The product name. [Return to example]

  6. The setld 3-digit product version code. [Return to example]

The order of the line entries in the NAME.list file reflects the order in which the entries are processed.

The /usr/sbin/doconfig program creates the NAME.list file by copying the .product.list file, if it exists. When you use the /usr/sbin/doconfig -c command option, /usr/sbin/doconfig uses the existing NAME.list file. If the .product.list file changes (for example, a new kernel layered product was installed) and the -c option is used, either delete the NAME.list file or manually edit it before invoking /usr/sbin/doconfig to propagate the change in the .product.list file to the NAME.list file.

You can also create the file by copying the .product.list file to the NAME.list file. You can then edit the NAME.list file and either delete the lines that you do not want built into the kernel or comment them out by putting a number sign ( # ) as the first character in each line that you do not want.

Note

Never edit the .product.list file.

Refer to the device driver documentation for more information on the NAME.list and .product.list files.

4.6.3    The param.c File

The param.c file contains default values for a number of system parameters. Do not modify these parameters unless instructed to do so in a document or by your technical support organization.

The precedence order in which attribute values are read and used is as follows:

  1. The run-time value of the attribute.

  2. The value recorded in the /etc/sysconfigtab file.

  3. The value recorded in the /usr/sys/conf/SYSTEM_NAME file.

  4. The value recorded in the /usr/sys/conf/param.c file.

In some cases, a parameter in the param.c file also exists in your target configuration file. In this case, a value specified in the configuration file overrides the value specified in the param.c file. Therefore, if you modify the value of a system parameter in the param.c file, be sure to remove the corresponding entry from the target configuration file.

4.6.4    System Configuration File Entries

The system configuration file contains the following keyword definitions:

Avoid performing manual tuning or custom configuration options in this file. Refer to the System Configuration and Tuning guide for information on configuring a kernel and tuning it.