Home

Getting started with Munki

Overview

See here for a basic overview of what Munki does and does not do.

Searching the wiki

To search this wiki use the "Search" field in the GitHub navigation bar above. Then on the search results page select the "Wiki" option or click here.

Details

See Demonstration Setup for a walk-through of setting up a functional Munki client and server on a single machine; no separate web server needed. This is a quick and easy way to get started with Munki, and is a recommended starting point for people new to Munki.

Munki Versions

• Munki 1.x and earlier support Mac OS X 10.5–10.9.x.
• Munki 2.x supports Mac OS X 10.6 – 10.11.x
• Munki 2.3.1 or higher is recommended for use with OS X 10.11 and macOS 10.12.
• Munki 3.x supports OS X 10.8 and higher.

Requirements:

Python

Munki requires Python 2.5 or higher with Objective-C Python bindings, which is included by default in Mac OS X. Munki 1.x is supported on Leopard through Mavericks (10.5-10.9). Munki 2 drops support for Leopard, and supports Snow Leopard or higher (10.6+). Munki 3 drops support for Snow Leopard and Lion, and supports Mountain Lion or higher (10.8+).

To see how to report cases where Python dependencies are broken, see Report Broken Client.

Web server

A basic Munki server is simply a web server. You do not need the Munki tools installed on the server. You can set up a Munki server on any platform that supports a web server. You can use OS X client, OS X Server, Linux, Windows or even a NAS appliance as a Munki server. You are simply setting up a filesystem on a web server for clients to access.

A Mac to administer your Munki server

This machine will use the Munki admin tools to create pkginfo files, catalogs and manifests. This machine must be running Mac OS X and it needs the munkitools.mpkg installed. You can also use your Munki server for this (if the server is running Mac OS X or Mac OS X Server) but it's not required. Installing the munki tools prompts a reboot so maybe your server isn't the best choice depending what other services it hosts. Common choices for an admin machine: The Mac you do your day to day work on, a spare Mac, your Munki server (if it's running OS X).

If your Munki server is on an OS X Server and you do decide to also use it as an admin station, consider installing only the admin tools. Installing the full package will also cause the server to be an unconfigured Munki client, which could lead to unwanted consequences ranging from unexpected software installs to security exploits by bad actors.

User / Client Machines

These are your users machines that you want to install updates and packages on via Munki. munkitools.mpkg must be installed on all client machines. munkitools.mpkg contains 4 sub packages: app, core, launchd and admin. The admin package is not required for your clients, but it's much simpler to just install the whole package.

The easiest way to start is by downloading the current packaged release here: https://github.com/munki/munki/releases

The installer package installs the munki command-line tools in /usr/local/munki/, and the GUI Managed Software Center.app in /Applications/ (alongside an Managed Software Update.app alias in /Applications/Utilities/).

Then follow the walkthrough here: Demonstration Setup to setup a demo Munki server and client.

Key tools

Admin tools:

munkiimport: A tool that helps an admin import software installation packages into the Munki server. See munkiimport for more info on this tool.

makepkginfo: A lower level tool. Given an installer package, creates basic pkginfo (metadata) for it. The admin should edit this and add to this metadata - if it was all automatically discoverable, we wouldn't need the separate pkginfo metadata file in the first place! See makepkginfo for more.

makecatalogs: Builds Munki catalogs from pkginfo files generated by makepkginfo or munkiimport. See makecatalogs for more.

manifestutil: A tool for manipulating manifest files. See manifestutil for documentation.

Client tools:

managedsoftwareupdate - checks with the server and retrieves current manifest(s); walks though the manifest(s), downloads catalogs, retrieves detail on individual manifest items and then builds a list of items that need to be installed, and a list of items that need to be removed. More info here: managedsoftwareupdate

Calling managedsoftwareupdate --installonly - installs or removes items.

GUI application:

Managed Software Center.app: Located at /Applications/Managed Software Center.app

This app is used to notify the user that there are updates to be installed. It also provides visual progress feedback during installs, even over the loginwindow. Additionally, it serves as an App Store-like source for on-demand/optional software installs and removals.

Users can also run this app to trigger a check for available updates; if there are no available updates (in InstallInfo.plist) when it is launched, it will run a check and return the results.

Demonstration setup of Munki server and client

See Demonstration Setup for a walkthrough of setting up a demo Munki server and client.

Where to go for more info and help

If, after working through the Demonstration Setup -- and reading the other documentation here -- you are still perplexed and need some help, post a a question on the munki-discuss Google Group.

There is also a #munki channel on the MacAdmins Slack group. Join here: https://macadmins.herokuapp.com

If you are looking for professional support or a managed solution, start here: Professional Support