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 firstname.lastname@example.org. Thanks
for your patronage. ;)
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.
From Ethan's site (http://penguinppc.org/usr/yaboot/), "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
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).
(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.
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
hdand 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 driveThe simplest way to find the OpenFirmware device path to a given disk is to use the
ofpathutility (included in current ybin distributions) example:
ofpath /dev/sdaor to find the path to a partition:
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
At which point you should see:installation successful.
ofbootscript 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
You can also edit yaboot.conf yourself if you wish. Open
/etc/yaboot.confin 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:boot=unconfigured device=hd: delay=10 timeout=20 install=/usr/local/lib/yaboot/yaboot magicboot=/usr/local/lib/yaboot/ofboot
Begin by changing the
bootline to the Linux-style path to your bootstrap partition, such as "
/dev/hda2" or "
deviceto the OF device-path to the drive where your kernel images are stored, followed by a trailing ":". Don't add the partition number.
installrefers to the bootloader ybin will install, and
magicbootrefers to the CHRP script; you can leave these at their defaults (inquiring users will want to look at the man pages for more information).
delayis the time in seconds ofboot will wait for you to choose an OS when the dual boot menu is enabled.
timeoutis 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
nonvramline (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=/vmlinux label=Linux root=/dev/hda3 read-only partition=3
imageis the location of the kernel image; if you're keeping them in
/bootand making symlinks, this will be "
rootis the Linux-style path to your root partition.
read-onlycauses the root filesystem to be mounted read-only to allow for fsck to run, and
partitionrefers to the partition number the image is on; you can usually set this to the digit in your root path.
labelis 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
labelto the label you assigned to your kernel configuration, change
timeoutto 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
mkofbootprepare 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
mkofbootexecutes 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
nonvramline 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 "
Xshould be the partition number of your MacOS partition (if you haven't re-partitioned your internal drive, you can leave the
Xoff 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
path-to-bootstrap-devicewith, well, the OF path to your bootstrap device (determined earlier) and replace
Xwith 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:boot path-to-bootstrap-device:X,\\yaboot
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.
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.
*** 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.
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
This section is obsolete, use the included
ofpathutility 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 )
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.
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 /tapewhere 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 ;-).
[device-path]/@idSo if, to continue the example above, my HFS partition is on SCSI device 6, so the complete device-path would be:
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 <return>
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
Ethan Benson (email@example.com)
Joe Mastroianni (joe@adaptive silicon.com)
Nelson Abramson (firstname.lastname@example.org)
Florin Oprina (email@example.com)
Chas Williams (firstname.lastname@example.org)
Mike McCallum (email@example.com)
Federico Heinz (Federico_Heinz@yahoo.com)
Gaby Levinson (firstname.lastname@example.org)
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.