macOS Upgrades or Erasing

Description

Upgrading or refreshing macOS from erasing requires the macOS Install App.  The following provides a Fileset to handle either of these cases

Historically, two KBs were provided to handle each of these options.  This newer Fileset allows for activation of either from one Fileset.  Certain fundamental changes have been made, for example the hidden upgrade file in /var/db is no longer required.

Ingredients

  • Custom Field – "macos_instal_flag"
  • Full Apple macOS Installer App
  • Provided Recipe
  • Provided Custom Field
Recipe:
↓ macOS


Custom Field:
↓ macOS



Full installer

Confirm the installer app is the 'Full' installer before continuing. If the app is relatively small e.g. 50MB, re-download the Install macOS Monterey.app. A full installer may be downloaded through Terminal on macOS 10.15+ devices. Example to download the 12.0 full installer to the Applications directory:

Download Full Installer
softwareupdate --fetch-full-installer --full-installer-version 12.0

Typically Apple only provides the latest point release of each Major OS version: 10.13.6, 10.14.6, etc.  For a full list of available updates, use the following command:

List Full Installers
softwareupdate --list-full-installers

Directions

Fileset

  1. Download and import the provided Fileset
  2. Download the desired version of the macOS Installer App
  3. Add the macOS Installer App into the same folder as the .placeholder fie; the .placeholder file may be removed if desired
  4. Select the Instal macOS App > Get Info > Verification, select Ignore At Verify and Apply to Enclosed
  5. Edit the Environment Variables for both the Activation Script and the Requirements Script

Fileset Contents

Environment Variables

The Environment Variables must be edited, providing appropriate values

  • M1 devices provide an additional complication when choosing to script the installation of macOS Instal Apps.  In this instance, a local macOS Administrator Username and Password must be passed to the script.  The two Variables 'local_admin' and 'admin_pass' should have their Values adapted respectively.  Intel device has no such consideration and will ignore these values if set.


Requirement Script – statosinstall_requirements.sh

Key values that require editing (in bold):

  • api_key –  Copy a Token (base64) from a chosen FileWave Administrator's 'Application tokens'
  • local_admin – username for a local admin on the target macOS device (Apple M1 only)


Activation Script – startosinstal_m1&intel.sh

Key values that require editing (in bold):

  • admin_pass – password for a local admin on the target macOS device (Apple M1 only)
  • local_admin – username for the matching local admin as password on the target macOS device (Apple M1 only)
  • installer_name – name of the App added, e.g. 'Install macOS Big Sur', 'Install macOS Monterey'
  • api_key –  Copy a Token (base64) from a chosen FileWave Administrator's 'Application tokens'

'installer_name' in Fileset is also set as REPLACE_ME, but value left as 'Install macOS Monterey'  as an example in the Fileset image.



Custom Field

Custom Field has 4 options:

  • NA – default value, the Fileset will not do anything with this setting
  • ERASE – device will have the OS erased and instal the provided version of macOS
  • INSTAL – device will upgrade with the provided version of macOS
  • FAILED – device will update the Custom Field flag to FAILED if something unexpected occurs.  No further attempts to run the Fileset will action anything whilst this is still the case

Either 'Assign to all devices' or select appropriate devices to associate the Custom Field.

Consider making Smart Group associations based upon the Custom Field value

Activation

  1. Create a Smart Group based upon macos_instal_flag value being either ERASE or INSTAL.
  2. Set the associated Custom Field for a device to one of these two values depending upon the experience you would desire

Since it is likely a subsequent installation attempt will be desired upon failure (once the reason for failure has been addressed, e.g. not enough disk space), the Smart Group could be set to also include a Custom Field value of FAILED.

To re-run a failed attempt, reset the Custom Field value to the appropriate ERASE or INSTAL value and choose to 'Reinstall Fielset'

Notes

By setting the macOS Installer App as leave behind, if the installation has not completed, but is no longer associated, this will ensure the installer remains on the device for subsequent attempts.  Additionally, since Apple automatically remove the macOS Installer App after upgrade, if the Fileset were still associated, there will be no re-attempt to download the installer.


Filesets that error will automatically re-attempt installation as standard.  The requirement script is designed to report an exit code of 210 to overrule this.  Even if the Requirement Script fails, it will report success and will neither continue download/activation nor will it re-attempt without intervention.  In this case, the client will update the Custom Field instead to report the failure.  Script log should show the output of the command.


Example log message:

|main|CUSTOM|CLIENT|startosinstall_requirements Exiting. Flag set as:

In this example, the Custom Field Flag reported has no value.  This should either mean the Custom Field is not associated to the device or the script has failed to read the value.  If the later, check the Environment Variables to ensure they are correct.