-
Notifications
You must be signed in to change notification settings - Fork 0
Overview
BootstrapMate ships as one package containing four executables plus a manifest you supply. This page names each moving part, says what it does, and says what runs as root. Read How It Works next for the order they act in.
The CLI is the whole tool. It lives at
/Applications/Utilities/BootstrapMate.app/Contents/MacOS/managedbootstrapinstall, with a
symlink at /usr/local/bootstrapmate/managedbootstrapinstall. It is a single flat
command — there are no subcommands — that loads its configuration, fetches the manifest,
runs the three stages in order, writes status and logs, optionally posts a run summary,
and then removes its own LaunchDaemon. It runs as root; it writes under /Library,
invokes /usr/sbin/installer and /usr/sbin/pkgutil, and executes every manifest script
in root context. Its flags and exit codes are in the
Command Line Reference.
/Library/LaunchDaemons/com.github.bootstrapmate.plist is what starts an unattended run.
Its ProgramArguments is just the CLI path with no arguments, so everything the run
needs must come from the com.github.bootstrapmate managed-preferences domain. It sets
RunAtLoad so the package's postinstall load starts a run immediately, and
AbandonProcessGroup so a donotwait child survives the daemon being booted out. There
is no KeepAlive: the run happens once, and the CLI deletes this plist on the way out.
That makes the daemon one-shot by design. See
Setup Assistant and MDM Bootstrap.
BootstrapMateCore is the shared Swift library holding every manager the other three
executables use: configuration and precedence, manifest decoding (JSON and YAML),
downloading and SHA-256 verification, signature policy, package and script execution, the
orchestrator that sequences the stages, status writing, logging, SwiftDialog control and
reporting. It is not something you install or invoke separately; it is named here because
the log lines and behaviour described across this wiki come from it, whichever front end
started the run.
BootstrapMate.app also contains a SwiftUI application, BootstrapMateGUI, for editing
settings and reviewing runs. It runs as the logged-in user, not as root, and it never
installs anything itself: it asks the privileged helper to launch the CLI and it streams
the CLI's output back into its own window, and it asks the helper to write system-level
preferences. Its Logs tab reads /Library/Managed Bootstrap/logs/, the same directory the
CLI writes.
BootstrapMateHelper is a privileged helper registered as the LaunchDaemon
com.github.bootstrapmate.helper, exposing the Mach service
com.github.bootstrapmate.helper. It runs as root and exists only so the unprivileged
GUI can do two privileged things: run the CLI with arguments (and stop it with SIGTERM),
and set, change or remove preferences in the system domain. Note that the helper's
connection check requires a placeholder Apple Team ID (TEAMID0000) in the source, so a
genuinely signed GUI is refused and the app reports no connection to the helper until an
organisation edits that requirement and rebuilds. The CLI itself is unaffected by this —
see Troubleshooting and Gotchas.
The manifest is the document you author and host. It is a JSON or YAML file with up to
three optional top-level arrays — preflight, setupassistant and userland — each
holding items. An item is one package to install or one script to run, identified by a
URL, an absolute destination file and a SHA-256 hash. BootstrapMate has no built-in
list of software; the manifest is the entire policy. See
Manifests and the Manifest Reference.
BootstrapMate is deliberately a one-shot tool. It has no scheduling, no recurring check-in and no notion of removing software; nothing in it is aware of Munki. The intended shape is that your manifest installs and configures an ongoing configuration manager — on macOS, Munki — and that manager takes over from the first user session onward. Everything about that transfer is therefore something you author as manifest items, not a feature you turn on. See Handoff to Munki.