Details on Munki's preferences

Munki stores its configuration info in the "ManagedInstalls" preferences domain. By default, this info is stored in /Library/Preferences/ManagedInstalls.plist, but you can also use MCX, configuration profiles, or /private/var/root/Library/Preferences/ManagedInstalls.plist, or a combination of these locations with the normal defaults precedence:

• MCX/Configuration profiles
• /private/var/root/Library/Preferences/ByHost/ManagedInstalls.XXXXXX.plist
• /private/var/root/Library/Preferences/ManagedInstalls.plist
• /Library/Preferences/ManagedInstalls.plist

Munki 3.1 new feature

managedsoftwareupdate has a new --show-config option, which will print Munki's current configuration. This can be helpful when troubleshooting the potentially confusing interaction between different preference levels and managed preferences.

Here's a sample /Library/Preferences/ManagedInstalls.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>ClientIdentifier</key>
    <string>arbitrary_name</string>
    <key>SoftwareRepoURL</key>
    <string>http://munkiwebserver/repo</string>
    <key>LoggingLevel</key>
    <integer>1</integer>
    <key>DaysBetweenNotifications</key>
    <integer>1</integer>
</dict>
</plist>

(Scroll the table horizontally to see all columns -- GitHub's default view tends to hide the last column, which contains a description of the key.)

Munki normally writes its logs to /Library/Managed Installs/Logs/, with the main log written to ManagedSoftwareUpdate.log in that directory. Other logs are named "Install.log", "errors.log", and "warnings.log". If you'd like the logs to be written somewhere else (for example /var/log or /Library/Logs), set LogFile to the desired pathname of the main log:

sudo defaults write /Library/Preferences/ManagedInstalls LogFile "/var/log/munki/managedsoftwareupdate.log"

The other logs will be written to the same directory.

If this key is present and set to True, Munki will call softwareupdate and attempt to install Apple Software Updates.

This key can be used to point to an internal Apple Software Update server.

This key (when present and value is set to True) causes Munki to never notify users of available updates. This might be useful in a lab environment, where you'd like updates to be applied only when no-one is logged in and the machine is at the login window.

Normally, Munki automatically installs and removes software if there are changes needed and that machine is at the loginwindow with no users logged in. If you have a need to do updates always and only with the consent of the user, including packages configured with unattended_install and unattended_uninstall, setting SuppressAutoInstall to True prevents Munki from automatically installing updates and processing removals.

(Added in version 0.8.4.1696.0) If this preference is set to true, Munki will not install updates when idle at the loginwindow, with the exception of updates marked for unattended_install or unattended_uninstall.

By default, Managed Software Update.app suppresses detail on what will be removed, instead showing a simple "Software removals" entry in the list. If you'd like Managed Software Update.app to show specific detail about what will be removed, set ShowRemovalDetail to True. This key has no effect on /usr/local/munki/managedsoftwareupdate, which always shows all detail.

Managed Software Center.app enforces a logout before it installs or removes software only if one or more items to be installed/removed requires a logout or restart. You can force a logout for all updates by setting InstallRequiresLogout to True. This key has no effect on running /usr/local/munki/managedsoftwareupdate from the command-line.

This key provides the ability to specify custom HTTP headers to be sent with all HTTP/HTTPS requests. AdditionalHttpHeaders must be an array of strings with valid HTTP header format. For example:

<key>AdditionalHttpHeaders</key>
<array>
    <string>Key-With-Optional-Dashes: Foo Value</string>
    <string>another-custom-header: bar value</string>
</array>

One could use this to obtain a cookie in a preflight script and update ManagedInstalls.plist with the appropriate header. However, it is recommended that you use Secure Config for sensitive data (i.e. cookie) since ManagedInstalls.plist is world-readable.

By default, Munki will not follow redirects that are returned by the web server. The FollowHTTPRedirects preference defines whether Munki should follow all redirects or only redirect to HTTPS URLs. The possible values for FollowHTTPRedirects are:

• none - This is the default and is the same as Munki's original behaviour. No redirects are followed.
• https - Only redirects to URLs using HTTPS are followed. Redirects to HTTP URLs are not followed.
• all - Redirects to both HTTP and HTTPS URLs are followed.

If there are parts of your Munki configuration you consider sensitive information (for example, repo authentication information, special HTTP headers, or even the Munki repo URLs), instead of storing those preferences in the world-readable /Library/Preferences/ManagedInstalls.plist file, you can use a more secure location for some Munki preferences: /var/root/Library/Preferences/ManagedInstalls.plist.

Use of this alternate preferences location is completely optional. If you do decide to use it, make sure you fully understand the implications.

Munki uses Apple's defaults mechanism to store and access its preferences. Since the core Munki tools run as root, they can access preferences from this file: /private/var/root/Library/Preferences/ManagedInstalls.plist as well as the "normal" /Library/Preferences/ManagedInstalls.plist file.

Non-admin users of machines managed by Munki will not be able to access or read the contents of /private/var/root/Library/Preferences/ManagedInstalls.plist, so this provides some additional security for possibly sensitive preference values.

Note: preferences defined in /var/root/Library/Preferences/ManagedInstalls.plist have a higher precedence than those defined /Library/Preferences/ManagedInstalls.plist, so any preferences set here will override preferences defined in /Library/Preferences/ManagedInstalls.plist! This might confuse you or other admins who think only to look in /Library/Preferences/ManagedInstalls.plist and forget that some preferences are also defined in /private/var/root/Library/Preferences/ManagedInstalls.plist.

With Munki 3.1 or later you can use sudo managedsoftwareupdate --show-config to show the effective preferences configuration, no matter where the preferences are defined (/Library/Preferences/ManagedPreferences.plist, /private/var/root/Library/Preferences/ManagedInstalls.plist, or managed preferences).

VERY IMPORTANT NOTE: the following preferences are required to be defined in /Library/Preferences/ManagedInstalls.plist (or set via MCX or configuration profile), as the GUI portion of Munki runs as the logged in user, not root. Do not place them in /var/root/Library/Preferences/ManagedInstalls.plist, or you may encounter unexpected behavior from Managed Software Center.app, since it can't read the contents of /var/root/Library/Preferences/ManagedInstalls.plist:

• ManagedInstallDir
• InstallAppleSoftwareUpdates
• AppleSoftwareUpdatesOnly
• ShowRemovalDetail
• InstallRequiresLogout
• HelpURL

Do not use a text editor or plist editor to edit preferences located at /Library/Preferences/ManagedInstalls.plist or the equivalent files in /var/root/Library/Preferences. Editing macOS preferences in this way is likely to lead to unexpected or unwanted results, as your changes may be ignored by macOS's preference caching. Instead, if you must manually change the values of one or more Munki preference, use the defaults command. This is not unique to Munki -- the same recommendations apply to changing any macOS preference.

If you script the setting of Munki preferences, do not use PlistBuddy or any tool designed to manipulate plists, for the same reasons as above. Instead use the defaults tool or call the CFPreferences methods in CoreFoundation. (https://developer.apple.com/documentation/corefoundation/preferences_utilities?language=objc)

The other supported way to set and manage Munki's preferences is to use configuration profiles. Be aware that Munki preferences managed via configuration profiles do not result in the values stored in /Library/Preferences/ManagedInstalls.plist or the equivalent files in /var/root/Library/Preferences changing. This is normal, expected behavior for macOS managed preferences.

If you use the /usr/bin/defaults command to set values for keys in ManagedInstalls.plist, remember that values default to the "string" type. If you are writing a boolean, integer, or array value, be sure to add the appropriate type flag. For example:

defaults write /Library/Preferences/ManagedInstalls SuppressAutoInstall -bool false

See man defaults for a complete list of type flags.