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-users      User related questions/discussion regarding yaboot
yaboot-devel      Technical and development discussion regarding yaboot

Please see https://ozlabs.org/mailman/listinfo/LISTNAME where LISTNAME is one
of the above named lists.

http://yaboot.ozlabs.org/

-------------------------------------------------------------------
Bootloader Installation Utilities  
ybin, mkofboot, ofpath, yabootconfig
Written by Ethan Benson <[email protected]>
-------------------------------------------------------------------

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.

===========================================================================