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