MDS Admin Guide

Created On
Last Updated On
byDave Lebbing
You are here:

Note: This unmaintained guide is for an unsupported version of MDS on our website for archival purposes. To view the most recent MDS Admin Guide, visit the MDS 5 Admin Guide.

MDS icon

Overview

MDS is a macOS application to create 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.

Requirements for Installing macOS

Previous versions of macOS and Mac hardware supported block-based imaging to deploy macOS and associated configuration and 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.

Recent Macs cannot boot from external volumes unless that security setting is disabled in the Startup Security Utility when booted to the recovery partition. This adds additional time for setup and configuration and reduces security if that security feature is not re-enabled after booting from an external volume.

Why MDS?

MDS is based on the idea that you should be able to easily wipe and reinstall a Mac quickly and easily 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, and 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 time it takes for setup. Apple also provides the Deployment Enrollment Program (or DEP) for initial setup and enrollment in an MDM service, but that requires both an organization be enrolled in DEP and all Macs 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, which can be a labor-intensive process.

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 by the person setting up the Mac computers. 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 unboxed and powered on with the option key held down. 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. So 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, hold the option key 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 result in large savings of time and labor costs.

This same process can be used for Macs that need to be re-setup either onsite or offsite.

Main Interface

The main interface of MDS has a toolbar at top with various options, a list of workflows in the middle, and some workflow management options near the bottom. The main window is used to perform the majority of options for organizing and creating the resources for deploying your Macs.

  1. MDM: MDS provides an interface to run MicroMDM. This button will launch a management window to start the MDM service, configure DEP tokens using Apple Business Manager or Apple School Manager, set up an initial MDM profile, send MDM commands to enrolled devices, and show an activity log for the MDM service. There is also an option to create a Push Notification Request and have it signed by Twocanoes Profile so that MDM client machines can contact the MDM service on the machine running MDS (requires support plan).
  2. Automaton:
    1. Create Automaton: Using an Arduino Micro, MDS can program it to automatically perform the keystrokes for setting up the Mac.
    2. Configure Automaton: This button is used to open a sheet for changing the default setting for the Automaton.
  3. Munki Admin: Open an application called Munki Admin
  4. Remote Workflow Log: This button will show the Log Viewer dialog. This dialog will have options to start/stop the process that receives the log information from workflows being run, and to clear the Log Viewer content received.
  5. Create Bootable Volume: This option opens a sheet for instructions on how to create a bootable external drive. This is not required for booting a Mac to the recovery partition, but is helpful for some older Macs.
  6. Download macOS: This will open a window to select and download macOS installers currently provided by Apple.
  7. Workflows: A workflow is the collection of steps that are done to erase the volume, install macOS, and specify which packages or profiles to install or scripts to run before or after installation.
  8. 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.
  9. 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.
  10. Duplicate: Make a copy of the selected workflow(s).
  11. 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 they were removed from the workflow list.
  12. Check for network: This option will have the target Mac recovery partition check for a network connection when first launching Imagr to run workflows.
  13. Connect to WiFi: This option will have the target Mac recovery partition connect to WiFi before launching Imagr to run workflows.
  14. Automatically run workflow: Choose a workflow to be run automatically by Imagr after the specified delay period.
  15. Set target volume name: This is usually not needed since the default volume selected is “Macintosh HD”, but can be useful if a machine has multiple macOS installations, and will only run the automatic workflow if the specified alternate volume name is found.
  16. Serve images: This option will start up a web server to make disk image files available over the network. DMG files created with Save to Disk Image can be saved to a selected folder, then will be available to mount remotely on a local network machine.
  17. Serve Munki: This option will start up a web server to make content from a Munki repository available to remote machines. Checking the box will first prompt to install Munki Tools if needed, then will allow the user to choose an existing Munki repository folder or to create a new one. The server url will be shown, which can be switched to https using an option in Preferences.
  18. Save to Disk Image: This will prompt 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.)
  19. Save to Volume: This will prompt 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).

