Another opinionated guide to Munki manifests

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?

Why this guide?

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 (which I've since adapted to a blog post called Absolute beginner’s guide to setting up Munki (not monkey)) 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.

The setup I would recommend

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.

manifestdisplaynameFor 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: includedmanifests 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:

No client id specified. Requesting MachineName.CompanyName.com...
Getting manifest MachineName.CompanyName.com...
Retrieving list of software for this machine...
Bytes received: 230
Request failed. Trying MachineName...
Getting manifest MachineName...
Retrieving list of software for this machine...
Bytes received: 219
Request failed. Trying SerialNumber...
Getting manifest SerialNumber...
Using manifest: SerialNumber

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

What are the benefits of this approach?

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.

Bulk-creating manifests from serial numbers

If you haven't created any manifests yet, and you have a whole ton to create and don't want to do them manually, 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.

Switching to serial numbers from a different setup

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.

Create subfolders for your included manifests

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.

And then, going forward?

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.

13 thoughts on “Another opinionated guide to Munki manifests”

  1. Hey Alan,
    I’d have a question regarding this setup. I’m trying to use your setup but I’m asking myself how you handle optional installs. I’d like to be able to assign certain software to only one machine and not push it out to everyone. I tried adding the software to the top level manifests (with the serialnumber as a name) in the “optional installs” section for the laptop but this is not working as expected.
    Am I missing something?

    I’d be thankfull for any insight or suggestion!

    Thanks,
    Patrick

    1. No, that’s absolutely right. If you have a serial number manifest that includes other manifests, and you want to target that specific machine, you just put it in the optional installs for that serial number manifest.

      Can you be more specific than “this is not working as expected,” though?

      Here are some tips: https://github.com/munki/munki/wiki/Troubleshooting

      1. Hey Alan,

        thans for the quick response! Sure, I’ll try to be more specific:
        So I’m triying to set up our munki structure as follows with the information in mind from your article:
        A Client manifests for each mac with serial numbers as name. They contain an included manifest called “software” where I defined managed installs and also some general optional installs for the kiosk so that people can install and remove software themselves. Each client manifest has a catalog that contains our pool of software. The included manifest itself does not have a catalog.
        When I add a software to the optional software section of the included manifest it works, the software can be installed. But the thing is that I have different types of software. For the kiosk we dont want to let people install software that needs licenses. Colleagues should only be able to install free software.
        So what is not working in this setup is to add software to the optional section auf the top level manifests (with the serial names). So that colleagues can request software and we can push it out to them.

        There was an a little bit different setup before I started in my current company, I just wanted to adjust it a little more to your setup recommendation. The old setup looked as follows:
        Also client manifests for each mac with serial numbers. One other manifest called “site_default” that has managed installs and optional installs. Each client manifest and the “site_default” have the catalogue defined (Which is not recommended in your setup, right?).
        But unfortunately we had the same problem with this.

        I like your setup because its very flexibel. But so far I was not able to get the your results.

        I hope I was specific enough and you can better understand what my plan is.

        Thank you for your help,
        Patrick

          1. Hey Alan,

            thanks for your response! I don’t have a Slack account yet. Can I use the account creation link on the link you send me to join the channel? Or do I need to create a general Slack Account first?

            Best,
            Patrick

          2. Hey Alan,

            I was able to find the problem today. It was with my rebranded munkitools installation package. While rebranding I set the client identifier to site_default. So the clients would only check at site_default, what makes sense… Didn’t know it better at the time and forgot about that. I rebranded it with an empty CI and now the clients are reporting as expected.

            Thank you for your help,
            Patrick

          3. Yes, you definitely don’t want to ever explicitly set site_default as a ClientIdentifier. That would be the fallback manifest in case no other manifest is found (but, again, only if no ClientIdentifier is set).

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.