MDS 5 Administrator Guide

Created On
Last Updated On
byTimothy Perfitt
You are here:

Overview

MDS is a macOS application that creates the resources needed to automate the install of macOS and initial software packages. Recent Macs do not support NetBoot or booting to external drives for setup: MDS solves this problem by providing a mechanism for initially installing macOS and software packages via the recovery partition or by setting up package installation after macOS is installed

Requirements for Installing macOS

Previous versions of macOS and Mac hardware supported block-based imaging to deploy macOS and associated configuration/hardware. Due to the number of Macs that did not have up-to-date firmware, Apple introduced software and firmware limitations that require macOS to be installed with an Apple-provided macOS installer. It also required an internet connection to check for firmware updates during the install process. The macOS installer has an optional feature to install packages after macOS has been installed.

Why MDS?

MDS is based on the idea that you should be able to wipe and reinstall a Mac quickly and easily, i.e., in an automated way. Apple provides the ability to reinstall macOS from the recovery partition, but the installer must be downloaded during the install process; many manual steps must be taken in the installer screens. This is not difficult for an individual user but, for larger organizations or deployments, it can be cost prohibitive due to the setup time. Apple also provides the Deployment Enrollment Program (DEP) for initial setup and enrollment in an MDM service. However, using DEP requires both that an organization be enrolled in DEP and that all Macs be purchased and enrolled in DEP. Older machines can only be enrolled in DEP if they were purchased via the correct channel. Finally, even if a Mac is enrolled in DEP, if it needs to be reset and is not able to contact the MDM server, the OS must be manually reinstalled. This can be a labor-intensive process.

MDS works great with both DEP and MDM by preloading content. This way, your Mac is usable from the moment your new user receives it. DEP kicks off the software installation process, though this can take a long time; using MDS with DEP allows an administrator to preload all applications and settings, allowing users to skip setup at first login.

How MDS Works

MDS creates all the resources required to reinstall macOS and install software packages for enrolling in MDM. The resources are organized into workflows, which can be selected as you set up the Mac. The resources and workflows are saved to an external drive or to a disk image for copying to a web server. Once saved, the target Macs are booted to the recovery partition and a script is run from the disk image on the web server or directly from the external drive. To further automate the process, MDS can flash an Arduino to turn it into an MDS Automaton, which gives the keystrokes for automatically selecting the recovery partition and running the script.

Time Savings

Using the Automaton and the resources created by MDS, a new Mac can be set up very quickly. The new Mac is booted into recovery by powering on with the Option key held down, or by pressing and holding the power button on Apple Silicon Macs. The external drive (optional if using a web server) and Automaton are plugged into the Mac. The Mac will then proceed to erase the internal volume, copy the OS installer and packages to the Mac, and then reboot into the installer. Once this first reboot happens, the Automaton and external volume can be disconnected. 

In terms of time for technician interaction with the Mac, it takes just a few seconds to plug in the Automaton and the external drive, boot into recovery to start the startup selector, and then return a few minutes later to disconnect the Automaton and external volume. This can dramatically reduce setup time and results in large savings of both time and labor costs. This same process can be used for Macs that need to be re-setup either onsite or offsite.

MDS 5 Highlighted Features

If you’re already familiar with older versions of MDS, using MDS 5 is easy to use. For ease of access, listed here are the highlighted features included with this latest release:

Single button DFU mode

On Apple Silicon Macs, putting a Mac into DFU mode requires a complicated series of keypresses. With MDS, it is a single button. Plug in the Mac to the DFU port and press a button and the Apple Silicon Mac goes into DFU mode. Easy as that.

Automatic Restore

MDS 5 can detect a Mac plugged into the DFU port and automatically put it into DFU mode, wipe and restore macOS. An MDS workflow can then be run for final setup.

Fully Automated Mass Restoring

MDS can restore multiple Macs at once. Using the Acroname for MDS USB-C hub, up to 5 Macs can be restored simultaneously, increasing the efficiency of deployments.

Mass Restoring

