BOOT(8) BSD System Manager's Manual (i386) BOOT(8) NAME boot, boot.cfg, ldbsd.com, pxeboot - i386 second-stage boot loader DESCRIPTION The boot system programme, often called ldbsd.com, aims to load the sys- tem kernel into core memory from disc or network and run it, as well as do some auxiliary functions, while dealing with the problems arising from the history of the i386 architecture since 1978, incompatibilities, ex- tensions, bugs, El Torito booting, Intel's Preboot Execution Environment (PXE) for network boot, etc. MirOS floppies use a specially limited ver- sion optimised for size, lacking support for any filesystem other than 4.2FFS and most commands. It can be loaded either directly from the BIOS (most commonly via PXE; earlier versions could also be loaded using El Torito), the bootxx first stage boot loader (from floppy, hard disc, compact flash card, USB stick, and the likes; recently, since bootxx itself was made El Torito capable, this has become the desired method for El Torito boot), any bootloader compliant with the Multiboot specification (as boot is a Multiboot com- pliant OS Kernel image), or after renaming to ldbsd.com by any bootloader implementing the COMBOOT API (specified by SYSLINUX, EXTLINUX, ISOLINUX, PXELINUX) or MS-DOS(R) (unless DOS occupies the HMA). Once loaded, it can be used, in a more or less limited fashion, to boot a MirOS kernel from a supported filesystem (4.2FFS, ISO 9660, FAT12, FAT16, FAT28, TFTP, NFS), inspect the filesystems, get or set machine information, or load other bootloaders (see below for details). It can inflate gzip(1) compressed files, set up serial console, and provides an interactive prompt. Basic operation procedure is as follows: 1. Be loaded. BIOS We are loaded to 0x07C00. The drive used to load us from is passed in the DL register. The ES:BX and DS:SI regis- ters and the stack contain additional data. While we do not care about the actual address, we expect to be whole. bootxx We are loaded at the final address. The drive used to load us from is passed in a special memory location. The DS:SI registers are set up if we were loaded from a HDD partition. The Master Boot Record (/usr/mdec/mbrldr or /usr/mdec/mbrmgr) takes care to set these up correctly. PXE The NIC's PXE boot ROM initialises the NIC, network driver, UNDI and PXE interfaces, contacts a DHCP server by broadcasting an IPv4 request on the network, gets an IP address and the name of a file to load from the DHCP server, and downloads the file indicated via TFTP to 0x07C00. That would be boot. Control is then passed to address 0x07C00 with ES:BX and the stack set up. PXE booting is useful for diskless(8) clients or initial download and execution of the installation kernel, bsd.rd, or for rescue system purposes. DOS We are loaded to xxxx:0100h with no drive or PXE informa- tion set up. The interrupt vectors are hooked by DOS, so if we overwrite any memory in use by DOS, we lose. That would be the case if xxxx is larger than our final ad- dress, any hooks point to an address between our final address and 9000:0000h, the HMA is in use (because that's where the kernel is loaded to), or somesuch. This also implies we cannot chain any other bootloader. Further- more, we require the machine to be in Real Mode, not in VM86 mode, so EMM386.SYS, Win32 or similar must not be active. We ask DOS for the current drive to use this in- formation later. COMBOOT We are loaded in a similar way as from DOS, except the machine state is not changed as much from the initial state. After determining that we are in fact loaded via COMBOOT and not DOS, we ask SYSLINUX to terminate after gathering information about the boot drive, partition, or PXE; the UNDI and PXE stacks are kept active if any. Multiboot We request to be loaded to 0x00100000 (the HMA) due to GNU GRUB's limitations, save the boot device off the MBI structure, copy ourselves to the final location, and switch back to Real Mode. During the initial operation, the stack is located about 80 KiB behind the start of our own memory area, and switched to the final location if the position in memory is known to be correct early. 2. System information (boot drive, potential partition table entry, PXENV+ and !PXE structure pointers) are stored in safe locations. 3. The code is relocated to the final address once or twice if needed. The final address is 4000:0000h with the stack beginning at 3000:FFFCh. The stack is shared between Real Mode and 32-bit Virtual Protected Address Mode. The code is mostly organised using the small memory model, with everything within 64 KiB (although the real limit is more than 256 bytes less than that due to initial loading is- sues), except some rather large uninitialised areas and the disc I/O bounce buffer, which begin at 3000:0000 and grow upwards. The heap begins after the bss section and grows up to just short of 9000:0000h. 4. If the bootloader is compiled to do so, for example on a Live CD, it displays a boot menu unless the shift key is pressed, and retains the numeric return value for later, to replace the cfg suffix of the configuration file with it. 5. The IDT for the Protected Mode is set up. 6. The system is switched to Protected Mode. 7. The hardware is probed: + o Console devices: the default BIOS console (INT 10h, which may be a MDA/MGA/Hercules, CGA/EGA or VGA CRT/LCD, plus DIN or PS/2 or emulated keyboard) as well as up to four serial ports (via the BIOS interface). + o Memory: ask the BIOS and probe page by page through the address space, in case the BIOS reports wrong information. + o APM support + o PXE support 8. Unless a control key is held, the files /x.x.x.x/boot.cfg (where x.x.x.x is our own IPv4 address) and /boot.cfg (with cfg possibly replaced from the menu) are read and executed as if the commands had been entered on the loader prompt. 9. The bootloader prompt boot> _ is issued, and a command line is read. If no key is pressed within five seconds, the kernels /bsd and /bsd.old are tried, in order, to be booted with the current parameters; if unsuccessful or any key is pressed, the timeout is disabled (it can be manipulated from the configuration file or command line). The system will be unable to boot if no suitable kernel image is found. Commands from the configuration file and the loader prompt are read line by line and executed as read. Empty lines and lines beginning with the comment character, '#', are ignored when reading from the configuration file. Just entering an empty line at the loader prompt, however, will do the default action of booting a kernel with the current parameters. To pass multiple commands on a line, use the U+0060 character, '`', as del- imiter. To pass multiple commands into a macro definition, use the tilde, '~', as delimiter. Leading and trailing whitespace is ignored. COMMANDS The following commands are accepted at the loader prompt: boot [image [-acds]] Boots the kernel image specified by image with any options given. If the image file specification, or one of its device or filename parts (see below) is omitted, values from variables will be used. -a Causes the kernel to ask for the root filesystem to use. -c Causes the kernel to go into UKC(8) before performing autoconf(4). -d Causes the kernel to drop into ddb(4) at the earliest con- venient point. -s Attempts to boot into single-user mode. cat image Displays the file onto the console. Output is paginated every 24 lines. echo Displays the arguments onto the console. env On i386, this command is not used. help Prints a list of available commands. ls [dirspec] Prints the content of the specified directory in long format. Output is paginated every 24 lines. The cd9660, tftp and nfs filesystems do not support this command. They will either always fail or always succeed with sane but unusable results. The FAT12, FAt16 and FAT28 filesystems have hardcoded perms and uid/gid. machine [command] Issues machine-specific commands: boot dev Load a bootsector (MBR or PBR) from the indicated dev- ice and boot it. Possible devices are fd0 (floppy boot), hd0 (MBR), hd0a, hd0b, hd0c, hd0d (PBR), and some more useless combinations. diskinfo Display a list of probed floppy and hard disc drives including BIOS and geometry information. exec type image Load a bootsector or other bootloader from an image file and execute it. Currently known values for type: grub GNU GRUB 0.9x stage2 file GNU GRUB 0.9x stage2_eltorito file GNU GRUB2 core.img file sector Boot sector or image, loaded to 0000:7C00h MirOS boot second-stage loader label [device] Displays the idea boot has about the disklabel of the currently active or the specified device. memory [arg] If used without any arguments, print the current idea boot has about the memory configuration taken from BIOS or probed. Arguments having the form of [+-]@
add (+) or exempt (-) the specified amount of memory. Both size and base address can be specified in decimal, octal or hexadecimal, using standard C prefixes. Memory segments are not required to be adjacent to each other; the only requirement is that there is real phy- sical memory under the range added. The following exam- ple adds 32 MiB of memory right after the first 16 MiB: boot> machine mem +0x2000000@0x01000000 Another useful command is to withdraw a range of memory from OS usage, which may have been wrongfully reported as useful by the BIOS. This example excludes the 1516 MiB range from the map of useful memory: boot> machine mem -0x100000@0x00F00000 regs Debugging command displaying register dumps. oldbios Enable or disable the so-called "Old BIOS / Soekris helper", which restricts boot from loading more than one sector at a time from disc. macro Displays the names of all currently defined macros. Up to four can be defined, holding up to 256 characters. macro name [cmd] Deletes the macro name, or defines it to cmd. reboot Initiates a warm machine reboot. set [name [value]] If invoked without arguments, prints a list of variables and their values. If only a name is given, the value of that variable is displayed. Otherwise, the variable is set to the new value. The following variables are defined: addr Address at which to load the kernel debug Debug flag device Boot device name (see below) doboot "0" disables automatic boot on entering an empty line howto Options passed to the loaded kernel, see boot image File name containing the kernel image timeout Number of seconds to wait for human intervention before auto-booting tty Name of the active console device, for example: + o com0 + o com1 + o pc0 stty [device [speed]] Displays or sets the speed for a console device. If the baudrate for the currently active console device is changed, boot offers you five seconds of grace period to switch your terminal to match. If the baudrate for an inactive device is changed, it will only become active on the next switch to a serial console device; it is not used on the PC CRT console. The default baudrate is 9600 bps. boot uses eight data bits, no parity, one stop bit. time Displays the system date and time. IMAGE SPECIFICATIONS An image specification consists of two parts, the device name and a path- name, separated by a colon (':'). In most circumstances, both can be om- itted, and pathnames do not need to begin with a leading slash even if they are absolute. Note that, for some filesystems, you are limited to an 8.3 character naming scheme with case insensitive (mapped to lowercase) filenames. Other filesystems may not provide directory listing informa- tion or the ability to stat files (especially remote filesystems). Examples of valid image specifications are: + o fd0a:/bsd + o hd0o:/bsd.rd + o / (for "ls") + o cd0a:/boot/grub/stage2 Disklabels are read from hard discs (BIOS drive >= 80h) by searching for a primary MirOS partition first. The default partition type, 0x27, can be changed at installboot(8) time, where it is hardcoded into the partition boot record. If no suitable MBR partition was found or we're on a floppy, the disklabel is searched at the beginning of the drive instead. The la- bel offset for the i386 architecture is one 512-byte sector. On MirOS DuaLive CDs, it may be embedded in the first-stage sparc bootloader. If no disklabel can be read from the disc, one is faked. The device size ('c' slice) defaults to the size of an 1440 KiB floppy disc, but if any MBR primary partitions are found which span more space, their values are used instead. The 'd', 'e', 'f' and 'g' slices are filled with the four MBR primary partitions, if any. The 'a' slice is filled, in this order, with: the partition passed via DS:SI if plausible, the first non-empty MBR partition ('d'-'g' slices), the whole disc ('c' slice). FILES /usr/mdec/bootxx first stage bootloader (PBR) /usr/mdec/boot second stage bootloader /usr/mdec/mbrldr hard disc MBR, simple version /usr/mdec/mbrmgr MBR, bootmanager version /boot usual location of installed loader ldbsd.com alternative name for boot /boot.cfg boot configuration file /bsd standard kernel image /bsd.rd kernel image for installation/recovery /bsd.old alternative kernel image /etc/dhcpd.conf dhcpd(8) configuration file /tftpboot/boot standard location of boot for netboot /tftpboot/boot.cfg common/shared boot configuration file on the TFTP server; /tftpboot/10.11.12.13/boot.cfg contains peer-specific configuration to be used instead /tftpboot/bsd kernel image /tftpboot/pxeboot deprecated, no longer in use EXAMPLES A sample configuration file for dhcpd(8) is already contained with MirOS and might look as follows: shared-network KICKSTART { subnet 172.23.42.0 netmask 255.255.255.0 { option routers 172.23.42.1; filename "boot"; range 172.23.42.10 172.23.42.199; } } Boot the default kernel: boot> boot Remove the 5 second pause at boot-time permanently, causing boot to load the kernel immediately without prompting: # echo "boot" >/boot.cfg Remove the 5 second pause at boot-time permanently, causing boot to do nothing automatically: # echo "set timeout 0" >/boot.cfg Use serial console. A null modem cable should connect the specified seri- al port to a terminal. Useful for debugging. boot> set tty com0 Invoke the serial console at every boot: # echo "set tty com0" >/boot.cfg Multiple commands on one line are useful for machines whose serial con- sole is unusable from within the boot loader, but the only way to talk to the kernel, e.g. for installation on a Soekris/WRAP: boot> stty com0 38400 ` set tty com0 ` boot /bsd.rd Boot the kernel named /bsd from the second hard disc in "User Kernel Configuration" mode (see boot_config(8)). This mechanism allows for the explicit enabling and disabling of devices during the current boot se- quence, as well as the modification of device parameters. Once booted, such changes can be made permanent by using config(8)'s -e option. boot> boot hd1a:/bsd -c SEE ALSO gzip(1), compress(3), autoconf(4), ddb(4), dhcpd.conf(5), boot_config(8), boot_i386(8), dhcpd(8), diskless(8), fdisk(8), httpd(8), inetd(8), installboot(8), reboot(8), tftpd(8) Intel Corporation, Preboot Execution Environment (PXE) Specification, Version 2.1, September 20, 1999. HISTORY This bootloader is based on code written by Michael Shalayeff for OpenBSD 2.1. The separate pxeboot command first appeared in OpenBSD 3.5, based upon work from NetBSD. In OpenBSD and MirOS #7 and below, the boot.cfg file was called boot.conf, it has been renamed for ISO 9660 and FAT compatibility. A version called cdboot appeared in MirOS #8 and went away for MirOS #10. The separate versions got merged into one bootloader, DOS, COMBOOT, Multiboot support, pagination, macros, the machine exec and cat commands, working chainbooting of bootsectors and GNU GRUB, faked disklabels (if none exist on disc), FAT filesystem support, and many more things were added or rewritten for MirOS #11 and grml by Thorsten Glaser. CAVEATS The default location of the kernels and the boot.cfg file can be changed at compile time. MirOS BSD #10-current February 1, 2009 6