Author: alanysiu

Tools for managing Munki manifests

You can manipulate your Munki repo using only command-line tools, and I would highly recommend you keep using munkiimport for all manual item imports (again, we’ll get to automated imports later), but I use a GUI (graphical user interface) app to manage my repo day to day, so I recommend using one. For these tutorials, I’ll be using MunkiAdmin.

If you have time to explore the command-line tool manifestutil, you may find it useful for quick direct manifest manipulation without having to deal with a GUI.

What is a manifest?

Expanding a bit on How does Munki work?, manifests are the key to deploying software to your fleet of Macs. One of the most frequently asked questions about Munki is I just set up Munki and there’s nothing available to install in Managed Software Center, and there’s no sidebar showing “Software” or “Categories”. How do I make things to install show up there?, and that’s because a lot of new Munki admins don’t really understand what a manifest is.

When your Munki clients check in with the Munki repo, one of the first things they’ll look for is a manifest, which tells the client what software it has available to install optionally, which software must be installed, which software must be updated, and which software must be removed.

Catalogs and manifests

One part of a manifest is the catalog(s) it has available to it. Remember when you imported an item with munkiimport, and it asked what catalog you wanted to import it into? You started with the testing catalog, which is a good place to start. If you have Firefox 141.0.3 in the testing catalog and Firefox 141.0.2 in the production catalog, the manifests that have the testing catalog will see 141.0.3 as the latest version of Firefox to update to or install, and the manifests that have the production catalog will see 141.0.2 as the latest version available. If one manifest has both testing and production catalogs, Munki will consider whichever one is listed first (literally the manifest is a XML-formatted text file, and whichever catalog is listed above the other in the text file).

For now, just to keep things simple, we’re going to use only the testing catalog. We can look at using a production catalog later.

Some Munki admins use the analogy of the catalogs being stores and the manifests being what you put in your basket or shopping cart, but there isn’t really a good exact analogy for this, because stores can’t force you to buy certain items or force you to return items that you may own.

Bottom line, a manifest can install, remove, or update only versions of items that are in the catalog(s) it uses.

Creating and modifying a manifest using MunkiAdmin

So if you install and launch up MunkiAdmin, the first thing you’ll see is a prompt for what repository to use.

Go ahead and pick the repo that you’d set up earlier in /Users/Shared/munki_repo/

Under the File menu, select New Manifest

For the file name, type in site_default

There are three views in MunkAdmin—the packages view, the catalogs view, and the manifests view. If you switch to the manifests view, you can then double-click the site_default manifest to edit it.

There are a whole bunch of manifest options to edit. The only available catalog is testing, because the only item in the Munki repo right now is Firefox, and the only catalog Firefox has right now is testing.

Go ahead and check (or tick) the box next to testing to allow the site_default manifest to items from the testing catalog.

On the left side, click on Optional Installs.

Click the plus (+) sign to add an item to the optional installs section of the manifest. (When I took this screenshot, the latest Firefox was 64.0.2, but MunkiAdmin show whatever version you imported.)

Right now, the only item we have to pick from is Firefox, so go ahead select that and then click Add Selected to add it to the optional_installs section of the site_default manifest.

Then, click Save to save your changes to the site_default file in the manifests folder.

If you go to /Users/Shared/munki_repo/manifests/site_default and open it up in a text editor, you’ll see that the catalog this manifest uses is the testing catalog, and it has one optional install available to clients using this manifest—Firefox.

Once a client machine connects to the Munki repo, it will be able to install Firefox or remove it.

Now that you’ve set up your Munki repo and installed Munki tools, let’s get an item into the Munki repo.

Get an item to import

In the future, we’ll look at a way to automate downloading new software into your Munki repo, but for now, let’s just manually download something. Firefox is as good an item to start with as any. It’s a simple drag-and-drop .app bundle, and it’s free to download. So go ahead and download Firefox.

Import the item

There are command-line tools to do everything you want to manage your Munki repo. I actually prefer to use a point-and-click program (which we’ll install later) to manage my Munki repo, but even with that, I still use the command-line for importing items into Munki, because it asks a lot of questions, and because it can create a .dmg on the fly for an .app bundle that doesn’t already come in a .dmg.

Let’s go ahead and use munkiimport to import Firefox.

munkiimport Downloads/Firefox\ 141.0.2.dmg

I’m using a specific version of Firefox for this example, but obviously use whatever version you downloaded. Tab completion can be helpful here. Once you type Firefox, hit Tab, and the rest should fill in, as long as you don’t have multiple Firefox versions downloaded to the same folder.

Item name: Firefox

