Why this guide?
The setup I would recommend
What are the benefits of this approach?
Bulk-creating manifests from serial numbers
Switching to serial numbers from a different setup
Subfolders for included manifests
And then, going forward?

When I first started using Munki, all the terminology was a bit overwhelming to me, even when I read Catalogs, Manifests, Packages: Anatomy of Munki or other Munki wiki articles.

I was so busy trying to do the Demonstration Setup that I didn’t give a lot of thought to how my manifests were structured.

Based on the kinds of questions other new Munki admins have asked on the Munki Discuss mailing list, the MacEnterprise mailing list, and the Mac Admins Slack Munki channel, it seems I wasn’t the only confused newcomer, and I probably won’t be the last.

Initially, I just had a handful of manifests that I shared on various client machines. So all the faculty were on a faculty manifest, all the library machines were on a library manifest, etc. That wasn’t ideal, because suddenly one library machine had to have a different setup from another library machine, or one faculty laptop had to be different from the other faculty laptops. Doing one-offs with computers sharing manifests was unwieldy and impractical.

At some point, like some other Munki newcomers, I thought “Maybe there’s a scripted way that I can fix this,” and I stumbled upon Munki Enroll. I’m not bagging on Munki Enroll. It works for Cody Eding (the author), and I’m sure it works for a lot of others as well. That said, I don’t think—if you are starting Munki from scratch—that Munki Enroll is necessarily the way you want to start out.

I’ve named this blog post in honor of An opinionated guide to Munki manifests, which also recommends against non-individual manifests and recommends against using Munki Enroll.

groob has been using Munki for over three years. I’ve been using it for about a year and a half, and I have regrets about how I initially implemented manifests. I’m fixing those mistakes now, but this blog post, like groob’s post is intended to help new Munki users avoid going down the wrong path and then having to fix things later.

I’m not a Munki expert, and I don’t know that there’s a consensus about best practice, because each organization has its own needs, but if you don’t know what you’re doing (you’re completely new to Munki), this is the way I would recommend to start.

I would recommend you create manifest names based on your Macs’ serial numbers, and then in each manifest, name the display_name to something meaningful to you.

For example, instead of creating an individual machine manifest Anne-Fausto-Sterling, you would create the manifest with Anne’s Mac’s serial number, and then have the display_name of the manifest be Anne Fausto-Sterling.

How you get all the serial numbers of your machines is up to you. Presumably you have an inventory database of some kind or even electronic invoices of machines you ordered. If all you have is Apple Remote Desktop (ARD) access to your fleet, you can select all your computers, click Reports, deselect all fields, expand Computer, check Serial Number, click Get Report, then click Export, and you’ll get a tab-delimited or comma-delimited report with the computer names and respective serial numbers.

MunkiAdmin has a nice GUI frontend for editing the display names of manifests. Munki Web Admin 2 does as well.

After each manifest has its own individual manifest named after its serial number, you can create some manifests to include. Keep in mind that you can include more than one manifest and can also have nested manifests.

The included manifests should not have a catalog defined. All the individual (serial number) manifests should (e.g., production for top-level manifest, nothing for included manifests). It honestly doesn’t hurt if the two catalogs are the same (e.g., production for both), but your manifests may not behave as you expect if they are different (e.g., production for top-level manifest, testing for included manifest). Still, it’s best and safest to have the included manifests have no catalog at all.

You also want your included manifests to be in a subdirectory of your manifests folder. More details on that below.

Here’s an example of how you can structure your manifests:

This is only an example so you can get the basic concepts, but you obviously need to tailor your manifest structuring to what suits your organization’s needs.

In this example, there are three machines in iMac Lab A. Each machine has its own manifest named for its serial number, and each of those individual machine manifests has a catalog specified (production, in this case).

But each of the three machines also has included manifests. They include a manifest for the lab itself, one for a bunch of printers, and one for general essentials.

