README

Yaboot  -- PowerPC GNU/Linux OpenFirmware bootloader
--------------------------------------------

Please read the "COPYING" file for licence informations.

   Copyright (C) 2000 Benjamin Herrenschmidt

   portions based on "poof"

   Copyright (C) 1999 Marius Vollmer

   portions based on "quik"
   
   Copyright (C) 1996 Paul Mackerras.

   PPC64 support & Misc fixes by Peter Bergner, David Engebretsen
   

--------------------------------------------

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 old MacOS ROM buit-in) are not
supported.

ybin Written by Ethan Benson <erbenson@alaska.net>

ybin (YaBoot INstaller) was created so that there could be a lilo/quik
style bootloader installer for PowerPC based machines which require
bootstrap partitions rather then a traditional bootblock (ie all
`NewWorld' Macintoshes).  It is designed to install yaboot, an
OpenFirmware bootloader for GNU/Linux written by Benjamin
Herrenschmidt.  When ybin is configured correctly you can simply type
ybin, and the bootloader and its configuration file will be
installed/updated on the bootstrap partition without any further user
intervention.

ybin also supports IBM PowerPC hardware which requires a slightly
different bootstrap partition setup, yaboot is directly dded to the
partition instead of copied to a filesystem on the partition.  For
these machines add fstype=raw to your /etc/yaboot.conf.  See
examples/yaboot.conf.rs6k for an example configuration.

Both ybin and mkofboot are shell scripts (compatible with ash, sh,
bash).  These are the first real scripts that I have written with any
sort of complexity, so don't be too brutal if they are ugly and
inefficient. ;-) Suggestions on how to do things better are welcome.

ybin can update a bootstrap filesystem either on a block device or a
ordinary file (as in a image of a filesystem.) 

Unless you use the usemount (or --mount) option it does not
necessarily need to be run as root, but it probably will, unless you
changed device permissions or are only updating an image.

mkofboot is a companion script (actually a symlink to ybin) to
initialise the bootstrap partition and then run ybin to install the
bootloader on it.  It uses the same configuration file as ybin to find
the device to use. It will validate the configuration file before
actually creating the filesystem. It will also confirm you want to
continue before proceeding unless called with the -f or --force
switch.

(>= 0.18): ofpath utility now included which can usually find the
OpenFirmware device path that corresponds with a unix device node in
/dev/.  Ybin will use this utility automatically to find the path to
the bootstrap partition and to any defined macos/macosx partitions.
NOTE: ofpath may not work with all SCSI cards/drivers. 
IMPORTANT: ofpath will NOT work if you boot your machine with BootX.

ofpath is based on the utility `show_of_path.sh' written by Olaf
Hering. 

(>= 0.20): ybin will now check for the new nvsetenv that is
compatible with Newworld PowerMacs, and if found it will automatically
update the boot-device variable in nvram to that of the bootstrap
partition.  This feature can be disabled by passing the --nonvram
switch to ybin or by adding `nonvram' to /etc/yaboot.conf.  This
feature works in both the userland and `usemount' modes.  In userland
mode ybin sets the boot-device variable to <path>,\\:tbxi, for example
if your bootstrap partition is /dev/hda2 boot-device will be set to
hd:2,\\:tbxi, in `usemount' mode it would be set to hd:2,ofboot (or
hd:2,yaboot if you don't have magicboot= set.)

NEW (>= 0.31): The ofboot script now has configurable colors, you can
change the foreground (text) and background colors it will use with
the fgcolor= and bgcolor= options in yaboot.conf, see below for
details.  Yaboot 1.0 and later also supports these options. 

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 its mounted.  It is not necessary to keep anything
but the boot loader on the bootstrap partition, yaboot will load the
kernel from your ext2fs root partition so do not mount the bootstrap
partition on top of /boot.

ybin now fully supports command line switches, see ybin --help for
information on these.

NEW: ybin can now generate a basic yaboot.conf on the fly that you may
customise with command line options:

      --device               yaboot auto configuration: sets the OF boot device
                               default: hd:
      --partition            yaboot auto configuration: sets the partition 
                               number of the root partition. default: 3
      --timeout              yaboot auto configuration: sets the time yaboot
                               will wait for user input before booting default
                               image default: 20 (2 seconds)
      --image                yaboot auto configuration: sets the path to the 
                               kernel image. default: /vmlinux
      --label                yaboot auto configuration: sets the image label
                               default: Linux
      --root                 yaboot auto configuration: sets the root device
                               default: /dev/hda3

This is experimental but appears to work ok. 

A much better method of generating an /etc/yaboot.conf is to run
yabootconfig however.

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. 

Configuration file documentation:

ybin will verify the configuration file is sane and valid
before proceeding.

IMPORTANT: The configuration file format as of version 0.12 has
changed, see below for the current format, note some options have been
removed. as with version 0.11 ybin allows you to put spaces around the
= eg: boot = /dev/hda3 (however this prevents spaces from being
embedded in the options themselves) As of version 0.12 the separate
ybin.conf file is deprecated, instead ybin's options should be placed
in /etc/yaboot.conf, you must have yaboot 0.6 or later for this to
work.  Ybin will no longer use the obsolete /etc/ybin.conf.

The kludge, and kludgedir options have been removed. The bootconf
option has been deprecated since yaboot and ybin both use
/etc/yaboot.conf (or whatever config file is specified to the -C
switch).

boot= (same as -b or --boot)

This option defines what device the bootstrap partition is.  It also
be a regular file if you are creating a filesystem image for some
reason. It is safe to specify a MacOS boot partition as long as you DO
NOT use mkofboot.  ybin is non destructive except that is overwrites
any existing yaboot files (yaboot and yaboot.conf) at the root level
of the bootstrap filesystem. 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. Example boot=/dev/hda2

ofboot= (same as -o or --ofboot) 

This option defines the OpenFirmware device path to the bootstrap
partition.  This is needed so the first stage ofboot loader can be
configured properly.  It should include the OpenFirmware path
including the partition number (but not a filename). Example: if your
bootstrap partition is /dev/hda2 the OF path will likely be hd:2.
As of ybin 0.18 you no longer are required to specify this option, if
left undefined ybin will attempt to figure out the OpenFirmware path
automatically using the ofpath utility.  You should only need to
define this option if ofpath fails.

install= (same as -i or --install)

The full pathname to the yaboot OpenFirmware executable file.  This
file will be copied to the root level of the bootstrap partition, its
filename will not be changed. The default is
/usr/local/lib/yaboot/yaboot, or if that does not exist
/usr/lib/yaboot/yaboot.

magicboot= (same as -m or --magicboot)

The full pathname to any OF CHRP script file. If this is defined then
it will be given the HFS filetype defined below and the bootfile will
be given type "boot" instead, if we set two files to `tbxi' we may get
unpredictable results from OF.  A wrapper file would generally only be
needed if you have a OF script that creates a nice boot menu or
possibly adds a option to the newer ibook boot screens. IMPORTANT: it
appears that OF will only load `tbxi' files if they have a CHRP script
embedded, so this option is now on by default and will install the
included basic script that just loads the yaboot executable. (at least
until/if yaboot gets a embedded script) If you later change your mind
about using an OF wrapper you will have to delete it manually from the
bootstrap partition, ybin will not and cannot do it for you. If the
partition is a dedicated bootstrap partition you can run mkofboot to
remove it (and anything else).  This should be set to
/usr/local/lib/yaboot/ofboot which is the new first stage loader
configured automatically by ybin from options in /etc/yaboot.conf.

bsd= 

The OpenFirmware or unix device path to a NetBSD or OpenBSD bootstrap
partition, this partition must already have the BSD ofwboot.elf
bootloader installed in the root directory.  When you define this
option you will be presented with a simple menu at bootup allowing you
to hit L to boot GNU/Linux or B to boot BSD (along with other choices
if configured).  This will only work if you are using the new
/usr/local/lib/yaboot/ofboot script.  When this is set to a unix
device node (ie /dev/hda11) then ybin will use the ofpath utility to
determine the OpenFirmware device path.

macos= 

The OpenFirmware or unix device path to a MacOS 8.* or 9.* boot
partition.  When you define this option you will be presented with a
simple menu at bootup allowing you to hit L to boot GNU/Linux or M to
boot MacOS (along with other choices if configured).  This will only
work if you are using the new /usr/local/lib/yaboot/ofboot script.
When this is set to a unix device node (ie /dev/hda11) then ybin will
use the ofpath utility to determine the OpenFirmware device path.

macosx= 

The OpenFirmware or unix device path to a MacOS X boot partition.
When you define this option you will be presented with a simple menu
at bootup allowing you to hit L to boot GNU/Linux or X to boot MacOSX
(along with other choices if configured).  This will only work if you
are using the new /usr/local/lib/yaboot/ofboot script.  
When this is set to a unix device node (ie /dev/hda11) then ybin will
use the ofpath utility to determine the OpenFirmware device path.

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.

darwin=

The OpenFirmware or unix device path to a Darwin boot partition.  When
you define this option you will be presented with a simple menu at
bootup allowing you to hit L to boot GNU/Linux or D to boot Darwin
(along with other choices if configured).  This will only work if you
are using the new /usr/local/lib/yaboot/ofboot script.  When this is
set to a unix device node (ie /dev/hda11) then ybin will use the
ofpath utility to determine the OpenFirmware device path.

enablecdboot

This option adds an entry to the multiboot menu to boot from the CDROM
drive.

enablenetboot

This option adds an entry to the mulitboot menu to boot from the
network.

enableofboot

This option adds an entry to the multiboot menu to boot into an
OpenFirmware prompt.

defaultos= 

The name of the default OS to load.  This can be linux, bsd, macos or
macosx. This option controls what the first stage ofboot loader will
boot by default after the delay elapses.  This is only relevant if you
are using the new /usr/local/lib/yaboot/ofboot script and you have
defined bsd= and/or macos= and/or macosx= in /etc/yaboot.conf.

delay= 

The time in seconds that the first stage ofboot loader will wait for
you to choose L for GNU/Linux,M for MacOS, or X for MacOSX before
booting the default OS defined in defaultos=.  If not set the value of
timeout= (converted to seconds) will be used.

usemount (same as -M or --mount)

Whether or not to use the standard mount and umount utilities (and
thus kernel space filesystem drivers instead of userspace utilities
that manipulate the partition directly (through the device file). If
this option is present ybin will insist that you be root. Note that
using this option will prevent ybin from setting HFS attributes on the
boot files (such as type and creator).  This option is here mainly to
allow ybin's use even if you do not have hfsutils. Default: no
IMPORTANT: It is not possible to bless the filesystem when mounted
this way, you will thus have to manually configure OF to make your
system bootable.

mntpoint= 

Requires `usemount' this works exactly like usemount does except it
does not mount the bootstrap partition but rather installs the
bootloader into the directory defined as the mountpoint.  The pathname
MUST be clean, ie no embedded spaces or metacharacters.  The directory
may not be more then one subdirectory deep from the root of the
partition (not necessarily the unix /).  You must not have a trailing
/ either.  This option is NOT recommended since it has the same
limitations as usemount, your system will not be bootable by
OpenFirmware, it will only be manually bootable or bootable if you
change the boot-device variable to the direct pathname to the
bootloader (which ybin will attempt to do). 

fstype= (same as --filesystem)

This defines what kind of filesystem exists (or created by mkofboot)
on the bootstrap partition.  Possible options are hfs and msdos (if
anyone can figure out how to get OF to execute a file on a ISO
filesystem I will add that too) Note that if you use msdos filesystem
you must have a DOS style partition table and not a Apple partition
map. (it also requires that usemount be yes) yaboot may not yet
support this configuration.  The "raw" type causes ybin or mkofboot to
copy the bootloader (value of install=) to the bootstrap without any
filesystem. CAUTION: this will destroy any data or filesystem on the
bootstrap partition (value of boot=) if you specify something like
boot=/dev/sda you will destroy the partition table and lose ALL data
on the disk.  Default: hfs

hfstype=

This defines the 4 character code that should be given to the bootfile
(the bootconf file will always be given type "conf") The main purpose
of this is to make OF think its loading a MacOSROM image file and boot
the system into GNU/Linux from the bootstrap partition as
automatically as it would MacOS.  In order for this to work you should
set this to `tbxi' (the default in the included config file). If you
have specified a OF wrapper (see above) then it will be given this
filetype and the bootfile will be given type "boot" instead.  NOTE:
This appears to not work unless the bootfile has a CHRP boot script
embedded in the header, at the moment yaboot lacks this script, see
README.ofboot for more details. Default: tbxi

hfscreator=

This defines the 4 character creator code that should be given to both
the bootfile and the bootconf files. This is largely pointless but if
you use MacOS you could configure it so you have a pretty icon on the
bootloader files. Default: UNIX

nobless (same as --nobless)

This prevents ybin from "blessing" the root directory of the bootstrap
partition.  This is Macspeak for "bootable directory" on the MacOS the
System Folder is "blessed".  Blessing the root directory will allow OF
to find the bootstrap partition and load the bootloader automatically
without reconfiguration (assuming the bootstrap partition is on the
default disk (internal IDE in most cases). You should probably only
set this if you are keeping the bootloader on a MacOS boot partition.

protect (same as --protect)

This defines whether the read-only bit should be set on the boot
files, this is mostly pointless but slightly discourages
tampering/deleting of the bootloader files if the bootstrap partition
is mounted by MacOS.  (hide below really would do a better job of
that) This option will work with both msdos and hfs filesystems.  It
also works whether you have the usemount option set or not. 

hide (same as --hide)

This defines whether or not the HFS invisible bit should be set on the
boot files. This is a stronger way to make sure nobody fscks up your
bootloader on the MacOS side of things.  (A better option is a
dedicated bootstrap partition with its partition type set to
Apple_Bootstrap which is acceptable to OF but MacOS will refuse to mount
it.) This option is ignored for msdos filesystems and will only work
if usemount is not set.

nonvram (same as --nonvram)

This option prevents ybin from using nvsetenv to set the OpenFirmware
boot-device variable in nvram.  This is currently required for IBM
machines.  NOTE: you should not use this option when dual booting
MacOS, it will cause the MacOS boot menu entries to fail on some
machines.

fgcolor=string

Specifies the foreground (text) color used by yaboot(8) 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(8) and the mulitboot
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
black.

ybin does not make any validations of the yaboot specific options,
that is up to you to make sure yaboot is configured correctly.

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

Copyright (C) 2001 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.

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