What I learned upgrading from MunkiReport 2 to MunkiReport 3

The setup for the old (version 2) MunkiReport was fairly simple. You essentially just downloaded the folder to your web server.

The setup for the new (version 3) MunkiReport has a bit more nuance to it. I had a lot of trouble setting it up, but thanks to some help from other Mac admins (special thanks to Rick Heil for getting me over the finish line), I was able to finally get it up and running.

Here are a few issues I ran into. Maybe if you're running into the same or similar issues, this list may help:

  • Ubuntu 16.04 doesn't have PHP 7.0.27 or higher, which the new version of MunkiReport requires, so I had to add it in with the appropriate PPA.
  • On a related note, once you add that PPA to your sources.list in Ubuntu, you get a whole ton of PHP versions available via apt: 7.0, 7.1, 7.2. It's best to make sure you have only version of PHP installed and remove all the rest. I'd recommend 7.2 at this point.
  • It's a good idea to start with the sqlite database just to eliminate MySQL connection issues as a possibility. That said, since the main MunkiReport 3 files don't live in the public-facing part of the web server, be especially mindful of this part of the wiki instructions: when using SQLite as backend (which is the default), check if the directory /app/db/ is writeable by the webserver.
  • If you're using AD or SAML authentication, move it up in the composer.json file from suggest to require and get rid of the description after the version number. For example, "adldap2/adldap2": "^8.0 Required for AD authentication" should change to "adldap2/adldap2": "^8.0" after being moved.
  • If you're running the composer command and get a [RuntimeException] The "--no-suggest" option does not exist. message, just ditch the --no-suggest part of the command.

No fix for “system_profiler hung; skipping SPApplicationsDataType query” error in MunkiReport

20 July, 2016 Update: None of those possible fixes actually fixed the issue. It's oddly just a handful of machines. Not sure why those machines in particular are throwing the error.

April 26, 2016 Update: Unfortunately, after doing extensive testing on this, it seems the problem just comes back, and for only certain machines. I'm going to see if these potential fixes work for my misbehaving client machines.

What's the problem?

For a while, I've been running into the issue of some clients erroring out with system_profiler hung; skipping SPApplicationsDataType query: fixsystemprofiler01 The error doesn't prevent Munki from running, but no matter how many times I would run Munki checks on those computers (whether scheduled checks or manual checks), the error would persist.

The solution to this error I found was rather simple, though: fixsystemprofiler02 Log into the client and then just run

system_profiler
manually and let it run fully (even if it hangs, let it hang until it resolves the hang). Once that's done, run /usr/local/munki/managedsoftwareupdate or launch up Managed Software Center, and the error should disappear.

Clearly when MunkiReport is running its scripts (preflight or postflight) Munki is running, it's allowing only a certain amount of time for the system_profiler command before considering it a timeout.

But there's something that actually is hanging it. I'm not sure if running the command on its own clears out some kind of cache that needs refreshing, and only one successful (not timed out) system_profiler clears that cache. I don't know what's going on there, but that fix worked for me. If you're seeing a hung system profiler in your MunkiReport, you may want to try running the command on its own. Subsequent Munki checks should be fine afterwards.

Using MySQL with MunkiReport

By default, MunkiReport uses its own embedded sqlite database, which apparently isn't as robust as MySQL (the sqlite website has more information on sqlite's appropriate uses and limitations). If you are extremely unfamiliar with MySQL databases, you may want to just stick with the default sqlite database until you are. I have a basic tutorial on how to set up MunkiReport with some sensible and relatively easy defaults.

I won't go step by step with how to configure MySQL, because there are a lot of intricacies and when you move off the default sqlite to MySQL, you'll likely have your own preferences for how you want to implement it.

That said, the following facts may help you if you are familiar with MySQL but aren't as familiar with MunkiReport:

  • This guide is handy for getting MySQL in general set up on macOS 10.12 (Sierra).
  • You do have to manually create a MySQL user and MySQL database (MunkiReport will create the tables).
  • Everything you need to configure MySQL is in the MunkiReport config.php file you copied from the original config_default.php. Simply uncomment the lines for MySQL and comment out the lines for sqlite.
  • Assuming you are installing the MySQL database to the same server as MunkiReport, all the values should be good, except you may want to change the dbname (default is munkireport), the pdo_user (default munki), and the pdo_pass (default munki) to whatever the database, username, and password is for your MySQL database.
  • You do actually have to still create the password hashes and usernames for MunkiReport admins and put them into the config.php file***. There is no user or user authentication table in the MySQL database.
  • Even though you've copied and customized the config.php, deleting the original config_default.php file will break MunkiReport. Leave that file alone.
  • While you can migrate your sqlite data to MySQL, there probably isn't a need. Once your Munki clients check in on their own, the database will pretty much re-create itself.