Note that none of the included manifests themselves has catalogs (i.e., iMac Lab A, Printers, Essentials, and iMac Labs).

iMac Lab A itself includes yet another (nested included) manifest of iMac Labs.

Why structure things this way? Well, it allows for maximum flexibility. You can say “I’ll plop this managed_install into iMac Lab A,” and it will install on all three computers. You can target a specific machine by serial number. Supposedly there’s an iMac Lab B, and an iMac Lab C, and you can target those (and iMac Lab A) by putting something in the iMac Labs manifest. You can apply the printers or essentials included manifests to other groups of computers not in labs.

Just be sure you don’t overly complicate things. If you have only 30 computers at your organization, it doesn’t make sense to have 10 included manifests. Do what makes sense for your organization. This chart is just to give you an idea about possibilities.

In your client machine preferences, do not set a ClientIdentifier. When the ClientIdentifier isn’t set, Munki will check for a fully qualified domain, a computer name, a serial number, and then site_default. Here’s an example:

I did ask some others on the Mac Admins Slack what they thought about specifying a ClientIdentifier vs. just letting it fall back to the serial number, and the consensus seemed to be there’s virtually no performance gain for specifying the ClientIdentifier, unless you have a huge fleet (50,000-100,000 Macs all checking in on the same Munki server). Then those two failed requests per machine may make a slight difference. Maybe then not enough for you to care—that’s your call. I have a fleet of about 300 Macs, so it’s no biggie to have the 230 Bytes or 219 Bytes fail before getting to the serial number manifest. (The time it takes to fail is also virtually nothing to an end user.)

Here’s why I recommend this approach:

• Not having a ClientIdentifier gives you the flexibility of using a serial number, an FQDN, or computer name without having to modify anything on the client end.
• Not having a ClientIdentifier also means if you have to re-image the machine, you don’t have to remember to put the correct ClientIdentifier in to get the correct manifest.
• Not having a ClientIdentifier allows you to easily repurpose a machine without having to make any preference changes to the machine itself. So if a faculty laptop suddenly becomes a loaner laptop, all you have to do is change the manifest’s display name and included manifest.
• You don’t have to come up with actually unique names for each client. Serial numbers have to be unique, so they’re a good choice for individual manifest name.
• You (as a person) likely won’t be able to tell machines by serial number, but the display name can be whatever makes the most sense to you, whether that’s the person who primarily uses the computer or the computer’s name.
• Since each machine has its own manifest, you can easily make changes to any particular machine. And since each machine likely has one or more (or nested) included manifests, you can also target many machines at once.

If you haven’t created any manifests yet, and you have a whole ton to create and don’t want to do them manually, there are a couple of ways to do that.

If you’re using MunkiAdmin, there’s an option to create manifests from a .csv file:

If you’d prefer to use a script instead, I wrote a script to bulk-create serial-number manifests, which you can adapt for your own organization based on whatever data you have on your machines.

What if it’s too late? Like me, you just started creating general manifests and then trying to create some individual manifests later with Munki Enroll.

Well, here is a script that I used to fix the manifests on my Munki server. You can’t just deploy it as is. You’ll have to adapt the parameters to fit your organization’s situation, but it may be a good jumping-off point for you.

Then, for the client side, I deployed this nopkg that deletes the ClientIdentifier from the ManagedInstalls preferences. You could also create your own payload-free package instead of using my nopkg.

As @elios on the MacAdmins Slack points out, it’s a good idea with the serial number–based approach to put included manifests in subfolder, just on the off chance that a client machine has a hostname that’s the same as an included manifest. For example, a machine might be called student_machine but wouldn’t be called groups/student_machine.

If you don’t have your included manifests in a subfolder, I wrote up a script that will put your included manifests in a subfolder.

Going forward, you can do whatever makes sense. If you get in one or two new machines, you can hand-create those manifests in MunkiAdmin or MWA2, or you can script copying from a template manifest.