Volume Number: 26
Issue Number: 12
Column Tag: MacEnterprise

MacEnterprise: Managing Software Installs with Munki-Part 3

Using munki for installs, updates, removals and more

By Greg Neagle, MacEnterprise.org

In the October 2010 issue, we started looking at munki, a set of open-source tools that can manage software installation and removal on Mac OS X machines. Munki can install software packaged in Apple's Installer package format, software delivered for "drag-and-drop" installs on disk images, and Adobe CS3, CS4 and CS5 products and updates using Adobe's supported enterprise deployment tools.

Last month, we set up a demonstration munki server on a Mac OS X "client" machine, using Apple's included Apache2 web server. We'll need a munki server to continue our exploration of the munki tools. If you haven't set up a munki server, and you don't have access to last month's column, here's a very quick recap.

First, we'll create the web server directories, and make sure the web server is running. From a command prompt:

cd /Users/Shared/
mkdir munki_repo
mkdir munki_repo/catalogs
mkdir munki_repo/manifests
mkdir munki_repo/pkgs
mkdir munki_repo/pkgsinfo
chmod -R a+rX munki_repo
cd /Library/WebServer/Documents/
sudo ln -s /Users/Shared/munki_repo .
sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist

(Note that the last command starting with "sudo launchctl" is all one line with no line breaks).

We created a set of directories, created a symlink in Apple's Apache web documents root, and made sure Apache2 was running. You can check your work in a web browser by visiting http://localhost/munki_repo - you should see a listing of the four directories you created inside /Users/Shared/munki_repo.

Next, download the most recent munki tools from http://code.google.com/p/munki. Make sure you are downloading a 0.7.0 release or later. Install the tools like you would any other Apple installer package. A restart will be needed.

Configure the munki import tool:

% /usr/local/munki/munkiimport -configure
Path to munki repo [None]: /Users/Shared/munki_repo
Repo fileshare [None]: 
pkginfo extension [None]:
pkginfo editor [None]: TextEdit.app

Here we set the path to the munki repo to the directory we created above, and set our pkginfo editor to TextEdit.app. (If you have a different preferred text editor, feel free to substitute it.)

Let's import a package. Download the current release of Google Chrome, and import it:

% /usr/local/munki/munkiimport ~/Downloads/googlechrome.dmg
      Item name [Chrome]: GoogleChrome
   Display name []: Google Chrome
    Description []: Fast web browser from Google
        Version [7.0.517.41.0]: 
       Catalogs [testing]: 
      Item name: GoogleChrome
   Display name: Google Chrome
    Description: Fast web browser from Google
        Version: 7.0.517.41.0
       Catalogs: testing
Import this item? [y/n] y
Upload item to subdirectory path []: apps
Path /Users/Shared/munki_repo/pkgs/apps doesn't exist. Create it? [y/n] y
Copying googlechrome.dmg to /Users/Shared/munki_repo/pkgs/apps/googlechrome.dmg...
Saving pkginfo to /Users/Shared/munki_repo/pkgsinfo/apps/GoogleChrome-7.0.517.41.0...
Rebuild catalogs? [y/n] y
Adding apps/GoogleChrome-7.0.517.41.0 to testing...

After munkimport uploads the package and pkginfo to the server directories, the pkginfo will be opened in the text editor you specified earlier. For now, just close the pkginfo and process with rebuilding the catalogs. We can test our work so far by visiting http://localhost/munki_repo/catalogs/testing - we should see a plist with information about Google Chrome (and any other packages you might have imported).

So far, we have a munki server with a single package and a single catalog. We need at least one more item to have a functional munki server - a manifest. Manifests tell munki which packages should be installed on a given machine. For our demonstration manifest, create a text file with these contents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>catalogs</key>
  <array>
    <string>testing</string>
  </array>
  <key>managed_installs</key>
  <array>
    <string>GoogleChrome</string>
  </array>
  <key>managed_uninstalls</key>
  <array>
  </array>
</dict>
</plist>

Save the file as /Users/Shared/munki_repo/-manifests/test_munki_client. Be sure your editor doesn't add a file extension to the filename. Again, check your work in your web browser by navigating to http://localhost/munki_repo/manifests/test_munki_client. You should see the file you just created displayed in your web browser.

We'll use the defaults command to configure the client to talk to our local demonstration munki server (each command is a single line):

sudo defaults write /Library/Preferences/ManagedInstalls SoftwareRepoURL "http://localhost/munki_repo"
sudo defaults write /Library/Preferences/ManagedInstalls ClientIdentifier "test_munki_client"

