Preferences

BootstrapMate reads its configuration from a single managed-preferences domain, com.github.bootstrapmate, normally delivered as a configuration profile. This page lists every key the tool reads, what it does, and which keys are read but never acted on. Use it when you are writing the profile that drives a provisioning run, or when a profile setting appears to have been ignored.

Precedence

Configuration is resolved in this order, highest first:

Command-line flags — see Command Line Reference.
Managed preferences in the com.github.bootstrapmate domain.
Built-in defaults — the values in the Default column below.

There is one important qualification. String options are only overridden by the command line when the flag was actually supplied, but the six boolean options followRedirects, dryRun, reboot, userscriptOnly, silentMode and verboseMode are written from the command line on every run, including when the corresponding flag is absent and therefore false. A profile that sets one of those keys to true is overwritten by the command line's false before the run begins. verifyPackageSignatures and allowUnsigned are the exceptions: the CLI only overrides them when --no-verify-signature or --allow-unsigned is passed, so profile values for those two survive.

Per-item manifest fields override the global configuration for expectedTeamID and allowUnsigned only. See Manifest Reference.

Where preferences are read from

The domain is read with CFPreferencesCopyAppValue, and these plists are read directly as a fallback:

/Library/Managed Preferences/com.github.bootstrapmate.plist
/Library/Managed Preferences/<username>/com.github.bootstrapmate.plist

The direct-plist fallback reads only url/jsonurl/JsonUrl, headers/Headers and followRedirects. Every other key below is read through the preferences domain.

There is no configuration file and no environment variable that BootstrapMate reads at runtime.

To confirm what a Mac has actually received:

defaults read /Library/Managed\ Preferences/com.github.bootstrapmate

Key summary

Key	Type	Required	Default	Summary
`url`	String	Yes, unless `--jsonurl` is passed	none	Manifest URL
`headers`	String	No	none	Value sent as the `Authorization` header on downloads
`followRedirects`	Bool	No	`false`	Read, but has no effect
`silentMode`	Bool	No	`false`	Suppress console output
`verboseMode`	Bool	No	`false`	Verbose logging
`reboot`	Bool	No	`false`	Reboot after a successful run
`dryRun`	Bool	No	`false`	Download nothing, install nothing
`userscriptOnly`	Bool	No	`false`	Run only userland scripts
`reportingUrl`	String	No	none	Endpoint to POST the run summary to
`reportingHeader`	String	No	none	`Authorization` header for the reporting POST
`verifyPackageSignatures`	Bool	No	`true`	Verify installer package signatures
`expectedTeamID`	String	No	none	Require packages signed by this Apple Team ID
`allowUnsigned`	Bool	No	`false`	Permit untrusted or unsigned packages
`enableDialog`	Bool	No	`true`	Read, but has no effect
`dialogTitle`	String	No	`Setting up your Mac`	Read, but has no effect
`dialogMessage`	String	No	`Please wait while we configure your device...`	Read, but has no effect
`dialogIcon`	String	No	none	Read, but has no effect
`blurScreen`	Bool	No	`false`	Read, but has no effect
`networkTimeout`	Int	No	`120`	Read, but has no effect
`installPath`	String	No	`/Library/Application Support/BootstrapMate`	Read, but has no effect
`daemonIdentifier`	String	No	`com.github.bootstrapmate`	Read, but has no effect
`agentIdentifier`	String	No	`com.github.bootstrapmate`	Read, but has no effect

Many keys accept more than one spelling. The alternatives are listed under each key; the first spelling found wins, in the order given.

`url`

Type: String
Default: none
Required: Yes, unless --jsonurl is passed
Also accepted: jsonurl, JsonUrl, ConfigURL, ManifestURL

The URL of the manifest BootstrapMate downloads and executes. When the tool starts from its LaunchDaemon it is given no arguments at all, so in a normal enrollment this key is the only way the manifest is located. If neither this key nor --jsonurl supplies a URL, BootstrapMate waits up to 300 seconds for the profile to arrive, then logs No manifest URL configured. Use --jsonurl or configure via management profile. and exits 1.

`headers`

Type: String
Default: none
Also accepted: Headers, AuthorizationHeader

The complete value of an Authorization header, for example Basic … or Bearer …. BootstrapMate sends it on the manifest request and on every payload download in the manifest, regardless of which host the payload URL points at. See Serving Manifests and Packages.

