iControl Boot · test guide

Test your diskless setup step by step

Separate walkthroughs for Windows checks, new diskless server installation and two-PC laboratory acceptance.

01. Part 1 · Windows test package

A Windows 10/11 x64 test PC or VM and Windows PowerShell 5.1 / PowerShell 7 are sufficient. No Python installation is needed.

LABWindows x64 · v1.4.88 · 67.6 MB

Windows build and native DPAPI checks passed. PXE, UI launch and persistence through three reset boots require laboratory testing.

ZIP SHA256de947c7c48b3ef2d6cfa74fa8aad6dddd0b0f4c4207082a0ff189f50e2791384
  1. 1
    Download and extract the ZIP. Keep Agent/ and deployment/ together. Double-click deployment/START-LAB.cmd to open the local tools menu.
  2. 2
    Verify the archive. Open PowerShell in the extracted package root and copy this command. Filename and SHA256 are filled in; change ArchivePath if the ZIP is outside Downloads. Expected result: archive_verified, exit 0.
    PowerShell
    $zip = "$env:USERPROFILE\Downloads\iControl-agent-boot-lab-1.4.88-win-x64-20261101T073451Z-9250b86b.zip"
    $expected = 'de947c7c48b3ef2d6cfa74fa8aad6dddd0b0f4c4207082a0ff189f50e2791384'
    if ((Get-FileHash -LiteralPath $zip -Algorithm SHA256).Hash -ieq $expected) {
      powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\deployment\lab-tools.ps1 -Action Verify -ArchivePath $zip -ExpectedSha256 $expected
    } else { throw 'ZIP SHA256 mismatch' }
  3. 3
    Check the result. The verifier checks the hash, manifest, unsafe paths and file integrity without extracting or executing anything. For blocked / exit 2, check the ZIP and selected path.

This package contains the Windows agent. Prepare the Linux boot-controller and PXE/iSCSI infrastructure separately for Part 2.

02. Install the new diskless server

Detailed Uzbek instructions for a teammate: inspect the existing server, prepare isolated Linux, build the Windows image, connect two PCs and verify three resets.

  1. 1
    Identify the current system first. The server may run Windows. Part 1 collects information only; later parts require a separate Linux/ZFS test environment.
  2. 2
    Check which machine each step belongs to. Linux server, Windows builder and client PC actions are separated, with commands, expected results and stop conditions.

03. Windows testing without a lab

