Handoff to Cimian

Handoff to Cimian

BootstrapMate exists to get a freshly provisioned device to the point where an ongoing configuration-management tool takes over. On Windows that tool is usually Cimian. This page describes what BootstrapMate leaves behind, how you arrange the handoff from your manifest, and how to confirm it happened.

What BootstrapMate automates, and what it does not

Be precise about this, because the tool's name and its registry layout both suggest more integration than exists.

BootstrapMate does not install Cimian, configure Cimian, or trigger a Cimian check-in on its own. There is no Cimian bootstrap built in. Every part of getting Cimian onto the device is something you put in your manifest.

There are exactly two Cimian-aware behaviours in the code:

• Cimian-built MSI routing. Before installing an item of type msi, BootstrapMate reads the MSI and looks for the literal marker CIMIAN_PKG_BUILD_INFO. If it is present and sbin-installer is available on the device, the package is installed through sbin-installer rather than msiexec, because sbin-installer handles the embedded scripts in those packages natively. Files whose name starts with sbin-installer are excluded from that check. If the marker is present but sbin-installer is not, the package falls back to msiexec.exe /i "<path>" /qn /norestart.
• Status registry root. Run status is written under HKLM\SOFTWARE\Cimian\BootstrapMate. This is a naming legacy, not an integration point — nothing reads it back except you.

What is left behind after a run

Artefact	Location
The CLI and GUI	C:\Program Files\BootstrapMate (on the system PATH)
The recurring task	BootstrapMate Self-Heal, daily 03:00, SYSTEM
Run log	C:\ProgramData\ManagedBootstrap\logs\<yyyy-MM-dd>\<HHmmss>ootstrap.log, beside events.jsonl and session.json
Phase status	HKLM\SOFTWARE\Cimian\BootstrapMate\Status\{SetupAssistant,Userland}
Completion marker	HKLM\SOFTWARE\Cimian\BootstrapMate → LastRunVersion
Status file	C:\ProgramData\ManagedBootstrap\status.json
Cache	C:\ProgramData\ManagedBootstrap\cache — empty on a clean run

Plus, of course, whatever your manifest installed. That is the handoff: BootstrapMate's job ends when the packages are on disk and the log says so.

Arranging the handoff in the manifest

The handoff is three things you list as items, in this order of intent.

1. sbin-installer, if you use Cimian-built packages. Install it before anything that depends on it. BootstrapMate looks for it at C:\Program Files\sbin\installer.exe, then C:\Program Files (x86)\sbin\installer.exe, C:\sbin\installer.exe, C:\Tools\sbin\installer.exe, and finally via where.exe installer.exe — accepting only results whose path contains sbin or System Binary. An item whose name contains System Binary Installer or sbin-installer, or whose filename contains sbin-installer, is treated as a critical package and gets the long retry policy: 10 attempts, 15 seconds apart, retrying on any non-zero exit rather than only the retryable codes.

2. The Cimian client itself, as an ordinary msi item.

3. Cimian's configuration and first run, as a ps1 item. This is where you write the Cimian software-repository URL and whatever else your client needs, and where you invoke the first check-in if you want one during provisioning. BootstrapMate has no built-in step for this.

A minimal shape, in the setupassistant phase:

{
  "setupassistant": [
    {
      "name": "System Binary Installer",
      "url": "https://example.com/pkgs/sbin-installer.msi",
      "file": "sbin-installer.msi",
      "type": "msi"
    },
    {
      "name": "Cimian",
      "url": "https://example.com/pkgs/cimian.msi",
      "file": "cimian.msi",
      "type": "msi"
    },
    {
      "name": "Configure Cimian",
      "url": "https://example.com/scripts/configure-cimian.ps1",
      "file": "configure-cimian.ps1",
      "type": "ps1"
    }
  ]
}

Ordering matters, and it is not purely manifest order. Items are reordered before execution: msi and exe run first, then nupkg, then general ps1, then everything else, and last of all any ps1 whose name contains cleanup, clean, wipe, remove, delete, purge, nuclear or maintenance. Within a band, manifest order is preserved. There is no dependency graph. That default happens to put installer packages before configuration scripts, which is what a Cimian handoff wants — but if you need a specific sequence, read Stages and Item Types before relying on it.

Two more things that bite here:

• A ps1 item is not Authenticode-gated. Signature verification applies only to msi and exe items.
• A ps1 that exits non-zero throws and the item is recorded as failed, but the run continues and still exits 0. Do not read the process exit code as "Cimian is configured". The failure does reach the phase status and suppresses LastRunVersion, so read those.

Verifying the handoff

Work through these in order on the device.

Confirm the run itself completed:

Get-ItemProperty 'HKLM:\SOFTWARE\Cimian\BootstrapMate' -Name LastRunVersion
Get-ItemProperty 'HKLM:\SOFTWARE\Cimian\BootstrapMate\Status\SetupAssistant'

Stage should read Completed, and LastRunVersion should be present — a run that failed any package marks the phase Failed and writes no LastRunVersion. Note that --status reports from a different registry root and will not tell you this; see Logging and Reporting.

Confirm no item failed. The exit code will not tell you, so count failures in the log:

Select-String 'Failed to install package ' (Get-ChildItem C:\ProgramData\ManagedBootstrap\logs -Filter *.log -Recurse | Sort-Object LastWriteTime -Descending | Select-Object -First 1).FullName

Confirm the cache is empty. A cached file is deleted after a successful install and kept after a failed one, so any file left in C:\ProgramData\ManagedBootstrap\cache is a failed install:

Get-ChildItem C:\ProgramData\ManagedBootstrap\cache

Then verify Cimian on its own terms — its binaries, its configuration and its own logs. BootstrapMate records that it installed a package; it has no visibility into whether that package's client is healthy afterwards.

The macOS equivalent

The same pattern on macOS hands off to Munki, and the sibling wiki documents it:

https://github.com/bootstrapmate/bootstrapmate-macintosh/wiki/Handoff-to-Munki

Note that "manifest" means different things on the two sides. BootstrapMate's manifest is the bootstrap document described in Manifests; it is not a Munki manifest and not a Cimian manifest.

See also

• Manifests
• Item Types
• Stages
• Logging and Reporting
• Troubleshooting and Gotchas