xref: /freebsd/usr.sbin/config/config.5 (revision f976241773df2260e6170317080761d1c5814fe5)
1.\" Copyright (c) 2003 Joseph Koshy
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\"    notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\"    notice, this list of conditions and the following disclaimer in the
10.\"    documentation and/or other materials provided with the distribution.
11.\"
12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
22.\" SUCH DAMAGE.
23.\"
24.\" $FreeBSD$
25.\"
26.Dd February 9, 2020
27.Dt CONFIG 5
28.Os
29.Sh NAME
30.Nm config
31.Nd kernel configuration file format
32.Sh DESCRIPTION
33A kernel configuration file specifies the configuration of a
34.Fx
35kernel.
36It is processed by
37.Xr config 8
38to create a build environment where a kernel may be built using
39.Xr make 1 .
40.Ss Lexical Structure
41A kernel configuration file comprises a sequence of specification
42directives.
43.Pp
44A specification directive starts with a keyword at the beginning
45of the line and is followed by additional parameters.
46.Pp
47A specification directive may be terminated by a semicolon
48.Ql \&;
49or by a newline.
50Long input lines may be broken into shorter lines by starting the
51second and subsequent lines with a white space character.
52.Pp
53Case is significant,
54.Dq Li machine
55and
56.Dq Li MACHINE
57are different tokens.
58.Pp
59A double quote character
60.Ql \[dq]
61starts a quoted string.
62All characters up to the next quote character form the value
63of the quoted string.
64A
65.Ql \[dq]
66character may be inserted into a quoted string by
67using the sequence
68.Ql \e\[dq] .
69.Pp
70Numbers are specified using
71.Tn C Ns -style
72syntax.
73.Pp
74A
75.Ql #
76character starts a comment; all characters from the
77.Ql #
78character till the end of the current line are ignored.
79.Pp
80Whitespace between tokens is ignored, except inside quoted strings.
81Whitespace following a comment line is ignored.
82.Ss Configuration Directives
83Kernel configuration directives may appear in any order
84in a kernel configuration file.
85Directives are processed in order of appearance with subsequent
86directive lines overriding the effect of prior ones.
87.Pp
88The list of keywords and their meanings are as follows:
89.Pp
90.Bl -tag -width indent -compact
91.\" -------- CPU --------
92.It Ic cpu Ar cputype
93Specify the CPU this kernel will run on.
94There can be more than one
95.Ic cpu
96directive in a configuration file.
97The allowed list of CPU names is architecture specific and is
98defined in the file
99.Pa sys/conf/options. Ns Aq Ar arch .
100.\" -------- DEVICE --------
101.Pp
102.It Ic device Ar name Op , Ar name Op ...
103.It Ic devices Ar name Op , Ar name Op ...
104Configures the specified devices
105for inclusion into the kernel image.
106Devices that are common to all architectures are
107defined in the file
108.Pa sys/conf/files .
109Devices that are specific to architecture
110.Ar arch
111are defined in the file
112.Pa sys/conf/files. Ns Aq Ar arch .
113.\" -------- ENV --------
114.Pp
115.It Ic env Ar filename
116Specifies a filename containing a kernel environment definition.
117.Pp
118The kernel will augment this compiled-in environment with the environment
119prepared for it at boot time by
120.Xr loader 8 .
121Environment variables specified in the
122.Xr loader 8
123environment will take precedence over environment variables specified in
124.Ar filename ,
125and environment variables specified in the dynamic environment take precedence
126over both of these.
127.Pp
128.Va loader_env.disabled=1
129may be specified in the static environment to disable the
130.Xr loader 8
131environment.
132Disabling the
133.Xr loader 8
134should be done with caution and due consideration for whether or not it supplies
135environment variables needed for properly booting the system.
136.Pp
137.Va static_env.disabled=1
138may be specified in the
139.Xr loader 8
140environment to disable use of the static environment.
141This option has no effect if specified in any environment after the
142.Xr loader 8
143environment is processed.
144This option is not usable in conjunction with
145.Va loader_env.disabled .
146.Pp
147This directive is useful for setting kernel tunables in
148embedded environments that do not start from
149.Xr loader 8 .
150.Pp
151All
152.Ic env
153and
154.Ic envvar
155directives will be processed and added to the static environment in reversed
156order of appearance so that later specified variables properly override earlier
157specified variables.
158Note that within
159.Ar filename ,
160the first appearance of a given variable will be the first one seen by the
161kernel, effectively shadowing any later appearances of the same variable within
162.Ar filename .
163.\" -------- ENVVAR --------
164.Pp
165.It Ic envvar Ar setting
166Specifies an individual environment setting to be added to the kernel's
167compiled-in environment.
168.Ar setting
169must be of the form
170.Dq Va name=value .
171Optional quotes are supported in both name and value.
172.Pp
173All
174.Ic env
175and
176.Ic envvar
177directives will be processed and added to the static environment in reversed
178order of appearance so that later specified variables properly override earlier
179specified variables.
180.\" -------- FILES --------
181.Pp
182.It Ic files Ar filename
183Specifies a file containing a list of files specific to that kernel
184configuration file (a la
185.Pa files. Ns Aq Ar arch ) .
186.\" -------- HINTS --------
187.Pp
188.It Ic hints Ar filename
189Specifies a file to load a static device configuration specification
190from.
191From
192.Fx 5.0
193onwards, the kernel reads the system's device configuration at boot
194time (see
195.Xr device.hints 5 ) .
196This directive configures the kernel to use the static device configuration
197listed in
198.Ar filename .
199.Pp
200Hints provided in this static device configuration will be overwritten in the
201order in which they're encountered.
202Hints in the compiled-in environment takes precedence over compiled-in hints,
203and hints in the environment prepared for the kernel by
204.Xr loader 8
205takes precedence over hints in the compiled-in environment.
206.Pp
207Once the dynamic environment becomes available, all compiled-in hints will be
208added to the dynamic environment if they do not already have an override in
209the dynamic environment.
210The dynamic environment will then be used for all searches of hints.
211.Pp
212.Va static_hints.disabled=1
213may be specified in either a compiled-in environment or the
214.Xr loader 8
215environment to disable use of these hints files.
216This option has no effect if specified in any environment after the
217.Xr loader 8
218environment is processed.
219.Pp
220The file
221.Ar filename
222must conform to the syntax specified by
223.Xr device.hints 5 .
224Multiple hints lines are allowed.
225The resulting hints will be the files concatenated in reverse order of
226appearance so that hints in later files properly override hints in earlier
227files.
228.\" -------- IDENT --------
229.Pp
230.It Ic ident Ar name
231Set the kernel name to
232.Ar name .
233At least one
234.Ic ident
235directive is required.
236.\" -------- INCLUDE --------
237.Pp
238.It Ic include Ar filename
239Read subsequent text from file
240.Ar filename
241and return to the current file after
242.Ar filename
243is successfully processed.
244.\" -------- MACHINE --------
245.Pp
246.It Ic machine Ar arch Op Ar cpuarch
247Specifies the architecture of the machine the kernel is being
248compiled for.
249Legal values for
250.Ar arch
251include:
252.Pp
253.Bl -tag -width ".Cm powerpc" -compact
254.It Cm arm64
255The 64-bit ARM application architecture.
256.It Cm arm
257The ARM architecture
258.It Cm amd64
259The AMD x86-64 architecture.
260.It Cm i386
261The Intel x86 based PC architecture.
262.It Cm mips
263The MIPS architecture.
264.It Cm powerpc
265The IBM PowerPC architecture.
266.It Cm riscv
267The RISC-V architecture.
268.El
269.Pp
270If argument
271.Ar cpuarch
272is specified, it points
273.Xr config 8
274to the cpu architecture of the machine.
275When
276.Ar cpuarch
277is not specified, it is assumed to be the same as
278.Ar arch .
279.Ar arch
280corresponds to MACHINE.
281.Ar cpuarch
282corresponds to MACHINE_ARCH.
283.Pp
284A kernel configuration file may have only one
285.Ic machine
286directive.
287.\" -------- MAKEOPTION --------
288.Pp
289.It Ic makeoption Ar options
290.It Ic makeoptions Ar options
291Add
292.Ar options
293to the generated makefile.
294.Pp
295The
296.Ar options
297argument is a comma separated list of one or more option
298specifications.
299Each option specification has the form
300.Pp
301.D1 Ar MakeVariableName Ns Op = Ns Ar Value
302.D1 Ar MakeVariableName Ns += Ns Ar Value
303.Pp
304and results in the appropriate
305.Xr make 1
306variable definition being inserted into the generated makefile.
307If only the name of the
308.Xr make 1
309variable is specified,
310.Ar value
311is assumed to be the empty string.
312.Pp
313Example:
314.Bd -literal -offset indent -compact
315makeoptions MYMAKEOPTION="foo"
316makeoptions MYMAKEOPTION+="bar"
317makeoptions MYNULLMAKEOPTION
318.Ed
319.\" -------- MAXUSERS --------
320.Pp
321.It Ic maxusers Ar number
322This optional directive is used to configure the size
323of some kernel data structures.
324The parameter
325.Ar number
326can be 0 (the default) or an integer greater than or equal to 2.
327A value of 0 indicates that the kernel should configure
328its data structures according to the size of available
329physical memory.
330If auto configuration is requested, the kernel will set
331this tunable to a value between 32 and 384.
332.Pp
333As explained in
334.Xr tuning 7 ,
335this tunable can also be set at boot time using
336.Xr loader 8 .
337.\" -------- NOCPU --------
338.Pp
339.It Ic nocpu Ar cputype
340Remove the specified CPU
341from the list of previously selected CPUs.
342This directive can be used to cancel the effect of
343.Ic cpu
344directives in files included using
345.Ic include .
346.\" -------- NODEVICE --------
347.Pp
348.It Ic nodevice Ar name Op , Ar name Op ...
349.It Ic nodevices Ar name Op , Ar name Op ...
350Remove the specified devices
351from the list of previously selected devices.
352This directive can be used to cancel the effects of
353.Ic device
354or
355.Ic devices
356directives in files included using
357.Ic include .
358.\" -------- NOMAKEOPTION --------
359.Pp
360.It Ic nomakeoption Ar name
361.It Ic nomakeoptions Ar name
362Removes previously defined
363.Xr make 1
364option
365.Ar name
366from the kernel build.
367This directive can be used to cancel the effects of
368.Ic makeoption
369directives in files included using
370.Ic include .
371.\" -------- NOOPTION --------
372.Pp
373.It Ic nooption Ar name Op , Ar name Op ...
374.It Ic nooptions Ar name Op , Ar name Op ...
375Remove the specified kernel options
376from the list of previously defined options.
377This directive can be used to cancel the effects of
378.Ic option
379or
380.Ic options
381directives in files included using
382.Ic include .
383.\" -------- OPTIONS --------
384.Pp
385.It Ic option Ar optionspec Op , Ar optionspec Op ...
386.It Ic options Ar optionspec Op , Ar optionspec Op ...
387Add compile time kernel options to the kernel build.
388Each option specification has the form
389.Pp
390.D1 Ar name Ns Op = Ns Ar value
391.Pp
392If
393.Ar value
394is not specified, it is assumed to be
395.Dv NULL .
396Options common to all architectures are specified in
397the file
398.Pa sys/conf/options .
399Options specific to architecture
400.Ar arch
401are specified in the file
402.Pa sys/conf/options. Ns Aq Ar arch .
403.\" -------- PROFILE --------
404.Pp
405.It Ic profile Ar number
406Enables kernel profiling if
407.Ar number
408is non-zero.
409If
410.Ar number
411is 2 or greater, the kernel is configured for
412high-resolution profiling.
413Kernels can also be built for profiling using the
414.Fl p
415option to
416.Xr config 8 .
417.El
418.Ss Obsolete Directives
419The following kernel configuration directives are obsolete.
420.Bl -tag -width indent
421.\" -------- CONFIG --------
422.It Ic config
423This directive was used to specify the device to be used for the root
424file system.
425From
426.Fx 4.0
427onwards, this information is passed to a booting kernel by
428.Xr loader 8 .
429.El
430.Sh FILES
431.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact
432.It Pa sys/compile/ Ns Ar NAME
433Compile directory created from a kernel configuration.
434.It Pa sys/conf/Makefile. Ns Ar arch
435.Pa Makefile
436fragments for architecture
437.Ar arch .
438.It Pa sys/conf/files
439Devices common to all architectures.
440.It Pa sys/conf/files. Ns Ar arch
441Devices for architecture
442.Ar arch .
443.It Pa sys/conf/options
444Options common to all architectures.
445.It Pa sys/conf/options. Ns Ar arch
446Options for architecture
447.Ar arch .
448.El
449.Sh SEE ALSO
450.Xr kenv 1 ,
451.Xr make 1 ,
452.Xr device.hints 5 ,
453.Xr loader.conf 5 ,
454.Xr config 8 ,
455.Xr kldload 8 ,
456.Xr loader 8
457.Rs
458.%T "Building 4.4BSD Kernels with Config"
459.%A "Samuel J. Leffler"
460.%A "Michael J. Karels"
461.Re
462.Sh HISTORY
463The
464.Xr config 8
465utility first appeared in
466.Bx 4.1 ,
467and was subsequently revised in
468.Bx 4.4 .
469.Pp
470The kernel configuration mechanism changed further in
471.Fx 4.0
472and
473.Fx 5.0 ,
474moving toward an architecture supporting dynamic kernel
475configuration.
476