How to set up Munki on macOS Server to manage your Apple computers

Image: Poravute, Getty Images

Mac management can be a dicey proposition for many organizations. While first-party tools often do an admirable job of handling the common management tasks, tools that provide real insight into the daily workings of these devices typically come from third-party developers and usually require pricey licensing fees.

More about Apple

While all tools—first and third party alike—have their pros and cons, support plays a big role in their on-going use. This is especially true for organizations that do not have engineers that specialize in Apple products, which forces them to rely on these support plans for help when things don't go as planned.

That said, powerful open-source tools like Munki, the systems administration tool with robust software management capabilities and a strong user support community can be installed, configured, and run on macOS to manage all the Apple computers in the enterprise—no matter how large or small. After all, Munki was developed by Walt Disney Animation Studios to aide in the management of the thousands of Macs they use daily when working on everything from animated shorts to feature films.

SEE: System update policy template download (Tech Pro Research)

Best of all, Munki only relies on Apple software packages, read and write permissions for shared deployment directories, and a web server to deliver the packages to client computers. And in this article, the steps necessary to setup Munki on macOS Server will be outlined.

However, before we jump in, there are a few requirements necessary to ensure that Munki can run properly:

• Apple computer running macOS Server 10.7 (Lion) -10.13 (High Sierra)
• Munki 3 package (latest v3.4.1, as of this writing)
• Google Chrome.dmg installer package
• Internet Access
• Switched Network
• Admin credentials

Note: Munki 3 supports macOS 10.14 (Mojave), however, due to changes made by Apple in this version, the setup process for Munki running natively on macOS Mojave is different from prior versions. A future article will include the steps to setup Munki on macOS Mojave without the macOS Server component.

Creating the Munki repository

Log in to the computer with admin credentials. Launch macOS Server and ensure the Websites service is initially configured (Figure A).

Figure A

If not present, launch Terminal and enter the command below to start the web server (Figure B).

Figure B

sudo serveradmin start web

Go back to the Server.app, and Websites should now appear under Services and should be turned on (Figure C).

Figure C

Go back to Terminal and enter the following commands to change the directory to the root location that will be used to create the directory structure for the Munki repository. When naming the repository, the word "repo" was used in the example, but it can be named to anything you wish (Figure D).

Figure D

cd /Library/Server/Web/Data/Sites/Default
mkdir repo
mkdir repo/catalogs
mkdir repo/pkgs
mkdir repo/pkgsinfo
mkdir repo/manifests

The final command below, when run, will change the permissions to assure that it's accessible.

chmod -R a+rX /Library/Server/Web/Data/Sites/Default/repo

Configuring the web server settings

1. With the repository created, switch back to the Websites section in Server.app. Click the Server Website/Port 80 entry to highlight it, then click the pencil button to edit the settings.
2. Next to Redirects, click the Edit...button and delete the single entry the redirects port 80 traffic to port 443, then click OK. Munki can sometimes have trouble redirecting traffic that causes it to fail to process certain files, so it's best to remove redirection altogether, for now.
3. After saving the settings, you'll be brought back to the previous section. Click the Edit Advanced Settings... button, and check the box next to Allow folder listing, then click OK to save. This will come in handy later when verifying that Munki was configured properly.
4. To test the web server's configuration, open a web browser and enter http://localhost/repo as the URL. If you can see the directory index, the repository is setup correctly (Figure E).

Figure E

5. Lastly, the following command will create a symbolic link to the Munki repository in the macOS web server that allows it to serve the repo's content (Figure F).

Figure F

sudo ln -s /Library/Server/Web/Data/Sites/Default/repo /Library/WebServer/Documents

Installing Munki tools

Execute the Munki Tools package and follow the prompts to complete the install (Figure G).

Figure G

By clicking on the Customize button, the individual tools that make up the package may be selected (or deselected) for installation. For the admin workstation setup, installing all the tools has its advantages. Click the Install button to complete the installation (Figure H).

Figure H

A reboot will be required once Munki Tools is installed (Figure I).

Figure I

Configuring the Munki repository

