Munki’s wiki describes a process called Bootstrapping, where you install a Base OS, add the Munki tools and some settings and at first boot of the freshly installed Mac, Munki takes over and does the rest of the installations and configuration.
Here I will describe how to build a NetInstall Image (nbi) with System Image Utility to install a base OS with Munki. I will describe how to dip this for Mavericks 10.9.5 and Yosemite 10.10.1. There are some differences.
Either way, there is a restriction in System Image Utility that you can only build an NetInstall (or NetBoot or NetRestore) set of the same version of the OS you are running. So you if want both a Mavericks and Yosemite NetInstall set you will have to do this twice, once on a Mavericks machine and once on a Yosemite machine.
Download Mavericks or Yosemite
Open the Mac App Store and download the installer for Mavericks or Yosemite. The installed OS has to match the version of the installer and the NetInstall image you want to build.
Mac App Store will complain that the OS is already installed, just click ‘continue’ to start the download anyway. Once the download is complete the installer will actually open, just quit it, we do not need that now. You can also use a copy of the “Install OS X Mavericks|Yosemite.app” you may have archived somewhere.
Open System Image Utility
In Mavericks you can find it in /System/Library/CoreServices. On Yosemite they grouped several useful applications, including System Image Utility, into a subfolder /System/Library/CoreServices/Applications/. Easiest Way to get there is Finder’s “Go To Folder…” option (command-shift G).
In Yosemite, I find it useful to link this folder to the
/Applicationsfolder for easier access:ln -s /System/Library/CoreServices/Applications /Applications/System
If the Install application is in the default location (/Applications folder) SIU should pick it up automatically and show the version and build number below. Make sure they match your current OS.
NetInstall Image is the default selection. Choose “Customize” to proceed.
Customize the image workflow
The window will change to the customizable workflow view. You will have two steps: “Define Image Source” and “Create Image.”
“Define Image Source” only has one option and that should be already set. The default values in “Create Image” will need some adjusting though.
“Type” should be “NetInstall” which also grays out the “Installed Volume” field.
“Save to” defines the location where the nbi folder will be built. Ultimately you will have to upload this folder to your netboot server. Choose a local folder to build it. If you have a fast SSD drive, building it there will speed up the process significantly.
“Image Name” is the name of the folder set. Change the default to “Munki Yosemite” or “Munki Mavericks”.
“Network Disk” is the display that will be used in the Server application, Startup Disk and the EFI boot picker. Change the default to “Munki Yosemite” or “Munki Mavericks”.
“Image Index” should be an integer that is unique to each different NetBoot/NetInstall image in your network. If you are serving the image from a single NetBoot server, the number should be less than 4095, otherwise greater than. SIU will choose a random for you, but you can change it now or later in the Server app.
Finally the Description field. SIU puts a decent summary here, I would add the version of Munki you are installing.
Adding Custom Packages
There should be a second “Automator Library” window with additional workflow steps. Find the “Add Packages and Install Scripts” step and drag it between the two existing steps. You can also drag to change the order of the steps later.
Download the latest Munki release.
Drag the munkitools-VERSION.pkg file into the “Add Packages and Install Scripts” step. (As of this writing be sure to get the very latest package [2.0.1 or newer] as the older versions might not install completely during NetInstall. https://github.com/munki/munki/commit/53edd6a050b9e6612b2b827145b40a6cc9a50792)
This will install Munki tools along side OS X. Then at the first boot, Munki will take over the mac and install additional software and configurations according to Munki’s catalog and manifest.
However the munkitools installer does not know to point the client to your Munki repository. This is one step we need to configure.
Open your preferred text editor and paste
#!/bin/bash
MUNKI_REPO_URL="http://munki-server/munki_repo/"
/bin/echo "setting Munki Repo URL at $3/Library/Preferences/ManagedInstalls defaults to $MUNKI_REPO_URL"
/usr/bin/defaults write "$3/Library/Preferences/ManagedInstalls" SoftwareRepoURL $MUNKI_REPO_URL
/usr/bin/touch "$3/Users/Shared/.com.googlecode.munki.checkandinstallatstartup"
Save the script as ‘setupMunki.sh’ and drag the script into “Add Packages and Installation Scripts” step in your SIU workflow.
Modify the MUNKI_REPO_URL variable to point to your server.
The defaults command sets the SoftwareRepoURL in the proper preference file. The touch command creates a flag file so that Munki starts installing package right away on first boot as described here: https://github.com/munki/munki/wiki/Bootstrapping-With-Munki#details
The $3 parameter is passed into the script by the installer process and contains the target volume for the installation. In this case it will be something like /Volumes/Macintosh HD/. Note that this path likely contains spaces (like any OS X path), so you need to remember to quote this variable properly when you modify this script.
Build and Upload Netboot set
Save your Workflow and give it a meaningful name. Then run it. This may take several minutes. Once the workflow is done you can upload the nbi folder to your NetBoot Server. (OS X Server stores these folders by default in /Library/NetBoot/NetBootSP0/) Enable and try it on a client.
Further customization
(Note: every time you update or add a package or script, you need to rebuild and re-upload the netinstall folder)
The point of “bootstrapping” is to do as much configuration as possible with Munki later, so the modifications to the NetInstall process are minor. You can even update the Munki software on the client through Munki, so you will not have to update the NetInstall image on every Munki update.
There are a few things, however, that do make sense to do in the NetInstall process. Two common settings are to add a admin user and/or suppress the OS X setup process.
The setup dialogs will be suppressed if the file /var/db/.AppleSetupDone exist. So we can just add a line to our setupMunki.sh script:
/usr/bin/touch "$3/var/db/.AppleSetupDone"
Alternatively you can create a second script that does just this, so you separate OS X configuration from Munki configuration.
Create Default Users
You can use the application CreateUserPKG to create a pkg file that will create the desired user for you. If you need multiple default users you can create multiple different packages with CreateUserPKG.
Yosemite requires packages added to the NetInstall process to be of a specific format, called ‘distribution type packages.’ CreateUserPKG packages are not in this particular format, so we have to convert them.
productbuild --package createuser-1.0.pkg createuser-1.0dist.pkg
Applying Apple Software Updates
Munki allows you to include Software Updates from Apple during the Munki install/update process. If you want to do that at first boot, then add this line to your setupMunki.sh.
/usr/bin/defaults write "$3/Library/Preferences/ManagedInstalls" InstallAppleSoftwareUpdates -bool true
If you want to a local Software Update Server, then you can provide that, too:
/usr/bin/defaults write "$3/Library/Preferences/ManagedInstalls" SoftwareUpdateServerURL http://sus.example.com/content/catalogs/index_production.sucatalog
Automate the installation
You may want to make the installation process completely without any user interaction. In this case a use will choose the NetInstall volume in System Preferences or at the EFI Boot Picker and the process will erase a partition with a pre-defined name and install a fresh OS with the Munki Tools and your settings.
This can be very useful, but also very dangerous.
To achieve this add the “Enabled Automated Installation” workflow step before the “Create Image” step. It only has three options:
- the partition or volume name to install into
- wether to erase the target volume
- the language to use for the installation UI
If you enable automated installation, then there will be no UI provided, even if there is no volume with the expected name. (Then the installer process will just give up and boot back to the previous boot volume.) So you will have no access to other tools provided on the NetInstall netboot image.
Also if you choose a generic name for the automated volume (such as “Macintosh HD”) the potential that someone might accidentally delete a volume might be very high. In this case you really want to restrict access to the NetInstall by subnet or some other means.