]> HOWTO-Booting with Yaboot on PowerPC Chris Tillman Version 1.03, Sep 14 2002 This document contains installation and usage instructions for yaboot, the GNU/Linux PowerPC bootloader. This document may be distributed and modified under the terms of the GNU General Public License. © 1998–2002 Chris Tillman

This document is maintained in the upstream yaboot source. Patches and translations should be sent to erbenson (at) alaska.net. The most recent sgml version of this document is available via the yaboot rsync tree: rsync://penguinppc.org/yaboot.

The master location of this document is .

This document is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This document is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

A copy of the GNU General Public License is available as /usr/share/common-licenses/GPL in the Debian GNU/Linux distribution or on the World Wide Web at the . You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. Yaboot's Purpose

Yaboot is a bootloader for PowerPC computers (NewWorld PowerMacs and IBM CHRP). It loads a Linux operating system kernel from an OpenFirmware-accessible filesystem and initiates operation of the kernel. On PowerMacs, an included CHRP script can display a multi-OS boot menu which can launch yaboot or other operating systems. Utilities are included to place yaboot and the associated script on a non-mountable bootstrap partition. System Requirements

Motorola PowerPC processors have been used on at least three different kinds of systems: NuBus, OldWorld PCI, and NewWorld PCI. Nubus systems include the 6100/7100/8100 line of Power Macintoshes. OldWorld systems are most Power Macintoshes with a floppy drive and a PCI bus. Most 603, 603e, 604, and 604e based Power Macintoshes, including the 7200, 7300, 7500, 7600, 8500, 8600, 9500, and 9600 are OldWorld machines. The beige colored G3 systems are also OldWorld.

yaboot will not work on NuBus or OldWorld machines, those will require quik or (for MacOS Pre-9.0.4 only) BootX/miboot.

The NewWorld PowerMacs, for which yaboot is designed, are any PowerMacs in translucent colored plastic cases. That includes all iMacs, iBooks, G4 systems, blue colored G3 systems, and most PowerBooks manufactured in and after 1999. Obtaining Yaboot

Yaboot is included with Debian GNU/Linux installation for PowerPC computers. Updates for Debian may be downloaded via the normal methods, such as apt-get, dselect, or dpkg. Installation of an updated version of yaboot on your system does not change your boot configuration; you must use the included ybin utility to do that.

You can also download yaboot directly from the yaboot home page at . If you download it using MacOS, be sure to download using binary (not text) format, and don't let Stuffit Expander or another utility expand the archive in MacOS.

You can download the precompiled yaboot-binary-X.Y.tar.gz, or the source tarball yaboot-X.Y.tar.gz. To unpack the binary distribution, use the command tar -zxvpf yaboot-X.Y.tar.gz. The components are unpacked into a usr/local/ directory inside the directory where the command was executed.

To make and install from source, first make sure you have a working compiler (gcc) and the make program installed. (If not, download the binary yaboot tarball instead of the source.) Then run the following commands (substitute the actual revision numbers for X and Y):

tar -zxvpf yaboot-X.Y.tar.gz cd yaboot-X.Y make su make install Creating the Bootstrap Partition

Be sure you have reviewed the mac-fdisk Basics page at . If you are creating a new Linux installation, the first partition you create with mac-fdisk should be the bootstrap partition. Just use the mac-fdisk b command to automatically create a bootstrap partition of the proper size and type. If your version of mac-fdisk doesn't include the b command, use:

Command (? for help): C xxxx 800k bootstrap Apple_Bootstrap

(Replace xxxx with the starting block number.) A working tarball of a bootstrap-capable version of mac-fdisk (Debian users already have this version) is also distributed at . To install this, use su - cd / gzip -dc mac-fdisk.tar.gz | tar -xvp

The bootstrap partition only takes 800k of space. If you are adding a bootstrap partition to your existing setup, you may have enough free space on your existing drive without changing other partitions. If not, you could avoid re-partitioning the entire disk by stealing a little space from your swap partition. Or parted would allow you to resize partitions.

The bootstrap partition should end up being partition #2, after the partition map itself but before any other partitions on the disk. You can easily change the order of the partitions in the partition map using the r command (see the mac-fdisk tutorial). In other words, it's not the physical placement of the bootstrap partition that counts, it's the logical order within the partition map. Note, though, if you have an existing system and you shift the partition numbers around, you will need to make the appropriate changes in /etc/fstab.

The reason you want the bootstrap partition as partition #2, is so that it precedes all other partitions in the boot sequence. This helps tremendously to make the entire system more stable, since some OS's are very intrusive in their use of partitions.

