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
