README

   1 Yaboot  -- PowerPC GNU/Linux OpenFirmware bootloader
   2 --------------------------------------------
   3
   4 Please read the "COPYING" file for licence informations.
   5
   6    Copyright (C) 2000 Benjamin Herrenschmidt
   7
   8    portions based on "poof"
   9
  10    Copyright (C) 1999 Marius Vollmer
  11
  12    portions based on "quik"
  13
  14    Copyright (C) 1996 Paul Mackerras.
  15
  16    PPC64 support & Misc fixes by Peter Bergner, David Engebretsen
  17
  18
  19 --------------------------------------------
  20
  21 Yaboot is an OpenFirmware bootloader for Open Firmware based
  22 machines. It is known to work on "NewWorld" class powermacs
  23 (iMac and all machines released after it), RS/6000, and possibly
  24 other OF based CHRP machines.
  25 "OldWorld" PowerMacs (with the old MacOS ROM buit-in) are not
  26 supported.
  27
  28 ybin Written by Ethan Benson <erbenson@alaska.net>
  29
  30 ybin (YaBoot INstaller) was created so that there could be a lilo/quik
  31 style bootloader installer for PowerPC based machines which require
  32 bootstrap partitions rather then a traditional bootblock (ie all
  33 `NewWorld' Macintoshes).  It is designed to install yaboot, an
  34 OpenFirmware bootloader for GNU/Linux written by Benjamin
  35 Herrenschmidt.  When ybin is configured correctly you can simply type
  36 ybin, and the bootloader and its configuration file will be
  37 installed/updated on the bootstrap partition without any further user
  38 intervention.
  39
  40 ybin also supports IBM PowerPC hardware which requires a slightly
  41 different bootstrap partition setup, yaboot is directly dded to the
  42 partition instead of copied to a filesystem on the partition.  For
  43 these machines add fstype=raw to your /etc/yaboot.conf.  See
  44 examples/yaboot.conf.rs6k for an example configuration.
  45
  46 Both ybin and mkofboot are shell scripts (compatible with ash, sh,
  47 bash).  These are the first real scripts that I have written with any
  48 sort of complexity, so don't be too brutal if they are ugly and
  49 inefficient. ;-) Suggestions on how to do things better are welcome.
  50
  51 ybin can update a bootstrap filesystem either on a block device or a
  52 ordinary file (as in a image of a filesystem.)
  53
  54 Unless you use the usemount (or --mount) option it does not
  55 necessarily need to be run as root, but it probably will, unless you
  56 changed device permissions or are only updating an image.
  57
  58 mkofboot is a companion script (actually a symlink to ybin) to
  59 initialise the bootstrap partition and then run ybin to install the
  60 bootloader on it.  It uses the same configuration file as ybin to find
  61 the device to use. It will validate the configuration file before
  62 actually creating the filesystem. It will also confirm you want to
  63 continue before proceeding unless called with the -f or --force
  64 switch.
  65
  66 (>= 0.18): ofpath utility now included which can usually find the
  67 OpenFirmware device path that corresponds with a unix device node in
  68 /dev/.  Ybin will use this utility automatically to find the path to
  69 the bootstrap partition and to any defined macos/macosx partitions.
  70 NOTE: ofpath may not work with all SCSI cards/drivers.
  71 IMPORTANT: ofpath will NOT work if you boot your machine with BootX.
  72
  73 ofpath is based on the utility `show_of_path.sh' written by Olaf
  74 Hering.
  75
  76 (>= 0.20): ybin will now check for the new nvsetenv that is
  77 compatible with Newworld PowerMacs, and if found it will automatically
  78 update the boot-device variable in nvram to that of the bootstrap
  79 partition.  This feature can be disabled by passing the --nonvram
  80 switch to ybin or by adding `nonvram' to /etc/yaboot.conf.  This
  81 feature works in both the userland and `usemount' modes.  In userland
  82 mode ybin sets the boot-device variable to <path>,\\:tbxi, for example
  83 if your bootstrap partition is /dev/hda2 boot-device will be set to
  84 hd:2,\\:tbxi, in `usemount' mode it would be set to hd:2,ofboot (or
  85 hd:2,yaboot if you don't have magicboot= set.)
  86
  87 NEW (>= 0.31): The ofboot script now has configurable colors, you can
  88 change the foreground (text) and background colors it will use with
  89 the fgcolor= and bgcolor= options in yaboot.conf, see below for
  90 details.  Yaboot 1.0 and later also supports these options.
  91
  92 IMPORTANT: The bootstrap partition should never be mounted anywhere on
  93 your filesystem, ybin and mkofboot will check if it is and refuse to
  94 operate on it if its mounted.  It is not necessary to keep anything
  95 but the boot loader on the bootstrap partition, yaboot will load the
  96 kernel from your ext2fs root partition so do not mount the bootstrap
  97 partition on top of /boot.
  98
  99 ybin now fully supports command line switches, see ybin --help for
 100 information on these.
 101
 102 NEW: ybin can now generate a basic yaboot.conf on the fly that you may
 103 customise with command line options:
 104
 105       --device               yaboot auto configuration: sets the OF boot device
 106                                default: hd:
 107       --partition            yaboot auto configuration: sets the partition
 108                                number of the root partition. default: 3
 109       --timeout              yaboot auto configuration: sets the time yaboot
 110                                will wait for user input before booting default
 111                                image default: 20 (2 seconds)
 112       --image                yaboot auto configuration: sets the path to the
 113                                kernel image. default: /vmlinux
 114       --label                yaboot auto configuration: sets the image label
 115                                default: Linux
 116       --root                 yaboot auto configuration: sets the root device
 117                                default: /dev/hda3
 118
 119 This is experimental but appears to work ok.
 120
 121 A much better method of generating an /etc/yaboot.conf is to run
 122 yabootconfig however.
 123
 124 NOTE: You must have a secure mktemp program otherwise ybin will be
 125 vulnerable to race conditions.  Debian's mktemp qualifies I don't know
 126 about the other distributions, you have been warned. The temp file is
 127 created in /tmp by default but ybin will respect the $TMPDIR
 128 environment variable.
 129
 130 Configuration file documentation:
 131
 132 ybin will verify the configuration file is sane and valid
 133 before proceeding.
 134
 135 IMPORTANT: The configuration file format as of version 0.12 has
 136 changed, see below for the current format, note some options have been
 137 removed. as with version 0.11 ybin allows you to put spaces around the
 138 = eg: boot = /dev/hda3 (however this prevents spaces from being
 139 embedded in the options themselves) As of version 0.12 the separate
 140 ybin.conf file is deprecated, instead ybin's options should be placed
 141 in /etc/yaboot.conf, you must have yaboot 0.6 or later for this to
 142 work.  Ybin will no longer use the obsolete /etc/ybin.conf.
 143
 144 The kludge, and kludgedir options have been removed. The bootconf
 145 option has been deprecated since yaboot and ybin both use
 146 /etc/yaboot.conf (or whatever config file is specified to the -C
 147 switch).
 148
 149 boot= (same as -b or --boot)
 150
 151 This option defines what device the bootstrap partition is.  It also
 152 be a regular file if you are creating a filesystem image for some
 153 reason. It is safe to specify a MacOS boot partition as long as you DO
 154 NOT use mkofboot.  ybin is non destructive except that is overwrites
 155 any existing yaboot files (yaboot and yaboot.conf) at the root level
 156 of the bootstrap filesystem. The default config file has this set to
 157 "unconfigured which will cause ybin to complain about you not reading
 158 the docs, it is the only option you should need to change for ybin to
 159 work. Example boot=/dev/hda2
 160
 161 ofboot= (same as -o or --ofboot)
 162
 163 This option defines the OpenFirmware device path to the bootstrap
 164 partition.  This is needed so the first stage ofboot loader can be
 165 configured properly.  It should include the OpenFirmware path
 166 including the partition number (but not a filename). Example: if your
 167 bootstrap partition is /dev/hda2 the OF path will likely be hd:2.
 168 As of ybin 0.18 you no longer are required to specify this option, if
 169 left undefined ybin will attempt to figure out the OpenFirmware path
 170 automatically using the ofpath utility.  You should only need to
 171 define this option if ofpath fails.
 172
 173 install= (same as -i or --install)
 174
 175 The full pathname to the yaboot OpenFirmware executable file.  This
 176 file will be copied to the root level of the bootstrap partition, its
 177 filename will not be changed. The default is
 178 /usr/local/lib/yaboot/yaboot, or if that does not exist
 179 /usr/lib/yaboot/yaboot.
 180
 181 magicboot= (same as -m or --magicboot)
 182
 183 The full pathname to any OF CHRP script file. If this is defined then
 184 it will be given the HFS filetype defined below and the bootfile will
 185 be given type "boot" instead, if we set two files to `tbxi' we may get
 186 unpredictable results from OF.  A wrapper file would generally only be
 187 needed if you have a OF script that creates a nice boot menu or
 188 possibly adds a option to the newer ibook boot screens. IMPORTANT: it
 189 appears that OF will only load `tbxi' files if they have a CHRP script
 190 embedded, so this option is now on by default and will install the
 191 included basic script that just loads the yaboot executable. (at least
 192 until/if yaboot gets a embedded script) If you later change your mind
 193 about using an OF wrapper you will have to delete it manually from the
 194 bootstrap partition, ybin will not and cannot do it for you. If the
 195 partition is a dedicated bootstrap partition you can run mkofboot to
 196 remove it (and anything else).  This should be set to
 197 /usr/local/lib/yaboot/ofboot which is the new first stage loader
 198 configured automatically by ybin from options in /etc/yaboot.conf.
 199
 200 bsd=
 201
 202 The OpenFirmware or unix device path to a NetBSD or OpenBSD bootstrap
 203 partition, this partition must already have the BSD ofwboot.elf
 204 bootloader installed in the root directory.  When you define this
 205 option you will be presented with a simple menu at bootup allowing you
 206 to hit L to boot GNU/Linux or B to boot BSD (along with other choices
 207 if configured).  This will only work if you are using the new
 208 /usr/local/lib/yaboot/ofboot script.  When this is set to a unix
 209 device node (ie /dev/hda11) then ybin will use the ofpath utility to
 210 determine the OpenFirmware device path.
 211
 212 macos=
 213
 214 The OpenFirmware or unix device path to a MacOS 8.* or 9.* boot
 215 partition.  When you define this option you will be presented with a
 216 simple menu at bootup allowing you to hit L to boot GNU/Linux or M to
 217 boot MacOS (along with other choices if configured).  This will only
 218 work if you are using the new /usr/local/lib/yaboot/ofboot script.
 219 When this is set to a unix device node (ie /dev/hda11) then ybin will
 220 use the ofpath utility to determine the OpenFirmware device path.
 221
 222 macosx=
 223
 224 The OpenFirmware or unix device path to a MacOS X boot partition.
 225 When you define this option you will be presented with a simple menu
 226 at bootup allowing you to hit L to boot GNU/Linux or X to boot MacOSX
 227 (along with other choices if configured).  This will only work if you
 228 are using the new /usr/local/lib/yaboot/ofboot script.
 229 When this is set to a unix device node (ie /dev/hda11) then ybin will
 230 use the ofpath utility to determine the OpenFirmware device path.
 231
 232 brokenosx
 233
 234 This option causes the menu entry for MacOSX to execute
 235 \System\Library\CoreServices\BootX from the macosx=device instead of
 236 the usual \\:tbxi.  This is necessary if OSX is installed onto an HFS+
 237 filesystem instead of UFS. When OSX is installed on an HFS+ filesystem
 238 MacOS will mount and debless the OSX partition.  Add this option if
 239 the OSX menu entry breaks after booting MacOS.  You should not use
 240 this option if OSX is installed on a UFS filesystem, for UFS installs
 241 you specify the OSX bootstrap partition which is protected against
 242 MacOS.
 243
 244 darwin=
 245
 246 The OpenFirmware or unix device path to a Darwin boot partition.  When
 247 you define this option you will be presented with a simple menu at
 248 bootup allowing you to hit L to boot GNU/Linux or D to boot Darwin
 249 (along with other choices if configured).  This will only work if you
 250 are using the new /usr/local/lib/yaboot/ofboot script.  When this is
 251 set to a unix device node (ie /dev/hda11) then ybin will use the
 252 ofpath utility to determine the OpenFirmware device path.
 253
 254 enablecdboot
 255
 256 This option adds an entry to the multiboot menu to boot from the CDROM
 257 drive.
 258
 259 enablenetboot
 260
 261 This option adds an entry to the mulitboot menu to boot from the
 262 network.
 263
 264 enableofboot
 265
 266 This option adds an entry to the multiboot menu to boot into an
 267 OpenFirmware prompt.
 268
 269 defaultos=
 270
 271 The name of the default OS to load.  This can be linux, bsd, macos or
 272 macosx. This option controls what the first stage ofboot loader will
 273 boot by default after the delay elapses.  This is only relevant if you
 274 are using the new /usr/local/lib/yaboot/ofboot script and you have
 275 defined bsd= and/or macos= and/or macosx= in /etc/yaboot.conf.
 276
 277 delay=
 278
 279 The time in seconds that the first stage ofboot loader will wait for
 280 you to choose L for GNU/Linux,M for MacOS, or X for MacOSX before
 281 booting the default OS defined in defaultos=.  If not set the value of
 282 timeout= (converted to seconds) will be used.
 283
 284 usemount (same as -M or --mount)
 285
 286 Whether or not to use the standard mount and umount utilities (and
 287 thus kernel space filesystem drivers instead of userspace utilities
 288 that manipulate the partition directly (through the device file). If
 289 this option is present ybin will insist that you be root. Note that
 290 using this option will prevent ybin from setting HFS attributes on the
 291 boot files (such as type and creator).  This option is here mainly to
 292 allow ybin's use even if you do not have hfsutils. Default: no
 293 IMPORTANT: It is not possible to bless the filesystem when mounted
 294 this way, you will thus have to manually configure OF to make your
 295 system bootable.
 296
 297 mntpoint=
 298
 299 Requires `usemount' this works exactly like usemount does except it
 300 does not mount the bootstrap partition but rather installs the
 301 bootloader into the directory defined as the mountpoint.  The pathname
 302 MUST be clean, ie no embedded spaces or metacharacters.  The directory
 303 may not be more then one subdirectory deep from the root of the
 304 partition (not necessarily the unix /).  You must not have a trailing
 305 / either.  This option is NOT recommended since it has the same
 306 limitations as usemount, your system will not be bootable by
 307 OpenFirmware, it will only be manually bootable or bootable if you
 308 change the boot-device variable to the direct pathname to the
 309 bootloader (which ybin will attempt to do).
 310
 311 fstype= (same as --filesystem)
 312
 313 This defines what kind of filesystem exists (or created by mkofboot)
 314 on the bootstrap partition.  Possible options are hfs and msdos (if
 315 anyone can figure out how to get OF to execute a file on a ISO
 316 filesystem I will add that too) Note that if you use msdos filesystem
 317 you must have a DOS style partition table and not a Apple partition
 318 map. (it also requires that usemount be yes) yaboot may not yet
 319 support this configuration.  The "raw" type causes ybin or mkofboot to
 320 copy the bootloader (value of install=) to the bootstrap without any
 321 filesystem. CAUTION: this will destroy any data or filesystem on the
 322 bootstrap partition (value of boot=) if you specify something like
 323 boot=/dev/sda you will destroy the partition table and lose ALL data
 324 on the disk.  Default: hfs
 325
 326 hfstype=
 327
 328 This defines the 4 character code that should be given to the bootfile
 329 (the bootconf file will always be given type "conf") The main purpose
 330 of this is to make OF think its loading a MacOSROM image file and boot
 331 the system into GNU/Linux from the bootstrap partition as
 332 automatically as it would MacOS.  In order for this to work you should
 333 set this to `tbxi' (the default in the included config file). If you
 334 have specified a OF wrapper (see above) then it will be given this
 335 filetype and the bootfile will be given type "boot" instead.  NOTE:
 336 This appears to not work unless the bootfile has a CHRP boot script
 337 embedded in the header, at the moment yaboot lacks this script, see
 338 README.ofboot for more details. Default: tbxi
 339
 340 hfscreator=
 341
 342 This defines the 4 character creator code that should be given to both
 343 the bootfile and the bootconf files. This is largely pointless but if
 344 you use MacOS you could configure it so you have a pretty icon on the
 345 bootloader files. Default: UNIX
 346
 347 nobless (same as --nobless)
 348
 349 This prevents ybin from "blessing" the root directory of the bootstrap
 350 partition.  This is Macspeak for "bootable directory" on the MacOS the
 351 System Folder is "blessed".  Blessing the root directory will allow OF
 352 to find the bootstrap partition and load the bootloader automatically
 353 without reconfiguration (assuming the bootstrap partition is on the
 354 default disk (internal IDE in most cases). You should probably only
 355 set this if you are keeping the bootloader on a MacOS boot partition.
 356
 357 protect (same as --protect)
 358
 359 This defines whether the read-only bit should be set on the boot
 360 files, this is mostly pointless but slightly discourages
 361 tampering/deleting of the bootloader files if the bootstrap partition
 362 is mounted by MacOS.  (hide below really would do a better job of
 363 that) This option will work with both msdos and hfs filesystems.  It
 364 also works whether you have the usemount option set or not.
 365
 366 hide (same as --hide)
 367
 368 This defines whether or not the HFS invisible bit should be set on the
 369 boot files. This is a stronger way to make sure nobody fscks up your
 370 bootloader on the MacOS side of things.  (A better option is a
 371 dedicated bootstrap partition with its partition type set to
 372 Apple_Bootstrap which is acceptable to OF but MacOS will refuse to mount
 373 it.) This option is ignored for msdos filesystems and will only work
 374 if usemount is not set.
 375
 376 nonvram (same as --nonvram)
 377
 378 This option prevents ybin from using nvsetenv to set the OpenFirmware
 379 boot-device variable in nvram.  This is currently required for IBM
 380 machines.  NOTE: you should not use this option when dual booting
 381 MacOS, it will cause the MacOS boot menu entries to fail on some
 382 machines.
 383
 384 fgcolor=string
 385
 386 Specifies the foreground (text) color used by yaboot(8) and the
 387 multiboot menu.  Available colors are: black, blue, light-blue, green,
 388 light-green, cyan, light-cyan, red, light-red, purple, light- purple,
 389 brown, light-gray, dark-gray, yellow, and white.  The default is
 390 white.
 391
 392 bgcolor=string
 393
 394 Specifies the background color used by yaboot(8) and the mulitboot
 395 menu.  Available colors are: black, blue, light-blue, green,
 396 light-green, cyan, light-cyan, red, light-red, purple, light-purple,
 397 brown, light-gray, dark-gray, yellow, and white.  The default is
 398 black.
 399
 400 ybin does not make any validations of the yaboot specific options,
 401 that is up to you to make sure yaboot is configured correctly.
 402
 403 ===========================================================================
 404
 405 Copyright (C) 2001 Ethan Benson
 406
 407 This program is free software; you can redistribute it and/or
 408 modify it under the terms of the GNU General Public License
 409 as published by the Free Software Foundation; either version 2
 410 of the License, or (at your option) any later version.
 411
 412 This program is distributed in the hope that it will be useful,
 413 but WITHOUT ANY WARRANTY; without even the implied warranty of
 414 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 415 GNU General Public License for more details.
 416
 417 You should have received a copy of the GNU General Public License
 418 along with this program; if not, write to the Free Software
 419 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 420
 421 ===========================================================================