--- /dev/null
+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.
+
+===========================================================================
projects / yaboot.git / blobdiff