Posted on 21st December 2015 by Ashley

Imagr 101: Web Service

Imagr banner

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.

 

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’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/).

Imagr 101 blog - part 2 - blog pic 1

 

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.

e.g.

cd /Volumes/Data HD

Imagr 101 blog - part 2 - blog pic 2

 

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.

e.g.

mkdir ./Imagr
ls -al

Imagr 101 blog - part 2 - blog pic 3

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.

e.g.

mkdir ./Imagr/workflow
mkdir ./Imagr/images
mkdir ./Imagr/packages
mkdir ./Imagr/scripts

Imagr 101 blog - part 2 - blog pic 4

 

5. Again, we’ll use the `ls` command to confirm these folders have been created.

e.g.

ls -al ./Imagr/

Imagr 101 blog - part 2 - blog pic 5

 

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.

e.g.

chmod -R a+rX ./Imagr

Imagr 101 blog - part 2 - blog pic 6

 

7. That’s most of the groundwork done. Next, leave the Terminal window open and launch the Server.app.

Imagr 101 blog - part 2 - blog pic 7

 

8. Go to the ‘Websites’ section on the left hand side.

Imagr 101 blog - part 2 - blog pic 8

 

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.

Imagr 101 blog - part 2 - blog pic 9

 

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.

Imagr 101 blog - part 2 - blog pic 10

 

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:

"/Library/Server/Web/Data/Sites/Default/"

Imagr 101 blog - part 2 - blog pic 11

Imagr 101 blog - part 2 - blog pic 12

 

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.

Imagr 101 blog - part 2 - blog pic 13

Imagr 101 blog - part 2 - blog pic 14

 

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/"

Imagr 101 blog - part 2 - blog pic 15

 

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.

Imagr 101 blog - part 2 - blog pic 16

 

16. Double click this and, if step 13 worked fine, you should get taken to your Imagr data folder.

Imagr 101 blog - part 2 - blog pic 17

 

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.

Imagr 101 blog - part 2 - blog pic 18

 

19. On the new popup screen, tick the “Allow folder listing” box, and click “OK” to close the window.

Imagr 101 blog - part 2 - blog pic 19

 

20. Click “OK” again to close the settings window.

Imagr 101 blog - part 2 - blog pic 20

 

21. Once back on the main Websites section, click the “Off” button to turn the service on.

Imagr 101 blog - part 2 - blog pic 21

 

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).

Imagr 101 blog - part 2 - blog pic 22

 

24. You should see the default Apple web browser homepage.

Imagr 101 blog - part 2 - blog pic 23

 

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.

Imagr 101 blog - part 2 - blog pic 24

 

26. You should now be able to see all the folder directories we created in step 4.

Imagr 101 blog - part 2 - blog pic 25

 

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.

e.g. https://amsys-imagr-blog-server.local

Imagr 101 blog - part 2 - blog pic 26

 

30. When the SSL certificate warning message appears, click “Show Certificate”

Imagr 101 blog - part 2 - blog pic 27

 

31. Tick the “Always trust…” box and click “Continue”

Imagr 101 blog - part 2 - blog pic 28

 

32. Enter the local administration username and password when requested.

Imagr 101 blog - part 2 - blog pic 29

 

33. Once the webpage is loaded, quit Safari.

34. Launch the Keychain Access application. This is found in the Utilities folder (/Applications/Utilities/).

Imagr 101 blog - part 2 - blog pic 30

 

35. Once launched, find the certificate we saved in steps 31 and 32. Click to highlight it.

Imagr 101 blog - part 2 - blog pic 31

 

36. Go to “File” > “Export Items” to export the certificate.

Imagr 101 blog - part 2 - blog pic 32

 

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”.

Imagr 101 blog - part 2 - blog pic 33

 

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.

 

Summary

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.