munkiimport may detect the item name. Please pay special attention to what you fill in here. You can go with whatever munkiimport suggests or put in your own preferred name, but names are how Munki refers to items. The display name and description below are things your users will see later, but the item name is what will change Munki functionality. If you have an item named Firefox that has a display name of Firefox and then another item named MozillaFirefox that has a display name of Firefox, your users may see them as the same, but Munki will see them as different, because they have different item names.

Display name: Mozilla Firefox
Description: Firefox web browser

For things that munkiimport doesn’t detect, go ahead and just fill in whatever you think is appropriate. You can also leave these blank, but I’d recommend filling in as much as you can.

Version: 141.0.2

Because this is an .app bundle, the version should be easily detectable (assuming the vendor packaged it properly), so you may find the version fills in automatically.

Category: Browsers
Developer: Mozilla

Once again, the more information you can give your users, the better. But you can leave these blank if you really want to.

Unattended install: True
Unattended uninstall: True

munkiimport will have these default to False, but in almost all cases (with some exceptions we’ll go into later), you’ll want to change these to True. If you even just type t, that’ll work, too. You don’t have to type out the entire word True.

Catalogs: testing

You almost always want to start with adding only to the testing catalog. Even if your testing is only to make sure the program installs successfully, launches up, and doesn’t crash immediately afterwards; that’s still better than putting it immediately into production.

Import this item? [y/n] y

Type y to confirm you want to import the item.

Upload item to subdirectory path []:

Some Munki admins like to put items into various subfolders for their own organizational purposes. In terms of functionality and performance, your Munki clients won’t care whether the item is at the top level or in a subfolder. I usually just go with the top-level (so hit Return here), but if you feel strongly about using your own subfolders, go for it, and organize them however you want.

No existing product icon found.
Attempt to create a product icon? [y/n] y
Attempting to extract and upload icon...
Imported icons/Firefox.png.

It will look prettier and be easier to navigate for your users if you have icons for the items in your Munki repo, so it’s worth it to see if munkiimport can extract a missing icon.

Many times (as with Firefox), munkiimport will find an appropriate icon, and then all is good. Sometimes, it may find various icons and not know which one to use, in which case, you’ll get numbered icons (e.g., NAMEOFITEM_1.png, NAMEOFITEM_2.png, NAMEOFITEM_3.png)—it would then be your job to go into the icons folder and rename one to be NAMEOFITEM.png and then delete the extraneous ones.

Copying Firefox 141.0.2.dmg to repo...
Copied Firefox 141.0.2.dmg to pkgs/Firefox 141.0.2.dmg.
Edit pkginfo before upload? [y/n]: n

There may be times you want to edit the pkginfo file for the item before you rebuild the catalogs, but in most cases, you’ll just want to proceed. Provided the vendor has packaged things properly, munkiimport is fairly good at detecting the right settings for each item.

Saved pkginfo to pkgsinfo/Firefox-141.0.2.
Rebuild catalogs? [y/n] y
Rebuilding catalogs at file:///Users/Shared/munki_repo...
Created icons/_icon_hashes.plist...

Munki clients cannot see pkginfo files. They see catalogs. So if you change a pkginfo file and want your Munki clients to pick up on those changes, you need to rebuild the catalogs. Since munkiimport prompts you, you can just type y to confirm you want catalogs rebuilt. If you edit a pkginfo file manually yourself later (apart from munkiimport), you’ll want to run the makecatalogs command manually afterwards.

Also, if you’re importing several items manually with munkiimport, you may want to wait until after the last item is done before you decide to rebuild catalogs. You can rebuild after each one, too—it may just take a little longer than doing it only once at the end.

Taking a look at what happened after an item import

After you do this import, your Munki repo should look like this:

catalogs/all
catalogs/testing

The all catalog has all the catalog info, but since you have only a testing catalog, right now the two are identical. You can take a look at these two files just to see what they look like, but you should never manually edit a catalog file.

icons/_icon_hashes.plist
icons/Firefox.png

The icon hashes have hashes for each icon in the directory, and then you have the icons you extracted or manually copied to the icons directory. See? There’s your Firefox.png that munkiimport extracted from the .app in the .dmg.

manifests/

We don’t have any manifests yet. We’ll make one in the next tutorial.

pkgs/Firefox 141.0.2.dmg

When you import an item, whatever “installer” it has munkiimport will copy to the pkgs directory. That will most likely be a .pkg or a .dmg.

Remember when you could have created a subdirectory? Well, if you had, your Firefox would be in pkgs/NAMEOFYOURSUBDIRECTORY/Firefox VERSIONNUMBER.dmg instead of pkgs/Firefox VERSIONNUMBER.dmg.

