README revision 44912
144842Schuckr README file, for the boot config file setup. This is meant 244842Schuckr to explain how to manage the loader configuration process. 344842Schuckr The boot and loading process is either defined, or being 444842Schuckr defined in boot(8) and loader(8). 544842Schuckr 644842Schuckr The ongoing development of the FreeBSD bootloader, and its 744842Schuckr rapid deployment while still in the development phase, has 844842Schuckr resulted in a large number of installations with outdated 944842Schuckr configurations. Those installations actively tracking the 1044842Schuckr FreeBSD development should also ensure that their bootloader 1144842Schuckr configurations are updated. If you see files discussed here 1244842Schuckr that your system doesn't yet have, add them yourself. 1344842Schuckr 1444842Schuckr This is an effort to give the currently correct method for 1544842Schuckr setting up your boot process. It includes information on 1644842Schuckr setting up screen savers and plug and play information, and 1744842Schuckr also on recording any changes you make in your kernel 1844842Schuckr configuration. This file is temporary, because as I noted, 1944842Schuckr the process is still undergoing development, and will still 2044842Schuckr change. Man pages are coming out, but they're still going 2144842Schuckr to be somewhat fragile for a while. If you note anything in 2244842Schuckr here that's broken, it would be a good idea to report it to 2344842Schuckr the FreeBSD-current list, or to Daniel C. Sobral 2444842Schuckr <dcs@FreeBSD.org> or Mike Smith <msmith@FreeBSD.org>. 2544842Schuckr 2644842Schuckr NOTE: 2744842Schuckr 2844842Schuckr Please understand, all this is very current development, and 2944842Schuckr while getting this working for STABLE is a goal, it's not 3044842Schuckr yet ready for that. It's possible that parts of this might 3144842Schuckr indeed work for stable, but if you're not absolutely sure 3244842Schuckr what you're doing, you're better off not using the 3344842Schuckr information in this README for STABLE. Use this for current 3444842Schuckr only for a while longer, please! 3544842Schuckr 3644842Schuckr After the first two stages in the booting process (described 3744842Schuckr in boot(8)), the last stage of the booting process, called 3844842Schuckr the loader (see loader(8)) reads in the /boot/loader.rc 3944842Schuckr file. The two lines you should have there are: 4044842Schuckr 4144842Schuckr include /boot/loader.4th 4244842Schuckr start 4344842Schuckr 4444842Schuckr This reads the ficl (forth) initialization files, then 4544842Schuckr /boot/default/loader.conf. This file, which strongly 4644842Schuckr resembles in form /etc/rc.conf but functions quite 4744842Schuckr differently, has spots for endless user customization but 4844842Schuckr isn't yet completely finished. For one thing, it used to 4944842Schuckr assume a /kernel.config instead of a /boot/kernel.conf. 5044842Schuckr Watch the first few lines of /boot/defaults/loader.conf to 5144842Schuckr see if the file name changes. 5244842Schuckr 5344842Schuckr [See the section at the end on loader.conf syntax] 5444842Schuckr 5544842Schuckr You don't actually want to make any changes to 5644842Schuckr /boot/defaults/loader.conf, the file that is a hacking- 5744842Schuckr target is: 5844842Schuckr 5944842Schuckr /boot/loader.conf 6044842Schuckr 6144842Schuckr and might very likely not exist yet on your system). You 6244842Schuckr should copy /boot/defaults/loader.conf to /boot/loader.conf, 6344842Schuckr and then cut out anything you didn't want changed. 6444842Schuckr 6544842Schuckr The start command also loads your kernel for you, so don't 6644842Schuckr put any lines in there like "load kernel", they'll fail (but 6744842Schuckr really have already worked for you). Start also reads in 6844842Schuckr the file /boot/defaults/loader.conf and /boot/loader.conf. 6944842Schuckr If you don't have /boot/loader.conf, you'll see a message on 7044842Schuckr boot about it, but it's a warning only, no other effects. 7144842Schuckr See the section on loader.conf syntax at the end of this 7244842Schuckr document, for some more pointers on loader.conf syntax. 7344842Schuckr 7444842Schuckr The best way to manage splash screens is with entries in 7544842Schuckr /boot/loader.conf, and this is very clearly illustrated in 7644842Schuckr /boot/defaults/loader.conf (which you could just copy over 7744842Schuckr to /boot/loader.conf). I'm going to illustrate here how you 7844912Sdcs *could* do it in /boot/loader.rc (for information only) 7944842Schuckr but I don't recommend you do this; use the 8044842Schuckr /boot/defaults/loader.conf syntax, it's easier to get it 8144842Schuckr correct. 8244842Schuckr 8344842Schuckr You can load your splash screen by putting the following 8444912Sdcs lines into /boot/loader.rc: 8544842Schuckr 8644842Schuckr load splash_bmp 8744842Schuckr load -t splash_image_data /path/to/file.bmp 8844842Schuckr 8944842Schuckr The top line causes the splash_bmp module to get loaded. 9044842Schuckr The second line has the parameter "-t" which tells the 9144842Schuckr loader that the class of DATA being loaded is not a module, 9244842Schuckr but instead a splash_image_data located in file 9344842Schuckr /path/to/file.bmp. 9444842Schuckr 9544842Schuckr To get your plug and play data correctly set, run kget, 9644842Schuckr redirecting the output to /boot/kernel.conf. Note that kget 9744842Schuckr right now adds an extra "q" to it's output (from the q for 9844842Schuckr quit you press when you exit config), and if you want, you 9944842Schuckr can remove that from the file. Kget reports data only, so 10044842Schuckr feel free to run it, just to see the output. Make certain 10144842Schuckr you have the kernel option USERCONFIG set in your kernel, so 10244842Schuckr that you can do a boot -c, to initially set your cards up. 10344842Schuckr Then, edit /boot/loader.conf so that the following line 10444842Schuckr shows up (overwriting, in effect, a similar line in 10544842Schuckr /boot/default/loader.conf): 10644842Schuckr 10744842Schuckr userconfig_script_load="YES" 10844842Schuckr 10944842Schuckr My own pnp line looks like: 11044842Schuckr pnp 1 0 os irq0 15 irq1 0 drq0 1 drq1 0 port0 1332 11144842Schuckr (kget changes numbers from hexadecimal to decimal). Note 11244842Schuckr that, at this moment, the change from using /kernel.config 11344842Schuckr to using /boot/kernel.conf as the storage place for kernel 11444842Schuckr config changes is going on. Take a look at your 11544842Schuckr /boot/defaults/loader.conf, see what's defined as 11644842Schuckr userconfig_script_name, and if you override, make sure the 11744842Schuckr file exists. Note that the loader only has access to the 11844842Schuckr root filesystem, so be careful where you tell it to read 11944842Schuckr from. 12044842Schuckr 12144842Schuckr 12244842Schuckr o If you interrupt autoboot, you'll engage interactive 12344842Schuckr mode with loader. Everything you type will have the 12444842Schuckr same effects as if it were lines in /boot/loader.rc. 12544842Schuckr 12644842Schuckr o While in interactive mode, you can get help by typing 12744842Schuckr "?", "help [<topic> [<subtopic>]]" and "help index". 12844842Schuckr These are mostly commands one would expect a normal 12944842Schuckr user to use. I recommend you play with them a little, 13044842Schuckr to gain further familiarity with what's going on. 13144842Schuckr 13244842Schuckr Note that it is not possible to damage or corrupt your 13344842Schuckr system while experimenting with the loader, as it 13444842Schuckr cannot write to any of your filesystems. 13544842Schuckr 13644842Schuckr o The command "unload" will unload everything. This is 13744842Schuckr very useful. Once loader.rc has finished and the 13844842Schuckr system is in the autoboot count-down, you will usually 13944842Schuckr have the kernel and other modules loaded. Now, suppose 14044842Schuckr your new /kernel is broken, how do you load 14144842Schuckr /kernel.old? By typing: 14244842Schuckr 14344842Schuckr unload 14444842Schuckr load kernel.old 14544842Schuckr [any other modules you wish to load] 14644842Schuckr boot 14744842Schuckr 14844842Schuckr o If you use loader.conf, you can do: 14944842Schuckr 15044842Schuckr unload 15144912Sdcs set kernel=kernel.old 15244842Schuckr boot-conf 15344842Schuckr 15444842Schuckr this will then load all the modules you have 15544842Schuckr configured, using kernel.old as kernel, and boot. 15644842Schuckr 15744842Schuckr o From loader, you can use the command "more" to read the 15844842Schuckr contents of /boot/loader.rc, if you wish. This is not 15944842Schuckr FreeBSD's more. It is one of loader's builtin commands. 16044842Schuckr Useful if you can't quite recall what you have there. 16144842Schuckr :-) Of course, you can use this command to read 16244842Schuckr anything else you want. 16344842Schuckr 16444842Schuckr o "boot -flag" works, "boot kernelname" works, "boot 16544842Schuckr -flag kernelname" doesn't. "boot kernelname -flag" 16644842Schuckr might work, but I'm not sure. The problem is that these 16744842Schuckr flags are kernel's flags, not boot's flags. 16844842Schuckr 16944842Schuckr o There are a number of variables that can be set. You 17044842Schuckr can see them in loader.conf, but you can get much more 17144842Schuckr detailed information using the "help" command, eg. help 17244842Schuckr set <variablename>. 17344842Schuckr 17444842Schuckr o The variable root_disk_unit is particularly important, 17544842Schuckr as it solves a relatively common problem. This problem 17644842Schuckr shows when the BIOS assign disk units in a different 17744842Schuckr way than the kernel. For example, if you have two IDE 17844842Schuckr disks, one on the primary, the other on the secondary 17944842Schuckr controller, and both as master, the default in most 18044842Schuckr kernels is having the first as wd0, and the second as 18144842Schuckr wd2. If your root partition is in wd2, you'll get an 18244842Schuckr error, because the BIOS sees these disks as 0 and 1 18344842Schuckr (well, 1 and 2), and that's what loader tells the 18444842Schuckr kernel. In this case, "set root_disk_unit=2" solves the 18544842Schuckr problem. You use this whenever the kernel fails to 18644842Schuckr mount to root partition because it has a wrong unit 18744842Schuckr number. 18844842Schuckr 18944842Schuckr FILE OVERVIEW 19044842Schuckr 19144842Schuckr 19244842Schuckr o /boot/defaults/loader.conf -- Master configuration 19344842Schuckr file, not to be edited. Overridden by 19444842Schuckr /boot/loader.conf. 19544842Schuckr 19644842Schuckr o /boot/loader.conf -- local system customization file, 19744842Schuckr in form very much like /boot/defaults/loader.conf. 19844842Schuckr This file is meant to be used by local users and the 19944842Schuckr sysinstall process. 20044842Schuckr 20144842Schuckr o /boot/loader.conf.local -- local installation override 20244842Schuckr file. This is intended for use by installations with 20344842Schuckr large numbers of systems, to allow global policy 20444842Schuckr overrides. No FreeBSD tools should ever write this 20544842Schuckr file. 20644842Schuckr 20744842Schuckr o /kernel.config -- old location of kernel configuration 20844842Schuckr changes (like pnp changes). 20944842Schuckr 21044842Schuckr o /boot/kernel.conf -- new location for kernel 21144842Schuckr configuration changes. 21244842Schuckr 21344842Schuckr o /boot/loader.rc -- loader initial configuration file, 21444842Schuckr chiefly used to source in a forth file, and start the 21544842Schuckr configuration process. 21644842Schuckr 21744842Schuckr NOTES ON LOADER.CONF SYNTAX 21844842Schuckr 21944842Schuckr I'm copy here from the last 11 lines from 22044842Schuckr /boot/defaults/loader.conf: 22144842Schuckr 22244842Schuckr ############################################################## 22344842Schuckr ### Module loading syntax example ########################## 22444842Schuckr ############################################################## 22544842Schuckr 22644842Schuckr #module_load="YES" # loads module "module" 22744842Schuckr #module_name="realname" # uses "realname" instead of "module" 22844842Schuckr #module_type="type" # passes "-t type" to load 22944842Schuckr #module_flags="flags" # passes "flags" to the module 23044842Schuckr #module_before="cmd" # executes "cmd" before loading module 23144842Schuckr #module_after="cmd" # executes "cmd" after loading module 23244842Schuckr #module_error="cmd" # executes "cmd" if load fails 23344842Schuckr 23444842Schuckr The way this works, the command processor used by the loader 23544842Schuckr (which is a subset of forth) inspects these variables for 23644842Schuckr their suffix, and the 7 lines above illustrate all the 23744842Schuckr currently defined suffixes, and their use. Take the part 23844842Schuckr before the underscore, and customize it i(make it unique) 23944842Schuckr for your particular use, keeping the suffix to allow the 24044842Schuckr particular function you want to activate. Extra underscores 24144842Schuckr are fine, because it's only the sufixes that are scanned 24244842Schuckr for. 24344842Schuckr 24444842Schuckr 24544842Schuckr 24644842Schuckr (authors Chuck Robey and Daniel Sobral). 247