README revision 44842
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.conf (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.conf: 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_name=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). 247
