1 <!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
4 file, directory, device == file
5 program, command == prgn
9 key input == em, example for longer ones
18 HOWTO-Booting with Yaboot on PowerPC
21 <name>Chris Tillman</name>
23 <version>Version 1.00, Oct 28 2001</version>
25 This document contains installation and usage instructions for
26 <prgn>yaboot</prgn>, the GNU/Linux PowerPC bootloader.
30 This document may be distributed and modified under the terms of the
31 GNU General Public License.
32 © 1998–2001 Chris Tillman
35 This document is free software; you may redistribute it and/or modify it
36 under the terms of the GNU General Public License as published by the
37 Free Software Foundation; either version 2, or (at your option) any
40 This document is distributed in the hope that it will be useful, but
41 <em>without any warranty</em>; without even the implied warranty of
42 merchantability or fitness for a particular purpose. See the GNU
43 General Public License for more details.
46 A copy of the GNU General Public License is available as
47 <file>/usr/share/common-licenses/GPL</file> in the Debian GNU/Linux
48 distribution or on the World Wide Web at the <url
49 id="http://www.gnu.org/copyleft/gpl.html" name="GNU website">. You can also
50 obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place
51 - Suite 330, Boston, MA 02111-1307, USA.
54 <chapt>Yaboot's Purpose
57 Yaboot is a bootloader for PowerPC computers (NewWorld PowerMacs and IBM
58 CHRP). It loads a Linux operating system kernel from an
59 OpenFirmware-accessible filesystem and initiates operation of the kernel. On
60 PowerMacs, an included CHRP script can display a multi-OS boot menu which
61 can launch <prgn>yaboot</prgn> or other operating systems. Utilities are
62 included to place <prgn>yaboot</prgn> and the associated script on a
63 non-mountable bootstrap partition.
66 <chapt>System Requirements
68 Motorola PowerPC processors have been used on at least three different
69 kinds of systems: NuBus, OldWorld PCI, and NewWorld PCI. Nubus systems
70 include the 6100/7100/8100 line of Power Macintoshes. OldWorld systems
71 are most Power Macintoshes with a floppy drive and a PCI bus. Most
72 603, 603e, 604, and 604e based Power Macintoshes, including the 7200,
73 7300, 7500, 7600, 8500, 8600, 9500, and 9600 are OldWorld
74 machines. The beige colored G3 systems are also OldWorld.
77 <em><prgn>yaboot</prgn> will not work on NuBus or OldWorld machines</em>,
78 those will require <prgn>quik</prgn> or (for MacOS Pre-9.0.4 only)
79 <prgn>BootX/miboot</prgn>.
82 The NewWorld PowerMacs, for which <prgn>yaboot</prgn> is designed, are
83 any PowerMacs in translucent colored plastic cases. That includes all
84 iMacs, iBooks, G4 systems, blue colored G3 systems, and most
85 PowerBooks manufactured in and after 1999.
88 <chapt>Obtaining Yaboot
91 Yaboot is included with Debian GNU/Linux installation for PowerPC computers.
92 Updates for Debian may be downloaded via the normal methods, such as
93 <prgn>apt-get</prgn>, <prgn>dselect</prgn>, or <prgn>dpkg</prgn>.
94 Installation of an updated version of <prgn>yaboot</prgn> on your system
95 does not change your boot configuration; you must use the included
96 <prgn>ybin</prgn> utility to do that.
100 You can also download <prgn>yaboot</prgn> directly from the
101 <prgn>yaboot</prgn> home page at <url
102 id="http://penguinppc.org/projects/yaboot">. If you download it using MacOS,
103 be sure to download using <em>binary</em> (not text) format, and don't let
104 Stuffit Expander or another utility expand the archive in MacOS.
108 You can download the precompiled <file>yaboot-binary-X.Y.tar.gz</file>, or
109 the source tarball <file>yaboot-X.Y.tar.gz</file>. To unpack the binary
110 distribution, use the command <tt>tar -zxvpf yaboot-X.Y.tar.gz</tt>. The
111 components are unpacked into a <file>usr/local/</file> directory inside the
112 directory where the command was executed.
116 To make and install from source, first make sure you have a working compiler
117 (<prgn>gcc</prgn>) and the <prgn>make</prgn> program installed. (If
118 not, download the binary yaboot tarball instead of the source.) Then run the
119 following commands (substitute the actual revision numbers for X and Y):
123 tar -zxvpf yaboot-X.Y.tar.gz
130 <chapt>Creating the Bootstrap Partition
133 Be sure you have reviewed the <prgn>mac-fdisk</prgn> Basics page at <url
134 id="http://penguinppc.org/projects/yaboot/doc/mac-fdisk-basics.shtml">. If
135 you are creating a new Linux installation, the first partition you create
136 with <prgn>mac-fdisk</prgn> should be the bootstrap partition. Just use the
137 <prgn>mac-fdisk</prgn> <tt>b</tt> command to automatically create a
138 bootstrap partition of the proper size and type. If your version of
139 <prgn>mac-fdisk</prgn> doesn't include the <tt>b</tt> command, use:
143 Command (? for help): C xxxx 800k bootstrap Apple_Bootstrap
147 (Replace xxxx with the starting block number.) A working tarball of a
148 bootstrap-capable version of mac-fdisk (Debian users already have this
149 version) is also distributed at <url
150 id="http://penguinppc.org/projects/eb/">. To install this, use
155 gzip -dc mac-fdisk.tar.gz | tar -xvp
159 The bootstrap partition only takes 800k of space. If you are adding a
160 bootstrap partition to your existing setup, you may have enough free
161 space on your existing drive without changing other partitions. If
162 not, you could avoid re-partitioning the entire disk by stealing a
163 little space from your swap partition. Or <prgn>parted</prgn> would allow
164 you to resize partitions.
168 The bootstrap partition should end up being partition #2, after the
169 partition map itself but before any other partitions on the disk. You can
170 easily change the order of the partitions in the partition map using the
171 <tt>r</tt> command (see the <prgn>mac-fdisk</prgn> tutorial). In other
172 words, it's not the physical placement of the bootstrap partition that
173 counts, it's the logical order within the partition map. Note, though, if
174 you have an existing system and you shift the partition numbers around, you
175 will need to make the appropriate changes in <file>/etc/fstab</file>.
179 The reason you want the bootstrap partition as partition #2, is so
180 that it precedes all other partitions in the boot sequence. This helps
181 tremendously to make the entire system more stable, since some OS's
182 are very intrusive in their use of partitions.
186 When you're finished partitioning, use the <tt>p</tt> command and make note
187 of the final partition numbers. You will need to know the partition
188 number for the bootstrap partition, the location of your kernel, and
189 if you intend to set up <prgn>yaboot</prgn> for multiple OS booting, partition
190 numbers for your alternate OS's.
194 While it's possible to install <prgn>yaboot</prgn> on a mountable HFS
195 <file>/boot</file> partition, that configuration is deprecated, discouraged
196 and completely unsupported.
198 <chapt>Yabootconfig: Make It Easy
201 For initial installation on a machine, you can use <prgn>yabootconfig</prgn>
202 to first create a <file>yaboot.conf</file> file and then install everything
203 on your bootstrap partition. Yabootconfig reads the running system's
204 <file>/etc/fstab</file> to determine the kernel location, and detects the
205 location of the 800k Apple_Bootstrap partition. The Debian installer uses
206 <prgn>yabootconfig</prgn> behind the scenes in the Make Hard Disk Bootable
211 Normally, the initial boot configuration is created while in a ramdisk
212 installer environment, with the system being installed being mounted under
213 <file>/target</file> or <file>/mnt</file>. To run <prgn>yabootconfig</prgn>
214 under these conditions, supply the path to the target system with -t or
215 --chroot option. For example: <tt>yabootconfig --chroot /target</tt>
219 The <file>yaboot.conf</file> automatically created by
220 <prgn>yabootconfig</prgn> will just control booting of the linux system
221 under which it was created. To boot additional OS's or add other options,
222 you will need to edit the <file>yaboot.conf</file> file.
225 <chapt>Customizing Your Boot Configuration
228 To customize your <prgn>yaboot</prgn> installation, use any text editor such
229 as <prgn>vi</prgn> or <prgn>nano</prgn> (or <prgn>nano-tiny</prgn> in the
230 Debian installer) to edit the <file>yaboot.conf</file> file. If you used
231 <prgn>yabootconfig</prgn> to create the initial <file>yaboot.conf</file>, it
232 will already contain a basic configuration to boot the linux system.
236 The <file>yaboot.conf</file> has numerous options; see the
237 <file>yaboot.conf</file> man page for details. I will briefly cover the most
238 popular items here. The file controls both <prgn>yaboot</prgn> operation
239 during tha actual boot, and <prgn>ybin</prgn> operation while saving the
240 configuration to the boot partition.
244 Lines in the file beginning with <tt>#</tt> are interpreted as comments. Each
245 option or parameter must be specified on a separate line. Don't use
246 any extra spaces within or following parameter definitions. Also, the
247 file must have unix newlines; be sure to save as a unix type file
248 if you create or edit it within MacOS.
251 <sect>Linux Style Device Paths
254 For those unfamiliar with Linux device naming, partition paths are in
255 the form of <tt>/dev/xxx#</tt> where xxx is the Linux device name and #
256 represents the partition number. Typical Linux device names are:
260 ---- --------------------------------------------------
261 hda internal ide drive (primary controller, master disk)
262 hdb internal ide drive (primary controller, slave disk)
263 hdc secondary controller, master disk (often used for CD-ROM)
264 hdd secondary controller, slave disk (often used for Zip drive)
265 sda first SCSI disk (SCSI ID address-wise)
267 scd0 first CD-ROM (or sr0)
268 fd0 first floppy drive
269 fd1 second floppy drive
273 <sect>OpenFirmware Device Paths
275 A utility for finding the OpenFirmware device path corresponding to a
276 given Linux device path is provided: <prgn>ofpath</prgn>. <prgn>ybin</prgn>
277 uses <prgn>ofpath</prgn>
278 internally to convert Linux device names you use in <file>yaboot.conf</file> to
279 OpenFirmware equivalents. Example: <tt>ofpath /dev/hda</tt> (should return hd:).
280 You can also figure out OpenFirmware device paths yourself, see
281 Recovering From Misconfiguration below.
283 <sect>Required Settings
286 The bootstrap partition is identified with <tt>boot=boot-partition</tt>,
287 where boot-partition is the Linux-style path to the bootstrap partition. If
288 you followed our partitioning recommendations on your internal hard disk,
289 that would be <tt>boot=/dev/hda2</tt>.
293 For PowerMacs, a magicboot line such as
294 <tt>magicboot=/usr/local/lib/yaboot/ofboot</tt> is also required. Several
295 models cannot execute a straight ELF, and need a CHRP script (which this
296 line in the <file>yaboot.conf</file> makes available).
300 The <tt>partition=</tt>, <tt>image=</tt>, and <tt>root=</tt> settings (under
301 kernel image settings below) are also required.
303 <sect>Boot Menu Options
306 A CHRP script (<file>ofboot</file>) has been provided which
307 <prgn>ybin</prgn> will modify using <file>yaboot.conf</file> settings, to
308 display a very handy multi-OS boot menu.
312 If you are setting up a multi-OS boot menu, you'll need to identify the
313 partitions where each OS lives. You can use Linux-style or OpenFirmware
314 partition paths. Here are some examples illustrating the possibilities:
323 When using <tt>macosx=</tt>, if you have OSX installed on a UFS partition,
324 then point the macosx to the OSX bootstrap partition, not the UFS root.
325 Don't be tempted to use the OSX bootstrap partition for <prgn>ybin</prgn>,
326 however — you still need a separate Apple_Bootstrap partition.
330 When using <tt>bsd=</tt>, on the other hand, point to the BSD root
331 partition, not a bsd bootstrap partition. To use <tt>bsd=</tt>, you also
332 need to have the bsd bootloader (ofwboot) available in
333 <file>/usr/local/lib/yaboot/</file> when running <prgn>ybin</prgn>.
337 If nothing is selected from the boot menu when it appears, the system
338 launches <prgn>yaboot</prgn> to start Linux. To launch another OS when no
339 key is pressed, add a <tt>defaultos=</tt> line, for example
340 <tt>defaultos=macos</tt> or <tt>defaultos=bsd</tt>.
343 <sect>Kernel Image Settings
345 Kernel images to be launched by yaboot can be kept on any partition,
346 in an ext2, ext3, XFS, ReiserFS, or HFS/HFS+ filesystem. Yaboot will
347 need to know the kernel partition number and filesystem path.
351 The <file>yaboot.conf</file> file has two sections; most options are in the
352 global section at the top of the file, and options pertaining to separate
353 kernel images are grouped together below. Most kernel image options may be
354 specified either globally or locally; a global option is overridden if it is
355 re-specified in a kernel image section. Each kernel image section begins
356 with an <tt>image=/</tt> line specifying the filesystem path to that kernel
357 image; the first <tt>image=/</tt> line marks the end of the global section.
361 Yaboot must know the device, partition number, and filesystem path for the
362 kernel image that is to be loaded and started. However, <tt>device=</tt> is
363 usually not necessary, because if you don't specify it <prgn>yaboot</prgn>
364 assumes it will find the kernel on the same device it was booted from, which
365 is quite often true. You should always supply the kernel partition number,
366 for example <tt>partition=3</tt>, and of course the image path (for example
367 <tt>image=/boot/vmlinux</tt> ). If your kernel image is at the root level of
368 the parttion, don't forget to include the leading slash when specifying the
369 image path (<tt>image=vmlinux</tt> will probably fail).
373 It's worth noting that <prgn>yaboot</prgn> locates the kernel image within a
374 partition's filesystem without regard to where that partition will
375 eventually be mounted within the Linux root filesystem. So, for example, if
376 you've placed a kernel image or symlink at /boot/vmlinux, but /boot is
377 actually a separate partition on your system, then the image path for
378 <prgn>yaboot</prgn> will just be <tt>image=/vmlinux</tt>.
382 You must also specify the Linux partition path for the root partition, for
383 example <tt>root=/dev/hda3</tt>. This parameter is passed to the kernel when
384 it starts up to let it know where its root filesystem is located. Many other
385 options are available to pass additional boot parameters to the kernel
386 (<tt>append=</tt>), specify initial ramdisk size (<tt>ramdisk=</tt>), load a
387 ramdisk image (<tt>initrd=</tt>), and others. Refer to the yaboot.conf man
388 page for details on kernel image options.
392 Here's a simple but complete example <file>yaboot.conf</file> with one
393 kernel image section:
396 # Where's the bootstrap partition
399 magicboot=/usr/lib/yaboot/ofboot
400 # Dual boot with MacOS
402 # How long to wait at the OS boot menu (seconds)
405 # How long to wait at the boot: prompt (tenths of a second)
407 # Globally identified root partition
409 # The device where the kernel lives
412 # Kernel image section begins here
413 # Specify the filesystem path to the kernel image, symlinks are OK
415 # Specify the partition number where this path is valid
417 # Add a label, you can type this at the boot: prompt to load this kernel
419 # Specify the type of root fs mounting, read-only allows fsck to run
422 ## You must run ybin for changes to take effect!!!!!!!
426 To netboot a kernel image via tftp, use <tt>image=/tftpboot/vmlinux</tt> (the
427 path on the tftp server) and <tt>device=enet:10.0.0.1</tt>
428 (substituting the tftp boot server IP address).
432 Normally the first image specified in the <file>yaboot.conf</file> will be the
433 image booted if no entry is made at the boot: prompt. To have another
434 image loaded by default, add a <tt>default=label</tt> line in the global
438 <sect>Optional and Cool Settings
441 Yaboot and your multiboot menu can throw a splash of color into your life!
442 Use <tt>fgcolor=</tt> and <tt>bgcolor=</tt> lines to set your screen to wake
443 you up in the morning with black, blue, light-blue, green, light-green,
444 cyan, light-cyan, red, light-red, purple, light-purple, brown, light-gray,
445 dark-gray, yellow, and white. Make fgcolor and bgcolor the same if you'd
446 really like a challenge.
450 Add any or all of enableofboot, enablenetboot, or enablecdboot to add
451 the respective options to your OS boot menu: boot from OpenFirmware,
452 the network, or CDROM.
456 Use Set delay= (in seconds) to determine how long the multiboot OS menu
457 should wait before booting the default OS. <tt>timeout=</tt> (in tenths of
458 seconds) to set how long yaboot should wait at the boot: prompt for
459 you to choose a kernel image before booting the first image in the
460 file or the <tt>default=</tt> image.
464 Booting password protection is available using a <tt>password=</tt> line.
465 When you add <tt>password=</tt>, a password will be required for all booting.
466 Automatic booting is not possible unless a <tt>restricted</tt> line is added.
470 If <tt>restricted</tt> is added in the global section, kernel images defined
471 in <file>yaboot.conf</file> may be booted as long as no arguments are added
472 at the boot: prompt. This is useful for unattended booting, while preventing
473 the instant rootshell problems of console access (though OpenFirmare
474 passwords are also needed to make this really secure, along with locking the
475 case). To boot an undefined image, or any image with additional arguments, a
476 password will be required.
480 The <tt>password=</tt> line may either be a plaintext password or an MD5
481 hash (the same format as the Linux <file>/etc/shadow</file> file). To make an
482 md5 hash use the following perl snippet:
485 $ perl -e 'printf("%s\n", crypt("secret", "\$1\$saltstrg"))'
487 The saltstrg should be a random string, for example one generated by
494 <chapt>Saving Boot Configuration Changes
497 There are currently three utilities provided to save your boot configuration
498 changes to the boot partition: <prgn>ybin</prgn>, <prgn>mkofboot</prgn>, and
499 <prgn>yabootconfig</prgn>. Ybin copies <prgn>yaboot</prgn>,
500 <file>yaboot.conf</file>, and the CHRP script to the boot partition, and
501 then performs the necessary blessing. Mkofboot initializes the bootstrap
502 partition, then runs <prgn>ybin</prgn>. And <prgn>yabootconfig</prgn>
503 creates a working <file>yaboot.conf</file> and then runs
504 <prgn>mkofboot</prgn>. For details and options of these utilities, see the
505 associated man pages or type the utility name followed by --help on the
509 <chapt>Common Mistakes
512 The most common mistake made in the usage of <prgn>yaboot</prgn> is trying
513 to use it to boot from a mountable partition on a permanent basis. When a
514 PowerPC first starts up, the booting process is started by locating a
515 so-called `blessed' folder. The MacOS places the blessing so that multiple
516 system folders may exist on a partition, but only one of them will be valid
517 for starting up. If the computer is set up to dual boot Linux and MacOS,
518 when MacOS is booted it will unbless any folders which do not contain a
519 valid MacOS system. Then the next time the machine boots, the partition
520 containing the formerly blessed folder will not be bootable.
524 The utilities provided with <prgn>yaboot</prgn> should always be used to set
525 it up on its own bootstrap partition for regular booting needs. The only
526 time you should place <prgn>yaboot</prgn> on a mountable partition is for
527 initial installation of Linux and rescue operations. In those cases you can
528 intervene in the normal bootloading process to request a specific file to be
529 executed, and blessed folders are not an issue since this type of booting is
534 After <prgn>yaboot</prgn> has been installed, another common mistake is
535 changing the boot configuration file or updating the <prgn>yaboot</prgn>
536 software and then failing to re-run the <prgn>ybin</prgn> utility to
537 transfer the changed configuration to the boot partition. Booting functions
538 will not be changed unless the changes are saved to the bootstrap partition.
539 If you change your <file>yaboot.conf</file> often, you might want to add a
540 comment line inside the <file>yaboot.conf</file> file to remind yourself to
541 run <prgn>ybin</prgn> after making changes.
544 <chapt>Recovering From Misconfiguration
547 If you have a problem booting, don't panic. Yaboot can boot any
548 installed Linux kernel and system from the boot: prompt.
550 <sect>Resetting the NVRAM
553 Hold the Command-Option-p-r keys all together at startup to reset all nvram
554 parameters to their factory defaults. Hold the keys until you hear the
555 startup chime two or three times. If the setup recommendations were
556 followed, the <prgn>yaboot</prgn> installation will be be the first bootable
557 partition and OpenFirmware will boot it automatically. It should be noted
558 that MacOS settings such as virtual memory, startup disk, and screen
559 resolution will also be reset to their defaults.
565 If a <tt>boot:</tt> prompt isn't presented, then <prgn>yaboot</prgn> isn't
566 being loaded. You can load it manually from
567 OpenFirmware. Holding the Command-Option-o-f keys all together after
568 pressing the power-on key will give you an OpenFirmware prompt
573 (Command is the key with the cloverleaf and/or apple engraved on it).
577 At the OF prompt, you will need to use OpenFirmware paths for most of
578 the boot configuration items. You can determine most OpenFirmware
579 paths from the OF prompt using a few OF commands, then construct an OF
580 boot command to directly boot your kernel.
584 The full OpenFirmware path consists of three parts in the format
587 device-name:partition-number,/filesystem-path
592 The OF command devalias will list all the device aliases effective on
593 your system. You may see some of these:
596 ---- --------------------------------------------------
597 hd internal ide drive (primary controller, master disk)
598 ultra1 internal ide drive (primary controller, slave disk)
599 ide0 ide drive (secondary controller, master disk)
600 ide1 ide drive (secondary controller, slave disk)
603 fw FireWire interface
605 enet Ethernet interface
608 Append the partition number of the boot partition (in our recommendation, 2)
609 and then follow that with <tt>,yaboot</tt> to boot the <prgn>yaboot</prgn>
610 file on the boot partition.
617 Hit return, and <prgn>yaboot</prgn> should be loaded and display its
618 <file>boot:</file> prompt. If you don't know the partition number, just
619 start at 2 and work your way up until you hit it.
621 <sect>Manually Loading a Kernel Image
624 Once you have the boot: prompt, you can enter a label defined in your
625 <file>yaboot.conf</file> to boot that kernel image. Or instead of a label,
626 you can enter a full OpenFirmware path. A typical kernel path might be
632 To pass parameters to the kernel, add them on to the <tt>boot:</tt> prompt
633 line after the kernel label or path. You'll need to specify <tt>root=</tt>
634 as a minimum, but you can add any kernel parameters desired. Here's an
638 boot: hd:3,/vmlinux root=/dev/hda3 ro
642 <chapt>Yaboot as a Temporary Bootloader
644 It's very convenient for certain tasks like installing a new system
645 the first time without a CD, or rescuing an existing system, to boot a
646 ramdisk system such as an installer directly from files placed on an
651 An example is the Debian installer. It is contained in a floppy-image
652 root.bin file which <prgn>yaboot</prgn> can boot directly. A simple
653 <file>yaboot.conf</file> to initialize the ramdisk, yaboot, root.bin, and a
654 kernel image (named linux in this example) are all that is needed. All files
655 are placed at the root level on an existing partition.
659 The <file>yaboot.conf</file> file for this purpose contains just
669 If you create <file>yaboot.conf</file> in the MacOS, you must convert
670 it to use Unix newlines (linefeeds only). If you use MacOS newlines
671 (just carriage returns), <prgn>yaboot</prgn> will be unable to read the file.
674 Boot into OpenFirmware, and type at the prompt:
676 0 > boot hd:xx,yaboot
679 replacing xx with the partition number of the partition where the
680 kernel and <prgn>yaboot</prgn> files were placed, followed by a return. At the
681 boot: prompt, type <em>install</em> followed by a return.
684 <chapt>For More Information
689 <item> <url id="http://penguinppc.org/projects/yaboot/" name="Yaboot Home">
694 How do I install Debian?
696 <item> <url id="http://mirrors.kernel.org/debian/dists/woody/main/disks-powerpc/current/doc/install.en.html"
697 name="Installing Debian GNU/Linux 3.0 For PowerPC">
698 <item> <url id="http://www.debian.org/releases/stable/powerpc/install" name="Installing Debian GNU/Linux 2.2 For PowerPC">
703 What's Open Firmware?
705 <item> <url id="http://developer.apple.com/technotes/tn/tn1044.html">
706 <item> <url id="http://developer.apple.com/technotes/tn/tn1061.html">
707 <item> <url id="http://developer.apple.com/technotes/tn/tn1062.html">
708 <item> <url id="http://developer.apple.com/technotes/tn/tn1167.html">
717 <!-- Keep this comment at the end of the file
722 sgml-namecase-general:t
723 sgml-general-insert-case:lower
724 sgml-minimize-attributes:max
725 sgml-always-quote-attributes:t
728 sgml-parent-document:nil
730 sgml-exposed-tags:nil
731 sgml-local-catalogs:nil
732 sgml-local-ecat-files:nil