Absolute beginner’s guide to setting up Munki (not monkey)

Table of Contents

Why this guide?
What is Munki?
What are the basic requirements for this setup?
Install on the server Mac the needed software
Prepare the server to be a Munki software repository.
Use MunkiAdmin to set up your repositories, catalogs, and manifests.
Import software into your repository manually
Figure out your server Mac's IP address
Set up the Munki client
Set up AutoPkgr

Why this guide?

While there's no dearth of comprehensive guides to Munki out there, many of them are too comprehensive (to the point of being potentially overwhelming to new users). The focus of this guide is to get you up and running with Munki, not to give you a comprehensive, in-depth explanation of everything Munki can and cannot do.

Interested in the more comprehensive guides instead? Check out the following links:

Still here? Okay. Let's proceed with the non-comprehensive guide...

Return to top

What is Munki?

Munki is a tool to deploy software out to Mac clients. You can force updates from the server or create optional software for clients to install themselves.

Return to top

What are the basic requirements for this setup?

  1. One Mac (OS X 10.8 or higher) that can act as a server (yes, you can actually run the server on Linux, Windows, etc., but again—the point of this tutorial is to get you up and running in at least one fashion and not to provide a comprehensive guide to all use cases).
    N.B.: you do not have to have OS X Server installed or have an actual Xserve machine. It can be any Mac that you want to repurpose as a Munki "server."
  2. At least one Mac that can act as a client (you will, supposedly, have many clients eventually).
  3. The latest Munki Tools release (this is the same installer for both the client and the server, but we'll tweak the installation slightly for the server).
  4. The latest MunkiAdmin release (not necessary for Munki operations in general but necessary for this tutorial).
  5. The latest AutoPkgr release (again, not necessary for Munki but extremely helpful).
  6. A working Internet connection... of course.

Return to top

Install on the server Mac the needed software

On the Mac that's going to be the server hosting the software, install all three downloads.

MunkiAdmin

munkiadmin Once you double-click the .dmg for MunkiAdmin, it's a simple drag-and-drop to the Applications folder (option to copy to Utilities instead, if you'd prefer).

AutoPkgr

autopkgr Double-click the .dmg for AutoPkgr and then drag and drop that to the Applications folder.

Munki Tools

Munki Tools has more of a wizard-style installer.

munkis01 Click Continue.

munkis02 You probably have only one drive you want to install to, but if you have two or more, pick the one you want, and then click Continue.

munkis03 For the server, click Customize.

munkis04 Uncheck Managed Software Center and Munki launchd agents, and make sure Munki core tools and Munki admin tools are checked.

munki11b Authenticate with an admin username and password. Then click Install Software.

munkis06 Click Close.

Return to top

Prepare the server to be a Munki software repository.

The standard in all the guides is to put the Munki repository in the shared users folder and then create a symlink to the web server directory (the equivalent of /var/www or /var/www/html for you Linux geeks out there). For consistency's sake, we'll keep that standard here, but if you're dedicating this machine to being a Munki repository, there isn't any reason you couldn't just make the repository directly (not just symlinked) in the web server directory.

We're still on the server Mac (until further notice).

Open up the Terminal.app (you can find it in /Applications/Utilities or search for it with Spotlight).

Then, paste in these commands:

cd /Users/Shared
mkdir -p munki_repo/catalogs
mkdir munki_repo/manifests
mkdir munki_repo/pkgs
mkdir munki_repo/pkgsinfo
mkdir munki_repo/icons
chmod -R a+rX munki_repo
sudo ln -s /Users/Shared/munki_repo /Library/WebServer/Documents/
sudo apachectl start

