1.\" $OpenBSD: config.8,v 1.61 2016/03/13 08:39:29 jmc 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: March 13 2016 $ 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.Op Fl u 47.Op Fl f | o Ar outfile 48.Fl e 49.Ar infile 50.Sh DESCRIPTION 51In the first synopsis form, the 52.Nm 53program creates a kernel build directory from the kernel configuration file 54specified by 55.Ar config-file . 56.Pp 57In the second synopsis form, 58.Nm 59allows editing of the kernel binary specified by 60.Ar infile . 61Devices may be enabled, disabled, or modified without recompiling, 62by editing the kernel executable. 63Similarly, the same editing can be done at boot-time, 64using the in-kernel editor, 65as described in 66.Xr boot_config 8 . 67.Pp 68For kernel building, the options are as follows: 69.Bl -tag -width Ds 70.It Fl b Ar builddir 71Create the build directory in the path specified by 72.Ar builddir 73instead of the default 74.Pa ../compile/SYSTEMNAME . 75.It Fl p 76Configure for a system that includes profiling code; see 77.Xr kgmon 8 78and 79.Xr gprof 1 . 80When this option is specified, 81.Nm 82acts as if the lines 83.Dq makeoptions PROF="-pg" 84and 85.Dq option GPROF 86appeared in the specified kernel configuration file. 87In addition, 88.Dq .PROF 89is appended to the default compilation directory name. 90.Pp 91The 92.Fl p 93flag is expected to be used for 94.Dq one-shot 95profiles of existing systems; for regular profiling, it is probably wiser to 96make a separate configuration containing the makeoptions line. 97.It Fl s Ar srcdir 98Use 99.Ar srcdir 100as the top-level kernel source directory instead of the default (four 101directories above the build directory). 102.El 103.Pp 104For kernel modification, the options are as follows: 105.Bl -tag -width Ds 106.It Fl e 107Allows the modification of kernel device configuration (see 108.Xr boot_config 8 ) . 109Temporary changes can be made to the running kernel's configuration or a new 110kernel binary may be written for permanent changes between system reboots. 111See the section 112.Sx KERNEL MODIFICATION 113below for more details. 114.It Fl f 115Overwrite the 116.Ar infile 117kernel binary with the modified kernel. 118Otherwise, 119.Fl o 120should be given to specify an alternate output file. 121.It Fl o Ar outfile 122Write the modified kernel to 123.Ar outfile . 124.It Fl u 125Check to see if the kernel configuration was modified at boot-time 126(i.e.\& 127.Cm boot -c 128was used). 129If so, compare the running kernel with the kernel to be edited 130.Pq Ar infile . 131If they seem to be the same, apply all configuration changes performed at 132boot. 133.El 134.Sh KERNEL BUILDING 135The output of 136.Nm 137consists of a number of files, principally 138.Pa ioconf.c 139(a description of I/O devices that may be attached to the system) 140and a 141.Pa Makefile , 142used by 143.Xr make 1 144when building the kernel. 145.Pp 146If 147.Nm 148stops due to errors, the problems reported should be corrected and 149.Nm 150should be run again. 151.Nm 152attempts to avoid changing the compilation directory if there are 153configuration errors, but this code is not well-tested and some problems 154(such as running out of disk space) are unrecoverable. 155.Pp 156If 157.Ar config-file 158is not specified, 159.Nm 160uses the current directory as the build directory, and looks in it for 161a file called 162.Pa CONFIG . 163If 164.Nm 165is run this way, the location of the top-level kernel source 166directory must be specified using the 167.Fl s 168option or by using the 169.Dq Li source 170directive at the beginning of the system configuration file. 171.Pp 172The configuration files consists of various statements which 173include the following: 174.Bl -tag -offset indent -width indent 175.It Ic machine Ar var 176Required. 177Specifies the machine architecture. 178.It Ic include Ar file 179Include another configuration file. 180.It Ic option Ar name 181Set a kernel option. 182Kernel options may take either the form 183.Ar NAME 184or the form 185.Ar NAME Ns = Ns Ar value . 186These options are passed to the compiler with the 187.Fl D 188flag. 189.It Ic rmoption Ar name 190Delete a previously set option. 191This is useful when including another kernel configuration file. 192A typical use is to include the 193.Va GENERIC 194kernel provided with each release and remove options that are 195unwanted, thus allowing for automatic inclusion of new device 196drivers. 197.It Ic maxusers Ar number 198Required. 199Used to size various system tables and maximum operating conditions 200in an approximate fashion. 201Multiple instances of this keyword may be specified. 202The number provided in the last instance will be used, and 203warnings will be printed for each duplicate value. 204This is convenient when used with the 205.Va include 206directive. 207.It Xo Ic config Cm bsd root on Ar dev 208.Op Cm swap on Ar dev Op Cm and Ar dev ... 209.Op Cm dumps on Ar dev Op Cm and Ar dev ... 210.Xc 211Required. 212Specifies the swap and dump devices which the system should use. 213.It Ic config Cm bsd swap generic 214Otherwise, if generic is specified, the system follows generic routines to 215decide what should happen. 216.El 217.Pp 218To debug kernels and their crash dumps with gdb, add 219.Dq makeoptions DEBUG="-g" 220to the kernel configuration file, along with (typically) 221.Dq option KGDB . 222Refer to 223.Xr options 4 224for further details. 225.Pp 226Many other statements exist, and the file format is fairly rich; for more 227information see the various configuration files included in the system, as 228well as 229.Xr files.conf 5 230for the 231.Nm 232rules base. 233.Sh KERNEL MODIFICATION 234When 235.Fl e 236is specified, device parameters that are normally hard-coded into the kernel 237may be changed. 238This is useful to avoid the need for kernel recompilation or rebooting. 239Modifications are made to the currently running kernel and can be written to 240a new kernel binary so changes are preserved during subsequent system restarts. 241.Pp 242When invoked, the kernel identification is first shown. 243.Bd -literal -offset indent 244# config -e -o bsd.new /bsd 245OpenBSD 5.3-current (GENERIC.MP) #91: Mon Mar 25 16:43:17 MDT 2013 246 deraadt@i386.openbsd.org:/usr/src/sys/arch/i386/compile/GENERIC.MP 247Enter 'help' for information 248ukc\*(Gt 249.Ed 250.Pp 251One or more warnings may be printed before the 252.Li ukc\*(Gt 253prompt. 254.Bd -literal -offset indent 255warning: no output file specified 256.Ed 257.Pp 258Neither the 259.Fl f 260nor 261.Fl o 262option has been specified. 263Changes will be ignored. 264.Bd -literal -offset indent 265WARNING kernel mismatch. -u ignored. 266WARNING the running kernel version: 267.Ed 268.Pp 269.Nm 270does not believe the running kernel is the same as the 271.Ar infile 272specified. 273Since the log of changes (from 274.Cm boot -c ) 275in the running kernel is kernel-specific, the 276.Fl u 277option is ignored. 278.Pp 279The commands are as follows: 280.Bl -tag -width "disable attr val | devno | dev" 281.It Ic add Ar dev 282Add a device through copying another. 283.It Ic base Cm 8 | 10 | 16 284Change the base of numbers displayed and entered. 285.It Ic bufcachepercent Op Ar number 286Change the BUFCACHEPERCENT value. 287Without arguments, displays its current value. 288.It Ic change Ar devno | dev 289Modify one or more devices. 290.It Ic disable Ar attr val | devno | dev 291Disable one or more devices. 292.It Ic enable Ar attr val | devno | dev 293Enable one or more devices. 294.It Ic exit 295Exit without saving changes. 296.It Ic find Ar devno | dev 297Find one or more devices. 298.It Ic help 299Give a short summary of all commands and their arguments. 300.It Ic lines Op Ar count 301Set the number of rows per page. 302.It Ic list 303Show all known devices, a screen at a time. 304.It Ic nkmempg Op Ar number 305Change the NKMEMPAGES value. 306Without arguments, displays its current value. 307.It Ic quit 308Exit and save changes. 309.It Ic show Op Ar attr Op Ar val 310Show all devices for which attribute 311.Ar attr 312has the value 313.Ar val . 314.It Ic timezone Op Ar minuteswest Op Ar dst 315Change the 316.Va tz 317timezone structure. 318.Va minuteswest 319is the number of minutes west of GMT and 320.Va dst 321is non-zero if Daylight Saving Time is in effect. 322Without arguments, displays its current value. 323.El 324.Sh EXAMPLES (kernel building) 325Note: 326The standard 327.Ox 328kernel configuration 329(GENERIC or GENERIC.MP) 330is suitable for most purposes. 331Use of an alternative kernel configuration is not recommended. 332A custom kernel is built in the following way. 333.Pp 334To compile a kernel from a non-writable media (such as a CD-ROM) 335mounted on 336.Pa /usr/src , 337do the following: 338.Bd -literal -offset indent 339# cd /somedir 340# cp /usr/src/sys/arch/somearch/conf/SOMEFILE . 341# vi SOMEFILE (to make any changes) 342# config -s /usr/src/sys -b . SOMEFILE 343# make 344.Ed 345.Pp 346To compile a kernel inside a writable source tree, do the following: 347.Bd -literal -offset indent 348# cd /usr/src/sys/arch/somearch/conf 349# vi SOMEFILE (to make any changes) 350# config SOMEFILE 351# cd ../compile/SOMEFILE 352# make 353.Ed 354.Pp 355In the examples above, 356.Ar somedir 357is a writable directory, 358.Ar somearch 359is the architecture (e.g. i386), 360and 361.Ar SOMEFILE 362should be a name indicative of a particular configuration (often 363that of the hostname). 364.Nm config 365will warn if a 366.Dq make clean 367is required. 368.Pp 369The new kernel, called 370.Pa bsd , 371can be copied to 372.Pa /bsd 373and the system will boot it next time. 374Most people save their backup kernels as 375.Pa /bsd.1 , 376.Pa /bsd.2 , 377etc. 378.Sh EXAMPLES (kernel modification) 379The Ethernet card is not detected at boot because the kernel configuration 380does not match the physical hardware configuration, 381e.g. wrong IRQ in OpenBSD/i386. 382The Ethernet card is supposed to use the 383.Xr ne 4 384driver. 385.Bd -literal 386.No ukc\*(Gt Ic find ne 38724 ne0 at isa0 port 0x240 size 0 iomem 0xd8000 iosiz 0 irq 9 drq -1 drq2 -1 flags 0x0 38825 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0 38926 ne* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 flags 0x0 39027 ne* at pci* dev -1 function -1 flags 0x0 39128 ne* at pcmcia* function -1 irq -1 flags 0x0 392ukc\*(Gt 393.Ed 394.Pp 395ne1 seems to match the configuration except it uses IRQ 10 instead of IRQ 5. 396So the irq on ne1 should be changed via the 397.Ic change 398command. 399The device can be specified by either name or number. 400.Bd -literal 401.No ukc\*(Gt Ic change ne1 40225 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 403.No change (y/n) \&? Ic y 404.No port [0x300] \&? 405.No size [0] \&? 406.No iomem [-1] \&? 407.No iosiz [0] \&? 408.No irq [10] \&? Ic 5 409.No drq [-1] \&? 410.No drq2 [-1] \&? 411.No flags [0] \&? 41225 ne1 changed 41325 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 5 drq -1 drq2 -1 flags 0x0 414ukc\*(Gt 415.Ed 416.Pp 417It's also possible to disable all devices with a common attribute. 418For example: 419.Bd -literal 420.No ukc\*(Gt Ic disable port 0x300 421 25 ne1 disabled 422 72 we1 disabled 423 75 el0 disabled 424 77 ie1 disabled 425.Ed 426.Pp 427The 428.Cm show 429command is useful for finding which devices have a certain attribute. 430It can also be used to find those devices with a particular value for 431an attribute. 432.Bd -literal 433.No ukc\*(Gt Ic show slot 434 2 ahc* at eisa0 slot -1 435 10 uha* at eisa0 slot -1 436 12 ep0 at eisa0 slot -1 437 17 ep* at eisa0 slot -1 438102 ahb* at eisa0 slot -1 439103 fea* at eisa0 slot -1 440.No ukc\*(Gt Ic show port 0x300 441 25 ne1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0 442 72 we1 at isa0 port 0x300 size 0 iomem 0xcc000 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0 443 75 el0 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 9 drq -1 drq2 -1 flags 0x0 444 77 ie1 at isa0 port 0x300 size 0 iomem -1 iosiz 0 irq 10 drq -1 drq2 -1 flags 0x0 445ukc\*(Gt 446.Ed 447.Pp 448It is possible to add new devices, but only devices that were linked into the 449kernel. 450If a new device is added, following devices will be renumbered. 451.Bd -literal 452.No ukc\*(Gt Ic find ep 453 11 ep0 at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1 flags 0x0 454 12 ep0 at eisa0 slot -1 flags 0x0 455 13 ep0 at pci* dev -1 function -1 flags 0x0 456 14 ep* at isapnp0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 flags 0x0 457 15 ep* at isa0 port -1 size 0 iomem -1 iosiz 0 irq -1 drq -1 drq2 -1 flags 0x0 458 16 ep* at eisa0 slot -1 flags 0x0 459 17 ep* at pci* dev -1 function -1 flags 0x0 460 18 ep* at pcmcia* dev -1 irq -1 flags 0x0 461.No ukc\*(Gt Ic add ep1 462.No "Clone Device (DevNo, 'q' or '\&?') \&?" Ic 13 463.No "Insert before Device (DevNo, 'q' or '\&?')" Ic 14 464 14 ep1 at pci* dev -1 function -1 465.No ukc\*(Gt Ic change 14 466 14 ep1 at pci* dev -1 function -1 467.No change (y/n) \&? Ic y 468.No dev [-1] \&? Ic 14 469.No function [-1] \&? 470.No flags [0] \&? Ic 18 471 14 ep1 changed 472 14 ep1 at pci* dev 14 function -1 flags 0x12 473ukc\*(Gt 474.Ed 475.Pp 476When done, exit the program with the 477.Ic quit 478or 479.Ic exit 480commands. 481.Ic exit 482will ignore any changes while 483.Ic quit 484writes the changes to 485.Ar outfile 486(if 487.Fl o 488or 489.Fl f 490was given, else ignore changes). 491.Bd -literal 492.No ukc\*(Gt Ic quit 493.Ed 494.Sh SEE ALSO 495.Xr options 4 , 496.Xr files.conf 5 , 497.Xr boot.conf 8 , 498.Xr boot_config 8 499.Pp 500The SYNOPSIS portion of each device in section 4 of the manual. 501.Rs 502.%T "Building 4.4 BSD Systems with Config" 503.Re 504.Sh HISTORY 505The 506.Nm 507program appeared in 508.Bx 4.1 509and was completely revised in 510.Bx 4.4 . 511The 512.Fl e 513option appeared in 514.Ox 2.6 . 515.Sh BUGS 516Included files should start with an empty line or comment. 517