pxeboot man page on MirBSD

Man page or keyword search:  
man Server   6113 pages
apropos Keyword Search (all sections)
Output format
MirBSD logo
[printable version]

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:

	  +   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).
	  +   Memory: ask the BIOS and probe page by page through the address
	      space, in case the BIOS reports wrong information.
	  +   APM support
	  +   PXE support
	  +   Loadable Multiboot Modules (if any, they are moved off to safe
	      locations and the virtual lmbm device and lmbmfs are set up)
	  +   Floppy disc drives
	  +   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:
		      +	  com0
		      +	  com1
		      +	  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:
     +	 fd0a:/bsd
     +	 hd0o:/bsd.rd
     +	 / (for "ls")
     +	 hd0a:/ (for "ls")
     +	 lmbm:/ (for "ls")
     +	 cd0a:/boot/grub/stage2
     +	 tftp:/bsd.rd.i386
     +	 lmbm:/bsd4grml
     +	 /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
[top]

List of man pages available for MirBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net