Workflow Editing

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.

Workflow macOS Settings

  1. Install macOS: Select a standard macOS installer downloaded from Apple (.app or .sparseimage), or select a disk image (.dmg) with the macOS installer inside it.
  2. Erase and Install macOS: If this option is selected, 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. Confirm network access before installing resources (only needed when a given resource installation requires network access to proceed).
  2. Package & Apps Folder: Specify a path to a folder with packages that will be installed when the workflow is run. The packages should be standard macOS package format, but it does not matter 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: on first boot, when running workflow, or when first user logs in.
  4. Scripts Folder: Specify a folder containing scripts to run on the target Mac.
  5. Choose when to run each script: 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: 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. After workflow action: 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. Name, short name, and password: Enter information to create a new user account on the target Mac.
  2. Set the UID for the user account.
  3. Set an SSH key for the user account.
  4. Set the user account password hint.
  5. Select if the new user account created should be an administrator.
  6. Hide the new user account when logging in. This may be useful for creating admin management accounts that should not be visible to other users.
  7. Have the selected user automatically logged in when macOS is started.

Workflow Options Settings

  1. Join WiFi: Have the target Mac be configured to join WiFi when a user logs in.
  2. Computer Name: Have Imagr either prompt the admin 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 (useful when using MDS to deploy a cluster of Macs and then identify them for remote access, or for sending logging information while the MDS workflow is run on a cluster of Macs).
  3. Skip Setup Assistant: Choose to skip some of the options usually presented during the initial setup of the target Mac.
  4. Skip User Privacy and Location Setup Assistant: Skip only these components of Setup Assistant.
  5. Enable SSH: Enable remote login preferences for administrators.
  6. Allow Administrators to screen share: Enable screen sharing preferences for administrators.
  7. Disable SIP NVRAM: Turn off macOS System Integrity Protection.

Workflow Munki Settings

  1. Configure Client: Check this box after activating the “Serve Munki” 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 will check in with the Munki server to make content available.
  2. Trust Munki TLS Certificate: Check this box if the option in MDS preferences 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. Click to activate script variables option.
  2. Click Edit to configure the settings for each variable that will be used.

This will prompt the user running the workflow to enter values. Variable values entered at that time 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.

The Prompt Title will be what is shown to the user running the workflow when prompted to enter a value. The Type is how they provide the information. Choosing “Text” will ask the user to type an answer. “Popup” will instead present a list of options.

  1. Choose Type.
  2. Add options to show as a popup list.
  3. Include an “Other” option when needed if the user may need to enter a value other than what is in the popup list.

Preferences

General Preferences

  1. Preferences is split into multiple tabs. The first one is the General tab.
  2. Imagr URL: Set the URL for downloading the current version of Imagr (usually leave as default).
  3. Temporary Files: A local file path that MDS will use to store temporary files.
  4. Clear Files: Clear the temporary files location when indicated.
  5. Disk Image Volume Name: Change the volume name used when saving workflows to a disk image.
  6. Port for Serve Images Over HTTP: Set the port used when enabling the option to serve images over HTTP.
  7. Restore All Defaults: Reset original values for all general preferences.

Security Preferences

  1. The Security preferences tab manages certificates to secure communication for the services that MDS can run: MDM, Munki, serve images over HTTP, remote workflow activity logging.
  2. Hostname: Set the host name that will be used for the certificate.
  3. Create New Self Signed Certificate: This button will create an 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.
  4. The “Create New” button described 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.

Munki Preferences

  1. The Munki tab manages the Munki server that MDS can run.
  2. Set the port used when running the Munki server.
  3. Host Munki Repo using TLS: Enable HTTPS when hosting a Munki repo. This will require first setting up a certificate in Security Preferences. Set this up before creating a workflow with Munki options so that this certificate can be included in the workflow.