Using the Single Button DFU and Apple Configurator 2 integration, Macs can be plugged into the DFU port on the Mac running MDS to put into DFU mode and then unplugged and plugged into any USB hub. Repeat and then mass restore all the macs plugged into the hub using MDS.

Licensing

MDS licensing is setup using a mobile configuration file for easy setup. The compiled, notarized, and signed version of the app now requires a license.

Apple Silicon support

With the release of macOS Big Sur 11.2, third-party utilities are now able to run in the M1 recovery mode. MDS can now automate erasing macOS, reinstalling macOS, installing software, and much more! Like on Intel Macs, all work is done upfront and you spend less than 5 minutes prepping each M1 Mac. After that, all operations are automatic. When completed, the Mac is fully set up and ready to go. If you add in the Automaton, you can reduce the time in front of an M1 Mac to less than 7 seconds!

Arduino support with Apple Silicon Macs

MDS 5 includes support for using the Automaton for fully automated setup of Apple Silicon Macs. The M1 Macs need to be in one of two states: FileVault On or FileVault Off. If FileVault is on, the Automaton will erase the Mac, then activate, then run workflows. If FileVault is off, the Automaton will open MDS Deploy to see if the drive is empty. If not, MDS Deploy will open and erase, then activate, then run the workflow. When installing macOS, the installer is now launched.

Override Workflow Options 

You can now select a script that returns the workflow to run if autorun is enabled. The basic script just returns a workflow name, but you can use any logic you want to determine what workflow to run. This is intended to probe the hardware/serial number and run workflows based on customer logic.

Drive now unmounts 

When MDS Deploy exits, the drive that has the resources is unmounted. This allows you to remove the drive without having to worry about the drive being mounted.

Log App

A new application called “LoginLogNG” was created specifically for Apple Silicon. It operates similarly to the older LoginLog, but is tailored specifically to the new architecture. The application shows both when packages are being installed at the login window (first boot) and when logged in (first login).

Auto Advance

Big Sur has an exciting new feature called Auto Advance; it allows for zero-touch setup of Macs enrolled in Apple School Manager or Apple Business Manager. The MDM feature in MDS has been updated to add Auto Advance to the initial profile. When a Mac is enrolled and assigned to the MDS MDM service, it will automatically skip all the setup assistant panes. When used together with MDS workflows, you can have a true “zero-touch” deployment.

MDS Deploy

MDS Deploy is a new app written to support Apple Silicon when running workflows. It is intended to run in recovery. It only runs for Apple Silicon Macs at this time; Imagr is used for Intel Macs. However, MDS Deploy supports all workflow operations created by MDS for both Intel and Apple Silicon, so the same workflow can be run on either platform. MDS Deploy also has an awesome, space-age UI. To make sure that everything runs smoothly, MDS Deploy does not sleep during operations.

Package Signing Certificates

Any identity can now be used for signing packages with MDS and can be specified in the Packages section.

Main Interface

MDS is organized into a side navigation panel and a main work area. The side panel has sections for Preferences, Deployment, Services, and Tools.

Under Deployment, the Workflows panel is the core of MDS. When opening MDS, the Workflows panel is automatically selected. This panel is used to set the majority of options for organizing and creating the resources to deploy your Macs. A workflow is the collection of steps that are done to erase the volume, install macOS, specify which packages and profiles to install, and specify which scripts to run before or after installation.

  1. To access the Workflows panel, select Deployment > Workflows in the Side Navigation.
  2. Add, Remove, and Edit Workflow: These buttons add, remove, and edit the above workflows. Double-clicking on a workflow will also open the editing sheet.
  3. Duplicate: Make a copy of the selected workflow(s).
  4. Import/Export Workflows: Select one or more workflows and click Export to save the workflow settings to a file. Click Import to add these workflows to MDS on another machine or after being removed from the workflow list.
  5. Activate/Deactivate Workflows: If a workflow is not active, it will not be included when the resources are saved. Uncheck a workflow to exclude it when saving to volume or disk image.
  6. Connect to Wi-Fi: This option will have the target Mac recovery partition connect to Wi-Fi before launching Imagr (or MDS Deploy) to run workflows.
  7. Check for network: This option will have the target Mac recovery partition check for a network connection when first launching Imagr (or MDS Deploy) to run workflows.
  8. Automatically run workflow: Choose a workflow to be run automatically after the specified delay period.
  9. Set target volume name: This is usually not needed as the default volume selected is “Macintosh HD,” but can be useful if a machine has multiple macOS installations. This will only run the automatic workflow if the specified alternate volume name is found.
  10. Override Workflow Options using Script: If you have a script that you’d like to use to override workflow options, you can select it here.
  11. Send logging information via http POST to: Target Macs will send logging information when running a workflow. This will default to send workflow status logging information to the Remote Log section of MDS on the current machine. If desired, this can instead be set to direct workflow status logging to a separate Imagr logging service when available.
  12. Save to Disk Image: Prompts for a name and location to save a new disk image that will contain all the resources and workflows. The disk image can be copied to a web server for deploying Macs. (The disk image volume name can be configured in Preferences > General)
  13. Save to Volume: Prompts to select an external HFS+ volume. The resources and workflows will be copied to the selected volume for deployment. A script called “run” will also be created that is used to launch the workflow selector (Imagr or MDS Deploy).

