How To Get Haiku Booted

This is an advanced guide with technical details about the on-disk layout and internals of how the Haiku boot process works. If you just want to install Haiku, you do not need this page, please refer to the Booting Haiku guide instead.

1. The Basic Boot Process

1.1 The BIOS

When you turn on a BIOS based (as opposed to firmware based) system, which is still the most common today, the first thing loaded will be the BIOS (Basic Input Output System). It is like a small operating system of its own and has the purpose of configuring the system hardware and provide an environment that a more high level operating system can work with. For example it configures PCI devices, harddrive controllers, USB, the processor itself and sets up ACPI tables in main memory. Current BIOSes are quite a bit more advanced than they were in the past, commonly having support for USB keyboards and USB mass storage to allow operating in so called legacy free configurations (i.e. without the old PS/2 input and maybe without some of the more traditional PC architecture components). OK, not going into more detail as that's not essential here.

So when the BIOS has done its job, it will try to find a Master Boot Record (MBR) on any of the harddisk-like medias or other boot method specific block on other media (El-Torito on CDs/DVDs for example). Something like a USB memory stick is regarded as being harddisk-like, because it really is emulating a SCSI harddisk to the system. When it finds a boot record, it then loads that into memory and instructs the CPU to start execution of the instructions present.

1.2 The Master Boot Record

Generally this is just the first block of any harddisk-like medium, usually 512 bytes in length. It contains boot code in the first part and the partition table at the end of the block. What you have there as boot code depends on what boot manager you have installed. You have either installed a boot manager explicitly, for example GRUB or the BeOS boot manager, or it was implicitly installed for you when partitioning the device (during Windows setup for example). Boot managers range from totally simple ones that are just enough to find the partition marked active and jump to the partition boot code of said partition, to almost complete operating systems with editing capabilities and other fancy features.

1.3 The Partition Boot Record

Additionally to the Master Boot Record, there can also be a partition boot record. It's located at the start of a partition and contains further boot code. Depending on the boot manager you are using and how you configured it, this boot code will be executed or not. In the case of Haiku the partition boot code does locate the "/boot/beos/system/zbeos" file which then starts the operating system boot process. Additionally it contains the partition offset needed to access this partition during boot. A wrong value for that offset is probably one of the most common reason why a Haiku installation doesn't start to boot.

As mentioned, whether or not the partition boot code is used depends on the boot manager and boot manager configuration. If you take GRUB installed as boot manager in the MBR and booting Linux. GRUB knows how to handle most Linux filesystems and it does know how to load and start a Linux kernel off of it. Therefore it can directly load Linux without the need for any additional boot code. However GRUB does neither know how to handle BFS and find the zbeos boot loader, nor would it really know how to execute it. Therefore you cannot use GRUB to directly boot Haiku. Instead you need to chainload the partition boot code of the BFS partition, as it knows how to handle both the BFS and zbeos.

1.4 The Boot Loader

After the boot loader (zbeos in case of BeOS/Haiku) has been found and loaded into memory, it is executed. The boot loader is the one providing you with the Haiku boot menu when pressing the space bar in early boot and is the one detecting basic system configuration. It also contains the logic to find and load the kernel (kernel_intel on BeOS and kernel_x86 on Haiku) as well as some boot modules required. Boot modules include the bus managers, bus and device drivers required by the kernel to successfully access the boot volume to load the rest of the modules and execute anything it needs to fully boot the system. If you boot to an ATA harddisk it would require for example the IDE or ATA bus manager, the harddisk controller driver and the helper modules used by them. Booting from USB would require the USB bus manager, the host controller drivers and the usb_disk driver for example. The boot loader also provides the kernel with configuration information and info about initial memory layout for example. This data passing between the boot loader and the kernel is specific to Haiku and the Haiku revision, it is possible that the information passed changes from one revision to another. This also makes it obvious that a zbeos from a BeOS installation cannot work with a Haiku kernel. Likewise using a BeOS bootfloppy that provides such a zbeos is not going to boot Haiku.

1.5 The Kernel

Once the kernel is loaded and starts executing it sets up a working environment. Memory management, bootstrapping and configuring non-boot CPUs, timers, interrupts, filesystems, module infrastructure, drivers... Everything that is needed for a fully working system and has not yet been loaded. Once this environment is set up, the kernel will start the bootscript, that then launches the different servers to provide a usable userland.

