In a previous post, I showed how to set up Sal.
Sal‘s basic functionality is useful on its own, for the basic Munki reporting – what are the completed installs, pending updates, what OS versions, how many devices checked in the past 24 hours, etc. In this post, I’m going to demonstrate how to get more out of Sal.
Adding in Facter:
You can add much more, though, by the use of Puppet, and more specifically, the piece of Puppet called Facter. Facter is a separate program that works with Puppet that simply gathers information (“facts”) about the host OS and stores them (ostensibly so that Puppet can determine what the machine’s state is and what needs to happen to it to bring it in line with configured policy).
At the bottom of Sal’s client configuration guide is a small section on using custom Facter facts. Puppet is not required to use Facter, and you can actually download it yourself as part of Puppet’s open source software.
Note: if you’re an Autopkg user, you can find a Facter recipe in the official default repo: autopkg run Facter.download
(or autopkg run Facter.munki
if you have Munki configured with Autopkg).
Install Facter on your clients, either with Munki or by simply installing the Facter.pkg.
Test out Facter on that client by opening up the Terminal and running Facter:
facter
You’ll see a whole lot of information about the client printed out. Handy!
Additional Facts:
A nice thing about Facter is that it’s easy to extend and customize with additional facts, which are essentially just Ruby scripts. Puppet Labs has documentation on Custom Facts here.
Graham Gilbert, the author of Sal, has also written some helpful custom facts for Macs, which I’m going to use here.
We’re going to need to get these facts downloaded and onto our clients. Use whatever packaging utility you like to do this, but all of those .rb files have to go into Facter’s custom facts directory. There are lots of places to put them, but I’m going to place them in /var/lib/puppet/lib/facter/
, where they can also be used by Puppet in the future.
Once those facts are installed on your client, you can run Facter again and access them using an additional argument:
sudo facter --puppet
Note that you now need sudo to see these extra facts. Facter needs administrative privileges to get access to those facts, so simply running facter --puppet
will give you the same results we had previously (before the new Mac facts were installed). This won’t be a problem, as the Sal postflight script, when executed with Munki, is run as root.
To make use of Facter with Sal, we need only run Munki again, which executes the Sal postflight: sudo managedsoftwareupdate
When the run is complete, take a look at the machine’s information in Sal. You’ll now see a “Facter” toggle with all of those neat facts for that client machine.
Faster Client Configuration:
One of the instructions as part of my Sal setup post, as well as part of the official documentation, is to set the client’s preferences for Sal URL and the Machine Group key for it to use. This was done using the defaults
command to write the preferences to the com.salsoftware.sal preferences domain.
Instead of using defaults
at the command line, we could also provide a simple .plist file that contains the two keys (machine group key, and URL) and two values, and place that in /Library/Preferences/com.salsoftware.sal.plist
. However, relying on .plist files to load preferences is problematic with cfprefsd, the preference caching daemon introduced in 10.9 Mavericks.
Well, if you can do it with defaults
, you can do it with configuration profiles! Configuration profiles (also known as .mobileconfig files) allow us to enforce preference domain values – such as enforcing the key and URL values for com.salsoftware.sal.
Making a configuration profile by hand is madness, so it’s better to use a tool that already produces profiles effectively – such as Profile Manager, Apple Configurator, or any MDM suite. That’s a lot of work just to get a profile, though.
Instead, we can thank Tim Sutton for his awesome mcxToProfile script, which takes a .plist or existing MCX object and converts it into a profile. We could use mcxToProfile to convert an existing com.salsoftware.sal.plist into a profile, but that means we now need to handcraft a .plist file for each Machine Group key we create.
I’m not a fan of manual tasks. I’m a big fan of automation, and I like it when we make things as simple, automatic, and repetitive as possible. We want a process that will do the same thing every time. So rather than create a plist for each Machine Group I want a profile for, and then run the mcxToProfile script, I’m going to write another script that does it for me.
All of this can be found on my Github repo for SalProfileGenerator.
Writing the script:
Here’s the code for the generate_sal_profile.py script:
#!/usr/bin/python import argparse import os from mcxToProfile import * parser = argparse.ArgumentParser() parser.add_argument("key", help="Machine Group key") parser.add_argument("-u", "--url", help="Server URL to Sal. Defaults to http://sal.") parser.add_argument("-o", "--output", help="Path to output .mobileconfig. Defaults to 'com.salsoftware.sal.mobileconfig' in current working directory.") args = parser.parse_args() plistDict = dict() if args.url: plistDict['ServerURL'] = args.url else: plistDict['ServerURL'] = "http://sal" plistDict['key'] = args.key newPayload = PayloadDict("com.salsoftware.sal", makeNewUUID(), False, "Sal", "Sal") newPayload.addPayloadFromPlistContents(plistDict, 'com.salsoftware.sal', 'Always') filename = "com.salsoftware.sal" filename+="." + plistDict['key'][0:5] if args.output: if os.path.isdir(args.output): output_path = os.path.join(args.output, filename + '.mobileconfig') elif os.path.isfile(args.output): output_path = args.output else: print "Invalid path: %s. Must be a valid directory or an output file." % args.output else: output_path = os.path.join(os.getcwd(), filename + '.mobileconfig') newPayload.finalizeAndSave(output_path)
Looking at the script, the first thing we see is that I’m importing mcxToProfile directly. No need to reinvent the wheel when someone else already has a really nice wheel with good tires and spinning rims that is also open-source.
Next, you see the argument parsing. As described in the README, this script takes three arguments:
- the Machine Group key
- the Sal Server URL
- the output path to write the profiles to
The payload of each profile needs to be enforced settings for com.salsoftware.sal, with the two settings it needs – the key and the URL. The URL isn’t likely to change for our profiles, so that’s an easy one.
First, initialize mcxToProfile’s PayloadDict
class with our identifier (“com.salsoftware.sal”), a new UUID, and filler content for the Organization, etc. We call upon mcxToProfile’s addPayloadFromPlistContents()
function to add in “always” enforcement of the preference domain com.salsoftware.sal.
The obvious filename to use for our profile is “com.salsoftware.sal.mobileconfig”. This presents a slight issue, because if our goal is to produce several profiles, we can’t name them all the same thing. The simple solution is to take a chunk of the Machine Group key and throw it into the filename – in this case, the first 5 letters.
Once we determine that our output location is valid, we can go ahead and save the profile.
Ultimately we should get a result like this:
./generate_sal_profile.py e4up7l5pzaq7w4x12en3c0d5y3neiutlezvd73z9qeac7zwybv3jj5tghhmlseorzy5kb4zkc7rnc2sffgir4uw79esdd60pfzfwszkukruop0mmyn5gnhark9n8lmx9
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>PayloadContent</key> <array> <dict> <key>PayloadContent</key> <dict> <key>com.salsoftware.sal</key> <dict> <key>Forced</key> <array> <dict> <key>mcx_preference_settings</key> <dict> <key>ServerURL</key> <string>http://sal</string> <key>key</key> <string>e4up7l5pzaq7w4x12en3c0d5y3neiutlezvd73z9qeac7zwybv3jj5tghhmlseorzy5kb4zkc7rnc2sffgir4uw79esdd60pfzfwszkukruop0mmyn5gnhark9n8lmx9</string> </dict> </dict> </array> </dict> </dict> <key>PayloadEnabled</key> <true/> <key>PayloadIdentifier</key> <string>MCXToProfile.2e34dadf-df5a-4b3c-b729-3a2a7bb7e44a.alacarte.customsettings.dcaacd13-3fea-47eb-991d-c0183c640b2e</string> <key>PayloadType</key> <string>com.apple.ManagedClient.preferences</string> <key>PayloadUUID</key> <string>dcaacd13-3fea-47eb-991d-c0183c640b2e</string> <key>PayloadVersion</key> <integer>1</integer> </dict> </array> <key>PayloadDescription</key> <string>Included custom settings: com.salsoftware.sal Git revision: a9edc21c62</string> <key>PayloadDisplayName</key> <string>Sal</string> <key>PayloadIdentifier</key> <string>com.salsoftware.sal</string> <key>PayloadOrganization</key> <string>Sal</string> <key>PayloadRemovalDisallowed</key> <true/> <key>PayloadScope</key> <string>System</string> <key>PayloadType</key> <string>Configuration</string> <key>PayloadUUID</key> <string>2e34dadf-df5a-4b3c-b729-3a2a7bb7e44a</string> <key>PayloadVersion</key> <integer>1</integer> </dict> </plist>
Adjusting mcxToProfile:
On OS X, plists can be handled and parsed easily because it’s built into the Foundation libraries. mcxToProfile itself incorporates several functions from Greg Neagle’s FoundationPlist library, which does improved plist handling compared to Python’s built-in plistlib.
Because of the reliance on the OS X Foundation libraries, however, we can’t use FoundationPlist outside of OS X. Since Sal is built to run on multiple platforms, and the Docker image is built on Ubuntu, we can’t use FoundationPlist as the core of our plist handling functionality.
Thus, we’ll need to make some adjustments to mcxToProfile:
try: from FoundationPlist import * except: from plistlib import *
In Tim Sutton’s original version of the script, he imports the necessary Foundation libraries into Python for use of them, and inline copied the parts of FoundationPlist he needed. If we’re going to make this more cross-platform friendly, we need to remove those dependencies.
So in my revision of mcxToProfile, I’ve removed all of the FoundationPlist functions completely from the code, instead relying on bundling a copy of FoundationPlist.py with the project. Instead of importing Foundation libraries, we’re going to try to use FoundationPlist – and if any part of that import goes wrong, we just abandon the whole thing and use Python’s built-in plistlib.
Dirty, but effective, and necessary for cross-platform compatibility.
Now we have a simple script for generating a profile for a Machine Key and URL for Sal that can run on any platform.
Automating the script:
Generating a single profile is a useful first step. The ultimate goal is to be able to generate all of the profiles we’ll need at once.
This script was written in Bash, rather than Python. You can find it in the Github repo here:
#!/bin/bash profile_path=`printenv PROFILE_PATH` if [[ ! $profile_path ]]; then profile_path="/home/docker/profiles" fi oldIFS="$IFS" IFS=$'\n' results=$( echo "SELECT key FROM server_machinegroup;" | python /home/docker/sal/manage.py dbshell | xargs | awk {'for (i=3; i<NF-1; i++) print $i'} ) read -rd '' -a lines <<<"$results" IFS=$oldIFS for line in "${lines[@]}" do if [[ -z $1 ]]; then /usr/local/salprofilegenerator/generate_sal_profile.py $line --output $profile_path else /usr/local/salprofilegenerator/generate_sal_profile.py $line --url $1 --output $profile_path fi done
It’s ugly Bash, I won’t deny. The README documents the usage of this script in detail.
The assumption is that this will be used within the Sal Docker container, and thus we can make use of environment variables. With that assumption, I’m also expecting that an environment variable PROFILE_PATH
gets passed in that can be used as the location to place our profiles. Absent the environmental variable, I chose /home/docker/profiles
as the default path.
IFS=$'\n'
The purpose of the IFS here is to help parse a long string based on newlines.
The actual pulling of the machine group keys is the complex part. I’m going to break down that one liner a bit:
echo "SELECT key FROM server_machinegroup;"
This is the SQL command that will give us the list of machine group keys from the Postgres database.
python /home/docker/sal/manage.py dbshell
This invokes the Django manage.py script to open up a database shell, which allows us to execute database commands directly from the command line. Since dbshell opens up an interpreter, we’re going to pipe standard input to it by echoing the previous SQL query.
xargs
Without going into a huge amount of unnecessary detail about xargs, the purpose of this is simply to compress the output into a single line, rather than multiple lines, for easier parsing.
awk {'for (i=3; i<NF-1; i++) print $i'}
Pretty much any time I start using awk in Bash, you know something has gone horribly wrong with my plan and I should probably have just used Python instead. But I didn’t, so now we’re stuck here, and awk will hopefully get us out of this mess.
In a nutshell, this awk command prints all the words starting at 4 through the last-word-minus-two. Since dbshell queries produces output at the end saying how many rows were produced as a result, we need to skip both the number and the word “rows” at the very end. The parsing works out because we set the IFS to divide words up based on newlines.
Ultimately, this handles the odd formatting from dbshell and prints out just the part we want – the two Machine Group keys.
read -rd '' -a lines <<<"$results"
This takes the list of Machine Group keys produced by the long line and shoves it into a Bash array.
for line in "${lines[@]}"
The for loop iterates through the array. For each key found in the array, call the generate_sal_profile.py
script.
As the README documents, the shell script does handle a single shell argument, if you want to pass a different URL than the default. If a shell argument is found, that is used as a --url
argument to the generate_sal_profile.py
script.
By calling the script, we now get a .mobileconfig profile for each Machine Group key. Those profiles can be copied off the Sal host (or out of the Sal container) and into a distribution system, such as Profile Manager, an MDM, or Munki. Installing profiles on OS X is a trivial matter, using the profiles
command or simply double-clicking them and installing them via GUI.
Because I’m currently in a “dockerize ALL THE THINGS” phase right now, I went ahead and created a Docker image for Sal incorporating this profile generation script.
Conclusion
Munki is a very useful tool. Munki with Sal by itself is a useful tool, but the best tools are ones that can be extended. Munki, Sal, and Facter provide great information about devices. Making Sal easy to install lessens the burden of setting it up, and makes the entire process of migrating to a more managed environment simpler.
Recent Comments