After rebooting, launch Terminal and enter the following command to change directories and configure the Munki repository's settings (Figure J).

Figure J

cd /usr/local/munki
munkiimport --configure

The command will ask a series of questions in order to set the correct configuration. First up is to enter the Repo URL. Depending on how the repo will be hosted, the entry could change from either a locally hosted (ex. file:///path/to/repo), a shared drive (ex. smb://path/to/repo), or web hosted (ex. http://domain.com/path/to/repo). For the purpose of this article, we'll go with our file-hosted setup and enter the following:

file:///Library/Server/Web/Data/Sites/Default/repo

The second question is the ,pkginfo file's extension. These files contain configuration information for each package that is imported. While typically not edited, it could be, and you may find some packages do require some light editing to make them deploy silently. The most common extension is .plist, so we'll be entering that here.

Third, we are prompted to choose a default app to edit the configuration files. You can enter the path or name of any installed application you prefer. To keep things simple, I've chosen the built-in TextEdit.app native to macOS.

SEE: Comparison chart: Enterprise collaboration tools (Tech Pro Research)

Next, we must create a catalog to store the package information for Munki. The catalogs will be read by Munki and used to provide context as to what applications are available for deployment. You can enter any name you choose, and more than one catalog may exist. Here I've entered Default as the catalog name.

Last, a repo access plugin must be selected. Unless there is a preference, FileRepo is the default choice. You may leave the entry blank, and the system will automatically default to that plugin's configuration. The repository is now configured.

Importing the initial package

While we're almost done with the setup of Munki, we must have at least one package in the catalog before completing the process. To add the initial package, we'll be using Google Chrome as an example. From Terminal, enter the following command to get the process started (Figure K).

Figure K

munkiimport /path/to/googlechrome.dmg

Again, Munki will prompt for a series of information regarding the package being imported, such as Item Name, Display name, Description, etc. Some of this information will auto-populate, some will not. That which doesn't should be added manually. By observing Figure K above, most of the information is basic and does not impact Munki too much except the Catalogs section. Here you must enter the name of the catalog created in section IV above or else the package will not be linked to Munki for distribution.

Additionally, you will be asked whether to import the item or not. Select Y to import it, as well as creating product icons and rebuilding the catalog. This will update the catalog with the newly imported package. You may, however, select N to skip the editing of the pkginfo file as Google Chrome does not require any additional syntax to deploy it.

Note: Typically, drag-and-drop-style installs do not require editing of the .plist configuration file. Installer-based PKG files may sometimes require additional syntax or switches to be passed along to complete the install process. In those cases, you will need to edit the pkginfo file to manually add those parameters.

Configuring the repo's manifest

The manifest file in Munki acts as a sort of map that tells the repo where catalogs are located and therefor what is in those catalogs, allowing Munki to manage software deployments with ease. By default, no manifest exists so one must be created. In Terminal, enter the following command to begin (Figure L).

Figure L

manifestutil

Begin by creating the new manifest and giving it a name with this command:

new-manifest site_default

Next, we will link the catalog we created to the newly created manifest:

add-catalog Default --manifest site_default

Last step is to add the package created to the manifest:

add-pkg Chrome --manifest site_default

Munki has officially been installed, setup, and ready for use. To test web connectivity, launch a browser and enter http://localhost/repo/manifests/site_default. You should receive a confirmation of the entries add to the manifest above (Figure M).

Figure M

Alternatively, by entering the following command in Terminal to verify the software repo URL is configured correctly (Figure N).

Figure N

defaults read /Library/Preferences/ManagedInstalls

Lastly, to test how Munki works at retrieving the packages and installing them, call the command from Terminal (Figure O).

Figure O

sudo managedsoftwareupdate

The above command will read the information stored in the catalogs and identify what applications are available and ready to be installed when compared against the inventory on the local machine. To install these apps, rerun the same command, but add the "—installonly" suffix to actually perform the install (Figure P)

Figure P

Apple Weekly Newsletter

Whether you need iPhone and Mac tips or rundowns of enterprise-specific Apple news, we've got you covered. Delivered Tuesdays

Sign up today

Also see