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