with the new boot loader configuration process. I got a lot of help from Daniel Sobral, and both Dan and I got help from Mike Smith. This really belongs in Warner's UPDATING, but he's not been answering his email recently, so that will wait a little. Robert Nordier also gave me a lot of help, but he hasn't seen the last version, and can't be blamed for my errors. Approved by: jkh Reviewed by: Mike Smith
247 lines
11 KiB
Plaintext
247 lines
11 KiB
Plaintext
README file, for the boot config file setup. This is meant
|
|
to explain how to manage the loader configuration process.
|
|
The boot and loading process is either defined, or being
|
|
defined in boot(8) and loader(8).
|
|
|
|
The ongoing development of the FreeBSD bootloader, and its
|
|
rapid deployment while still in the development phase, has
|
|
resulted in a large number of installations with outdated
|
|
configurations. Those installations actively tracking the
|
|
FreeBSD development should also ensure that their bootloader
|
|
configurations are updated. If you see files discussed here
|
|
that your system doesn't yet have, add them yourself.
|
|
|
|
This is an effort to give the currently correct method for
|
|
setting up your boot process. It includes information on
|
|
setting up screen savers and plug and play information, and
|
|
also on recording any changes you make in your kernel
|
|
configuration. This file is temporary, because as I noted,
|
|
the process is still undergoing development, and will still
|
|
change. Man pages are coming out, but they're still going
|
|
to be somewhat fragile for a while. If you note anything in
|
|
here that's broken, it would be a good idea to report it to
|
|
the FreeBSD-current list, or to Daniel C. Sobral
|
|
<dcs@FreeBSD.org> or Mike Smith <msmith@FreeBSD.org>.
|
|
|
|
NOTE:
|
|
|
|
Please understand, all this is very current development, and
|
|
while getting this working for STABLE is a goal, it's not
|
|
yet ready for that. It's possible that parts of this might
|
|
indeed work for stable, but if you're not absolutely sure
|
|
what you're doing, you're better off not using the
|
|
information in this README for STABLE. Use this for current
|
|
only for a while longer, please!
|
|
|
|
After the first two stages in the booting process (described
|
|
in boot(8)), the last stage of the booting process, called
|
|
the loader (see loader(8)) reads in the /boot/loader.rc
|
|
file. The two lines you should have there are:
|
|
|
|
include /boot/loader.4th
|
|
start
|
|
|
|
This reads the ficl (forth) initialization files, then
|
|
/boot/default/loader.conf. This file, which strongly
|
|
resembles in form /etc/rc.conf but functions quite
|
|
differently, has spots for endless user customization but
|
|
isn't yet completely finished. For one thing, it used to
|
|
assume a /kernel.config instead of a /boot/kernel.conf.
|
|
Watch the first few lines of /boot/defaults/loader.conf to
|
|
see if the file name changes.
|
|
|
|
[See the section at the end on loader.conf syntax]
|
|
|
|
You don't actually want to make any changes to
|
|
/boot/defaults/loader.conf, the file that is a hacking-
|
|
target is:
|
|
|
|
/boot/loader.conf
|
|
|
|
and might very likely not exist yet on your system). You
|
|
should copy /boot/defaults/loader.conf to /boot/loader.conf,
|
|
and then cut out anything you didn't want changed.
|
|
|
|
The start command also loads your kernel for you, so don't
|
|
put any lines in there like "load kernel", they'll fail (but
|
|
really have already worked for you). Start also reads in
|
|
the file /boot/defaults/loader.conf and /boot/loader.conf.
|
|
If you don't have /boot/loader.conf, you'll see a message on
|
|
boot about it, but it's a warning only, no other effects.
|
|
See the section on loader.conf syntax at the end of this
|
|
document, for some more pointers on loader.conf syntax.
|
|
|
|
The best way to manage splash screens is with entries in
|
|
/boot/loader.conf, and this is very clearly illustrated in
|
|
/boot/defaults/loader.conf (which you could just copy over
|
|
to /boot/loader.conf). I'm going to illustrate here how you
|
|
*could* do it in /boot/loader.conf (for information only)
|
|
but I don't recommend you do this; use the
|
|
/boot/defaults/loader.conf syntax, it's easier to get it
|
|
correct.
|
|
|
|
You can load your splash screen by putting the following
|
|
lines into /boot/loader.conf:
|
|
|
|
load splash_bmp
|
|
load -t splash_image_data /path/to/file.bmp
|
|
|
|
The top line causes the splash_bmp module to get loaded.
|
|
The second line has the parameter "-t" which tells the
|
|
loader that the class of DATA being loaded is not a module,
|
|
but instead a splash_image_data located in file
|
|
/path/to/file.bmp.
|
|
|
|
To get your plug and play data correctly set, run kget,
|
|
redirecting the output to /boot/kernel.conf. Note that kget
|
|
right now adds an extra "q" to it's output (from the q for
|
|
quit you press when you exit config), and if you want, you
|
|
can remove that from the file. Kget reports data only, so
|
|
feel free to run it, just to see the output. Make certain
|
|
you have the kernel option USERCONFIG set in your kernel, so
|
|
that you can do a boot -c, to initially set your cards up.
|
|
Then, edit /boot/loader.conf so that the following line
|
|
shows up (overwriting, in effect, a similar line in
|
|
/boot/default/loader.conf):
|
|
|
|
userconfig_script_load="YES"
|
|
|
|
My own pnp line looks like:
|
|
pnp 1 0 os irq0 15 irq1 0 drq0 1 drq1 0 port0 1332
|
|
(kget changes numbers from hexadecimal to decimal). Note
|
|
that, at this moment, the change from using /kernel.config
|
|
to using /boot/kernel.conf as the storage place for kernel
|
|
config changes is going on. Take a look at your
|
|
/boot/defaults/loader.conf, see what's defined as
|
|
userconfig_script_name, and if you override, make sure the
|
|
file exists. Note that the loader only has access to the
|
|
root filesystem, so be careful where you tell it to read
|
|
from.
|
|
|
|
|
|
o If you interrupt autoboot, you'll engage interactive
|
|
mode with loader. Everything you type will have the
|
|
same effects as if it were lines in /boot/loader.rc.
|
|
|
|
o While in interactive mode, you can get help by typing
|
|
"?", "help [<topic> [<subtopic>]]" and "help index".
|
|
These are mostly commands one would expect a normal
|
|
user to use. I recommend you play with them a little,
|
|
to gain further familiarity with what's going on.
|
|
|
|
Note that it is not possible to damage or corrupt your
|
|
system while experimenting with the loader, as it
|
|
cannot write to any of your filesystems.
|
|
|
|
o The command "unload" will unload everything. This is
|
|
very useful. Once loader.rc has finished and the
|
|
system is in the autoboot count-down, you will usually
|
|
have the kernel and other modules loaded. Now, suppose
|
|
your new /kernel is broken, how do you load
|
|
/kernel.old? By typing:
|
|
|
|
unload
|
|
load kernel.old
|
|
[any other modules you wish to load]
|
|
boot
|
|
|
|
o If you use loader.conf, you can do:
|
|
|
|
unload
|
|
set kernel_name=kernel.old
|
|
boot-conf
|
|
|
|
this will then load all the modules you have
|
|
configured, using kernel.old as kernel, and boot.
|
|
|
|
o From loader, you can use the command "more" to read the
|
|
contents of /boot/loader.rc, if you wish. This is not
|
|
FreeBSD's more. It is one of loader's builtin commands.
|
|
Useful if you can't quite recall what you have there.
|
|
:-) Of course, you can use this command to read
|
|
anything else you want.
|
|
|
|
o "boot -flag" works, "boot kernelname" works, "boot
|
|
-flag kernelname" doesn't. "boot kernelname -flag"
|
|
might work, but I'm not sure. The problem is that these
|
|
flags are kernel's flags, not boot's flags.
|
|
|
|
o There are a number of variables that can be set. You
|
|
can see them in loader.conf, but you can get much more
|
|
detailed information using the "help" command, eg. help
|
|
set <variablename>.
|
|
|
|
o The variable root_disk_unit is particularly important,
|
|
as it solves a relatively common problem. This problem
|
|
shows when the BIOS assign disk units in a different
|
|
way than the kernel. For example, if you have two IDE
|
|
disks, one on the primary, the other on the secondary
|
|
controller, and both as master, the default in most
|
|
kernels is having the first as wd0, and the second as
|
|
wd2. If your root partition is in wd2, you'll get an
|
|
error, because the BIOS sees these disks as 0 and 1
|
|
(well, 1 and 2), and that's what loader tells the
|
|
kernel. In this case, "set root_disk_unit=2" solves the
|
|
problem. You use this whenever the kernel fails to
|
|
mount to root partition because it has a wrong unit
|
|
number.
|
|
|
|
FILE OVERVIEW
|
|
|
|
|
|
o /boot/defaults/loader.conf -- Master configuration
|
|
file, not to be edited. Overridden by
|
|
/boot/loader.conf.
|
|
|
|
o /boot/loader.conf -- local system customization file,
|
|
in form very much like /boot/defaults/loader.conf.
|
|
This file is meant to be used by local users and the
|
|
sysinstall process.
|
|
|
|
o /boot/loader.conf.local -- local installation override
|
|
file. This is intended for use by installations with
|
|
large numbers of systems, to allow global policy
|
|
overrides. No FreeBSD tools should ever write this
|
|
file.
|
|
|
|
o /kernel.config -- old location of kernel configuration
|
|
changes (like pnp changes).
|
|
|
|
o /boot/kernel.conf -- new location for kernel
|
|
configuration changes.
|
|
|
|
o /boot/loader.rc -- loader initial configuration file,
|
|
chiefly used to source in a forth file, and start the
|
|
configuration process.
|
|
|
|
NOTES ON LOADER.CONF SYNTAX
|
|
|
|
I'm copy here from the last 11 lines from
|
|
/boot/defaults/loader.conf:
|
|
|
|
##############################################################
|
|
### Module loading syntax example ##########################
|
|
##############################################################
|
|
|
|
#module_load="YES" # loads module "module"
|
|
#module_name="realname" # uses "realname" instead of "module"
|
|
#module_type="type" # passes "-t type" to load
|
|
#module_flags="flags" # passes "flags" to the module
|
|
#module_before="cmd" # executes "cmd" before loading module
|
|
#module_after="cmd" # executes "cmd" after loading module
|
|
#module_error="cmd" # executes "cmd" if load fails
|
|
|
|
The way this works, the command processor used by the loader
|
|
(which is a subset of forth) inspects these variables for
|
|
their suffix, and the 7 lines above illustrate all the
|
|
currently defined suffixes, and their use. Take the part
|
|
before the underscore, and customize it i(make it unique)
|
|
for your particular use, keeping the suffix to allow the
|
|
particular function you want to activate. Extra underscores
|
|
are fine, because it's only the sufixes that are scanned
|
|
for.
|
|
|
|
|
|
|
|
(authors Chuck Robey and Daniel Sobral).
|