docs/handbook/Booting/index.mdwn

   1 # The DragonFly Booting Process
   2 [[!toc  levels=3]]
   3
   4 ## Synopsis
   5
   6 The process of starting a computer and loading the operating system is referred to as ***the bootstrap process***, or simply ***booting***. DragonFly's boot process provides a great deal of flexibility in customizing what happens when you start the system, allowing you to select from different operating systems installed on the same computer, or even different versions of the same operating system or installed kernel.
   7
   8 This chapter details the configuration options you can set and how to customize the DragonFly boot process. This includes everything that happens until the DragonFly kernel has started, probed for devices, and started [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#init&section8). If you are not quite sure when this happens, it occurs when the text color changes from bright white to grey.
   9
  10 After reading this chapter, you will know:
  11
  12 * What the components of the DragonFly bootstrap system are, and how they interact.
  13
  14 * The options you can give to the components in the DragonFly bootstrap to control the boot process.
  15
  16 * The basics of [device.hints(5)](http://leaf.dragonflybsd.org/cgi/web-man?command#device.hints&section5&manpath=FreeBSD+5.2-current).
  17
  18  **x86 Only:** This chapter only describes the boot process for DragonFly running on x86 systems.
  19
  20 ## The Booting Problem
  21
  22 Turning on a computer and starting the operating system poses an interesting dilemma. By definition, the computer does not know how to do anything until the operating system is started. This includes running programs from the disk. So if the computer can not run a program from the disk without the operating system, and the operating system programs are on the disk, how is the operating system started?
  23
  24 This problem parallels one in the book ***The Adventures of Baron Munchausen***. A character had fallen part way down a manhole, and pulled himself out by grabbing his bootstraps, and lifting. In the early days of computing the term ***bootstrap*** was applied to the mechanism used to load the operating system, which has become shortened to ***booting***.
  25
  26 On x86 hardware the Basic Input/Output System (BIOS) is responsible for loading the operating system. To do this, the BIOS looks on the hard disk for the Master Boot Record (MBR), which must be located on a specific place on the disk. The BIOS has enough knowledge to load and run the MBR, and assumes that the MBR can then carry out the rest of the tasks involved in loading the operating system possibly with the help of the BIOS.
  27
  28 The code within the MBR is usually referred to as a ***boot manager***, especially when it interacts with the user. In this case the boot manager usually has more code in the first ***track*** of the disk or within some OS's file system. (A boot manager is sometimes also called a ***boot loader***, but FreeBSD uses that term for a later stage of booting.) Popular boot managers include  **boot0**  (a.k.a.  **Boot Easy** , the standard DragonFly boot manager),  **Grub** ,  **GAG** , and  **LILO** . (Only  **boot0**  fits within the MBR.)
  29
  30 If you have only one operating system installed on your disks then a standard PC MBR will suffice. This MBR searches for the first bootable (a.k.a. active) slice on the disk, and then runs the code on that slice to load the remainder of the operating system. The MBR installed by [fdisk(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fdisk&section=8), by default, is such an MBR. It is based on `/boot/mbr`.
  31
  32 If you have installed multiple operating systems on your disks then you can install a different boot manager, one that can display a list of different operating systems, and allows you to choose the one to boot from. Two of these are discussed in the next subsection.
  33
  34 The remainder of the DragonFly bootstrap system is divided into three stages. The first stage is run by the MBR, which knows just enough to get the computer into a specific state and run the second stage. The second stage can do a little bit more, before running the third stage. The third stage finishes the task of loading the operating system. The work is split into these three stages because the PC standards put limits on the size of the programs that can be run at stages one and two. Chaining the tasks together allows DragonFly to provide a more flexible loader.
  35
  36 The kernel is then started and it begins to probe for devices and initialize them for use. Once the kernel boot process is finished, the kernel passes control to the user process [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8), which then makes sure the disks are in a usable state. [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8) then starts the user-level resource configuration which mounts file systems, sets up network cards to communicate on the network, and generally starts all the processes that usually are run on a DragonFly system at startup.
  37
  38 ----
  39
  40 ## The Boot Manager and Boot Stages
  41
  42 ### The Boot Manager
  43
  44 The code in the MBR or boot manager is sometimes referred to as ***stage zero*** of the boot process. This subsection discusses two of the boot managers previously mentioned:  **boot0**  and  **LILO** .
  45
  46  **The** boot0 ** Boot Manager:** The MBR installed by FreeBSD's installer or [boot0cfg(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=boot0cfg&section=8), by default, is based on `/boot/boot0`. (The  **boot0**  program is very simple, since the program in the MBR can only be 446 bytes long because of the slice table and `0x55AA` identifier at the end of the MBR.) If you have installed  **boot0**  and multiple operating systems on your hard disks, then you will see a display similar to this one at boot time:
  47
  48  **Example 7-1. `boot0` Screenshot**
  49
  50
  51
  52     F1 DOS
  53
  54     F2 FreeBSD
  55
  56     F3 Linux
  57
  58     F4 ??
  59
  60     F5 Drive 1
  61
  62
  63
  64     Default: F2
  65
  66 Other operating systems, in particular Windows®, have been known to overwrite an existing MBR with their own. If this happens to you, or you want to replace your existing MBR with the DragonFly MBR then use the following command:
  67
  68
  69
  70     # fdisk -B -b /boot/boot0 device
  71
  72 where `***device***` is the device that you boot from, such as `ad0` for the first IDE disk, `ad2` for the first IDE disk on a second IDE controller, `da0` for the first SCSI disk, and so on. Or, if you want a custom configuration of the MBR, use [boot0cfg(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=boot0cfg&section=8).
  73
  74  **The LILO Boot Manager:** To install this boot manager so it will also boot DragonFly, first start Linux and add the following to your existing `/etc/lilo.conf` configuration file:
  75
  76
  77
  78     other=/dev/hdXY
  79
  80     table=/dev/hdX
  81
  82     loader=/boot/chain.b
  83
  84     label=DragonFly
  85
  86 In the above, specify DragonFly's primary partition and drive using Linux specifiers, replacing `***X***` with the Linux drive letter and `***Y***` with the Linux primary partition number. If you are using a SCSI drive, you will need to change `***/dev/hd***` to read something similar to `***/dev/sd***`. The `loader=/boot/chain.b` line can be omitted if you have both operating systems on the same drive. Now run `/sbin/lilo -v` to commit your new changes to the system; this should be verified by checking its screen messages.
  87
  88 ### Stage One, /boot/boot1, and Stage Two, /boot/boot2
  89
  90 Conceptually the first and second stages are part of the same program, on the same area of the disk. Because of space constraints they have been split into two, but you would always install them together. They are copied from the combined file `/boot/boot` by the installer or  **disklabel**  (see below).
  91
  92 They are located outside file systems, in the first track of the boot slice, starting with the first sector. This is where [ boot0](boot-blocks.html#BOOT-BOOT0), or any other boot manager, expects to find a program to run which will continue the boot process. The number of sectors used is easily determined from the size of `/boot/boot`.
  93
  94 They are found on the boot sector of the boot slice, which is where [ boot0](boot-blocks.html#BOOT-BOOT0), or any other program on the MBR expects to find the program to run to continue the boot process. The files in the `/boot` directory are copies of the real files, which are stored outside of the DragonFly file system.
  95
  96 `boot1` is very simple, since it can only be 512 bytes in size, and knows just enough about the DragonFly ***disklabel***, which stores information about the slice, to find and execute `boot2`.
  97
  98 `boot2` is slightly more sophisticated, and understands the DragonFly file system enough to find files on it, and can provide a simple interface to choose the kernel or loader to run.
  99
 100 Since the [ loader](boot-blocks.html#BOOT-LOADER) is much more sophisticated, and provides a nice easy-to-use boot configuration, `boot2` usually runs it, but previously it was tasked to run the kernel directly.
 101
 102  **Example 7-2. boot2 Screenshot**
 103
 104
 105
 106     >> DragonFly/i386 BOOT
 107
 108     Default: 0:ad(0,a)/boot/loader
 109
 110     boot:
 111
 112 If you ever need to replace the installed `boot1` and `boot2` use [disklabel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=disklabel&section=8):
 113
 114
 115
 116     # disklabel -B diskslice
 117
 118 where `***diskslice***` is the disk and slice you boot from, such as `ad0s1` for the first slice on the first IDE disk.
 119
 120 ### Stage Three, `/boot/loader`
 121
 122 The loader is the final stage of the three-stage bootstrap, and is located on the file system, usually as `/boot/loader`.
 123
 124 The loader is intended as a user-friendly method for configuration, using an easy-to-use built-in command set, backed up by a more powerful interpreter, with a more complex command set.
 125
 126 #### Loader Program Flow
 127
 128 During initialization, the loader will probe for a console and for disks, and figure out what disk it is booting from. It will set variables accordingly, and an interpreter is started where user commands can be passed from a script or interactively.
 129
 130 The loader will then read `/boot/loader.rc`, which by default reads in `/boot/defaults/loader.conf` which sets reasonable defaults for variables and reads `/boot/loader.conf` for local changes to those variables. `loader.rc` then acts on these variables, loading whichever modules and kernel are selected.
 131
 132 Finally, by default, the loader issues a 10 second wait for key presses, and boots the kernel if it is not interrupted. If interrupted, the user is presented with a prompt which understands the easy-to-use command set, where the user may adjust variables, unload all modules, load modules, and then finally boot or reboot.
 133
 134 #### Loader Built-In Commands
 135
 136 These are the most commonly used loader commands. For a complete discussion of all available commands, please see [loader(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=loader&section=8).
 137
 138 * autoboot `***seconds***`: Proceeds to boot the kernel if not interrupted within the time span given, in seconds. It displays a countdown, and the default time span is 10 seconds.
 139
 140 * boot [`***-options***`] [`***kernelname***`]: Immediately proceeds to boot the kernel, with the given options, if any, and with the kernel name given, if it is.
 141
 142 *boot-conf: Goes through the same automatic configuration of modules based on variables as what happens at boot. This only makes sense if you use `unload` first, and change some variables, most commonly `kernel`.
 143
 144 * help [`***topic***`]: Shows help messages read from `/boot/loader.help`. If the topic given is `index`, then the list of available topics is given.
 145
 146 * include `***filename***` ...: Processes the file with the given filename. The file is read in, and interpreted line by line. An error immediately stops the include command.
 147
 148 * load [`-t` `***type***`] `***filename***`: Loads the kernel, kernel module, or file of the type given, with the filename given. Any arguments after filename are passed to the file.
 149
 150 * ls [`-l`] [`***path***`]: Displays a listing of files in the given path, or the root directory, if the path is not specified. If `-l` is specified, file sizes will be shown too.
 151
 152 * lsdev [`-v`]: Lists all of the devices from which it may be possible to load modules. If `-v` is specified, more details are printed.
 153
 154 * lsmod [`-v`]: Displays loaded modules. If `-v` is specified, more details are shown.
 155
 156 * more `***filename***`: Displays the files specified, with a pause at each `LINES` displayed.
 157
 158 * reboot: Immediately reboots the system.
 159
 160 * set `***variable***`, set `***variable***`=`***value***`: Sets the loader's environment variables.
 161
 162 * unload: Removes all loaded modules.
 163
 164 #### Loader Examples
 165
 166 Here are some practical examples of loader usage:
 167
 168 * To simply boot your usual kernel, but in single-user mode:
 169
 170
 171
 172           boot -s
 173
 174
 175
 176 * To unload your usual kernel and modules, and then load just your old (or another) kernel:
 177
 178
 179
 180           unload
 181
 182           load kernel.old
 183
 184
 185
 186   You can use `kernel.GENERIC` to refer to the generic kernel that comes on the install disk, or `kernel.old` to refer to your previously installed kernel (when you have upgraded or configured your own kernel, for example).
 187
 188    **Note:** Use the following to load your usual modules with another kernel:
 189
 190
 191
 192           unload
 193
 194           set kernel="kernel.old"
 195
 196           boot-conf
 197
 198
 199
 200 * To load a kernel configuration script (an automated script which does the things you would normally do in the kernel boot-time configurator):
 201
 202
 203
 204          load -t userconfig_script /boot/kernel.conf
 205
 206
 207
 208 ----
 209
 210 ## Kernel Interaction During Boot
 211
 212 Once the kernel is loaded by either [ loader](boot-blocks.html#BOOT-LOADER) (as usual) or [ boot2](boot-blocks.html#BOOT-BOOT1) (bypassing the loader), it examines its boot flags, if any, and adjusts its behavior as necessary.
 213
 214 ### Kernel Boot Flags
 215
 216 Here are the more common boot flags:
 217
 218 `-a`:: during kernel initialization, ask for the device to mount as the root file system.`-C`:: boot from CDROM.`-c`:: run UserConfig, the boot-time kernel configurator`-s`:: boot into single-user mode`-v`:: be more verbose during kernel startup
 219
 220  **Note:** There are other boot flags; read [boot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=boot&section=8) for more information on them.
 221
 222 ## Init: Process Control Initialization
 223
 224 Once the kernel has finished booting, it passes control to the user process [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8), which is located at `/sbin/init`, or the program path specified in the `init_path` variable in `loader`.
 225
 226 ### Automatic Reboot Sequence
 227
 228 The automatic reboot sequence makes sure that the file systems available on the system are consistent. If they are not, and [fsck(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=fsck&section=8) cannot fix the inconsistencies, [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8) drops the system into [single-user mode](boot-init.html#BOOT-SINGLEUSER) for the system administrator to take care of the problems directly.
 229
 230 ### Single-User Mode
 231
 232 This mode can be reached through the [automatic reboot sequence](boot-init.html#BOOT-AUTOREBOOT), or by the user booting with the `-s` option or setting the `boot_single` variable in `loader`.
 233
 234 It can also be reached by calling [shutdown(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=shutdown&section=8) without the reboot (`-r`) or halt (`-h`) options, from [multi-user mode](boot-init.html#BOOT-MULTIUSER).
 235
 236 If the system `console` is set to `insecure` in `/etc/ttys`, then the system prompts for the `root` password before initiating single-user mode.
 237
 238 ***'Example 7-3. An Insecure Console in `/etc/ttys`***'
 239
 240
 241
 242     # name  getty                           type    status          comments
 243
 244     #
 245
 246     # If console is marked "insecure", then init will ask for the root password
 247
 248     # when going to single-user mode.
 249
 250     console none                            unknown off insecure
 251
 252  **Note:** An `insecure` console means that you consider your physical security to the console to be insecure, and want to make sure only someone who knows the `root` password may use single-user mode, and it does not mean that you want to run your console insecurely. Thus, if you want security, choose `insecure`, not `secure`.
 253
 254 ### Multi-User Mode
 255
 256 If [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8) finds your file systems to be in order, or once the user has finished in [single-user mode](boot-init.html#BOOT-SINGLEUSER), the system enters multi-user mode, in which it starts the resource configuration of the system.
 257
 258 #### Resource Configuration (rc)
 259
 260 The resource configuration system reads in configuration defaults from `/etc/defaults/rc.conf`, and system-specific details from `/etc/rc.conf`, and then proceeds to mount the system file systems mentioned in `/etc/fstab`, start up networking services, start up miscellaneous system daemons, and finally runs the startup scripts of locally installed packages.
 261
 262 The [rc(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=rc&section=8) manual page is a good reference to the resource configuration system, as is examining the scripts themselves.
 263
 264 ## Shutdown Sequence
 265
 266 Upon controlled shutdown, via [shutdown(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=shutdown&section=8), [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=init&section=8) will attempt to run the script `/etc/rc.shutdown`, and then proceed to send all processes the `TERM` signal, and subsequently the `KILL` signal to any that do not terminate timely.
 267
 268 To power down a DragonFly machine on architectures and systems that support power management, simply use the command `shutdown -p now` to turn the power off immediately. To just reboot a DragonFly system, just use `shutdown -r now`. You need to be `root` or a member of `operator` group to run [shutdown(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=shutdown&section=8). The [halt(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=halt&section=8) and [reboot(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=reboot&section=8) commands can also be used, please refer to their manual pages and to [shutdown(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=shutdown&section=8)'s one for more information.
 269
 270  **Note:** Power management requires [acpi(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=acpi&section=4) support in the kernel or loaded as a module, or [apm(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=apm&section=4) support.
 271
 272 <!-- this section needs the info about sernos and vfs.mountrootfrom or whatever it's called -->
 273