Imagr 101: Web Service
Hi All, and welcome back to our series on configuring Imagr. Last time, we introduced you to Imagr and ran through the setup of the NetBoot / NetInstall service.
This ‘part 2’ looks to cover the configuration of the OS X web service to host the Imagr data. ‘Part 3’ will cover the creation of the Netboot set using AutoImagrNBI. ‘Part 4’ will 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.
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
- Auto[X]NBI (such as AutoCasperNBI or AutoImagrNBI)
- Editing XML files (or OS X plist files)
I’m also assuming you’ve got a fully working Mac OS X server setup and running.
I will often be using “Repo” as shorthand for “Repository” throughout this series.
Step-By-Step: The Repo Web Server
One of the reasons that Imagr can easily be used cross-platform is its use of a standard web server to host both the configuration files, and the data used (such as OS images, installer packages and scripts). In a similar way to the Munki blog, we will configure the built in version of Apache that Apple uses with their server offering.
Additionally, new with OS X Yosemite, Apple introduced a default rule on the built in Server.app webserver to redirect HTTP requested websites to HTTPS. As part of this series, I will leave this in place, as it is good practice. If you need to use HTTP, you will need to disable the redirect in the options of the HTTP website.
Please Note: In this guide, we will be using the basic self-signed certificate generated by the Server.app. If you wish to use a similar setup in production, ensure to replace this with a ‘proper’ signed SSL certificate. See Ben Toms’ great JNUC talk on certificates here: Let’s talk about certs.
Lets get to it!
1. Fire up the Terminal application. I’ve added this to my Dock for quick access, but it can be found in the Utilities folder (in /Applications/Utilities/).
2. Navigate to your ‘service data’ storage location using the `cd` command. In my example, I am using a secondary non-boot volume called “Data HD”. I’d consider this good practice, as it’ll stop any services filling up the server’s boot drive, causing performance, crashing and booting issues.
cd /Volumes/Data HD
3. In this top-level area, I’m going to create a specific and dedicated folder for the Imagr data (using the `mkdir` command). This isn’t required and quiet often, Administrator’s will utilise existing locations, such as an existing Munki repo. I then use the `ls` command to check that the folder has been created.
mkdir ./Imagr ls -al
4. I will now create four folders, inside this ‘Imagr’ folder to organise the data I will be using. Again, this is not required but I find it is easier to find items for other team members you maybe sharing the administration with. These folders are specifically:
a) ‘workflow’ – To store the main Imagr configuration plist detailing each Workflow and the tasks to carry out.
b) ‘images’ – To store the OS images that will be deployed using Imagr.
c) ‘packages’ – To store the installer packages that will be deployed using Imagr.
d) ‘scripts’ – To store the scripts that will be run using Imagr.
mkdir ./Imagr/workflow mkdir ./Imagr/images mkdir ./Imagr/packages mkdir ./Imagr/scripts
5. Again, we’ll use the `ls` command to confirm these folders have been created.
ls -al ./Imagr/
6. Now we need to make sure all these directories we’ve created have the correct permissions. We need to use the `chmod` command to add the ‘read’ and ‘execute’ permissions to the Imagr folder and downwards.
chmod -R a+rX ./Imagr
7. That’s most of the groundwork done. Next, leave the Terminal window open and launch the Server.app.
8. Go to the ‘Websites’ section on the left hand side.
9. Click to highlight the “Server Website (SSL)” text and click the ‘pencil’ / edit button. Alternatively, double-click the “Server Website (SSL)” text to open the same edit window.
10. This will show you the options set for the HTTPS side of the web service. Much like setting up the Munki web server, we need to redirect the web site storage to the ‘service data’ drive. Click the arrow next to the “Store Site Files in” box.
11. This will show the location of this storage area in a new Finder window. Hold down the Apple / ‘cmd’ key and click the folder name in the top of the window to see the path to this folder. Make a note of this.
For my example, the path would be:
12. Another method to make it easier is to enable “Show Path Bar” in Finder. Click the “View” menu, followed by “Show Path Bar”. This will then show the full path to the current item in the bottom of the Finder Window.
13. Right, now we’re going to use the `ln` command, as root (sudo), to create a sym-link from inside this folder, to our Imagr folder. Go back to the Terminal window and enter the following, substituting [path to Imagr folder] for the full path to your Imagr folder created in step 3, and [path to web service folder] with the full path as found in step 11:
Please Note: All spaces must be ‘escaped’ for this to work. The simplest method is to wrap the entire path in double quotes. This must not be ‘curly’ double quotes as seen in word processors, but should be the straight ones as seen in scripts. If in doubt, manually write out (not copy) the example texts.
sudo ln -s "[path to Imagr folder]" "[path to web service folder]"
In my example, it would be:
sudo ln -s "/Volumes/Data HD/Imagr" "/Library/Server/Web/Data/Sites/Default/"
14. Enter your administration password when requested.
15. Once complete, you should be able to switch back to the Finder window showing the web server data folder and see a new ‘Imagr’ shortcut icon.
16. Double click this and, if step 13 worked fine, you should get taken to your Imagr data folder.
17. We are now going to test that the sym-link works from a web-browser. This will involve temporarily enabling the folder listing option.
18. Go back to the Server.app and, on the SSL site, click the “Edit Advanced Settings…” button.
19. On the new popup screen, tick the “Allow folder listing” box, and click “OK” to close the window.
20. Click “OK” again to close the settings window.
21. Once back on the main Websites section, click the “Off” button to turn the service on.
22. Give this a minute to turn to complete its enabling steps, then launch Safari.
23. Navigate to https://127.0.0.1, dismissing the SSL certificate area (this will popup as you are accessing the server as ‘127.0.0.1’ and the SSL certificate that is provided is for a full hostname).
24. You should see the default Apple web browser homepage.
25. If this loads successfully, click back into the address bar and add “/Imagr” to the URL (https://127.0.0.1/Imagr) and attempt to load this.
26. You should now be able to see all the folder directories we created in step 4.
27. Quit Safari, go back to the Server.app, repeat steps 18 – 20 and use the ‘On / Off’ switch to restart the service. This will disable the folder listing option on the HTTPS site, stopping users (or anyone else) from browsing your Imagr repo and helping themselves to the contents.
There you go; that’s the web service configured and ready for content. If you are using a self-signed SSL certificate for this lab (as I am with these examples) there’s one more step we need to complete to obtain the certificate, ready to add into the client NetBoot Image.
Step-By-Step: Obtaining the SSL Certificate
These steps are only required if your Web server SSL certificate is not trusted by default by the NetBoot’d client OS.
28. Grab a second Mac / Virtual Mac OS and launch Safari.
29. Navigate to the HTTPS site for your Imagr web server repo.
30. When the SSL certificate warning message appears, click “Show Certificate”
31. Tick the “Always trust…” box and click “Continue”
32. Enter the local administration username and password when requested.
33. Once the webpage is loaded, quit Safari.
34. Launch the Keychain Access application. This is found in the Utilities folder (/Applications/Utilities/).
35. Once launched, find the certificate we saved in steps 31 and 32. Click to highlight it.
36. Go to “File” > “Export Items” to export the certificate.
37. You’ll be asked where you’d like to save this. I’d suggest to your desktop and ensure that the type is “Certificate (.cer)”. Click “Save”.
38. Quit Keychain Access and keep a copy of that SSL cert to hand for next time!
And that’s pretty much it. Congratulations you now have your web server up and running ready to add some content
Next time, we look at configuring a NetBoot set to work with your Imagr solution using Ben Toms’ AutoImagrNBI.
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.