--- /dev/null
+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
+
+ [+-]<size>@<address>
+
+ 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
projects / grml-live.git / blobdiff