Configuration

Configuration

Every setting the client reads, where it can come from, and what it does. Everything on this page is taken from Sources/Core/Configuration/ConfigurationManager.swift.

The preference domain is com.github.reportmate throughout.

Precedence

ConfigurationManager starts from the embedded defaults and merges each source over the last, so a later source wins:

1. Embedded defaults.
2. User plist: ~/Library/Managed Reports/reportmate.plist.
3. Environment variables with the REPORTMATE_ prefix.
4. System plist: /Library/Preferences/com.github.reportmate.plist.
5. Configuration profile: any key in the com.github.reportmate domain that a profile forces, detected with CFPreferencesAppValueIsForced.
6. Command-line overrides for this run.

Because the client runs as root under launchd, "user plist" means root's home directory in practice. The system plist is what the installer and the GUI write.

Every key in the table below can be set by a configuration profile, and a profile-forced value beats both the system plist and the environment. Only three settings can be overridden from the command line (--api-url, --device-id and --storage-mode), and those are the only values that beat a profile.

Keys

Key	Type	Default	Effect
ApiUrl	string	none	Base URL of the ReportMate API. The client appends api/v1/events. Without it, transmission fails with API URL not configured.
DeviceId	string	derived	Device UUID sent as metadata.deviceId. When unset, a stable UUID is derived by SHA-256 of the hardware serial.
Passphrase	string	none	Sent as the X-Client-Passphrase header.
ApiKey	string	none	Sent as the X-API-Key header. Sent alongside the passphrase; the API prefers the key and falls through to the passphrase, so both can coexist during a rollout.
CollectionInterval	integer	3600	Carried in the configuration but not used to schedule anything. Scheduling is done by the LaunchDaemons.
LogLevel	string	info	Carried in the configuration. Effective console and file levels are set by -v on the command line, not by this key.
EnabledModules	array of string	hardware, system, network, security, applications, management, inventory, identity, peripherals, installs	Modules run when no --run-module/--run-modules flag is given.
OsqueryPath	string	/usr/local/bin/osqueryi	First osquery candidate tried. See Architecture for the fallbacks and the trust checks every candidate must pass.
OsqueryExtensionPath	string	resolved	Explicit path to the macadmins extension. When unset, the resolution order in Architecture applies.
ExtensionEnabled	boolean	true	When false, no extension is loaded and every extension-table query falls back to shell collection.
UseAltSystemInfo	boolean	true	Carried in the configuration and editable in the GUI. No collection module reads it.
ValidateSSL	boolean	true	Carried in the configuration and editable in the GUI. The API client does not consult it; certificate validation always follows the system trust settings.
Timeout	integer	300	HTTP request timeout in seconds for API calls.
CompressPayload	boolean	true	Gzip the check-in body and set Content-Encoding: gzip. Set false to put a machine back on uncompressed check-ins without shipping a new client. If the encoder declines, the body is sent uncompressed regardless.
MaxRetryAttempts	integer	3	Attempts per check-in, counting the first. A transport failure or an HTTP 408, 429, 500, 502, 503 or 504 is resent after 1 s, then 2 s, doubling. Other failures are returned at once. Values below 1 are treated as 1.
QueryTimeoutSeconds	number	30	Per-query timeout for built-in osquery tables. osqueryi is SIGTERMed, then SIGKILLed after a 2 s grace period.
ExtensionQueryTimeoutSeconds	number	60	Per-query timeout for macadmins extension tables. Higher because the extension path includes a startup sleep plus registration, and some tables do online I/O.
ModuleTimeoutSeconds	number	120	Per-module budget in the configuration model. The command-line runner's module loop does not enforce it; each module is bounded by its own per-query timeouts instead.
StorageMode	string	auto	quick, deep or auto. Controls whether the hardware module runs directory-level storage analysis; see Modules.

Environment variables

Variable	Sets
REPORTMATE_API_URL	ApiUrl
REPORTMATE_DEVICE_ID	DeviceId
REPORTMATE_PASSPHRASE	Passphrase
REPORTMATE_API_KEY	ApiKey
REPORTMATE_COLLECTION_INTERVAL	CollectionInterval
REPORTMATE_LOG_LEVEL	LogLevel
REPORTMATE_QUERY_TIMEOUT	QueryTimeoutSeconds
REPORTMATE_EXTENSION_QUERY_TIMEOUT	ExtensionQueryTimeoutSeconds
REPORTMATE_MODULE_TIMEOUT	ModuleTimeoutSeconds

There is no environment variable for EnabledModules; use the plist, a profile, or --run-modules. Environment variables sit below the system plist, so a value in /Library/Preferences/com.github.reportmate.plist wins over the same setting in the environment.

One further variable is read outside the configuration model: REPORTMATE_CATALOGS_DIR points the installs module at a different Munki catalogs directory (default /Library/Managed Installs/catalogs), which is useful for testing catalog parsing.

Setting values locally

sudo defaults write /Library/Preferences/com.github.reportmate ApiUrl -string "https://reportmate.example.com"

sudo defaults write /Library/Preferences/com.github.reportmate EnabledModules -array hardware system network security applications management inventory identity peripherals installs

The postinstall seeds CollectionInterval, LogLevel, OsqueryPath, OsqueryExtensionPath, ExtensionEnabled, ValidateSSL, Timeout and EnabledModules, plus ApiUrl when the package was built with --api-url, but only where the key is absent, so your values survive upgrades.

Setting values by MDM profile

Deliver a com.github.reportmate custom-settings payload. Any key in the table above can be included.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadDisplayName</key>
  <string>ReportMate</string>
  <key>PayloadIdentifier</key>
  <string>com.example.reportmate.settings</string>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadUUID</key>
  <string>00000000-0000-0000-0000-0000000000A1</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>com.github.reportmate</string>
      <key>PayloadIdentifier</key>
      <string>com.example.reportmate.settings.prefs</string>
      <key>PayloadUUID</key>
      <string>00000000-0000-0000-0000-0000000000A2</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>ApiUrl</key>
      <string>https://reportmate.example.com</string>
      <key>Passphrase</key>
      <string>your-client-passphrase</string>
      <key>EnabledModules</key>
      <array>
        <string>hardware</string>
        <string>system</string>
        <string>network</string>
        <string>security</string>
        <string>applications</string>
        <string>management</string>
        <string>inventory</string>
        <string>identity</string>
        <string>peripherals</string>
        <string>installs</string>
      </array>
    </dict>
  </array>
</dict>
</plist>

A key delivered this way is forced. The runner reads it ahead of the system plist and the environment, the GUI shows the forced value and locks the field, and the privileged helper refuses to write or remove it.

GUI

Managed Reports Runner.app edits ApiUrl, DeviceId, Passphrase, ValidateSSL, CollectionInterval, LogLevel, StorageMode, Timeout, OsqueryPath, OsqueryExtensionPath, ExtensionEnabled, UseAltSystemInfo and EnabledModules. Edits auto-save 0.75 s after the last change, written to the system plist through the privileged XPC helper. The other keys (ApiKey, CompressPayload, MaxRetryAttempts and the timeouts) are set by defaults, a profile or the environment. See Managed Reports Runner App.