Eight steps for an ordinary Windows 10/11 x64 PC or VM. Use PowerShell 5.1 or 7 to check the ZIP, Windows preflight, DPAPI and a diagnostics report in order.

  1. 1
    Download and extract the ZIP. Use the ZIP button above for the current package. Extract to an iControl-Lab folder inside Downloads, with Agent and deployment directly inside it. These commands use that location.
  2. 2
    Verify ZIP integrity. Open PowerShell and copy the ready-to-use command below. Filename and SHA256 are filled in; adjust $zip if the archive is outside Downloads. Expect archive_verified. Stop on a hash mismatch. hardware_verified:false and ui_launch_verified:false mean hardware and UI acceptance remain separate checks.
    PowerShell
    cd "$env:USERPROFILE\Downloads\iControl-Lab"
    $zip = "$env:USERPROFILE\Downloads\iControl-agent-boot-lab-1.4.88-win-x64-20261101T073451Z-9250b86b.zip"
    $expected = 'de947c7c48b3ef2d6cfa74fa8aad6dddd0b0f4c4207082a0ff189f50e2791384'
    if ((Get-FileHash -LiteralPath $zip -Algorithm SHA256).Hash -ieq $expected) {
      powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\deployment\lab-tools.ps1 -Action Verify -ArchivePath $zip -ExpectedSha256 $expected
    } else { throw 'ZIP SHA256 mismatch' }
  3. 3
    Run Windows preflight. Double-click deployment\START-LAB.cmd and choose 2 — Windows preflight. Elevation is not required. windows, architecture, powershell and dpapi must be passed, with overall status ready. For blocked, read that check’s hint. The menu runs one action; reopen it for the next check.
  4. 4
    Create the DPAPI test file. Use Win + R to open powershell.exe -NoProfile -ExecutionPolicy Bypass, then run the command below. Bypass applies only to this PowerShell process. Expect dpapi-test.bin and DPAPI test file created. This non-secret challenge does not touch a real AgentKey. Close the PowerShell window afterward.
    PowerShell
    & {
      $ErrorActionPreference = 'Stop'
      cd "$env:USERPROFILE\Downloads\iControl-Lab"
      . .\deployment\boot-acceptance-tools.ps1
      $path = "$env:USERPROFILE\Downloads\iControl-Lab\dpapi-test.bin"
      $data = [Text.Encoding]::UTF8.GetBytes('icontrol-lab-test')
      [IO.File]::WriteAllBytes($path, (Protect-IControlAcceptanceData $data))
      'DPAPI test file created'
    }
  5. 5
    Verify in a new PowerShell window. Under the same Windows account, use Win + R to open a new powershell.exe -NoProfile -ExecutionPolicy Bypass window. Run the command below; expect DPAPI OK. Keep the test file for now.
    PowerShell
    & {
      $ErrorActionPreference = 'Stop'
      cd "$env:USERPROFILE\Downloads\iControl-Lab"
      . .\deployment\boot-acceptance-tools.ps1
      $path = "$env:USERPROFILE\Downloads\iControl-Lab\dpapi-test.bin"
      $data = Unprotect-IControlAcceptanceData ([IO.File]::ReadAllBytes($path))
      if ([Text.Encoding]::UTF8.GetString($data) -ceq 'icontrol-lab-test') {
        'DPAPI OK'
      } else { throw 'DPAPI test failed' }
    }
  6. 6
    Repeat after an ordinary Windows restart. Save your work and restart the computer. Sign in to the same Windows account, open a new PowerShell window as above and run this again. Expect DPAPI OK. This checks a normal local restart; diskless-reset acceptance is a separate laboratory test.
    PowerShell
    & {
      $ErrorActionPreference = 'Stop'
      cd "$env:USERPROFILE\Downloads\iControl-Lab"
      . .\deployment\boot-acceptance-tools.ps1
      $path = "$env:USERPROFILE\Downloads\iControl-Lab\dpapi-test.bin"
      $data = Unprotect-IControlAcceptanceData ([IO.File]::ReadAllBytes($path))
      if ([Text.Encoding]::UTF8.GetString($data) -ceq 'icontrol-lab-test') {
        'DPAPI OK'
      } else { throw 'DPAPI test failed' }
    }
  7. 7
    Create a diagnostics ZIP. Reopen START-LAB.cmd, choose 4 — Diagnostics ZIP, then W — Windows. A new iControl-support-....zip appears on Desktop. It should contain preflight.json, events.json and README.txt. files_scanned:0 is normal if the agent has not run on this PC. The report stays local and is not uploaded automatically.
  8. 8
    Remove the test file. After completing all checks, run this in PowerShell. It removes only the dpapi-test.bin created by this walkthrough. You can keep the package, original ZIP and diagnostics report.
    PowerShell
    Remove-Item -LiteralPath "$env:USERPROFILE\Downloads\iControl-Lab\dpapi-test.bin"

Success criteria: archive_verified → ready → DPAPI OK in a new window and after a normal restart → a diagnostics ZIP. PXE and three diskless resets are tested in the laboratory phase.

04. Automatic preflight

Read-only checks: no Windows settings, disks, tasks, markers or identity are changed. AgentKey and config contents are not read.

  1. 1
    Windows check. Start without a lab. Checks x64 OS/process, PowerShell and an in-memory DPAPI roundtrip under the current Windows account.
    PowerShell
    powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\deployment\lab-tools.ps1 -Action Check -Mode Windows
  2. 2
    Diskless check. When the lab is ready, run elevated as the kiosk account itself. Checks image policy, OS iSCSI target, private disk/serial, manifest, UUID firmware binding, task account and autologin/shell.
    PowerShell
    powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\deployment\lab-tools.ps1 -Action Check -Mode Diskless -InstallDir C:\iControl\Agent -StateRoot P:\iControl
  3. 3
    Read the status. ready / exit 0: checks for this mode passed. pending / exit 3: complete the separate agent setup/reboot gate. maintenance / exit 3: a maintenance boot was detected. blocked / exit 2: follow the reported hint.

Preflight does not replace the agent startup gate or three-reset acceptance. An unavailable UUID firmware identity requires operator review.

05. Part 2 · diskless laboratory

