This document is unmaintained and deprecated, please read the Yaboot HowTo instead.

Of course, this is just a very preliminary version of the FAQ. Many pieces are unfinished, and many others haven't even been started yet. I'd welcome any and all comments on this document. E-mail them to me at Thanks for your patronage. ;)
--ebp, 4/22/2000

modified to clarify yaboot's non-support of oldworld hardware
-- Ethan, 6/6/2000

modified the ybin section to document the new ybin 0.17 ofboot which is autoconfiguring. Also corrected the explanation of the read-only keyword in /etc/yaboot.conf. Updated again to better reflect new features in current versions of ybin and document ofpath.
-- Ethan, 2000/11/18

In this version, new or modified sections of text are marked by a dark red color.

What is 'yaboot?'

From Ethan's site (, "yaboot is an OpenFirmware based bootloader for newworld machines."

In layman's terms, it's an alternate method of booting into Linux.

NOTE: yaboot will NOT work on oldworld hardware

Why do I need 'yaboot?'

You don't have any other option for booting into Linux if you're using one of the NewWorld Macs (i.e., any colored Mac) with MacOS 9.0.4 or higher. BootX, another bootloader from BenH, used to boot those machines, but changes made to the MacOS in 9.0.4 (and possibly the earlier 9.0.x series) broke it completely. It worked in MacOS 9.0 and earlier, but performance was sporadic and unpredictable. If you're using a NewWorld machine, we highly recommend you use yaboot. Owners of earlier machines can probably get along just fine with BootX; if you experience odd problems starting Linux, though, you should consider switching to yaboot (only if you have a newworld machine, if you have an oldworld machine consider switching to quik).

What's a bootstrap partition?

(Please note: I've taken a few liberties with this explanation, and skipped over a few subtleties. This isn't exactly what happens, but it should be close enough to satisfy most people. If you'd like more detailed technical information, you're encouraged to search the various LinuxPPC lists for more information.)

When your Mac first starts up, Open Firmware begins checking your partitions, beginning with the one pointed to by the environment variable "boot-device," for a blessed folder (in the case of the MacOS, this folder is titled "System Folder," but the name is irrelevant). It looks inside each blessed folder it finds for a file of type 'tbxi.' Upon finding this file, it checks to ensure that the file is a CHRP script, which is a set of instructions further directing Open Firmware on how to continue the start process. When you boot into the MacOS, the CHRP script loaded by OF is the MacOS ROM file, and this file in turn places a copy of the Mac OS ROM into memory. From there, the startup process you're used to seeing is under way.

In the case of yaboot, instead of loading the MacOS ROM, the CHRP script loads up yaboot and hands off the startup process to it. Yaboot in turn asks which kernel image you wish to load, and boots into Linux from there.

From this, a reasonable person would assume that, to boot Linux, you'd simply point OF to a yaboot-loading CHRP script, and this is exactly what we do. We "bless" the folder/partition containing the script, and instruct OF to boot from that. However, we run into a problem the next time we boot into the MacOS: in all its greedy glory, unblesses any folder/partition it finds which doesn't contain a valid MacOS, preventing you from booting from it again. This is obviously undesirable. Several people have created methods for faking out the MacOS and tricking it into loading yaboot using a "dummy" System Folder. The SuSE distribution does this using dummy Finder and System files that are sufficiently hacked to trick the MacOS into thinking they're valid (although this doesn't always work; by some reports it fails as much as 90% of the time). Another method involves ybin, created by Ethan Benson, which we will get to later. We can avoid the entire "unblessing" process, however, by making the yaboot partition on a drive a bootstrap partition of type "Apple_Bootstrap." The MacOS won't even try to mount a partition of this type, and since it never mounts, it never unblesses it.

When you create a bootstrap partition, which you will likely do eventually, please note that it should never be mounted directly, in either OS. If you're making a bootstrap partition, you're most likely using ybin anyway, and it will take care of the work for you. We cover setting up ybin[not completed] and creating a partition[not completed] in further detail elsewhere, so see those sections if you want more information.

What's Open Firmware?

Setting Up ybin

The first bit of advice I can offer for ybin is: don't uncompress it in the MacOS! Move the .gz archive into Linux first, or download it from there in the first place. The archive contains some symlinks that aren't worth the effort to recreate. You should also note that these instructions assume you have some method of booting into Linux, be it from your distribution CD or from some other method you already have working. Installing yaboot shouldn't break that method, but be forewarned that you may have to spend quite a bit of time fiddling to get things back the way they were if something goes wrong here.