`followRedirects`

Type: Bool
Default: false
Also accepted: FollowRedirects

This key has no effect. The value is read and passed through the download API, but no redirect-controlling delegate is installed, so URLSession follows redirects either way. See Troubleshooting and Gotchas.

`silentMode`

Type: Bool
Default: false
Also accepted: SilentMode, silent

Suppresses console output. The logger is initialised from the --silent flag before managed preferences are applied, so setting this key by profile does not change what appears on the console. It is also one of the boolean keys the command line overwrites on every run; see Precedence above.

`verboseMode`

Type: Bool
Default: false
Also accepted: VerboseMode, verbose

Enables verbose logging. The same two caveats as silentMode apply: the logger is already initialised from --verbose by the time this value is read, and the command line overwrites the key on every run. Use --verbose when you want verbose output.

`reboot`

Type: Bool
Default: false
Also accepted: Reboot

Reboots the Mac five seconds after the run, and only when the run succeeded. This is one of the boolean keys the command line overwrites on every run; see Precedence above.

`dryRun`

Type: Bool
Default: false

Downloads nothing and installs nothing; each item is logged as [Dry Run] Would download <name>. This is one of the boolean keys the command line overwrites on every run; see Precedence above.

`userscriptOnly`

Type: Bool
Default: false

Runs only the userscript items in the userland stage, then exits 0. This is one of the boolean keys the command line overwrites on every run; see Precedence above.

`reportingUrl`

Type: String
Default: none
Also accepted: ReportingUrl, ReportURL, reportingURL

When set, BootstrapMate POSTs a JSON run summary to this URL once, at the end of the run. A reporting failure is logged and never fails the run. See Logging and Reporting for the payload.

`reportingHeader`

Type: String
Default: none
Also accepted: ReportingHeader, ReportingAuthorizationHeader

The complete value of the Authorization header sent with the reporting POST. It is separate from headers, which is used for downloads.

`verifyPackageSignatures`

Type: Bool
Default: true
Also accepted: VerifyPackageSignatures, verifySignatures

Controls whether installer packages are checked with pkgutil --check-signature before installer runs. See Security and Package Verification.

`expectedTeamID`

Type: String
Default: none, meaning any signature macOS trusts is accepted
Also accepted: ExpectedTeamID, teamID, TeamID

A ten-character Apple Team ID. When set, a package whose signing chain reports a different Team ID is refused, and that refusal cannot be overridden by allowUnsigned. The value is trimmed and upper-cased before comparison. A manifest item may set its own expectedTeamID, which takes precedence over this key for that item.

`allowUnsigned`

Type: Bool
Default: false
Also accepted: AllowUnsigned

Permits a package with no signature, or a signature macOS does not trust, to install anyway. It does not permit a Team ID mismatch. A manifest item may set its own allowUnsigned, which takes precedence over this key for that item.

`enableDialog`

Type: Bool
Default: true

This key has no effect. The SwiftDialog window is enabled by the command line only, from --no-dialog and --silent. See Troubleshooting and Gotchas.

`dialogTitle`

Type: String
Default: Setting up your Mac
Also accepted: DialogTitle

This key has no effect. The dialog title comes from --dialog-title only. See Troubleshooting and Gotchas.

`dialogMessage`

Type: String
Default: Please wait while we configure your device...
Also accepted: DialogMessage

This key has no effect. The dialog message comes from --dialog-message only. See Troubleshooting and Gotchas.

`dialogIcon`

Type: String
Default: none

This key has no effect. The dialog always uses its built-in icon. See Troubleshooting and Gotchas.

`blurScreen`

Type: Bool
Default: false

This key has no effect. Nothing in the CLI passes the value to the dialog. See Troubleshooting and Gotchas.

`networkTimeout`

Type: Int
Default: 120

This key has no effect. The network wait uses the --network-timeout option, which defaults to 120 seconds, and never the profile value. See Troubleshooting and Gotchas.

`installPath`

Type: String
Default: /Library/Application Support/BootstrapMate
Also accepted: InstallPath, iapath

This key has no effect. Every download goes to the absolute path in the manifest item's file field. See Troubleshooting and Gotchas.

`daemonIdentifier`

Type: String
Default: com.github.bootstrapmate
Also accepted: ldidentifier