Prepare a Linux boot-controller, two test PCs, a Windows maintenance image, a persistent kiosk profile and a private state disk per PC.

  1. 1
    Prepare a pilot image. Copy Agent/ to C:\Lab\Agent inside the image. Disable iCafe billing/lock autostart in that pilot image. Prepare explorer.exe shell, Windows autologin and a kiosk account that already has Administrator rights.
  2. 2
    Stage the agent. Keep the deployment scripts together and run elevated. Replace LAB\Kiosk and YOUR-PILOT-API.example with your test account and pilot API URL. The IQN prefix must match the controller.
    PowerShell
    .\deployment\prepare-icontrol-boot-image.ps1 `
      -AgentBuildDir C:\Lab\Agent `
      -KioskUser 'LAB\Kiosk' `
      -IqnPrefix 'iqn.2026-10.uz.i-control.lab' `
      -StateRoot P:\iControl `
      -ServerUrl 'https://YOUR-PILOT-API.example' `
      -ICafeDisabledOnPilotImage
  3. 3
    Keep the shared image clean. Do not copy AgentKey, club enrollment tokens, another PC’s config or DPAPI files into it. Full prerequisites are in deployment/ICONTROL-BOOT.md inside the ZIP.

06. Identity for each PC

An ordinary boot exports the OS at LUN 0 and that PC’s private state disk at LUN 1. Maintenance boots do not attach the state disk.

  1. 1
    Export a controller manifest. Use station-identity pc01 to create pc01.boot-station.json. Create a separate manifest for pc02 and transfer each to the matching test PC through a trusted administrative route.
  2. 2
    Verify the state disk. Manually prepare only the blank private disk with the expected serial and assign P:. Never select a boot/system disk. The script below does not format disks.
  3. 3
    Install the manifest. Stop the agent and run from a separate Windows administrator account. Use pc02’s own manifest on pc02.
    PowerShell
    .\deployment\initialize-icontrol-boot-state.ps1 -ManifestPath C:\Setup\pc01.boot-station.json -StateRoot P:\iControl
  4. 4
    Start the agent. The first kiosk-account boot records the binding and requests a reboot. After the gate passes on the next distinct boot, use per-PC provisioning. Confirm separate identities in the dashboard.

07. DPAPI · three reset boots

Use the same kiosk account as the agent. Keep the private disk, Windows profile and account unchanged.

  1. 1
    Begin once. Run Begin from the extracted package folder.
    PowerShell
    .\deployment\test-icontrol-boot-state.ps1 -Mode Begin -StateRoot P:\iControl
  2. 2
    Perform three actual resets. After each controller-managed reset boot, run Verify. Repeating it during one Windows boot does not count as another reset.
    PowerShell
    .\deployment\test-icontrol-boot-state.ps1 -Mode Verify -StateRoot P:\iControl
  3. 3
    Read the result. Exit 3 / pending_reboots: another distinct reset is needed. Exit 0 / verified: the three-reset test passed. Exit 2 / blocked: investigate the disk, manifest, account or DPAPI failure.

Preserve the test history and markers on failure; do not delete them to bypass the gate.

08. Diagnostics ZIP

Choose option 4 in START-LAB or create a new support report with a command.

  1. 1
    Create a report. This example is for diskless. Use -Mode Windows for a standard host check. Existing reports are never overwritten; choose another filename. The menu uses a new Desktop filename automatically.
    PowerShell
    powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\deployment\lab-tools.ps1 -Action Report -Mode Diskless -InstallDir C:\iControl\Agent -StateRoot P:\iControl -OutputPath "$env:USERPROFILE\Desktop\iControl-support.zip"
  2. 2
    Report contents. preflight.json contains allowlisted statuses. events.json contains category counts from at most 256 KiB of each of the latest four agent logs. README.txt explains scope. No raw logs, tokens, AgentKey, config contents, usernames, SID, serial or DPAPI files are included.
  3. 3
    Review and share yourself. The report stays local and is never uploaded automatically. Share it with support if needed. files_scanned=0 means no readable agent logs were found; preflight can still describe a blocked machine.

09. Acceptance checklist

Record the following for both test PCs.

  1. 1
    Identity and connection. pc01 and pc02 appear separately; after three resets both connect without asking for AgentKey again.
  2. 2
    Maintenance and blocking. Maintenance boots exit before sessions/kiosk start. A missing state disk or another PC’s manifest blocks startup.
  3. 3
    Test session. Check a dedicated session, lock/unlock and booking flow in the pilot club.
  4. 4
    Report a problem. Record the step, JSON status/exit code, Windows version and test PC name. Do not send AgentKey, tokens or DPAPI files.

Ready to test?

Extract the ZIP and complete the Windows checks first. Continue to diskless testing when the laboratory is ready.