Apple Silicon Restore

Apple Silicon Macs can be restored using Apple Configurator, but only once they have been put into DFU mode. MDS makes it easy to put a mac info DFU mode. Connect a USB-C cable supporting charging and data to the DFU port on each Mac, then click DFU mode. The target Mac will instantly go into DFU mode. The target Mac can be restored by clicking Restore With Apple Configurator 2. Alternatively, the Apple Configurator 2 can be opened, and the Mac can be restored directly from Apple Configurator 2.

To automate the process, click start. MDS will then detect any device plugged into the DFU port, put the mac into DFU mode, erase and restore macOS.

Acroname Hub

To fully automate restoration, a full featured USB-C hub can be purchased and used with MDS. Plug the included USB-C cable from any USB-C port on the Mac running MDS and plug into port 0 of the Acroname for MDS hub. Plug up to 5 Macs into the USB-C ports 1-5 on the Acroname hub, making sure to select the DFU port on the target Macs. Click Refresh, and the attached Macs will show up for putting into DFU mode and restoring with Apple Configurator 2.

Additional Options

Additional options can be specificed by clicking the Options button:

  1. Remove Apple Configurator temporary cache before each restore: When a Mac is restored, the macOS is unzipped to the local drive by Apple Configurator 2. This results in a very large cache files. Select this option to erase the cache before each restore. You can also click Empty Now to erase the cache now.
  2. Use Custom IPSW: Select a specific version of macOS to restore by selecting an IPSW downloaded from Apple or from Download macOS in MDS.

Workflow Creation and Editing Sheet

Workflow Description

When the workflow is created or edited, a sheet will be shown to edit the workflow.

  1. Workflow Name: A name for the workflow. This will be shown in the recovery partition when selecting a workflow.
  2. Workflow Description: A description for the workflow. This will be shown in the recovery partition when selecting a workflow.
  3. Only show workflow if model identifier contains: When the checkbox is checked, use this field to specify for which models this workflow will appear. For example, entering “MacBook” will have the workflow appear on all computers containing “MacBook” in their model identifier, i.e., all MacBooks and not iMacs.

Workflow macOS Settings

  1. Install macOS: Select a standard macOS installer downloaded from Apple (.app or .sparseimage),select a disk image (.dmg) with the macOS installer inside it, or provide a URL where such a file is hosted.
  2. Erase and Install macOS: If this is checked, the selected macOS partition will be erased and the macOS installer will be used to install macOS. Alternatively, to upgrade the current macOS installation without erasing, leave this option unselected.
  3. Rename volume: Change the volume name to a new value.
  4. Restart/Shutdown: Use this option if an additional restart is needed after the OS and package install process completes or to shut down the machine after the install process.
  5. Erase Volume and Restore macOS from Disk Image: Select a file prepared with AutoDMG to reinstall macOS using Apple Software Restore (ASR).
  6. Do not install macOS: Use this option to only install packages and other content. The current OS will be left on the target volume. This is ideal if you have a new Mac that has the most up-to-date macOS on it and you just want to install packages.

