Home - munki/munki GitHub Wiki

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 or jump to..." field in the GitHub navigation bar above. Then on the search results page select the "Wiki" option or click here and search.

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

NOTE: only the current/latest version of Munki is actively supported. This list is mostly for historical purposes. If you are running an old version of macOS not supported by the current version of Munki, use this list to find an older (but no-longer supported) version that will work with your OS.

The current version of Munki is 6.4.1, and can be downloaded at https://github.com/munki/munki/releases.

The primary developer tests (and uses) Munki on fairly recent releases of macOS. Little or no testing is done on releases older than N-2. The list below is not guaranteed to be 100% accurate, but is based on information available. If you find a new release of Munki does not work on an older macOS release and that fact isn't here: please let us know.

  • Munki 1.x and earlier supported Mac OS X 10.5–10.9.x.
  • Munki 2.x supported Mac OS X 10.6 – 10.11.x
  • Munki 2.3.1 or higher was recommended for use with OS X 10.11 and macOS 10.12.
  • Munki 3.0-3.5.x dropped support for Mac OS X 10.6 and 10.7, and was supported on OS X 10.8 - macOS 10.13.
  • Munki 3.6 dropped support for OS X 10.8 and 10.9, and was supported on macOS 10.10-10.14.
  • Munki 3.6.3 or later is recommended for macOS 10.15.
  • Munki 4 is supported on macOS 10.10-10.15.
  • Munki 5.0 and 5.1 is supported on macOS 10.10-10.15.
  • Munki 5.2 drops support for macOS 10.10, and is supported on macOS 10.11 - macOS 11.
  • Munki 5.2.2 or later is recommended for use on Apple silicon.
  • Munki 5.6 or later is recommended for use on macOS 12 (Monterey).
  • Munki 6.3 or later is recommended for use on macOS 13 (Ventura).
  • Munki 6.3 drops support for macOS 10.11 and 10.12, and is supported on macOS 10.13 - macOS 14.
  • Munki 6.3.2 or later is recommended for use on macOS 14 (Sonoma).

Requirements:

Python

Munki versions 1-3 require Python 2.5 or higher with Objective-C Python bindings, which is included by default in macOS. Starting with Munki 4, Munki includes its own Python interpreter with all required dependencies.

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 macOS 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 macOS and it needs the munkitools.mpkg installed. You can also use your Munki server for this (if the server is running macOS 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 macOS).

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/.

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://www.macadmins.org/

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