This key has no effect. Cleanup removes the compiled-in LaunchDaemon label, not the configured one. See Troubleshooting and Gotchas.

`agentIdentifier`

Type: String
Default: com.github.bootstrapmate
Also accepted: laidentifier

This key has no effect. BootstrapMate registers no LaunchAgent. See Troubleshooting and Gotchas.

A note on `retainCache`

The example profile shipped in the repository contains a retainCache key. No code reads it. Downloaded payloads are never removed, whatever you set it to. It is omitted from the example below.

Worked profile

The payload is a com.apple.configuration.plist payload with PreferenceDomain set to com.github.bootstrapmate, inside a System-scoped configuration profile. Replace the two PayloadUUID values with UUIDs of your own, the identifiers with your own reverse-DNS identifiers, and the Team ID with the Team ID that signs your packages. Keys with no effect are left out, so everything below does something.

<?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>PayloadContent</key>
	<array>
		<dict>
			<key>PayloadContent</key>
			<dict>
				<key>url</key>
				<string>https://example.com/bootstrap/manifest.json</string>
				<key>headers</key>
				<string>Bearer YOUR_AUTH_TOKEN_HERE</string>
				<key>reportingUrl</key>
				<string>https://example.com/bootstrap/report</string>
				<key>reportingHeader</key>
				<string>Bearer YOUR_REPORTING_TOKEN_HERE</string>
				<key>verifyPackageSignatures</key>
				<true/>
				<key>expectedTeamID</key>
				<string>AB12CD34EF</string>
				<key>allowUnsigned</key>
				<false/>
			</dict>
			<key>PayloadDescription</key>
			<string>Configures BootstrapMate.</string>
			<key>PayloadDisplayName</key>
			<string>BootstrapMate Configuration</string>
			<key>PayloadIdentifier</key>
			<string>com.example.bootstrap.config.prefs</string>
			<key>PayloadOrganization</key>
			<string>Your Organization</string>
			<key>PayloadType</key>
			<string>com.apple.configuration.plist</string>
			<key>PayloadUUID</key>
			<string>4A5E8F1B-2C3D-4E5F-6A7B-8C9D0E1F2A3B</string>
			<key>PayloadVersion</key>
			<integer>1</integer>
			<key>PreferenceDomain</key>
			<string>com.github.bootstrapmate</string>
		</dict>
	</array>
	<key>PayloadDescription</key>
	<string>Configures BootstrapMate to fetch its deployment manifest.</string>
	<key>PayloadDisplayName</key>
	<string>BootstrapMate Configuration</string>
	<key>PayloadIdentifier</key>
	<string>com.example.bootstrap.config</string>
	<key>PayloadOrganization</key>
	<string>Your Organization</string>
	<key>PayloadScope</key>
	<string>System</string>
	<key>PayloadType</key>
	<string>Configuration</string>
	<key>PayloadUUID</key>
	<string>7B8C9D0E-1F2A-3B4C-5D6E-7F8A9B0C1D2E</string>
	<key>PayloadVersion</key>
	<integer>1</integer>
</dict>
</plist>

Deliver the profile during the Remote Management step of Setup Assistant, before or alongside the BootstrapMate package. See Setup Assistant and MDM Bootstrap.

Uh oh!

Preferences

Preferences

Precedence

Where preferences are read from

Key summary

url

headers

followRedirects

silentMode

verboseMode

reboot

dryRun

userscriptOnly

reportingUrl

reportingHeader

verifyPackageSignatures

expectedTeamID

allowUnsigned

enableDialog

dialogTitle

dialogMessage

dialogIcon

blurScreen

networkTimeout

installPath

daemonIdentifier

agentIdentifier

A note on retainCache

Worked profile

See also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Introduction

The Manifest

Configuration

Operations

More

Clone this wiki locally

`url`

`headers`

`followRedirects`

`silentMode`

`verboseMode`

`reboot`

`dryRun`

`userscriptOnly`

`reportingUrl`

`reportingHeader`

`verifyPackageSignatures`

`expectedTeamID`

`allowUnsigned`

`enableDialog`

`dialogTitle`

`dialogMessage`

`dialogIcon`

`blurScreen`

`networkTimeout`

`installPath`

`daemonIdentifier`

`agentIdentifier`

A note on `retainCache`