Workflow Resources Settings

  1. Wait for network access before installing resources: This is only needed when a given resource installation requires network access to proceed.
  2. Package & Apps Folder: Specify a path to a folder with packages to be installed when the workflow is run. The packages should be standard macOS package format, regardless of what the type of package it is (flat, bundle, etc); MDS will convert them when the resources are copied. Any “.app” bundles found will also be converted and installed.
  3. Choose when to run each Package or App: You can select from running packages and apps on first boot, when running the workflow, or when the user first logs in.
  4. Scripts Folder: Specify a folder containing scripts to run on the target Mac.
  5. Choose when to run each script: You can select from running scripts after first boot packages are installed, before packages are installed when running the workflow, or when running workflow.
  6. Profiles Folder: Specify a folder containing configuration profiles to install on the target Mac.
  7. Choose when to install each Profile: You can select from installing profiles after first boot packages are installed (when not installing macOS), after macOS and packages are installed, or after macOS is installed but before packages.
  8. Reboot after first boot: Choose if the Mac should restart after applying the resources that are marked to be installed or run after the first time that macOS finishes booting. Additionally, you can wait for the Setup Assistant to complete before rebooting.
  9. After running workflow: When a workflow does not reinstall macOS, choose to either restart or shutdown the machine when the workflow finishes.

Workflow User Account Settings

MDS can create multiple user accounts. Click the “+” button on the User Account panel to add one.

  1. Full Name, Short Name, and Password: Enter this information to create a new user account on the target Mac.
  2. Set the UID.
  3. Set the photo.
  4. Set an SSH key.
  5. Set the Password Hint.
  6. Choose between /bin/zsh and /bin/bash for the default shell.
  7. Select if the new user account is an administrator.
  8. Hide the user account from other users when logging in: This may be useful for creating admin management accounts that should not be visible to other users.
  9. Automatic login: The selected user will be automatically logged in when macOS is started.

Workflow Options Settings

  1. Join Wi-Fi: The target Mac will be configured to join Wi-Fi when a user logs in. Enter the SSID and Password below the checkbox.
  2. Set Computer Name: When selecting this option, either the admin is prompted for a computer name when the workflow is run or set computer name to the value entered. Include the machine’s serial number if desired by adding {{serial_number}} to the name expression. This is useful when using MDS to deploy a cluster of Macs and identifying them for remote access or when sending logging information while the MDS workflow is run on a cluster of Macs.
  3. Trust Server Certificate in System Keychain: This will use the certificate from “Preferences > Security” so that after the workflow is run, the target machine will be able to use secure Web Services created in MDS.
  4. Skip Setup Assistant: Choose to skip some of the options usually presented during the initial setup of the target Mac.
  5. Skip User Privacy and Location Setup Assistant: Skip only these components of Setup Assistant.
  6. Enable SSH: Enable remote login preferences for administrators.
  7. Allow Administrators to screen share: Enable screen sharing preferences for administrators.
  8. Disable SIP NVRAM: Turn off macOS System Integrity Protection. This works on Intel Macs only.
  9. Install MunkiReport: Configure the target machine to use MunkiReport if set up in MDS Web Services.

Workflow Munki Settings

  1. Configure Client: Check this box after activating the “Munki Server” option on the main window and the URL box will be automatically populated with the correct Munki server URL. Make sure to also add the Munki Tools package to the “Resources” panel. When this workflow is run on client machines, they will have an app called “Managed Software Center” installed that checks in with the Munki server to make content available.
  2. Trust Munki TLS Certificate: Check this box if the option in MDS “Services > Munki” was set to use HTTPS for the Munki server. This will configure client machines to correctly trust the certificate used for the secure connection.

Workflow Variables Settings

  1. Set Variables: Check to activate the script variables option.
  2. Edit: Click to configure the settings for each variable that will be used.

Editing variables will prompt the user running the workflow to enter values. The values entered will then be available to scripts added to the Resources section of the workflow. Scripts can reference these values as “mds_var1”, “mds_var2”, etc.

