xref: /freebsd/usr.sbin/config/config.5 (revision 195ebc7e9e4b129de810833791a19dfb4349d6a9)
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 December 3, 2005
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.Bl -tag -width indent -compact
90.\" -------- CPU --------
91.Pp
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.
117The kernel normally uses an environment prepared for it at boot time
118by
119.Xr loader 8 .
120This directive makes the kernel ignore the boot environment and use
121the compiled-in environment instead.
122.Pp
123This directive is useful for setting kernel tunables in
124embedded environments that do not start from
125.Xr loader 8 .
126.\" -------- FILES --------
127.Pp
128.It Ic files Ar filename
129Specifies a file containing a list of files specific to that kernel
130configuration file (a la
131.Pa files. Ns Aq Ar arch ) .
132.\" -------- HINTS --------
133.Pp
134.It Ic hints Ar filename
135Specifies a file to load a static device configuration specification
136from.
137From
138.Fx 5.0
139onwards, the kernel reads the system's device configuration at boot
140time (see
141.Xr device.hints 5 ) .
142This directive configures the kernel to use the static device configuration
143listed in
144.Ar filename .
145The file
146.Ar filename
147must conform to the syntax specified by
148.Xr device.hints 5 .
149Multiple hints lines are allowed.
150The resulting hints will be the files concatenated in the order of appearance.
151.\" -------- IDENT --------
152.Pp
153.It Ic ident Ar name
154Set the kernel name to
155.Ar name .
156At least one
157.Ic ident
158directive is required.
159.\" -------- INCLUDE --------
160.Pp
161.It Ic include Ar filename
162Read subsequent text from file
163.Ar filename
164and return to the current file after
165.Ar filename
166is successfully processed.
167.\" -------- MACHINE --------
168.Pp
169.It Ic machine Ar arch Op Ar cpuarch
170Specifies the architecture of the machine the kernel is being
171compiled for.
172Legal values for
173.Ar arch
174include:
175.Pp
176.Bl -tag -width ".Cm powerpc" -compact
177.It Cm alpha
178The DEC Alpha architecture.
179.It Cm arm
180The ARM architecture.
181.It Cm amd64
182The AMD x86-64 architecture.
183.It Cm i386
184The Intel x86 based PC architecture.
185.It Cm ia64
186The Intel IA64 architecture.
187.It Cm mips
188The MIPS architecture.
189.It Cm pc98
190The PC98 architecture.
191.It Cm powerpc
192The IBM PowerPC architecture.
193.It Cm sparc64
194The Sun Sparc64 architecture.
195.El
196.Pp
197If argument
198.Ar cpuarch
199is specified, it points
200.Xr config 8
201to the cpu architecture of the machine.
202Currently the
203.Cm pc98
204architecture requires its cpu architecture
205to be set to
206.Cm i386 .
207When
208.Ar cpuarch
209is not specified, it is assumed to be the same as
210.Ar arch .
211.Ar arch
212corresponds to MACHINE.
213.Ar cpuarch
214corresponds to MACHINE_ARCH.
215.Pp
216A kernel configuration file may have only one
217.Ic machine
218directive.
219.\" -------- MAKEOPTION --------
220.Pp
221.It Ic makeoption Ar options
222.It Ic makeoptions Ar options
223Add
224.Ar options
225to the generated makefile.
226.Pp
227The
228.Ar options
229argument is a comma separated list of one or more option
230specifications.
231Each option specification has the form
232.Pp
233.D1 Ar MakeVariableName Ns Op = Ns Ar Value
234.D1 Ar MakeVariableName Ns += Ns Ar Value
235.Pp
236and results in the appropriate
237.Xr make 1
238variable definition being inserted into the generated makefile.
239If only the name of the
240.Xr make 1
241variable is specified,
242.Ar value
243is assumed to be the empty string.
244.Pp
245Example:
246.Bd -literal -offset indent -compact
247makeoptions MYMAKEOPTION="foo"
248makeoptions MYMAKEOPTION+="bar"
249makeoptions MYNULLMAKEOPTION
250.Ed
251.\" -------- MAXUSERS --------
252.Pp
253.It Ic maxusers Ar number
254This optional directive is used to configure the size
255of some kernel data structures.
256The parameter
257.Ar number
258can be 0 (the default) or an integer greater than or equal to 2.
259A value of 0 indicates that the kernel should configure
260its data structures according to the size of available
261physical memory.
262If auto configuration is requested, the kernel will set
263this tunable to a value between 32 and 384.
264.Pp
265As explained in
266.Xr tuning 7 ,
267this tunable can also be set at boot time using
268.Xr loader 8 .
269.\" -------- NOCPU --------
270.Pp
271.It Ic nocpu Ar cputype
272Remove the specified CPU
273from the list of previously selected CPUs.
274This directive can be used to cancel the effect of
275.Ic cpu
276directives in files included using
277.Ic include .
278.\" -------- NODEVICE --------
279.Pp
280.It Ic nodevice Ar name Op , Ar name Op ...
281.It Ic nodevices Ar name Op , Ar name Op ...
282Remove the specified devices
283from the list of previously selected devices.
284This directive can be used to cancel the effects of
285.Ic device
286or
287.Ic devices
288directives in files included using
289.Ic include .
290.\" -------- NOMAKEOPTION --------
291.Pp
292.It Ic nomakeoption Ar name
293.It Ic nomakeoptions Ar name
294Removes previously defined
295.Xr make 1
296option
297.Ar name
298from the kernel build.
299This directive can be used to cancel the effects of
300.Ic makeoption
301directives in files included using
302.Ic include .
303.\" -------- NOOPTION --------
304.Pp
305.It Ic nooption Ar name Op , Ar name Op ...
306.It Ic nooptions Ar name Op , Ar name Op ...
307Remove the specified kernel options
308from the list of previously defined options.
309This directive can be used to cancel the effects of
310.Ic option
311or
312.Ic options
313directives in files included using
314.Ic include .
315.\" -------- OPTIONS --------
316.Pp
317.It Ic option Ar optionspec Op , Ar optionspec Op ...
318.It Ic options Ar optionspec Op , Ar optionspec Op ...
319Add compile time kernel options to the kernel build.
320Each option specification has the form
321.Pp
322.D1 Ar name Ns Op = Ns Ar value
323.Pp
324If
325.Ar value
326is not specified, it is assumed to be
327.Dv NULL .
328Options common to all architectures are specified in
329the file
330.Pa sys/conf/options .
331Options specific to architecture
332.Ar arch
333are specified in the file
334.Pa sys/conf/options. Ns Aq Ar arch .
335.\" -------- PROFILE --------
336.Pp
337.It Ic profile Ar number
338Enables kernel profiling if
339.Ar number
340is non-zero.
341If
342.Ar number
343is 2 or greater, the kernel is configured for
344high-resolution profiling.
345Kernels can also be built for profiling using the
346.Fl p
347option to
348.Xr config 8 .
349.El
350.Ss Obsolete Directives
351The following kernel configuration directives are obsolete.
352.Bl -tag -width indent
353.\" -------- CONFIG --------
354.Pp
355.It Ic config
356This directive was used to specify the device to be used for the root
357file system.
358From
359.Fx 4.0
360onwards, this information is passed to a booting kernel by
361.Xr loader 8 .
362.El
363.Sh FILES
364.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact
365.It Pa sys/compile/ Ns Ar NAME
366Compile directory created from a kernel configuration.
367.It Pa sys/conf/Makefile. Ns Ar arch
368.Pa Makefile
369fragments for architecture
370.Ar arch .
371.It Pa sys/conf/files
372Devices common to all architectures.
373.It Pa sys/conf/files. Ns Ar arch
374Devices for architecture
375.Ar arch .
376.It Pa sys/conf/options
377Options common to all architectures.
378.It Pa sys/conf/options. Ns Ar arch
379Options for architecture
380.Ar arch .
381.El
382.Sh SEE ALSO
383.Xr kenv 1 ,
384.Xr make 1 ,
385.Xr device.hints 5 ,
386.Xr loader.conf 5 ,
387.Xr config 8 ,
388.Xr kldload 8 ,
389.Xr loader 8
390.Rs
391.%T "Building 4.4BSD Kernels with Config"
392.%A "Samuel J. Leffler"
393.%A "Michael J. Karels"
394.Re
395.Sh HISTORY
396The
397.Xr config 8
398utility first appeared in
399.Bx 4.1 ,
400and was subsequently revised in
401.Bx 4.4 .
402.Pp
403The kernel configuration mechanism changed further in
404.Fx 4.0
405and
406.Fx 5.0 ,
407moving toward an architecture supporting dynamic kernel
408configuration.
409