2. Installing Haiku

If you intend to put Haiku onto a dedicated partition on your normal harddisk, you have several options to do so depending on your host operating system and wehther or not you intend to use a pre-built image or build from source.

2.1 Building from Source

Building from source generally has the advantage that you can do modifications, include optional packages and that making everything bootable is mostly taken care of automatically. On the other hand it is of course quite a bit more time consuming and resource intensive.

See the Building Haiku on Ubuntu Linux article for more details if you're building from Linux. Building from Windows is described in this tutorial, note though that under Windows you can currently only build images and not install directly to a partition. If you're building on BeOS see the tools section of of the getting started page and see this article on getting the source and building it.

2.2 Copying a Pre-Built Image

If you can't or don't want to go through building from source, you can also take an already built image. You can download those from Haiku-Files. Download a raw image, not a VMWare one. Note that these are test images, they are not complete distributions that include a lot of software, both to keep the size and complexity of building them down. Future releases will include a more complete set of software obviously.

When you've downloaded the raw image, you need to get this image to the partition or medium you intend to install it to. Under BeOS, Linux or basically everything except Windows you can use dd to just copy it over, using the partition or drive as a target.

# under BeOS to partition X on the master on the first channel
dd if=/path/to/image of=/dev/disk/ide/ata/0/master/X

# under BeOS to the raw slave on the first channel (overwriting the MBR)
dd if=/path/to/image of=/dev/disk/ide/ata/0/master/raw

# under Linux to partition X on the first harddisk
dd if=/path/to/image of=/dev/hdaX

# under Linux to the raw second SCSI disk (could be a USB drive)
dd if=/path/to/image of=/dev/sdb

Make extra sure that you have the right partition picked there, as these commands are destructive. Recheck with a partitioning tool to verify for example. Note that you'll probably need administrative rights under Linux, so use sudo or su to execute these commands.

If you want to put the image at the absolute start of the drive (so that you don't need an additional boot manager), make sure that you write to the whole raw drive and not to a partition. You do that by specifying a raw device instead of a partition. Under Linux you would for example omit the partition number resulting in "sdb" instead of "sdb1". Under BeOS you would pick the ".../raw" path instead of one with a number. If you use such a command, you overwrite the MBR containing the partition table. This means, that all the partitions on that drive will become inaccessible (not only the first part of the drive). So be sure that you want to do such a destructive operation!

Under Windows things are sadly a bit more complicated. You can try dd for Windows or use a tool like flashnul to get the image to a partition or USB drive. You should find the tools on the Internet, see this forum post about how to use flashnul to copy a Haiku image to a USB flash drive.

Note that when you just copy over an image to a partition or drive, you won't be able to use the full size of the target partition/drive. The image was built with a certain size (256MB currently) which is the size of the filesystem inside the image. So there's no real point in making a 10GB partition available for it, it won't be usable.

2.3 Copying the Contents of a Pre-Built Image

Instead of copying the image itself you can also make a separate BFS partition yourself and then copy over the contents of the image to that partition. You will need a platform supporting BFS to do that obviously, which leaves you with two possible options. Either you use a version of BeOS to do the setup with DriveSetup or mkbfs or you use Haiku itself with the Installer or DriveSetup. Once you've created and initialized the target partition you can mount the image (using tools like Mount Image or through the Terminal) and copy over all the files. If you are under Haiku, you can just as well use the Installer to make a duplicate of your currently booted installation.

3. Getting Bootable

Now that you have installed Haiku in some way or another there might remain steps to take to actually make this installation bootable. As you saw above, there are quite a few things involved when booting an OS. Some of the parts differ between OSes, not everyone might split boot loader and kernel, but essentially the steps are the same. Most of the things can and will be further automated when Haiku will be released, but others are more complicated and not within the power of Haiku.

3.1 Making the Partition Bootable

If you built from source directly to a partition the build system has most probably done the required steps to make the partition bootable automatically. If so you can skip this point and continue with configuring the boot manager below.

When you just create a plain partition and initialize it to a BFS filesystem or if you copy over a complete Haiku image, this doesn't necessarily make the partition bootable. The partition boot record may be missing, or the partition offset could be misconfigured. The prebuilt images for example contain a partition offset of 0 for example, since they are not actually partitioned. They only consist of a direct BFS filesystem, so the offset to that is 0. This will work in exactly one case, where you don't actually put it into a partition. If you for example copy such an image directly to a USB drive starting from 0, overwriting the MBR (destoying all partitions already there), then this will boot. If you however copy an image to the first partition on your harddisk, this will not work out of the box, as the boot code in the partition boot record won't find the desired filesystem at offset 0 (that's where the MBR still is).