Variables can be set to prompt either for text or provide a pop-up with multiple choice. When desired, multiple choice can include an “Other…” option to enter an answer not provided in the list.

Preferences

General Preferences

Preferences are split into multiple sections; the first section is the General tab.

  1. Imagr Download URL: Set the URL for downloading the current version of Imagr (usually leave as default).
  2. Temporary Folder: A local file path that MDS will use to store temporary files.
  3. Clear Files: Clicking will clear the temporary files location.
  4. Disk Image Volume Name: Change the volume name used when saving workflows to a disk image.
  5. Alternate Run Command: When saving workflows to a volume or disk image, MDS will usually create a run script to begin the process to run workflows. If any part of this needs to be customized, the user can write a custom run script and add it here.
  6. Migrate Settings: Export all MDS settings that were set up on one Mac and import them in MDS on another Mac (workflows not included).
  7. Restore Ignore Prompts: Reset calls for system permissions.
  8. Restore All Defaults: Reset original values for all General and Security Preferences.

Security Preferences

The Security Preferences tab manages certificates to secure communication for the services that MDS can run: MDM, Munki, and other items in Services > Web Service.

  1. Hostname: Set the hostname that will be used for the certificate.
  2. Create Self Signed Certificate…: This button will create a X.509 certificate at a location selected. The DNS name on the certificate should match the DNS name that is used to initiate the connection.
  3. SSL Certificate Folder: The “Create Self Signed Certificate…” button above will automatically populate the Certificate and Key values required, but if an existing certificate and key is to be used, they can be selected here.
  4. The current file paths for the certificate and private key are shown.

Packages

The Packages Preferences tab manages how MDS can sign packages with a signing identity.

  1. Sign Packages: Select an item from the macOS keychain to sign packages.
  2. Skip signing if package is already signed: If some packages added to workflows will already be signed, click the second checkbox to leave signed packages as-is and only sign unsigned packages.

Syncing Preferences

Sync URL Preferences: MDS can save workflow content and settings to a master disk image to which other Macs running MDS can sync.

  1. Add a new URL to be used for syncing workflows to a remote master. This can be any valid file path that the computer can currently reach (i.e., local network, HTTP, or other remote address). The address should point to a sparseimage file previously created with MDS using the “Save Master for Syncing” option in the File menu.
  2. Remove: Removes the selected Sync URL.
  3. Select a Sync URL: More than one Sync URL can be added. Switch the current selection by selecting from the list.
  4. Click the arrow to open the folder used to store files for syncing.
  5. Sync Now: Update the Workflows panel with content from the current Sync URL master disk image.
  6. Clear Sync Cache: Clear local files previously downloaded when syncing to a remote master.

Running the Workflow

To run the workflow, you must first boot into recovery (instructions for booting into recovery are separated below between Intel Macs and Apple Silicon Macs). After booting into recovery, start the workflow selector, either Imagr or MDS Deploy, and run the workflow.

Booting Into Recovery

Intel Macs

On the Intel Mac that is to be set up, hold Command-R (⌘R) when starting up the Mac. Once the Mac is booted (to the recovery partition), open the Terminal by selecting Terminal from the Utilities menu. Then, start Imagr from an external volume, a file server, or a web server using the instructions above

Apple Silicon Macs

On Apple Silicon Macs, this process is slightly different, but still largely similar. To boot into recovery, press and hold the power button until the drive and “Options” are showing; then, select Options. You will now boot into One True Recovery (1TR).

Running Imagr/MDS Deploy

External Volume

Plug in the external volume and enter the following command:

/Volumes/<Volume Name>/run

For instance, if the volume name is “MacDeployStick”, enter in:

/Volumes/MacDeployStick/run

Web Server

If the resources were saved to a Disk Image, copy the disk image to the web server and locate the URL to the disk image. To mount the disk image and open Imagr, enter command in this format:

hdiutil mount <URL to Disk Image>
/Volumes/MacDeployStickResources/run

For example:

hdiutil mount http://192.168.168.50/images/mds.dmg
/Volumes/MacDeployStickResources/run
File Server

