xetup/SPEC.md

MSP Windows Deployment - Specification

Purpose: Automated preparation of new Windows 10/11 computers for X9.cz clients

---

Overview

xetup.exe replaces ~3 hours of manual computer setup. GUI launcher embeds PowerShell scripts, runs them sequentially, handles reboot cycles, sends email report when done. Settings are applied to Default Profile (NTUSER.DAT) so every new user inherits them.

---

Prerequisites

• Windows 10 or Windows 11 (x64)
• Run as Administrator
• Internet connection (for winget installs, Atera agent, Windows Update)
• Post-OOBE (fully installed Windows with at least one user account)

---

Step execution order

#	Step	Script	Notes
00	Admin account	00-admin-account.ps1	adminx9, no password, hidden
08	Windows activation	08-activation.ps1	OA3 → config key → GVLK fallback
01	Bloatware removal	01-bloatware.ps1	AppX + Capabilities + Features
02	Software install	02-software.ps1	Parallel winget + Atera + PDF default
03	System registry	03-system-registry.ps1	HKLM tweaks, Edge, powercfg, WPAD
04	Profile + personalization	04-default-profile.ps1	NTUSER.DAT + HKCU + theme
07	BackInfo	07-backinfo.ps1	System info wallpaper overlay
10	Network	10-network.ps1	Private profile, ping, discovery
11	Dell Update	11-dell-update.ps1	Auto-skip on non-Dell HW
09	PC identity	09-pc-identity.ps1	Rename + C:\X9 (reboot on rename)
12	Windows Update	12-windows-update.ps1	Multi-round reboot cycle

---

Step 00 - Admin account

Creates local admin account adminx9:

• No password (empty) - account is hidden, only accessible to technicians
• FullName = "X9.cz s.r.o." (via ADSI)
• Added to Administrators group
• Hidden from login screen (SpecialAccounts\UserList = 0)
• Password never expires

---

Step 08 - Windows activation

Priority: OA3 embedded key (BIOS/UEFI) → config.json productKey → GVLK by edition. Optional KMS server via config.json. Skips if already activated (LicenseStatus = 1).

---

Step 01 - Bloatware removal

Removes ~35 AppX packages (Cortana, Copilot, Teams, Xbox, Skype, News, etc.), ~14 Windows Capabilities (Fax, IE, WordPad, etc.), and Optional Features (PowerShell 2.0, Recall). Calculator intentionally kept.

Three GUI feature toggles gate removal:

• standardBloatware (default on) - the bulk list above.
• removeNewOutlook (default on) - the new Outlook for Windows app (Microsoft.OutlookForWindows). Classic Outlook from M365 is a Win32 app and is never touched.
• removeSnippingTool (default OFF) - Snipping Tool across all three lists (ScreenSketch app + legacy capability + legacy feature). Kept by default as a common productivity tool, like Calculator.

---

Step 02 - Software installation

Parallel winget installs (Start-Job). Every install uses --source winget to bypass the msstore source, which fails on fresh Win11 ISOs (stale App Installer cert, 0x8a15005e):

Software	Winget ID
7-Zip	7zip.7zip
Adobe Acrobat Reader 64-bit	Adobe.Acrobat.Reader.64-bit
OpenVPN Connect	OpenVPNTechnologies.OpenVPNConnect

After Acrobat: UCPD driver stopped, .pdf → AcroExch.Document.DC set via HKCR, UCPD restarted. On Win11 24H2 UCPD is a protected service and the stop fails (logged WARN, not ERROR); the system-wide HKCR write succeeds regardless.

Atera RMM agent: downloaded from x9.servicedesk.atera.com, installed under NT AUTHORITY\SYSTEM via a one-shot scheduled task (msiexec /qn). Under SYSTEM the agent registers silently with no interactive MFA prompt. Verified via the AteraAgent service (Get-Service), with a path check (incl. C:\ProgramData) as fallback.

---

Step 03 - System registry (HKLM)

Always applied: password max age unlimited, timezone (Central Europe Standard Time).

Feature-toggled sections:

• systemTweaks: BypassNRO, disable Teams auto-install, Widgets, GameDVR, Recall, Copilot search, Smart App Control (VerifiedAndReputablePolicyState=0, permanent)
• edgePolicies: mandatory only (HideFirstRunExperience, DefaultBrowserSettingEnabled, DiagnosticData, FeedbackSurveysEnabled) + initial_preferences file for UI defaults (favorites bar, no home button, no search suggestions, clean NTP, no rewards/shopping/collections). initial_preferences is read by Edge once on first profile creation - user can override freely.
• oneDriveUninstall: removes consumer OneDrive (no policy block - M365 can reinstall)
• powercfg: hibernate off; standby-ac=0, monitor-ac=60, standby-dc=30, monitor-dc=15
• proxyDisable: WPAD auto-detect off

