Munki Business - A Guide to Munki 2

A lot has changed since my original post on Munki 1, with Munki 2 well and truly out I have taken the opportunity to write an updated guide on Munki 2.

What is Munki?

Munki is a community driven project created by Greg Neagle, allowing IT Administrators to efficiently deploy software to large numbers of Macs.

A Munki implementation can be broken down into two core parts;
a) repository hosted on a web server
b) bunch of clients running the Munki software
 

A Munki Repository

Since a Munki repository is simply a collection of organised files served out by a web server it can be hosted on any web server (e.g. IIS, Apache, etc.) regardless of platform. In the situation where the repository is hosted on a remote server, Administrators can remotely edit the repository over a network share.

Every Munki repository is comprised of the following four directories:
pkgs: All package (.pkg) and disk image (.dmg, .iso) files.

pkgsinfo: For each piece of software in the pkgs directory there is an associated file in pkgsinfo. These files contain detailed information about that piece of software and the catalog(s) that software is assigned to. Conventionally these pkgsinfo files have the .plist extension.

catalogs: Catalog files are generated from the contents of pkginfo files, they are used to separate production (tested) from development (untested) versions of software.

manifests: Clients are configured to download a particular manifest file. These manifest files contain a list of software to install and the catalog (version) to use.

Note: Apart from the contents of pkgs every other directory contains standard Extensible Markup Language (XML) files.

With the release of Munki 2, there are three additional directories:
artwork: A place to store any images used within software descriptions.

client_resources: Home to the Managed Software Center application theme files.

icons: Contains images (.png) used as software icons in the Managed Software Center application. The recommended icon resolution is 300x300.

Setting Up a Repository

The steps for setting up a Munki repository vary depending on web server and platform. For OS X the standard procedure involves creating a ‘munki_repo’ directory in ‘/Users/Shared/‘, populating it with the directories listed above. Then creating a symbolic link from ‘/Users/Shared/munki_repo’ to ‘/Library/Server/Web/Data/Sites/Default/’ and enabling the OS X Server web server.

View fullsize

Managing Munki Repositories

Download and install the latest release of Munki Tools here.

Part of Munki Tools are the Munki Admin Tools for command-line management of Munki repositories. Unless you enjoy working purely in the command-line, I recommend downloading Hannes Juutilainen’s MunkiAdmin, a user-friendly application for managing Munki repositories. 

Install AutoPkg

AutoPkg automates the process of downloading and importing third party software updates straight into the Munki repository. Look at setting up AutoPkg by following my guide here.

Manually Importing New Software

If you wish to manually import a piece of software here are the steps:

Before we can use the Munki Admin Tools we need to complete the initial setup. To start the setup open Terminal and type:

munkiimport --configure

View fullsize

The 'Repo fileshare URL' can be left blank if the Munki repository is stored on the local disk, otherwise provide a network share path (e.g. smb://SERVERADDRESS/munki_repo).

I recommend following the guidelines below, to keep your Munki repository tidy:
First rename the software you wish to import:

• Match the name to the software (e.g. jre-7u67-macosx-x64.dmg > java.dmg).
• Only use lowercase letters (e.g. Firefox 32.0.3.dmg > firefox.dmg).
• Do not use dashes, underscores or spaces (e.g. Skype_6.19.0.452.dmg > skype.dmg).
• Delete version numbers (e.g. vlc-2.1.5.dmg > vlc.dmg).
• Omit the developer’s name (e.g. googlechrome.dmg > chrome.dmg).

Once renamed open Terminal and type ‘munkiimport ‘ (take note of the trailing space).
Drag the renamed package onto the Terminal window and hit return.
When prompted for an item name enter the name of the package without the extension (e.g. firefox.dmg > firefox).
The display name can contain spaces and capitals (e.g. Flash Player).
The description can be left blank for now, as it can be added in later with MunkiAdmin.
The version number is pulled from the software, verify it is accurate and hit return, otherwise type in the correct version number.
When prompted for a category, use the Mac App Store categories as a guide (e.g. Productivity, Utilities, etc).
Enter the developer’s name (e.g. Apple, Google, etc).
When prompted for Catalogs hit return.
You will be presented with a summary of your input, if you are happy that it is all correct type y and hit return.
Just hit return when asked for a subdirectory path.
Munki may offer to extract an icon, type y and hit return. 
You are given a chance to make any alterations to the newly generated pkginfo file, simply press control + X.
Lastly you are asked if you would like to rebuild catalogs, type y and hit return.

View fullsize

Assigning Software to Manifests

To put it simply manifests contain lists of software to install and the catalogs (software version) to use. Software can either be set as mandatory (managed_installs) or optional (optional_installs). Optional installs provide a self-service experience similar to the Mac App Store.

View fullsize

MunkiAdmin makes the process of assigning software to manifests simple, just add a new item under either the Installs tab (mandatory) or the Optional Installs tab.

View fullsize

As seen in the diagram below, every Mac installs a SOE (Standard Operating Environment) suite of software. Depending on the Mac’s location (e.g. Art, Music, etc.) and the intended user type (e.g. staff or student), additional software (e.g. Photoshop, Sibelius, etc.) is installed. Since Munki clients can only check a single manifest, I have dealt with this limitation by stacking manifests.

View fullsize

It may seem confusing at first, but once the manifest infrastructure is in place, assigning new software to all relevant clients is simple. The green bubbles are manifests that clients check and we normally avoid adding 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.) and software is assigned to these.

