Munki: Getting Started
Let's get started with setting up a very basic Munki implementation. These instructions will work either on your Mac workstation with Web Sharing enabled or on OS X Server, the difference being where the web root is located.
Download and install Munki
https://code.google.com/p/munki/downloads/list
Enable Web Server
OS X
- System Preferences > Sharing > Web Sharing
OS X Server
- Launch /Applications/Server/Server Admin.app
- Login to your OS X Server
- Click + in lower left > Add Service > Web
Creating the Repository
While you can name your repository whatever you like, the subdirectories must be named as covered in Munki: Basics. For this guide, I'll be referring to the repository created in this step as munki_repo. Open Terminal and cd to your document root. Alternately, users setting this up on their workstation can create the repo in /Users/Shared/ and then symlink to the document root.
cd /Library/WebServer/Documents/
Create your repository and name it as desired.
mkdir munki_repo
Then populate it with the required subdirectories
cd /munki_repo && mkdir catalogs manifests pkgs pkgsinfo
Now set the permissions on the repository. You'll want to ensure anyone can read and execute the content.
chmod -R a+rX ../munki_repo
Congrats. You've just created your munki repository. I suggest sharing your repository with AFP or SMB if you're setting this up on a server.
Populate your Repository
For brevity, I am going to cover Firefox as the example since it's very common and works out of the box with the vendors Disk Image.
Download Firefox: https://www.mozilla.com/en-US/products/download.html
You can manage your repo manually or with the munkiimport tool. Using muniimport is very easy and saves time so I'll briefly cover both.
Munkiimport
You'll need to first configure munkiimport before using.
/usr/local/munki/munkiimport --configure
The out put will look something like this. These are my very quick choices for a demo. Please use your own settings accordingly. You can always reconfigure as your munki evolves.
Path to munki repo (example: /Volumes/repo) [None]: /Library/WebServer/Documents/munki_repo
Repo fileshare URL (example: afp://munki.pretendco.com/repo) [None]:
pkginfo extension (Example: .plist) [None]: pkginfo
pkginfo editor (examples: /usr/bin/vi or TextMate.app) [None]: TextWrangler.app
With munkiimport configured, it's time to use it to populate our repository.
/usr/local/munki/munkiimport ~/Desktop/Firefox\ X.dmg
Follow the prompts and change accordingly. For this brief demo, the detected settings are fine.
Item name [Firefox]:
Display name []:
Description ll:
Version [4.0.1]:
Catalogs [testing]:
Import this item? [y/n] y
Upload item to subdirectory path ll:
Copying Firefox 4.0.1.dmg to /Library/WebServer/Documents/munki_repo/pkgs/Firefox X.dmg...
Saving pkginfo to /Library/WebServer/Documents/munki_repolpkgsinfo/Firefox X.pkginfo...
Rebuild catalogs? [y/n] y
Adding Firefox X.pkginfo to testing...
munkiimport does more, too! It will take a .pkg and wrap it in a dmg so you don't have to take the extra steps. This is especially helpful for things like Opera that launch a EULA at mount. Now, you just mount it and point munkiimport at the .pkg instead of like the .dmg above.
Manually
Copy the Firefox disk image to your Munki Repository. At this point, this is where it's easier to have your repository shared with AFP or SMB if you're using a separate server for your repository. If you're hosting it locally, just drag the Firefox disk image to your /munki_repo/pkgs/ directory. It's a "best practice" to organize your repository by type and vendor.
Generate pkgsinfo
Here you'll need to use the makepkginfo tool to generate a pkgsinfo file. In Terminal, you'll run the tool from /usr/local/munki at the Firefox you just put into pkgs/ and redirect the output to pkgsinfo/. It's advised to use the same name for the pkgsinfo as the package itself. Also, you can add a file extension to make it more easily identifiable. Here's an example.
/usr/local/munki/makepkgsinfo /munki_repo/pkgs/Firefox\ X.dmg > /munki_repo/pkgsinfo/Firefox\ X.pkginfo
Generate catalogs
Here you'll need to use the makecatalogs tool to generate a catalog.
/usr/local/munki/makecatalogs /munki_repo
Create Manifest
Now we need to create a manifest. You can use the following barebones template for now. For more Keys and information, please check out the official Munki docs at: https://code.google.com/p/munki/source/browse/trunk/manifest%20examples/sample
You can copy and paste the following into a text editor and save it as testing. Either save or move to your /munki_repo/manifests. The catalogs key is where you specify the catalog that this manifest is using. In this case, we're using the testing catalog that we just created in an earlier step. The managed_installs key is where we specify the installer item we're deploying. managed_uninstalls is where you would specify software to remove. For more information and available keys, see the official Munki sample linked above.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>catalogs</key>
<array>
<string>testing</string>
</array>
<key>managed_installs</key>
<array>
<string>Firefox</string>
</array>
<key>managed_uninstalls</key>
<array>
</array>
</dict>
</plist>
Almost done! You now have an operable Munki repository waiting to deploy software! All that we need to do now is configure our clients.
Configure Client
Clients use the /Library/Preferences/ManagedInstalls.plist for instructions. This file outlines Munki's behavior on the client. You may have multiple configurations deployed. Two good examples would be a lab management configuration and a workstation management configuration. Some settings are better suited to different environments. I highly suggest that once you have a working Munki, you see the official wiki pages for *many* more client configuration options. https://code.google.com/p/munki/wiki/configuration
You can copy and paste this sample ManagedInstalls.plist and make edits or just custom build your own. This is in XML format of course so depending on your comfort level, you may want to use an editor like Text Wrangler or even the Property List Editor in the Developer Tools. I'll assume you don't have either so we'll make our changes with the defaults command.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>ClientIdentifier</key>
<string>testing</string>
<key>DaysBetweenNotifications</key>
<integer>1</integer>
<key>InstallAppleSoftwareUpdates</key>
<false/>
<key>LogFile</key>
<string>/Library/Managed Installs/Logs/ManagedSoftwareUpdate.log</string>
<key>LoggingLevel</key>
<integer>1</integer>
<key>ManagedInstallDir</key>
<string>/Library/Managed Installs</string>
<key>SoftwareRepoURL</key>
<string>http://localhost/munki_repo</string>
<key>SuppressAutoInstall</key>
<false/>
<key>SuppressStopButtonOnInstall</key>
<false/>
<key>SuppressUserNotification</key>
<false/>
</dict>
</plist>
Set ClientIdentifier
The ClientIdentifier is the key that you'll use to associate a client with a manifest. In our case, we're using testing. A basic example is below.
defaults write /Library/Preferences/ManagedInstalls ClientIdentifier testing
Set SoftwareRepoURL
The SoftwareRepoURL is the key that tells the Munki tools where your repository is located. In this example, I am assuming you set it up locally and named it munki_repo. Modify the command if you're setting this up on a server or changed the repository name.
defaults write /Library/Preferences/ManagedInstalls SoftwareRepoURL http://localhost/munki_repo
Example Optional Keys
There are *many* optional keys. I want to cover 2 basic ones. Please see the Official Wiki for the latest keys and information. https://code.google.com/p/munki/wiki/configuration
InstallAppleSoftwareUpdates
This example would enable Munki to handle your Apple Software Updates instead of Apple's built-in Software Update
defaults write /Library/Preferences/ManagedInstalls InstallAppleSoftwareUpdates -bool YES
SuppressUserNotification
This example would allow you to disable notifying the user of available updates. This might be ideal for lab environments where you don't want the user to be disturbed with prompts.
defaults write /Library/Preferences/ManagedInstalls SuppressUserNotification -bool YES
Congratulations are in order! You've just setup Munki! You can now start tailoring your implementation to see what works for you in your environment. There are a lot of great resources out there. Please check out the last page in this guide for helpful links in getting the most of your Munki.