README

   1 Yaboot  -- PowerPC GNU/Linux OpenFirmware bootloader
   2 -------------------------------------------------------------------
   3
   4 Please read the "COPYING" file for licence informations.
   5
   6 -------------------------------------------------------------------
   7
   8 Yaboot is an OpenFirmware bootloader for Open Firmware based
   9 machines. It is known to work on "NewWorld" class powermacs (iMac and
  10 all machines released after it), RS/6000, and possibly other OF based
  11 CHRP machines. "OldWorld" PowerMacs (with the built-in MacOS ROM)
  12 are not supported.
  13
  14 This README serves as a quick-start introduction to yaboot and its
  15 installation utilities. For a more complete usage and installation
  16 guide, see yaboot-howto.html/index.en.html in the same folder where
  17 this README is located, or else inside the doc folder in this
  18 directory. For documentation about all the options available, see the
  19 man pages (bootstrap, yaboot, yaboot.conf, ybin, mkofboot, ofpath,
  20 yabootconfig).
  21
  22
  23 -------------------------------------------------------------------
  24 Bootloader Installation Utilities
  25 ybin, mkofboot, ofpath, yabootconfig
  26 Written by Ethan Benson <erbenson@alaska.net>
  27 -------------------------------------------------------------------
  28
  29 ybin (YaBoot INstaller) and mkofboot
  30 -------------------------------------------------------------------
  31
  32 ybin is a lilo/quik style bootloader installer for PowerPC based
  33 machines which require a bootstrap partition rather than a traditional
  34 bootblock (i.e. all `NewWorld' Macintoshes). When ybin is configured
  35 correctly you can simply type ybin at the command line as root, and
  36 the bootloader and its configuration file will be installed or updated
  37 on the bootstrap partition without any further user intervention.
  38
  39 ybin also supports IBM PowerPC hardware which requires a slightly different
  40 bootstrap partition setup. For these machines, ybin uses dd to write yaboot
  41 directly to the partition instead of copying it to a filesystem on the
  42 partition. ybin will add the requisite .note section to yaboot prior to
  43 installation (IBM CHRP only).
  44
  45 mkofboot is a companion script (actually a symlink to ybin) which
  46 initializes the bootstrap partition prior to running ybin to install
  47 the bootloader on it. mkofboot will confirm you want to continue
  48 before proceeding unless called with the -f or --force switch. This
  49 is in contrast to ybin, which is non destructive except that it
  50 overwrites any existing yaboot files (yaboot and yaboot.conf) at the
  51 root level of the bootstrap filesystem.
  52
  53 mkofboot and ybin both refer to the same configuration file (normally
  54 yaboot.conf) to determine where the bootstrap files will be placed.
  55
  56 IMPORTANT: The bootstrap partition should never be mounted anywhere on
  57 your filesystem, ybin and mkofboot will check if it is and refuse to
  58 operate on it if it is mounted.  It is not necessary to keep anything
  59 but the boot loader on the bootstrap partition, yaboot will load the
  60 kernel from your root partition (which can be an ext2/3, XFS, or
  61 ReiserFS filesystem). Do not mount the bootstrap partition on top of
  62 /boot.
  63
  64 ybin can update a bootstrap filesystem either on a block device or in
  65 an ordinary file (as in an image of a filesystem.)
  66
  67 NOTE: You must have a secure mktemp program otherwise ybin will be
  68 vulnerable to race conditions.  Debian's mktemp qualifies I don't know
  69 about the other distributions, you have been warned. The temp file is
  70 created in /tmp by default but ybin will respect the $TMPDIR
  71 environment variable.
  72
  73
  74 ofpath
  75 -------------------------------------------------------------------
  76
  77 The included ofpath utility can usually determine the OpenFirmware
  78 device path that corresponds with a unix device node in /dev/.  Ybin
  79 uses this utility to find the path to the bootstrap partition and to
  80 any defined macos/macosx partitions. ofpath is based on the utility
  81 `show_of_path.sh' written by Olaf Hering.
  82
  83
  84 NOTE: ofpath may not work with all SCSI cards/drivers.
  85
  86 IMPORTANT: ofpath will NOT work on NewWorld Powermacs if the machine
  87 was booted with BootX.
  88
  89
  90 yabootconfig
  91 -------------------------------------------------------------------
  92
  93 Yabootconfig creates a default configuration file and then runs mkofboot to
  94 complete the bootloader installation. yabootconfig reads the running
  95 system's /etc/fstab to determine the kernel location, and detects the
  96 location of the 800k Apple_Bootstrap partition. It will also find IBM
  97 CHRP bootstrap partitions (type 0x41 PReP Boot).
  98
  99
 100
 101 Yaboot.conf Configuration File
 102 -------------------------------------------------------------------
 103
 104 yaboot.conf configuration file settings are covered in detail in `man
 105 yaboot.conf'. Avoid the use of spaces in the config file, except in
 106 comment lines or inside quotes. Here are the essential settings.
 107
 108
 109 boot=
 110 Example:   boot=/dev/hda2
 111
 112 This required setting defines the bootstrap partition device.  It can
 113 also be a regular file if you are creating a filesystem image for some
 114 reason. The default config file has this set to ``unconfigured'' which
 115 will cause ybin to complain about you not reading the docs, it is the
 116 only option you should need to change for ybin to work. Be sure you
 117 include the partition number at the end, it should never be something
 118 like /dev/hda.
 119
 120
 121 install=
 122 Example:  install=/usr/lib/yaboot/yaboot or /usr/local/lib/yaboot/yaboot
 123
 124 The full pathname to the yaboot OpenFirmware executable file. The
 125 default is shown above. This file will be copied to the root level of
 126 the bootstrap partition. Note: If you are installing an alternative
 127 bootloader, its filename will be changed to yaboot when it is copied
 128 (to match what the first stage bootloader expects to be loading).
 129
 130
 131 partition=
 132 Example:   partition=3
 133
 134 The partition number on which the kernel image is located. By default,
 135 this partition is assumed to be on the same device from which yaboot
 136 was loaded. If needed, device= can be used to explicitly specify the
 137 device.
 138
 139
 140 image=
 141 Examples:  image=/vmlinux  or  image=/boot/vmlinux-2.2.19-pmac
 142
 143 The path to the image from the root level of the partition (remember
 144 that yaboot is unaware of mountpoints).  Don't forget to include the
 145 leading slash when specifying the image path (image=vmlinux will
 146 probably fail).
 147
 148
 149 root=
 150 Example:   root=/dev/hda3
 151
 152 The Linux device name for the root partition. This parameter is
 153 passed to the kernel when it starts up to let it know where its root
 154 filesystem is located. Refer to the yaboot.conf man page for details
 155 on kernel image options such as append=, initrd=, and initrd-size=.
 156
 157
 158 magicboot= (same as -m or --magicboot)
 159 Example:   /usr/local/lib/yaboot/ofboot
 160
 161 Identifies the first stage loader. The example shown is the default. The
 162 ofboot script it refers to is included with and configured automatically by
 163 ybin from options in /etc/yaboot.conf. The magicboot= can be the full
 164 pathname to any OF CHRP script file. Since some newer OpenFirmware
 165 implementations appear to require a CHRP script, the magicboot= setting is
 166 highly recommended. If you don't include magicboot=, then yaboot itself will
 167 be the active bootfile.  magicboot= cannot be used on IBM CHRP.
 168
 169
 170 Boot Menu Options
 171 -------------------------------------------------------------------
 172
 173 The following options work only if you have specified the magicboot= option.
 174 Each option specifies an OpenFirmware or unix device path to another
 175 operating system's boot partition.  When you define one of these options you
 176 will be presented with a simple menu at bootup allowing you to hit `l' to
 177 boot GNU/Linux or another letter to boot the other OS (see below). These
 178 letters are typed without a shift key (the boot menu is case sensitive).
 179 When set to a unix device node such as /dev/hda11 then ybin will use the
 180 ofpath utility to determine the OpenFirmware device path.
 181
 182   Option       Letter  Operating System Type
 183   ---------    ------  ---------------------------------------------
 184   bsd=           b     NetBSD or OpenBSD root partition (you must
 185                           have the BSD ofwboot bootloader
 186                           installed at /usr/local/lib/yaboot/ofwboot)
 187
 188   macos=         m     MacOS 8.* or 9.* bootable partition
 189
 190   macosx=        x     MacOS X boot partition (also see brokenosx)
 191
 192   darwin=        d     Darwin boot partition
 193
 194   enablecdboot   c     Boot from the CDROM drive
 195
 196   enablenetboot  n     Boot from the network
 197
 198   enableofboot   o     Display an OpenFirmware prompt
 199
 200   defaultos=           The default OS to load (linux, bsd, macos,
 201                           darwin or macosx.
 202
 203 brokenosx
 204
 205 This option causes the menu entry for MacOSX to execute
 206 \System\Library\CoreServices\BootX from the macosx=device instead of
 207 the usual \\:tbxi.  This is necessary if OSX is installed onto an HFS+
 208 filesystem instead of UFS. When OSX is installed on an HFS+ filesystem
 209 MacOS will mount and debless the OSX partition.  Add this option if
 210 the OSX menu entry breaks after booting MacOS.  You should not use
 211 this option if OSX is installed on a UFS filesystem, for UFS installs
 212 you specify the OSX bootstrap partition which is protected against
 213 MacOS.
 214
 215 delay=
 216 Example:  delay=5
 217
 218 The time in seconds that the first stage ofboot loader will wait for
 219 you to choose a letter before booting the default OS defined in
 220 defaultos=.  If not set, the value of timeout= (converted to seconds)
 221 will be used.
 222
 223
 224 Colors
 225 -------------------------------------------------------------------
 226
 227 fgcolor=string
 228
 229 Specifies the foreground (text) color used by yaboot and the
 230 multiboot menu.  Available colors are: black, blue, light-blue, green,
 231 light-green, cyan, light-cyan, red, light-red, purple, light- purple,
 232 brown, light-gray, dark-gray, yellow, and white.  The default is
 233 white.
 234
 235 bgcolor=string
 236
 237 Specifies the background color used by yaboot and the multiboot
 238 menu.  Available colors are the same as fgcolor. The default is
 239 black.
 240
 241
 242 ===========================================================================
 243
 244 Copyright (C) 2000, 2001 Ethan Benson
 245
 246 This program is free software; you can redistribute it and/or
 247 modify it under the terms of the GNU General Public License
 248 as published by the Free Software Foundation; either version 2
 249 of the License, or (at your option) any later version.
 250
 251 This program is distributed in the hope that it will be useful,
 252 but WITHOUT ANY WARRANTY; without even the implied warranty of
 253 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 254 GNU General Public License for more details.
 255
 256 You should have received a copy of the GNU General Public License
 257 along with this program; if not, write to the Free Software
 258 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 259
 260 ===========================================================================