Packages Preferences

  1. Packages Preferences manages how MDS can sign packages with a signing identity.
  2. Sign Packages: Select an item from macOS keychain to be used to sign packages created.
  3. Skip signing: 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.

MDM Preferences

  1. MDM Preferences manages options for the MicroMDM server that MDS can run.
  2. Database Location: This shows the location of the database that MDS creates for the MDM server. 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 server.
  5. MDM HTTP Debugging: Turn on verbose information that can be displayed by going to top toolbar > MDM > Show Log. This will show information on communications with the MDM server.

Logging Preferences

  1. Logging Preferences: Have target Macs send logging information when running a workflow.
  2. Send logging information: When selected this will attempt to select the local network address of the current admin Mac. Workflows will be configured to use this value to send status while running.
  3. Change the network address to use when sending logging information, or leave it as the default value.

Syncing Preferences

  1. Syncing Preferences: MDS can save workflow content and settings to a master disk image to which other Macs running MDS can sync.
  2. Set a URL to be used for syncing workflows to a remote master. This can be any valid file path that the computer can currently reach (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.
  3. Clear Sync Cache: Clear local files previously downloaded when syncing to a remote master.

Running the Workflow

On the Mac that is to be set up, boot into the recovery partition by holding Command-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. Once the Terminal is open, start Imagr from an external volume, a file server, or a web server:

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

Selecting Target Volume and Workflow

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

Create Automaton

The Create 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 on a Mac, 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 command-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).

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

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

The Automaton will press the command-R keyboard command 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: This is the firmware version.
  2. Command: 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 current volume name). 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
  3. Delay before opening Terminal: The amount of seconds between pressing command-R and issuing the commands to open Terminal to run the command.
  4. Delay before running command in Terminal: Additional time before the command is executed.
  5. 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.
  6. 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. Or this option can be configured to boot to the different recovery partition options available (note that some of these may not be available for older macOS versions):
    1. Latest macOS that was installed on your Mac (Command-R)
    2. Latest macOS that is compatible with your Mac (Option-Command-R)
    3. macOS that came with your Mac, or the closest version still available (Shift-Option-Command-R)
  7. 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.

Create Chromebook Automaton

MDS can also create an Automaton for Chromebook setup. Click Create to flash a connected Arduino with this software.

Configure Chromebook Automaton

After using the Create Chromebook Automaton sheet, open the Configure Chromebook Automaton sheet to choose settings needed for the target machine(s).

  1. Select the ChromeOS Version tab.
  2. Choose a ChromeOS version. This is needed to know the correct sequence of steps the Automaton will need to do.
  1. Select the Chromebook automaton WiFi tab.
  2. Enter standard WiFi settings. This will allow the target machine to be configured to join a WiFi network in order to proceed with further setup.
  3. If the desired WiFi network requires advanced configuration, select “Advanced Network Security” to show additional options.
  4. Enter any advanced WiFi options when necessary.
  1. Select the Chromebook automaton Google Enterprise tab to add credentials.
  2. Enter credentials: Add information for the Google account to be used to set up the target machine. Automaton does not currently support entering two-factor authentication, so this must be an account that does not have two-factor enabled.

Create Bootable Volume

The Create Bootable Volume sheet provides an easy way to create the command to install macOS on an external volume.

  1. Select macOS Installer App: Select this button to select a macOS Installer app downloaded from Apple.
  2. Select the volume to install macOS. NOTE: THIS VOLUME WILL BE ERASED AND FORMATTED AS HFS+
  3. Copy and paste the generated command into Terminal and press return. You will be prompted for the admin password.
  4. Close: Once finished, click the Close button.

Note that 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 the workflows since the resources are accessed by the volume name. To resolve this, you can do 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 the Image Installer volume. The workflow resources will then be referenced by the correct name and you can run the workflow by running /Volumes/”Image Volume”/run

More Resources

MDS Automaton Setup

Tags: