Explaining Munki – The Rest of the Owl

Introduction

There are plenty of great blog posts and walkthroughs for setting up munki, the indispensable tool for admins looking to deploy and update applications on macOS. My personal favorite guide is from Clayton Burlison (though by now it may be a little out-of-date). The munki GitHub repo wiki is another great starting point. I plan to eventually write up my own guide for setting up and securing munki, but this isn’t that.

Instead, this is what I hope is a very clear explanation of how the different parts of a munki set-up work together. Many people, myself included, seem to have problems wrapping their heads around munki, understanding how it works, and how the different pieces fit together. In my experience, once that understanding “clicks,” the rest falls into place. Ideally, this is the post I wish I’d read before starting to work with munki for the first time.

Components

Munki has two basic components: the client tools and the server. Many beginners (myself among them) initially seem confused by the division of labor between these two components, or even that they are separate at all. There is a tendency to think of munki as a web app that does something, such as read and write to a database or perform some sort of computation or logic. But the all of the actual logic and management are handled by the munki tools, running on client Macs, while the server simply serves files at particular URLs.

The Munki tools

The munki tools are a collection of resources packaged together and installed onto client machines. They include a number of command-line tools, several LaunchDaemons and LaunchAgents, and the Managed Software Center app. These are bundled together into a macOS pkg, which can be downloaded from the munki GitHub releases page and installed on macOS clients.

Command Line Tools

The command line tools are a collection of Python scripts for managing the munki repository and for client machines to interact with the server. The primary tool is managedsoftwareupdate, which is the program actually responsible for downloading and installing the apps, packages, and profiles from the server. This is the core of munki’s functionality. There are also several other tools used for managing and administering the munki repository, including munkiimport, makepkginfo, makecatalogs, and manifestutil.

LaunchDaemons & LaunchAgents

Munki also includes a number of launchd daemons and agents that run in the background to check for and download updates without user interaction. These allow munki to run behind the scenes, checking in with the server to download and install apps and updates automatically.

Managed Software Center.app

Managed Software Center is a GUI app that allows end-users on client machines to easily interact with munki and take advantage of self-service options without needing to use the command line. This allows users to install apps and run scripts on-demand. In most cases, this is users’ only exposure to munki, and can be customized for your organization.

The Munki Server

The munki “server” is one of the concepts than newcomers to munki often have difficulty understanding. Many seem to expect the server to be doing something; people will sometimes ask how to install munki and get it running on the server. On the contrary, the munki server is a “dumb” server: it is nothing more than a basic web server that delivers static files over http(s). The files on the server—whether apps, packages, pkginfo files, catalogs, icons, or whatever else—are arranged in a hierarchy and then served over the web to clients who request items at specific locations. Other than organizing files in a particular directory structure, there is no server-side logic, and no application running besides Nginx or Apache (or whatever your preferred web server may be).

The Munki Repository

The munki repository (or “repo”) refers to the hierarchy of files offered for download on the server. Generally, this consists of several top-level directories, under which everything else is organized: catalogs, client_resources, icons, manifests, pkgs, and pkgsinfo.

The catalogs, manifests, and pkginfo directories contain the different type of files generated and manipulated using the munki tools. Catalogs and manifests are usually in a flat (i.e., single) directory, whereas pkginfo files tend to be organized into a hierarchy identical to the one in the pkgs directory. The information in the catalogs are generated from pkginfo files using the makecatalogs tool.
The pkgs directory contains a hierarchy of pkgs, as well as DMGs, apps, configuration profiles and any other resources to be downloaded.
The icons directory consists of all the icons shown in Managed Software Center for the items in the pkgs directory, while client_resources contains resources used to customize the Managed Software Center appearance.

How it Works

All of the “logic” of munki takes place on the client machines. When a client kicks of a managedsoftwareupdate run (either manually or prompted by launchd) it goes looking for a manifest file at specific URL set in the preferences. For example, when a client or a manifest such as example_manifest, it goes to the URL http://munki.com/repo/manifests/example_manifest and downloads the file it finds there. That manifest file lists items to install, uninstall, offer up as optional installs, and possibly include other manifests with more information. The client will recursively look up all included manifests at their respective URLs. The manifest will also include at least one catalog file, describing which versions of the items to install or offer, and where they are located on the server (i.e., their URL). You can think of the manifest file(s) as a “shopping list” for the client, telling them what to download, install, update, uninstall, or offer as an optional install, while the catalog file is what is available in the store, listing what items and versions are (or aren’t, in some cases) available in the “store” and where to find them.

Munki (specifically, managedsoftwareupdate) will continue this process of recursively reading manifest and catalog files from their URLs until it has a list of apps, profiles, pkgs, etc. to install, as well as their available versions and locations on the server (URLs). It will then compare those versions with the versions found on the machine (if any) and download and install the necessary items.

Conclusion

Once you can wrap your head around the idea that the server isn’t performing any operation or logic besides serving items requested from different locations over http(s), setting everything up should hopefully make more sense. Wherever your repository is, you only need a web server to serve the requested files. Managing the munki server—or, more specifically, the repo—is done by importing files in the proper folders and manipulating manifest, pkginfo, and catalog files using the proper command line tools. Once you’ve gained an understanding of what each of these do, you can move on to GUI tools, such as MunkiAdmin, but it helps to know what such tools are doing “under the hood,” so to speak.