1.\" $OpenBSD: config.8,v 1.75 2021/11/20 03:13:37 jcs Exp $ 2.\" $NetBSD: config.8,v 1.10 1996/08/31 20:58:16 mycroft Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" from: @(#)config.8 8.2 (Berkeley) 4/19/94 32.\" 33.Dd $Mdocdate: November 20 2021 $ 34.Dt CONFIG 8 35.Os 36.Sh NAME 37.Nm config 38.Nd build kernel compilation directories or modify a kernel 39.Sh SYNOPSIS 40.Nm config 41.Op Fl p 42.Op Fl b Ar builddir 43.Op Fl s Ar srcdir 44.Op Ar config-file 45.Nm config 46.Fl e 47.Op Fl u 48.Op Fl c Ar cmdfile 49.Op Fl f | o Ar outfile 50.Ar infile 51.Sh DESCRIPTION 52In the first synopsis form, the 53.Nm 54program creates a kernel build directory from the kernel configuration file 55specified by 56.Ar config-file . 57.Pp 58In the second synopsis form, 59.Nm 60allows editing of the kernel binary specified by 61.Ar infile . 62Devices may be enabled, disabled, or modified without recompiling, 63by editing the kernel executable. 64Similarly, the same editing can be done at boot-time, 65using the in-kernel editor, 66as described in 67.Xr boot_config 8 . 68Note that any such edits will be lost during upgrades and prevent a newly 69linked kernel from being installed at boot time. 70For such cases, this process can also be automated during boot using the 71.Xr bsd.re-config 5 72configuration file. 73.Pp 74For kernel building, the options are as follows: 75.Bl -tag -width Ds 76.It Fl b Ar builddir 77Create the build directory in the path specified by 78.Ar builddir 79instead of the default 80.Pa ../compile/SYSTEMNAME . 81.It Fl p 82Configure for a system that includes profiling code; see 83.Xr kgmon 8 84and 85.Xr gprof 1 . 86When this option is specified, 87.Nm 88acts as if the lines 89.Dq makeoptions PROF="-pg" 90and 91.Dq option GPROF 92appeared in the specified kernel configuration file. 93In addition, 94.Dq .PROF 95is appended to the default compilation directory name. 96.Pp 97The 98.Fl p 99flag is expected to be used for 100.Dq one-shot 101profiles of existing systems; for regular profiling, it is probably wiser to 102make a separate configuration containing the makeoptions line. 103.It Fl s Ar srcdir 104Use 105.Ar srcdir 106as the top-level kernel source directory instead of the default (four 107directories above the build directory). 108.El 109.Pp 110For kernel modification, the options are as follows: 111.Bl -tag -width Ds 112.It Fl c Ar cmdfile 113Read commands and answers from the specified file instead of the standard 114input. 115Save and quit automatically when the end of file is reached. 116.It Fl e 117Allows the modification of kernel device configuration (see 118.Xr boot_config 8 ) . 119Temporary changes can be made to the running kernel's configuration or a new 120kernel binary may be written for permanent changes between system reboots. 121See the section 122.Sx KERNEL MODIFICATION 123below for more details. 124.It Fl f 125Overwrite the 126.Ar infile 127kernel binary with the modified kernel. 128Otherwise, 129.Fl o 130should be given to specify an alternate output file. 131.It Fl o Ar outfile 132Write the modified kernel to 133.Ar outfile . 134.It Fl u 135Check to see if the kernel configuration was modified at boot-time 136(i.e.\& 137.Cm boot -c 138was used). 139If so, compare the running kernel with the kernel to be edited 140.Pq Ar infile . 141If they seem to be the same, apply all configuration changes performed at 142boot. 143Using this option requires read access to 144.Pa /dev/mem , 145which may be restricted based upon the value of the 146.Ar kern.allowkmem 147.Xr sysctl 8 . 148.El 149.Sh KERNEL BUILDING 150The output of 151.Nm 152consists of a number of files, principally 153.Pa ioconf.c 154(a description of I/O devices that may be attached to the system) 155and a 156.Pa Makefile , 157used by 158.Xr make 1 159when building the kernel. 160.Pp 161If 162.Nm 163stops due to errors, the problems reported should be corrected and 164.Nm 165should be run again. 166.Nm 167attempts to avoid changing the compilation directory if there are 168configuration errors, but this code is not well-tested and some problems 169(such as running out of disk space) are unrecoverable. 170.Pp 171If 172.Ar config-file 173is not specified, 174.Nm 175uses the current directory as the build directory, and looks in it for 176a file called 177.Pa CONFIG . 178If 179.Nm 180is run this way, the location of the top-level kernel source 181directory must be specified using the 182.Fl s 183option or by using the 184.Dq Li source 185directive at the beginning of the system configuration file. 186.Pp 187The configuration files consists of various statements which 188include the following: 189.Bl -tag -offset indent -width indent 190.It Ic machine Ar var 191Required. 192Specifies the machine architecture. 193.It Ic include Ar file 194Include another configuration file. 195.It Ic option Ar name 196Set a kernel option. 197Kernel options may take either the form 198.Ar NAME 199or the form 200.Ar NAME Ns = Ns Ar value . 201These options are passed to the compiler with the 202.Fl D 203flag. 204.It Ic rmoption Ar name 205Delete a previously set option. 206This is useful when including another kernel configuration file. 207A typical use is to include the 208.Va GENERIC 209kernel provided with each release and remove options that are 210unwanted, thus allowing for automatic inclusion of new device 211drivers. 212.It Ic maxusers Ar number 213Required. 214Used to size various system tables and maximum operating conditions 215in an approximate fashion. 216Multiple instances of this keyword may be specified. 217The number provided in the last instance will be used, and 218warnings will be printed for each duplicate value. 219This is convenient when used with the 220.Va include 221directive. 222.It Xo Ic config Cm bsd root on Ar dev 223.Op Cm swap on Ar dev Op Cm and Ar dev ... 224.Op Cm dumps on Ar dev 225.Xc 226Required. 227Specifies the swap and dump devices which the system should use. 228.It Ic config Cm bsd swap generic 229Otherwise, if generic is specified, the system follows generic routines to 230decide what should happen. 231.El 232.Pp 233To debug kernels and their crash dumps with gdb, add 234.Dq makeoptions DEBUG="-g" 235to the kernel configuration file. 236Refer to 237.Xr options 4 238for further details. 239.Pp 240Many other statements exist, and the file format is fairly rich; for more 241information see the various configuration files included in the system, as 242well as 243.Xr files.conf 5 244for the 245.Nm 246rules base. 247.Sh KERNEL MODIFICATION 248When 249.Fl e 250is specified, device parameters that are normally hard-coded into the kernel 251may be changed. 252This is useful to avoid the need for kernel recompilation or rebooting. 253Modifications are made to the currently running kernel and can be written to 254a new kernel binary so changes are preserved during subsequent system restarts. 255.Pp 256When invoked, the kernel identification is first shown. 257.Bd -literal -offset indent 258# config -e -o bsd.new /bsd 259OpenBSD 5.3-current (GENERIC.MP) #91: Mon Mar 25 16:43:17 MDT 2013 260 deraadt@i386.openbsd.org:/usr/src/sys/arch/i386/compile/GENERIC.MP 261Enter 'help' for information 262ukc> 263.Ed 264.Pp 265One or more warnings may be printed before the 266.Li ukc> 267prompt. 268.Bd -literal -offset indent 269warning: no output file specified 270.Ed 271.Pp 272Neither the 273.Fl f 274nor 275.Fl o 276option has been specified. 277Changes will be ignored. 278.Bd -literal -offset indent 279WARNING kernel mismatch. -u ignored. 280WARNING the running kernel version: 281.Ed 282.Pp 283.Nm 284does not believe the running kernel is the same as the 285.Ar infile 286specified. 287Since the log of changes (from 288.Cm boot -c ) 289in the running kernel is kernel-specific, the 290.Fl u 291option is ignored. 292.Pp 293The commands are as follows: 294.Bl -tag -width "disable attr val | devno | dev" 295.It Ic add Ar dev 296Add a device through copying another. 297.It Ic base Cm 8 | 10 | 16 298Change the base of numbers displayed and entered. 299.It Ic change Ar devno | dev 300Modify one or more devices. 301.It Ic disable Ar attr val | devno | dev 302Disable one or more devices. 303.It Ic enable Ar attr val | devno | dev 304Enable one or more devices. 305.It Ic exit 306Exit without saving changes. 307.It Ic find Ar devno | dev 308Find one or more devices. 309.It Ic help 310Give a short summary of all commands and their arguments. 311.It Ic lines Op Ar count 312Set the number of rows per page. 313.It Ic list 314Show all known devices, a screen at a time. 315.It Ic nkmempg Op Ar number 316Change the NKMEMPAGES value. 317Without arguments, displays its current value. 318.It Ic quit 319Exit and save changes. 320.It Ic show Op Ar attr Op Ar val 321Show all devices for which attribute 322.Ar attr 323has the value 324.Ar val . 325.El 326.Sh EXIT STATUS 327.Ex -std 328.Sh EXAMPLES 329The Ethernet card is not detected at boot because the kernel configuration 330does not match the physical hardware configuration, 331e.g. wrong IRQ in OpenBSD/i386. 332The Ethernet card is supposed to use the 333.Xr ne 4 334driver. 335.Bd -literal 336.No ukc> Ic find ne 33724 ne0 at isa0 port 0x240 size 0 iomem 0xd8000 iosiz 0 irq 9 drq -1 drq2 -1 flags 0x0 33825 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0 33926 ne* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 flags 0x0 34027 ne* at pci* dev -1 function -1 flags 0x0 34128 ne* at pcmcia* function -1 irq -1 flags 0x0 342ukc> 343.Ed 344.Pp 345ne1 seems to match the configuration except it uses IRQ 10 instead of IRQ 5. 346So the irq on ne1 should be changed via the 347.Ic change 348command. 349The device can be specified by either name or number. 350.Bd -literal 351.No ukc> Ic change ne1 35225 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 353.No change (y/n) \&? Ic y 354.No port [0x300] \&? 355.No size [0] \&? 356.No iomem [-1] \&? 357.No iosiz [0] \&? 358.No irq [10] \&? Ic 5 359.No drq [-1] \&? 360.No drq2 [-1] \&? 361.No flags [0] \&? 36225 ne1 changed 36325 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 5 drq -1 drq2 -1 flags 0x0 364ukc> 365.Ed 366.Pp 367It's also possible to disable all devices with a common attribute. 368For example: 369.Bd -literal 370.No ukc> Ic disable port 0x300 371 25 ne1 disabled 372 72 we1 disabled 373 75 el0 disabled 374 77 ie1 disabled 375.Ed 376.Pp 377The 378.Cm show 379command is useful for finding which devices have a certain attribute. 380It can also be used to find those devices with a particular value for 381an attribute. 382.Bd -literal 383.No ukc> Ic show slot 384 2 ahc* at eisa0 slot -1 385 10 uha* at eisa0 slot -1 386 12 ep0 at eisa0 slot -1 387 17 ep* at eisa0 slot -1 388102 ahb* at eisa0 slot -1 389103 fea* at eisa0 slot -1 390.No ukc> Ic show port 0x300 391 25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0 392 72 we1 at isa0 port 0x300 size 0 iomem 0xcc000 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0 393 75 el0 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 9 drq -1 drq2 -1 flags 0x0 394 77 ie1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0 395ukc> 396.Ed 397.Pp 398It is possible to add new devices, but only devices that were linked into the 399kernel. 400If a new device is added, following devices will be renumbered. 401.Bd -literal 402.No ukc> Ic find ep 403 11 ep0 at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1 flags 0x0 404 12 ep0 at eisa0 slot -1 flags 0x0 405 13 ep0 at pci* dev -1 function -1 flags 0x0 406 14 ep* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 flags 0x0 407 15 ep* at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1 flags 0x0 408 16 ep* at eisa0 slot -1 flags 0x0 409 17 ep* at pci* dev -1 function -1 flags 0x0 410 18 ep* at pcmcia* dev -1 irq -1 flags 0x0 411.No ukc> Ic add ep1 412.No "Clone Device (DevNo, 'q' or '\&?') \&?" Ic 13 413.No "Insert before Device (DevNo, 'q' or '\&?')" Ic 14 414 14 ep1 at pci* dev -1 function -1 415.No ukc> Ic change 14 416 14 ep1 at pci* dev -1 function -1 417.No change (y/n) \&? Ic y 418.No dev [-1] \&? Ic 14 419.No function [-1] \&? 420.No flags [0] \&? Ic 18 421 14 ep1 changed 422 14 ep1 at pci* dev 14 function -1 flags 0x12 423ukc> 424.Ed 425.Pp 426When done, exit the program with the 427.Ic quit 428or 429.Ic exit 430commands. 431.Ic exit 432will ignore any changes while 433.Ic quit 434writes the changes to 435.Ar outfile 436(if 437.Fl o 438or 439.Fl f 440was given, else ignore changes). 441.Bd -literal 442.No ukc> Ic quit 443.Ed 444.Sh SEE ALSO 445.Xr options 4 , 446.Xr bsd.re-config 5 , 447.Xr files.conf 5 , 448.Xr boot.conf 8 , 449.Xr boot_config 8 450.Pp 451The SYNOPSIS portion of each device in section 4 of the manual. 452.Rs 453.\" 4.4BSD SMM:2 454.%A S. J. Leffler 455.%A M. J. Karels 456.%T "Building 4.4 BSD Systems with Config" 457.%B 4.4BSD System Manager's Manual (SMM) 458.Re 459.Sh HISTORY 460The 461.Nm 462program appeared in 463.Bx 4.1 464and was completely revised in 465.Bx 4.4 . 466The 467.Fl e 468option appeared in 469.Ox 2.6 . 470.Sh BUGS 471Included files should start with an empty line or comment. 472