How to create a module (advanced)

Modules are self-contained pieces of code that add functionality to munkireport without changing the core.

Anatomy of a module

A module is a directory that contains one ore more directories and files. Some of these have a special purpose. Let's take a look at the disk_report module (app/modules/disk_report) to see what is going on:

• disk_report
  • disk_report_controller.php
  • disk_report_model.php
  • scripts
    • disk_info
    • install.sh
    • uninstall.sh
  • README.md

Collect the data

Controller

<?php 

/**
 * Disk report controller class
 *
 * @package munkireport
 * @author AvB
 **/
class Disk_report_controller extends Module_controller
{
	function __construct()
	{
		$this->module_path = dirname(__FILE__);
	}

	/**
	 * Default method
	 *
	 * @author AvB
	 **/
	function index()
	{
		echo "You've loaded the disk report module!";
	}

} // END class Disk_report_controller

The controller file can be used to create/retrieve/update/delete data from munkireport. The controller file is named: <module_name>_controller.php. To access the controller you can visit http://your.munkireport.server/index.php?/module/<module_name>

If you don't specify anything after <module_name>, munkireport will load the default method called index.php

Security

You need to take care to protect your module_controller methods against unauthorised access.

Model

<?php
class Disk_report_model extends Model {

	function __construct($serial='')
	{
		parent::__construct('id', 'diskreport'); //primary key, tablename
		$this->rs['id'] = '';
		$this->rs['serial_number'] = $serial; $this->rt['serial_number'] = 'VARCHAR(255) UNIQUE';
		$this->rs['TotalSize'] = 0; $this->rt['TotalSize'] = 'BIGINT';
		$this->rs['FreeSpace'] = 0; $this->rt['FreeSpace'] = 'BIGINT';
		$this->rs['Percentage'] = 0;
		$this->rs['SMARTStatus'] = '';
		$this->rs['SolidState'] = 0;
		   
		
		// Create table if it does not exist
		$this->create_table();
		
		if ($serial)
			$this->retrieve_one('serial_number=?', $serial);
		
		$this->serial = $serial;
		  
	}
	
	// ------------------------------------------------------------------------

	/**
	 * Process data sent by postflight
	 *
	 * @param string data
	 * @author abn290
	 **/
	function process($plist)
	{		
		require_once(APP_PATH . 'lib/CFPropertyList/CFPropertyList.php');
		$parser = new CFPropertyList();
		$parser->parse($plist, CFPropertyList::FORMAT_XML);
		$mylist = $parser->toArray();

		// Calculate percentage
		if(isset($mylist['TotalSize']) && isset($mylist['FreeSpace']))
		{
			$mylist['Percentage'] = round(($mylist['TotalSize'] - $mylist['FreeSpace']) /
				$mylist['TotalSize'] * 100);
		}
		$this->merge($mylist)->save();
	}
}

A model is a representation of the data in the database. ...

install.sh

#!/bin/bash

# disk_report controller
DR_CTL="${BASEURL}index.php?/module/disk_report/"

# Get the scripts in the proper directories
"${CURL[@]}" "${DR_CTL}get_script/disk_info" -o "${MUNKIPATH}preflight.d/disk_info"

# Check exit status of curl
if [ $? = 0 ]; then
	# Make executable
	chmod a+x "${MUNKIPATH}preflight.d/disk_info"

	# Set preference to include this file in the preflight check
	setreportpref "disk_report" "${CACHEPATH}disk.plist"

else
	echo "Failed to download all required components!"
	rm -f "${MUNKIPATH}preflight.d/disk_info"
	ERR=1
fi

install.sh is included in the munkireport install script if this module is enabled. You can use install.sh to:

• put the files in place to collect the data that you need
• configure the client to send this data to the reporting server

As install.sh is included in the main install script, there are some variables available:

${MUNKIPATH} - contains the path to the munki directory (usually /usr/local/munki/)
${PREFPATH} - contains the path to the munkireport preferences file
${BASEURL} - the url to the reporting server, you need to add index.php? to this string
${CURL} - path to curl with some sane options

Uninstall.sh

#!/bin/bash

# Remove disk_info script
rm -f "${MUNKIPATH}preflight.d/disk_info"

# Remove disk.plist
rm -f "${MUNKIPATH}preflight.d/cache/disk.plist"

uninstall.sh is included in the munkireport install script if this module is disabled. You can use uninstall.sh to:

• Cleanup scripts and temporary files your module created on the client.