Munki supports middleware modules that can alter an HTTP(S) request to work with servers (often cloud-based) that require specific headers, keys, or encrypted/signed requests.

Middleware for Munki 7 must be implemented as a loadable dylib.

Several popular middleware modules have been ported to Swift using Munki 7's middleware protocol, and are believed to work:

• https://github.com/munki/DemoMiddleware (this one does nothing useful other than to demonstrate how a middleware module has access to the request details)
• https://github.com/munki/AzureStorageMiddleware
• https://github.com/munki/BunnyNetMiddleware
• https://github.com/munki/CloudFrontMiddleware
• https://github.com/munki/GCSMiddleware
• https://github.com/munki/S3Middleware

Though these ported middleware modules are believed to work, they are not officially supported at this time. My preference would be for others who actually use the modules to take over development, support, and maintenance.

Middleware modules must be installed in a /usr/local/munki/middleware directory. Only a single module will be loaded, so only a single middleware module should be installed in that directory.

This optional feature, introduced in Munki 2.7, allows a Munki admin to use third party code, or create their own code to manipulate Munki's HTTP requests. The primary use case for this feature is to provide interaction with APIs, although it is not limited to that. Middleware is activated by the presence of a Python file. If it's there it gets called, if it's not it won't, it's as simple as that.

Middleware gets imported at runtime as a Python module so the middleware file must be written in Python. Nothing is stopping you from then calling another executable from Python, so in that sense, you're not limited to Python. At the beginning of the Munki run, Munki searches for "middleware*.py", it then tries to import it then looks for the function, "process_request_options". The options are then sent through, examined, changed, or not, before heading to the server.

You may only use one middleware file. If you have more then one of middleware file you will have unpredictable results.

For the middleware to work, you will need the following:

Munki is looking for files the start with "middleware" and end with ".py". Examples of good and bad middleware filenames:

• middleware.py👍
• middleware👎
• my_middleware.py👎
• middleware_cloudfoo.py👍

The middleware file must live in the root of the munkitools folder (/usr/local/munki).

Root must be the owner of the file and be able to read it. Since its imported by python, the executable part isn't necessary. It's important to note that if you plan on storing sensitive information inside you should restrict access.

sudo chown root /usr/local/munki/middleware*.py
sudo chmod 600 /usr/local/munki/middleware*.py

This is the function that Munki is looking for. Think of it as the "main" fuction for the middleware. If Munki doesn't find this function it will abandon the middleware, and continue on as if it wasn't there.

Example function

def process_request_options(options):
   print('***Requesting: %s' % options.get('url'))
   return options

This is a basic example: Munki sends the request options, we print the requested url and then return the options unchanged.

process_request_options has a single input parameter: the options dictionary (described in detail below). It must return the options dictionary (possibly modified).

Query Params Example

from urllib import urlencode

QUERY_PARAMS = {"username": "apiuser", "password": "secret password"}


def encode_params(data):
    """Encode parameters in a piece of data.
    Will successfully encode parameters when passed as a dict or a list of
    2-tuples. Order is retained if data is a list of 2-tuples but arbitrary
    if parameters are supplied as a dict.
    """
    result = []

    for k, vs in QUERY_PARAMS.items():
        if isinstance(vs, basestring) or not hasattr(vs, "__iter__"):
            vs = [vs]
        for v in vs:
            if v is not None:
                result.append(
                    (
                        k.encode("utf-8") if isinstance(k, str) else k,
                        v.encode("utf-8") if isinstance(v, str) else v,
                    )
                )
    return urlencode(result, doseq=True)


def process_request_options(options):
    url = options.get("url")
    if "swscan.apple.com" not in url:
        print("URL Before: %s" % options.get("url"))
        # concat url and query string
        options["url"] = options["url"] + "?" + encode_params(QUERY_PARAMS)
        print("URL After: %s" % options.get("url"))
    return options

In the example above we are joining the URL from Munki and query string together.

http://munki.example.com/catalogs/production

http://munki.example.com/catalogs/production?username=apiuser&password=secret+password

Headers Example

HEADERS = {"api_key": "123_IAM_A_KEY", "api_secret": "SECRETKEY"}


def process_request_options(options):
    url = options.get("url")
    if "swscan.apple.com" not in url:
        print("Headers before: %s" % options["additional_headers"])
        # Merge headers with Munki
        options["additional_headers"].update(HEADERS)
        print("Headers after: %s" % options["additional_headers"])
    return options

Since the 'additional_headers' key is a dictionary it is easy for us to update retaining the User-Agent and Authorization headers.

{u'Authorization': u'Basic bXVua2k6WUhuUXhWWFFh==', 'User-Agent': u'managedsoftwareupdate/2.6.1 Darwin/15.4.0'}

{'api_secret': 'SECRETKEY', 'api_key': '123_IAM_A_KEY', u'Authorization': u'Basic bXVua2k6WUhuUXhWWFFh==', 'User-Agent': u'managedsoftwareupdate/2.6.1 Darwin/15.4.0'}

These are all the options that can be changed with the middleware. Most of the time you'll only be interested in the url and the additional_headers

Here are some middleware modules to try: