1 README file, for the boot config file setup. This is meant
2 to explain how to manage the loader configuration process.
3 The boot and loading process is either defined, or being
4 defined in boot(8) and loader(8).
5
6 The ongoing development of the FreeBSD bootloader, and its
7 rapid deployment while still in the development phase, has
8 resulted in a large number of installations with outdated
9 configurations. Those installations actively tracking the
10 FreeBSD development should also ensure that their bootloader
11 configurations are updated. If you see files discussed here
12 that your system doesn't yet have, add them yourself.
13
14 This is an effort to give the currently correct method for
15 setting up your boot process. It includes information on
16 setting up screen savers and plug and play information, and
17 also on recording any changes you make in your kernel
18 configuration. This file is temporary, because as I noted,
19 the process is still undergoing development, and will still
20 change. Man pages are coming out, but they're still going
21 to be somewhat fragile for a while. If you note anything in
22 here that's broken, it would be a good idea to report it to
23 the FreeBSD-current list, or to Daniel C. Sobral
24 <dcs@FreeBSD.org> or Mike Smith <msmith@FreeBSD.org>.
25
26 NOTE:
27
28 Please understand, all this is very current development, and
29 while getting this working for STABLE is a goal, it's not
30 yet ready for that. It's possible that parts of this might
31 indeed work for stable, but if you're not absolutely sure
32 what you're doing, you're better off not using the
33 information in this README for STABLE. Use this for current
34 only for a while longer, please!
35
36 After the first two stages in the booting process (described
37 in boot(8)), the last stage of the booting process, called
38 the loader (see loader(8)) reads in the /boot/loader.rc
39 file. The two lines you should have there are:
40
41 include /boot/loader.4th
42 start
43
44 This reads the ficl (forth) initialization files, then
45 /boot/default/loader.conf. This file, which strongly
46 resembles in form /etc/rc.conf but functions quite
47 differently, has spots for endless user customization but
48 isn't yet completely finished. For one thing, it used to
49 assume a /kernel.config instead of a /boot/kernel.conf.
50 Watch the first few lines of /boot/defaults/loader.conf to
51 see if the file name changes.
52
53 [See the section at the end on loader.conf syntax]
54
55 You don't actually want to make any changes to
56 /boot/defaults/loader.conf, the file that is a hacking-
57 target is:
58
59 /boot/loader.conf
60
61 and might very likely not exist yet on your system). You
62 should copy /boot/defaults/loader.conf to /boot/loader.conf,
63 and then cut out anything you didn't want changed.
64
65 The start command also loads your kernel for you, so don't
66 put any lines in there like "load kernel", they'll fail (but
67 really have already worked for you). Start also reads in
68 the file /boot/defaults/loader.conf and /boot/loader.conf.
69 If you don't have /boot/loader.conf, you'll see a message on
70 boot about it, but it's a warning only, no other effects.
71 See the section on loader.conf syntax at the end of this
72 document, for some more pointers on loader.conf syntax.
73
74 The best way to manage splash screens is with entries in
75 /boot/loader.conf, and this is very clearly illustrated in
76 /boot/defaults/loader.conf (which you could just copy over
77 to /boot/loader.conf). I'm going to illustrate here how you
78 *could* do it in /boot/loader.rc (for information only)
79 but I don't recommend you do this; use the
80 /boot/defaults/loader.conf syntax, it's easier to get it
81 correct.
82
83 You can load your splash screen by putting the following
84 lines into /boot/loader.rc:
85
86 load splash_bmp
87 load -t splash_image_data /path/to/file.bmp
88
89 The top line causes the splash_bmp module to get loaded.
90 The second line has the parameter "-t" which tells the
91 loader that the class of DATA being loaded is not a module,
92 but instead a splash_image_data located in file
93 /path/to/file.bmp.
94
95 To get your plug and play data correctly set, run kget,
96 redirecting the output to /boot/kernel.conf. Note that kget
97 right now adds an extra "q" to it's output (from the q for
98 quit you press when you exit config), and if you want, you
99 can remove that from the file. Kget reports data only, so
100 feel free to run it, just to see the output. Make certain
101 you have the kernel option USERCONFIG set in your kernel, so
102 that you can do a boot -c, to initially set your cards up.
103 Then, edit /boot/loader.conf so that the following line
104 shows up (overwriting, in effect, a similar line in
105 /boot/default/loader.conf):
106
107 userconfig_script_load="YES"
108
109 My own pnp line looks like:
110 pnp 1 0 os irq0 15 irq1 0 drq0 1 drq1 0 port0 1332
111 (kget changes numbers from hexadecimal to decimal). Note
112 that, at this moment, the change from using /kernel.config
113 to using /boot/kernel.conf as the storage place for kernel
114 config changes is going on. Take a look at your
115 /boot/defaults/loader.conf, see what's defined as
116 userconfig_script_name, and if you override, make sure the
117 file exists. Note that the loader only has access to the
118 root filesystem, so be careful where you tell it to read
119 from.
120
121
122 o If you interrupt autoboot, you'll engage interactive
123 mode with loader. Everything you type will have the
124 same effects as if it were lines in /boot/loader.rc.
125
126 o While in interactive mode, you can get help by typing
127 "?", "help [<topic> [<subtopic>]]" and "help index".
128 These are mostly commands one would expect a normal
129 user to use. I recommend you play with them a little,
130 to gain further familiarity with what's going on.
131
132 Note that it is not possible to damage or corrupt your
133 system while experimenting with the loader, as it
134 cannot write to any of your filesystems.
135
136 o The command "unload" will unload everything. This is
137 very useful. Once loader.rc has finished and the
138 system is in the autoboot count-down, you will usually
139 have the kernel and other modules loaded. Now, suppose
140 your new /kernel is broken, how do you load
141 /kernel.old? By typing:
142
143 unload
144 load kernel.old
145 [any other modules you wish to load]
146 boot
147
148 o If you use loader.conf, you can do:
149
150 unload
151 set kernel=kernel.old
152 boot-conf
153
154 this will then load all the modules you have
155 configured, using kernel.old as kernel, and boot.
156
157 o From loader, you can use the command "more" to read the
158 contents of /boot/loader.rc, if you wish. This is not
159 FreeBSD's more. It is one of loader's builtin commands.
160 Useful if you can't quite recall what you have there.
161 :-) Of course, you can use this command to read
162 anything else you want.
163
164 o "boot -flag" works, "boot kernelname" works, "boot
165 -flag kernelname" doesn't. "boot kernelname -flag"
166 might work, but I'm not sure. The problem is that these
167 flags are kernel's flags, not boot's flags.
168
169 o There are a number of variables that can be set. You
170 can see them in loader.conf, but you can get much more
171 detailed information using the "help" command, eg. help
172 set <variablename>.
173
174 o The variable root_disk_unit is particularly important,
175 as it solves a relatively common problem. This problem
176 shows when the BIOS assign disk units in a different
177 way than the kernel. For example, if you have two IDE
178 disks, one on the primary, the other on the secondary
179 controller, and both as master, the default in most
180 kernels is having the first as wd0, and the second as
181 wd2. If your root partition is in wd2, you'll get an
182 error, because the BIOS sees these disks as 0 and 1
183 (well, 1 and 2), and that's what loader tells the
184 kernel. In this case, "set root_disk_unit=2" solves the
185 problem. You use this whenever the kernel fails to
186 mount to root partition because it has a wrong unit
187 number.
188
189 FILE OVERVIEW
190
191
192 o /boot/defaults/loader.conf -- Master configuration
193 file, not to be edited. Overridden by
194 /boot/loader.conf.
195
196 o /boot/loader.conf -- local system customization file,
197 in form very much like /boot/defaults/loader.conf.
198 This file is meant to be used by local users and the
199 sysinstall process.
200
201 o /boot/loader.conf.local -- local installation override
202 file. This is intended for use by installations with
203 large numbers of systems, to allow global policy
204 overrides. No FreeBSD tools should ever write this
205 file.
206
207 o /kernel.config -- old location of kernel configuration
208 changes (like pnp changes).
209
210 o /boot/kernel.conf -- new location for kernel
211 configuration changes.
212
213 o /boot/loader.rc -- loader initial configuration file,
214 chiefly used to source in a forth file, and start the
215 configuration process.
216
217 NOTES ON LOADER.CONF SYNTAX
218
219 I'm copy here from the last 11 lines from
220 /boot/defaults/loader.conf:
221
222 ##############################################################
223 ### Module loading syntax example ##########################
224 ##############################################################
225
226 #module_load="YES" # loads module "module"
227 #module_name="realname" # uses "realname" instead of "module"
228 #module_type="type" # passes "-t type" to load
229 #module_flags="flags" # passes "flags" to the module
230 #module_before="cmd" # executes "cmd" before loading module
231 #module_after="cmd" # executes "cmd" after loading module
232 #module_error="cmd" # executes "cmd" if load fails
233
234 The way this works, the command processor used by the loader
235 (which is a subset of forth) inspects these variables for
236 their suffix, and the 7 lines above illustrate all the
237 currently defined suffixes, and their use. Take the part
238 before the underscore, and customize it i(make it unique)
239 for your particular use, keeping the suffix to allow the
240 particular function you want to activate. Extra underscores
241 are fine, because it's only the sufixes that are scanned
242 for.
243
244
245
246 (authors Chuck Robey and Daniel Sobral).
| 3 README file, for the boot config file setup. This is meant
4 to explain how to manage the loader configuration process.
5 The boot and loading process is either defined, or being
6 defined in boot(8) and loader(8).
7
8 The ongoing development of the FreeBSD bootloader, and its
9 rapid deployment while still in the development phase, has
10 resulted in a large number of installations with outdated
11 configurations. Those installations actively tracking the
12 FreeBSD development should also ensure that their bootloader
13 configurations are updated. If you see files discussed here
14 that your system doesn't yet have, add them yourself.
15
16 This is an effort to give the currently correct method for
17 setting up your boot process. It includes information on
18 setting up screen savers and plug and play information, and
19 also on recording any changes you make in your kernel
20 configuration. This file is temporary, because as I noted,
21 the process is still undergoing development, and will still
22 change. Man pages are coming out, but they're still going
23 to be somewhat fragile for a while. If you note anything in
24 here that's broken, it would be a good idea to report it to
25 the FreeBSD-current list, or to Daniel C. Sobral
26 <dcs@FreeBSD.org> or Mike Smith <msmith@FreeBSD.org>.
27
28 NOTE:
29
30 Please understand, all this is very current development, and
31 while getting this working for STABLE is a goal, it's not
32 yet ready for that. It's possible that parts of this might
33 indeed work for stable, but if you're not absolutely sure
34 what you're doing, you're better off not using the
35 information in this README for STABLE. Use this for current
36 only for a while longer, please!
37
38 After the first two stages in the booting process (described
39 in boot(8)), the last stage of the booting process, called
40 the loader (see loader(8)) reads in the /boot/loader.rc
41 file. The two lines you should have there are:
42
43 include /boot/loader.4th
44 start
45
46 This reads the ficl (forth) initialization files, then
47 /boot/default/loader.conf. This file, which strongly
48 resembles in form /etc/rc.conf but functions quite
49 differently, has spots for endless user customization but
50 isn't yet completely finished. For one thing, it used to
51 assume a /kernel.config instead of a /boot/kernel.conf.
52 Watch the first few lines of /boot/defaults/loader.conf to
53 see if the file name changes.
54
55 [See the section at the end on loader.conf syntax]
56
57 You don't actually want to make any changes to
58 /boot/defaults/loader.conf, the file that is a hacking-
59 target is:
60
61 /boot/loader.conf
62
63 and might very likely not exist yet on your system). You
64 should copy /boot/defaults/loader.conf to /boot/loader.conf,
65 and then cut out anything you didn't want changed.
66
67 The start command also loads your kernel for you, so don't
68 put any lines in there like "load kernel", they'll fail (but
69 really have already worked for you). Start also reads in
70 the file /boot/defaults/loader.conf and /boot/loader.conf.
71 If you don't have /boot/loader.conf, you'll see a message on
72 boot about it, but it's a warning only, no other effects.
73 See the section on loader.conf syntax at the end of this
74 document, for some more pointers on loader.conf syntax.
75
76 The best way to manage splash screens is with entries in
77 /boot/loader.conf, and this is very clearly illustrated in
78 /boot/defaults/loader.conf (which you could just copy over
79 to /boot/loader.conf). I'm going to illustrate here how you
80 *could* do it in /boot/loader.rc (for information only)
81 but I don't recommend you do this; use the
82 /boot/defaults/loader.conf syntax, it's easier to get it
83 correct.
84
85 You can load your splash screen by putting the following
86 lines into /boot/loader.rc:
87
88 load splash_bmp
89 load -t splash_image_data /path/to/file.bmp
90
91 The top line causes the splash_bmp module to get loaded.
92 The second line has the parameter "-t" which tells the
93 loader that the class of DATA being loaded is not a module,
94 but instead a splash_image_data located in file
95 /path/to/file.bmp.
96
97 To get your plug and play data correctly set, run kget,
98 redirecting the output to /boot/kernel.conf. Note that kget
99 right now adds an extra "q" to it's output (from the q for
100 quit you press when you exit config), and if you want, you
101 can remove that from the file. Kget reports data only, so
102 feel free to run it, just to see the output. Make certain
103 you have the kernel option USERCONFIG set in your kernel, so
104 that you can do a boot -c, to initially set your cards up.
105 Then, edit /boot/loader.conf so that the following line
106 shows up (overwriting, in effect, a similar line in
107 /boot/default/loader.conf):
108
109 userconfig_script_load="YES"
110
111 My own pnp line looks like:
112 pnp 1 0 os irq0 15 irq1 0 drq0 1 drq1 0 port0 1332
113 (kget changes numbers from hexadecimal to decimal). Note
114 that, at this moment, the change from using /kernel.config
115 to using /boot/kernel.conf as the storage place for kernel
116 config changes is going on. Take a look at your
117 /boot/defaults/loader.conf, see what's defined as
118 userconfig_script_name, and if you override, make sure the
119 file exists. Note that the loader only has access to the
120 root filesystem, so be careful where you tell it to read
121 from.
122
123
124 o If you interrupt autoboot, you'll engage interactive
125 mode with loader. Everything you type will have the
126 same effects as if it were lines in /boot/loader.rc.
127
128 o While in interactive mode, you can get help by typing
129 "?", "help [<topic> [<subtopic>]]" and "help index".
130 These are mostly commands one would expect a normal
131 user to use. I recommend you play with them a little,
132 to gain further familiarity with what's going on.
133
134 Note that it is not possible to damage or corrupt your
135 system while experimenting with the loader, as it
136 cannot write to any of your filesystems.
137
138 o The command "unload" will unload everything. This is
139 very useful. Once loader.rc has finished and the
140 system is in the autoboot count-down, you will usually
141 have the kernel and other modules loaded. Now, suppose
142 your new /kernel is broken, how do you load
143 /kernel.old? By typing:
144
145 unload
146 load kernel.old
147 [any other modules you wish to load]
148 boot
149
150 o If you use loader.conf, you can do:
151
152 unload
153 set kernel=kernel.old
154 boot-conf
155
156 this will then load all the modules you have
157 configured, using kernel.old as kernel, and boot.
158
159 o From loader, you can use the command "more" to read the
160 contents of /boot/loader.rc, if you wish. This is not
161 FreeBSD's more. It is one of loader's builtin commands.
162 Useful if you can't quite recall what you have there.
163 :-) Of course, you can use this command to read
164 anything else you want.
165
166 o "boot -flag" works, "boot kernelname" works, "boot
167 -flag kernelname" doesn't. "boot kernelname -flag"
168 might work, but I'm not sure. The problem is that these
169 flags are kernel's flags, not boot's flags.
170
171 o There are a number of variables that can be set. You
172 can see them in loader.conf, but you can get much more
173 detailed information using the "help" command, eg. help
174 set <variablename>.
175
176 o The variable root_disk_unit is particularly important,
177 as it solves a relatively common problem. This problem
178 shows when the BIOS assign disk units in a different
179 way than the kernel. For example, if you have two IDE
180 disks, one on the primary, the other on the secondary
181 controller, and both as master, the default in most
182 kernels is having the first as wd0, and the second as
183 wd2. If your root partition is in wd2, you'll get an
184 error, because the BIOS sees these disks as 0 and 1
185 (well, 1 and 2), and that's what loader tells the
186 kernel. In this case, "set root_disk_unit=2" solves the
187 problem. You use this whenever the kernel fails to
188 mount to root partition because it has a wrong unit
189 number.
190
191 FILE OVERVIEW
192
193
194 o /boot/defaults/loader.conf -- Master configuration
195 file, not to be edited. Overridden by
196 /boot/loader.conf.
197
198 o /boot/loader.conf -- local system customization file,
199 in form very much like /boot/defaults/loader.conf.
200 This file is meant to be used by local users and the
201 sysinstall process.
202
203 o /boot/loader.conf.local -- local installation override
204 file. This is intended for use by installations with
205 large numbers of systems, to allow global policy
206 overrides. No FreeBSD tools should ever write this
207 file.
208
209 o /kernel.config -- old location of kernel configuration
210 changes (like pnp changes).
211
212 o /boot/kernel.conf -- new location for kernel
213 configuration changes.
214
215 o /boot/loader.rc -- loader initial configuration file,
216 chiefly used to source in a forth file, and start the
217 configuration process.
218
219 NOTES ON LOADER.CONF SYNTAX
220
221 I'm copy here from the last 11 lines from
222 /boot/defaults/loader.conf:
223
224 ##############################################################
225 ### Module loading syntax example ##########################
226 ##############################################################
227
228 #module_load="YES" # loads module "module"
229 #module_name="realname" # uses "realname" instead of "module"
230 #module_type="type" # passes "-t type" to load
231 #module_flags="flags" # passes "flags" to the module
232 #module_before="cmd" # executes "cmd" before loading module
233 #module_after="cmd" # executes "cmd" after loading module
234 #module_error="cmd" # executes "cmd" if load fails
235
236 The way this works, the command processor used by the loader
237 (which is a subset of forth) inspects these variables for
238 their suffix, and the 7 lines above illustrate all the
239 currently defined suffixes, and their use. Take the part
240 before the underscore, and customize it i(make it unique)
241 for your particular use, keeping the suffix to allow the
242 particular function you want to activate. Extra underscores
243 are fine, because it's only the sufixes that are scanned
244 for.
245
246
247
248 (authors Chuck Robey and Daniel Sobral).
|