Recently I have come across a number of Mac schools and businesses running Munki, an open source software distribution tool. I have only studied it for a couple weeks but I can already see why so many Mac sites are using it. This post covers the concept of Munki, my best practices and a list of common commands.
The Concept
To put it simply, a Munki server maintains a repository of Mac software. Users running the Munki client application (a.k.a. Managed Software Update) are notified of new software and are then prompted to install it.
Munki can deploy newer versions of currently installed applications (e.g. Google Chrome), Apple software updates (e.g. OS X 10.9.3 Combo) or even custom in-house packages (e.g. ConfigurePrinters.pkg). Munki can also detect if an application has been deleted and will reinstall it.
The Structure
A Munki repository is hosted on an internal web server and consists of four directories:
pkgs: This contains all available software, generally as dmg, iso or pkg files.
pkgsinfo: This contains a plist file for each software in the pkgs folder. It’s common to edit these plist files to add software to different catalogues, set software dependencies or edit the minimum OS requirements. The Munki server reads all the plists in pkgsinfo and compiles catalogues from the data. Clients do not access this directory.
catalogs: This is another directory of plists. My Munki server has two catalogues: ‘development’ and ‘production.’ Catalogues are useful for sandboxing new versions of software until they are deemed ready for widespread deployment. Munki automatically generates a catalogue named ‘all’. This catalogue should not be included in any manifest.
manifests: This directory contains more plist files, controlling which software is deployed to which clients as each client is set to download a specific manifest (e.g testing, staff_laptop, etc.). A manifest plist lists software (without versions) to install and/or remove. You can also add the optional_items key in a manifest plist and specify a list of optional software choices. This provides a self-service interface, allowing users to choose from the list of optional software.
My Best Practices
Naming Conventions
To make maintaining the Munki repository more intuitive, I have taken a different approach to naming my catalogues and manifests that differs from norm found on the Munki wiki. I have chosen not to have a ‘testing’ catalogue, only ‘development’ and ‘production’ catalogues. I do however have a manifest called ‘testing’ that accesses the ‘development’ catalogue.
Munki imports new .dmg files with the same filename. To keep the repository tidy, I recommend renaming files before importing. The filename should be in lowercase with no spaces, followed by a dash and the softwares version number (e.g. googlechrome-2.1.4.dmg).
Granular Software Control
In my previous workplace, every Mac ran a SOE (Standard Operating Environment) suite of software. Depending on the location (e.g. Art, Music, etc.) and user type (e.g. staff or student), specific extra software (e.g. Photoshop, Sibelius, etc.) was installed. On top of that there were faculty that required access to software normally only provided to Art or Music computer labs. Since Munki clients can only check a single manifest, I dealt with this limitation by creating a structure of manifests included in other manifests.
It seems confusing at first, but once the infrastructure is set up, assigning new software to all relevant clients is simple. The green bubbles are manifests that clients check, we normally do not add any software directly to these. Yellow are purely for merging manifests, again nothing should be added to these. Blue are core attributes (e.g. laptop, staff, science, etc) software is assigned to these.
For example; Skype is an application only installed on boarding house student machines. To add Skype to the boarders manifest I run:
/usr/local/munki/manifestutil add-pkg Skype --manifest boarder
The boarder’s MacBooks are configured to check the ‘student_laptop_boarder’ manifest and therefore are notified of any changes made to ‘soe,’ ‘student,’ ‘laptop’ and ‘boarder’ manifests.
Since Skype was added to the ‘boarder’ manifest, Managed Software Update lists Skype as well as VLC media player from the ‘soe’ manifest as available software.
Please note: Manifests directly accessed by clients require a catalogue (e.g. ‘production’) to be specified, however, included manifests that are not directly accessed by clients do not require a catalogue to be set.
Updating Software
In this example I have two versions of Skype, 6.15 and 6.17 in my repository. Version 6.15 has already been tested and added to the ‘production’ catalogue, however, the newer version 6.17 still needs to be tested and was added to the ‘development’ catalogue on import. After thoroughly testing Skype version 6.17, I would simply edit the associated Skype-6.17.plist file in pkgsinfo, replacing 'development' with ‘production’ in the 'catalogs' section.
To update the ‘production’ catalogue with this change I run:
/usr/local/munki/makecatalogs
The new version of Skype is now part of the ‘production’ catalogue and made available to clients.
Common Commands
Server Commands
Display Munki server configuration:
defaults read ~/Library/Preferences/com.googlecode.munki.munkiimport
Import a new application or package:
sudo /usr/local/munki/munkiimport /PATH/TO/SOFTWARE
Rebuild catalogues from pkgsinfo data:
/usr/local/munki/makecatalogs
Enter manifest utility interactive mode:
/usr/local/munki/manifestutil
Common manifest utility interactive mode commands:
list-manifests new-manifest MANIFESTNAME display-manifest MANIFESTNAME list-catalogs list-catalog-items CATALOGNAME add-catalog CATALOGNAME --manifest MANIFESTNAME add-pkg CATALOGITEM --manifest MANIFESTNAME
Client Commands
Set Munki software repo URL:
sudo defaults write /Library/Preferences/ManagedInstalls SoftwareRepoURL "http://swupate.local/munki_repo"
Set ClientIdentifier (manifest):
sudo defaults write /Library/Preferences/ManagedInstalls ClientIdentifier "student_laptop_boarder"
View client configuration:
defaults read /Library/Preferences/ManagedInstalls
Check for available updates from Terminal:
sudo /usr/local/munki/managedsoftwareupdate
After checking for updates, install any discovered updates:
sudo /usr/local/munki/managedsoftwareupdate —-installonly
Download and install Apple software updates (does not require admin rights):
sudo defaults write /Library/Preferences/ManagedInstalls InstallAppleSoftwareUpdates -bool true
Show the user which software will be removed (managed uninstalls):
sudo defaults write /Library/Preferences/ManagedInstalls ShowRemovalDetail -bool true
Disable Munki installing software at the login window (useful for laptop users):
sudo defaults write /Library/Preferences/ManagedInstalls SuppressAutoInstall -bool true
Disable Munki installing software while user is logged in (useful for computer labs):
sudo defaults write /Library/Preferences/ManagedInstalls SuppressUserNotification -bool true