What is macvdmtool?

It is a tool from the AsahiLinux project that lets you put an Apple Silicon Mac in DFU mode with a simple set of terminal commands.

Note: macvdmtool requires that you have two Apple silicon machines on hand. One acts as the “host” machine which initiates the “target” machine to perform a restore.

Setting up and using macvdmtool

  1. Install Xcode and the Xcode commandline tools.

  2. Install Apple Configurator 2 from the Mac App Store.

  3. Clone macvdmtool

    git clone https://github.com/AsahiLinux/macvdmtool.git

  4. Change into the macvdmtool directory and compile the tool

    ~ % cd macvdmtool && make
cc -o macvdmtool main.o -framework CoreFoundation -framework IOKit -lc++
macvdmtool %

  5. (Optional) Copy macvdmtool to somewhere that is in the default path.

    macvdmtool % sudo cp macvdmtool /usr/local/bin
Password:
macvdmtool %

  6. Launch Apple Configuration 2 and install the “Automation Tools”.

    Install Automation Tools

    Install Automation Tools dialogue

    Install Automation Tools password prompt

  7. Connect the host and target Macs together via an official Apple USB-C charging cable. The cable must be plugged into the DFU port on both ends.

    • On the M1 Macbook Air, the DFU port is the usb-c port closest to the screen.
    • On the M1 Pro, the DFU port is the usb-c port closest to the Magsafe connector.

  8. Put the target mac in DFU mode.

    ~ % sudo macvdmtool dfu
Mac type: J313AP
Looking for HPM devices...
Found: IOService:/AppleARMPE/arm-io@10F00000/AppleT810xIO/i2c0@35010000/AppleS5L8940XI2CController/hpmBusManager@6B/AppleHPMBusController/hpm0/AppleHPMARM
Connection: Source
Status: APP
Unlocking... OK
Entering DBMa mode... Status: DBMa
Rebooting target into DFU mode... OK
Exiting DBMa mode... OK
~ %

  9. Confirm the device is in DFU mode by launching Apple Configurator 2. It should look like this.

    Apple Configurator 2 is now showing target device in DFU

  10. Grab the IPSW you want to restore from Mr. Macintosh’s database.

  11. Use cfgutil to restore that IPSW.

    ~ % cfgutil restore -I ~/Downloads/UniversalMac_12.1_21C5021h_Restore.ipsw
objc[53015]: Class AMSupportURLConnectionDelegate is implemented in both /usr/lib/libauthinstall.dylib (0x1da64c9e8) and /Library/Apple/System/Library/PrivateFrameworks/MobileDevice.framework/Versions/A/MobileDevice (0x104d782c8). One of the two will be used. Which one is undefined.
objc[53015]: Class AMSupportURLSession is implemented in both /usr/lib/libauthinstall.dylib (0x1da64ca38) and /Library/Apple/System/Library/PrivateFrameworks/MobileDevice.framework/Versions/A/MobileDevice (0x104d78318). One of the two will be used. Which one is undefined.
cfgutil: restore: target OS is 12.1

Waiting for the device [1/2] [*******************************************]  100%
Step 2 of 2: Installing System [2/2] [**********************************>]  99%

At this point you’ll see an Apple logo and a loading bar on the target mac.

After a few minutes, the Mac will reboot and launch the standard Setup Assistant experience.

That’s it! Enjoy.

Future automation enhancements

  • Once Apple adds 12.X IPSWs to the com_apple_macOSIPSW.xml feed, I could write a script to download the latest IPSW and then execute macvdmtool and cfgutil.
  • Autopkg recipe to download latest IPSW and package it with Munki. This could be useful to distribute IPSWs to technicians.

Have a question, clarification, or comment?

File an issue or PR (pull request) against my blog at https://github.com/discentem/blog-content or reach out via MacAdmins Slack.

Further Readings on DFU

See Mr. Macintosh’s excellent blog post on DFU restores for more information.