Check your work by reading the file with defaults:

# defaults read /Library/Preferences/ManagedInstalls
{
    ClientIdentifier = "test_munki_client";
    SoftwareRepoURL = "http://localhost/munki_repo";
}

That completes our quick recap of configuring a server and client; for more detail and information, consult the November 2010 MacTech, or look over the documentation on http://code.google.com/p/munki.

Last month, we installed Firefox using munki. This month, before we look at other munki features, we'll review by installing Google Chrome.

% sudo /usr/local/munki/managedsoftwareupdate
Managed Software Update Tool
Copyright 2010 The Munki Project
http://code.google.com/p/munki
Downloading googlechrome.dmg...
   0..20..40..60..80..100
Verifying package integrity...
The following items will be installed or upgraded:
    + GoogleChrome-7.0.517.41.0
        Fast web browser from Google
Run managedsoftwareupdate -installonly to install the downloaded updates.

If, instead, managedsoftwareupdate tells you there are no changes to be made, it's likely you already have that version (or later) of Google Chrome installed; delete it manually and run managedsoftwareupdate again.

Note that when run manually, managedsoftwar-eupdate only downloads the updates, but does not automatically install them. You must run it again with the -installonly flag to actually install the downloaded updates:

% sudo /usr/local/munki/managedsoftwareupdate -installonly
Managed Software Update Tool
Copyright 2010 The Munki Project
http://code.google.com/p/munki
Installing Google Chrome (1 of 1)...
Mounting disk image googlechrome.dmg...
Copying Google Chrome.app to /Applications...
The software was successfully installed.

You can delete Google Chrome from the /Applications folder, and if you run managedsoftwareupdate again, munki will download the installer for Google Chrome again. As long as <string>GoogleChrome</string> remains in the managed_installs list in the manifest, munki will ensure it is installed.

After our review, we are finally ready to forge ahead. You've used munki to install Google Chrome. But Google updates its browser frequently, and you'd like munki to keep Google Chrome up to date. Fortunately, this is very easy. Just download the newer version from Google, and use munkiimport to add it to the munki repo:

% /usr/local/munki/munkiimport ~/Downloads/googlechrome.dmg
      Item name [Chrome]: GoogleChrome
   Display name []: Google Chrome
    Description []: Fast web browser from Google
        Version [7.0.517.44.0]: 
       Catalogs [testing]: 
      Item name: GoogleChrome
   Display name: Google Chrome
    Description: Fast web browser from Google
        Version: 7.0.517.44.0
       Catalogs: testing
Import this item? [y/n] y
Upload item to subdirectory path []: apps
Copying googlechrome.dmg to /Users/Shared/munki_repo/pkgs/apps/googlechrome-7.0.517.44.0.dmg...
Saving pkginfo to /Users/Shared/munki_repo/pkgsinfo/apps/GoogleChrome-7.0.517.44.0...
Rebuild catalogs? [y/n] y
Adding apps/GoogleChrome-7.0.517.44.0 to testing...

That's all you need to do. As long as the "Item name" for the new version matches the previous version (in this case, "GoogleChrome"), munki will automatically notice the newer version:

% sudo /usr/local/munki/managedsoftwareupdate
Managed Software Update Tool
Copyright 2010 The Munki Project
http://code.google.com/p/munki
Downloading googlechrome.dmg...
   0..20..40..60..80..100
Verifying package integrity...
The following items will be installed or upgraded:
    + GoogleChrome-7.0.517.44.0
        Fast web browser from Google
Run managedsoftwareupdate -installonly to install the downloaded updates.

Munki can also remove managed software. To demonstrate, we'll edit the test_munki_client manifest. First, make certain Google Chrome is installed. In your favorite text editor, open /Users/Shared/munki_repo/manifests/test_munki_client. Move the line <string>GoogleChrome</string> from the managed_installs section to the managed_uninstalls section. It should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>catalogs</key>
  <array>
    <string>testing</string>
  </array>
  <key>managed_installs</key>
  <array>
  </array>
  <key>managed_uninstalls</key>
  <array>
    <string>GoogleChrome</string>
  </array>
</dict>
</plist>

Save the file and run managedsoftwareupdate:

% sudo /usr/local/munki/managedsoftwareupdate
Managed Software Update Tool
Copyright 2010 The Munki Project
http://code.google.com/p/munki
The following items will be removed:
    - GoogleChrome
Run managedsoftwareupdate -installonly to install the downloaded updates.