When you're finished partitioning, use the p command and make note of the final partition numbers. You will need to know the partition number for the bootstrap partition, the location of your kernel, and if you intend to set up yaboot for multiple OS booting, partition numbers for your alternate OS's.

While it's possible to install yaboot on a mountable HFS /boot partition, that configuration is deprecated, discouraged and completely unsupported. Yabootconfig: Make It Easy

For initial installation on a machine, you can use yabootconfig to first create a yaboot.conf file and then install everything on your bootstrap partition. Yabootconfig reads the running system's /etc/fstab to determine the kernel location, and detects the location of the 800k Apple_Bootstrap partition. The Debian installer uses yabootconfig behind the scenes in the Make Hard Disk Bootable step.

Normally, the initial boot configuration is created while in a ramdisk installer environment, with the system being installed being mounted under /target or /mnt. To run yabootconfig under these conditions, supply the path to the target system with -t or --chroot option. For example: yabootconfig --chroot /target

The yaboot.conf automatically created by yabootconfig will just control booting of the linux system under which it was created. To boot additional OS's or add other options, you will need to edit the yaboot.conf file. Customizing Your Boot Configuration

To customize your yaboot installation, use any text editor such as vi or nano (or nano-tiny in the Debian installer) to edit the yaboot.conf file. If you used yabootconfig to create the initial yaboot.conf, it will already contain a basic configuration to boot the linux system.

The yaboot.conf has numerous options; see the yaboot.conf man page for details. I will briefly cover the most popular items here. The file controls both yaboot operation during tha actual boot, and ybin operation while saving the configuration to the boot partition.

Lines in the file beginning with # are interpreted as comments. Each option or parameter must be specified on a separate line. Don't use any extra spaces within or following parameter definitions. Also, the file must have unix newlines; be sure to save as a unix type file if you create or edit it within MacOS. Linux Style Device Paths

For those unfamiliar with Linux device naming, partition paths are in the form of /dev/xxx# where xxx is the Linux device name and # represents the partition number. Typical Linux device names are: Name Device Type ---- -------------------------------------------------- hda internal ide drive (primary controller, master disk) hdb internal ide drive (primary controller, slave disk) hdc secondary controller, master disk (often used for CD-ROM) hdd secondary controller, slave disk (often used for Zip drive) sda first SCSI disk (SCSI ID address-wise) sdb second SCSI disk scd0 first CD-ROM (or sr0) fd0 first floppy drive fd1 second floppy drive OpenFirmware Device Paths

A utility for finding the OpenFirmware device path corresponding to a given Linux device path is provided: ofpath. ybin uses ofpath internally to convert Linux device names you use in yaboot.conf to OpenFirmware equivalents. Example: ofpath /dev/hda (should return hd:). You can also figure out OpenFirmware device paths yourself, see Recovering From Misconfiguration below. Required Settings

The bootstrap partition is identified with boot=boot-partition, where boot-partition is the Linux-style path to the bootstrap partition. If you followed our partitioning recommendations on your internal hard disk, that would be boot=/dev/hda2.

For PowerMacs, a magicboot line such as magicboot=/usr/local/lib/yaboot/ofboot is also required. Several models cannot execute a straight ELF, and need a CHRP script (which this line in the yaboot.conf makes available).

The partition=, image=, and root= settings (under kernel image settings below) are also required. Boot Menu Options

A CHRP script (ofboot) has been provided which ybin will modify using yaboot.conf settings, to display a very handy multi-OS boot menu.

If you are setting up a multi-OS boot menu, you'll need to identify the partitions where each OS lives. You can use Linux-style or OpenFirmware partition paths. Here are some examples illustrating the possibilities: macos=/dev/hda10 macosx=/dev/hda12 darwin=hd:9 bsd=zip:1 When using macosx=, if you have OSX installed on a UFS partition, then point the macosx to the OSX bootstrap partition, not the UFS root. Don't be tempted to use the OSX bootstrap partition for ybin, however — you still need a separate Apple_Bootstrap partition.

When using bsd=, on the other hand, point to the BSD root partition, not a bsd bootstrap partition. To use bsd=, you also need to have the bsd bootloader (ofwboot) available in /usr/local/lib/yaboot/ when running ybin.

If nothing is selected from the boot menu when it appears, the system launches yaboot to start Linux. To launch another OS when no key is pressed, add a defaultos= line, for example defaultos=macos or defaultos=bsd. Kernel Image Settings

Kernel images to be launched by yaboot can be kept on any partition, in an ext2, ext3, XFS, ReiserFS, or HFS/HFS+ filesystem. Yaboot will need to know the kernel partition number and filesystem path.