If the disk image is hosted on a SMB file server, mount the file server and mount the image directly from the file server. The mount point must be created first, then the file server mounted, and the image then mounted in this format:

mkdir <mountpoint>
mount_smbfs smb://<username>@hostname/<sharedfolderpath> <mountpoint>
hdiutil mount <mountpoint> </path/to/disk/image.dmg>
/Volumes/<Disk Image Volume Name>/run

For example:

mkdir /tmp/mnt
mount_smbfs smb://guest@imac.local/Shared /tmp/mnt
hdiutil mount /tmp/mnt/mds/MDSDiskImage.dmg
/Volumes/MacDeployStickResources/run

Running the Workflow in the Workflow Selector

Intel Macs

When Imagr starts, select the Target and Workflow and click Run Workflow.

Apple Silicon Macs

Once the Mac is booted to the recovery partition, open the Terminal by selecting Terminal from the Utilities menu.

Here, you can select your target Partition and your Workflow. 

After selecting a Workflow and Partition, click “Run Workflow”. If you need to cancel the workflow, the button will turn into a “Cancel” button after starting to run the workflow.

Remote Log Viewer

When a workflow starts running in Imagr or MDS Deploy, it can send status logging information to the MDS Remote Log Viewer. However, the workflow must be configured to do so in the Workflows panel prior to saving the workflow to a volume or disk image.

  1. Before running a workflow, make sure to click the toggle button to turn on Remote Log Viewer so it can receive log info.
  2. Clear log info if needed.

Services

MicroMDM

Devices

MDS provides an interface to run MicroMDM. In order to use MicroMDM, go to the MicroMDM tab under Services.

  1. To set up MicroMDM you may need to first click the lock icon to access the tab.
  2. Once unlocked, click the toggle switch to turn on the MicroMDM service.
  3. Once MicroMDM is set up and machines are enrolled, refresh the Devices list to view information on them.
Settings
  1. To set up the MDM service, enter Settings within the MicroMDM screen.
  2. Click the icon to unlock if needed before proceeding.
  3. After unlocking, click the toggle switch to start the service if it is not running.
  4. Configure Push Certificate: In order to send MDM commands, you need to have a signed Push Notification Request. This feature will save a file for these requests and provide instructions to get it signed by Twocanoes Profile. Note: this requires a support plan.
  5. Configure MDM Profile: This feature can be used to configure the components of a DEP including Resources, User Account creation, and other options similar to those in an MDS workflow, as well as options to skip sections of macOS Setup Assistant.
  6. Configure DEP Token: In order to use the Initial MDM Profile mentioned above, this feature will export a public key to be used in Apple Business Manager or Apple School Manager, then import the DEP token issued by Apple.
  7. Once the MDM service is configured, click Open Enrollment Page to see the URL in a browser to use in enrolling devices.
  8. Status indicators will turn green to indicate when each component of MDM is activated or set up.

When MicroMDM is set up, visit the enrollment page on a target device to download the enrollment profile or include the enrollment profile in an MDS Workflow. Once a device is enrolled, select the device in the Devices list, then use the MDM menu in the menu bar to send MDM commands.

Preferences
  1. MDM Preferences manages options for the MicroMDM service, but these options may not need to be changed.
  2. Database Location: This shows the location of the database that MDS creates for the MDM service. Change this only when necessary.
  3. API Key: MDS communicates with the MDM service using an API key that is auto-generated. Change this only when necessary.
  4. MDM Server Port: Set the port to be used for the MDM service.
  5. MDM HTTP Debugging: Turn on verbose information that can be displayed by going to Window > Show Log. This will show information on communications with the MDM service.

Web Service

MDS can run several web services such as Munki and MunkiReport. However, it can also create additional services for making files available from a URL. This can be useful when building workflows or running workflows from a disk image instead of saving them to a flash drive.

  1. Click the + button to add a new web service.
  2. View the list of existing web services and click the checkbox to turn individual services on or off.
  3. After configuring Security Preferences in MDS, check “Use TLS” to make the web service secure.
  4. Click the arrow button for each service to load its URL in a browser.
  5. Click the toggle button to turn all current web services on or off.
