Yaboot -- PowerPC GNU/Linux OpenFirmware bootloader ------------------------------------------------------------------- Please read the "COPYING" file for licence informations. ------------------------------------------------------------------- Yaboot is an OpenFirmware bootloader for Open Firmware based machines. It is known to work on "NewWorld" class powermacs (iMac and all machines released after it), RS/6000, and possibly other OF based CHRP machines. "OldWorld" PowerMacs (with the built-in MacOS ROM) are not supported. This README serves as a quick-start introduction to yaboot and its installation utilities. For a more complete usage and installation guide, see yaboot-howto.html/index.en.html in the same folder where this README is located, or else inside the doc folder in this directory. For documentation about all the options available, see the man pages (bootstrap, yaboot, yaboot.conf, ybin, mkofboot, ofpath, yabootconfig). Mailing lists ------------------------------------------------------------------- The following mailing lists exist for yaboot: yaboot-announce Announcements regarding yaboot (read-only) yaboot-users User related questions/discussion regarding yaboot yaboot-devel Technical and development discussion regarding yaboot Please see http://lists.penguinppc.org/LISTNAME where LISTNAME is one of the above named lists. ------------------------------------------------------------------- Bootloader Installation Utilities ybin, mkofboot, ofpath, yabootconfig Written by Ethan Benson ------------------------------------------------------------------- ybin (YaBoot INstaller) and mkofboot ------------------------------------------------------------------- ybin is a lilo/quik style bootloader installer for PowerPC based machines which require a bootstrap partition rather than a traditional bootblock (i.e. all `NewWorld' Macintoshes). When ybin is configured correctly you can simply type ybin at the command line as root, and the bootloader and its configuration file will be installed or updated on the bootstrap partition without any further user intervention. ybin also supports IBM PowerPC hardware which requires a slightly different bootstrap partition setup. For these machines, ybin uses dd to write yaboot directly to the partition instead of copying it to a filesystem on the partition. ybin will add the requisite .note section to yaboot prior to installation (IBM CHRP only). mkofboot is a companion script (actually a symlink to ybin) which initializes the bootstrap partition prior to running ybin to install the bootloader on it. mkofboot will confirm you want to continue before proceeding unless called with the -f or --force switch. This is in contrast to ybin, which is non destructive except that it overwrites any existing yaboot files (yaboot and yaboot.conf) at the root level of the bootstrap filesystem. mkofboot and ybin both refer to the same configuration file (normally yaboot.conf) to determine where the bootstrap files will be placed. IMPORTANT: The bootstrap partition should never be mounted anywhere on your filesystem, ybin and mkofboot will check if it is and refuse to operate on it if it is mounted. It is not necessary to keep anything but the boot loader on the bootstrap partition, yaboot will load the kernel from your root partition (which can be an ext2/3, XFS, or ReiserFS filesystem). Do not mount the bootstrap partition on top of /boot. ybin can update a bootstrap filesystem either on a block device or in an ordinary file (as in an image of a filesystem.) NOTE: You must have a secure mktemp program otherwise ybin will be vulnerable to race conditions. Debian's mktemp qualifies I don't know about the other distributions, you have been warned. The temp file is created in /tmp by default but ybin will respect the $TMPDIR environment variable. ofpath ------------------------------------------------------------------- The included ofpath utility can usually determine the OpenFirmware device path that corresponds with a unix device node in /dev/. Ybin uses this utility to find the path to the bootstrap partition and to any defined macos/macosx partitions. ofpath is based on the utility `show_of_path.sh' written by Olaf Hering. NOTE: ofpath may not work with all SCSI cards/drivers. IMPORTANT: ofpath will NOT work on NewWorld Powermacs if the machine was booted with BootX. yabootconfig ------------------------------------------------------------------- Yabootconfig creates a default configuration file and then runs mkofboot to complete the bootloader installation. yabootconfig reads the running system's /etc/fstab to determine the kernel location, and detects the location of the 800k Apple_Bootstrap partition. It will also find IBM CHRP bootstrap partitions (type 0x41 PReP Boot). Yaboot.conf Configuration File ------------------------------------------------------------------- yaboot.conf configuration file settings are covered in detail in `man yaboot.conf'. Avoid the use of spaces in the config file, except in comment lines or inside quotes. Here are the essential settings. boot= Example: boot=/dev/hda2 This required setting defines the bootstrap partition device. It can also be a regular file if you are creating a filesystem image for some reason. The default config file has this set to ``unconfigured'' which will cause ybin to complain about you not reading the docs, it is the only option you should need to change for ybin to work. Be sure you include the partition number at the end, it should never be something like /dev/hda. install= Example: install=/usr/lib/yaboot/yaboot or /usr/local/lib/yaboot/yaboot The full pathname to the yaboot OpenFirmware executable file. The default is shown above. This file will be copied to the root level of the bootstrap partition. Note: If you are installing an alternative bootloader, its filename will be changed to yaboot when it is copied (to match what the first stage bootloader expects to be loading). partition= Example: partition=3 The partition number on which the kernel image is located. By default, this partition is assumed to be on the same device from which yaboot was loaded. If needed, device= can be used to explicitly specify the device. image= Examples: image=/vmlinux or image=/boot/vmlinux-2.2.19-pmac The path to the image from the root level of the partition (remember that yaboot is unaware of mountpoints). Don't forget to include the leading slash when specifying the image path (image=vmlinux will probably fail). root= Example: root=/dev/hda3 The Linux device name for the root partition. This parameter is passed to the kernel when it starts up to let it know where its root filesystem is located. Refer to the yaboot.conf man page for details on kernel image options such as append=, initrd=, and initrd-size=. magicboot= (same as -m or --magicboot) Example: /usr/local/lib/yaboot/ofboot Identifies the first stage loader. The example shown is the default. The ofboot script it refers to is included with and configured automatically by ybin from options in /etc/yaboot.conf. The magicboot= can be the full pathname to any OF CHRP script file. Since some newer OpenFirmware implementations appear to require a CHRP script, the magicboot= setting is highly recommended. If you don't include magicboot=, then yaboot itself will be the active bootfile. magicboot= cannot be used on IBM CHRP. Boot Menu Options ------------------------------------------------------------------- The following options work only if you have specified the magicboot= option. Each option specifies an OpenFirmware or unix device path to another operating system's boot partition. When you define one of these options you will be presented with a simple menu at bootup allowing you to hit `l' to boot GNU/Linux or another letter to boot the other OS (see below). These letters are typed without a shift key (the boot menu is case sensitive). When set to a unix device node such as /dev/hda11 then ybin will use the ofpath utility to determine the OpenFirmware device path. Option Letter Operating System Type --------- ------ --------------------------------------------- bsd= b NetBSD or OpenBSD root partition (you must have the BSD ofwboot bootloader installed at /usr/local/lib/yaboot/ofwboot) macos= m MacOS 8.* or 9.* bootable partition macosx= x MacOS X boot partition (also see brokenosx) darwin= d Darwin boot partition enablecdboot c Boot from the CDROM drive enablenetboot n Boot from the network enableofboot o Display an OpenFirmware prompt defaultos= The default OS to load (linux, bsd, macos, darwin or macosx. brokenosx This option causes the menu entry for MacOSX to execute \System\Library\CoreServices\BootX from the macosx=device instead of the usual \\:tbxi. This is necessary if OSX is installed onto an HFS+ filesystem instead of UFS. When OSX is installed on an HFS+ filesystem MacOS will mount and debless the OSX partition. Add this option if the OSX menu entry breaks after booting MacOS. You should not use this option if OSX is installed on a UFS filesystem, for UFS installs you specify the OSX bootstrap partition which is protected against MacOS. delay= Example: delay=5 The time in seconds that the first stage ofboot loader will wait for you to choose a letter before booting the default OS defined in defaultos=. If not set, the value of timeout= (converted to seconds) will be used. Colors ------------------------------------------------------------------- fgcolor=string Specifies the foreground (text) color used by yaboot and the multiboot menu. Available colors are: black, blue, light-blue, green, light-green, cyan, light-cyan, red, light-red, purple, light- purple, brown, light-gray, dark-gray, yellow, and white. The default is white. bgcolor=string Specifies the background color used by yaboot and the multiboot menu. Available colors are the same as fgcolor. The default is black. =========================================================================== Copyright (C) 2000, 2001, 2002, 2003 Ethan Benson This program is free software; you can 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 of the License, or (at your option) any later version. This program 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. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ===========================================================================