How to Upgrade Versions

This guide is meant to inform you of the changes that have occurred for each major version change. If you are upgrading from 2.x or 3.x, it is best to read through this document so that you are aware of what configuration settings will need to be updated. For instructions on performing the upgrade, please see the General Upgrade Procedures.

Version x.x -> 5.8.x

Mac Admins Python version 3.10 is required to be installed on each client computer.

Version 3.10 of Mac Admins Python can be found on this page: https://github.com/macadmins/python/releases/tag/v3.10.9.80716

Minimum version of PHP is now 8

Version x.x -> 5.7.x

MunkiReport Python2 is required to be installed on each client computer.

The latest release of MunkiReport Python2 can be found on this page: https://github.com/munkireport/MunkiReport-Python/releases

Minimum version of PHP is now 7.3

Version x.x -> 5.6.x

The database/migrate.php command has been replaced in favor of ./please migrate

Minimum version of PHP is now 7.2.5

Version x.x -> 5.5.x

The localadmin module is retired in favour of the more versatile users module. If you have localadmin enabled in .env, please replace with users.

Version 4.x -> 5.x

This release changes the way MunkiReport runs on the client. MunkiReport now has it's own launchDaemon, which means that it will no longer take up time when munki runs it's pre- and postflight scripts. The MunkiReport scripts have moved to /usr/local/munkireport MunkiReport log files are now found in /Library/MunkiReport/Logs/

To take advantage of the new scripts, create a new client package and distribute to your munki clients.

IMPORTANT

MunkiReport does not run scripts in /usr/local/munki/preflight.d, /usr/local/munki/postlight.d and /usr/local/munki/preflight_abort.d anymore! If you depended on these locations, please consider creating your own implementation for these. Also note that MunkiReport will not clean up the legacy directories.

Version 3.x -> 4.x

This release changes the entire configuration system to .env. This means that config.php and config_default.php are no longer in use. To aid in moving the old configuration to the new one, a migration script is available. To run the migration script use the terminal:

cd /path/to/munkireport
./build/config_to_env

There is a new directory called local that is used for user accounts, dashboards, certificates and module specific yaml files. The migration script will use those directories to store some of the converted items (users, certs, dashboard layouts). You can override the local directory location by setting

LOCAL_DIRECTORY_PATH="/path/to/local/directory/"

in your .env file. This allows you to keep your local configs separate from the MunkiReport files and optionally store them in your own versioning system.

Version 3.2.x -> 3.3

MunkiReport version 3.3 brings some major changes to module configuration.

Notable changes:

• Add module search path
• Modules are split off into separate repos
• Added composer-merge plugin (allows for local composer.json file)

If you have copied config_default.php previously, ensure that you at least update your config.php first line from:

<?php if ( ! defined( 'KISS' ) ) exit; to <?php
remove the line: $conf['module_path'] = APP_ROOT . "/vendor/munkireport/";

It has been common practice to copy config_default.php to config.php and to edit those things that need changed. This is no longer the case and can cause unintended consequences because of the changes to the way MunkiReport manages settings. Clear out any old default settings from config.php.

Module Directory Location

While the upgrade procedure for 3.3 remains the same, the location of all modules has moved from app/modules to vendor/munkireport. This directory is updated when the composer.json or composer.local.json files are updated and composer update is run.

Custom module location has also changed. There is no longer a custom folder by default and a module search path can be configured in the .env file to facilitate custom modules. Example:

MODULE_SEARCH_PATHS=/full/path/to/munkireport/custom-modules

Local Composer Settings

Starting with version 3, a composer file was created to manage the dependencies of the project. With 3.3, the modules are now a part of the dependencies which makes managing the composer file more important.

composer.json should now be considered the default values of the project and any alterations should begin to be placed in composer.local.json.

composer.local.json example:

{
    "require": {
        "adldap2/adldap2": "^8.0"
    }
}

To create this file and load into project, simply run the following command:

COMPOSER=composer.local.json composer require adldap2/adldap2:^8.0
composer dumpautoload --no-dev

Module installation overview:

A module creator can now create modules in a dedicated repo. To make them available with composer a packagist account must be created and linked to their GitHub account. Once linked, creating releases in the module will automatically create a package that can be installed in composer.local.json.

Example: https://packagist.org/packages/joncrain/manifests

