x9/xetup
1
0
Fork 0
Code Issues 17 Pull requests Projects Releases 2 Packages Wiki Activity Actions
xetup/SPEC.md
Filip Zubik c42943cfa8 PS scripts, web platform, Forgejo CI, xetup.exe launcher 
Initial deployment suite for X9.cz MSP Windows 10/11 deployment:
- PowerShell scripts 00-11: admin account, bloatware removal, software (winget+Atera),
  system registry tweaks, default profile, personalization, scheduled tasks,
  BackInfo desktop info, Windows activation, PC identity/rename, network, Dell Update
- Web platform: xetup.x9.cz (nginx), spec/annotation page, /dl shortlink, GitHub mirror
- Forgejo Actions CI: auto-build xetup.exe on push, publish to releases/latest
- Go xetup.exe: embeds all scripts/assets, per-feature checkboxes, load/save config
2026-04-16 14:49:41 +02:00

293 lines
9.8 KiB
Markdown
Raw Permalink Blame History

# MSP Windows Deployment - Specification (SPEC.md)
> Version: 0.2 (draft)
> Author: X9.cz
> Purpose: Automated preparation of new Windows 10/11 computers for clients
---
## Overview
Script replaces ~3 hours of manual computer setup. Run once as Administrator on
already-installed Windows, performs everything automatically, saves result to Default
Profile so settings apply to every subsequent user.
---
## Prerequisites
- Windows 10 or Windows 11 (x64)
- Run as Administrator
- Internet connection (for winget installs)
- Computer received either as clean OEM install or with manufacturer pre-installed Windows
---
## What the script does NOT do
- Does not install Windows (not an autounattend.xml for clean install)
- Does not create images
- Does not manage the computer ongoing (one-time deployment)
---
## Script structure
Script is divided into steps. Each step logs its result. Steps can be skipped with switches.
---
## STEP 0a - Admin account
Creates local admin account `adminx9`:
- Password from `config.json` (`adminAccount.password`)
- Added to Administrators group
- Password never expires, user cannot change password
- Hidden from Windows login screen (SpecialAccounts\UserList = 0)
---
## STEP 0b - Windows activation
Activates Windows using product key from config:
- Key from `config.json` (`activation.productKey`) - set to real MAK/retail key for production
- Falls back to GVLK (KMS client key) matched by detected OS edition
- Optional KMS server via `activation.kmsServer`
- If already activated, skips silently
---
## STEP 1 - Bloatware removal
### 1a - AppX packages (UWP apps)
Removed for all users (-AllUsers) and from provisioned packages (so they do not return for new users).
| Package | Description |
|---|---|
| Microsoft.Microsoft3DViewer | 3D Viewer |
| Microsoft.BingSearch | Bing Search |
| Microsoft.WindowsCamera | Camera |
| Clipchamp.Clipchamp | Clipchamp video editor |
| Microsoft.WindowsAlarms | Clock / Alarm |
| Microsoft.Copilot | Copilot AI |
| Microsoft.549981C3F5F10 | Cortana |
| Microsoft.Windows.DevHome | Dev Home |
| MicrosoftCorporationII.MicrosoftFamily | Family Safety |
| Microsoft.WindowsFeedbackHub | Feedback Hub |
| Microsoft.Edge.GameAssist | Game Assist |
| Microsoft.GetHelp | Help |
| Microsoft.Getstarted | Tips / Get Started |
| microsoft.windowscommunicationsapps | Mail and Calendar |
| Microsoft.WindowsMaps | Maps |
| Microsoft.MixedReality.Portal | Mixed Reality |
| Microsoft.BingNews | News |
| Microsoft.MicrosoftOfficeHub | Office Hub |
| Microsoft.Office.OneNote | OneNote |
| Microsoft.OutlookForWindows | Outlook (new) |
| Microsoft.Paint | Paint (new UWP) |
| Microsoft.MSPaint | Paint (legacy) |
| Microsoft.People | People |
| Microsoft.Windows.Photos | Photos |
| Microsoft.PowerAutomateDesktop | Power Automate |
| MicrosoftCorporationII.QuickAssist | Quick Assist |
| Microsoft.SkypeApp | Skype |
| Microsoft.ScreenSketch | Snipping Tool |
| Microsoft.MicrosoftSolitaireCollection | Solitaire |
| Microsoft.MicrosoftStickyNotes | Sticky Notes |
| MicrosoftTeams / MSTeams | Teams (personal) |
| Microsoft.Todos | To Do |
| Microsoft.WindowsSoundRecorder | Voice Recorder |
| Microsoft.Wallet | Wallet |
| Microsoft.BingWeather | Weather |
| Microsoft.WindowsTerminal | Windows Terminal |
| Microsoft.Xbox.TCUI | Xbox UI |
| Microsoft.XboxApp | Xbox |
| Microsoft.XboxGameOverlay | Xbox Game Overlay |
| Microsoft.XboxGamingOverlay | Xbox Gaming Overlay |
| Microsoft.XboxIdentityProvider | Xbox Identity |
| Microsoft.XboxSpeechToTextOverlay | Xbox Speech |
| Microsoft.GamingApp | Gaming App |
| Microsoft.YourPhone | Phone Link |
| Microsoft.ZuneMusic | Music |
| Microsoft.ZuneVideo | Movies and TV |
NOTE: Microsoft.WindowsCalculator is intentionally KEPT.
### 1b - Windows Capabilities
| Capability | Description |
|---|---|
| Print.Fax.Scan | Fax and Scan |
| Language.Handwriting | Handwriting |
| Browser.InternetExplorer | Internet Explorer |
| MathRecognizer | Math Input |
| OneCoreUAP.OneSync | OneSync |
| OpenSSH.Client | OpenSSH client |
| Microsoft.Windows.MSPaint | Paint (Win32) |
| Microsoft.Windows.PowerShell.ISE | PowerShell ISE |
| App.Support.QuickAssist | Quick Assist |
| Microsoft.Windows.SnippingTool | Snipping Tool |
| App.StepsRecorder | Steps Recorder |
| Hello.Face.* | Windows Hello face |
| Media.WindowsMediaPlayer | Windows Media Player |
| Microsoft.Windows.WordPad | WordPad |
### 1c - Windows Optional Features
| Feature | Description |
|---|---|
| MediaPlayback | Media playback |
| MicrosoftWindowsPowerShellV2Root | PowerShell 2.0 |
| Microsoft-RemoteDesktopConnection | RDP client |
| Recall | Windows Recall (AI) |
| Microsoft-SnippingTool | Snipping Tool (feature) |
---
## STEP 2 - Software installation (winget)
| Software | Winget ID | Notes |
|---|---|---|
| 7-Zip | `7zip.7zip` | OK |
| Adobe Acrobat Reader | `Adobe.Acrobat.Reader.64-bit` | OK, see note |
| OpenVPN Connect | `OpenVPNTechnologies.OpenVPNConnect` | OK |
| ... | ... | TODO: complete list |
> Adobe Acrobat Reader: After install, script sets .pdf -> AcroRd32 as default.
> Scheduled task PDF-DefaultApp restores this association on every logon as a guard
> against Edge overwriting it.
> BackInfo: NOT used. Replaced by custom PowerShell scheduled task DesktopInfo.
> See STEP 7.
---
## STEP 3 - System settings (HKLM - applies to whole system)
| Setting | Value | Notes |
|---|---|---|
| Disable NRO (bypass network check) | HKLM\...\OOBE\BypassNRO = 1 | |
| Disable auto-install of Teams | ConfigureChatAutoInstall = 0 | |
| Disable Cloud Optimized Content | DisableCloudOptimizedContent = 1 | |
| Disable Widgets (News and Interests) | HKLM\...\Dsh\AllowNewsAndInterests = 0 | |
| Edge - hide First Run Experience | HKLM\Policies\Edge\HideFirstRunExperience = 1 | |
| Passwords - no expiration | net accounts /maxpwage:UNLIMITED | |
| Time zone | Central Europe Standard Time | |
| OneDrive - remove | Delete OneDriveSetup.exe + Start Menu lnk | |
| Outlook (new) - disable auto-install | Delete UScheduler registry key | |
| Disable GameDVR | AppCaptureEnabled = 0 | |
---
## STEP 4 - Default Profile (NTUSER.DAT)
Settings applied to C:\Users\Default\NTUSER.DAT - inherited by every new user on first logon.
Method: script loads Default hive (reg load), makes changes, unloads (reg unload).
| Setting | Key / Value | Description |
|---|---|---|
| Taskbar - align left | TaskbarAl = 0 | Win11 default is center |
| Taskbar - hide Search box | SearchboxTaskbarMode = 0 | |
| Taskbar - hide Copilot button | ShowCopilotButton = 0 | |
| Taskbar - hide Task View button | ShowTaskViewButton = 0 | |
| Taskbar - hide Widgets | TaskbarDa = 0 | |
| Taskbar - hide Chat/Teams button | TaskbarMn = 0 | |
| Taskbar - show all tray icons | Scheduled task ShowAllTrayIcons | Runs on every logon |
| Taskbar - empty pinlist | TaskbarLayoutModification.xml | Removes default pinned apps |
| Explorer - show file extensions | HideFileExt = 0 | |
| Explorer - open to This PC | LaunchTo = 1 | Instead of Quick Access |
| Start menu - empty pins | ConfigureStartPins = {"pinnedList":[]} | Win11 |
| Start menu - disable Bing results | DisableSearchBoxSuggestions = 1 | |
| Copilot - disable | TurnOffWindowsCopilot = 1 | |
| GameDVR - disable | AppCaptureEnabled = 0 | |
| OneDrive - remove RunOnce key | Delete OneDriveSetup from Run | |
| Num Lock on startup - enable | InitialKeyboardIndicators = 2 | |
| Accent color on title bars | ColorPrevalence = 1 | |
---
## STEP 5 - Personalization (colors, wallpaper)
Applied to both Default Profile and currently logged-in user.
| Setting | Value |
|---|---|
| System theme (taskbar, Start) | Dark |
| App theme | Light |
| Accent color | #223B47 (dark blue-gray) |
| Accent color on Start and taskbar | Yes |
| Accent color on title bars | Yes |
| Transparency | Disabled |
| Wallpaper | Solid color #223B47 (no image) |
NOTE: DesktopInfo scheduled task (STEP 7) will overwrite the wallpaper with a system
info BMP. The solid color here is only a fallback if DesktopInfo is not running.
---
## STEP 6 - Scheduled Tasks
| Task | Trigger | Purpose |
|---|---|---|
| ShowAllTrayIcons | Every logon, every 1 min | Show all icons in system tray (Win11) |
| UnlockStartLayout | Once after layout is applied | Unlock Start menu layout |
| PDF-DefaultApp | Every logon | Restore .pdf -> Adobe Reader if Edge overwrote it |
| DesktopInfo | Every logon | Render system info onto desktop wallpaper |
---
## STEP 7 - DesktopInfo (BackInfo replacement)
Custom PowerShell scheduled task. No external dependencies.
**What it displays:**
- Computer name (hostname)
- IP address
- Windows version and build
- Logged-in username
- Deployment date
**How it works:**
1. PS script collects system info
2. Renders text onto bitmap via WPF / System.Drawing
3. Saves BMP to C:\Windows\Setup\Scripts\desktopinfo.bmp
4. Sets BMP as desktop wallpaper via SystemParametersInfo
5. Runs on every user logon via Scheduled Task
**Why not BackInfo:**
- BackInfo has Win11 rendering issues requiring registry hacks
- External EXE dependency is hard to distribute
- Custom PS solution = full control, no dependencies, works on Win10 and Win11
---
## STEP 8 - Logging and output
- Every step writes to C:\Windows\Setup\Scripts\Deploy.log
- Format: [HH:mm:ss] Step description - OK / ERROR: ...
- At end: summary report (how many steps OK, how many failed)
- Log stays on disk for diagnostics
---
## Script switches
| Switch | Behavior |
|---|---|
| `-SkipBloatware` | Skip step 1 |
| `-SkipSoftware` | Skip step 2 |
| `-SkipDefaultProfile` | Skip step 4 |
| `-DryRun` | Run through steps without changes, log only |
---
## Open questions
| # | Question | Status |
|---|---|---|
| 1 | BackInfo replacement | DONE - custom PS scheduled task DesktopInfo |
| 2 | Complete SW list for winget | TODO |
| 3 | Per-client variability via config.json | FUTURE |
| 4 | Admin account adminx9 - script or manual? | DONE - script (00-admin-account.ps1) |
Reference in a new issue View git blame Copy permalink