---

Step 04 - Default Profile + Personalization

Single hive load of C:\Users\Default\NTUSER.DAT. All changes applied to both Default hive and current HKCU. Feature-toggled sections:

• taskbarTweaks: left alignment, hide Search/Copilot/TaskView/Widgets/Chat, show all tray icons, taskbar layout XML per ProfileType (default/admin/user), NumLock on. File Explorer is pinned via its AppUserModelID (DesktopApplicationID="Microsoft.Windows.Explorer"), not a custom .lnk - a hand-made shortcut launched a second Explorer and could not be unpinned.
• startMenuTweaks: empty pins, disable Bing search, disable Copilot, disable GameDVR
• explorerTweaks: show extensions, LaunchTo=ThisPC, hide Recent/Frequent, full path

Keyboard (always): CZ primary + US secondary - Set-WinUserLanguageList (current user) plus the Preload key (1=00000405 CZ, 2=00000409 US) in the Default hive and HKU.DEFAULT.

Personalization (always): Custom mode (dark shell / light apps), accent #223B47 set via AccentColor AND AccentPalette (the palette is required or Win11 drops the custom accent on Start/taskbar), ColorPrevalence on for Start/taskbar and title bars/borders, transparency off, solid wallpaper #223B47 (BackInfo overwrites on logon). Written to the Default hive (new users), the current user (HKCU) and HKU.DEFAULT (lock/welcome screen) so all profiles match.

---

Step 07 - BackInfo

Copies BackInfo.exe + INI to C:\Program Files\Backinfo. Detects OS, writes OSName to registry. Creates startup shortcut for all users. BackInfo renders system info BMP as desktop wallpaper on every logon. Background is solid #223B47 (BackInfo.ini BackgroundColor = 4668194; BackInfo uses a COLORREF / 0x00BBGGRR / BGR value, so #223B47 = 7165536 + 59256 + 34 = 4668194. The RGB value 2243399 rendered olive-brown). Because BackInfo paints a centered bitmap, step 04 also sets the solid desktop background color (#223B47) in the Default hive, the current user, HKU.DEFAULT and every existing profile - otherwise a sub-screen bitmap shows a black border around it.

---

Step 10 - Network

Sets all connected adapters to Private profile. Enables ICMP echo (ping) and Network Discovery firewall rules. Network Discovery is matched by its resource-string group (-Group "@FirewallAPI.dll,-32752"), not the localized display name, so it works on non-English (e.g. Czech) Windows.

---

Step 11 - Dell Command | Update

Detects Dell hardware via Win32_ComputerSystem.Manufacturer. On non-Dell: skips silently. On Dell: installs DCU Universal via winget, runs dcu-cli.exe /applyUpdates with -reboot=disable. Feature-toggled: drivers/firmware and BIOS separately. Exit 9 when BIOS/firmware updates are staged (finalize on next restart).

---

Step 09 - PC identity

Creates C:\X9\ directory (Logs, Scripts, Assets) with custom folder icon. Sets computer description. Renames computer if config.json pcName is set and differs from current. Exit 9 only when rename actually happened (restart required).

---

Step 12 - Windows Update

Installs PSWindowsUpdate module, runs one update pass. Exit 9 when updates were installed (reboot needed for next round). Exit 0 when fully up to date. xetup state machine handles the reboot cycle automatically. Installed updates are logged via their Result/Title properties (logging the raw objects printed "System.__ComObject").

---

Config structure

{
  "deployment": { "pcName": "", "pcDescription": "", "timezone": "...", "profileType": "default" },
  "adminAccount": { "username": "adminx9" },
  "activation": { "productKey": "", "kmsServer": "" },
  "software": { "install": [{ "name": "...", "wingetId": "..." }] },
  "steps": { "adminAccount": true, ... },
  "features": { "bloatware": { "standardBloatware": true, "removeNewOutlook": true, "removeSnippingTool": false }, "software": { "wingetInstalls": true, ... }, ... },
  "bloatware": { "keepPackages": ["Microsoft.WindowsCalculator"] }
}

---

Email report

Sent via SMTP2Go at end of deployment. HTML with per-step status table, timestamps, OK/ERROR/SKIPPED counts. Subject: "xetup report HOSTNAME". From: xetup@x9.cz, To: net@x9.cz.

---

Code signing (CI)

The Forgejo Actions release workflow signs xetup.exe on every push to main (and via workflow_dispatch): build → sign → publish. Signing uses Azure Trusted Signing (certificate "X9.cz s.r.o.") through jsign, with an RFC3161 timestamp (timestamp.acs.microsoft.com). Trusted Signing certs are short-lived (~3 days); the timestamp keeps the signature valid past expiry. Only the Entra client secret is a Forgejo secret (AZURE_CLIENT_SECRET); the signed binary is published as the "latest" release asset.