+++ /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, the Multiboot Specification, etc. MirOS floppies
- use a specially limited version 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,
- and a pseudo filesystem called lmbmfs), inspect the filesystems, get or
- set machine information, or load other bootloaders (see below for de-
- tails). It can inflate gzip(1) compressed files (with LZMA compression
- planned), set up serial console, and provides an interactive prompt.
-
- Basic operation procedure is as follows:
-
- 1. Be loaded. However this is done, as the first thing we write a RETF
- instruction to 0000:0000 and CALL FAR it (from 16-bit code), or
- write a RET instruction to 0x00000000 and CALL it (from 32-bit
- code), backing up the previous content of course, so that qemu+gdb
- users can intercept via "b *0".
-
- 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. DOS has set up a PSP (Program Segment
- Prefix) for us, which may contain a command line which we
- store away for later perusal if it is not empty.
-
- 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. The
- COMBOOT API has set up a PSP like DOS as well, which we
- handle the same.
-
- 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. Modules passed to us by the
- Multiboot compliant boot loader will be moved off to just
- above 20 MiB in memory; their dirnames as well as any
- command lines to the Multiboot modules are discarded. If
- a command line is passed to the Multiboot OS kernel, i.e.
- this bootloader, the pathname of the loader is skipped;
- it is then cut off after a certain size limit (currently,
- 256 bytes) and stored away for later use. The modules are
- made available as regular files using the virtual lmbm
- (Loadable Multiboot Modules) device and filesystem (in-
- RAM file store, really).
-
- 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, multiboot module information)
- 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:FF7Ch. The 128 bytes in between, from 3000:FF80h onwards, con-
- tains a potentially stored away PSP command line, before it is moved
- to the buffer after the bss and ssbss sections have been initialised
- (zeroed out). The stack is shared between Real Mode and 32-bit Vir-
- tual 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
- issues), except some rather large uninitialised areas and the disc
- I/O bounce buffer, which begin at 3000:0000 and grow upwards, nick-
- named the ssbss section. 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, unless a (non-empty) command line is
- passed.
-
- 5. The system is switched to Protected Mode.
-
- 6. If a command line was passed, it is moved from its original (Multi-
- boot, above 1 MiB or way below in the real mode area) or temporary
- (0x3FF80) location to cmd_buf.
-
- 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
- + o Loadable Multiboot Modules (if any, they are moved off to safe
- locations and the virtual lmbm device and lmbmfs are set up)
- + o Floppy disc drives
- + o Hard disc drives, including El Torito CD-ROM drives
-
- 8. If a command line was passed, it is executed. If it contained a boot
- command, the kernel is attempted to be loaded; otherwise, or if it
- fails, execution flow continues at the command prompt (see below)
- with no timeout or auto-boot enabled.
-
- 9. Unless a control key is held or a command line was passed, the files
- /x.x.x.x/boot.cfg if loaded via PXE (where x.x.x.x is our own IPv4
- address) and /boot.cfg, with "cfg" possibly replaced from the Live
- CD menu, are read and executed as if the commands had been entered
- on the loader prompt.
-
- 10. 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 dos Execute INT 21h, AH=4Ch, to return to DOS or SYSLINUX,
- if possible. This will not always work and may hang
- your system.
-
- 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
-
- 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.
-
- pxe Forcibly scan for a PXE boot ROM.
-
- regs Debugging command displaying register dumps.
-
- 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 hd0a:/ (for "ls")
- + o lmbm:/ (for "ls")
- + o cd0a:/boot/grub/stage2
- + o tftp:/bsd.rd.i386
- + o lmbm:/bsd4grml
- + o /bsd
-
- 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.
-
- Free Software Foundation, Inc., Multiboot Specification, Version 0.6.93.
-
-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 (including modules), 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
- MirOS bsd4grml by Thorsten Glaser.
-
-CAVEATS
- The default location of the kernels and the boot.cfg file can be changed
- at compile time.
-
- FILESYSTEM SPECIFIC NOTES
-
- ISO 9660 Filesystems above 4 GiB in size definitively do not work. We
- do not know at this time if there is a 2 GiB or 4 GiB limit,
- nor if this affects any other filesystems.
-
- The ls command does not work.
-
- lmbmfs This filesystem and device will only appear if loaded via a
- Multiboot compliant boot loader, masquerading as Multiboot
- compliant OS kernel, and when modules are passed. ls is possi-
- ble only on the root directory ("/", "/."). Files keep the
- names passed by the Multiboot boot loader, but have the direc-
- tory part stripped, and can be accessed with any directory
- leading. If they have no names, they are given an enumerated
- hex number as name.
-
- tftp, nfs These filesystems and devices will only appear of loaded via
- PXE. They obviously do not support ls.
-
- http There are plans to support this if pxebsd.0 is loaded from
- gPXE, but no code yet. For now, gPXE can load boot using Mul-
- tiboot, and any passed modules are handled via lmbmfs.
-
- ustarfs This filesystem is currently only usable with the boot floppy
- and assumes that the entire floppy disc (except, on sparc, the
- MD disklabel) is a valid ustar archive.
-
-MirOS BSD #10-current August 6, 2010 7
projects / grml-live.git / blobdiff