Repository navigation
Item Types
An item's type decides how the downloaded file is run, which optional keys apply, and what
counts as success. Five values are handled: msi, exe, ps1 (with powershell as a
synonym), nupkg and pkg. Anything else fails the item with
Unsupported package type: {type}. Supported types are: msi, exe, ps1, nupkg, pkg.
type is matched case-insensitively. It is also the main ordering key inside a stage; see
Stages. Whatever the type, a download with a hash must match it before anything
runs; see Manifest Reference.
type |
Run by | Signature gate | arguments |
target |
Success is |
|---|---|---|---|---|---|
msi |
msiexec.exe, or sbin-installer for a Cimian-built MSI |
Yes | Appended to msiexec; forces msiexec
|
On the sbin-installer path | Exit code 0, with retries |
exe |
The file itself | Yes | The whole command line | No | Exit code 0 |
ps1, powershell
|
powershell.exe |
No | Appended after -File
|
No | Exit code 0 |
nupkg |
sbin-installer, else Chocolatey | No | Appended to either command | On the sbin-installer path | Exit code 0 |
pkg |
sbin-installer only | No | Appended to the command | Yes | Exit code 0 |
The Authenticode gate applies only to msi and exe, the formats WinVerifyTrust can
validate, so expectedPublisher and allowUnsigned do nothing on other types. See
Security and Package Verification.
The default path is:
msiexec.exe /i "<cached file>" /qn /norestart <arguments>
/qn /norestart are always present, so an MSI never shows UI and never restarts the machine.
BootstrapMate has no reboot handling; a package that needs one gets it when something else
restarts the device.
Before each launch BootstrapMate waits for the Windows Installer mutex to go idle, and it retries a defined set of exit codes. That has its own page: Retries and Timeouts.
A Cimian-built MSI, one that contains the marker CIMIAN_PKG_BUILD_INFO, goes to
sbin-installer, which runs the package's embedded scripts, logging Using sbin-installer for Cimian MSI: {file}. Three cases go to msiexec instead:
- sbin-installer is not present on the machine.
- The item has
arguments. Those are msiexec arguments, and sbin-installer's command line takes none. - The item is the sbin-installer package itself, recognised by a file or item name starting
sbin-installerorSbinInstaller(ignoring punctuation and case), or a name containingSystem Binary Installer.
The Debug log names the reason. Third-party MSIs always use msiexec. The marker test reads
the whole MSI into memory, which is worth knowing for very large MSIs. On the sbin-installer
path the MSI retry policy does not apply and target does.
| Exit code | Treated as | Effect |
|---|---|---|
0 |
Success | Item complete |
1618 ERROR_INSTALL_ALREADY_RUNNING |
Scheduling collision | Waits for the other transaction and retries without using an attempt |
1603 ERROR_INSTALL_FAILURE |
Retryable | Retried up to the attempt limit |
1619 ERROR_INSTALL_PACKAGE_OPEN_FAILED |
Retryable | Retried up to the attempt limit |
1620 ERROR_INSTALL_PACKAGE_INVALID |
Retryable | Retried up to the attempt limit |
1612 ERROR_INSTALL_SOURCE_ABSENT |
Retryable | Retried up to the attempt limit |
| Anything else non-zero | Failure | MSI installer failed with exit code: {n} |
An item recognised as the installer helper (its name contains System Binary Installer or
sbin-installer, or its file name contains sbin-installer) retries on any non-zero code.
3010 (reboot required) is neither retryable nor success, so an MSI that returns it fails the
item even though it installed.
The file is started directly, with arguments joined by spaces as its whole command line.
Nothing is added, so supply the vendor's silent switches yourself. Standard output is logged at
INFO and standard error at WARN, both prefixed [OUTPUT] {name}: .
A non-zero exit fails the item with Executable failed with exit code: {n}. There are no
retries. An installer that reports success with a non-zero code, or returns before its work is
done, is misreported; wrap it in a ps1 item instead.
Both spellings run:
powershell.exe -ExecutionPolicy Bypass -NoProfile -File "<cached file>" <arguments>
That is Windows PowerShell, not PowerShell 7, with the run's own elevated token. Output is
captured as for exe. A non-zero exit fails the item with PowerShell script failed with exit code: {n}, so the script's own exit code is the only success signal; a script that swallows
its errors reports success.
Scripts are not signature-checked; pin them with hash. A script whose name contains
cleanup, clean, wipe, remove, delete, purge, nuclear or maintenance runs at the
end of its stage. The same command runs preflight scripts, where the
exit code picks the mode instead.
If sbin-installer is present it handles the package. If not, the log records sbin-installer not found / Using Chocolatey fallback and the item goes to Chocolatey.
On the Chocolatey path BootstrapMate reads the package id and version from the .nuspec inside
the .nupkg (falling back to the file name), checks whether the package is already present to
choose install or upgrade, and runs Chocolatey through powershell.exe with the cache
directory as a local source:
choco {install|upgrade} "<id>" --source="<cache dir>" --version="<version>" -y --acceptlicense --confirm --force --no-progress --quiet --limit-output <arguments>
Chocolatey verifies the checksums of what a package downloads. An item that genuinely needs that
off sets "ignoreChecksums": true, which adds --ignore-checksums and logs a warning.
If Chocolatey is not installed, BootstrapMate installs it from
https://community.chocolatey.org/install.ps1 first, so the fallback needs internet access to
that host. If it finds a Chocolatey directory whose choco.exe does not work, it logs Broken Chocolatey detected, deletes C:\ProgramData\chocolatey, clears ChocolateyInstall and
removes Chocolatey's directory from the machine PATH before reinstalling.
Failure message: Chocolatey {install|upgrade} failed with exit code {n}, with the captured
output appended.
sbin-installer only. Without it the item fails with sbin-installer is required for .pkg packages but was not found. Please install sbin-installer first. The source marks this type for
removal, so prefer msi or nupkg for new work.
Three types can end up here: pkg always, nupkg when sbin-installer is present, and a
Cimian-built msi under the conditions above. The command is:
installer --pkg "<cached file>" --target <target> <arguments>
target defaults to /. The helper is found 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 where.exe installer.exe, accepting a where hit only
if its path contains sbin or System Binary so a Chocolatey shim of the same name is not
mistaken for it.
A non-zero exit fails the item with sbin-installer install failed with exit code: {n} plus the
captured output. sbin-installer's own output is logged at Debug.
The macOS build has its own type vocabulary and verification model; nothing in the type values
transfers between the two. See https://github.com/bootstrapmate/bootstrapmate-macintosh/wiki/Item-Types.
- 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