To sum up (in case you don't speak bash), we just created a directory and a few subdirectories for Munki business, made sure the proper permissions on that directory are in place, made a symlink to that directory from the web server directory, and then started up the Apache web service.

Note: If you're using OS X Server, the path is slightly different—more details at Setting Up Munki With OS X Yosemite Server.

You may also want to configure munkiimport:

/usr/local/munki/munkiimport --configure
It will ask you some questions. For the path to the Munki repo, put in /Users/Shared/munki_repo, since that's where we just created the Munki repository location.

For the repo fileshare URL, leave it blank. The rest you can decide for yourself or just stick with the defaults by hitting Return/Enter instead of typing something in. (Personally, I prefer a .plist extension and TextWrangler.)

Return to top

Use MunkiAdmin to set up your repositories, catalogs, and manifests.

Launch up MunkiAdmin (you installed this earlier).

munki07
When it launches up the first time, it'll immediately prompt you to Select a munki Repository. Go ahead and navigate to the /Users/Shared/munki_repo directory and then click Open.

Once you do that, it should be fairly empty, that's because all you have are the empty directories you'd created earlier.

You may want to make it so that MunkiAdmin remembers your repository instead of asking you every time at startup which repository you want to use.

munki07a Go to MunkiAdmin > Preferences....

munki07b Then, next to On Startup, select Open previous repository.

munki07c Once that's selected, you can close the Preferences window.

munki08 Go to File > New Catalog. The catalogs are general lists of what software is available in the repository—a sort of table of contents.

munki09 Call your new catalog production.

I'd also recommend creating a testing catalog. That's what most AutoPkg recipes will default to, and it's a good idea in general to have a set of testing clients install updates or new packages before you move the packages into production.

munki10 Go to File > New Manifest. Manifests pick out of the larger catalog(s) and then select software available to certain users. Each machine should have its own individual manifest, but each individual manifest can also include other manifests.

munki11b Call your new manifest the serial number of your test machine.

Note: Why the serial number? I explain more about this in Another opinionated guide to Munki manifests.

Return to top

Import software into your repository manually

One way to get software into your repository is manually—you download Firefox, for example, and it comes as a .dmg file.

munki12
In (still) MunkiAdmin (still on the server Mac), go to File > Import Items.

munki13 Find your .dmg file and open it.

munki14 Save it, when prompted.

munki15 You may see a dialogue pop up that says Status: Running makepkginfo.

munki16 When prompted to save, save again.

Note: With a lot of basic packages, it's fine to import it this way using MunkiAdmin. I've found that some packages import better using the command line (e.g., Adobe Creative Suite), so you may—after you get the swing of the point-and-click way—want to try using munkiimport at the command line instead).

munki17 If you go to catalogs (Cmd-2), you'll see your production catalog. If you click on production, you should see your one imported package there unchecked. If you want to include that package in your catalog, check (or tick) the box next to it. Then click the Save button above it.

munki18b Same deal if you go to manifests (Cmd-3), you'll see your serial number manifest that's empty.

You'll also see some different categories within the manifest. Managed Installs is for software you want definitely installed (Managed Uninstalls is for software you want definitely removed). Managed Updates are for software you definitely want updated (whether originally installed through Munki or not). Optional Installs are items you want the clients to have the option to add or remove. Click on the category you want to add the package to.

munki19 If you click the + (plus sign) near the bottom, you can now select the package you'd previously added to your catalog.

munki20b Again, click the Save button to save your changes.

Return to top

Figure out your server Mac's IP address

Here are four ways to do that. I'd recommend

ifconfig

in the Terminal.app as the quickest method.

Make a note of the IP address. We'll need that later for the Munki client(s).

Note: if you are on a domain, you can also use your server Mac's host name to reference it instead of using the IP address (e.g., munki.yourorganization.edu).

That's it for the server side (for now... until we come back for AutoPkgr).

Return to top

Set up the Munki client

As I mentioned before, Munki Tools is the same setup package, whether you're on the server Mac or the client Mac.