The yaboot.conf file has two sections; most options are in the global section at the top of the file, and options pertaining to separate kernel images are grouped together below. Most kernel image options may be specified either globally or locally; a global option is overridden if it is re-specified in a kernel image section. Each kernel image section begins with an image=/ line specifying the filesystem path to that kernel image; the first image=/ line marks the end of the global section.

Yaboot must know the device, partition number, and filesystem path for the kernel image that is to be loaded and started. However, device= is usually not necessary, because if you don't specify it yaboot assumes it will find the kernel on the same device it was booted from, which is quite often true. You should always supply the kernel partition number, for example partition=3, and of course the image path (for example image=/boot/vmlinux ). If your kernel image is at the root level of the partition, don't forget to include the leading slash when specifying the image path (image=vmlinux will probably fail).

It's worth noting that yaboot locates the kernel image within a partition's filesystem without regard to where that partition will eventually be mounted within the Linux root filesystem. So, for example, if you've placed a kernel image or symlink at /boot/vmlinux, but /boot is actually a separate partition on your system, then the image path for yaboot will just be image=/vmlinux.

You must also specify the Linux partition path for the root partition, for example root=/dev/hda3. This parameter is passed to the kernel when it starts up to let it know where its root filesystem is located. Many other options are available to pass additional boot parameters to the kernel (append=), specify initial ramdisk size (ramdisk=), load a ramdisk image (initrd=), and others. Refer to the yaboot.conf man page for details on kernel image options.

Here's a simple but complete example yaboot.conf with one kernel image section: # Where's the bootstrap partition boot=/dev/hda2 # CHRP script spec magicboot=/usr/lib/yaboot/ofboot # Dual boot with MacOS macos=hd:14 # How long to wait at the OS boot menu (seconds) delay=5 # How long to wait at the boot: prompt (tenths of a second) timeout=50 # Globally identified root partition root=/dev/hda3 # The device where the kernel lives device=hd: # Kernel image section begins here # Specify the filesystem path to the kernel image, symlinks are OK image=/vmlinux # Specify the partition number where this path is valid partition=3 # Add a label, you can type this at the boot: prompt to load this kernel label=Linux # Specify the type of root fs mounting, read-only allows fsck to run read-only ## You must run ybin for changes to take effect!!!!!!!

To netboot a kernel image via tftp, use image=/tftpboot/vmlinux (the path on the tftp server) and device=enet:10.0.0.1 (substituting the tftp boot server IP address).

Normally the first image specified in the yaboot.conf will be the image booted if no entry is made at the boot: prompt. To have another image loaded by default, add a default=label line in the global section. Optional and Cool Settings

Yaboot and your multiboot menu can throw a splash of color into your life! Use fgcolor= and bgcolor= lines to set your screen to wake you up in the morning with black, blue, light-blue, green, light-green, cyan, light-cyan, red, light-red, purple, light-purple, brown, light-gray, dark-gray, yellow, and white. Make fgcolor and bgcolor the same if you'd really like a challenge.

Add any or all of enableofboot, enablenetboot, or enablecdboot to add the respective options to your OS boot menu: boot from OpenFirmware, the network, or CDROM.

Use Set delay= (in seconds) to determine how long the multiboot OS menu should wait before booting the default OS. timeout= (in tenths of seconds) to set how long yaboot should wait at the boot: prompt for you to choose a kernel image before booting the first image in the file or the default= image.

Booting password protection is available using a password= line. When you add password=, a password will be required for all booting. Automatic booting is not possible unless a restricted line is added.

If restricted is added in the global section, kernel images defined in yaboot.conf may be booted as long as no arguments are added at the boot: prompt. This is useful for unattended booting, while preventing the instant rootshell problems of console access (though OpenFirmare passwords are also needed to make this really secure, along with locking the case). To boot an undefined image, or any image with additional arguments, a password will be required.

The password= line may either be a plaintext password or an MD5 hash (the same format as the Linux /etc/shadow file). To make an md5 hash use the following perl snippet: $ perl -e 'printf("%s\n", crypt("secret", "\$1\$saltstrg"))' The saltstrg should be a random string, for example one generated by makepasswd --chars=8 Saving Boot Configuration Changes

There are currently three utilities provided to save your boot configuration changes to the boot partition: ybin, mkofboot, and yabootconfig. Ybin copies yaboot, yaboot.conf, and the CHRP script to the boot partition, and then performs the necessary blessing. Mkofboot initializes the bootstrap partition, then runs ybin. And yabootconfig creates a working yaboot.conf and then runs mkofboot. For details and options of these utilities, see the associated man pages or type the utility name followed by --help on the command line. Common Mistakes