COMPOSER=composer.local.json composer require joncrain/manifests:^1.0
composer dumpautoload --no-dev

Version 2.x -> 3.x

MunkiReport version 3 attempts to solve a couple of longstanding issues concerning security, dependency management and database management. We're moving slowly to using eloquent as replacement for the KISS database abstraction. A ton of work has been done by @mosen to make this all work.

Most notable changes are:

• Minimum PHP version is 7.0.27
• Document root is now in a directory called /public. The best practice is to serve your munkireport instance from this directory or make a symlink to this directory.
• If you install MunkiReport via git pull, you need to install all dependencies first via composer
• There is a new database configuration format $conf['connection']. See config_default.php on how to use it.
• Database migrations (also the initial ones) are not running automatically. You need to run migrations via the command line tool php database/migrate.php

To take advantage of these security changes see the following common scenarios when updating:

Apache on macOS

In-Place Upgrade

An In-Place upgrade will allow you to keep the existing URL structure you have today but incorporate the security changes. There is no need to adjust apache config changes with this method. Note: this method relies on .htaccess URL rewrites provided in the updated code to redirect traffic accordingly.

After following the instructions on General Upgrade Procedures to update the code, you can do the following:

1. Move the existing MunkiReport folder to a directory outside of the hosted webroot.

mv /var/www/webroot/munkireport-php /Volumes/SecureConnectedStorage/munkireport-php

2. Create a symlink of the munkireport-php public folder from the new location to the webroot location. Name the link the same as the folder name of munkireport-php when it was in the webroot.

ln -s /Volumes/SecureConnectedStorage/munkireport-php/public /var/www/webroot/munkireport-php

Install dependencies

MunkiReport version 3 uses a dependency manager called composer. Make sure you have composer installed in the munkireport-php directory before you proceed. Instructions on how to install composer can be found on the Composer Website. After you have installed composer on your system, run the following from the munkireport-php directory:

php composer install --no-dev --no-suggest --optimize-autoloader

This will download and install all the dependencies for MunkiReport in a vendor directory in munkireport-php and generate the autoload files.

Database configuration

MunkiReport V3 switches to the eloquent database framework. This framework needs a different db configuration than the previous PDO config. See config_default.php for examples like below:

SQLite

SQLite is configured by default. You can override the path to the database file:

$conf['connection'] = [
    'driver'    => 'sqlite',
    'database'  => 'path/to/db.sqlite',
];

MySQL

$conf['connection'] = [
    'driver'    => 'mysql',
    'host'      => 'your.mysql.hostname',
    'port'      => 3306,
    'database'  => 'munkireport',
    'username'  => 'munkireport_user',
    'password'  => 'munkireport_pass',
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'strict' => true,
    'engine' => 'InnoDB',
];

Migrate the database

The database migration method has changed in version 3. Previously, database changes would happen automatically when a client would upload new data or when accessing a view that needed changes in the web interface. That is no longer the case.

The config.php value to allow migrations ($conf['allow_migrations'] = TRUE;) is no longer respected and can be removed as of v3.

The admin must manually trigger a database migration. That can be done two ways:

• Run the migration script from the munkireport-php folder on the server via CLI

./please migrate

• In the web console access the Admin->Database menu and click the Update button.

Custom CSS and Javascript Overrides

If you have custom CSS or Javascript overrides in use there may be some configuration changes to make in config.php and the file structure. There are two options:

1. Place your custom files in a web accessible location, outside of the munkireport-php folder structure and change your configuration settings to access it directly:

$conf['custom_css'] = 'https://server.com/some/accessible/url/custom.css';
$conf['custom_js'] = 'https://server.com/some/accessible/url/custom.js';

2. Store the custom files in their current location or somewhere accessible the server and add a symlink to the files in the public folder. For this example say your custom files are stored in the directory munkireport-php/custom/

cd munkireport-php/public
ln -s ../custom/custom.css custom.css
ln -s ../custom/custom.js custom.js

The config.php setting in this instance would be the following since the symlinks are in the root of the public folder:

$conf['custom_css'] = '/custom.css';
$conf['custom_js'] = '/custom.js';

Known Errors

When updating from v2.x, there is a change of the ARD table column names. The migration currently does not seem to fix the issue. The old column names are "Text1" (through h4) and the new column names are "text1". We have seen issues with the newer MunkiReport versions not pulling in these columns correctly.