You could then run managedsoftwareupdate with the -installonly flag to have it actually perform the removal. If instead of using the command line, you launched /Applications/Utilities/Managed Software Update.app, you should see something like Figure 1.

Figure 1 - Managed Software Update software removal

Notice that Managed Software Update doesn't display the details of what will be removed. This is the default behavior, but the administrator can override this and cause the details to be displayed if that is better for your organization. So that we may continue with the next demonstration, click Update now and allow munki to remove Google Chrome.

Munki also supports "optional installs." This is similar in concept to the "self-service" installs offered by some of the commercial software deployment products. To demonstrate this feature, once again we'll edit the test_munki_client manifest. Once again, open /Users/Shared/munki_repo/manifests/test_munki_client in your favorite text editor. This time, rename the managed_uninstalls section to optional_installs and save. It should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>catalogs</key>
  <array>
    <string>testing</string>
  </array>
  <key>managed_installs</key>
  <array>
  </array>
  <key>optional_installs</key>
  <array>
    <string>GoogleChrome</string>
  </array>
</dict>
</plist>

Since "optional installs" require the user to decide to install them, they aren't available from the command line. Launch Managed Software Update.app from /Applications/Utilities. After a few seconds, you should see a notification like the one in Figure 2. Along with an alert saying your software is up to date, there is a new Optional software... button.

Figure 2 - Optional software

Clicking the Optional software... button changes the Managed Software Update window to resemble Figure 3.

Figure 3 - Available optional installs

If you check the box next to Google Chrome and click Add or Remove, after a few seconds, Google Chrome is ready to install, as in Figure 4. Click Update now and let munki install Google Chrome once again.

Figure 4 - Optional install of Google Chrome ready to install

If you'd like, run Managed Software Update yet again, and use the Optional software controls to uninstall Google Chrome. You can see that this feature allows an administrator to make software available to end-users and allows these users to install and remove the software themselves. Even better, once a user chooses to install software from the optional installs list, if you add an updated version to the munki repository, the user will be notified of the updated version automatically.

So far we've spent most of our time demonstrating the use of munki from the administrator's point of view, occasionally running the client tools from the command line or the GUI to check our work or demonstrate the feature. All of this manual effort might give you a mistaken impression about what the end-user sees or must do to use munki. Let's take a short detour and describe what the end-user sees.

By default, when installed and configured, the managedsoftwareupdate process runs in the background once an hour. It looks for changes on the server, downloading new or changed manifests and catalogs. It then uses the manifests and catalogs to determine what is supposed to be installed or removed from the user's machine. If anything needs to be installed, it is downloaded in the background. All of this is done in the background without involving the user. If there are any changes that need to be made, what munki does next depends on whether or not there is a user logged in.

If there is no user logged in, munki proceeds to install or remove the required software without asking. It displays a status window over the loginwindow, effectively preventing users from logging in until the updates are complete. If any of the updates require a restart, munki will restart the machine at the end of its session.

If there is a user logged in, munki will launch Managed Software Update to notify the user of available updates. (Munki won't notify the user of the same updates more than once a day, however.) The user is then in control - he or she can elect to perform the updates right away, or defer them until later.

If the user chooses to perform the updates, there are a couple of possibilities. If any of the updates require a logout or restart, the only choice available will be to logout and update. If none of the updates require a logout or restart, the user is also given the option to update without logging out. If you've been following along with the demonstrations so far, you've probably seen this behavior.

Some of this behavior is configurable by the administrator. For example, if you do not want munki to install automatically when the machine is at the loginwindow, you can set SuppressAutoInstalls to true:

sudo defaults write /Library/Preferences/ManagedInstalls SuppressAutoInstalls -bool TRUE

On the other hand, if you are managing a lab of machines and you'd like munki only to install at the loginwindow, and never notify logged-in users of updates, you could set the ManagedInstalls preference SuppressUserNotification to true. (If you set both SuppressAutoInstalls and SuppressUserNotification to true, munki will only install things when manually invoked - it won't install at the loginwindow, and will never notify users of available updates).

You can also disable the option allowing users to update without logging out by setting the ManagedInstalls preference InstallRequiresLogout to true. When this preference is true, users must logout to perform any updates.

The end-user experience with munki is similar to that with Apple Software Update, and the Managed Software Update application resembles Apple Software Update to reinforce the similarities. So it's natural to wonder if munki can help you deploy Apple Software Updates as well as third-party software. The answer is yes.

