-
Notifications
You must be signed in to change notification settings - Fork 0
Glossary
The words on this wiki are borrowed from InstallApplications, Munki and Apple, and two of them mean something different here than they do in Munki. Read the disambiguations at the bottom if you are arriving from a Munki-managed fleet.
Manifest — the document BootstrapMate downloads and executes. JSON or YAML, with up to
three optional top-level arrays (preflight, setupassistant, userland), each holding
items. This is the whole policy: BootstrapMate has no other source of software. See
Manifest Reference.
Item — one unit of work inside a stage: one package to install or one script to run.
An item is identified by a url to fetch from, an absolute file to write to, a SHA-256
hash to verify against, and a type of package, rootscript or userscript.
Stage — one of the three top-level groupings of items, run in the fixed order
preflight → setupassistant → userland. The term comes from InstallApplications. The
Windows implementation calls the same idea a phase; the two words mean the same thing.
preflight — the first stage. Only the first rootscript item in it is used. Its exit
code decides the run: 0 skips the entire bootstrap, greater than 0 continues, and a
negative code (the script could not be downloaded or launched) fails the run and skips
both remaining stages. Its purpose is to answer "has this Mac already been provisioned?".
setupassistant — the second stage. Its items run as root while Setup Assistant is still on screen and no user session exists. This is where packages that must be present before anyone logs in belong. An item failing here is recorded but does not stop the other items.
userland — the third stage. The run blocks until a real console user exists, then runs
the items. Despite the name, userscript items here still execute as root in the daemon
process; the code that would run a script as the console user exists but is never called.
Handoff — what BootstrapMate leaves behind for the ongoing configuration manager. On macOS that is Munki. BootstrapMate contains no Munki-specific code: the handoff is something you author as manifest items — install the tools, write their configuration, put Munki into bootstrap mode. See Handoff to Munki.
Bootstrap mode — Munki's own term, and it does not mean "BootstrapMate is running". It
is the state Munki enters when the marker file
/Users/Shared/.com.googlecode.munki.checkandinstallatstartup exists, which makes
managedsoftwareupdate loop at the login window until there is nothing left to install.
It is set and cleared with managedsoftwareupdate --set-bootstrap-mode and
--clear-bootstrap-mode. Use the phrase only in that sense.
LaunchDaemon — a launchd job that runs as root with no user session, which is how
BootstrapMate runs unattended. Two are involved:
/Library/LaunchDaemons/com.github.bootstrapmate.plist, the one-shot bootstrap job that
the CLI deletes on the way out, and com.github.bootstrapmate.helper, the privileged
helper the GUI talks to.
XPC helper — BootstrapMateHelper, a root process exposing the Mach service
com.github.bootstrapmate.helper. It exists so the unprivileged GUI can ask for two
privileged things: run or stop the CLI, and write system-domain preferences. It does not
install anything itself.
Setup Assistant — Apple's first-boot experience on a new or erased Mac. A Mac enrolled
through Automated Device Enrollment can have software installed by MDM while Setup
Assistant is still up, before any user account exists. That window is what the
setupassistant stage is named after.
Remote Management enrollment — the enrollment a Mac performs during Setup Assistant when Apple's activation record says it belongs to an MDM. It is the point at which the MDM can push the BootstrapMate package and its configuration profile. See Setup Assistant and MDM Bootstrap.
DEP / ADE — Device Enrollment Program, now Automated Device Enrollment: the Apple service that binds a Mac's serial number to an organisation's MDM so that Remote Management enrollment happens automatically during Setup Assistant. "DEP" and "ADE" refer to the same thing; ADE is the current name.
Munki — the open-source macOS software management system BootstrapMate hands off to. It has its own manifests, catalogs, pkginfo files and check-in schedule, and it is what manages the Mac from the first login onwards.
Cimian — the equivalent ongoing manager on Windows, and the handoff target of the Windows implementation of BootstrapMate. It appears on this wiki only as the counterpart to Munki.
ESP / OOBE — the Windows analogue of Setup Assistant. OOBE (Out-Of-Box Experience) is Windows' first-boot setup, and the ESP (Enrollment Status Page) is the screen Autopilot shows during it while device-phase and user-phase work completes. A Mac administrator does not need these, but the Windows wiki uses them where this one says Setup Assistant.
BootstrapMate manifest is not a Munki manifest. In Munki, a manifest lists the software a client should have installed or removed, and is consulted on every check-in for the life of the machine. A BootstrapMate manifest is the InstallApplications sense of the word: a one-shot list of things to download and run during provisioning, with no concept of removal and no ongoing evaluation. A Mac will normally have both, and they are unrelated documents.
preflight the stage is not Munki's preflight script. Munki's preflight and
postflight are hook scripts it runs around each of its own check-in cycles, for the life
of the machine. BootstrapMate's preflight is a stage name inherited from
InstallApplications: one script, run once, whose exit code decides whether the bootstrap
happens at all.