Remove some stale code
[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-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 ===========================================================================