OS X Recovery Partition: Customizing With Different Apps

Originally, I wanted to use Casper Imaging  from the Recovery partition.  So this post is based off of this article and this feature request on JAMF Nation.  At the end, I realized I probably wouldn’t be able to add this app to the Recovery HD until JAMF updates it to 64-bit.  However, this process seems to work for other 64-bit apps.  The example I use in this walkthrough is Calculator.app.

Requirements For This Walkthrough

Materials

  1. Mac

Downloads

Knowledge, Skills, and Abilities

  • Ability and confidence to enter commands in the Terminal, adjusting them to suit your environment, if necessary
  • Familiarity with disk partitioning and mounting/unmounting volumes
  • Ability to edit plist files
  • Knowledge of OS X file system

Resources

Warnings

  • Use a test machine for this as you will be overwriting data and possibly creating partitions
  • You will not be able to use Cmd+R to boot to your custom Recovery HD (unless you use the dmtest tool)
  • Last tested on 10.9.2

Download Install OS X Mavericks.app

  1. Download the app to ~/Desktop
  2. Right-click Install OS X Mountain Lion.app
  3. Choose Show Package Contents
  4. Copy SharedSupport/InstallESD.dmg  to ~/Desktop

Mount InstallESD.dmg to Find The Recovery HD Image

  1. Run the command
    defaults write com.apple.finder AppleShowAllFiles TRUE;killall Finder
  2. Double-click InstallESD.dmg  to mount it
  3. Copy BaseSystem.dmg  and BaseSystem.chunklist  to the Desktop (both are hidden files)
  4. Eject Mac OS X Install ESD

Mount BaseSystem.dmg to Make A Read/write Copy of it

  1. Double-click ~/Desktop/BaseSystem.dmg  to mount it
  2. Open Disk Utility
  3. Highlight OS X Base System 
  4. Click New Image
  5. Adjust the settings as follows:
    • Save As: OS X Base System RW
    • Where: Desktop
    • Image Format: read/write
    • Encryption: none
  6. Eject Mac OS Base System
  7. Quit Disk Utility

Backup the Read/write Image

In case a mistake is made, it would be a good idea to make a copy of the read/write version of the .dmg.

  1. Right-click ~/Desktop/Mac OS X Base System RW.dmg
  2. Choose Duplicate
  3. Save it somewhere safe

Mount the Read/write Base System to Make Customizations

  1. Double-click ~/Desktop/Mac OS X Base System RW.dmg  to mount it
  2. Rename the mounted volume as Mac OS X Base System RW  so it won’t get mixed up with the original

Add Calculator.app

  1. Copy over Calculator.app (or any 64-bit app) into either /Volumes/Mac OS X Base System RW/Applications  or /Volumes/Mac OS X Base System RW/Applications/Utilities jacob_salmela_calcinrecovery
  2. Copy over /System/Library/PrivateFrameworks/Calculate.framework/  from your main system into the same path inside the Base System RW disk image (I’ll explain this a bit more later).
  3. If need be, you can check what architecture the app is with the Get Info dialog or running the command:
    lipo -info /Applciations/<app_name>/Contents/Mac\ OS/<app_name>

Modify the Utilities.plist to Have Calculator.app Show in The Utilities When Booted To the Recovery HD

One important step here is that the BundlePath  point to just the .app and the Path  points to the actual binary inside the .app.

  1. Open /Volumes/Mac OS X Base System RW/System/Installation/CDIS/OS X Utilities.app/Contents/Resources/Utilities.plist  in Xcode or another plist editor
  2. Duplicate one of the keys under the Buttons section
  3. Expand the duplicated item
  4. Edit the BundlePath  to point to /Applications/Utilities/Calculator.app jacob_salmela_utiltiesplist
  5. Edit the description to make sense
  6. Edit the Path  to point to /Applications/Utilities/Calculator.app/Contents/MacOS/Calculator
  7. Edit the paths for any app added in the previous step
  8. Repeat the process for any other apps added in
  9. Save the changes

Convert the Custom Volume Back to Read-only

During my experiments, I was never able to get a the read/write version of the disk image to restore to a partition.  I always got the resource busy error.  It seems to work fine once it is converted back to read-only.

  1. Temporarily rename /Volumes/Mac OS X Base System RW  to /Volumes/CustomRecovery
  2. Open Disk Utility
  3. Highlight the Mac OS X Base System RW.dmg (not the volume that was just renamed)
  4. Click Convert
  5. Adjust the settings as follows:
  • Save As: Custom Recovery.dmg
  • Where: Desktop
  • Image Format: read-only
  • Encryption: none

A Fork in the Road

Here you have two ways to add your recovery partition:

  • Restore using Apple’s dmtest  to retain Cmd+R functionality during boot
  • Restore using Disk Utility, where holding Option at boot will let you boot to this volume

I’ll show the dmtest  way first, since that will be most useful and is also a bit easier. The Disk Utility method might be easier for cloning or capturing the volume.  This could also be used if you wanted to have the Recovery HD on a USB drive or some other location.

Method One: Restore The CustomRecovery Using dmtest

