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:
34 1. Be loaded. However this is done, as the first thing we write a RETF
35 instruction to 0000:0000 and CALL FAR it (from 16-bit code), or
36 write a RET instruction to 0x00000000 and CALL it (from 32-bit
37 code), backing up the previous content of course, so that qemu+gdb
38 users can intercept via "b *0".
40 BIOS We are loaded to 0x07C00. The drive used to load us from
41 is passed in the DL register. The ES:BX and DS:SI regis-
42 ters and the stack contain additional data. While we do
43 not care about the actual address, we expect to be whole.
45 bootxx We are loaded at the final address. The drive used to
46 load us from is passed in a special memory location. The
47 DS:SI registers are set up if we were loaded from a HDD
48 partition. The Master Boot Record (/usr/mdec/mbrldr or
49 /usr/mdec/mbrmgr) takes care to set these up correctly.
51 PXE The NIC's PXE boot ROM initialises the NIC, network
52 driver, UNDI and PXE interfaces, contacts a DHCP server
53 by broadcasting an IPv4 request on the network, gets an
54 IP address and the name of a file to load from the DHCP
55 server, and downloads the file indicated via TFTP to
56 0x07C00. That would be boot. Control is then passed to
57 address 0x07C00 with ES:BX and the stack set up.
59 PXE booting is useful for diskless(8) clients or initial
60 download and execution of the installation kernel,
61 bsd.rd, or for rescue system purposes.
63 DOS We are loaded to xxxx:0100h with no drive or PXE informa-
64 tion set up. The interrupt vectors are hooked by DOS, so
65 if we overwrite any memory in use by DOS, we lose. That
66 would be the case if xxxx is larger than our final ad-
67 dress, any hooks point to an address between our final
68 address and 9000:0000h, the HMA is in use (because that's
69 where the kernel is loaded to), or somesuch. This also
70 implies we cannot chain any other bootloader. Further-
71 more, we require the machine to be in Real Mode, not in
72 VM86 mode, so EMM386.SYS, Win32 or similar must not be
73 active. We ask DOS for the current drive to use this in-
74 formation later. DOS has set up a PSP (Program Segment
75 Prefix) for us, which may contain a command line which we
76 store away for later perusal if it is not empty.
78 COMBOOT We are loaded in a similar way as from DOS, except the
79 machine state is not changed as much from the initial
80 state. After determining that we are in fact loaded via
81 COMBOOT and not DOS, we ask SYSLINUX to terminate after
82 gathering information about the boot drive, partition, or
83 PXE; the UNDI and PXE stacks are kept active if any. The
84 COMBOOT API has set up a PSP like DOS as well, which we
87 Multiboot We request to be loaded to 0x00100000 (the HMA) due to
88 GNU GRUB's limitations, save the boot device off the MBI
89 structure, copy ourselves to the final location, and
90 switch back to Real Mode. Modules passed to us by the
91 Multiboot compliant boot loader will be moved off to just
92 above 20 MiB in memory; their dirnames as well as any
93 command lines to the Multiboot modules are discarded. If
94 a command line is passed to the Multiboot OS kernel, i.e.
95 this bootloader, the pathname of the loader is skipped;
96 it is then cut off after a certain size limit (currently,
97 256 bytes) and stored away for later use. The modules are
98 made available as regular files using the virtual lmbm
99 (Loadable Multiboot Modules) device and filesystem (in-
100 RAM file store, really).
102 During the initial operation, the stack is located about 80 KiB
103 behind the start of our own memory area, and switched to the final
104 location if the position in memory is known to be correct early.
106 2. System information (boot drive, potential partition table entry,
107 PXENV+ and !PXE structure pointers, multiboot module information)
108 are stored in safe locations.
110 3. The code is relocated to the final address once or twice if needed.
111 The final address is 4000:0000h with the stack beginning at
112 3000:FF7Ch. The 128 bytes in between, from 3000:FF80h onwards, con-
113 tains a potentially stored away PSP command line, before it is moved
114 to the buffer after the bss and ssbss sections have been initialised
115 (zeroed out). The stack is shared between Real Mode and 32-bit Vir-
116 tual Protected Address Mode. The code is mostly organised using the
117 small memory model, with everything within 64 KiB (although the real
118 limit is more than 256 bytes less than that due to initial loading
119 issues), except some rather large uninitialised areas and the disc
120 I/O bounce buffer, which begin at 3000:0000 and grow upwards, nick-
121 named the ssbss section. The heap begins after the bss section and
122 grows up to just short of 9000:0000h.
124 4. If the bootloader is compiled to do so, for example on a Live CD, it
125 displays a boot menu unless the shift key is pressed, and retains
126 the numeric return value for later, to replace the cfg suffix of the
127 configuration file with it, unless a (non-empty) command line is
130 5. The system is switched to Protected Mode.
132 6. If a command line was passed, it is moved from its original (Multi-
133 boot, above 1 MiB or way below in the real mode area) or temporary
134 (0x3FF80) location to cmd_buf.
136 7. The hardware is probed:
138 + o Console devices: the default BIOS console (INT 10h, which may be
139 a MDA/MGA/Hercules, CGA/EGA or VGA CRT/LCD, plus DIN or PS/2 or
140 emulated keyboard) as well as up to four serial ports (via the
142 + o Memory: ask the BIOS and probe page by page through the address
143 space, in case the BIOS reports wrong information.
146 + o Loadable Multiboot Modules (if any, they are moved off to safe
147 locations and the virtual lmbm device and lmbmfs are set up)
148 + o Floppy disc drives
149 + o Hard disc drives, including El Torito CD-ROM drives
151 8. If a command line was passed, it is executed. If it contained a boot
152 command, the kernel is attempted to be loaded; otherwise, or if it
153 fails, execution flow continues at the command prompt (see below)
154 with no timeout or auto-boot enabled.
156 9. Unless a control key is held or a command line was passed, the files
157 /x.x.x.x/boot.cfg if loaded via PXE (where x.x.x.x is our own IPv4
158 address) and /boot.cfg, with "cfg" possibly replaced from the Live
159 CD menu, are read and executed as if the commands had been entered
160 on the loader prompt.
162 10. The bootloader prompt
166 is issued, and a command line is read. If no key is pressed within
167 five seconds, the kernels /bsd and /bsd.old are tried, in order, to
168 be booted with the current parameters; if unsuccessful or any key is
169 pressed, the timeout is disabled (it can be manipulated from the
170 configuration file or command line). The system will be unable to
171 boot if no suitable kernel image is found.
173 Commands from the configuration file and the loader prompt are read line
174 by line and executed as read. Empty lines and lines beginning with the
175 comment character, '#', are ignored when reading from the configuration
176 file. Just entering an empty line at the loader prompt, however, will do
177 the default action of booting a kernel with the current parameters. To
178 pass multiple commands on a line, use the U+0060 character, '`', as del-
179 imiter. To pass multiple commands into a macro definition, use the tilde,
180 '~', as delimiter. Leading and trailing whitespace is ignored.
183 The following commands are accepted at the loader prompt:
186 Boots the kernel image specified by image with any options given.
187 If the image file specification, or one of its device or filename
188 parts (see below) is omitted, values from variables will be used.
190 -a Causes the kernel to ask for the root filesystem to use.
192 -c Causes the kernel to go into UKC(8) before performing
195 -d Causes the kernel to drop into ddb(4) at the earliest con-
198 -s Attempts to boot into single-user mode.
201 Displays the file onto the console. Output is paginated every 24
204 echo Displays the arguments onto the console.
206 env On i386, this command is not used.
208 help Prints a list of available commands.
211 Prints the content of the specified directory in long format.
212 Output is paginated every 24 lines.
214 The cd9660, tftp and nfs filesystems do not support this command.
215 They will either always fail or always succeed with sane but
216 unusable results. The FAT12, FAT16 and FAT28 filesystems have
217 hardcoded perms and uid/gid.
220 Issues machine-specific commands:
222 boot dev Load a bootsector (MBR or PBR) from the indicated dev-
223 ice and boot it. Possible devices are fd0 (floppy
224 boot), hd0 (MBR), hd0a, hd0b, hd0c, hd0d (PBR), and
225 some more useless combinations.
227 diskinfo Display a list of probed floppy and hard disc drives
228 including BIOS and geometry information.
230 exec dos Execute INT 21h, AH=4Ch, to return to DOS or SYSLINUX,
231 if possible. This will not always work and may hang
235 Load a bootsector or other bootloader from an image
236 file and execute it. Currently known values for type:
238 grub GNU GRUB 0.9x stage2 file
239 GNU GRUB 0.9x stage2_eltorito file
240 GNU GRUB2 core.img file
242 sector Boot sector or image, loaded to 0000:7C00h
243 MirOS boot second-stage loader
246 Displays the idea boot has about the disklabel of the
247 currently active or the specified device.
250 If used without any arguments, print the current idea
251 boot has about the memory configuration taken from BIOS
252 or probed. Arguments having the form of
256 add (+) or exempt (-) the specified amount of memory.
257 Both size and base address can be specified in decimal,
258 octal or hexadecimal, using standard C prefixes.
260 Memory segments are not required to be adjacent to each
261 other; the only requirement is that there is real phy-
262 sical memory under the range added. The following exam-
263 ple adds 32 MiB of memory right after the first 16 MiB:
265 boot> machine mem +0x2000000@0x01000000
267 Another useful command is to withdraw a range of memory
268 from OS usage, which may have been wrongfully reported
269 as useful by the BIOS. This example excludes the 1516
270 MiB range from the map of useful memory:
272 boot> machine mem -0x100000@0x00F00000
274 oldbios Enable or disable the so-called "Old BIOS / Soekris
275 helper", which restricts boot from loading more than
276 one sector at a time from disc.
278 pxe Forcibly scan for a PXE boot ROM.
280 regs Debugging command displaying register dumps.
282 macro Displays the names of all currently defined macros. Up to four
283 can be defined, holding up to 256 characters.
286 Deletes the macro name, or defines it to cmd.
288 reboot Initiates a warm machine reboot.
291 If invoked without arguments, prints a list of variables and
292 their values. If only a name is given, the value of that variable
293 is displayed. Otherwise, the variable is set to the new value.
294 The following variables are defined:
296 addr Address at which to load the kernel
300 device Boot device name (see below)
302 doboot "0" disables automatic boot on entering an empty line
304 howto Options passed to the loaded kernel, see boot
306 image File name containing the kernel image
308 timeout Number of seconds to wait for human intervention before
311 tty Name of the active console device, for example:
316 stty [device [speed]]
317 Displays or sets the speed for a console device. If the baudrate
318 for the currently active console device is changed, boot offers
319 you five seconds of grace period to switch your terminal to
320 match. If the baudrate for an inactive device is changed, it will
321 only become active on the next switch to a serial console device;
322 it is not used on the PC CRT console.
324 The default baudrate is 9600 bps. boot uses eight data bits, no
325 parity, one stop bit.
327 time Displays the system date and time.
330 An image specification consists of two parts, the device name and a path-
331 name, separated by a colon (':'). In most circumstances, both can be om-
332 itted, and pathnames do not need to begin with a leading slash even if
333 they are absolute. Note that, for some filesystems, you are limited to an
334 8.3 character naming scheme with case insensitive (mapped to lowercase)
335 filenames. Other filesystems may not provide directory listing informa-
336 tion or the ability to stat files (especially remote filesystems).
338 Examples of valid image specifications are:
342 + o hd0a:/ (for "ls")
343 + o lmbm:/ (for "ls")
344 + o cd0a:/boot/grub/stage2
345 + o tftp:/bsd.rd.i386
349 Disklabels are read from hard discs (BIOS drive >= 80h) by searching for
350 a primary MirOS partition first. The default partition type, 0x27, can be
351 changed at installboot(8) time, where it is hardcoded into the partition
352 boot record. If no suitable MBR partition was found or we're on a floppy,
353 the disklabel is searched at the beginning of the drive instead. The la-
354 bel offset for the i386 architecture is one 512-byte sector. On MirOS
355 DuaLive CDs, it may be embedded in the first-stage sparc bootloader. If
356 no disklabel can be read from the disc, one is faked. The device size
357 ('c' slice) defaults to the size of an 1440 KiB floppy disc, but if any
358 MBR primary partitions are found which span more space, their values are
359 used instead. The 'd', 'e', 'f' and 'g' slices are filled with the four
360 MBR primary partitions, if any. The 'a' slice is filled, in this order,
361 with: the partition passed via DS:SI if plausible, the first non-empty
362 MBR partition ('d'-'g' slices), the whole disc ('c' slice).
365 /usr/mdec/bootxx first stage bootloader (PBR)
366 /usr/mdec/boot second stage bootloader
367 /usr/mdec/mbrldr hard disc MBR, simple version
368 /usr/mdec/mbrmgr MBR, bootmanager version
369 /boot usual location of installed loader
370 ldbsd.com alternative name for boot
371 /boot.cfg boot configuration file
372 /bsd standard kernel image
373 /bsd.rd kernel image for installation/recovery
374 /bsd.old alternative kernel image
375 /etc/dhcpd.conf dhcpd(8) configuration file
376 /tftpboot/boot standard location of boot for netboot
377 /tftpboot/boot.cfg common/shared boot configuration file on the TFTP
378 server; /tftpboot/10.11.12.13/boot.cfg contains
379 peer-specific configuration to be used instead
380 /tftpboot/bsd kernel image
381 /tftpboot/pxeboot deprecated, no longer in use
384 A sample configuration file for dhcpd(8) is already contained with MirOS
385 and might look as follows:
387 shared-network KICKSTART {
388 subnet 172.23.42.0 netmask 255.255.255.0 {
389 option routers 172.23.42.1;
391 range 172.23.42.10 172.23.42.199;
395 Boot the default kernel:
399 Remove the 5 second pause at boot-time permanently, causing boot to load
400 the kernel immediately without prompting:
402 # echo "boot" >/boot.cfg
404 Remove the 5 second pause at boot-time permanently, causing boot to do
405 nothing automatically:
407 # echo "set timeout 0" >/boot.cfg
409 Use serial console. A null modem cable should connect the specified seri-
410 al port to a terminal. Useful for debugging.
414 Invoke the serial console at every boot:
416 # echo "set tty com0" >/boot.cfg
418 Multiple commands on one line are useful for machines whose serial con-
419 sole is unusable from within the boot loader, but the only way to talk to
420 the kernel, e.g. for installation on a Soekris/WRAP:
422 boot> stty com0 38400 ` set tty com0 ` boot /bsd.rd
424 Boot the kernel named /bsd from the second hard disc in "User Kernel
425 Configuration" mode (see boot_config(8)). This mechanism allows for the
426 explicit enabling and disabling of devices during the current boot se-
427 quence, as well as the modification of device parameters. Once booted,
428 such changes can be made permanent by using config(8)'s -e option.
430 boot> boot hd1a:/bsd -c
433 gzip(1), compress(3), autoconf(4), ddb(4), dhcpd.conf(5), boot_config(8),
434 boot_i386(8), dhcpd(8), diskless(8), fdisk(8), httpd(8), inetd(8),
435 installboot(8), reboot(8), tftpd(8)
437 Intel Corporation, Preboot Execution Environment (PXE) Specification,
438 Version 2.1, September 20, 1999.
440 Free Software Foundation, Inc., Multiboot Specification, Version 0.6.93.
443 This bootloader is based on code written by Michael Shalayeff for
444 OpenBSD 2.1. The separate pxeboot command first appeared in OpenBSD 3.5,
445 based upon work from NetBSD. In OpenBSD and MirOS #7 and below, the
446 boot.cfg file was called boot.conf, it has been renamed for ISO 9660 and
447 FAT compatibility. A version called cdboot appeared in MirOS #8 and went
448 away for MirOS #10. The separate versions got merged into one bootloader,
449 DOS, COMBOOT, Multiboot support (including modules), pagination, macros,
450 the machine exec and cat commands, working chainbooting of bootsectors
451 and GNU GRUB, faked disklabels (if none exist on disc), FAT filesystem
452 support, and many more things were added or rewritten for MirOS #11 and
453 MirOS bsd4grml by Thorsten Glaser.
456 The default location of the kernels and the boot.cfg file can be changed
459 FILESYSTEM SPECIFIC NOTES
461 ISO 9660 Filesystems above 4 GiB in size definitively do not work. We
462 do not know at this time if there is a 2 GiB or 4 GiB limit,
463 nor if this affects any other filesystems.
465 The ls command does not work.
467 lmbmfs This filesystem and device will only appear if loaded via a
468 Multiboot compliant boot loader, masquerading as Multiboot
469 compliant OS kernel, and when modules are passed. ls is possi-
470 ble only on the root directory ("/", "/."). Files keep the
471 names passed by the Multiboot boot loader, but have the direc-
472 tory part stripped, and can be accessed with any directory
473 leading. If they have no names, they are given an enumerated
476 tftp, nfs These filesystems and devices will only appear of loaded via
477 PXE. They obviously do not support ls.
479 http There are plans to support this if pxebsd.0 is loaded from
480 gPXE, but no code yet. For now, gPXE can load boot using Mul-
481 tiboot, and any passed modules are handled via lmbmfs.
483 ustarfs This filesystem is currently only usable with the boot floppy
484 and assumes that the entire floppy disc (except, on sparc, the
485 MD disklabel) is a valid ustar archive.
487 MirOS BSD #10-current August 6, 2010 7
projects / grml-live.git / blob