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