sys/boot/README

   1 $FreeBSD: src/sys/boot/README,v 1.2.2.1 2000/07/07 21:12:28 jhb Exp $
   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).