There are two ways to distribute Apple updates using munki. The first is to treat an Apple update just like any other software package. An update for iPhoto could be downloaded from Apple's website, imported into munki, and installed like any other software. This approach can work well for Apple software that may be not installed on every machine - the iLife and iWork suites; the Xcode tools; and Apple's professional applications like Final Cut Studio and Logic Studio. This is a recommended option if you need the ability to later remove any of these applications using munki. By importing the updates into the munki repository, you ensure munki has the information needed to remove the updated applications later.

But for Apple updates like OS updates, Safari and iTunes updates, Security updates, Java updates and the like, managing these by downloading them and importing them into munki might be a lot of work, as you need to duplicate Apple's logic in which updates must happen in which order, and which apply to which machines. Further, none of these updates are removable in a useful sense, so there's no particular benefit to importing them into your munki repository.

So the second way to use munki with Apple updates is to let munki run Apple Software Update for you. Again, this is controlled by preferences stored in /Library/Preferences/ManagedInstalls.plist.

sudo defaults write /Library/Preferences/ManagedInstalls InstallAppleSoftwareUpdates -bool TRUE

Setting this preference to true causes munki to download all available updates from the Apple Software Update server if there are no outstanding updates from the munki server. Munki will contact Apple's Software Update server, or you can define your own update server via MCX, by setting the appropriate preferences in /Library/Preferences/com.apple.SoftwareUpdate.plist, or by adding the CatalogURL to the ManagedInstalls.plist:

sudo defaults write /Library/Preferences/ManagedInstalls SoftwareUpdateServerURL <CatalogURL>

If there are no available updates from the munki server, munki will check with the Apple Software Update server and download all available updates. If no one is logged in, munki will automatically install the updates; otherwise, it will display the Apple updates in a manner similar to those munki itself manages. See Figure 5 for an example.

Figure 5 - Apple Software Updates via munki

Configured this way, munki allows users without administrative privileges to install Apple software updates. By using your own internal Apple Software Update server, you can approve new updates only after a period of testing. In fact, you can use the munki tools without a munki server to only install Apple software updates:

sudo defaults write /Library/Preferences/ManagedInstalls AppleSoftwareUpdatesOnly -bool TRUE

In this configuration, munki never checks a munki repository - it only checks Apple Software Update for updates.

This month we reviewed the setup and configuration of a munki server and client - the server is running locally on a client machine, so it's not suitable for actual production use, but is useful for testing and getting a feel for the munki tools.

We then demonstrated importing a software package and then installing, updating, and removing software from this package. We created a manifest file for your test client to demonstrate these tasks. A manifest is the file that tells munki what software should be installed or removed on a given client machine.

Finally, we looked at some other munki features: optional installs, and support for Apple Software Updates. Optional installs allow end-users to choose to install or remove software on their own. Support for Apple Software Updates lets you leverage Apple's mechanism for delivering updates to Apple software, and munki allows users without administrative rights to install these updates.

Next time, we'll dig a little deeper into the most complex part of munki: Package information files, or pkginfo files. These are the files that provide munki with metadata about installation packages and provide munki with information it can use to decide whether a package needs to be installed or removed, and if additional items are needed to complete the installation. Properly crafted pkginfo files can allow you to add "PhotoshopCS5" to the managed_installs of a client's manifest and have munki discover all of the updates and additions and install those as well, without having to explicitly add the updates and add-ons to a manifest.

If you've decided that you are done exploring munki, or you intend to explore more, but don't want to leave the munki tools and munki server in place until next month's installment, here's what you need to remove. Watch the line breaks.

Removing the client tools:

sudo launchctl unload /Library/LaunchDaemons/com.googlecode.munki.*
sudo rm -rf "/Applications/Utilities/Managed Software Update.app"
sudo rm -f /Library/LaunchDaemons/com.googlecode.munki.*
sudo rm -f /Library/LaunchAgents/com.googlecode.munki.*
sudo rm -rf "/Library/Managed Installs"
sudo rm -rf /usr/local/munki
sudo pkgutil -forget com.googlecode.munki

Removing the server:

sudo rm /Library/WebServer/Documents/munki_repo
rm -r /Users/Shared/munki_repo

If you aren't using Web Sharing for anything else, remember to turn it off using the Sharing preferences pane.

Greg Neagle is a member of the steering committee of the Mac OS X Enterprise Project (macenterprise.org) and is a senior systems engineer at a large animation studio. Greg has been working with the Mac since 1984, and with OS X since its release. He can be reached at gregneagle@mac.com.