pkgsinfo/Firefox-141.0.2.pkginfo

munkiimport creates a pkginfo file for the Firefox item. This has all the information that will get put into the catalogs file(s) that your Munki clients will use to decide whether Firefox (or whatever item it is) is installed already, how to install it, how to remove it, which is the newest version, etc.

Before you begin…

Please read the following before you start rolling up your sleeves and setting up Munki:

• Why should your school use Munki to manage its Macs?
• Basic requirements for Munki
• How does Munki work?

tl;dr

This guide will walk you through getting set up a certain way so you can get up and running quickly with some sensible defaults. There are many ways to set up Munki. After you get really comfortable with it, for example, you may want to change things up a bit (for example, run Nginx instead of Apache or use Linux instead of macOS). Covering all the ways to run Munki is not the point of this site.

Turning on Apache

Don’t use Server.app

On your Mac Mini (or whatever Mac you’re setting aside to be your server), do not use Server.app. Make sure Server.app has either never touched that Mac or that you’ve completely removed it. Starting with Server 5.7.1, it may even be a non-issue, since Websites has been stripped out of it. That was in 2022, so I hope it doesn’t need to be said, but I’ll said it anyway: don’t use Server.app.

We’re going to use the built-in Apache.

Turning on the built-in Apache

Go to /Applications/Utilities/Terminal.app and paste in this command to turn on Apache:

sudo apachectl start

If it worked, you should be able to go to http://localhost and see It works!.

Creating the directories needed for your Munki repo

Paste in these commands to create subdirectories in /Users/Shared for the Munki repo

cd /Users/Shared/
mkdir munki_repo
mkdir munki_repo/catalogs
mkdir munki_repo/icons
mkdir munki_repo/manifests
mkdir munki_repo/pkgs
mkdir munki_repo/pkgsinfo

Let’s set proper permissions for these directories:

chmod -R a+rX munki_repo

Now, we’re going to create a symlink from the munki_repo folder we created in /Users/Shared to the /Library/WebServer/Documents directory (which is where Apache looks to serve up files):

sudo ln -s /Users/Shared/munki_repo /Library/WebServer/Documents/

Now you should have an empty Munki repo. In order to populate it, we’ll have to install Munki tools.

Setting up Munki tools to manage your repo

It’s important to know that a “Munki server” is just a web server. All it does is host files. So even though we’re about to install Munki on this Mac, which is also the Munki server, a Munki server does not need to have Munki tools installed. In fact, many Munki servers (for example, ones hosted on Linux or Windows) cannot have Munki tools installed on them. If you were to eventually host your repo on Linux, you would install Munki tools on a Mac, and then remotely manage your Linux-hosted Munki repo from that Mac (or another Mac).

Installing Munki tools

You can always get the latest Munki tools from https://github.com/munki/munki/releases/latest

I’d recommend you do the standard install, which installs all the components. If, in the middle of installation, you click to customize, you’ll see there are five components:

• Munki core tools
• Munki admin tools
• Managed Software Center
• Munki app usage monitoring tool
• Munki launchd files

Munki core tools are what allows Munki to do most of its work (analyze what’s installed and compare it to what should be installed, and install or remove what needs to be installed or removed, etc.).

Munki admin tools are what we’re about to use to populate and manage the Munki repo. There’s really no harm in installing it on your client machines, because, without write-access to the Munki repo, your clients can’t really do anything with the tools.

Managed Software Center is the App Store–like graphical interface your users will see to install updates that require user interaction (for example, ones that require a reboot or logout) or to self-select software that you make available as optional installs.

Munki launchd files gives Munki a dynamic quality, for example, allowing Munki to do its background runs every hour or so.

Munki app usage monitoring tools keep track of how often users are launching applications or quitting them, so that if you want to remove software that hasn’t been used in a while, you can specify how long it should be before unused software is automatically removed. You don’t have to remove unused software, but there isn’t a ton of overhead to install this, so feel free to install this along with the other four components.

Setting up munkiimport

For now, we’re just going to use the Munki server to manage itself. Really, though, if you configure file sharing properly (via SMB, for example), you should be able to use any Mac to manage the Munki server.

In the terminal, run this command, and then answer the prompts appropriately.
munkiimport --configure

