Changing client computer names using a Munki nopkg

In Another opinionated guide to Munki manifests, I said one of the benefits of having no ClientIdentifier and using serial numbers as manifests was not having to manually change preferences on the machine if you repurpose it.

What if you want the machine name to change, though? It used to be something like Basketball01, and now you want it to be Music05, for example.

You can make that change by simply adding this ComputerFromDisplayName nopkg to the client's serial number manifest (or one of its included manifests).

What the nopkg script does is check that the client manifest has been downloaded to the client machine (usually has after one Munki run, but can't hurt to verify), checks that the downloaded manifest has a display name, and then sees if the display name differs from the computer name. If the two names differ, the script changes the computer name (and the hostname and local hostname) to match the display name.

So you would just add this to the manifest, change the manifest's display name, and then on the next Munki run, it would change the computer's name to match the display name you set earlier.


Scripting manifest creation in Munki

If you're new to Munki, you probably have an entire fleet of Macs you have to manage. It could be hundreds, thousands, or tens of thousands. You're not going to enroll those all by hand, are you?

But please be intentional about how you structure things. Before you run off scripting, read Another opinionated guide to Munki manifests and the original An opinionated guide to Munki manifests.

Seriously. Read those first. Don't start scripting the creation of Munki manifests before you get the full lowdown.

I'm waiting.

Okay. You read those, right? You aren't just itching to download a script from GitHub?

Okay. Let's proceed.

First off, there doesn't need to be anything terribly complicated to the script-creation of manifests. If you get in a new batch of machines with serial numbers, you can just copy a template manifest over and over again, naming the new files after the serial numbers. You could also create a script that builds the manifest from scratch based on a number of parameters (example here).

I recently created a fork of Munki Enroll. The fork is called Munki Serial Enroll, and it works similarly to Munki Enroll, except that it doesn't use a ClientIdentifier (just creates manifests with serial numbers and display names), has different logic for laptops/desktops, and copies from existing manifest templates instead of creating the manifest on the fly.

You should not just use Munki Enroll. You should not just use Munki Serial Enroll.

But either of those can be helpful templates, which you should modify, after you've given serious thought to what workflow works best for your organization's needs.

I made Munki Serial Enroll really specific for my organization's needs, so it is not at all meant to be used out of the box, and that's by design. It's meant to give you a jumping-off point and some ideas. It is not meant to be used as is.

I urge you once again before you go scripting manifest creation: read Another opinionated guide to Munki manifests and the original An opinionated guide to Munki manifests first.

Know what you want to manually do repeatedly. Then start thinking about scripting it.


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


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
Getting manifest
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, 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.

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.