Retain Cmd+R boot keystroke to boot to the Recovery

You can download dmtest  (Lion) (Mavericks) from me, or manually extract it from the recovery update using the instructions below:

  1. Download the Lion Recovery Update V1.0 (Yosemite Recovery Update is distributed via the App Store, so if you want to be able to extract the tool from there, take a look at Saving App Store Downloads As .pkgs–which is how I got the Yosemite dmtest  tool)
  2. Run the following commands
hdiutil mount ~/Downloads/RecoveryHDUpdate.dmg
pkgutil --expand /Volumes/Mac\ OS\ X\ Lion\ Recovery\ HD\ Update/RecoveryHDUpdate.pkg ~/Desktop/recoveryupdate
cp ~/Desktop/recoveryupdate/RecoveryHDUpdate.pkg/Scripts/Tools/dmtest ~/Desktop
umount /Volumes/Mac\ OS\ X\ Lion\ Recovery\ HD\ Update/
sudo dmtest ensureRecoveryPartition / ~/Desktop/CustomRecovery.dmg 0 0 ~/Desktop/BaseSystem.chunklist

If you get the error

Error (async): The new recovery partition would be too large (-69668)

Then you will need to trim down the content on the .dmg (maybe by removing unneeded apps liek Safari (~34MB), or Disk Utility (~21MB), Install OS X Yosemite (~8MB) etc.)

Others have mentioned that these two commands need to also be run in order to clean things up, clear the cache, and make the system recognize the new partition, but in my testing, it worked fine without doing these:

sudo touch /Library/Preferences/SystemConfiguration/com.apple.Boot.plist
sudo kextcache -f -u /

Method Two: Restore The CustomRecovery Using Disk Utility

Disables Cmd+R during boot, but you could restore this to any partition and boot to it.

Caution here.  This will overwrite any existing data.  Hopefully, you are using a test machine to try this.  Also, if you restore this way, the Cmd+R boot keystroke will not work, you need to hold Option to get into it.

  1. Open Disk Utility
  2. Highlight CustomRecovery.dmg
  3. Click Images > Scan Image for Restore
  4. Highlight  CustomRecovery.dmg again
  5. Click the Restore tab
  6. Drag an empty partition into the Destination fieldjacob_salmela_diskutility_customrestore
  7. Click Restore
  8. Click Erase
  9. Notice the name of the partition is now changed to CustomRecovery: a visual clue that the partition now has the CustomRecovery on itcustomrecoverypartition

Reboot Into the New Partition to Test it Before Moving Forward

  1. Reboot the Mac holding Option
  2. Select the Custom Recovery partition created in the previous stepjacob_salmlela_customrecoveryboot

Success!

jacob_salmela_appinrecovery

Copy Over Frameworks if an App Does Not Launch in the Recovery Partition

Since the Recovery Partition is a slimmed down version of OS X, it does not have all the lower-level files needed to run some apps.  If you launch an app from Recovery and it doesn’t open, you may need to do some digging to find the frameworks needed to run it.  The steps below are how I found out what the Calculator.app needed to run.

  1. Open Terminal when booted to the Recovery partition
  2. Type /Applications/Calculator.app/Contents/MacOS/Calculator
  3. View the output to see if there are mentions of any missing frameworks
  4. Reboot back into OS X
  5. Follow the steps to edit the read/write partition but instead of adding an app, copy over the framework.  In the case of Calculator.app, we need to copy over /System/Library/PrivateFrameworks/Calculate.framework/  See the output below from trying to run the Calculator binary:
    Library not loaded: /System/Library/PrivateFrameworks/Calculate.framework/Versions/A/Calculate

    calculator error