The most common mistake made in the usage of yaboot is trying to use it to boot from a mountable partition on a permanent basis. When a PowerPC first starts up, the booting process is started by locating a so-called `blessed' folder. The MacOS places the blessing so that multiple system folders may exist on a partition, but only one of them will be valid for starting up. If the computer is set up to dual boot Linux and MacOS, when MacOS is booted it will unbless any folders which do not contain a valid MacOS system. Then the next time the machine boots, the partition containing the formerly blessed folder will not be bootable.

The utilities provided with yaboot should always be used to set it up on its own bootstrap partition for regular booting needs. The only time you should place yaboot on a mountable partition is for initial installation of Linux and rescue operations. In those cases you can intervene in the normal bootloading process to request a specific file to be executed, and blessed folders are not an issue since this type of booting is not automatic.

After yaboot has been installed, another common mistake is changing the boot configuration file or updating the yaboot software and then failing to re-run the ybin utility to transfer the changed configuration to the boot partition. Booting functions will not be changed unless the changes are saved to the bootstrap partition. If you change your yaboot.conf often, you might want to add a comment line inside the yaboot.conf file to remind yourself to run ybin after making changes. Recovering From Misconfiguration

If you have a problem booting, don't panic. Yaboot can boot any installed Linux kernel and system from the boot: prompt. Resetting the NVRAM

Hold the Command-Option-p-r keys all together at startup to reset all nvram parameters to their factory defaults. Hold the keys until you hear the startup chime two or three times. If the setup recommendations were followed, the yaboot installation will be be the first bootable partition and OpenFirmware will boot it automatically. It should be noted that MacOS settings such as virtual memory, startup disk, and screen resolution will also be reset to their defaults. Loading Yaboot

If a boot: prompt isn't presented, then yaboot isn't being loaded. You can load it manually from OpenFirmware. Holding the Command-Option-o-f keys all together after pressing the power-on key will give you an OpenFirmware prompt 0 > (Command is the key with the cloverleaf and/or apple engraved on it).

At the OF prompt, you will need to use OpenFirmware paths for most of the boot configuration items. You can determine most OpenFirmware paths from the OF prompt using a few OF commands, then construct an OF boot command to directly boot your kernel.

The full OpenFirmware path consists of three parts in the format device-name:partition-number,/filesystem-path

The OF command devalias will list all the device aliases effective on your system. You may see some of these: Name Device Type ---- -------------------------------------------------- hd internal ide drive (primary controller, master disk) ultra1 internal ide drive (primary controller, slave disk) ide0 ide drive (secondary controller, master disk) ide1 ide drive (secondary controller, slave disk) cd CD-ROM zip Zip drive fw FireWire interface fd Floppy drive enet Ethernet interface Append the partition number of the boot partition (in our recommendation, 2) and then follow that with ,yaboot to boot the yaboot file on the boot partition. 0 > boot hd:2,yaboot

Hit return, and yaboot should be loaded and display its boot: prompt. If you don't know the partition number, just start at 2 and work your way up until you hit it. Manually Loading a Kernel Image

Once you have the boot: prompt, you can enter a label defined in your yaboot.conf to boot that kernel image. Or instead of a label, you can enter a full OpenFirmware path. A typical kernel path might be boot: hd:3,/vmlinux To pass parameters to the kernel, add them on to the boot: prompt line after the kernel label or path. You'll need to specify root= as a minimum, but you can add any kernel parameters desired. Here's an example; boot: hd:3,/vmlinux root=/dev/hda3 ro Yaboot as a Temporary Bootloader

It's very convenient for certain tasks like installing a new system the first time without a CD, or rescuing an existing system, to boot a ramdisk system such as an installer directly from files placed on an existing partition.

An example is the Debian installer. It is contained in a floppy-image root.bin file which yaboot can boot directly. A simple yaboot.conf to initialize the ramdisk, yaboot, root.bin, and a kernel image (named linux in this example) are all that is needed. All files are placed at the root level on an existing partition.

The yaboot.conf file for this purpose contains just four lines: image=linux label=install initrd=root.bin initrd-size=8192

If you create yaboot.conf in the MacOS, you must convert it to use Unix newlines (linefeeds only). If you use MacOS newlines (just carriage returns), yaboot will be unable to read the file.

Boot into OpenFirmware, and type at the prompt: 0 > boot hd:xx,yaboot replacing xx with the partition number of the partition where the kernel and yaboot files were placed, followed by a return. At the boot: prompt, type install followed by a return. For More Information

Where's home?

How do I install Debian?

What's Open Firmware?