CONFIG(8) | System Manager's Manual | CONFIG(8)

# NAME

`config` — build kernel compilation directories or modify a kernel

# SYNOPSIS

`config` | [`-p`] [`-b` builddir] [`-s` srcdir] [config-file]

`config` | `-e` [`-u`] [`-c` cmdfile] [`-f` | `-o` outfile] infile

# DESCRIPTION

In the first synopsis form, the `config` program creates a kernel build directory from the kernel configuration file specified by config-file.

In the second synopsis form, `config` allows editing of the kernel binary specified by infile. Devices may be enabled, disabled, or modified without recompiling, by editing the kernel executable. Similarly, the same editing can be done at boot-time, using the in-kernel editor, as described in boot_config(8). Note that any such edits will be lost during upgrades and prevent a newly linked kernel from being installed at boot time. For such cases, this process can also be automated during boot using the bsd.re-config(5) configuration file.

For kernel building, the options are as follows:

`-b` builddir
  Create the build directory in the path specified by builddir instead of the default ../compile/SYSTEMNAME.
`-p`
  Configure for a system that includes profiling code; see kgmon(8) and gprof(1). When this option is specified, `config` acts as if the lines “makeoptions PROF="-pg"” and “option GPROF” appeared in the specified kernel configuration file. In addition, “.PROF” is appended to the default compilation directory name.

  The `-p` flag is expected to be used for “one-shot” profiles of existing systems; for regular profiling, it is probably wiser to make a separate configuration containing the makeoptions line.

`-s` srcdir
  Use srcdir as the top-level kernel source directory instead of the default (four directories above the build directory).

For kernel modification, the options are as follows:

`-c` cmdfile
  Read commands and answers from the specified file instead of the standard input. Save and quit automatically when the end of file is reached.
`-e`
  Allows the modification of kernel device configuration (see boot_config(8)). Temporary changes can be made to the running kernel's configuration or a new kernel binary may be written for permanent changes between system reboots. See the section KERNEL MODIFICATION below for more details.
`-f`
  Overwrite the infile kernel binary with the modified kernel. Otherwise, `-o` should be given to specify an alternate output file.
`-o` outfile
  Write the modified kernel to outfile.
`-u`
  Check to see if the kernel configuration was modified at boot-time (i.e. `boot -c` was used). If so, compare the running kernel with the kernel to be edited (infile). If they seem to be the same, apply all configuration changes performed at boot. Using this option requires read access to /dev/mem, which may be restricted based upon the value of the kern.allowkmem sysctl(8).

# KERNEL BUILDING

The output of `config` consists of a number of files, principally ioconf.c (a description of I/O devices that may be attached to the system) and a Makefile, used by make(1) when building the kernel.

If `config` stops due to errors, the problems reported should be corrected and `config` should be run again. `config` attempts to avoid changing the compilation directory if there are configuration errors, but this code is not well-tested and some problems (such as running out of disk space) are unrecoverable.

If config-file is not specified, `config` uses the current directory as the build directory, and looks in it for a file called CONFIG. If `config` is run this way, the location of the top-level kernel source directory must be specified using the `-s` option or by using the “`source`” directive at the beginning of the system configuration file.

The configuration files consists of various statements which include the following:

`machine` var
  Required. Specifies the machine architecture.
`include` file
  Include another configuration file.
`option` name
  Set a kernel option. Kernel options may take either the form NAME or the form NAME=value. These options are passed to the compiler with the `-D` flag.
`rmoption` name
  Delete a previously set option. This is useful when including another kernel configuration file. A typical use is to include the GENERIC kernel provided with each release and remove options that are unwanted, thus allowing for automatic inclusion of new device drivers.
`maxusers` number
  Required. Used to size various system tables and maximum operating conditions in an approximate fashion. Multiple instances of this keyword may be specified. The number provided in the last instance will be used, and warnings will be printed for each duplicate value. This is convenient when used with the include directive.
`config` `bsd root on` dev [`swap on` dev [`and` dev ...]] [`dumps on` dev]
  Required. Specifies the swap and dump devices which the system should use.
`config` `bsd swap generic`
  Otherwise, if generic is specified, the system follows generic routines to decide what should happen.

To debug kernels and their crash dumps with gdb, add “makeoptions DEBUG="-g"” to the kernel configuration file. Refer to options(4) for further details.

Many other statements exist, and the file format is fairly rich; for more information see the various configuration files included in the system, as well as files.conf(5) for the `config` rules base.

# KERNEL MODIFICATION

When `-e` is specified, device parameters that are normally hard-coded into the kernel may be changed. This is useful to avoid the need for kernel recompilation or rebooting. Modifications are made to the currently running kernel and can be written to a new kernel binary so changes are preserved during subsequent system restarts.

When invoked, the kernel identification is first shown.

    # config -e -o bsd.new /bsd
    OpenBSD 5.3-current (GENERIC.MP) #91: Mon Mar 25 16:43:17 MDT 2013
        deraadt@i386.openbsd.org:/usr/src/sys/arch/i386/compile/GENERIC.MP
    Enter 'help' for information
    ukc>