Configuring Munki Clients

Once Munki Tools is installed, clients need to be configured with the Munki repository's address and which manifest to check. Often these settings are configured using DeployStudio, a payload-free package or another means of script execution. This can be performed manually in Terminal with:

defaults write /Library/Preferences/ManagedInstalls.plist SoftwareRepoURL http://SERVERADDRESS/munki_repo
defaults write /Library/Preferences/ManagedInstalls.plist ClientIdentifier MANIFESTNAME

Testing Software

Before pushing out software to every Munki client it is important to thoroughly test that it works as expected. You should configure at least one test machine the same way as the rest of your client’s with the exception of pointing it to a testing manifest.

A testing manifest should include both the development and production catalogs, as well as a manifest directly accessed by clients.

Once that piece of software has been deemed stable, add it to the production catalog and watch as the rest of your clients install it.

Frequently Asked Questions

If you have read this far, you should be starting to get an understanding of how useful and feature rich Munki is. For readability I have chosen to tackle common queries I receive regarding Munki.

How does Munki know what is already installed?
Any applications installed by simply dragging and dropping them into Applications are detected by Munki. If a user deletes a drag and drop app from Applications Munki will notice its absence and reinstall it.

With package files, Munki indirectly checks for the existence of receipt files, therefore deleting the associated .plist and .bom files of a package in /var/db/receipts will cause Munki to reinstall that package.

Managed Software Center keeps attempting to install the same package over and over. What’s going wrong?
If MSC loops on a package, compare the receipts listed in the pkginfo file to the receipts present in the '/var/db/receipts/' directory. Once you figure out the missing receipt(s) mark them as optional (ignored).

You can also use Terminal’s ‘pkgutil’ command to search for installed receipts. In the example below I am searching for receipts containing the word xerox, the (?i) part ignores case and .* are wildcards.

View fullsize

Can we customise the banners in Managed Software Center?
Absolutely! You can even customise the sidebar and footer links. The official Munki wiki does a great job covering this in detail here.

How frequently does Munki check for updates?
After ten seconds of inactivity at the login window Munki will automatically install any locally cached updates.

By default a launch daemon is set to run ‘/usr/local/munki/supervisor’ ten minutes past every hour. The supervisor generates a random delay of up to sixty minutes to help stagger clients contacting the Munki repository. Once the delay is over supervisor triggers ‘/usr/local/munki/managedsoftwareupdate’, if there are new updates the logged in user is notified by Managed Software Center.

Note: Munki is also capable of installing software without any user intervention. This is achieved  by enabling 'Unattended install' in MunkiAdmin.

View fullsize

Will Managed Software Center work outside of the organisation?
As long as the web server hosting the Munki repository is externally accessible MSC will also work externally. If you plan on hosting a Munki repository on a public web server you should also configure SSL Client Certificates to ensure access to the repository is limited to permitted clients. 

How can I remotely trigger Munki clients to check for updates?
Using Apple Remote Desktop you can trigger groups of Macs to instantly check the Munki repository for updates and install.

Trigger Munki instantly regardless of whether a user is logged in:

/usr/local/munki/managedsoftwareupdate;/usr/local/munki/managedsoftwareupdate --installonly

Trigger Munki to run the moment the current user logs out or if nobody is currently logged in:

