NameDateSize

..11-Dec-201810

common/06-Dec-201955

efi/01-Jul-20197

forth/17-Sep-201933

i386/01-Jul-201914

libcrypto/06-Oct-20198

libficl/19-Aug-20198

libstand/06-Oct-20196

Makefile23-Feb-20191.2 KiB

Makefile.inc26-Nov-20192.6 KiB

README23-Sep-201610.8 KiB

README

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