You'll first need to determine where you want to store your kernel images, as you'll need to pass this information onto ybin and yaboot before you actually use them. yaboot, particularly in conjuction with ybin, offers you amazing flexibity in where you store your kernel images. They can be kept on anypartition: ext2, HFS, or even HFS+. A common misconception is that to use any kernel images downloaded in the MacOS, you have to first move them to an HFS "exchange" partition. With yaboot, this is completely untrue. You can keep them, quite literally, anywhere.

The first bit of "down-and-dirty" work you'll have to do is actually partitioning your drive, if you haven't done so already. Check out "How do I partition my drive?" for detailed information.

Once that's done, you'll need to determine the Open Firmware path to your boot device. You'll need to have a bootstrap partition to do this (see "What's a bootstrap partition?" for pointers; I'll be adding actual instructions soon). This bootstrap partition can be on any drive, but the steps for finding the OF path will vary depending on what type of drive it is. If you'll be re-partitioning your internal hard drive anyway, the absolute easiest thing to do is to make the first partition on that drive the bootstrap. See the section on drive partitioning for details.

If you're installing to an IDE hard drive

If the bootstrap is on your Mac's internal hard drive, the device path is "hd:". Make a note of this and continue to "Setting Up Configuration Files".

If you have another drive connected to your Mac's second IDE bus, then use "ultra1:" as your device path. If you're using a slave drive on one of the IDE busses, then you'll have to display the path of hd and change the last bit from "disk@0" to "disk@1." I'll have more detailed instructions on this later on.

If you're installing to an external SCSI drive

The simplest way to find the OpenFirmware device path to a given disk is to use the ofpath utility (included in current ybin distributions) example: ofpath /dev/sda or to find the path to a partition: ofpath /dev/sda2

If you're installing to a Zip disk

The path is "zip:". Make note of it. You may proceed.

Setting Up Configuration Files

ybin comes with the yaboot distribution as of yaboot-1.3. Simply download the latest yaboot distribution and run the following commands:
tar -zxvpf yaboot-X.Y.tar.gz
cd yaboot-X.Y
make install
At which point you should see:

installation successful. 

The ofboot script included with ybin 0.17 and later is automatically configured by ybin based on options in /etc/yaboot.conf. It is capable of presenting a dual or tri-boot menu. To enable dual booting of GNU/Linux and MacOS add "macos=hd:10" to /etc/yaboot.conf where "hd:10" is the OF path to a MacOS boot partition. If you want to boot MacOSX you can also add a "macosx=hd:11" line. You can also use the unix device node for these options and ybin will automatically find the OpenFirmware device path, example: "/dev/hda10". The default OS that is booted is controlled by the "defaultos=" option, the default is GNU/Linux.

IMPORTANT: You should never edit this new ofboot script.

Now you're ready to run yabootconfig, it will generate a valid and working /etc/yaboot.conf for you.
You can also edit yaboot.conf yourself if you wish. Open /etc/yaboot.conf in your editor. Information on all the possible fields in this file is available in the man page for yaboot.conf. The first part of the default yaboot.conf file looks like this:


Begin by changing the boot line to the Linux-style path to your bootstrap partition, such as "/dev/hda2" or "/dev/sda9". Set device to the OF device-path to the drive where your kernel images are stored, followed by a trailing ":". Don't add the partition number. install refers to the bootloader ybin will install, and magicboot refers to the CHRP script; you can leave these at their defaults (inquiring users will want to look at the man pages for more information). delay is the time in seconds ofboot will wait for you to choose an OS when the dual boot menu is enabled. timeout is the time, in tenths of a second, before yaboot boots the default kernel image (you'll set the default shortly). Comment out or delete the nonvram line (if one exists) if you have a up to date system, this will allow ybin to automatically update the OpenFirmware boot-device variable to boot the bootstrap partition ensuring you don't have to enter OpenFirmware and boot the system manually. Below the "header" information, you see an entry that looks like this:


image is the location of the kernel image; if you're keeping them in /boot and making symlinks, this will be "/boot/vmlinux". root is the Linux-style path to your root partition. read-only causes the root filesystem to be mounted read-only to allow for fsck to run, and partition refers to the partition number the image is on; you can usually set this to the digit in your root path. label is a name that you can assign to this particular kernel configuration; make sure each config has a unique name!

Once you've set those options, go back up to the top of the file and add a line:

default = label

Change label to the label you assigned to your kernel configuration, change timeout to whatever length of time you prefer (remember, it's measured in tenths of a second). Save and close yaboot.conf, and you're just about ready to go. First, though, you have to create an HFS filesystem on the bootstrap partition. Ethan has included a utility to do this for you. Please note that this will format the bootstrap partition, so if you have any useful information on it, be sure to move it elsewhere before you have mkofboot prepare that partition. Run "mkofboot -v," and you should be asked if you want to create an HFS filesystem on whatever device you indicated was your bootstrap partition. Respond "y," and mkofboot should output something like the following:

mkofboot: Finding OpenFirmware device path to `/dev/hda2'...
mkofboot: Creating HFS filesystem on /dev/hda2...
mkofboot: Checking /dev/hda2 for valid HFS filesystem...
mkofboot: Copying /usr/local/lib/yaboot/yaboot to /dev/hda2...
mkofboot: Copying /etc/yaboot.conf to /dev/hda2...
mkofboot: Installing first stage bootstrap: ofboot...
mkofboot: Setting attributes on yaboot...
mkofboot: Setting attributes on yaboot.conf...
mkofboot: Setting attributes on ofboot...
mkofboot: Blessing /dev/hda2...
mkofboot: Cleaning up...
mkofboot: Updating OpenFirmware boot-device variable in nvram...

Of course, your partition numbers will be different, but you get the idea. If mkofboot executes with no errors, you're almost ready to go! If you're on a G4, iMacDV, or Pismo laptop, you can restart while holding down the option key, and you should be presented with two buttons: one for the MacOS, and one for Linux. Click the Linux button, then the arrow, and you should boot into yaboot and from there into Linux. Ybin will update the boot-device OpenFirmware variable automatically so you should boot right into yaboot without any extra effort.

Changing the boot-device in Open Firmware

(Remember, you can skip this section if you've re-partitioned your internal drive and made the first partition the bootstrap. If this describes the steps you've taken, restart as usual, and your boot script should kick in; if it does, you can skip this step.) You can also skip this step if you removed the nonvram line from /etc/yaboot.conf and ybin did not complain about being unable to update OpenFirmware.

Important! Open Firmware can be pretty intimidating. If you follow these instructions carefully, you shouldn't have any problems. However, if at any time you find yourself totally unable to boot into the MacOS, simply restart while holding down command-option-O-F, and at the "0 >" prompt type "boot hd:X,\\:tbxi". X should be the partition number of your MacOS partition (if you haven't re-partitioned your internal drive, you can leave the X off entirely). This should take you back into the MacOS, where you can re-select your startup drive in the Startup Disk control panel, and then have another go at it. It might also be a good idea to have a startup CD for your Mac handy, although you probably won't need it if you use the "boot hd:X,\\:tbxi" command. You can also use the OF command "set-defaults" to restore anything you may have changed back to their defaults. Use this if things really seem screwed up.

Reboot into Open Firmware (restart while holding down command-option-O-F). At the "0 >" prompt type:

setenv boot-device path-to-bootstrap-device:X,\\:tbxi

Replace path-to-bootstrap-device with, well, the OF path to your bootstrap device (determined earlier) and replace X with the bootstrap partition number. Press return, and then type "boot". If your ofboot.b file was configured to launch yaboot by default, you should be in yaboot. If you set the MacOS as the default, you should be in the MacOS. Restart again and hold down the spacebar; you should switch into whichever OS you haven't already been in. Congratulations. ;)

If, on the other hand, things don't seem to work quite right, try typing this at the OF prompt:


If yaboot.conf isn't configured properly, this should generate an OF error message that may be useful in tracking down the error. If you're e-mailing me or one of the lists for assistance with your setup, please include this error if at all possible; it makes it much easier for us to narrow down were the problem most likely is.

Why doesn't yaboot seem to use the changes I made to yaboot.conf?

You'll need to re-run ybin whenever you make changes to your configuration files. ybin will copy them to your bootstrap partition and make other necessary modifications for them to be used by yaboot.

Okay. I've downloaded it. What do I do now?

*** I've removed this section. The ybin section has virtually all the information that used to be contained here. If anyway wants instructions on yaboot alone back, please let me know. ***

How do I partition my drive?

This is probably the most vital part of setting up Linux on your system. However, since you're messing around with some very powerful software, it can also be the most dangerous if you're careful. Before you begin partitioning, make sure you have a backup of anything you can't stand to lose. If you don't, and something goes awry, you'll be very, very angry at yourself; don't say I didn't warn you. ;)

[still not completed, but being worked on] For a basic tutorial on partitioning the hard disk using mac-fdisk (aka pdisk) see mac-fdisk-basics

How do I determine the boot path to an external SCSI drive?

This section is obsolete, use the included ofpath utility find the OpenFirmware device path instead, its easier and more reliable.

This is similar to setting up yaboot to use a non-adapted drive, except it takes a few more steps to determine the boot device. (special thanks go to Joe M. for his excellent post dealing with this issue, on which these instructions are heavily based )

  1. Identify SCSI card name
    First, open up the Apple System Profiler (probably on your Apple Menu, unless you moved it) and switch to the "Devices and Volumes" tab. Find your SCSI card in the list, and click the exposure triangle to display detailed information for it. You're interested in the "Card name" field. Make note of the name displayed there (I suggest writing it down; you won't be able to access it in a text file or anything in Open Firmware, which you're about to get into). It should be something cryptic looking like "ADPT,2930CU." (Note: That's the name of my card; yours may vary.) You can skip this step if you've got a pretty good idea of what device name you'll be looking for in the next step, but don't come cryin' to me when you waste several restarts switching back and forth to look the name up.
  2. Determine Open Firmware device path
    Restart your Mac, and hold down command-option-O-F. You should switch into the white, tiny-text-filled Open Firmware screen (why it isn't a lower resolution, I'll probably never know). Type in "dev / ls", sans the quotes but with the spaces on both sides of the '/,' and it should pop out an oppressive looking screen of information. This is an ASCII "graphical" representation of all the hardware on your system. We're only interested in the device that matches the card name you wrote above. Mine looks something like:
    /pci@f2000000 ...  /pci-bridge@d ...  /ADPT,2930CU@2 /disk
    where the elipses denote a bunch of other junk in between. Notice that, with the exception of an "@2" tacked on at the end, we see the card name we wrote down earlier. This is the device we're looking for. Write down the path, ignoring the levels after the card name (in this case we'd write down "/pci@f2000000/pci-bridge@d/ADPT,2930CU@2/"; of course, your system will probably be a little different). You'll now add a bit more information to your boot path, and then create an alias for this device so you don't have to do so much typing later on (this is a common and valuable technique in the Linux world, btw ;-).
  3. Determine SCSI ID and HFS partition
    There's just one last piece of information you need to determine the fully-qualified device path to your Linux boot device (actually, two small pieces, but we'll pretend they go as a unit): the SCSI ID, and the partition ID of the MacOS (HFS) partition that yaboot and the kernel images are stored on. The first one is usually pretty easy to get (just check the back of your drive; there's usually a dial or switchable-number back there; that's your SCSI ID), but the second requires a little more work. If you don't remember the partition number from when you first partioned your drive (you have already partitioned it, haven't you?) then you'll have to boot back into the MacOS - using either "boot" or "reset-all" - and launch pdisk and examine the partition map for your drive. If you need help obtaining or using pdisk, please see "How do I use pdisk? [not completed]" for a mini-primer on the venerable disk partitioning utility. You'll add the SCSI ID to the very end of the device-path you wrote down in step 2, in this format:
    So if, to continue the example above, my HFS partition is on SCSI device 6, so the complete device-path would be:
  4. Adding a devalias
    Now, when you're setting up yaboot.conf and ofboot.b, you have to type this path a lot, and who in their right mind would want to type this monster out over and over? Fortunately, Open Firmware lets you create your own aliases; unfortunately, it acts a little flaky with them sometimes. If these work for you the first time, then great! If they don't, restart and try 'em again.

    Still in Open Firmware, type:

    setenv use-nvramrc? true

    followed by a return, and then:

    nvalias sd
    		[device-path] <return> nvstore

    This assigns a new alias, sd, to the device path you determined above. Now, when setting up yaboot and ybin, when I refer to your device path, I'm talking about "sd".

[Credits, far from done, these are basically notes to myself]

Ethan Benson (
Joe Mastroianni (joe@adaptive
Nelson Abramson (
Clay (
Florin Oprina (
Chas Williams (
Andy (
Mike McCallum (
Federico Heinz (
Gaby Levinson (
and the many other people, who for one reason or another, have not been mentioned. You know who you are. ;)

I'd like to close by thanking God for putting me here and bringing to where I am today. Without Him, we are nothing.