1.Dd May 24, 2013 2.Os "Mac OS X" 3.Dt BLESS 8 4.Sh NAME 5.Nm bless 6.Nd set volume bootability and startup disk options 7.Sh SYNOPSIS 8.Nm bless 9.Fl -help 10.Pp 11.Nm bless 12.Fl -folder Ar directory 13.Op Fl -file Ar file 14.Op Fl -bootinfo Op Ar file 15.Op Fl -bootefi Op Ar file 16.Op Fl -label Ar name | Fl -labelfile Ar file 17.Op Fl -setBoot 18.Op Fl -openfolder Ar directory 19.Op Fl -nextonly 20.Op Fl -shortform 21.Op Fl -legacy 22.Op Fl -legacydrivehint Ar device 23.Op Fl -options Ar string 24.Op Fl -quiet | -verbose 25.Pp 26.Nm bless 27.Fl -mount Ar directory 28.Op Fl -file Ar file 29.Op Fl -setBoot 30.Op Fl -nextonly 31.Op Fl -shortform 32.Op Fl -legacy 33.Op Fl -legacydrivehint Ar device 34.Op Fl -options Ar string 35.Op Fl -quiet | -verbose 36.Pp 37.Nm bless 38.Fl -device Ar device 39.Op Fl -label Ar name | Fl -labelfile Ar file 40.Op Fl -startupfile Ar file 41.Op Fl -setBoot 42.Op Fl -nextonly 43.Op Fl -shortform 44.Op Fl -legacy 45.Op Fl -legacydrivehint Ar device 46.Op Fl -options Ar string 47.Op Fl -quiet | -verbose 48.Pp 49.Nm bless 50.Fl -netboot 51.Fl -server Ar url 52.Op Fl -nextonly 53.Op Fl -options Ar string 54.Op Fl -quiet | -verbose 55.Pp 56.Nm bless 57.Fl -info Op Ar directory 58.Op Fl -getBoot 59.Op Fl -plist 60.Op Fl -quiet | -verbose 61.Op Fl -version 62.Pp 63.Nm bless 64.Fl -unbless Ar directory 65.Sh DESCRIPTION 66.Nm bless 67is used to modify the volume bootability characteristics of filesystems, as well 68as select the active boot volume. 69.Nm bless 70has 6 modes of execution: Folder Mode, Mount Mode, Device Mode, NetBoot Mode, 71Info Mode, and Unbless Mode. 72.Pp 73Folder Mode allows you to select a directory on a mounted 74volume to act as the 75.Do blessed Dc 76directory, which causes the system firmware to look in that directory 77for boot code. EFI-based systems also support a 78.Do blessed Dc 79system file, which is the primary mechanism of specifying the booter for 80a volume for those systems. In Folder Mode, if you are operating on an HFS+ 81volume, the HFS+ Volume Header is updated to reflect the files/directories 82given, which persists even if the volume is moved to another system or NVRAM 83is cleared. 84.Pp 85Mount Mode does not make permanent modifications to the filesystem, but rather 86set the system firmware to boot from the 87specified volume, assuming it has been properly blessed. This is a subset of 88the functionality of Folder Mode with the 89.Fl -setBoot 90option, but is convenient when you don't want to change or interrogate 91the filesystem for its blessed status. 92.Pp 93Device Mode is similar to Mount Mode, but allows selection of unmounted 94filesystems, for instance while in single user mode. It can also perform 95certain offline modifications to the filesystem, but is not generally recommended. 96.Pp 97NetBoot Mode sets the system firmware to boot from the network, using a 98URL syntax to specify the protocol and server. 99.Nm 100only sets the local system to go into NetBoot mode, and does not communicate 101to the server what image should be used, if there are multiple images. Some 102other mechanism, such as using Startup Disk, should be used to select that. 103.Pp 104Info Mode will print 105out the currently\-blessed directory of a volume, or if no mountpoint is 106specified, the active boot volume that the firmware is set to boot from. 107.Pp 108Unbless Mode complements Folder Mode, and clears the persistent blessed 109folder and file information on HFS+ volumes. 110.Pp 111Additionally, 112.Fl -help 113can be used to display the command-line usage summary. 114.Ss FILE/FOLDER MODE 115Folder Mode has the following options: 116.Bl -tag -width "xxopenfolderxdirectoryx" -compact 117.It Fl -folder Ar directory 118Set this directory to be the Mac OS X/Darwin blessed directory, containing a 119.Pa BootX 120secondary loader for New World machines. 121.It Fl -file Ar file 122Set this file to be the Mac OS X/Darwin blessed boot file, containing a booter 123for EFI-based systems. If this option is not provided, a default boot file 124is used based on the blessed directory. 125.It Fl -bootinfo Op Ar file 126Create a 127.Pa BootX 128file in the Mac OS X/Darwin system folder using 129.Ar file 130as a source. If 131.Ar file 132is not provided, a default is used (see FILES), using a path relative 133to the mountpoint you are blessing. This attempts to ensure that a 134.Pa BootX 135is used that is compatible with the OS on the target volume. 136.It Fl -bootefi Op Ar file 137Create a 138.Pa boot.efi 139file in the Mac OS X/Darwin system folder using 140.Ar file 141as a source. If 142.Ar file 143is not provided, a default is used (see FILES), using a path relative 144to the mountpoint you are blessing. This attempts to ensure that a 145.Pa boot.efi 146is used that is compatible with the OS on the target volume. If 147.Fl -file 148is also provided, the new file will be created at that path instead. 149.It Fl -label Ar name 150Render a text label used in the firmware-based OS picker 151.It Fl -labelfile Ar file 152Use a pre-rendered label used for the firmware-based OS picker 153.It Fl -openfolder Ar directory 154Specify a folder to be opened in the Finder when the volume is mounted by 155the system. 156.It Fl -setBoot 157Set the system to boot off the specified partition. This is implemented in 158a platform-specific manner. On Open Firmware-based systems, the 159.Em boot-device 160variable is modified. On EFI-based systems, the 161.Em efi-boot-device 162variable is changed. 163.It Fl -nextonly 164Only change the boot device selection for the next boot. This is only supported 165on EFI-based systems. 166.It Fl -shortform 167Use an abbreviated device path form. This option can allow for booting from 168new devices, at the expense of boot time performance. This is only supported 169on EFI-based systems. 170.It Fl -legacy 171If 172.Fl -setBoot 173is given, set the firmware to boot a legacy BIOS-based operating system 174from the specified disk. The active flag of an MBR-partitioned disk is not 175modified, which can be done with 176.Xr fdisk 8 177\&. This is only supported 178on EFI-based systems. 179.It Fl -legacydrivehint Ar device 180Instruct the firmware to treat the specified whole disk as the primary, 181master IDE drive. This is only supported 182on EFI-based systems. 183.It Fl -options 184Set load options associated with the new boot option. This is only supported 185on EFI-based systems, and in general should be avoided. Instead, use 186.Xr nvram 8 187to set 188.Qo boot-args Qc 189, which will work with both Open Firmware- and EFI-based systems. 190.It Fl -quiet 191Do not print any output 192.It Fl -verbose 193Print verbose output 194.El 195.Ss MOUNT MODE 196Mount Mode has the following options: 197.Bl -tag -width "xxopenfolderxdirectoryx" -compact 198.It Fl -mount Ar directory 199Use the volume mounted at 200.Ar directory 201to change the active boot volume, in conjunction with 202.Fl -setBoot 203\&. The volume must already be properly blessed. 204.It Fl -file Ar file 205Instead of allowing the firmware to discover the booter based on the blessed 206directory or file, pass an explicit path to the firmware to boot from. This 207can be used to run EFI applications or EFI booters for alternate OSes, but 208should not be normally used. This is only supported on EFI-based systems. 209.It Fl -setBoot 210Same as for Folder Mode. 211.It Fl -nextonly 212Same as for Folder Mode. 213.It Fl -shortform 214Same as for Folder Mode. 215.It Fl -legacy 216Same as for Folder Mode. 217.It Fl -legacydrivehint Ar device 218Same as for Folder Mode. 219.It Fl -options 220Same as for Folder Mode. 221.It Fl -quiet 222Do not print any output 223.It Fl -verbose 224Print verbose output 225.El 226.Ss DEVICE MODE 227Device Mode has the following options: 228.Bl -tag -width "xxopenfolderxdirectoryx" -compact 229.It Fl -device Ar device 230Use the block device 231.Ar device 232to change the active boot volume. No volumes should be mounted from 233.Ar device 234\&, and the filesystem should already be properly blessed. 235.It Fl -label Ar name 236Set the firmware-based OS picker label for the unmounted filesystem, using 237.Ar name 238\&, which should be in UTF-8 encoding. 239.It Fl -labelfile Ar file 240Use a pre-rendered label used with the firmware-based OS picker. 241.It Fl -setBoot 242Set the system to boot off the specified partition, as with Folder and Mount 243Modes. 244.It Fl -startupfile Ar file 245Add the 246.Ar file 247as the HFS+ StartupFile, and update other information on disk as appropriate 248for the startup file type. 249.It Fl -nextonly 250Same as for Folder Mode. 251.It Fl -shortform 252Same as for Folder Mode. 253.It Fl -options 254Same as for Folder Mode. 255.It Fl -legacy 256Same as for Folder Mode. 257.It Fl -legacydrivehint Ar device 258Same as for Folder Mode. 259.It Fl -quiet 260Do not print any output 261.It Fl -verbose 262Print verbose output 263.El 264.Ss NETBOOT MODE 265NetBoot Mode has the following options: 266.Bl -tag -width "xxopenfolderxdirectoryx" -compact 267.It Fl -netboot 268Instead of setting the active boot selection to a disk-based volume, set the system 269to NetBoot. 270.It Fl -server Ar protocol://[interface@]server 271A URL specification of how to boot the system. Currently, the only 272.Em protocol 273supported is BSDP ("bsdp"), Apple's Boot Service Discovery Protocol. The 274.Em interface 275is optional, and the 276.Em server 277is the IPv4 address of the server in dotted-quad notation. If there is not 278a specific server you'd like to use, pass "255.255.255.255" to have the 279firmware broadcast for the first available server. Examples of this notation 280would be "bsdp://255.255.255.255" and "bsdp://en1@17.203.12.203". 281.It Fl -nextonly 282Same as for Folder Mode. 283.It Fl -options 284Same as for Folder Mode. 285.It Fl -quiet 286Do not print any output 287.It Fl -verbose 288Print verbose output 289.El 290.Ss INFO MODE 291Info Mode has the following options: 292.Bl -tag -width "xxopenfolderxdirectoryx" -compact 293.It Fl -info Op Ar directory 294Print out the blessed system folder for the volume mounted at 295.Ar directory 296\&. If 297.Ar directory 298is not specified, print information for the currently selected boot volume 299(which may not necessarily be 300.So 301/ 302.Sc 303\&. 304.It Fl -getBoot 305Print out the logical boot volume, based on what is currently selected. This 306option will take into account the fact that the firmware may be pointing to an 307auxiliary booter partition, and will print out the corresponding root partition 308for those cases. If the system is configured to NetBoot, a URL matching the 309format of the 310.Fl -server 311specification for NetBoot mode will be printed. 312.It Fl -plist 313Output all information in Property List (.plist) format, suitable 314for parsing by CoreFoundation. This is most useful when 315.Nm bless 316is executed from another program and its standard output must be parsed. 317.It Fl -quiet 318Do not print any output 319.It Fl -verbose 320Print verbose output 321.It Fl -version 322Print bless version and exit immediately 323.El 324.Ss UNBLESS MODE 325Unbless Mode has the following options: 326.Bl -tag -width "xxopenfolderxdirectoryx" -compact 327.It Fl -unbless Ar directory 328Use the HFS+ volume mounted at 329.Ar directory 330and unset any persistent blessed files/directories in the HFS+ Volume Header. 331.El 332.Sh FILES 333.Bl -tag -width /usr/standalone/ppc/bootx.bootinfo -compact 334.It Pa /usr/standalone/ppc/bootx.bootinfo 335Secondary loader with XML headers, used with the 336.Fl -bootinfo 337flag. Used for booting New World PPC-based Macintoshes. If the argument to 338.Fl -bootinfo 339is ommitted, this file will be used as the default input. 340.It Pa /usr/standalone/i386/boot.efi 341Booter for EFI-based systems, used with the 342.Fl -bootefi 343flag. If the argument to 344.Fl -bootefi 345is ommitted, this file will be used as the default input. 346.It Pa /System/Library/CoreServices 347Typical blessed folder for Mac OS X and Darwin 348.El 349.Sh EXAMPLES 350.Ss FOLDER MODE 351To bless a volume with only Mac OS X or Darwin, and create the BootX and 352boot.efi files as needed: 353.Bd -ragged -offset indent 354.Nm bless 355.Fl -folder 356.Qo /Volumes/Mac OS X/System/Library/CoreServices Qc 357.Fl -bootinfo 358.Fl -bootefi 359.Ed 360.Ss MOUNT MODE 361To set a volume containing either Mac OS 9 and Mac OS X to be 362the active volume: 363.Bd -ragged -offset indent 364.Nm bless 365.Fl -mount 366.Qo /Volumes/Mac OS Qc 367.Fl -setBoot 368.Ed 369.Ss NETBOOT MODE 370To set the system to NetBoot and broadcast for an available server: 371.Bd -ragged -offset indent 372.Nm bless 373.Fl -netboot 374.Fl -server 375.Ar bsdp://255.255.255.255 376.Ed 377.Ss INFO MODE 378To gather information about the currently selected volume (as 379determined by the firmware), suitable for piping to a program capable 380of parsing Property Lists: 381.Bd -ragged -offset indent 382.Nm bless 383.Fl -info 384.Fl -plist 385.Ed 386.Sh SEE ALSO 387.Xr mount 8 , 388.Xr newfs 8 , 389.Xr nvram 8 390