Skip to content

TotlProvision Runbook

Field procedure for provisioning a new PC end-to-end.

A. Prep (do once per client, at your bench)

  1. scripts\Initialize-Git.ps1 — initialise the repo on your machine (one time).
  2. Copy-Item .env.example .env, then set TOTL_LOCAL_ADMIN_PWD (and TOTL_BIOS_PWD if your Dell BIOS has a setup password).
  3. Place the Office Deployment Tool setup.exe in assets\office\. Get it from Microsoft (search "Office Deployment Tool download"), run the self-extractor, and copy setup.exe only.
  4. Build the client config: gui\New-TotlConfig.ps1. Review the pre-checked recommendations, set the client name and local admin username, save. This writes config\clients\<client>.config.json.
  5. (Per client RMM) edit the config's rmm section: set enabled: true and the installerUrl or installerPath and silentArgs.

B. Build deployment media (USB)

.\oobe\Build-OobeMedia.ps1 -ConfigPath .\config\clients\<client>.config.json -MediaRoot E:\

This writes autounattend.xml to the USB root and stages the whole toolkit to E:\TotlProvision. The answer file creates the local admin account and skips the Microsoft-account screens automatically.

The answer file holds the admin password in plain text. Treat the USB as sensitive; wipe or rotate after the batch.

C. At the new PC

Preferred path (automated OOBE)

  1. Boot the PC. With autounattend.xml on attached media, OOBE creates the local account and, on first logon, auto-runs bootstrap.ps1 from the USB.
  2. Provisioning starts automatically and resumes through any reboots.

Fallback path (your current manual method, still supported)

  1. At OOBE press Shift+F10.
  2. Run start ms-cxh:localonly and create the local user (e.g. Totlcom).
  3. At the desktop, plug in the USB and run: powershell -ExecutionPolicy Bypass -File E:\TotlProvision\scripts\bootstrap.ps1 -ConfigPath E:\TotlProvision\config\clients\<client>.config.json

bootstrap.ps1 copies the toolkit to C:\TotlProvision (so it survives USB removal and reboots), self-elevates, and starts the orchestrator.

D. What happens during the run

Phases run in phases.order. Each phase is logged and marked complete in state.json. If a phase requires a reboot (rename), the orchestrator registers a resume scheduled task, optionally enables temporary auto-logon, reboots, and continues. When all phases finish it removes the resume task, clears auto-logon, and clears state. Windows Updates run last.

E. Profile / data migration (separate, on-site)

This is normally done later, on the same subnet as the old machine.

Account migration (recommended — fixes SID/permission errors):

.\scripts\Migrate-UserProfile.ps1 -Mode Account -ProfwizPath 'C:\Tools\Profwiz.exe' `
  -SourceProfile 'olduser' -TargetAccount 'AzureAD\user@contoso.com' -JoinType AzureAD -AzureIdXml 'C:\Tools\aadusers.xml'

Data-only copy (hardened robocopy fallback):

.\scripts\Migrate-UserProfile.ps1 -Mode Data -SourceRoot '\\OLDPC\C$\Users\olduser' -DestRoot 'C:\Users\newuser' -DryRun
# remove -DryRun to actually copy

Always log the source user off first — a logged-on profile locks NTUSER.DAT and browser files (the tool checks and warns).

F. Troubleshooting

  • BIOS attribute not found — names vary by model. On that model run Import-Module DellBIOSProvider; Get-ChildItem DellSmbios:\ | Format-List to find the exact category\attribute, then add it to the candidate list in src\modules\Totl.Bios\Totl.Bios.psm1.
  • Secure Boot didn't apply — the machine must be in UEFI mode (not Legacy/CSM). The log warns when it isn't.
  • winget missing — install "App Installer" from the Store, or set apps.manager to choco.
  • A URL app didn't install silently — set its silentArgs explicitly in the config apps.fromUrl entry.
  • Office phase skipped — assets\office\setup.exe (ODT) is missing.
  • Resume didn't fire after reboot — confirm identity.localAdmin.autoLogonForSetup is true and TOTL_LOCAL_ADMIN_PWD is set; otherwise log in as the admin and the scheduled task runs at logon.
  • Logs — C:\ProgramData\TotlProvision\Logs\.

G. Security operations (Phase 2)

  • Force-clear autologon credentials on a box (e.g. after an interrupted run): powershell -File .\src\Invoke-Provision.ps1 -ClearCredentials
  • What the watchdog does. While autologon is enabled, a SYSTEM task TotlProvision-CredCleanup runs at every startup. It leaves credentials in place while the run is actively heartbeating, and clears them once the run finalizes or stalls past security.credentialCleanup.staleMinutes (default 60). It removes itself once it has cleaned up or the run finalizes normally.
  • Prompt instead of .env. Set security.secretSource: "prompt" in the client config to be asked for the local-admin password at runtime rather than shipping it in .env on the USB.
  • Tune the autologon window with security.autoLogon.maxLogonCount (default 5).
  • Sign a release before distribution: .\scripts\Sign-TotlRelease.ps1 -Thumbprint <codeSigningCertThumbprint> (add -WhatIf to preview).