Adding a Web Service
  1. Select Folder: Select a folder for the web service, such as a location where one has saved workflows to the disk image.
  2. Port: Change the port for the web service or leave the auto-selected value.
  3. Use TLS: you can check this box if needed to make the web service secure.
  4. Allow Directory Listings: Check if relevant to allow or disable a directory listing to show a list of all content in the selected folder.
  5. Enable PHP7: Check if the folder will contain PHP script to be run.

All web services will remain running even after quitting MDS or logging out the current user from macOS. Use the toggle switch to turn off web services when desired.

Munki

Munki is a web service that requires additional setup.

  1. Click the icon to unlock if necessary.
  2. Click the toggle switch to start the Munki service. If Munki has not yet been installed, this will prompt with information to download and install Munki Tools. A new Munki repository will be created when the service is started.
  3. Click the arrow to load the Munki service URL in a browser. This will use HTTPS if a certificate is created in MDS Security Preferences.
  4. If there is an existing Munki repository or if the location needs to be changed, click the Change button to select a new location. Click the arrow button to go to the current repository location.
MunkiAdmin

To configure the content for the Munki repo, go to the MDS Tools menu and select “Open MunkiAdmin”. Instructions will be provided to download MunkiAdmin if needed.

MunkiReport

Overview

MunkiReport is a web service that also has its own setup area within MDS.

  1. Click the icon to unlock if needed.
  2. Click the toggle switch to turn on the service once configured.
  3. Click the arrow button to load MunkiReport in a browser.
Setup
  1. Go to the Setup tab before starting MunkiReport.
  2. Open Download Page: Get the needed setup files by clicking the button to open the MunkiReport download page.
  3. Import MunkiReport Files: Once the setup files have been downloaded, click to import the setup files.
Users
  1. Once set up, go to MunkiReport Users.
  2. Click the + button to create a User account to be able to log into MunkiReport in the browser.
Preferences
  1. Go to MunkiReport Preferences if needed after setting up the service to make changes.
  2. Select a new location for the MunkiReport folder.
  3. Click the arrow button to go to the current folder location.

Automatons

The Create Mac Automaton function programs an Arduino ItsyBitsy to act as a keyboard when plugged into a USB port. The Automaton should be inserted at the boot selector screen. To enter the boot selector screen, press the power button and immediately hold the option key down. The Mac will show bootable volumes. The Automaton should then be plugged into a USB port. The Automaton will issue a ⌘R keyboard command, which will boot the Mac into the recovery partition. The Automaton will then wait for an adjustable delay period and then issue commands to open the Terminal and launch the workflow selector (Imagr or MDS Deploy). 

After connecting an Automaton device, click Create to program it or update its software version. Devices previously flashed with Automaton software do not require pressing the device’s programming button; devices not previously flashed with Automaton software do.

Once the Arduino has been flashed, a success message will be displayed.

Once programming is complete, disconnect the Automaton. If left connected, it will begin pressing the keyboard strokes.

Configure Automaton

Click “Configure Mac Automaton” to change options.

The Automaton will press the Command-R keyboard shortcut (⌘R) a few seconds after it has been plugged in. It will then wait for a defined startup delay before issuing the commands for opening Terminal and running the specified command. These values can be adjusted using the Configure Mac Automaton sheet.

  1. Version: View the current Automaton firmware version. MDS will prompt to update the Automaton if it has older firmware than what is provided in the current MDS version.
  2. Command: Listed is the command that will run in Terminal in the recovery partition. It should be adjusted to match the name of the external volume (replace “mds” with the name of the volume that contains the MDS resources). Depending on where the resources are located, the command will be different. See below for examples:


External Volume

/Volumes/mds/run

Web Server

hdiutil mount http://imac.local/mds/MDSDiskImage.dmg && /Volumes/MacDeployStickResources/run

SMB Server

mkdir /tmp/mnt && mount_smbfs smb://guest@imac.local/Shared /tmp/mnt && hdiutil mount /tmp/mnt/mds/MDSDiskImage.dmg && /Volumes/MacDeployStickResources/run
  1. Delay before opening Terminal: The amount of seconds between pressing ⌘R and issuing the commands to open Terminal to run the command.
  2. Delay before running command in Terminal: Additional time before the command is executed.
