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.

Both ybin and mkofboot are bash shell scripts.  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 have usemount set to yes (in ybin.conf, see below) 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 to initialize 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.

Configuration file documentation:

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

IMPORTANT: The configuration file is sourced as bash shell variables
so no spaces are allowed between the = like in lilo/quik/yaboot config
files.

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


bootfile=

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 /boot/yaboot in the
included configuration file.

bootconf=

The full pathname to the yaboot configuration file. This file will be
copied to the root level of the bootstrap partition right next to the
bootfile, its filename will be "yaboot.conf" for hfs filesystems and
"yaboot.cnf" for DOS filesystems. The default is set to
/etc/yaboot.conf in the included configuration file.

wrapper=

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

usemount=

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). This
option must be either yes or no.  yes will cause ybin to insist that
you be root. Note that setting this to yes will prevent ybin from
setting HFS attributes on the boot files (such as type and creator)
unless you also use the "kludge" option below.  This option is mainly
here mainly to allow ybin's use even if you do not have hfsutils (or
vise versa do not have kernel HFS support). This is set to no in the
included configuration file. 

fstype=

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. This is set to hfs in the included
configuration file.

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.b for more details.  This option may be ommited if
fstype=msdos

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.  This option may be ommited if fstype=msdos.

bless=

This defines whether or not the root directory of the bootstrap
partition should be "blessed".  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 to yes when you have a
dedicated bootstrap partition, if you are keeping the bootloader on a
MacOS boot partition this will probably break MacOS. This option must
be either yes or no, but may be ommited if hfstype=msdos.

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 must be either yes or no and will work with both
msdos and hfs filesystems.  It also works whether you have usemount
set to yes or no.  

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_BootROM 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 set to no or if you use the kludge mode below.

kludge=

This option defines whether we should use a ugly hack to set HFS
metadata on the bootfiles when we are using mount instead of
hfsutils. Here is an explanation:

You may have noticed when you mount a hfs filesystem with kernel
space drivers that there is a .finderinfo directory containing a
file for each file in the directory, it just so happens that
contains the file's hfs metadata, so if we overwrite it with
another version we can change the file's metadata. ybin should come
with premade files to either just set the type and creator, or to
set type+creator along with the invisible and locked bits.  no guarantees
this won't hose your filesystem however. (it works for me TM)

kludgedir=

This defines where to find the so called kludge files, these are
copies of the .finderinfo/* files with whatever metadata you prefer.
You can make your own by using hfsutils to set the attributes on a
file and then copying the appropriate .finderinfo/* file.  ybin looks
for a matching filename to the bootfile and bootconf filenames
installed onto the bootstrap partition. The included config file
defines this as /boot/ybin.hfs it must point to a directory.  This
option may be ommited if kludge is set to no.

ybin does not make any validations of the yaboot.conf file that is up
to you to make sure its correct.

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

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

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