Module Overview

MunkiReport is built around modules. You should consider a module as a self contained unit that is responsible for collecting data, processing data and storing data in the database. Modules have an API to retrieve the collected data and present it.

Installation

Built in modules are now found in the ./vendor/munkireport folder. The Zip Archive will include all modules available for that release.

Git Modules

If you are utilizing Git for installation and updates, the actual modules for MunkiReport are dependencies for the main MunkiReport project. MunkiReport relies on the PHP dependecy manager Composer to install/update modules. Modules are stored within their own repo like https://github.com/munkireport/supported_os. These repos have been connected to the main Composer repository, Packagist, and when a new release is made on GitHub, Packagist updates the Composer repo and new modules can be updated by running composer update.

Common Composer commands:

composer update --no-dev
    # update all dependencies to latest with no dev dependencies.
composer install --no-dev --no-suggest --optimize-autoloader
    # install any dependencies if they aren't already installed
composer dumpautoload --optimize --no-dev
    # dump the composer cache and rebuild

If you don't use AD, you can choose to ignore the platform reqs with:

composer update --no-dev --no-suggest --ignore-platform-reqs

Adding Custom Modules

Modules can be created or sourced from outside of the standard MunkiReport modules.

Manually

To manually add a custom module, download the files of the module and copy the folder into the local/modules directory on the server.

Using Composer

If a module is in Packagist, you can add the module with composer either by creating composer.local.json with the required modules and running composer, or by having composer automatically create and update composer.local.json by running:

COMPOSER=composer.local.json composer require joncrain/manifests:^1.4

(substituting joncrain/manifests:^1.4 with the module and version you'd like to add). With either method you should end up with a composer.local.json file that looks similar to the following:

{
    "require": {
        "joncrain/manifests": "^1.4",
        "tuxudo/icloud": "^1.0"
    }
}

After you run composer update --no-dev the module will automatically download into the vendor directory into a directory of the namespace of the module. In the case above, joncrain and tuxudo are the namespaces. Your vendor directory should now have these folders in them (among other MunkiReport dependencies):

└──vendor
    └── joncrain
    └── munkireport
    └── tuxudo

Setting Module Search Paths

Note that the local/modules directory is included by default in the MODULE_SEARCH_PATHS. If modules are stored in this directory, you do not need to add anything to the search path.

Once a custom module is on the server, the parent directory for the modules must be included in the .env file as MODULE_SEARCH_PATHS. Multiple custom modules can be included in this directory. For example, to include custom module 1 and 2 below, MODULE_SEARCH_PATHS=/custom/modules must be included in the .env file. You will then need to add any custom modules to the MODULES array in your .env file.

Remember that this needs to include the full path, not just the path from the MunkiReport root!

custom
└──modules
    └── custom_module_1
    └── custom_module_2

Configuration

Module configuration is controlled by the .env file. Settings that affect modules are as follows:

MODULES='munkireport, managedinstalls, disk_report' 
    # comma separated list of modules to enable
HIDE_INACTIVE_MODULES=TRUE 
    # When false, all modules will be shown in the 
    # interface like in the 'Listings' menu.
MODULE_SEARCH_PATHS="/full/path/to/custom/vendor/tuxudo/, /full/path/to/custom/folder_of_modules/" 
    # used to add custom modules

Client side setup

MunkiReport includes 3 example reporting modules: munkireport, managedinstalls and disk_report. If you add other modules and wish to continue using these modules, you will need to include them in your .env file as well.

If you would like to see all available modules for your installation, visit:

http://example.com/index.php?/install/dump_modules/env

Paste the resulting MODULES="..." in your .env file. Remove items that you don't need reporting on from the array (e.g. servermetrics and service only make sense when installed on a client that runs Mac OS X server).

Then you can create a package as described here and distribute that to your clients.

Note: If you later decide to add/remove modules post client install, you will need to redistribute the resultant MunkiReport package created for your clients through your preferred distribution method.

Note 2: If you've added any custom modules, they will appear at the beginning of the list.

Module Creation Overview

A script to create a basic module is included with MunkiReport in the build directory. A module can be created by running:

../build/addmodule.sh $module_name

For more information on this process check out this Module Creation Series