sys/boot/README

   1 $FreeBSD: src/sys/boot/README,v 1.3 2000/05/01 20:26:17 peter Exp $
   2 $DragonFly: src/sys/boot/README,v 1.4 2005/02/26 12:00:55 swildner Exp $
   3
   4        README file, for the boot config file setup.  This is meant
   5        to explain how to manage the loader configuration process.
   6        The boot and loading process is either defined, or being
   7        defined in boot(8) and loader(8).
   8
   9        The ongoing development of the FreeBSD bootloader, and its
  10        rapid deployment while still in the development phase, has
  11        resulted in a large number of installations with outdated
  12        configurations.  Those installations actively tracking the
  13        FreeBSD development should also ensure that their bootloader
  14        configurations are updated.  If you see files discussed here
  15        that your system doesn't yet have, add them yourself.
  16
  17        This is an effort to give the currently correct method for
  18        setting up your boot process.  It includes information on
  19        setting up screen savers and plug and play information, and
  20        also on recording any changes you make in your kernel
  21        configuration.  This file is temporary, because as I noted,
  22        the process is still undergoing development, and will still
  23        change.  Man pages are coming out, but they're still going
  24        to be somewhat fragile for a while.  If you note anything in
  25        here that's broken, it would be a good idea to report it to
  26        the FreeBSD-current list, or to Daniel C. Sobral
  27        <dcs@FreeBSD.org> or Mike Smith <msmith@FreeBSD.org>.
  28
  29        NOTE:
  30
  31        Please understand, all this is very current development, and
  32        while getting this working for STABLE is a goal, it's not
  33        yet ready for that.  It's possible that parts of this might
  34        indeed work for stable, but if you're not absolutely sure
  35        what you're doing, you're better off not using the
  36        information in this README for STABLE.  Use this for current
  37        only for a while longer, please!
  38
  39        After the first two stages in the booting process (described
  40        in boot(8)), the last stage of the booting process, called
  41        the loader (see loader(8)) reads in the /boot/loader.rc
  42        file.  The two lines you should have there are:
  43
  44        include /boot/loader.4th
  45        start
  46
  47        This reads the ficl (forth) initialization files, then
  48        /boot/default/loader.conf.  This file, which strongly
  49        resembles in form /etc/rc.conf but functions quite
  50        differently, has spots for endless user customization but
  51        isn't yet completely finished.  For one thing, it used to
  52        assume a /kernel.config instead of a /boot/kernel.conf.
  53        Watch the first few lines of /boot/defaults/loader.conf to
  54        see if the file name changes.
  55
  56        [See the section at the end on loader.conf syntax]
  57
  58        You don't actually want to make any changes to
  59        /boot/defaults/loader.conf, the file that is a  hacking-
  60        target is:
  61
  62        /boot/loader.conf
  63
  64        and might very likely not exist yet on your system).  You
  65        should copy /boot/defaults/loader.conf to /boot/loader.conf,
  66        and then cut out anything you didn't want changed.
  67
  68        The start command also loads your kernel for you, so don't
  69        put any lines in there like "load kernel", they'll fail (but
  70        really have already worked for you).  Start also reads in
  71        the file /boot/defaults/loader.conf and /boot/loader.conf.
  72        If you don't have /boot/loader.conf, you'll see a message on
  73        boot about it, but it's a warning only, no other effects.
  74        See the section on loader.conf syntax at the end of this
  75        document, for some more pointers on loader.conf syntax.
  76
  77        The best way to manage splash screens is with entries in
  78        /boot/loader.conf, and this is very clearly illustrated in
  79        /boot/defaults/loader.conf (which you could just copy over
  80        to /boot/loader.conf).  I'm going to illustrate here how you
  81        *could* do it in /boot/loader.rc (for information only)
  82        but I don't recommend you do this; use the
  83        /boot/defaults/loader.conf syntax, it's easier to get it
  84        correct.
  85
  86        You can load your splash screen by putting the following
  87        lines into /boot/loader.rc:
  88
  89        load splash_bmp
  90        load -t splash_image_data /path/to/file.bmp
  91
  92        The top line causes the splash_bmp module to get loaded.
  93        The second line has the parameter "-t" which tells the
  94        loader that the class of DATA being loaded is not a module,
  95        but instead a splash_image_data located in file
  96        /path/to/file.bmp.
  97
  98        To get your plug and play data correctly set, run kget,
  99        redirecting the output to /boot/kernel.conf.  Note that kget
 100        right now adds an extra "q" to it's output (from the q for
 101        quit you press when you exit config), and if you want, you
 102        can remove that from the file.  Kget reports data only, so
 103        feel free to run it, just to see the output.  Make certain
 104        you have the kernel option USERCONFIG set in your kernel, so
 105        that you can do a boot -c, to initially set your cards up.
 106        Then, edit /boot/loader.conf so that the following line
 107        shows up (overwriting, in effect, a similar line in
 108        /boot/default/loader.conf):
 109
 110        userconfig_script_load="YES"
 111
 112        My own pnp line looks like:
 113        pnp 1 0 os irq0 15 irq1 0 drq0 1 drq1 0 port0 1332
 114        (kget changes numbers from hexadecimal to decimal).  Note
 115        that, at this moment, the change from using /kernel.config
 116        to using /boot/kernel.conf as the storage place for kernel
 117        config changes is going on.  Take a look at your
 118        /boot/defaults/loader.conf, see what's defined as
 119        userconfig_script_name, and if you override, make sure the
 120        file exists.  Note that the loader only has access to the
 121        root filesystem, so be careful where you tell it to read
 122        from.
 123
 124
 125           o If you interrupt autoboot, you'll engage interactive
 126             mode with loader. Everything you type will have the
 127             same effects as if it were lines in /boot/loader.rc.
 128
 129           o While in interactive mode, you can get help by typing
 130             "?", "help [<topic> [<subtopic>]]" and "help index".
 131             These are mostly commands one would expect a normal
 132             user to use. I recommend you play with them a little,
 133             to gain further familiarity with what's going on.
 134
 135             Note that it is not possible to damage or corrupt your
 136             system while experimenting with the loader, as it
 137             cannot write to any of your filesystems.
 138
 139           o The command "unload" will unload everything. This is
 140             very useful.  Once loader.rc has finished and the
 141             system is in the autoboot count-down, you will usually
 142             have the kernel and other modules loaded. Now, suppose
 143             your new /kernel is broken, how do you load
 144             /kernel.old? By typing:
 145
 146                  unload
 147                  load kernel.old
 148                  [any other modules you wish to load]
 149                  boot
 150
 151           o If you use loader.conf, you can do:
 152
 153                  unload
 154                  set kernel=kernel.old
 155                  boot-conf
 156
 157             this will then load all the modules you have
 158             configured, using kernel.old as kernel, and boot.
 159
 160           o From loader, you can use the command "more" to read the
 161             contents of /boot/loader.rc, if you wish. This is not
 162             FreeBSD's more. It is one of loader's builtin commands.
 163             Useful if you can't quite recall what you have there.
 164             :-) Of course, you can use this command to read
 165             anything else you want.
 166
 167           o "boot -flag" works, "boot kernelname" works, "boot
 168             -flag kernelname" doesn't. "boot kernelname -flag"
 169             might work, but I'm not sure. The problem is that these
 170             flags are kernel's flags, not boot's flags.
 171
 172           o There are a number of variables that can be set. You
 173             can see them in loader.conf, but you can get much more
 174             detailed information using the "help" command, eg. help
 175             set <variablename>.
 176
 177           o The variable root_disk_unit is particularly important,
 178             as it solves a relatively common problem. This problem
 179             shows when the BIOS assign disk units in a different
 180             way than the kernel. For example, if you have two IDE
 181             disks, one on the primary, the other on the secondary
 182             controller, and both as master, the default in most
 183             kernels is having the first as ad0, and the second as
 184             ad2. If your root partition is in ad2, you'll get an
 185             error, because the BIOS sees these disks as 0 and 1
 186             (well, 1 and 2), and that's what loader tells the
 187             kernel. In this case, "set root_disk_unit=2" solves the
 188             problem.  You use this whenever the kernel fails to
 189             mount to root partition because it has a wrong unit
 190             number.
 191
 192        FILE OVERVIEW
 193
 194
 195           o /boot/defaults/loader.conf -- Master configuration
 196             file, not to be edited.  Overridden by
 197             /boot/loader.conf.
 198
 199           o /boot/loader.conf -- local system customization file,
 200             in form very much like /boot/defaults/loader.conf.
 201             This file is meant to be used by local users and the
 202             sysinstall process.
 203
 204           o /boot/loader.conf.local -- local installation override
 205             file.  This is intended for use by installations with
 206             large numbers of systems, to allow global policy
 207             overrides.  No FreeBSD tools should ever write this
 208             file.
 209
 210           o /kernel.config -- old location of kernel configuration
 211             changes (like pnp changes).
 212
 213           o /boot/kernel.conf -- new location for kernel
 214             configuration changes.
 215
 216           o /boot/loader.rc -- loader initial configuration file,
 217             chiefly used to source in a forth file, and start the
 218             configuration process.
 219
 220        NOTES ON LOADER.CONF SYNTAX
 221
 222        I'm copy here from the last 11 lines from
 223        /boot/defaults/loader.conf:
 224
 225        ##############################################################
 226        ###  Module loading syntax example  ##########################
 227        ##############################################################
 228
 229        #module_load="YES"              # loads module "module"
 230        #module_name="realname"         # uses "realname" instead of "module"
 231        #module_type="type"             # passes "-t type" to load
 232        #module_flags="flags"           # passes "flags" to the module
 233        #module_before="cmd"            # executes "cmd" before loading module
 234        #module_after="cmd"             # executes "cmd" after loading module
 235        #module_error="cmd"             # executes "cmd" if load fails
 236
 237        The way this works, the command processor used by the loader
 238        (which is a subset of forth) inspects  these  variables  for
 239        their  suffix,  and  the  7  lines  above illustrate all the
 240        currently defined suffixes, and their use.   Take  the  part
 241        before  the  underscore,  and customize it i(make it unique)
 242        for your particular use, keeping the  suffix  to  allow  the
 243        particular function you want to activate.  Extra underscores
 244        are fine, because it's only the  sufixes  that  are  scanned
 245        for.
 246
 247
 248
 249        (authors Chuck Robey and Daniel Sobral).