Commit yaboot 1.3.5
[yaboot.git] / 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 ===========================================================================