munkis07 So for the client Mac, just install those tools (you don't need the Munki admin tools here). This time, however, you will have to reboot immediately after installation.

Then, in the Terminal.app, put in your own version of this command:

sudo defaults write /Library/Preferences/ManagedInstalls SoftwareRepoURL "http://192.168.1.50/munki_repo"

where 192.168.1.50 is whatever your actual IP address is for the server Mac. For the sake of this demo, we're using http, but you may want to check out Using Munki With SSL Client Certificates or Using Basic Authentication for details on using https instead.

The Munki client should check in with the server every hour or so (not exactly an hour—there's a random bit of time tacked on so if you have a bunch of clients checking in at once, they're not clobbering the server together).

managedsoftwarecenter But you can also manually check for updates by going to Managed Software Center (in your Applications folder).

Return to top

Set up AutoPkgr

As we saw with the Firefox example above, you can manually import packages. There are, however, repositories for software that's pre-packaged and ready to work with Munki. These AutoPkgr repositories of cooked "recipes" can be especially helpful, for example, if you want to automatically push out updates to Flash and Java, and you don't want to deal with the promotion-ware Adobe and Oracle sometimes include in the installer.

You should already have AutoPkgr installed from a previous step, but here's a handy link in case you need to install it on your server Mac right now.

autopkgr01 When you launch up AutoPkgr the first time, you may be prompted for your password a couple of times. Go ahead and authenticate.

Once it's launched, it will have little red dots letting you know Git and AutoPkg are not installed. Go ahead and start with clicking Install Git.

autopkgr03 You'll see it download Git and then start installing Git. At a certain point, it may prompt you for your password. Go ahead and authenticate.

autopkgr04 Then click the Install AutoPkg.

autopkgr05 Same deal. Let it download and try to install. Authenticate, when prompted.

autopkgr07 Once they're both installed, you may want to change the other settings below. I like to check Launch AutoPkgr at login, for example. You may or may not want to hide in the Dock—your choice.

autopkgr08 There are a bunch of recipe repositories. If you're unsure where to start, just check the first one, and it will give you a good, basic selection of software. Obviously, the more repositories you check, the more software recipes you'll have available to you.

For this example, we're going to get the Oracle Java 8 package. For our purposes starting out, you'll need to check only the .munki recipes. You can leave the .download, .install, and .pkg recipes alone. Start by creating an override. Overrides allow you to specify other options without touching the original recipe, but they're also important for security (more on that later). autopkgr09a Then, go ahead and check the box next to your override.

Then, skip over Schedule for now, and go straight to Folders & Integration.

autopkgr11 AutoPkgr will just use what's grayed out, but if you want to change any of these directories for the integration piece, you may want to click Choose.

autopkgr12 Then you can choose your Munki repo.

autopkgr13 You'll see it's essentially the same except in black instead of gray.

Then go ahead and go to Schedule.

autopkgr14 Check both Run AutoPkg every 24 hours and Check for repo updates before each AutoPkg run.

N.B.: Please make sure you read AutoPkg and recipe parent trust info to get more information on a workflow for auditing changes to recipes.

autopkgr15 autopkgr16 It will run automatically in the background, but this first time, you may want to manually run both processes. Again, there may be a password authentication. Just roll with it.

autopkgr17 If everything worked, you should return to MunkiAdmin and see your OracleJava8 package in your Munki repo, ready to be added to a catalog and to a manifest (if you don't, click Reload).

Acknowledgements

Special thanks to Munki creator Greg Neagle for creating Munki but also for having a look this page and suggesting a couple of minor tweaks. Thanks also to the open source community surrounding Munki, AutoPkg, and another fun Mac-admin tools.

26 thoughts on “Absolute beginner’s guide to setting up 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!

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

    1. 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 “http://192.168.1.50/munki_repo”

    made it work for me.

    I got hung up here for the longest time.

    Thank you again for putting this together!

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

    1. 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?

    1. 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:
      https://github.com/autopkg/recipes/blob/master/munkitools/munkitools2.munki.recipe

      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
    chad

Leave a Reply

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