YABOOT.CONF(5) File Formats YABOOT.CONF(5)NAMEyaboot.conf - Configuration file format used by yaboot(8) and ybin(8).
SYNOPSIS
/etc/yaboot.conf
DESCRIPTION
The yaboot.conf file is a configuration file for yaboot which is read
during booting, and for ybin(8) to generate a boot menu and to properly
install yaboot onto the bootstrap(8) partition.
yaboot.conf provides instructions for yaboot. This includes which ker‐
nels to load and what options to pass to them. yaboot reads and parses
its configuration file found on the bootstrap(8) partition on Power‐
Macs, and directly from the root filesystem on IBM PowerPC hardware.
On PowerMacs you must run the ybin(8) command each time you modify
/etc/yaboot.conf.
yaboot is able to boot kernels even without this configuration file or
if this file is crippled or contains syntax errors, but the user has to
enter full OpenFirmware names and full path of the images to load and
all options required for them manually.
FILE FORMAT
The file consists of comments and variable assignments.
Comments
Start with a # character, and continue to the end of the line.
Flag variables
Consist of a single keyword and are followed by whitespace or
the end of the file.
String variables
Consist of the variable name, optional whitespace, a = charac‐
ter, optional whitespace, the value and required newline.
IMPORTANT: ybin(8) specific options do not support embedded spa‐
ces. It is important that there be no trailing whitespace at
the end of a line.
File names
Some string variables are expecting file names. A file name for‐
mat in yaboot is:
[<devicename>][<part>]<absolute_pathname>
or
[<devicename>][<part>][[<m>-<n>]]
The first form refers to a file or directory on some supported
filesystem (currently ext2, hfs, hfs+ or iso9660), the latter
refers to a range of 512B blocks on a device. For a device block
range, either <devicename>, or <part>, or [<m>-<n>] must be
given.
Optional <devicename> is the OpenFirmware name of the device the
file or range is located on. See below for its syntax. For Open‐
Firmware the device name must be immediately followed by the :
character. The default is the boot device yaboot was booted
from, or the value of device= in /etc/yaboot.conf.
Optional <part> is the 1 based partition number on the device.
First partition is 1 (e.g. on /dev/sda in Linux is this
/dev/sda1). The default is the default partition (the value of
the partition variable in the config file). Note that on Apple
partition tables the first partition is always the partition ta‐
ble itself (/dev/sda1 is the partition table).
<absolute_pathname> must start with a / character and is the
pathname from the root of the filesystem on that device (unless
it is the root filesystem this is different to the pathname you
will see in GNU/Linux).
<m> is the first block number (in blocksize 512 bytes) of the
range to be loaded and <n> is the last block number plus one.
Device name syntax is:
<fully_qualified_prom_device_name>[:<part_number>]
where the fully qualified OpenFirmware device name starts with a
/ character for the root of the OpenFirmware device tree and
contains all the nodes from the root in the tree up to the disk
device node. If some node contains more than one child node with
the same name and the path has to go through such node, a @
character followed by hexadecimal address pair is desirable to
resolve the ambiguity. Optional partition number is a number
that follows the : character 1 (for first partition) 2 (for sec‐
ond, partition, etc). OpenFirmware device names might look like:
/pci@80000000/pci-bridge@d/ADPT,2930CU@2/@0:
/pci/@d/mac-io/ata-3@20000/disk@1:
/pci/@d/pci-ata@1/ata-4@0/disk@0:
/pci/@d/pci-ata@1/ata-4@0/disk@1:
OpenFirmware device names if specified as part of the file name
(see above) should be followed by the : character to separate
the device name from the optional Linux partition number, as
shown above. For more information on this topic, consult boot‐
strap(8).
OpenFirmware also has some predefined aliases which are used
instead of the longer canonical device names. Standard aliases
include:
hd: - The primary master IDE hard disk.
ultra1: - The primary slave IDE hard disk.
cd: - The secondary master device (usually CDROM).
zip: - The secondary slave device (usually zip drive).
Variable names are case sensitive, values of string variables are also
case sensitive.
Blanks and equal signs may only be part of a variable name or a value
if they are escaped by a backslash or if the value is embedded in dou‐
ble quotes. An equal sign may not be the only character in a name or
value.
An escaped tab is converted to an escaped blank. An escaped newline is
removed from the input stream. An escaped backslash (i.e. two back‐
slashes) is converted to a backslash. Inside quoted strings, only dou‐
ble quotes, backslashes and newlines can be escaped.
Example:
# Simple yaboot.conf
boot=/dev/hda2
device=hd:
partition=3
magicboot=/usr/lib/yaboot/ofboot
timeout=50
root=/dev/hda3
read-only
# End of global variables - begin image labels
image=/boot/vmlinux
label=linux
image=/boot/vmlinux.old
label=old
This file contains options for two distinct programs: the ybin(8) (and
mkofboot(8)) bootstrap(8) installer, and the yaboot(8) bootloader, each
ignores the other's configuration options.
The ybin/mkofboot options are: boot= ofboot= install= magicboot= delay=
bsd= macos= macosx= darwin= defaultos= usemount mntpoint= fstype=
hfstype= nobless hide protect nonvram enablecdboot enablenetboot
enableofboot brokenosx
The remaining options belong to yaboot(8).
GLOBAL OPTIONS
/etc/yaboot.conf begins with a possibly empty global options section.
This section contains all variable assignments up to the first image
setting.
The following global options are recognized:
boot=boot-device
Specifies the bootstrap(8) partition ybin(8) will install the
boot loader on. This partition needs to have an HFS or MSDOS
filesystem created on it (except on IBM hardware). ybin(8) will
not create a filesystem. If a filesystem is not present run
mkofboot(8) instead of ybin(8) for the first time. The boot‐
strap(8) partition must have a partition type of Apple_Bootstrap
to prevent MacOS[X] from mounting it. If MacOS is able to mount
the bootstrap(8) partition it will make it unbootable by remov‐
ing the attributes ybin(8) set to make the partition bootable by
OpenFirmware. The bootstrap partition must not be mounted any‐
where on your filesystem, ybin(8) and mkofboot(8) will refuse to
operate on it if it is mounted. On IBM hardware the boot‐
strap(8) should be a type 0x41 PReP Boot partition.
ofboot=of-path
This option defines the OpenFirmware device path to the boot‐
strap(8) partition. This is needed so the first stage ofboot.b
loader can be configured properly. It should include the Open‐
Firmware path including the partition number (but not a file‐
name). Example: if your bootstrap partition is /dev/hda2 the OF
path will likely be hd:2. As of ybin(8) 0.18 you no longer are
required to (and should not) specify this option. If left unde‐
fined ybin(8) will attempt to figure out the OpenFirmware path
automatically using the ofpath(8) utility. You should only need
to define this option if ofpath(8) fails.
install=boot-loader
Specifies the path to the yaboot(8) OpenFirmware executable
file. This file is copied by ybin(8) to the bootstrap(8) parti‐
tion. The default if this is not specified is
/usr/local/lib/yaboot/yaboot or /usr/lib/yaboot/yaboot.
magicboot=magicboot-script
Specifies the path to an OpenFirmware CHRP script that ybin(8)
will copy to the bootstrap(8) partition. Such a script contains
Forth commands that can allow you to do interesting things such
as creating a boot menu to choose between MacOS or GNU/Linux.
Currently you must use a magicboot script do to a bug in Open‐
Firmware. Eventually a CHRP header could be added to the
yaboot(8) executable so this can be optional. When this option
is defined the magicboot script will be executed by OF automati‐
cally at boot (instead of the install file.) See man boot‐
strap(8) for more information on this. As of ybin 0.22 you
should set this to /usr/lib/yaboot/ofboot which is a autoconfig‐
uring first stage loader for yaboot. It is capable of present‐
ing a dual boot menu for GNU/Linux, MacOS and MacOSX. If dual
booting is not required or configured it will simply load yaboot
directly. You must specify this for most PowerMacs or they will
fail to boot. You cannot use magicboot scripts with IBM hard‐
ware.
default=name
Uses the specified image as the default boot image. If `default'
is omitted, the image appearing first in the configuration file
is used.
defaultos=linux|bsd|macos|macosx|darwin
Defines the default OS for the first stage multiboot menu to
load, by default this is linux, which really means yaboot.
Valid values are: linux, bsd, macos, macosx, and darwin. This
is only relevant if you have bsd=, macos=, macosx=, or darwin=
options defined.
message=message_filename
Specifies a file containing a message that is displayed before
the boot prompt. You may specify either a plain pathname, in
which case the default device and partition will be derived from
the device= and partition= lines in the global section of
yaboot.conf, or you can specify a full OpenFirmware device path,
the file may be on any yaboot(8) supported filesystem. The mes‐
sage file must be plain ASCII text with UNIX newlines. Note:
only the first 2000 bytes of this file will be read.
password=password
Protect booting by a password. The password is given in either
cleartext or an md5 hash (of the same format as used in
GNU/Linux passwd files)in the configuration file. Because of
that, the configuration file should be only readable by the
superuser and the password should differ if possible from other
passwords on the system. See chmod(1) to set permissions on
yaboot.conf(5). Passwords currently do not affect the multiboot
menu entries (macos=, macosx=, etc).
timeout=tsecs
Sets a timeout (in tenths of a second) for keyboard input. If no
key is pressed for the specified time, the first image is auto‐
matically booted.
delay=secs
Sets a timeout (in seconds) for an OS choice in the first stage
ofboot loader. If no key is pressed for the specified time, the
default OS defined by defaultos= (or GNU/Linux) is automatically
booted. If this is left unset, the value of timeout= (converted
to seconds) will be used.
init-code=string
Specifies that yaboot(8) should call OpenFirmware to execute the
string given (a series of forth commands) before printing the
boot prompt.
fgcolor=string
Specifies the foreground (text) color used by yaboot(8) and the
multiboot menu. Available colors are: black, blue, light-blue,
green, light-green, cyan, light-cyan, red, light-red, purple,
light-purple, brown, light-gray, dark-gray, yellow, and white.
The default is white.
bgcolor=string
Specifies the background color used by yaboot(8) and the mulit‐
boot menu. Available colors are: black, blue, light-blue,
green, light-green, cyan, light-cyan, red, light-red, purple,
light-purple, brown, light-gray, dark-gray, yellow, and white.
The default is black.
bsd=of-path
The OpenFirmware or Unix device path to a NetBSD or OpenBSD root
partition, this partition must have the BSD kernel located at
/bsd. You must also have the BSD bootloader ofwboot installed
at /usr/local/lib/yaboot/ofwboot, ybin(8) will install this onto
the bootstrap(8) partition. When you define this option you
will be presented with a simple menu at bootup allowing you to
hit L to boot GNU/Linux or B to boot BSD (along with other
choices if configured). This will only work if you are using
the new /usr/lib/yaboot/ofboot script. When this is set to a
unix device node (ie /dev/hda11) then ybin will use the
ofpath(8) utility to determine the OpenFirmware device path.
macos=of-path
The OpenFirmware or Unix device path to a MacOS 8.* or 9.* boot
partition. When you define this option you will be presented
with a simple menu at bootup allowing you to hit L to boot
GNU/Linux or M to boot MacOS (along with other choices if con‐
figured). This will only work if you are using the new
/usr/lib/yaboot/ofboot script. When this is set to a unix
device node (ie /dev/hda11) then ybin will use the ofpath(8)
utility to determine the OpenFirmware device path.
macosx=of-path
The OpenFirmware or unix device path to a MacOS X boot parti‐
tion. When you define this option you will be presented with a
simple menu at bootup allowing you to hit L to boot GNU/Linux or
X to boot MacOSX (along with other choices if configured). This
will only work if you are using the new /usr/lib/yaboot/ofboot
script. When this is set to a unix device node (ie /dev/hda11)
then ybin will use the ofpath(8) utility to determine the Open‐
Firmware device path.
brokenosx
This option causes the menu entry for MacOSX to execute \Sys‐
tem\Library\CoreServices\BootX from the macosx=device instead of
the usual \\:tbxi. This is necessary if OSX is installed onto
an HFS+ filesystem instead of UFS. When OSX is installed on an
HFS+ filesystem MacOS will mount and debless the OSX partition.
Add this option if the OSX menu entry breaks after booting Mac‐
OS. You should not use this option if OSX is installed on a UFS
filesystem, for UFS installs you specify the OSX bootstrap par‐
tition which is protected against MacOS. This option requires
macosx= to be set.
darwin=of-path
The OpenFirmware or unix device path to a Darwin boot partition.
When you define this option you will be presented with a simple
menu at bootup allowing you to hit L to boot GNU/Linux or D to
boot Darwin (along with other choices if configured). This will
only work if you are using the new /usr/lib/yaboot/ofboot
script. When this is set to a unix device node (ie /dev/hda11)
then ybin will use the ofpath(8) utility to determine the Open‐
Firmware device path.
enablecdboot
This option adds an entry to the multiboot menu to boot from the
CDROM drive.
enablenetboot
This option adds an entry to the multiboot menu to boot from the
network.
enableofboot
This option adds an entry to the multiboot menu to boot into an
OpenFirmware prompt.
usemount
This option causes ybin to use the regular mount(8) utilities to
access the filesystem on the bootstrap(8) partition instead of
the userspace hfsutils(1). This is not recommended for HFS
filesystems since it is not possible to set all the attributes
required for automatic OpenFirmware booting. If you use this
option you will have to modify OpenFirmware's boot-device vari‐
able to make your machine bootable (see man bootstrap(8)).
Without this option you can normally reset OpenFirmware to its
default configuration and your system will boot automatically
into GNU/Linux. (See bootstrap(8) for details) This option is
required for MSDOS filesystems.
mntpoint=/path/to/directory
Requires usemount this works exactly like usemount does except
it does not mount the bootstrap(8) partition but rather installs
the bootloader into the directory defined as the mountpoint.
The pathname MUST be clean, ie no embedded spaces or metacharac‐
ters. The directory may not be more then one subdirectory deep
from the root of the partition (not necessarily the unix /).
You must not have a trailing / either. This option is NOT rec‐
ommended since it has the same limitations as usemount, your
system will not be bootable by OpenFirmware, it will only be
manually bootable or bootable if you change the boot-device
variable to the direct pathname to the bootloader (which ybin(8)
will attempt to do). WARNING: This option is not secure if
untrusted users can write to the value of mntpoint=, and the
filesystem supports links.
fstype=hfs|msdos|raw
Specifies what kind of filesystem is created on the bootstrap(8)
partition by mkofboot(8). It must be either hfs or msdos or
raw. For Apple PowerMacs HFS is the only workable option unless
you have partitioned your disk with Intel partition tables.
Ybin(8) also uses this option to determine how to access the
partition properly. The raw type causes ybin(8) or mkofboot(8)
to copy the bootloader (value of install=) to the bootstrap(8)
partition without any filesystem. CAUTION: this will destroy any
data or filesystem on the bootstrap(8) partition (value of
boot=) if you specify something like boot=/dev/sda you will
destroy the partition table and lose ALL data on the disk. The
default if omitted, is hfs.
hfstype=type-code
Specifies the four character HFS type code that is given to the
boot loader (or magicboot script). The default is tbxi and
should not be changed unless you really know what you are doing,
OpenFirmware (on PowerMacs) looks for a file of this type to
execute as a boot loader so if you change this your system will
not boot automatically. This is only meant for users who must
use a MacOS boot partition as the bootstrap partition, otherwise
the conflict of two tbxi files could potentially cause MacOS to
fail to boot. This code is only given to the file intended for
OpenFirmware to boot. This option is ignored on non-HFS
filesystems.
nobless
This prevents ybin(8) from “blessing” the root directory of the
bootstrap(8) partition. Blessing the root directory is required
for OpenFirmware to boot correctly. This should only be used
when a MacOS boot partition is being used as the bootstrap(8) in
which case blessing the root directory would make MacOS
unbootable. If you use this option you must manually configure
OpenFirmware to boot yaboot(8). (see bootstrap(8))
hide This causes ybin(8) to set the HFS invisible bit on all the boot
loader files. OpenFirmware ignores this bit, but MacOS will not
show invisible files in the Finder. This is useful if the boot‐
strap(8) partition is MacOS mountable and you want to prevent
annoying MacOS lusers from screwing up your GNU/Linux boot
loader ;-). This option is ignored for non-HFS filesystems.
protect
This causes ybin(8) to set the HFS/MSDOS read-only bit on all
the boot loader files. MacOS will not allow a read-only file to
be modified or deleted (but does not prevent anyone from remov‐
ing this bit) This is only useful if the bootstrap(8) partition
is MacOS mountable and you want to discourage modification/dele‐
tion of the boot loader.
nonvram
This option prevents ybin(8) from setting the OpenFirmware boot-
device variable with nvsetenv(8).
In addition to these global options, per-image options append, device,
image, initrd-prompt, initrd-size, initrd, partition, pause-after,
pause-message, ramdisk, read-only, read-write, root and restricted can
be specified in the global section. They are used as defaults if they
aren't specified in the configuration sections of the respective kernel
images and will be used also for the arbitrary images specified on the
input line and not mentioned in the configuration file (unless overrid‐
den by input line options).
PER-IMAGE SECTIONS
A per-image section starts with either a line
image=filename
(for booting from files) From the image line on until next image line
are variable assignments and flags for this image's section. The fol‐
lowing options and flags are recognized:
label=name
The bootloader uses the main file name (without its path) of
each image specification to identify that image. A different
name can be used by setting the variable `label'.
alias=name
A second name for the same entry can be used by specifying an
alias.
partition=part_no
Specifies the default partition number (a digit, hda1 is part_no
1) to be used if some filename does not specify a partition num‐
ber explicitly. The kernel images should be located on the root
filesystem, thus partition should usually be set to the root
partition number. For example if the root partition is
/dev/hda3 (the third partition), then partition should be set to
partition=3.
device=device_name
Specifies the default device name to be used if some filename
does not specify a device name explicitly. This defaults to the
device yaboot has been booted from if you don't specify device
in either the global section or per-image section of the config
file.
append=string
Appends the options specified to the parameter line passed to
the kernel. This is typically used to specify parameters of
hardware that can't be entirely auto-detected or for which prob‐
ing may be dangerous. Example:
append = "video=ofonly"
literal=string
Like `append', but removes all other options (e.g. setting of
the root device). Because vital options can be removed uninten‐
tionally with `literal', this option cannot be set in the global
options section.
ramdisk=size
This specifies the size of the optional RAM disk. A value of
zero indicates that no RAM disk should be created. If this vari‐
able is omitted, the RAM disk size configured into the boot
image is used.
read-only
This specifies that the root file system should be mounted read-
only. Typically, the system startup procedure re-mounts the
root file system read-write later (e.g. after fsck'ing it).
read-write
This specifies that the root file system should be mounted read-
write.
root=root-device
This specifies the device that should be mounted as root.
initrd=filename
Specifies the file that will be loaded at boot time as the ini‐
tial RAM disk. Example:
initrd=/images/initrd.img
yaboot will not decompress the initial ramdisk, the Linux kernel
will do that. If the initial ramdisk does not fit on one media
(usually floppy), you can split it into several pieces and sepa‐
rate the filenames in the list by | characters. In this case,
you have to provide a non-zero initrd-size and, if the images
reside on different medias, initrd-prompt as well. Example (on
the first floppy is initrd1.img, on the second initrd2.img
always in the root directory and the sum of both image sizes is
1700000 bytes):
initrd=/initrd1.img|/initrd2.img
initrd-size=1700000
initrd-prompt
initrd-size=size
When more than one initial ramdisk part is specified in the ini‐
trd setting, this option is required to be the sum of sizes of
all the images mentioned on that line, in bytes. It is required
so that yaboot can reserve space for the image, even though size
of some parts has not been determined yet.
initrd-prompt
If more than one initial ramdisk part is specified, wait for
user pressing a key between loading the different images, so
that the user can exchange media. This flag is needed if some
initrd parts reside on the same device, but different removable
media. On the other side, if you e.g. load one part from a
floppy and the second part from a hard disk, such option is not
needed (the question is who'd write something like that into
yaboot.conf).
pause-after
If this flag is specified, yaboot will stop after loading the
kernel (and initial ramdisks if specified) and ask the user to
press a key before continuing.
pause-message=string
If pause-after is specified, this variable specifies the string
to print to the user when asking him to press a key. The default
is:
Press ENTER to continue.
sysmap=filename
Specifies the path for the System.map file that goes with the
kernel image (image=). This is for 2.4 kernels with a kernel
debugger only.
single-key
Enables booting the image by hitting a single key when the cur‐
sor is at the first character in the input line, without the
need to press <ENTER> afterwards. single-key requires that
either the image's label or its alias (or both) is a single
character. If you need to specify parameters for such an image,
or if you want to boot some other image which happens to start
with the same letter, then you need to start the input line with
at least one space which will be removed before processing but
will disable this single-key feature.
restricted
Restricted limits the ability to customize command line argu‐
ments. restricted has no effect if password= is not specified.
A password is only required to boot the image specified in
/etc/yaboot.conf if parameters are specified on the command line
or if the user enters an image that is not specified in the con‐
figuration file at all (arbitrary file load). For an image not
including the restricted keyword (unless restricted is in the
global section), the password will be required. If restricted
is in the global section, all boot labels act as above (duh:).
EXAMPLES
Here is an example yaboot.conf file:
boot=/dev/hda2
device=hd:
root=/dev/hda3
partition=3
timeout=20
install=/usr/lib/yaboot/yaboot
magicboot=/usr/lib/yaboot/ofboot
fgcolor=black
bgcolor=green
default=Linux
defaultos=linux
password=secret
image=/boot/vmlinux
label=Linux
read-only
restricted
image=/boot/vmlinux.old
label=linux.old
read-only
macos=hd:9
macosx=/dev/hda10
NOTES
The format defined in this man page will not work with versions of
yaboot(8) older then 0.6. The color options only work with yaboot 1.0
and later.
BUGS
Some yaboot options may not be implemented fully.
AUTHORS
This man page was derived from silo.conf(5) written by Jakub Jelinek
and the SparcLinux team, and modified for yaboot(8)/ybin(8) by Ethan
Benson.
yaboot(8) was written by Benjamin Herrenschmidt <benh@kernel.crash‐
ing.org>.
ybin(8) was written by Ethan Benson <erbenson@alaska.net>.
SEE ALSObootstrap(8), chmod(1), hfsutils(1), mkofboot(8), mount(8),
nvsetenv(8), ofpath(8), yaboot(8), ybin(8).
GNU/Linux PowerPC 28 October 2001 YABOOT.CONF(5)
