Mac Developer Library Developer


This manual page is for Mac OS X version 10.9

If you are running a different version of Mac OS X, view the documentation locally:

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.     BSD File Formats Manual

NAME -- Configuration plist for Mac OS X booter

     The Mac OS X booter ( boot.efi on EFI-based Macintosh systems) is responsible for loading the initial
     parts of the operating system into memory and executing them. Its default behavior is to start up Mac
     OS X in graphical mode. However, certain behavior can be configured using the
     file, as well as NVRAM variables, EFI boot options, and keyboard "snag keys".

     The is a standard plist(5) format Core Foundation property list stored in XML for-mat. format.
     mat. Keys are generally strings like Kernel Flags, with either string or integer values. The following
     key-values are currently supported:

     Kernel Flags
            [string] This option specifies arguments to be passed directly to the kernel to change its
            behavior (although some kernel options are parsed by the booter as well for correctness). Common
            options include "debug=0x144" to enable kernel debugging, "-v" to enable verbose boot, "-s" to
            boot to single user mode, "cpus=1" to simulate a single core system, and "maxmem=1024" to cap
            available memory to 1024 MB RAM. All desired options should be space-separated within the
            <string> tag. The default value is the empty string.

     MKext Cache
            [string] This option specifies the mkext file to be loaded, which contains kernel extensions.
            The path uses backslash ("\ ") path delimeters. The default value is System\ Library\ Caches\
  \ Startup\ Extensions.mkext.

            [string] This option specifies the kernel file to be loaded. The path uses backslash ("\ ") path
            delimeters. The default value is mach_kernel.

     Kernel Cache
            [string] This option specifies the prelinked kernel file to be loaded, which contains both the
            kernel and kernel extensions, linked at their final load addresses. The path uses backslash ("\
            ") path delimeters. The default value is calculated programmatically using System\ Library\
            Caches\\ Startup\ kernelcache_${ARCH}.${CHECKSUM} as the template, where
            ${ARCH} is the architecture of the kernel ("i386" or "x86_64") and ${CHECKSUM} is a 32-bit hash
            of characteristics of the boot volume and machine hardware.

     Kernel Architecture
            [string] This option specifies which kernel architecture to use when the kernel file is a uni-versal universal
            versal binary and the hardware supports more than one kernel architecture. It can be either
            "i386" or "x86_64" to choose the respective slice of the universal binary. If the kernel is not
            a universal binary, this option has no effect. If the hardware only supports the 32-bit kernel,
            this option has no effect. The default value is determined programmatically based on the hard-ware, hardware,
            ware, and whether Mac OS X Server is being used.

     Root UUID
            [string] This option is rarely used and specifies to the kernel what block device should be
            probed as the root filesystem ("/"), and is most commonly overriden by the OS installation soft-ware software
            ware when installing onto AppleRAID volumes. It can be either a filesystem volume UUID, as rep-resented represented
            resented by diskutil info, or a GPT partition UUID. The default is generated programmatically
            based on which filesystem the booter itself was loaded from.

     Since the file exists on the root filesystem, it is tied to that  OS volume, and
     is no longer honored if Startup Disk or bless(8) is used to change the boot preference to another vol-ume. volume.

     The Kernel Flags options can also be specified via --optionto bless(8), which encodes the string in the
     EFI boot options along with the OS boot volume preference. The space-separated strings are merged with
     kernel flags specified in the and NVRAM.

     At boot time, the booter checks to see if certain keys are being pressed, and alters behavior accord-ingly. accordingly.
     ingly. This is in addition to similar functionality that the firmware itself may implement before
     starting the booter. Since pressing keys requires physical interaction, they take precendence over
     preferences set through other means, including the file and NVRAM. The following
     key combinations are currently supported:

     Shift  Boot in Safe Mode. Effectively the same as passing "-x" in Kernel Flags, and causes most caches
            to be ignored by the booter.

            Boot in Single User Mode. Effectively the same as passing "-s" in Kernel Flags, and causes the
            system to boot to an interactive shell with no system services started.

            Boot in Verbose Mode. Effectively the same as passing "-v" in Kernel Flags, and causes the sys-tem system
            tem to boot to verbose text logging before starting the graphical user interface.

            Boot in Recovery Mode.  This causes the system to boot into special Recovery System image, which
            can be used used to restore the system from Time Machine Backup, re-install Mac OS X, or use
            Disk Utility to repair or erase disks.

     3 2    Boot with the 32-bit kernel. Effectively the same as passing "arch=i386" in Kernel Flags, and
            causes the system to prefer the 32-bit kernel on systems that would otherwise boot the 64-bit

     6 4    Boot with the 64-bit kernel (if supported on this system). Effectively the same as passing
            "arch=x86_64" in Kernel Flags, and causes the system to prefer the 64-bit kernel on systems that
            would otherwise boot the 32-bit kernel. If the 64-bit kernel is not supported, the option is

     The Mac OS X booter can also be controlled by NVRAM variables, which are analogous to environment vari-ables. variables.
     ables. NVRAM variables are key-value pairs. The "boot-args" NVRAM variable can be used to provide addi-tional additional
     tional arguments to the kernel, and will be merged with Kernel Flags in the file
     and EFI boot options set with bless(8).

     Since NVRAM variables are system-wide, they are consulted regardless of what OS volume is set as the
     boot preference. NVRAM variables are persistent even when the boot preference is changed by Startup
     Disk or bless(8).

             Location of the file.

     nvram(8), bless(8), kextcache(8)

Darwin                          March 17, 2011                          Darwin

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.