21 Replies to “OS X Recovery Partition: Customizing With Different Apps”

  1. I used the following guide to install 10.8.5 on an old MBP 2,2.

    http://forums.macrumors.com/showthread.php?p=19670444#post19670444

    Then I tried to follow your guide to make a custom Recovery partition with my boot.efi-files. But ran into some problems. I had already created a regular (non working) recovery with Silvertooths Recovery Partition Creator 3.8.

    At first I tried the Lion dmtest, which just gave me random async errors. But when I tried the dmtest from mavericks it instructed that the image was too large for the partition. But after removing the partition with Recovery Editor found here:

    http://forums.macrumors.com/showthread.php?t=1606779

    dmtest was able to run successfully and created a larger partition. But I had to run dmtest twice to make it work, first time it almost always gave me:

    Error (async): Invalid request (-69886)

  2. So eventually, you got it to work?

    I think each version of the recovery hd that Apple has released is slightly bigger than the previous. For example the Lion recovery was ~650MB and the one from Mavericks is ~815MB, so if your previous partition was not large enough, the newer version would not fit.

    I have seen similar errors on devices using CoreStorage, but since you are using an older MBP, I’m not sure what that would be.

    In any event, I’m glad it works!

    1. Yes, it worked! If I ran dmtest twice, maybe some problem with mounting.

      The only issue is that I couldn’t get my replacement ATI kexts and OpenCL/GL frameworks to work. Maybe it’s an issue with rebuilding kernel cache that I don’t know how to do in an image, removing the kernelcache-file didn’t help. But hw rendering isn’t really needed in recovery.

        1. I’m not fluent with the kextcache command but I tried at least one after booting into recovery. Had to remount though with “mount -uw /”. Maybe I’ll look into it further and try again.

  3. So glad that I came across your post. I believe you may be the only person to write specifically about how to add programs to the recovery drive. I’m attempting to make a 10.11 recovery thumb drive. (Have you resolved your Casper Imaging 32 bit hurdle?)

    My problem is that only one added program (DiskWarrior) launches and other added programs don’t (coconutBattery, Smart Utility, Xfolders, Malwarebytes). They all do show up as buttons. All native apps launch fine from buttons. When launching in my OS (10.10 or 10.11), no problem launching from terminal through the thumb recovery drive image. When booting into the thumb recovery drive and launch through Terminal I get one of two errors; ‘Killed: 9’ or ‘code signature invalid’. I’ve added a fresh copy of Sparkle.framework to the Framework folder (for coconutBattery), and the issue persists. I’m guessing the Killed 9 is a security block. I’ve also tried making a 10.10 drive and the issue is the same. I know this is an older post and any insight that you have is greatly appreciate.

    -bash-3.2# ls /Applications/
    .DS_Store OmniDiskSweeper.app Utilities
    Disk Utility.app SMART Utility.app Xfolders.app
    DiskWarrior.app Safari.app coconutBattery.app
    Malwarebytes.app Terminal.app

    -bash-3.2# /Applications/OmniDiskSweeper.app/Contents/MacOS/OmniDiskSweeper
    Killed: 9

    -bash-3.2# /Applications/coconutBattery.app/Contents/MacOS/coconutBattery
    dyld: Library not loaded:
    @loader_path/../Frameworks/Sparkle.framework/Versions/A/Sparkle
    Referenced from:
    /Applications/coconutBattery.app/Contents/MacOS/coconutBattery
    Reason: no suitable image found. Did find:
    /Applications/coconutBattery.app/Contents/MacOS/../Frameworks/Sparkle.framework/Versions/A/Sparkle:
    code signature invalid for
    ‘/Applications/coconutBattery.app/Contents/MacOS/../Frameworks/Sparkle.framework/Versions/A/Sparkle’

    /Applications/coconutBattery.app/Contents/MacOS/../Frameworks/Sparkle.framework/Versions/A/Sparkle:
    code signature invalid for
    ‘/Applications/coconutBattery.app/Contents/MacOS/../Frameworks/Sparkle.framework/Versions/A/Sparkle’

    Trace/BPT trap: 5

    1. It has been increasingly difficult to add and run apps with each new Recovery HD Apple releases. I never got over the 32-bit hurdle with Casper Imaging either.

      I suspect Apple is putting in more security measures to prevent apps from running. I also noticed that some apps need access to the Finder or other frameworks, which you can sometimes add to the image and get them to work. It’s a lot of work, though.

      As for the killed 9, I recall that having something to do with running out of memory or something but my hu-man memory is flawed.

  4. Very interesting article, I didn’t knew about the dmtest tool.

    What I was thinking of doing and looking information for before I landed here was to add certain apps to the recovery partition just by copying them and their dependencies from the main HD using Terminal while booted into recovery mode.

    Any reasons why that wouldn’t work?

    1. Back in 10.7, it was much easier. Newer versions of OS X have really locked things down. I haven’t tried for a long time, so I cannot say for certain.

      1. So far I found that I can’t write to /Applications when booted in the recovery partition, seems to be mounted read only but didn’t try remounting.
        But I figured the system uses a lot of ram disk when in recovery mode. So I tried creating a ram disk of my own, and copying the app I was interested in running there. Then I was able to unmount the main system disk and run this app without problem, so that is an option right there as long as the app is self-contained and doesn’t depend on other frameworks.

      2. So far I found that I can’t write to /Applications when booted in the recovery partition, seems to be mounted read only but didn’t try remounting.
        But I figured the system uses a lot of ram disk when in recovery mode. So I tried creating a ram disk of my own, and copying the app I was interested in running there. Then I was able to unmount the main system disk and run this app without problem, so that is an option right there as long as the app is self-contained and doesn’t depend on other frameworks.

  5. Jacob, isn’t Recovery HD locked to certain size? Is it possible to create a custom Recovery with let’s say 1 Gb, to be able to add more apps, restore it to usb, and boot from it?

      1. So if I want to restore it to USB 16 Gb there shouldn’t be a problem to add more applications?

  6. I don’t understand this part:

    “Double-click ~/Desktop/Mac OS X Base System RW.dmg to mount it

    Rename the mounted volume as Mac OS X Base System RW so it won’t get mixed up with the original.”

    Rename Mac OS X Base System RW to Mac OS X Base System RW? The same name?

    1. The .dmg has the name Mac OS X Base System RW, but when you actually mount it, the volume is still named Mac OS X Base System. So if you rename it after it’s mounted, you won’t get them mixed up.

Leave a Reply