Repo URL (example: afp://munki.example.com/repo): file:///Users/Shared/munki_repo

Again, this is a file address for if you’re using the Mac you’re using as the server to access itself. If you were mounting the server share from another machine, you’d configure munkiimport to use an smb:// or afp:// address instead.

pkginfo extension (Example: .plist): .pkginfo

You can just press Return here to use the .plist extension. Some people choose to use .pkginfo instead. It’s up to you. Both are fine. Or leaving it blank, too, can work. I like to put in .pkginfo as an extension, so that’s what you’ll see in future tutorials.

pkginfo editor (examples: /usr/bin/vi or TextMate.app; leave empty to not open an editor after import): BBEdit.app

If you have strong opinions about what text editor you like to use, go ahead and put it in here. If you’re not sure what to use, I’d recommend BBEdit.

Default catalog to use (example: testing):

Just hit Return here. testing is a fine default catalog to use.

Repo access plugin (defaults to FileRepo):

Hit Return here as well, and then you’re all set.

Now we have a Munki repo set up and munkiimport configured to use the repo. Next time, we’ll work on actually setting up the repo to be useful to clients.

Even though the posts on this blog go into detail on how to get Munki set up for your school environment, you may want to get more of a bird’s-eye-view of what all the pieces are, and how they work together.

On a very basic level, there is a Munki client, which is any Mac (MacBook Air, MacBook Pro, iMac, etc.) that has Munki installed and configured on it, and then the Munki repo server, which is a static web server of any kind (Apache, Nginx, IIS, etc.). All the server does is serve up files. It is just as static as a Geocities website from the 1990s. The Munki client does all the work. The Mac will check in with the Munki repo (in the background once every hour or so or manually if the user launches up Managed Software Center) to check for instructions on what needs to be done (Do I need to update my software? Is there new optional software the user can install herself? What new software that wasn’t installed before should I install?).

On the Munki repo itself, there are several key components that a Mac admin would need to change up so machines checking in know what to do to themselves.

When you add items (packages, drag-and-drop .app bundles) to the Munki repo, there’s a pkginfo text file (a plist or XML format) that stores information about that item (what version, the name of the item, where its installer is, etc.), and then there’s the installer itself, in whatever form it takes (.pkg, .dmg, etc.).

Every item has at least one catalog attached to it, indicating whether it is in testing or production (or both). You can also have a development catalog, too, if you want to add a third layer to your rollout process.

Each client machine uses a manifest on the Munki repo to determine what items it should install, remove, update, or make available for the user to install. There can be manifests that many client Macs share, or you can have individual manifests unique to each machine.

As you go through the tutorials on this blog, you’ll get a much better sense of how all these pieces fit together.

Knowledge Requirements

• You should have at least a basic understanding of IP addresses and domain names, and the ability to assign a static IP to a computer/server, give a computer/server a proper fully qualified domain name that internal or external DNS can recognize, or do both.
• You should be able to double-click-install a .pkg on a Mac.
• If you have never maintained a web server before, you have some sense of the idea of a computer serving up files for other computers to view or download, and the importance of securing it with https (either with a self-signed or proper Certificate Authority–issued certificate).
• Even though there are graphical (point-and-click) ways to manage Munki, in order to fully understand what you’re doing, it’s best to learn some things via the command-line. So even if you don’t know a lot of terminal commands, being comfortable copying and pasting or re-typing some commands into the terminal will be critical to the learning experience. You don’t have to have these commands memorized.

Hardware Requirements

• At least one web server (or a Mac that can act as one). That can be a server in the cloud (e.g., Amazon Web Services, Google Cloud Platform) or one you host locally (e.g., Linux VM, IIS on a Windows server). If you don’t have any of those things, you can even just use a Mac Mini. Since the Mac Mini would be the lowest common denominator (the only thing we can assume you have if you’re doing Mac management would be at least two Macs, and one of those can be the web server you host the Munki repo on).
• A working Internet connection. Your client Macs will be downloading files from the web server that hosts the Munki repo. Even if you don’t have a great external connection, the Macs should at least be able to reach an internal server.

Munki (cost-free and open source) is a way to deploy software to and update software on a fleet of Macs. It’s used widely by schools, universities, and corporations (here’s a list of only what’s publicly known about who’s using Munki, and that’s only what can be easily found publicly).

Even if you have the money for a cheaper MDM like Mosyle (which is fully featured at a very affordable per-device-per-year price but also has a one-platform-only free tier), it really operates quite differently from Munki, and ideally you would have both together. Mosyle even has a write-up on this: Why deploy Munki using an MDM solution and Apple DEP.

Many schools use and like Jamf, which is an MDM but also has a lot of non-MDM features. Even with Jamf, there are those who desire Munki’s features and deploy the two together. To get a sense of why, you might want to read this thread: Software Patching – What’s the future?.

If your school cannot afford an MDM of any kind (please don’t use Profile Manager as your MDM), Munki on its own can be an affordable (just costs time to set up) and extremely useful tool for managing Macs (you’ll just miss out on certain things that Apple requires a user-approved MDM for, like system extension approval).