Intel Configuration
  1. Firmware Password: Use only if the target Mac has been configured to use a firmware password. This setting will enter the required firmware password before booting to the recovery partition.
  2. Boot into recovery: Usually this should be left checked. Unchecking this option will disable the Automaton’s normal function of immediately issuing keyboard commands to boot to the recovery partition. Instead the Automaton will wait to receive commands later using its command line interface. This option can also be configured to boot to the different recovery partition options available (Note: some of these may not be available for older macOS versions):
    1. Latest macOS that was installed on your Mac (⌘R)
    2. Latest macOS that is compatible with your Mac (⌥⌘R)
    3. macOS that came with your Mac, or the closest version still available (⇧⌥⌘R)
  3. Open Disk Utility and erase first volume: This is for use with volumes that have FileVault enabled. To avoid being prompted for a password when running the workflow, this option will instead have the Automaton open Disk Utility and delete the first volume in the recovery partition prior to running Imagr. A volume with the same name will be created so that Imagr can then proceed normally.
Apple Silicon Configuration
  1. Boot into recovery: in Apple Silicon, the Automaton can boot into recovery for you to run the workflow. If the Erase Mac option is checked, the Automaton will select the “Erase Mac…” menu option to erase the Mac prior to installing macOS and resources.
  2. Connect to Wi-Fi for activation: here, you can enter the SSID and password of the Wi-Fi needed for activation, skipping manually entering in the information during the workflow itself.

Create Bootable Installer

The Create macOS Bootable Installer sheet provides an easy way to create a bootable macOS installation on an external drive

  1. Select macOS Installer: Click to select a macOS Installer app downloaded from Apple. (MDS provides a feature to do this if needed.)
  2. Target Volume: Select the target volume to install macOS (Note: this volume will be erased and formatted as HFS+).
  3. Click the icon to unlock if needed.
  4. Create: When the macOS Installer and Target Volume are selected, you can now create a Bootable Installer.

Note: this function is not required to restore macOS and packages. This is normally done by booting to the recovery partition. However, in some cases it is convenient to have a bootable external volume.

Running Workflows from External Volume

If you are saving an MDS workflow to a bootable external volume, be aware that the macOS installer presents the volume name as /Volumes/Image Volume rather than /Volumes/<name of volume>. This can cause issues with workflows, since the resources are accessed by the volume name. To resolve this, you can use one of two solutions:

  1. Create two HFS+ partitions on the external drive. Install the bootable macOS on one partition and save the MDS resources to the other partition. You can then run the command using /Volume/<name of volume>/run/
  2. After installing macOS to the external volume, rename it to “Image Volume” then save the resources from MDS to said volume. The workflow resources will then be referenced by the correct name and you can run the workflow by running /Volumes/”Image Volume”/run

Download macOS

Use the Download macOS screen to download macOS installers made available from Apple.

  1. Select a version of macOS from the list.
  2. Download: After selecting the desired version, click download. Depending on your network connection, this may take some time. A prompt will indicate when the download is complete.
  3. Catalog: Select a different catalog of macOS installers provided by Apple, such as if a development version is needed.

While downloading, select “Show Log” from the Window dropdown menu to view status. Note: once complete, the download will be provided as a “sparseimage” file. Additionally, a folder is created named “content” that is no longer needed once the download is complete and can be discarded.

More Resources

If you need help configuring MDS Automatons, please visit MDS Automaton Setup.

MDS Keyboard Commands

  • ⇧⌘I: Import Workflows
  • ⇧⌘E: Export Selected Workflows…
  • ⇧⌘M: Save Master for Syncing…
  • ⇧⌘S: Sync Now
  • ⌘N: New Workflow…
  • ⌘D: Duplicate Workflow(s)
  • ⌘E: Edit Selected Workflow…
  • ⌫: Remove Selected Workflow(s)…
  • ⌘W: Close
  • ⌘R: Check For Resources…
  • ⌘K: Clear Resource Cache
  • ⌘L: Show Log