README revision 59874
1$FreeBSD: head/sys/boot/README 59874 2000-05-01 20:32:07Z peter $ 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 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). 249
