1 BOOT(8) BSD System Manager's Manual (i386) BOOT(8)
4 boot, boot.cfg, ldbsd.com, pxeboot - i386 second-stage boot loader
7 The boot system programme, often called ldbsd.com, aims to load the sys-
8 tem kernel into core memory from disc or network and run it, as well as
9 do some auxiliary functions, while dealing with the problems arising from
10 the history of the i386 architecture since 1978, incompatibilities, ex-
11 tensions, bugs, El Torito booting, Intel's Preboot Execution Environment
12 (PXE) for network boot, the Multiboot Specification, etc. MirOS floppies
13 use a specially limited version optimised for size, lacking support for
14 any filesystem other than 4.2FFS and most commands.
16 It can be loaded either directly from the BIOS (most commonly via PXE;
17 earlier versions could also be loaded using El Torito), the bootxx first
18 stage boot loader (from floppy, hard disc, compact flash card, USB stick,
19 and the likes; recently, since bootxx itself was made El Torito capable,
20 this has become the desired method for El Torito boot), any bootloader
21 compliant with the Multiboot specification (as boot is a Multiboot com-
22 pliant OS Kernel image), or after renaming to ldbsd.com by any bootloader
23 implementing the COMBOOT API (specified by SYSLINUX, EXTLINUX, ISOLINUX,
24 PXELINUX) or MS-DOS(R) (unless DOS occupies the HMA). Once loaded, it can
25 be used, in a more or less limited fashion, to boot a MirOS kernel from a
26 supported filesystem (4.2FFS, ISO 9660, FAT12, FAT16, FAT28, TFTP, NFS,
27 and a pseudo filesystem called lmbmfs), inspect the filesystems, get or
28 set machine information, or load other bootloaders (see below for de-
29 tails). It can inflate gzip(1) compressed files (with LZMA compression
30 planned), set up serial console, and provides an interactive prompt.
32 Basic operation procedure is as follows:
36 BIOS We are loaded to 0x07C00. The drive used to load us from
37 is passed in the DL register. The ES:BX and DS:SI regis-
38 ters and the stack contain additional data. While we do
39 not care about the actual address, we expect to be whole.
41 bootxx We are loaded at the final address. The drive used to
42 load us from is passed in a special memory location. The
43 DS:SI registers are set up if we were loaded from a HDD
44 partition. The Master Boot Record (/usr/mdec/mbrldr or
45 /usr/mdec/mbrmgr) takes care to set these up correctly.
47 PXE The NIC's PXE boot ROM initialises the NIC, network
48 driver, UNDI and PXE interfaces, contacts a DHCP server
49 by broadcasting an IPv4 request on the network, gets an
50 IP address and the name of a file to load from the DHCP
51 server, and downloads the file indicated via TFTP to
52 0x07C00. That would be boot. Control is then passed to
53 address 0x07C00 with ES:BX and the stack set up.
55 PXE booting is useful for diskless(8) clients or initial
56 download and execution of the installation kernel,
57 bsd.rd, or for rescue system purposes.
59 DOS We are loaded to xxxx:0100h with no drive or PXE informa-
60 tion set up. The interrupt vectors are hooked by DOS, so
61 if we overwrite any memory in use by DOS, we lose. That
62 would be the case if xxxx is larger than our final ad-
63 dress, any hooks point to an address between our final
64 address and 9000:0000h, the HMA is in use (because that's
65 where the kernel is loaded to), or somesuch. This also
66 implies we cannot chain any other bootloader. Further-
67 more, we require the machine to be in Real Mode, not in
68 VM86 mode, so EMM386.SYS, Win32 or similar must not be
69 active. We ask DOS for the current drive to use this in-
72 COMBOOT We are loaded in a similar way as from DOS, except the
73 machine state is not changed as much from the initial
74 state. After determining that we are in fact loaded via
75 COMBOOT and not DOS, we ask SYSLINUX to terminate after
76 gathering information about the boot drive, partition, or
77 PXE; the UNDI and PXE stacks are kept active if any.
79 Multiboot We request to be loaded to 0x00100000 (the HMA) due to
80 GNU GRUB's limitations, save the boot device off the MBI
81 structure, copy ourselves to the final location, and
82 switch back to Real Mode. Modules passed to us by the
83 Multiboot compliant boot loader will be moved off to just
84 above 20 MiB in memory; their dirnames as well as any
85 command lines (to the Multiboot OS kernel, i.e. this
86 bootloader, as well as to the Multiboot modules) are dis-
87 carded. The modules are made available as regular files
88 using the virtual lmbm (Loadable Multiboot Modules) dev-
89 ice and filesystem (in-RAM file store, really).
91 During the initial operation, the stack is located about 80 KiB
92 behind the start of our own memory area, and switched to the final
93 location if the position in memory is known to be correct early.
95 2. System information (boot drive, potential partition table entry,
96 PXENV+ and !PXE structure pointers, multiboot module information)
97 are stored in safe locations.
99 3. The code is relocated to the final address once or twice if needed.
100 The final address is 4000:0000h with the stack beginning at
101 3000:FFFCh. The stack is shared between Real Mode and 32-bit Virtual
102 Protected Address Mode. The code is mostly organised using the small
103 memory model, with everything within 64 KiB (although the real limit
104 is more than 256 bytes less than that due to initial loading is-
105 sues), except some rather large uninitialised areas and the disc I/O
106 bounce buffer, which begin at 3000:0000 and grow upwards. The heap
107 begins after the bss section and grows up to just short of
110 4. If the bootloader is compiled to do so, for example on a Live CD, it
111 displays a boot menu unless the shift key is pressed, and retains
112 the numeric return value for later, to replace the cfg suffix of the
113 configuration file with it.
115 5. The system is switched to Protected Mode.
117 6. The hardware is probed:
119 + o Console devices: the default BIOS console (INT 10h, which may be
120 a MDA/MGA/Hercules, CGA/EGA or VGA CRT/LCD, plus DIN or PS/2 or
121 emulated keyboard) as well as up to four serial ports (via the
123 + o Memory: ask the BIOS and probe page by page through the address
124 space, in case the BIOS reports wrong information.
127 + o Loadable Multiboot Modules (if any, they are moved off to safe
128 locations and the virtual lmbm device and lmbmfs are set up)
129 + o Floppy disc drives
130 + o Hard disc drives, including El Torito CD-ROM drives
132 7. Unless a control key is held, the files /x.x.x.x/boot.cfg if loaded
133 via PXE (where x.x.x.x is our own IPv4 address) and /boot.cfg, with
134 "cfg" possibly replaced from the Live CD menu, are read and executed
135 as if the commands had been entered on the loader prompt.
137 8. The bootloader prompt
141 is issued, and a command line is read. If no key is pressed within
142 five seconds, the kernels /bsd and /bsd.old are tried, in order, to
143 be booted with the current parameters; if unsuccessful or any key is
144 pressed, the timeout is disabled (it can be manipulated from the
145 configuration file or command line). The system will be unable to
146 boot if no suitable kernel image is found.
148 Commands from the configuration file and the loader prompt are read line
149 by line and executed as read. Empty lines and lines beginning with the
150 comment character, '#', are ignored when reading from the configuration
151 file. Just entering an empty line at the loader prompt, however, will do
152 the default action of booting a kernel with the current parameters. To
153 pass multiple commands on a line, use the U+0060 character, '`', as del-
154 imiter. To pass multiple commands into a macro definition, use the tilde,
155 '~', as delimiter. Leading and trailing whitespace is ignored.
158 The following commands are accepted at the loader prompt:
161 Boots the kernel image specified by image with any options given.
162 If the image file specification, or one of its device or filename
163 parts (see below) is omitted, values from variables will be used.
165 -a Causes the kernel to ask for the root filesystem to use.
167 -c Causes the kernel to go into UKC(8) before performing
170 -d Causes the kernel to drop into ddb(4) at the earliest con-
173 -s Attempts to boot into single-user mode.
176 Displays the file onto the console. Output is paginated every 24
179 echo Displays the arguments onto the console.
181 env On i386, this command is not used.
183 help Prints a list of available commands.
186 Prints the content of the specified directory in long format.
187 Output is paginated every 24 lines.
189 The cd9660, tftp and nfs filesystems do not support this command.
190 They will either always fail or always succeed with sane but
191 unusable results. The FAT12, FAT16 and FAT28 filesystems have
192 hardcoded perms and uid/gid.
195 Issues machine-specific commands:
197 boot dev Load a bootsector (MBR or PBR) from the indicated dev-
198 ice and boot it. Possible devices are fd0 (floppy
199 boot), hd0 (MBR), hd0a, hd0b, hd0c, hd0d (PBR), and
200 some more useless combinations.
202 diskinfo Display a list of probed floppy and hard disc drives
203 including BIOS and geometry information.
206 Load a bootsector or other bootloader from an image
207 file and execute it. Currently known values for type:
209 grub GNU GRUB 0.9x stage2 file
210 GNU GRUB 0.9x stage2_eltorito file
211 GNU GRUB2 core.img file
213 sector Boot sector or image, loaded to 0000:7C00h
214 MirOS boot second-stage loader
217 Displays the idea boot has about the disklabel of the
218 currently active or the specified device.
221 If used without any arguments, print the current idea
222 boot has about the memory configuration taken from BIOS
223 or probed. Arguments having the form of
227 add (+) or exempt (-) the specified amount of memory.
228 Both size and base address can be specified in decimal,
229 octal or hexadecimal, using standard C prefixes.
231 Memory segments are not required to be adjacent to each
232 other; the only requirement is that there is real phy-
233 sical memory under the range added. The following exam-
234 ple adds 32 MiB of memory right after the first 16 MiB:
236 boot> machine mem +0x2000000@0x01000000
238 Another useful command is to withdraw a range of memory
239 from OS usage, which may have been wrongfully reported
240 as useful by the BIOS. This example excludes the 1516
241 MiB range from the map of useful memory:
243 boot> machine mem -0x100000@0x00F00000
245 regs Debugging command displaying register dumps.
247 oldbios Enable or disable the so-called "Old BIOS / Soekris
248 helper", which restricts boot from loading more than
249 one sector at a time from disc.
251 macro Displays the names of all currently defined macros. Up to four
252 can be defined, holding up to 256 characters.
255 Deletes the macro name, or defines it to cmd.
257 reboot Initiates a warm machine reboot.
260 If invoked without arguments, prints a list of variables and
261 their values. If only a name is given, the value of that variable
262 is displayed. Otherwise, the variable is set to the new value.
263 The following variables are defined:
265 addr Address at which to load the kernel
269 device Boot device name (see below)
271 doboot "0" disables automatic boot on entering an empty line
273 howto Options passed to the loaded kernel, see boot
275 image File name containing the kernel image
277 timeout Number of seconds to wait for human intervention before
280 tty Name of the active console device, for example:
285 stty [device [speed]]
286 Displays or sets the speed for a console device. If the baudrate
287 for the currently active console device is changed, boot offers
288 you five seconds of grace period to switch your terminal to
289 match. If the baudrate for an inactive device is changed, it will
290 only become active on the next switch to a serial console device;
291 it is not used on the PC CRT console.
293 The default baudrate is 9600 bps. boot uses eight data bits, no
294 parity, one stop bit.
296 time Displays the system date and time.
299 An image specification consists of two parts, the device name and a path-
300 name, separated by a colon (':'). In most circumstances, both can be om-
301 itted, and pathnames do not need to begin with a leading slash even if
302 they are absolute. Note that, for some filesystems, you are limited to an
303 8.3 character naming scheme with case insensitive (mapped to lowercase)
304 filenames. Other filesystems may not provide directory listing informa-
305 tion or the ability to stat files (especially remote filesystems).
307 Examples of valid image specifications are:
311 + o hd0a:/ (for "ls")
312 + o lmbm:/ (for "ls")
313 + o cd0a:/boot/grub/stage2
314 + o tftp:/bsd.rd.i386
318 Disklabels are read from hard discs (BIOS drive >= 80h) by searching for
319 a primary MirOS partition first. The default partition type, 0x27, can be
320 changed at installboot(8) time, where it is hardcoded into the partition
321 boot record. If no suitable MBR partition was found or we're on a floppy,
322 the disklabel is searched at the beginning of the drive instead. The la-
323 bel offset for the i386 architecture is one 512-byte sector. On MirOS
324 DuaLive CDs, it may be embedded in the first-stage sparc bootloader. If
325 no disklabel can be read from the disc, one is faked. The device size
326 ('c' slice) defaults to the size of an 1440 KiB floppy disc, but if any
327 MBR primary partitions are found which span more space, their values are
328 used instead. The 'd', 'e', 'f' and 'g' slices are filled with the four
329 MBR primary partitions, if any. The 'a' slice is filled, in this order,
330 with: the partition passed via DS:SI if plausible, the first non-empty
331 MBR partition ('d'-'g' slices), the whole disc ('c' slice).
334 /usr/mdec/bootxx first stage bootloader (PBR)
335 /usr/mdec/boot second stage bootloader
336 /usr/mdec/mbrldr hard disc MBR, simple version
337 /usr/mdec/mbrmgr MBR, bootmanager version
338 /boot usual location of installed loader
339 ldbsd.com alternative name for boot
340 /boot.cfg boot configuration file
341 /bsd standard kernel image
342 /bsd.rd kernel image for installation/recovery
343 /bsd.old alternative kernel image
344 /etc/dhcpd.conf dhcpd(8) configuration file
345 /tftpboot/boot standard location of boot for netboot
346 /tftpboot/boot.cfg common/shared boot configuration file on the TFTP
347 server; /tftpboot/10.11.12.13/boot.cfg contains
348 peer-specific configuration to be used instead
349 /tftpboot/bsd kernel image
350 /tftpboot/pxeboot deprecated, no longer in use
353 A sample configuration file for dhcpd(8) is already contained with MirOS
354 and might look as follows:
356 shared-network KICKSTART {
357 subnet 172.23.42.0 netmask 255.255.255.0 {
358 option routers 172.23.42.1;
360 range 172.23.42.10 172.23.42.199;
364 Boot the default kernel:
368 Remove the 5 second pause at boot-time permanently, causing boot to load
369 the kernel immediately without prompting:
371 # echo "boot" >/boot.cfg
373 Remove the 5 second pause at boot-time permanently, causing boot to do
374 nothing automatically:
376 # echo "set timeout 0" >/boot.cfg
378 Use serial console. A null modem cable should connect the specified seri-
379 al port to a terminal. Useful for debugging.
383 Invoke the serial console at every boot:
385 # echo "set tty com0" >/boot.cfg
387 Multiple commands on one line are useful for machines whose serial con-
388 sole is unusable from within the boot loader, but the only way to talk to
389 the kernel, e.g. for installation on a Soekris/WRAP:
391 boot> stty com0 38400 ` set tty com0 ` boot /bsd.rd
393 Boot the kernel named /bsd from the second hard disc in "User Kernel
394 Configuration" mode (see boot_config(8)). This mechanism allows for the
395 explicit enabling and disabling of devices during the current boot se-
396 quence, as well as the modification of device parameters. Once booted,
397 such changes can be made permanent by using config(8)'s -e option.
399 boot> boot hd1a:/bsd -c
402 gzip(1), compress(3), autoconf(4), ddb(4), dhcpd.conf(5), boot_config(8),
403 boot_i386(8), dhcpd(8), diskless(8), fdisk(8), httpd(8), inetd(8),
404 installboot(8), reboot(8), tftpd(8)
406 Intel Corporation, Preboot Execution Environment (PXE) Specification,
407 Version 2.1, September 20, 1999.
409 Free Software Foundation, Inc., Multiboot Specification, Version 0.6.93.
412 This bootloader is based on code written by Michael Shalayeff for
413 OpenBSD 2.1. The separate pxeboot command first appeared in OpenBSD 3.5,
414 based upon work from NetBSD. In OpenBSD and MirOS #7 and below, the
415 boot.cfg file was called boot.conf, it has been renamed for ISO 9660 and
416 FAT compatibility. A version called cdboot appeared in MirOS #8 and went
417 away for MirOS #10. The separate versions got merged into one bootloader,
418 DOS, COMBOOT, Multiboot support (including modules), pagination, macros,
419 the machine exec and cat commands, working chainbooting of bootsectors
420 and GNU GRUB, faked disklabels (if none exist on disc), FAT filesystem
421 support, and many more things were added or rewritten for MirOS #11 and
422 MirOS bsd4grml by Thorsten Glaser.
425 The default location of the kernels and the boot.cfg file can be changed
428 FILESYSTEM SPECIFIC NOTES
430 ISO 9660 Filesystems above 4 GiB in size definitively do not work. We
431 do not know at this time if there is a 2 GiB or 4 GiB limit,
432 nor if this affects any other filesystems.
434 The ls command does not work.
436 lmbmfs This filesystem and device will only appear if loaded via a
437 Multiboot compliant boot loader, masquerading as Multiboot
438 compliant OS kernel, and when modules are passed. ls is possi-
439 ble only on the root directory ("/", "/."). Files keep the
440 names passed by the Multiboot boot loader, but have the direc-
441 tory part stripped, and can be accessed with any directory
442 leading. If they have no names, they are given an enumerated
445 tftp, nfs These filesystems and devices will only appear of loaded via
446 PXE. They obviously do not support ls.
448 ustarfs This filesystem will be implemented soon.
450 MirOS BSD #10-current August 9, 2009 6