AutoImagrNBI differs from AutoNBI in that the end result is a NetBoot Image & not a NetInstall Image. A NetBoot Image is a full OS that can be made available for network booting, whereas NetInstall is a limited environment. AutoImagrNBI can also create a DMG for restoring to external media such as USB sticks.
AutoImagrNBI is designed to cut down on the faff associated with creating NBI’s, by not only by allowing you to create NBI’s on a different OS version. But by also saving your settings for when you next run the tool.
- 1 Prerequisites
- 2 On Launch
- 3 OS.dmg
- 4 Imagr.app
- 5 Imagr Configuration Plist URL
- 6 NetBoot Name
- 7 NetBoot Required Settings
- 8 Options
- 8.1 Options – Always Set
- 8.2 Suppresses Apple/iCloud & Diagnostics Setup Assistants:
- 8.3 Creates & Auto logs in as Root:
- 8.4 Disable Screen Saver for Root account:
- 8.5 Deletes com.apple.dockfixup.plist:
- 8.6 Creates A Minimal Dock for Root Account:
- 8.7 Copies Imagr to the NBI’s Applications Folder:
- 8.8 Launches Imagr At Login:
- 8.9 Removes Imagr’s Quarantine Flag:
- 8.10 Disables App Nap:
- 8.11 Disables Software Update:
- 8.12 Disables Spotlight:
- 8.13 Disables TimeMachine prompts:
- 8.14 Disables Gatekeeper:
- 8.15 Enables Disk Utilities Debug Menu:
- 8.16 Enables Diskless NetBoot:
- 8.17 Expands NetBoot Image to 64GB:
- 8.18 Compacts NetBoot Image:
- 8.19 Renames Sparseimage to DMG for hosting on NetSUS:
- 9 Options – App Config
- 10 Options – Standard
- 11 Options – Advanced
- 12 Options – Additionals
- 13 Administrative Privileges
- 15 NBI Folder Location
- 16 Space Needed
- 17 Building The NBI
- 18 Read-Only DMG
- 19 Logging
- 20 Updating
- 21 Issues
- 22 Secret Sauce
AutoImagrNBI’s goal is to automate the NBI creation process, this will do you little good if you do not have the following things in place;
NetBoot Server Connectivity
Your mac clients need to be able to see you NetBoot server & any NBI’s hosted on it. These images can be seen via the Startup Disk pref pane:
This can be tested by creating a vanilla NetBoot Image via System Image Utility, once created upload it to your NetBoot server of choice.
NBI’s created with AutoImagrNBI really should be created from a clean never booted Operating System disk image (read: OS.dmg).
With AutoImagrNBI the OS versions do not have to match. 10.10+ NBI’s can be created on 10.9+ Macs running AutoImagrNBI.
NOTE: 10.10 is the minimum OS Imagr will run on.
Troubleshooting the NetBoot Process
If you have any issues in setting this far, the following (despite it’s age) is still the best resource to help you in “Troubleshooting the NetBoot process.” Apple also has some documentation available.
Enabling verbose booting on a client can show where in the process things are failing.
Other things to look out for are:
- 3rd Party Thunderbolt or USB adaptors might not always support NetBooting.
- Some NetBoot Servers do not support the NetBoot shadow files, & so a modified rc.netboot is needed.
Imagr gets its workflows from a plist that is accessible over HTTP, therefore a web server is needed to host the Imagr Configuration Plist & associated PKG’s & DMG’s.
On Launch, AutoImagrNBI’s opens with some options are greyed out, this is by design. To activate the other options, some items need to be added to AutoImagrNBI 1st.
On selecting either, an OS.dmg AutoImagrNBI will attempt to get the OS.dmg OS X version & build number.
When selecting an OS.dmg for the 1st time, AutoImagrNBI may appear to “hang” This is as the OS.dmg is silently mounted using hdituil attach. The reason for this can be found in the hdiutil man page: “hdiutil attach attempts to intelligently verify images that contain checksums before attaching them. If hdiutil can write to an image it has verified, attach will store an attribute with the image so that it will not be verified again unless its timestamp changes.”
You can either add a copy of the Imagr.app by pressing the “Select” button or you can download the latest release by pressing the “Download” button.
When pressing “Select” you are prompted to select an app to add to AutoImagrNBI, the version number of that is then reported back in AutoImagrNBI & if you have an internet connection that version will be checked against the latest release.
If the app you upload is an older version than the latest release you’ll be asked if you wish to download the latest release.
Pressing “Release Info” will take you to the latest releases information on GitHub: https://github.com/grahamgilbert/imagr/releases/latest
Pressing “No” closes the window.
Pressing “Yes” will download the latest release of Imagr from https://github.com/grahamgilbert/imagr/releases/latest to a temp location & this version will be added to the NBI.
Imagr Configuration Plist URL
Imagr gets its workflows from a plist that is accessible over HTTP, this URL needs to be set in Imagrs plist.
AutoImagrNBI will now attempt to download the Imagr Configuration Plist & will check it via Imagr’s validateplist. The output of which will show under the entered Imagr Configuration Plist URL.
Once the validation has run, AutoImagrNBI’s other options will become available.
The NetBoot Name field will now auto populate, in the format of “<OS Version> AutoImagrNBI”, the “NetBoot Image Index” will be set to a random number & the “Serve Image over” options will be shown.
If you now click “Build”, & AutoImagrNBI will start the NBI creation process.
NOTE: The Imagr URL is written to AutoImagrNBI’s plist for when you next run AutoImagrNBI.
NetBoot Required Settings
AutoImagrNBI will set this field to “<OS version> AutoImagrNBI,” this name is the name of the folder AutoImagrNBI will create for the NBI, as well as the name of the NBI that is shown to clients (except when running NetSUS as this shows as “Faux NetBoot”)
If uploading to NetSUS or BSDPy, this name cannot contain a space & by enabling “Will be served from a NetSUS appliance” should remove any spaces you have. In AutoImagrNBI this option is ticked by default.
NetBoot Image Index:
A NetBoot Images Index (alongside it’s name) is used to identify the NBI to clients & server.
If this NBI is to be hosted on only one server, then the image index will need to be a value between 1-4095. But, if you’re load-balancing the NBI by hosting it on more than one server you’ll need to set a value between 4096-65535.
The value of the index is randomly determined by AutoImagrNBI & is dependent on whether the “Will be served from more than one server” checkbox is enabling.
Serve Image Over:
Depending on your environment, one option may work better than the other. You can select which option to set in the NBI here.
NOTE: The selections made to “Will be served from a NetSUS appliance”, “Will be served from more than one server” & “Serve Image over” are written to AutoImagrNBI’s plist.
Technically, you could just hit the build button & be on your way. But AutoImagrNBI can do much more & does several things in creating an NBI.
Pressing the Options button will open a new tabbed window, each of the Tabs & the options within are discussed in detail below.
Each option also has a Tool Tip which explain their function.
Options – Always Set
Suppresses Apple/iCloud & Diagnostics Setup Assistants:
Creates & Auto logs in as Root:
AutoImagrNBI will always enable the root user & will auto login as root.
The root users password is set to: netboot.
Imagr requires running as root & was originally planned to be running in a NetInstall where root is the only user.
Disable Screen Saver for Root account:
As the screen saver being activated can pause some processes, the screensaver is disabled for the root account.
This plist can add “unwanted” items to the dock, so it’s removed.
Creates A Minimal Dock for Root Account:
Copies Imagr to the NBI’s Applications Folder:
The Imagr.app selected earlier is copied into the /Applications folder of the NBI.
Launches Imagr At Login:
A Launch Agent is installed which launches Imagr once logged into the NBI.
This Launch Agent can be found at: /Library/LaunchAgents/com.AutoImagrNBI.Imagr.plist
Removes Imagr’s Quarantine Flag:
If the version of Imagr selected is one that has just been download from GitHub, it may still have the Quarantine Flag. AutoImagrNBI removes the flag if present.
Disables App Nap:
Similar to the screen saver, App Nap is disabled in case an app is napped.
Disables Software Update:
Software Update is disabled as not needed on an NBI.
Spotlight indexing can stop a volume from being unmounted, & so Spotlight is disabled.
Disables TimeMachine prompts:
OSX, by default, will ask if you wish to use new disks for TimeMachine backups. This can get boring pretty fast when imaging macs, as you can see the prompt several times. So AutoImagrNBI disables the prompts.
Gatekeeper is “disabled” by setting it to “Allow apps downloaded from anywhere.” This again stops any prompts from interfering with the imaging process.
Enables Disk Utilities Debug Menu:
Disk Utilities Debug menu is enabled, giving access to some more detailed information which can be handy when troubleshooting.
Enables Diskless NetBoot:
NBI’s used for Imagr are required to be diskless, so that the booted Macs HD can be erased or partitioned as needed.
Expands NetBoot Image to 64GB:
The NBI is set to expand up to 64GB, this is to allow for more disk space to be created if needed by applications running on the NBI without expanding on the size used by the NBI.
Compacts NetBoot Image:
To save on disk space used by the NBI itself, the NBI is compacted at the end of the process, so this is after installing any extra Packages etc.
Renames Sparseimage to DMG for hosting on NetSUS:
Currently, NetSUS can only host NBI’s that end .dmg. As such, if the option “Will be served from a NetSUS appliance” is ticked then the NBI’s DMG is renamed.
Options – App Config
NOTE: Anything set in this panel is written to AutoImagrNBI’s plist.
Imagr allows you to send report information to either a HTTP server via POST, or a Syslog server.
For more information, please see the Imagr Wiki
Options – Standard
Set NetBoot Description:
If selected, AutoImagrNBI will generate a description for the NBI that contains the OS.dmg’s OS & build versions, Imagr’s version, the Imagr URL (if supplied), the name of the user that created the NBI & the date of creation.
Reduce Image Size:
Reducing the NBI’s size is not needed, really it’s not.
NetBoot clients will only pull the data required to boot the OS, so starting with a clean OS.dmg will lower what the clients request.
However, AutoImagrNBI can be used to reduce the size of the NBI by checking this box.
The resulting DMG size will vary, but for 10.7-10.9 NBI’s it falls under 8GB, for 10.10 it’s around 8.7GB. This dmg will be named NetBoot.reduced.dmg & will be in the NBI folder.
There is a long list of items that AutoImagrNBI removes, & whilst i’ve not listed them anywhere other than the code, below are the apps & utilities that are left on the NBI post reduction:
/Applications/Imagr.app /Applications/Launchpad.app /Applications/Safari.app /Applications/System Preferences.app /Applications/TextEdit.app /Applications/Utilities/Activity Monitor.app /Applications/Utilities/Console.app /Applications/Utilities/Disk Utility.app /Applications/Utilities/Grab.app /Applications/Utilities/Keychain Access.app /Applications/Utilities/System Information.app /Applications/Utilities/Terminal.app
Also, some Preference Panes are removed leaving only the following:
/System/Library/PreferencePanes/DateAndTime.prefPane /System/Library/PreferencePanes/Network.prefPane /System/Library/PreferencePanes/SharingPref.prefPane /System/Library/PreferencePanes/StartupDisk.prefPane
One last point to mention is that the default desktop is also removed when reducing the NBI, this results in a background like the following (note the below has had a custom dock deployed).
One of the benefits of imaging via a NetBoot instead of a NetInstall is that you can remotely connect via screen sharing. This allows you to image macs that are either 1 desk, or 1,000 miles away & review the progress.
Another benefit of NetBoot, is that you can perform some diagnostics when NetBooted, things like repairing permissions etc are possible as you’re not booted to the same volume you’re running the repair on.
If you check “Enable ARD” the username & password you enter are written in plain text to AutoImagrNBI’s plist, but on the NBI itself they are encoded. When the NBI is started up, AutoImagrNBI’s launch daemon runs a script that will create a user with the username & password given & then enables ARD.
When “Enable VNC”, is checked the VNC password is written to the NBI in the following file,
/Library/Preferences/com.apple.VNCSettings.txt this password is obfuscated via a perl command.
This password is again written to AutoImagrNBI’s plist.
Checking this option will replace the default desktop located: /System/Library/CoreServices/DefaultDesktop.jpg with the image you supply.
Nothing is done in regards to resizing etc, so bare that in mind with the image you set.
The path to this image is written to AutoImagrNBI’s plist. On build AutoImagrNBI will check that the image exists, alerting if it cannot be found.
Options – Advanced
NOTE: Anything set in this panel is written to AutoImagrNBI’s plist.
Here you can set the NTP for the NBI to use as well as the timezone.
The “Time Zone” pop up includes the main locations for setting timezones on OSX, it’s not the complete list, but it’s the primary ones. You should be able to find a location appropriate for the timezone you wish to set.
From the “NetBoot Language” pop up includes a list of OSX’s “tier 1 languages” (to quote Apple), the “Input Language” pop up includes all of OSX’s supported input languages.
Create a Restorable DMG:
When this option is checked, AutoImagrNBI will create a second ASR’d read-only DMG in the root of the folder AutoImagrNBI creates.
This read-only DMG can then be restored to external media, such as a USB stick. This gives you a portable OS from which you can image.
This option is ticked by default in AutoImagrNBI, & creates a 2GB RAM Disk instead of the NetBoot image using AFP Shadow files. Which some 3rd party NetBoot server do not offer.
With OSX Servers NetInstall service, after the 10th or so client has booted the using AFP Shadow Files there are often issues booting more.
For several years people have used the following guidance from the University of Utah to modify the rc.netboot file to allow more than 10 clients to boot.
Checking this option replaces the NBI’s standard rc.netboot file with a modified version of the above linked example & was supplied by foigus.
Enable Simple Finder:
Simple Finder is a stripped down, simplified version of the Finder. Checking this enables Simple Finder, which results in the Finder behaving such as what’s mentioned here.
Options – Additionals
NOTE: Anything set in this panel is written to AutoImagrNBI’s plist.
Certificates added here are copied to the following location on the NBI:
When the NBI is started up, AutoImagrNBI’s launch daemon runs a script that trust as root any certificates found in this location.
Install Additional Packages:
Packages added here, are installed onto the NBI after any items are deleting off the NBI (if reducing), but before the final NetBoot.dmg is created.
On launch & pre-build AutoImagrNBI checks that the selected certificates &/or packages exist.
If any certificates &/or packages cannot be found when the build button is pressed, you’ll receive an alert & the build will stop.
Any that are missing are shown in red under the “Additionals” tab.
If they are missing as you’ve not connect some removable media they were on, reconnect the media & then click the refresh button.
AutoImagrNBI will again check that the items exist & in finding them, will change the text to black.
Administrative privileges are required by AutoImagrNBI in order to build the NBI without prompting for permissions every 5 minutes as per sudoers 5 minute timeout.
AutoImagrNBI caches the entered username & password to variables within AutoImagrNBI & they are not written anywhere.
NBI Folder Location
On clicking “Build” AutoImagrNBI will ask for the location to create the NBI’s enclosing folder.
This folder will be named the the same as what you set the NBI name to, & within there will be the .nbi folder for uploading to a NetBoot Server. Also, the .restorable.dmg, will be located in this folder at the same level as the .nbi folder.
With a location selected, AutoImagrNBI checks to make sure there is enough space available to create the NBI.
AutoImagrNBI reads the used space on the OS.dmg, rounds up the used space & then checks the destination to see if we have enough space, erroring if not.
Building The NBI
Once “Build” has been pressed, AutoImagrNBI will again check the version of the Imagr.app you have selected against the latest release & offer to download the latest release if you’ve selected an older one.
When all other checks have passed, AutoImagrNBI will close it’s windows & show the progress bar shown above. This gives visible feedback as to the builds progress.
The contents of OS.dmg are copied to a new DMG within the NBI folder. (Well a sparse image which is then renamed dmg).
You may see AutoImagrNBI show as “not responding” during the NBI creation, this is normal & a side affect of writing an app in AppleScript as it’s not able to multiple thread.
During these “hangs” the cogs animation will continue, just leave AutoImagrNBI to do it’s thing.
The NBI creation can take upto 20 minutes on a Mac with an SSD, to 90 minutes if running on a spinning disk.
Once the NBI has been created a few things happen:
- The main window should reappear.
- OSX’s complete notification will sound.
- The progress window will look like the below.
Whilst AutoImagrNBI is creates a Read-Write sparseimage, this is renamed from NetBoot.sparseimage to NetBoot.dmg to make sure the resultant NBI is compatible with not only OS X’s NetInstall service, but also BSDPy & NetSUS.
If you wish to make the NBI Read-Write again, rename to NetBoot.sparseimage. Make your changes then rename back to NetBoot.dmg.
AutoImagrNBI writes it’s logs to ~/Library/Logs/AutoImagrNBI/. These can be quite verbose, but are handy if you need to troubleshoot why AutoImagrNBI is failing to create the NBI or if you just wish to have a nose at what it’s doing.
If you do have any issues, please log them here. You are taken to the same page when you select Help > Log An Issue from the menu bar.
The log can also be accessed when the build has completed or failed by clicking the “Open Log” button.
AutoImagrNBI checks for updates once a day, if an update is found you’ll will be asked to update.
You can also manually check for updates by clicking AutoImagrNBI > Check For Updates.. from the menubar.
AutoImagrNBI will generally error out with a message like the below that has a button that links to the log:
AutoImagrNBI & Casper NetInstall Creator leverage the same methods to create NetBoot & NetInstall images as System Image Utility.
These scripts can be found at the following location on 10.9:
/System/Library/CoreServices/System Image Utility.app/Contents/Frameworks/SIUFoundation.framework/Versions/A/XPCServices/com.apple.SIUAgent.xpc/Contents/
Whereas on 10.10 it’s:
/System/Library/CoreServices/Applications/System Image Utility.app/Contents/Frameworks/SIUFoundation.framework/Versions/A/XPCServices/com.apple.SIUAgent.xpc/Contents/Resources/
They are highlighted below.