*** Another alternative is to use LDAP or Active Directory authentication. You can find more details about that in the comments of the config_default.php file.

Installing MunkiReport

What is MunkiReport

MunkiReport is a web-based reporting interface for Munki clients. It's cool to deploy a bunch of Munki clients, but it'd be nice to know how many are out there, and any errors or pending installs there may be on those clients.

If you haven't set up your Munki server yet, do that first!

Assumptions (for simplicity's sake)

There are many different possible scenarios for installing MunkiReport, but for simplicity's sake, we're going to make some assumptions. If you're really advanced, you can obviously adapt these instructions for your particular case. If not, follow as is.

  • You are using a Mac computer as a server.
  • You installed munki_repo to a subdirectory of the server directory.
  • You are going to install MunkiReport to the root directory of your web server.
  • You are going to do all of these instructions from your web server (and not from a client computer).

Making sure the web server is PHP-ready

Apparently, Mac OS X by default does not interpret PHP correctly when you launch up the Apache service. So let's make sure that's good first.

In the Terminal.app, edit the appropriate file using nano (or your editor of choice)

sudo nano -B /etc/apache2/httpd.conf
If you see a line that looks like this:
#LoadModule php5_module libexec/apache2/libphp5.so
change it to look like this instead
LoadModule php5_module libexec/apache2/libphp5.so
Then save out (if you're using nano, Control-X we save).

Then restart apache

sudo apachectl restart

A) Downloading MunkiReport with Git

If you have Git installed, you can do a git clone on MunkiReport.

cd ~/Downloads
git clone https://github.com/munkireport/munkireport-php.git munkireport-php-master

B) Downloading MunkiReport with a web browser

Using a web browser on the web server itself, go to the MunkiReport GitHub repository and click the Download ZIP button to download the latest version. When you get the .zip file, you may have to double-click it to unzip it. Once it's unzipped, you should have a folder with all the necessary files in it.

Installing MunkiReport

Copy the contents of the folder (not the folder itself) to your web server's root directory. Make sure the file ownership/permissions match that of the other files or folders in there (e.g., whatever index.html file says It works! when you first got your web server up and running.

If you no idea, then make it all 755 permissions with ownership of root:_www.

Here's an example to paste into the Terminal.app:

sudo chown -R root:_www ~/Downloads/munkireport-php-master/*
sudo chmod -R 775 ~/Downloads/munkireport-php-master/*
sudo mkdir -p /Library/WebServer/Documents/munkireport
sudo mv ~/Downloads/munkireport-php-master/* /Library/WebServer/Documents/munkireport/
sudo cp /Library/WebServer/Documents/munkireport/config_default.php /Library/WebServer/Documents/munkireport/config.php
The last command just makes a copy of the default config to a new custom config file. You will need both (I thought, at first, that I could ditch the default config file, but then I got an error when I loaded up the page in a browser).

Note: If you're using OS X Server, the path is typically /Library/Server/Web/Data/Sites/Default and not /Library/WebServer/Documents

munkireport01
If all went well, you should be able to go to http://localhost/munkireport and enter a first username and password. This doesn't actually create a user. All it does is create a hash.

munkireport02
Once you have the password hash created, highlight the results and then paste them in at the end of the config.php file on the web server. If you ever need to generate another hash again, go to http://localhost/index.php?/auth/generate and enter in more credentials.

When you do log in, you should see... nothing. No clients.

To create a client, paste these commands into the Terminal.app

bash -c "$(curl http://nameofyourdomain/munkireport/index.php?/install)" bash -i ~/Desktop
/usr/local/munki/munkiimport ~/Desktop/munkireport-2.11.0.pkg
Replace nameofyourdomain with your actual domain name or the server's IP address.

Note: if you're using https with a self-signed certificate, you may want to run

bash -c "$(curl -k https://nameofyourdomain/munkireport/index.php?/install)" bash -i ~/Desktop
instead of the first command.

Note: the version number may change, so after you type ~/Desktop/munkireport-, just hit Tab to autocomplete, instead of typing in the number (it's faster to autocomplete anyway).

Once you have that package imported, and have rebuilt your Munki catalogs when prompted, go ahead and them to the appropriate manifests so they can be pushed out to your existing clients.

If you are well-versed in MySQL and prefer that to MunkiReport's default sqlite database, read Using MySQL with MunkiReport for some implementation tips.