yaboot.conf - Configuration file format used by yaboot(8) and
ybin(8).
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 kernels to load and what options to pass to them.
yaboot reads and parses its configuration file found on the
bootstrap(8) partition on PowerMacs, and directly from the root
filesystem on IBM PowerPC hardware. On PowerMacs you must run the
ybin(8) command each time you modify /boot/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.
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 = character,
optional whitespace, the value and required newline. IMPORTANT:
ybin(8) specific options do not support embedded spaces. 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 format 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
OpenFirmware 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 /boot/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 table
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 second,
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
bootstrap(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
double 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
backslashes) is converted to a backslash. Inside quoted strings, only double
quotes, backslashes and newlines can be escaped.
Example:
# Simple yaboot.conf
boot=/dev/hda2
device=hd:
partition=3
magicboot=/usr/local/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).
/boot/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 bootstrap(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 removing the
attributes ybin(8) set to make the partition bootable by
OpenFirmware. The bootstrap partition must not be mounted anywhere
on your filesystem, ybin(8) and mkofboot(8) will refuse to
operate on it if it is mounted. On IBM hardware the bootstrap(8)
should be a type 0x41 PReP Boot partition.
- ofboot=of-path
- This option defines the OpenFirmware device path to the
bootstrap(8) partition. This is needed so the first stage
ofboot.b loader can be configured properly. It should include the
OpenFirmware path including the partition number (but not a filename).
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 undefined 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)
partition. 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 OpenFirmware. 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
automatically at boot (instead of the install file.) See man
bootstrap(8) for more information on this. As of ybin 0.22 you
should set this to /usr/local/lib/yaboot/ofboot which is a autoconfiguring
first stage loader for yaboot. It is capable of presenting 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 hardware.
- 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 boot 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 message 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 boot 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 automatically
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
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
white.
- bgcolor=string
- Specifies the background color used by yaboot(8) and the mulitboot
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/local/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 configured). This will only work if you are using
the new /usr/local/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 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 X to boot MacOSX (along with
other choices if configured). This will only work if you are using the new
/usr/local/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.
- brokenosx
- This option causes the menu entry for MacOSX to execute
\System\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 MacOS. You should not use this option if
OSX is installed on a UFS filesystem, for UFS installs you specify the OSX
bootstrap partition 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/local/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.
- enablecdboot
- This option adds an entry to the boot menu to boot from the CDROM
drive.
- enablenetboot
- This option adds an entry to the boot menu to boot from the network.
- enableofboot
- This option adds an entry to the boot 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 variable 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 metacharacters. 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 recommended 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 bootstrap(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 removing this bit) This is only
useful if the bootstrap(8) partition is MacOS mountable and you
want to discourage modification/deletion 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 overridden by input line options).
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 following 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 number 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 probing 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 unintentionally 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 variable 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 initial 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 separate 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 initrd
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 cursor 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 arguments.
restricted has no effect if password= is not specified. A
password is only required to boot the image specified in
/boot/yaboot.conf if parameters are specified on the command line
or if the user enters an image that is not specified in the configuration
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:).
Here is an example yaboot.conf file:
-
boot=/dev/hda2
device=hd:
root=/dev/hda3
partition=3
timeout=20
install=/usr/local/lib/yaboot/yaboot
magicboot=/usr/local/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
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.
Some yaboot options may not be implemented fully.
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.crashing.org>.
ybin(8) was written by Ethan Benson
<erbenson@alaska.net>.
bootstrap(8), chmod(1), hfsutils(1), mkofboot(8),
mount(8), nvsetenv(8), ofpath(8), yaboot(8),
ybin(8).