Repository navigation
FAQ
Questions that come up repeatedly, answered against what the Windows code does.
They share the concept, the manifest vocabulary, the page names in these wikis, and the
last-run.json, baseline.json, preflight exit-code and run-summary contracts; they share no
code. On Windows every stage runs back to back in one SYSTEM process, so userland items do not
run in a user's session. Item types and verification differ too: Windows verifies msi and exe
items with Authenticode, and any item with a SHA-256 hash. Start at
https://github.com/bootstrapmate/bootstrapmate-macintosh/wiki for the macOS behaviour.
No. It is a provisioning tool with a beginning and an end. It has no desired-state model, no
uninstall, no catalogs and no scheduling beyond the daily task. Baseline mode refreshes the
setupassistant items on a provisioned machine, but that is a safety net for the tooling that
manages the machine, not management itself. The normal reason to run it is to get Cimian onto a
device early, then let Cimian do the ongoing work. See Handoff to Cimian.
The failure is logged as Failed to install package {name}: {msg}, the downloaded file is kept in
C:\ProgramData\ManagedBootstrap\cache for inspection, and the run continues to the next item.
Nothing aborts and nothing rolls back. MSI items are retried first, up to 5 attempts on exit codes
1603, 1619, 1620 and 1612; downloads retry stalls, network errors and 5xx responses. At the end
the run exits 2, the stage reads Failed, and last-run.json reads partial_failure with the
item marked failed.
0 success, 1 usage or manifest error (or a failed preflight, or a dry run), 2 packages
failed, 3 administrator rights not obtained. See
Command Line Reference.
Both. An item with hash must match that SHA-256 before it runs, whatever its type, preflight
scripts included. msi and exe items are also checked with WinVerifyTrust, on by default
(VerifyPackageSignatures); you can require a signer with ExpectedPublisher, permit untrusted
binaries with AllowUnsigned, and override both per item. A publisher mismatch is refused even
with AllowUnsigned. Revocation is not checked, because OCSP and CRL are unreliable during OOBE.
See Security and Package Verification.
No. There is no reboot handling: no pending-reboot detection, no resume after a restart. Every
MSI is run with /norestart. If an installer restarts the machine itself, the next run records
the cut-short run as interrupted and starts the manifest again.
Yes. The MSI registers BootstrapMate Self-Heal, which runs daily at 03:00 as SYSTEM with
--silent --no-dialog. Without a preflight, every run provisions in full and installs every
item again, so your installers need to tolerate that. With a preflight, a provisioned machine can
get a Skip or a throttled baseline that skips what is already installed. Only one run happens at a
time; a second waits on a global mutex for up to 30 minutes. See
Preflight and Baseline.
Add a preflight script that recognises a provisioned machine and exits 2 for a baseline or
0 to skip. A baseline shows no dialog, never runs userland, skips items already installed, and
runs at most once per BaselineMinIntervalHours (default 144). Mark one-time items
"baseline": false. See Preflight and Baseline.
The installed build:
managedbootstrapinstall.exe --version
The last run's mode, outcome and failed items:
managedbootstrapinstall.exe --last-run
The MSI also records the installed build under HKLM\SOFTWARE\BootstrapMate as Version.
To detect that a build is installed, Version under HKLM\SOFTWARE\BootstrapMate. To detect
that a bootstrap run completed, status in C:\ProgramData\ManagedBootstrap\last-run.json.
LastRunVersion is weaker: the MSI writes it at install, and a run with failed packages leaves it
in place. See Deployment.
Almost always the Authorization header. BootstrapMate sends it to a package download only when
the package's host matches the manifest's host, and logs Authorization header withheld for cross-host download at Debug when it does not. Some public object stores return 403 for a public
object carrying an Authorization header they cannot validate. Packages on another host that
need authentication must carry it in the URL itself. See
Serving Manifests and Packages.
In HKLM\SOFTWARE\BootstrapMate\Secrets, which only SYSTEM and Administrators can read. Deliver
it by policy or the app; the next elevated run moves a policy or settings copy there and blanks the
readable copy. See Preferences.
BootstrapMate has no simulated install, so DryRun and --dry-run refuse to run and exit 1.
That applies to every run while the setting is on, the scheduled task included. Test on a device
you can rebuild instead.
One directory per run, C:\ProgramData\ManagedBootstrap\logs\yyyy-MM-dd\HHmmss\ in local time,
holding bootstrap.log, events.jsonl and session.json. At the start of each run, day
directories older than 30 days are deleted, then all but the newest 100 sessions. bootstrap.log
always contains every level, including Debug. See Logging and Reporting.
Yes, Managed Bootstrap Install, from the Start Menu. It shows and edits the machine settings after an administrator unlocks it, runs the CLI with live output, and browses past runs. See Managed Bootstrap Install App.
- Manifests
- Manifest Reference
- Stages
- Preflight and Baseline
- Item Types
- Conditions and Skipping
- Retries and Timeouts
- Example Manifests
- Preferences
- Command Line Reference
- Managed Bootstrap Install App
- Security and Package Verification
- Serving Manifests and Packages