To make sure a partition boot record is there and it contains the right partition offset, you can use the tool "makebootable". Makebootable will do both, write the partition boot code to the beginning of the partition and detect and write the partition offset to where it is needed. You can use the makebootable from BeOS if you have a BeOS installation that has access to the partition in question. To do that, mount the volume you have Haiku installed to and use:

makebootable /HaikuMountpoint

Where "/HaikuMountpoint" is where you have mounted your Haiku volume to. Note that the BeOS makebootable can be used, because the partition boot record does only load the zbeos boot loader. As Haiku does provide a zbeos as well and there is no information passed from the partition boot code to the boot loader, this is compatible between BeOS and Haiku and you can use a BeOS makebootable with a Haiku boot loader and the other way around.

If you already have some Haiku medium capable of booting Haiku (like a USB drive) you could also boot into Haiku and run makebootable from there. Note that there is currently a bug in makebootable that will require you to run it from the location it resides in like so:

cd /bin
makebootable /MountpointOfNewHaikuInstallation

If you are on Linux or another build platform that has support for makebootable and have the sources available you can run:

jam run ":<build>makebootable" /dev/sdaX

Where the "/dev/sdaX" is the partition that is supposed to be made bootable. Under Windows this is currently not possible.

3.2 Configuring the Boot Manager

When the partition itself is bootable, i.e. contains a partition boot record and the correct partition offset, there needs to be a way to get it executed. If you installed Haiku by copying an image to the complete beginning of a disk or USB drive, this will already be the case. There is no boot manager and no MBR at all, but straight the partition boot code, which should then work out of the box. So if you have it installed this way, go right ahead and boot.

If you use a boot manager like GRUB however, you need to instruct it to load from that partition. You do that for GRUB by adding an entry to its menu.lst usually located at "/boot/grub/menu.lst". The following would instruct it to switch to the partition and then just chainload the partition boot record:

title Haiku
rootnoverify (hd0,3)
chainloader +1

That would work if you installed to disk "0" and partition "3". Note that the GRUB naming is one-off the Linux one, so if you have it installed to "/dev/sda4" that would translate to disk "0" (sda == 0, sdb == 1, ...) and partition "3" (4 - 1).

In case you are using the BeOS boot manager, just re-run the "bootman" command and add the new Haiku partition to the boot menu.

If you have another boot manager consult its documentation on how to chainload partitions, most should support such a thing, possibly named a bit different. In doubt just add an entry for the partition, probably this will cause it to chainload, even if not explicitly named so.

4. Easy Installation through USB Drives

The above steps should get you going in most cases, but maybe sound a bit scary or involved. My personally recommended method that should work on most current hardware would be to make a dedicated USB drive like a USB memory stick to boot Haiku. To do that, you can take a relatively small USB drive that has enough space to fit the image onto. Then you just copy that image directly to the raw drive, not to a partition, replacing everything including the MBR, destroying all the partitions that were on there (see above as to tools to use). This is destructive and you can't use anything after the image size of that drive, but if you get some cheap small USB memory stick just for that purpose it's certainly one of the easiest ways to boot Haiku. Once you've booted Haiku you can also do an installation from there, initializing partitions with BFS using DriveSetup and using the Installer to do a proper installation. Note that you cannot currently create partitions under Haiku. Use your preferred partition tool to create a dedicated partition before booting Haiku. Note also that the Installer doesn't have a link in the Haiku menu, therefore just run it from the Terminal. If you additionally execute it from "/bin" this works around the makebootable problem, giving you the commands:

cd /bin
Installer

That should work and be pretty usable to boot devices that you have no other means to put Haiku onto otherwise. This works for example out of the box on the Asus EEE, but really should work for every USB bootable x86 machine. If it doesn't, please make sure that your issue is documented in a bug report at our bug tracker. We cannot fix it if we don't know that it's broken.

I hope this clears up some things. If nothing else this should get you a better starting point for troubleshooting if it indeed doesn't boot.