touch /Users/Shared/.com.googlecode.munki.checkandinstallatstartup

Tip: You can save those commands as Unix command templates in ARD.

View fullsize

How do I go about troubleshooting a Munki issue?
Since the Munki repository is just a bunch of files served out by a web server, almost all troubleshooting is performed from Munki clients.

On a client open Terminal and run:

sudo managedsoftwareupdate

This will immediately display any issues with the repository. You can also check the client log files stored in ‘/Library/Managed Installs/Logs/‘.

How do we update the version of Munki Tools running on clients?
AutoPkg makes it easy to keep your Munki clients up-to-date with frequently updated software (e.g. Flash Player, Java, etc.). You can quickly set up AutoPkg by following my guide here. There is a munkitools2.munki.recipe override included in my collection of recipe overrides. This will automatically import the latest release of Munki Tools into your Munki repository, as four separate packages:
munkitools_core.pkg: The required core command-line tools used by Munki.
munkitools_admin.pkg: The optional admin command-line tools for managing Munki repositories.
munkitools_app.pkg: The user-friendly Managed Software Center application.
munkitools_launchd.pkg: The launchd items to automate checking for updates.

View fullsize

The only package that should be assigned to a manifest is the munkitools_app, the rest are either marked as ‘required’ or ‘update for’ packages that would be installed regardless.

Meet Munki - Managed Mac Software Deployment

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.

View fullsize

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.

View fullsize

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.

View fullsize

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.

View fullsize

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.

View fullsize

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.

View fullsize

To update the ‘production’ catalogue with this change I run:

/usr/local/munki/makecatalogs

View fullsize

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

Turn Your Mac into a PHP Web Server In Under 10 Seconds

In almost no time at all this post will have your Mac up and running as an Apache 2 web server with PHP support. It's great for those that want to set-up a local web development environment to code that quick web app idea.

I have tested the following steps on Mac OS X Lion (10.7), OS X Mountain Lion (10.8) and OS X Mavericks (10.9).

Step 1: Enable PHP in the Apache configuration file

Open Terminal (/Applications/Utilities/Terminal) and type: 

sudo nano /etc/apache2/httpd.conf

Hit return and type your password. Don’t worry if it looks like you are not typing anything, it's just Terminal hiding your password input for added security.

To search the document press control + w, type 'php' and hit return.

You'll need to uncomment (remove the leading #) the php5_module.

To save changes press control + x, type y and hit return.

Step 2: Start up Apache

Type: 

sudo apachectl restart

Step 3: Test it out

Open Safari and type 'localhost' into the address bar. You should see:

This is the default web page that comes with Apache.

Open Finder and click 'Go' → 'Go to Folder…'

Type “/Library/WebServer/Documents/“ and click 'Go.'

Tip: You can press ‘tab’ to autocomplete folder names.

 /Library/WebServer/Documents/

This index.html file is the “This works!” web page you saw in the last step. Go ahead and edit index.html in your favourite text editor. I like to use Coda 2 (bit pricey) for my web development projects, but you could use any text editor. Before Coda 2 I was using Smultron and Notepad++, which are much cheaper. Once you have made a change refresh the page in Safari to see your changes.

[SOLVED] "This copy of the Install OS X Mavericks application can't be verified. It may have been corrupted or tampered with during downloading."

2018 UPDATE: This issue also occurs when attempting to install macOS High Sierra, with a slightly different error message: “This copy of the Install macOS High Sierra application is damaged, and can’t be used to install macOS.”

While trying to do a clean install of Mavericks onto a MacBook Air I received the error: "This copy of the install OS X Mavericks application can't be verified. It may have been corrupted or tampered with during downloading."

View fullsize

I found the error wasn't due to a corrupted Mavericks installer, but an incorrect date setting, caused by a flat battery. Since I had already blown away the previous Mac OS X install I needed to fix the time while booted from the Mavericks installer.

If you're experiencing this issue, here's what to do:

Boot into the Mavericks Installer. You can learn how to make bootable Mavericks USB here.

Open Terminal (Utilities → Terminal)

Check what the date is currently set to by typing "date". If it's incorrect type:

	date mmddHHMMYYYY

	
	Substitute

	mm = current month (e.g. February = 02)

	dd = current date (e.g 31)

	HH = current hour (e.g. 6pm = 18)

	MM = current minute (e.g. 05)

	YYYY = current year (e.g. 2013)
	

