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