README - yaboot - Rivoreo Source Code Repositories

 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 <erbenson@alaska.net>
 -------------------------------------------------------------------

 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 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.

 ===========================================================================
	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 <erbenson@alaska.net>
	-------------------------------------------------------------------

	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 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.

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