1<manpage> 2 <docdate>March 17, 2011</docdate> 3 <doctitle>com.apple.Boot.plist</doctitle> 4 <os>Darwin</os> 5 <section>5</section> 6 <names> 7 <name>com.apple.Boot.plist<desc>Configuration plist for Mac OS X booter</desc></name> 8 </names> 9 <description> 10 <p>The Mac OS X booter (<path>boot.efi</path> on EFI-based Macintosh systems) is responsible for 11 loading the initial parts of the operating system into memory and executing them. Its default 12 behavior is to start up Mac OS X in graphical mode. However, certain behavior can be 13 configured using the <path>com.apple.Boot.plist</path> file, as well as NVRAM variables, 14 EFI boot options, and keyboard "snag keys". 15 </p> 16 <p>The <path>com.apple.Boot.plist</path> is a standard <manpage>plist<section>5</section></manpage> 17 format Core Foundation property list stored in XML format. Keys are generally strings like <command>Kernel Flags</command>, 18 with either string or integer values. The following key-values are currently supported: 19 </p> 20 <dl> 21 <dt><command>Kernel Flags</command></dt><dd>[string] This option specifies arguments to be passed 22 directly to the kernel to change its behavior (although some kernel options are parsed by the 23 booter as well for correctness). Common options include "debug=0x144" to enable kernel debugging, 24 "-v" to enable verbose boot, "-s" to boot to single user mode, "cpus=1" to simulate a 25 single core system, and "maxmem=1024" to cap available memory to 1024 MB RAM. All desired options 26 should be space-separated within the <string> tag. The default value is the empty string.</dd> 27 28 <dt><command>MKext Cache</command></dt><dd>[string] This option specifies the mkext file 29 to be loaded, which contains kernel extensions. The path uses backslash ("\") path delimeters. 30 The default value is <path>System\Library\Caches\com.apple.kext.caches\Startup\Extensions.mkext</path>.</dd> 31 32 <dt><command>Kernel</command></dt><dd>[string] This option specifies the kernel file to 33 be loaded. The path uses backslash ("\") path delimeters. The default 34 value is <path>mach_kernel</path>.</dd> 35 36 <dt><command>Kernel Cache</command></dt><dd>[string] This option specifies the prelinked 37 kernel file to be loaded, which contains both the kernel and kernel extensions, linked 38 at their final load addresses. The path uses backslash ("\") path delimeters. The 39 default value is calculated programmatically using 40 <path>System\Library\Caches\com.apple.kext.caches\Startup\kernelcache_${ARCH}.${CHECKSUM}</path> 41 as the template, where ${ARCH} is the architecture of the kernel ("i386" or "x86_64") and 42 ${CHECKSUM} is a 32-bit hash of characteristics of the boot volume and machine hardware.</dd> 43 44 <dt><command>Kernel Architecture</command></dt><dd>[string] This option specifies which kernel 45 architecture to use when the kernel file is a universal binary and the hardware supports 46 more than one kernel architecture. It can be either "i386" or "x86_64" to choose the respective 47 slice of the universal binary. If the kernel is not a universal binary, this option has 48 no effect. If the hardware only supports the 32-bit kernel, this option has no effect. The default 49 value is determined programmatically based on the hardware, and whether Mac OS X Server 50 is being used.</dd> 51 52 <dt><command>Root UUID</command></dt><dd>[string] This option is rarely used and specifies 53 to the kernel what block device should be probed as the root filesystem ("/"), and is most 54 commonly overriden by the OS installation software when installing onto AppleRAID volumes. It can be 55 either a filesystem volume UUID, as represented by <command>diskutil info</command>, or 56 a GPT partition UUID. The default is generated programmatically based on which filesystem 57 the booter itself was loaded from.</dd> 58 </dl> 59 60 <p>Since the <path>com.apple.Boot.plist</path> file exists on the root filesystem, it is tied to that 61 OS volume, and is no longer honored if Startup Disk or <manpage>bless<section>8</section></manpage> 62 is used to change the boot preference to another volume. 63 </p> 64 65 <p>The <command>Kernel Flags</command> options can also be specified via <arg>--option</arg> 66 to <manpage>bless<section>8</section></manpage>, which encodes 67 the string in the EFI boot options along with the 68 OS boot volume preference. The space-separated strings 69 are merged with kernel flags specified in the 70 <path>com.apple.Boot.plist</path> and NVRAM. 71 </p> 72 73 <p>At boot time, the booter checks to see if certain keys are being pressed, and alters behavior accordingly. 74 This is in addition to similar functionality that the firmware itself may implement before starting the 75 booter. Since pressing keys requires physical interaction, they take precendence over preferences 76 set through other means, including the <path>com.apple.Boot.plist</path> file and NVRAM. 77 The following key combinations are currently supported: 78 </p> 79 <dl> 80 <dt><command>Shift</command></dt><dd>Boot in Safe Mode. Effectively the same as passing "-x" in 81 <command>Kernel Flags</command>, and causes most caches to be ignored by the booter.</dd> 82 83 <dt><command>Command-S</command></dt><dd>Boot in Single User Mode. Effectively the same as passing "-s" in 84 <command>Kernel Flags</command>, and causes the system to boot to an interactive shell 85 with no system services started.</dd> 86 87 <dt><command>Command-V</command></dt><dd>Boot in Verbose Mode. Effectively the same as passing "-v" in 88 <command>Kernel Flags</command>, and causes the system to boot to verbose text logging before 89 starting the graphical user interface.</dd> 90 91 <dt><command>Command-R</command></dt><dd>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.</dd> 92 93 <dt><command>3 2</command></dt><dd>Boot with the 32-bit kernel. Effectively the same as passing 94 "arch=i386" in <command>Kernel Flags</command>, and causes the system to prefer the 32-bit 95 kernel on systems that would otherwise boot the 64-bit kernel.</dd> 96 97 <dt><command>6 4</command></dt><dd>Boot with the 64-bit kernel (if supported on this system). Effectively the same as passing 98 "arch=x86_64" in <command>Kernel Flags</command>, and causes the system to prefer the 64-bit 99 kernel on systems that would otherwise boot the 32-bit kernel. If the 64-bit kernel is not supported, the option is ignored.</dd> 100 </dl> 101 102 </description> 103 <environment> 104 <p>The Mac OS X booter can also be controlled by NVRAM variables, which are analogous 105 to environment variables. NVRAM variables are key-value pairs. The "boot-args" NVRAM variable 106 can be used to provide additional arguments to the kernel, and will be merged with 107 <command>Kernel Flags</command> in the <path>com.apple.Boot.plist</path> file and 108 EFI boot options set with <manpage>bless<section>8</section></manpage>. 109 </p> 110 111 <p> 112 Since NVRAM variables are system-wide, they are consulted regardless of what OS volume is 113 set as the boot preference. NVRAM variables are persistent even when the boot preference 114 is changed by Startup Disk or <manpage>bless<section>8</section></manpage>. 115 </p> 116 </environment> 117 <files> 118 <file>/Library/Preferences/SystemConfiguration/com.apple.Boot.plist<desc>Location of the <path>com.apple.Boot.plist</path> file.</desc></file> 119 </files> 120 <seealso> 121 <manpage>nvram<section>8</section>, </manpage> 122 <manpage>bless<section>8</section>, </manpage> 123 <manpage>kextcache<section>8</section></manpage> 124 </seealso> 125</manpage> 126