dloader: Add a new option for color loader, "fred_is_blue"
[dragonfly.git] / share / man / man5 / loader.conf.5
CommitLineData
984263bc
MD
1.\" Copyright (c) 1999 Daniel C. Sobral
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
5ee58eed 25.\" $FreeBSD: src/sys/boot/forth/loader.conf.5,v 1.18 2002/08/27 01:02:56 trhodes Exp $
a147fd46 26.Dd November 29, 2014
984263bc
MD
27.Dt LOADER.CONF 5
28.Os
29.Sh NAME
30.Nm loader.conf
31.Nd system bootstrap configuration information
32.Sh DESCRIPTION
33The file
34.Nm
0389edac 35contains descriptive information on bootstrapping the system.
b5ef8da1
TN
36Through it you can specify the kernel to be booted,
37parameters to be passed to it,
38and additional kernel modules to be loaded;
39and generally set all variables described in
984263bc
MD
40.Xr loader 8 .
41.Pp
2a2fb130 42A file
b5ef8da1
TN
43.Pa dloader.rc
44must contain the following lines for
984263bc
MD
45.Nm
46to be automatically processed:
47.Pp
b5ef8da1
TN
48.Dl include defaults/loader.conf
49.Dl optinclude loader.conf
50.Dl optinclude loader.conf.local
984263bc
MD
51.Pp
52If no
b5ef8da1 53.Pa /boot/dloader.rc
984263bc
MD
54exists at installworld time, one with the above lines will be installed.
55.Sh SYNTAX
56Though
57.Nm Ns 's
58format was defined explicitly to resemble
59.Xr rc.conf 5 ,
60and can be sourced by
61.Xr sh 1 ,
0389edac 62some settings are treated in a special fashion.
b5ef8da1 63Also, the behavior of some settings is defined by the setting's suffix;
984263bc
MD
64the prefix identifies which module the setting controls.
65.Pp
66The general parsing rules are:
67.Bl -bullet
68.It
69Spaces and empty lines are ignored.
70.It
0389edac
TN
71A
72.Ql #
73sign will mark the remainder of the line as a comment.
984263bc
MD
74.It
75Only one setting can be present on each line.
76.El
77.Pp
78All settings have the following format:
79.Pp
80.Dl variable="value"
81.Pp
b5ef8da1
TN
82This assigns value to a local variable.
83If variable is in a list of known kernel environment variables or
84is a kernel tunable,
85it is also assigned to the kernel environment variable of the given name.
86.Pp
87The settings that receive special treatment are listed below.
0389edac
TN
88Settings beginning with
89.Aq Ar module
b5ef8da1 90below define the kernel modules to be loaded.
984263bc
MD
91All such settings sharing a common
92prefix refer to the same module.
b5ef8da1 93.Bl -tag -width indent
984263bc 94.It Ar kernel
0389edac
TN
95Name of the kernel to be loaded.
96If no kernel name is set, no additional
984263bc
MD
97modules will be loaded.
98.It Ar kernel_options
d18ae742
SW
99Flags to be passed to the kernel (see
100.Xr boot 8 ) .
984263bc
MD
101.It Ar verbose_loading
102If set to
103.Dq YES ,
104module names will be displayed as they are loaded.
0389edac 105.It Ao Ar module Ac Ns Ar _load
984263bc
MD
106If set to
107.Dq YES ,
b5ef8da1 108that kernel module will be loaded.
0389edac
TN
109If no
110.Ao Ar module Ac Ns Ar _name
111is defined (see below), the
112module's name is taken to be
113.Aq Ar module .
114.It Ao Ar module Ac Ns Ar _name
984263bc 115Defines the name of the module.
0389edac
TN
116.It Ao Ar module Ac Ns Ar _type
117Defines the module's type.
b5ef8da1
TN
118If none is given, it defaults to a
119.Xr kld 4
120module.
0389edac 121.It Ao Ar module Ac Ns Ar _flags
984263bc 122Flags and parameters to be passed to the module.
0389edac
TN
123.It Ao Ar module Ac Ns Ar _before
124Commands to be executed before the module is loaded.
125Use of this setting
984263bc 126should be avoided.
0389edac
TN
127.It Ao Ar module Ac Ns Ar _after
128Commands to be executed after the module is loaded.
129Use of this setting
984263bc 130should be avoided.
0389edac
TN
131.It Ao Ar module Ac Ns Ar _error
132Commands to be executed if the loading of a module fails.
133Except for the
984263bc
MD
134special value
135.Dq abort ,
136which aborts the bootstrap process, use of this setting should be avoided.
137.El
138.Sh DEFAULT SETTINGS
b5ef8da1
TN
139See
140.Pa /boot/defaults/loader.conf
141for
984263bc 142.Nm Ns 's
b5ef8da1 143default settings.
0389edac 144The few of them which are important
984263bc 145or useful are:
b5ef8da1 146.Bl -tag -width indent
984263bc
MD
147.It Va bitmap_load
148.Pq Dq NO
149If set to
150.Dq YES ,
151a bitmap will be loaded to be displayed on screen while booting.
152.It Va bitmap_name
2a2fb130 153.Pq Dq splash.bmp
0389edac
TN
154Name of the bitmap to be loaded.
155Any other name can be used.
526a18df 156.It Va boot_verbose
9f488f94 157.Pq Dq NO
526a18df
JT
158Set to
159.Dq YES
160to enable verbose booting.
5ee58eed
MD
161.It Va console
162.Pq Dq vidconsole
163.Dq comconsole
164selects serial console,
165.Dq vidconsole
166selects the video console, and
167.Dq nullconsole
168selects a mute console
169(useful for systems with neither a video console nor a serial port).
792c92cb
MD
170.Pp
171When using a comconsole the kernel defaults to allowing a console on sio0.
172To change this to sio1 you must specify
173.Va sio0.flags=0
174and
175.Va sio1.flags=0x10
176in addition to setting the console to the comconsole.
1b3de706
MD
177You can also set the baud rate with (for example)
178.Va sio1.baud=115200
179or simply inherit the baud set in the boot code.
180Normally these must be set if you want to use a stock kernel in a
181IPMI environment.
fe29771d
MD
182When setting the serial console you must specify the serial port
183with (for example)
184.Va sio1.port=0x3e8 .
185Typically sio0 is on 0x3f8 and sio1 is on 0x2f8, but IPMI consoles
186on sio1 are often on 0x3e8 (instead of sio2), which can be confusing.
187Be sure to specify the correct port
188if you want early kernel boot messages to work.
189If you do not specify the port the console will still operate on
190the serial port but only after the kernel has started init.
792c92cb 191.Pp
97a8cef1
MD
192Some IPMI environments do not enable sio1 during the BIOS boot,
193which can cause the loader to get confused and not pass RB_SERIAL
194to the kernel.
195Setting console=comconsole in this situation also does not work because
196then the loader is inacessible. Instead, set the sioX fields as shown
197above and also add
198.Va set boot_serial="YES"
199to cause the kernel to use the serial port without also forcing the
200boot loader to use the serial port.
201.Pp
202The boot1/boot2 code uses BIOS calls to read and write the screen but also
1b3de706
MD
203mirrors output to and monitors COM1 @ 9600.
204In an IPMI environment you do not usually have to adjust the boot code
97a8cef1 205at all, instead using the IPMI feature to redirect the video output.
1b3de706
MD
206In non-IPMI setups if you want the boot code to be available on
207COM2 at 57600 baud instead of COM1, for example, you must set the variables
792c92cb
MD
208.Va BOOT_COMCONSOLE_PORT=0x2f8
209and
210.Va BOOT_COMCONSOLE_SPEED=57600
211in
212.Pa /etc/make.conf
213and recompile and install the boot code at
214.Pa /usr/src/sys/boot ,
215then install the bootcode to the partition via
216.Xr disklabel 8 .
217.Pp
218Note that in comconsole mode the kernel will pick up the baud rate
219from the boot loader, so no kernel recompile is needed.
a147fd46
JM
220.It Va kernel
221.Pq Dq kernel .
2fca4b67
SW
222.It Va fred_disable
223.Pq Dq NO
a3220ac5
SW
224Shows a monochrome version of Fred, the official
225.Dx
226mascot, when the
0389edac
TN
227boot menu appears.
228To make his life a bit more colorful, consider setting
2fca4b67
SW
229.Pa loader_color
230to
231.Dq YES .
8b20437d
JT
232.It Va fred_on_left
233.Pq Dq NO
234Shows Fred on the left side of the menu rather than the right side.
a147fd46
JM
235.It Va fred_separated
236.Pq Dq NO
237Draws a line between Fred and the menu block.
2fca4b67
SW
238.It Va loader_color
239.Pq Dq NO
240If set to
241.Dq YES ,
a3220ac5
SW
242you'll meet Fred, the official
243.Dx
244mascot, in technicolor when the
2fca4b67
SW
245boot menu appears (remember to set
246.Pa fred_disable
247to
248.Dq NO
249for this to work.)
a147fd46
JM
250.It Va fred_is blue
251.Pq Dq NO
252When a color loader is requested, Fred is depicted as a red dragonfly
253with red wings. This setting causes Fred to be shown as a blue dragonfly.
984263bc
MD
254.It Va splash_bmp_load
255.Pq Dq NO
256If set to
257.Dq YES ,
258will load the splash screen module, making it possible to display a bmp image
259on the screen while booting.
260.It Va splash_pcx_load
261.Pq Dq NO
262If set to
263.Dq YES ,
264will load the splash screen module, making it possible to display a pcx image
265on the screen while booting.
266.It Va userconfig_script_load
267.Pq Dq NO
268If set to
269.Dq YES ,
270will load the userconfig data.
271.It Va vesa_load
272.Pq Dq NO
273If set to
274.Dq YES ,
275the vesa module will be loaded, enabling bitmaps above VGA resolution to
276be displayed.
277.El
792c92cb
MD
278.Sh IPMI
279Generally speaking machines with IPMI capabilities are capable of
280redirecting the BIOS POST to a fake serial port controlled by the BMC.
281It is then possible to use
282.Xr ipmitool 1
c8e8a2e5
SW
283from
284.Xr dports 7
285to access the console.
440b845a
SW
286.Dx
287kernels adjust the video mode in a way that the BMC cannot usually
792c92cb
MD
288redirect, so your best bet is to set the boot loader AND the kernel up to
289use a serial port via the
290.Va console=comconsole
291feature described above.
292Often the IPMI controller, called the BMC, is not sitting on COM1 so
440b845a
SW
293.Dx Ap s
294default console parameters and baud rate will not work.
984263bc 295.Sh FILES
b5ef8da1
TN
296.Bl -tag -width ".Pa /boot/defaults/dloader.menu" -compact
297.It Pa /boot/defaults/dloader.menu
298default settings for menu setup -- do not change this file.
984263bc
MD
299.It Pa /boot/defaults/loader.conf
300default settings -- do not change this file.
b5ef8da1
TN
301.It Pa /boot/dloader.menu
302defines the commands used by
303.Nm loader
304to setup menus.
984263bc
MD
305.It Pa /boot/loader.conf
306user defined settings.
307.It Pa /boot/loader.conf.local
308machine-specific settings for sites with a common loader.conf.
b5ef8da1
TN
309.It Pa /boot/dloader.rc
310contains the instructions to automatically process.
984263bc
MD
311.El
312.Sh SEE ALSO
313.Xr boot 8 ,
9b38070e 314.Xr loader 8
984263bc
MD
315.Sh HISTORY
316The file
317.Nm
318first appeared in
319.Fx 3.2 .
320.Sh AUTHORS
321This manual page was written by
c616d378 322.An Daniel C. Sobral Aq Mt dcs@FreeBSD.org .