Getting Started with Munki (not monkey)

5 April, 2018 update: This page used to have a tutorial that walked you through setting up a bunch of GUI tools to manage and keep up-to-date a Munki server. I’ve reconsidered, and I don’t think that’s the best approach for new Munki administrators to take to learning Munki.

First Steps

Here are a series of links you should read and follow, in this order, to explore Munki on your own:

  1. Demonstration Setup: Walks you through a very basic setup, using a Mac as a Munki server and another Mac (or even the server itself) as a test Munki client. Even though you can do so, I’d highly recommend against setting up a Mac running to be your Munki server. If you use a Mac, just use regular macOS with the built-in Apache.
  2. Overview: If you’re absolutely new to Munki, you should really understand the basic mechanics of it and what catalogs and manifests are. If you read the overview and are still confused, ask for clarification from other Munki administrators (see links in Getting Help).
  3. How Munki Decides What Needs To Be Installed: This is one of the most frequently asked questions from new Munki administrators, so it’s very important you understand why you may have a Munki item that’s in an endless install loop (and how to fix it).
  4. An opinionated guide to Munki manifests : Some opinions on how you should structure your manifests in Munki.
  5. Another opinionated guide to Munki manifests: Some more (related) opinions on how you should structure your manifests in Munki.

Getting Help

And here are some great places to go for help, if you have Munki-related questions:

  1. MacAdmins Slack #munki channel
  2. Munki-Discuss Google Group
  3. MacEnterprise mailing list

Server Setup

Want to secure your Munki repo and/or move it to Linux? You may find these links handy:

  1. Using https / self-signed certificates and basic authentication with Munki: If you want to stay with macOS and have basic authentication on an internal-only server.
  2. Certbot Apache on macOS: If you’re going for basic authentication on a public-facing server, and you want a proper (not self-signed) SSL certificate.
  3. Setup a Munki repo on Ubuntu 14.04 – Part 1: Yes, I know it says 14.04, but the basic instructions still work for 16.04, and they’ll probably work for 18.04, too.
  4. Certbot Nginx on Ubuntu 16.04 (xenial): Proper SSL certificate for Ubuntu (again, if your server is public-facing).
  5. Using Munki With SSL Client Certificates: Basic authentication not enough security for you? Set up revokable client certificates instead.

Munki-related Helper Tools

Need other helper tools?

  1. AutoPkg: Allows you to automate downloading and installing new software into your Munki repo. Get to know the command-line tool well first if you choose to also install the (no longer maintained) GUI management for it called AutoPkgr.
  2. MunkiAdmin: A great graphical frontend for managing your Munki repo (after you’ve already understood how the pieces work together… and, frankly, even with MunkiAdmin, I’d still recommend using munkiimport on the command-line to manually import new items that don’t come through AutoPkg). As an alternative, you may want to check out mwa2, which is web-based.
  3. MunkiReport-PHP or sal: If you want to add in a reporting piece to see what your Munki clients are up to.

28 responses to “Getting Started with Munki (not monkey)”

  1. Thank you for this guide and thanks to Greg Neagle who I just met at psumac.
    You might have both saved my job!

    • There actually isn’t anything that’s El Capitan–specific. These instructions, though using Yosemite, also apply to El Capitan. No plans for a YouTube video, but if you run into any roadblocks, let me know. You can also post on the Mac Enterprise mailing list or the MacAdmins Slack.

  2. Is there an easy way of deploying software to a specific group of machines? I know I can create a catalog -> manifest but this might get quite convoluted quickly.

    • Yes, Alex. Read Another opinionated guide to Munki manifests for more details, but you essentially have individual manifests per machine, and then those individual manifests include other manifests.

      So, for example, let’s say you have an iMac lab with ten machines. Each of those machines has its own manifest (so ten in total), but each machine manifest also includes a lab manifest (so an additional one).

      Then if someone says “Hey, Alex, can we get such-and-such software on the iMacs in the lab?” you can just plop that software into the lab manifest. And if someone says, “Alex, can we get such-and-such software on only machine #1 in the lab?” you can put it in machine #1’s manifest.

  3. This guide has been super helpful!

    One note though…on the client side, it seems like you are missing an extra command. Found that:

    sudo defaults write /Library/Preferences/ManagedInstalls ClientIdentifier “manifest_that_you_named”

    after doing:

    sudo defaults write /Library/Preferences/ManagedInstalls SoftwareRepoURL “”

    made it work for me.

    I got hung up here for the longest time.

    Thank you again for putting this together!

    • My recommendation is that you use a manifest that is the serial number of the machine, so you shouldn’t, in that case, need a ClientIdentifier. But, yes, if you want to specify a manifest that is not the serial number, you need to add that as a separate preference on the client.

  4. Hi Alan, so thankful for this write up. I had no idea what Munki and AutoPkgr was; still learning, even though I’ve been using DeployStudio for some time. I’m probably missing out on a lot of good stuff. Thanks again. Mel

    • Glad you’re finding it helpful. If you have any simple questions, feel free to post on the blog here, and I can try to help you out. More complex stuff, you may want to hop on the MacAdmins Slack for.

  5. I followed the guide here but i goofed up the first try installing the server. I did not uncheck the client components. So I did the un-install moves on the munki GitHub wiki the reinstalled munki on the server and unchecked the client components. After rebooting and getting some packages imported to the Munki repo, I see that the server is installing them. Can you share how to remove the client portions to prevent the server from installing the extra software?

    • I’m not sure I understand your situation. The server is installing the client components on itself? How do you “see that the server is installing them”? What are you seeing exactly?

      For separating out the components, you may want to check out the munkitools2 AutoPkg recipe, which downloads them all as the four separate component .pkg installers:

      That said, I wouldn’t stress too much about it. There isn’t really a lot of harm in the client tools being on the server, as long as you put in a SoftwareRepoURL (otherwise, it defaults to http://munki).

  6. YOU are awesome Alan!! I always have been impressed with your willingness to share problems/solutions from behind your nifty desk down there in the tech office.
    Am so appreciative of your Munki seminar (have watched second-by-second) setting up the server today (Saturday) at school. SO much here….
    Thank you x1000

  7. Thanks for your great job posting this info here, but is there any way so you please can update this article with the most current version and steps?

    • Hi, VS. I just made some edits yesterday to that effect. Can you point out some stuff that’s out of date, so I can update again if necessary?

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.