One or more warnings may be printed before the `ukc>` prompt.

    warning: no output file specified

Neither the `-f` nor `-o` option has been specified. Changes will be ignored.

    WARNING kernel mismatch. -u ignored.
    WARNING the running kernel version:

`config` does not believe the running kernel is the same as the infile specified. Since the log of changes (from `boot -c`) in the running kernel is kernel-specific, the `-u` option is ignored.

The commands are as follows:

`add` dev
  Add a device through copying another.
`base` `8` | `10` | `16`
  Change the base of numbers displayed and entered.
`change` devno | dev
  Modify one or more devices.
`disable` attr val | devno | dev
  Disable one or more devices.
`enable` attr val | devno | dev
  Enable one or more devices.
`exit`
  Exit without saving changes.
`find` devno | dev
  Find one or more devices.
`help`
  Give a short summary of all commands and their arguments.
`lines` [count]
  Set the number of rows per page.
`list`
  Show all known devices, a screen at a time.
`nkmempg` [number]
  Change the NKMEMPAGES value. Without arguments, displays its current value.
`quit`
  Exit and save changes.
`show` [attr [val]]
  Show all devices for which attribute attr has the value val.
`#` [cmd]
  Ignored. Allows comments in bsd.re-config(5).

# EXIT STATUS

The `config` utility exits 0 on success, and >0 if an error occurs.

# EXAMPLES

The Ethernet card is not detected at boot because the kernel configuration does not match the physical hardware configuration, e.g. wrong IRQ in OpenBSD/i386. The Ethernet card is supposed to use the ne(4) driver.

    ukc> find ne
    24 ne0 at isa0 port 0x240 size 0 iomem 0xd8000 iosiz 0 irq 9 drq -1 drq2 -1 flags 0x0
    25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
    26 ne* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 flags 0x0
    27 ne* at pci* dev -1 function -1 flags 0x0
    28 ne* at pcmcia* function -1 irq -1 flags 0x0
    ukc>

ne1 seems to match the configuration except it uses IRQ 10 instead of IRQ 5. So the irq on ne1 should be changed via the `change` command. The device can be specified by either name or number.

    ukc> change ne1
    25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1
    change (y/n) ? y
    port [0x300] ?
    size [0] ?
    iomem [-1] ?
    iosiz [0] ?
    irq [10] ? 5
    drq [-1] ?
    drq2 [-1] ?
    flags [0] ?
    25 ne1 changed
    25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 5 drq -1 drq2 -1 flags 0x0
    ukc>

It's also possible to disable all devices with a common attribute. For example:

    ukc> disable port 0x300
     25 ne1 disabled
     72 we1 disabled
     75 el0 disabled
     77 ie1 disabled

The `show` command is useful for finding which devices have a certain attribute. It can also be used to find those devices with a particular value for an attribute.

    ukc> show slot
      2 ahc* at eisa0 slot -1
     10 uha* at eisa0 slot -1
     12 ep0 at eisa0 slot -1
     17 ep* at eisa0 slot -1
    102 ahb* at eisa0 slot -1
    103 fea* at eisa0 slot -1
    ukc> show port 0x300
     25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
     72 we1 at isa0 port 0x300 size 0 iomem 0xcc000 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
     75 el0 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 9 drq -1 drq2 -1 flags 0x0
     77 ie1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0
    ukc>

It is possible to add new devices, but only devices that were linked into the kernel. If a new device is added, following devices will be renumbered.

    ukc> find ep
     11 ep0 at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1 flags 0x0
     12 ep0 at eisa0 slot -1 flags 0x0
     13 ep0 at pci* dev -1 function -1 flags 0x0
     14 ep* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 flags 0x0
     15 ep* at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1 flags 0x0
     16 ep* at eisa0 slot -1 flags 0x0
     17 ep* at pci* dev -1 function -1 flags 0x0
     18 ep* at pcmcia* dev -1 irq -1 flags 0x0
    ukc> add ep1
    Clone Device (DevNo, 'q' or '?') ? 13
    Insert before Device (DevNo, 'q' or '?') 14
     14 ep1 at pci* dev -1 function -1
    ukc> change 14
     14 ep1 at pci* dev -1 function -1
    change (y/n) ? y
    dev [-1] ? 14
    function [-1] ?
    flags [0] ? 18
     14 ep1 changed
     14 ep1 at pci* dev 14 function -1 flags 0x12
    ukc>

When done, exit the program with the `quit` or `exit` commands. `exit` will ignore any changes while `quit` writes the changes to outfile (if `-o` or `-f` was given, else ignore changes).

    ukc> quit

# SEE ALSO

options(4), bsd.re-config(5), files.conf(5), boot.conf(8), boot_config(8)

The SYNOPSIS portion of each device in section 4 of the manual.

S. J. Leffler and M. J. Karels, Building 4.4 BSD Systems with Config, 4.4BSD System Manager's Manual (SMM).

# HISTORY

The `config` program appeared in 4.1BSD and was completely revised in 4.4BSD. The `-e` option appeared in OpenBSD 2.6.

# BUGS

Included files should start with an empty line or comment.

May 19, 2025 | Debian