Hit return and quit Terminal. Now attempt the Mavericks install again, if it fails again it's not a date issue and I would try downloading and recreating your Mavericks installer.

Creating a Bootable OS X/macOS USB Installer

Since the release of Mac OS X 10.6 (Snow Leopard) I've carried around a bootable USB on my keychain. It has made my life a lot easier reinstalling OS X/macOS without an Internet connection and troubleshooting Macs without a recovery partition. I also much prefer clean installs of the operating system, using this method vs updating from a previous version of OS X/macOS.

This post will go through the process I use to create a bootable OS X/macOS installer.

Requirements

• At least an 8GB USB, you can also use a FireWire or Thunderbolt drive.

• A Mac running 10.6.8 (Snow Leopard) or newer.

• A fast Internet connection to download the OS X/macOS installer.

Step 1: Download OS X/macOS

If you haven’t already you can download the desired Install macOS application from the Mac App Store. Here are some direct links:

• macOS Catalina (10.15)

• macOS Big Sur (11)

• macOS Monterey (12)

Once it's downloaded the installer automatically opens, simply quit it.

Step 2: Prepare the USB

We are about to erase everything on the USB, make sure you have copied off anything you wish to keep. 

Open Disk Utility (/Applications/Utilities/Disk Utility), select your USB drive from the list and click the ‘Erase’ tab.

Set format to: Mac OS Extended (Journaled)

Set name to either: Mavericks, Yosemite, El Capitan, Sierra, High Sierra, Mojave, Catalina, Big Sur, Monterey

Click ‘Erase...’ and 'Erase' again, then enter your password if required. 

Step 3: Copy over the files

Open Terminal  (/Applications/Utilities/Terminal) and paste the appropriate command.

For Mavericks (10.9):

sudo /Applications/Install\ OS\ X\ Mavericks.app/Contents/Resources/createinstallmedia --volume /Volumes/Mavericks --applicationpath /Applications/Install\ OS\ X\ Mavericks.app --nointeraction

For Yosemite (10.10):

sudo /Applications/Install\ OS\ X\ Yosemite.app/Contents/Resources/createinstallmedia --volume /Volumes/Yosemite --applicationpath /Applications/Install\ OS\ X\ Yosemite.app --nointeraction

For El Capitan (10.11):

sudo /Applications/Install\ OS\ X\ El\ Capitan.app/Contents/Resources/createinstallmedia --volume /Volumes/El\ Capitan --applicationpath /Applications/Install\ OS\ X\ El\ Capitan.app --nointeraction

For Sierra (10.12):

sudo /Applications/Install\ macOS\ Sierra.app/Contents/Resources/createinstallmedia --volume /Volumes/Sierra --applicationpath /Applications/Install\ macOS\ Sierra.app --nointeraction

For High Sierra (10.13):

sudo /Applications/Install\ macOS\ High\ Sierra.app/Contents/Resources/createinstallmedia --volume /Volumes/High\ Sierra --applicationpath /Applications/Install\ macOS\ High\ Sierra.app --nointeraction

 For Mojave (10.14):

sudo /Applications/Install\ macOS\ Mojave.app/Contents/Resources/createinstallmedia --volume /Volumes/Mojave --applicationpath /Applications/Install\ macOS\ Mojave.app --nointeraction --downloadassets

For Catalina (10.15):

sudo /Applications/Install\ macOS\ Catalina.app/Contents/Resources/createinstallmedia --volume /Volumes/Catalina --nointeraction --downloadassets

For Big Sur (11):

sudo /Applications/Install\ macOS\ Big\ Sur.app/Contents/Resources/createinstallmedia --volume /Volumes/Big\ Sur --nointeraction --downloadassets

For Monterey (12):

sudo /Applications/Install\ macOS\ Monterey.app/Contents/Resources/createinstallmedia --volume /Volumes/Monterey --nointeraction --downloadassets

Hit return, type in your password, then hit return again. Don’t worry if it looks like you are not typing anything, it's just Terminal hiding your password input for added security. Depending on your USB, the copy process takes approximately 20 minutes to finish.

That's it! You should now have a bootable OS X USB installer. Go test it out by plugging it into a Mac that is turned off, pressing the power button and then holding down the 'option' key.

I’d like to thank tywebb13  for sharing the above Terminal command on the MacRumors forums.

If you need any help feel free to leave a comment.