Hi All, and welcome back to our series on configuring Imagr.
Last time, we ran through the setup of the NetBoot image to use with Imagr.
This ‘part 4’ looks to cover populating the Imagr repo with content and building a workflow. ‘Part 5’ will look at some possible use cases for Imagr with the current popular management tools.
Key Facts
OS Used: OS X El Capitan (10.11.1)
Server App Used: 5.0.15
Imagr Used: 0.0.4
Recommended knowledge (but not required):
- Apple NetBoot server configuration
- AutoDMG
- Auto[X]NBI (such as AutoCasperNBI or AutoImagrNBI)
- Editing XML files (or OS X plist files)
I will often be using “Repo” as shorthand for “Repository” throughout this series.
UPDATE 28 January 2106:
Between writing this blog and publishing it, there have been a lot of updates to Imagr.
The current version is 1.0.1 and so I’d highly recommend using the latest version.
Step-By-Step: Adding Items into the Repo
Before we can configure a workflow with items, we need to add those items to the Repo.
1. On your Repo server, open up Finder and navigate to the location of your Imagr folder. In the example, this is located at /Volumes/Data HD/Imagr.
2. For the example, I will be using the following items:
c) “Enable_VNC.sh” – Another shell script to enable VNC with some basic settings.
d) “001-outset-1.0.2.pkg” – An installation package to install the basic components of the Outset solution (see here for more information on Outset)
e) “002-Ouset-setupAssistant-1.0.pkg” – Another installation package that uses Outset to setup a profile on every boot to skip the iCloud setup request (see here for more information on SetupAssistantProfiler).
Please Note: In my screenshots, these installer packages are shown with spaces in the filenames. In practice these caused issues when trying to be retrieved from the web server Repo. I would strongly recommend removing all spaces in the filenames for disk images, installers and scripts you use with Imagr. To be honest, I’d recommended this as general good practice (as I’ve done in the past and forgotten when running through this screenshots)!
3. Drag these items into the relevant folders, within the Imagr directory, e.g. OS images into ‘images’, installers into ‘packages’ and scripts into ‘scripts’.
4. Next we need to move the imagr_config.plist file into the ‘workflow’ folder. You can create this from scratch, or grab the template version from the Imagr GitHub page. I have also put up a template configuration file in our GitHub here . This guide will be assuming you are using the Amsys template version, only as it contains all the relevant sections we’ll work through as part of this blog.
5. However you get your copy of “imagr_config.plist”, drag a copy into the ‘workflow’ folder in the Imagr directory.
6. Right, once we’ve got this in place, we’re going to need to edit this using a plain text editor. Personally, I’d recommend TextWrangler but feel free to use your own favourite. Please do not use Microsoft Word, or TextEdit as these will do funny things to the file and break its functionality.
7. I’d suggest, once you’ve got your chosen editor installed, use the ‘right click’ > “Open With” menu item to open the file in this application.
8. You should see the contents of the file open and ripe for editing!
Step-By-Step: Configuring the imagr_config.plist
Still with me? Good, as this next section is going to have us hand-editing XML files and so might get a little heavy!
9. The first bit we need to change / add is the password key and value. This is the password that the technician would need to enter before the can view the Imagr workflows. To quote the wiki (here ):
This section needs to be within the initial dictionary (“<dict>”) tags, but outside any others (such as the ‘workflows’ keys). This is stored as a SHA hash within the plist. The example below was for ‘apple’ as the password so we need to change this!
10. Launch your Terminal application (located in /Application/Utilities/).
11. Run the below command, substituting the words “YOURPASSWORDHERE” with…well, your chosen password! I’ve used “apple123” in these examples.
python -c 'import hashlib; print hashlib.sha512("YOURPASSWORDHERE").hexdigest()'
12. You will get back the SHA hash of your password. This is on one line, but may wrap onto a second line in the GUI due to its length.
13. Highlight this and copy it.
14. Switch back to your imagr_config.plist, and highlight the hash that is already present. Ensure to not also select the two “string” tags on the same line (shown as “<string>” and “</string>”).
15. Now paste your SHA hash you copied from step 13, ensuring there are no spaces at the end of it. This will overwrite the old password with your new one.
16. The next section we’ll move onto is ‘workflows’. This is an array of dictionary items, with each dictionary item a separate workflow. To keep things simple, we’ll stick with one workflow for this example.
17. Let’s start with the ‘name’ key. This is the name of the workflow as shown to the end user. As each workflow is its own dictionary item, there will be a ‘name’ key for each dictionary item. In the Amsys template, this has the value “Rename and image the Mac”. Find this in the template plist.
Please Note: Some XML editors will format keys within dictionaries and arrays in alphabetical order. As you can probably see with the Amsys template, this puts the ‘name’ key towards the bottom of the XML.
18. Edit this value to the chosen name for your workflow. This is the first thing your technician will see when picking a workflow to run. As with step 14, ensure to not remove the ‘string’ tags. In the example screenshots, I have changed this to “Rename, image with 10.11.1 and install outset”
19. Next is the ‘description’ key. As you can imagine, this is the description of the workflow. As per the ‘name’ key, this is unique to each workflow. In the Amsys template, this has the value “Deploys a 10.10.1 image and renames the device” and is above the ‘name’ value.
20. Edit this value to the chosen description for this workflow. This is the second thing your technician will see when picking a workflow to run, as it’s shown when the relevant workflow is selected (put not started). This is a similar behaviour to DeployStudio. As with steps 14 and 18, ensure to not remove the ‘string’ tags. In the example screenshots, I have changed this to “Deploys a 10.10.1 image, renames the device, installs Outset and sets up a boot script to disable the iCloud…”
21. Next is the (optional) restart_action key (more information) . This key tells the workflow what to do once its finished its other tasks. Options are ‘none’ (do nothing), ‘restart’ (set the target volume as the start-up disk and restart) and ‘shutdown’ (set the target volume as the start-up disk and shutdown). As per the ‘name’ and ‘description’ keys, this is a ‘per-workflow’ option. In the Amsys template, this has the value “restart” and is at the bottom of the XML file.
22. Change this as required. In the example screenshots, I have changed this to “shutdown”. If this key is missing, Imagr will use the default behaviour of ‘none’.
23. Next is the (also optional) bless_target key (more information). This key tells the workflow if it should set the target volume as the system boot disk. Options are ‘true’ (set the target volume as the start-up disk), and ‘false (don’t set the target volume as the start-up disk). As per the ‘name’ and ‘description’ keys, this is a ‘per-workflow’ option. In the Amsys template, this has the value “true” and is at the bottom of the XML file.
24. Change this as required (if you need to). In the example screenshots, I have left this as “true”. If this key is missing, Imagr will use the default behaviour of ‘true’.
25. So that’s the key options of the workflow as a whole configured and set. Don’t forget to save the file as you go! Next, we’ll look at the workflow ‘tasks’ that can be used to deploy our items we copied into the Repo, back in step 3. These are added into each workflow dictionary item, into another array under the ‘components’ key. This array, much in the same way as the ‘workflow’ array, is made up of dictionary items for each task. Told you this was going to get a little heavy!
Please Note: These will be run in the order specified so I would suggest an order something along the lines of:
- ‘image’
- ‘Computer Naming’
- Any scripts and / or installers
See Component Ordering for more information.
26. First up, deploying an Image (more information ). This dictionary item will mount the disk image over HTTP / HTTPS and restore the data using ASR (Apple Software Restore).
27. This needs a full URL to the item, of the format:
In the example, our disk image lives in the Imagr directory, in an ‘images’ folder:
28. As a result, in this example, the URL for this image will be:
Enter this into the “url” key for the disk image and, as before, keep the ‘string’ tags intact.
29. Next one, computer name (more information). This dictionary item, left as-is and with no additional keys, will prompt the technician for the desired device name. If the technician doesn’t supply one, Imagr will try to pull the name from the current target volume and use this. If this doesn’t work, or is not possible (such as its blank or not set on the target volume) then it will set the name to blank.
30. You can add further options for using the device serial number, and preventing the technician from providing a name (and overriding other options), details of which can be found on the Imagr wiki. For this example, we’ll let the technician set the name.
31. Next, is the package task (more information). This dictionary item will grab a copy of the specified package, and either copy it locally to the target volume for installation on first boot (default behaviour), or will run it whilst booted to the NetBoot image.
32. In the same way as for the image task (step 29), this needs the URL path to the item in question. In our example, the first package we want to install lives in the Imagr directory, within the ‘packages’ folder:
33. As a result, in this example, the URL for this image will be:
Enter this into the “url” key for the disk image and, as before, keep the ‘string’ tags intact.
34. By default, this will install the package on first boot. But what if you don’t want that behaviour? You can use the (optional) ‘first_boot’ key in your package task.
35. Change the value from ‘true’ to ‘false’ to have this specific installer package run within the NetBoot Image, onto the ‘target volume’.
Please Note: To use this option, any scripts within the specific installer package must work on a non-boot volume.
36. Package task fully configured! But my example had two installer package items and you may have even more. How do we get these to run too?
37. Firstly, I’d recommend keeping the items installed and configured by Imagr to a minimum, and instead use it to ‘boot strap’ a device into your management solution (more on that, in part 5).
38. However, taking off the Grinch hat, it can be done. Highlight the entire ‘package’ section, including it’s opening and closing ‘dict’ tags.
39. Add a line under the close ‘dict’ tag, and paste the copied ‘package’ task, thereby duplicating the full dictionary item.
40. Repeat steps 32 to 35 for this new, second package task. In this example, I have added the “002-Outset-SetupAssistant-1.0.pkg” installer.
41. If you don’t have any installers you wish to run as part of this workflow, simply highlight the task as per step 38, and remove it, instead of copying it.
42. Next up, running scripts (more information ). Imagr can run scripts in one of two ways, embedded or from a URL. With an embedded script, the contents of the script live within the imagr_config.plist itself, and any ‘non-xml safe characters’ would need to be escaped. In my opinion, this is more work, with more potential to go wrong, and can make your imagr_config.plist file a little messy.
43. The second method works in pretty much the same way as the image and package tasks, and will pull the script from the Repo and run it.
44. In the same way as for the image task (step 29), this needs the URL path to the item in question. In our example, the first script we want to install lives in the Imagr directory, within the ‘scripts’ folder:
45. As a result, in this example, the URL for this image will be:
Enter this into the “url” key for the disk image and, as before, keep the ‘string’ tags intact.
46. In the same way as the package task, by default, the script task will run the scripts on first boot. To override this behaviour, use the same “first_boot” key we used for the package task, in exactly the same way (steps 34 and 35).
47. Script task fully configured! But again, my example had two to run and you may have even more. How do we get these to run too? The same way as we did for the package tasks.
48. Highlight the entire ‘script section, including it’s opening and closing ‘dict’ tags.
49. Add a line under the close ‘dict’ tag, and paste the copied ‘package’ task, thereby duplicating the full dictionary item.
50. Repeat steps 44 to 46 for this new, second script task. In this example, I have added the “Enable-Automatic-SUS.sh” script.
51. If you don’t have any scripts you wish to run as part of this workflow, simply highlight the task as per step 48, and remove it, instead of copying it.
52. Quit your text editor and save the edited file.
53. That completes the configuration of the imagr_config.plist.
Step-By-Step: Validating the plist and testing the URLs
So we’ve got your workflow plist file configured, but we’ve made a lot of manual changes. How can we test these changes are good? The Imagr GitHub has you covered using the ‘validateplist’ tool.
54. Download the latest releases DMG, or clone the GitHub repo to your local machine, or navigate to the GitHub page in a web browser (https://github.com/grahamgilbert/imagr) and download a Zip of the repo.
55. Un-zip the download so you can access the files. Find the ‘validateplist’ tool in the Finder.
56. Launch the Terminal application (/Applications/Utilities/) and drag the ‘validateplist’ tool into the Terminal window. This will complete the full path to the tool.
57. Find your imagr_config.plist in the Finder, and drag this in after the ‘validateplist’ tool, leaving a single space in between. Hit enter to run the tool.
58. You should get a message to say “SUCCESS: [path to plist] looks like a valid Imagr configuration plist.”
59. If you see any errors or failures, the tool will tell you what part of the configuration file it doesn’t like. The tool will check for items such as:
b) Is it using options that are known to Imagr?
c) Does each built in task have all the required keys?
It will not check if the URLs you have provided are valid and correct, but it’s a good and fast initial check of your configuration plist file.
60. If your Repo is live and accessible, you can also swap out the file path we grabbed in step 57 with the full URL to the imagr_config.plist, like so:
61. So your plist file is good, but what about all those URLs you specified in each task? Simply copy each URL out of the workflow task (without the tags) and paste into a web browser. If successful, the browser should be able to download the files.
Pre-testing complete. Now it’s time to run a full test!
Step-By-Step: Full Testing!
The final section, full testing!
62. Grab a spare Mac, or a VM and NetBoot it to your Imagr NetBoot Image we created last time.
63. As before, eventually the Imagr local application will launch. This time it will ask you for the password, the same one we configured in steps 9 to 15. Enter this and click “Login”.
64. You will be greeted with the main workflow ‘chooser’ menu.
65. Use the “Choose Target” dropdown menu to select the storage volume you wish to run the workflow on. By default this will target the first non-booted volume, which typically would be the internal Hard Drive.
66. Use the “Choose Workflow” dropdown menu to select the workflow you wish to run. The name/s listed here are the ones we’ve set in step 18 above.
67. When you pick the workflow in step 66, the box below will show the description. This is what we set in step 19 above.
68. Once you’ve got your workflow and target selected, click “Run Workflow” to start things off.
69. The first task will ask you to specify a name for the computer (as we configured in step 26). Fill this in and click “Set Computer Name”.
70. The Imagr application will now work through the remaining steps. Restoring the OS image, installing packages and running scripts.
71. Once complete, the device will reboot (as per what we configured in step 21).
If your workflow reaches this far, then Congratulations! You’ve successfully got an Imagr lab configured and running! Go forth and play!
Summary
Congratulations you now have your Imagr solution lab image up and running and deploying Macs!
Next time, I’ll offer some specific use cases that I’ve come across for Imagr, as well as touching on some more advanced features and next steps.
As always, if you have any questions, queries or comments, let us know below and I’ll try to respond to and delve into as many as I can. I’m especially eager to hear any feedback on this new series.
The usual Disclaimer:
While the author has taken care to provide our readers with accurate information, please use your discretion before acting upon information based on the blog post. Amsys will not compensate you in any way whatsoever if you ever happen to suffer a loss/inconvenience/damage because of/while making use of information in this blog.