From e8a612a5b8dfc9827ddc2c2ef6c4177cf95b1398 Mon Sep 17 00:00:00 2001 From: imacks Date: Sat, 3 Mar 2018 18:03:18 +0800 Subject: [PATCH] added docs More docs. --- README.md | 19 +++---- docs/feature-list.md | 35 ++++++++++++ docs/walkthrough-vm.md | 64 ++++++++++++++++++++++ docs/walkthrough-winpe.md | 81 ++++++++++++++++++++++++++++ docs/walkthrough.md | 110 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 297 insertions(+), 12 deletions(-) create mode 100644 docs/feature-list.md create mode 100644 docs/walkthrough-vm.md create mode 100644 docs/walkthrough-winpe.md create mode 100644 docs/walkthrough.md diff --git a/README.md b/README.md index 6a6a056..836babe 100644 --- a/README.md +++ b/README.md @@ -3,22 +3,17 @@ Windows Image Customization Tool WindowsBuilder is a tool for servicing Windows `WIM` image. You can now deep customize your Windows installation with ease! ```batchfile -C:\> md win10 && cd win10 -C:\repo\> powershell -Command "& { wget https://raw.githubusercontent.com/buildcenter/WindowsBuilder/master/scaffold.ps1 -UseBasicParsing | iex }" -C:\repo\> build configure -C:\repo\> build mount -C:\repo\> build -C:\repo\> build dismount +C:\> md WindowsBuilder && cd WindowsBuilder +C:\WindowsBuilder\> powershell -Command "& { wget https://raw.githubusercontent.com/buildcenter/WindowsBuilder/master/scaffold.ps1 -UseBasicParsing | iex }" +C:\WindowsBuilder\> build configure +C:\WindowsBuilder\> build mount +C:\WindowsBuilder\> build +C:\WindowsBuilder\> build dismount ``` Congrats! Your shiny new Windows image is ready! - -How to Customize -================ -First make a copy of `/src/global.bsd` and name it something meaningful, like `win10.bsd`. Edit it with reference to the schema described below. - -Your assets lives under `/resource` by default, so copy them there. +We have prepared a [detailed walkthrough ](./docs/walkthrough.md) here. We Need Undo diff --git a/docs/feature-list.md b/docs/feature-list.md new file mode 100644 index 0000000..b27acad --- /dev/null +++ b/docs/feature-list.md @@ -0,0 +1,35 @@ +Feature List +============ +This document tracks the features available and our roadmap. + +[x] Account Pictures +[x] Appx + [x] Removal +[-] Custom BSOD color + [x] Legacy + [ ] Win10 +[x] Windows capability + [x] Removal +[x] Copy files +[x] Cursor scheme +[x] Drivers + [x] Add +[x] Host file + [x] Domain blocking +[x] Lockscreen picture +[x] OEM info +[x] OEM license +[x] Optional features +[x] Package + [x] Unprotect + [x] Remove +[x] Regional settings +[x] Sound themes +[x] Startup sound + [x] Enable + [ ] Customize +[x] Theme color + [x] Default user +[x] TTS + [x] Enable Eva and David +[x] Wallpaper \ No newline at end of file diff --git a/docs/walkthrough-vm.md b/docs/walkthrough-vm.md new file mode 100644 index 0000000..5a853ca --- /dev/null +++ b/docs/walkthrough-vm.md @@ -0,0 +1,64 @@ +Walkthrough +=========== +Congrats for completing [the walkthrough](./walkthrough.md)! We are here to deploy your image to a VM for Hyper-V. + +You need to install Hyper-V on your Windows PC to complete this walkthrough. + + +Creating a VHD +-------------- +This VHD will be used to boot your VM. Run Powershell with administrative privileges and type the following: + +```powershell +Set-ExecutionPolicy Unrestricted +New-VHD -Path C:\WindowsBuilder\working\output\Win10.vhdx -SizeBytes 64GB -Dynamic +ipmo C:\WindowsBuilder\provisioning\WindowsProvisioning.psm1 +Install-WindowsImage -ImagePath C:\WindowsBuilder\working\output\install.wim -Index 3 -VHDPath C:\WindowsBuilder\working\output\Win10.vhdx -UEFI -Verbose +``` + + +Create a differencing VHD +------------------------- +Installing a Windows image to VHD can take some time. Let's create a differencing VHD to play with, so the original VHD is never touched: + +```powershell +New-VHD -Path C:\WindowsBuilder\working\output\win10-sub.vhdx -ParentPath C:\WindowsBuilder\working\output\win10.vhdx -Differencing +``` + + +Preboot Customization +--------------------- +Use `/provisioning/customizer.ps1` to generate `oemcustom.json` and `unattend.xml`. Then copy the files: + +```powershell +. C:\WindowsBuilder\provisioning\customizer.ps1 +# Answer the questions +Mount-VHD -Path C:\WindowsBuilder\working\output\Win10-sub.vhdx + +# Take note of the mounted Windows drive! The script below assumes I: +copy C:\WindowsBuilder\provisioning\oemcustom.json I:\Windows\Setup\Scripts\ -Force +copy C:\WindowsBuilder\provisioning\unattend.xml I:\Windows\System32\Sysprep\ -Force +Dismount-VHD -Path C:\WindowsBuilder\working\output\Win10-sub.vhdx +``` + + +Deploy to VM +------------ +Create a generation 2 VM on Hyper-V, using `C:\WindowsBuilder\working\output\win10-sub.vhdx` as the boot disk. + +Start the VM and voila! + + +Optimization for Production +--------------------------- +You should always use a fixed VHD when running in production mode. Dynamic VHD has very lousy I/O speed because it needs to expand dynamically. + +You shouldn't use a differencing disk either. Copy the reference VHD out entirely as a new VHD. + +```powershell +New-VHD -Path C:\WindowsBuilder\working\output\Win10.vhdx -SizeBytes 64GB -Fixed +# ... +New-VHD -Path C:\WindowsBuilder\working\output\Win10-sub.vhdx -ParentPath C:\WindowsBuilder\working\output\win10.vhdx +``` + +Of course, this takes more time and disk space. diff --git a/docs/walkthrough-winpe.md b/docs/walkthrough-winpe.md new file mode 100644 index 0000000..a06f83e --- /dev/null +++ b/docs/walkthrough-winpe.md @@ -0,0 +1,81 @@ +Walkthrough +=========== +Congrats for completing [the walkthrough](./walkthrough.md)! We are here to deploy your image to a bare metal PC. + + +Deploying Windows PE +-------------------- +Download Windows 10 ADK from Microsoft. Follow the instructions for creating a Windows PE boot USB drive. You need to customize the image to +include Powershell. + +#todo #up_for_grabs Windows 10 PE build bsd. + + +Deploying Windows 10 +-------------------- +Copy out your customized image (*.swm) to your USB drive. Let's put them in `[USB]\osimage\` (create the folder) on your USB drive. + +Copy out the `C:\WindowsBuilder\provisioning` folder to your USB too. + +Boot the PC you want to service using that USB drive. You should boot into Windows PE. + +Once you are in: + +```powershell +powershell +Set-ExecutionPolicy Unrestricted +Get-PSDrive +# Assuming D: is the USB drive +ipmo D:\provisioning\WindowsProvisioning.psm1 +Get-Disk +# Take note of the disk number of the PC's boot disk. Be very careful! +# The boot disk is normally disk 0, but double check, because that disk will be formatted. +Install-WindowsImage -ImagePath D:\osimage\surfacepro.swm -Index 3 -DiskNumber 0 -UEFI -Compact -Verbose +# The `UEFI` parameter is recommended for newer PC that supports UEFI firmware. +# The `Compact` parameter is recommended when the boot disk is a SSD. +# The `-Verbose` parameter is optional, but we want to see what it is doing for this exercise +``` + + +Preboot Customization +--------------------- +Use `[USB Drive]/provisioning/customizer.ps1` to generate `oemcustom.json` and `unattend.xml`. Then copy the files: + +```powershell +. D:\provisioning\customizer.ps1 +# Answer the questions + +# Assuming I: is the new drive letter of the Windows volume +copy D:\provisioning\oemcustom.json I:\Windows\Setup\Scripts\ -Force +copy D:\provisioning\unattend.xml I:\Windows\System32\Sysprep\ -Force +``` + + +Finalize deployment +------------------- +You should now unplug the USB drive from your PC. + +Reboot the PC for installation to continue. The PC should reboot 3 times, finishing at the logon screen. + +```powershell +Restart-Computer +``` + +Three accounts are created by default. The super account is an administrative account, another one with your customized name is a normal user +account, and a `Friend` account for guest access. + +Logon using the super account, using the password provided in the preboot customization stage. You can get the passwords for 2 additiona accounts +created from `[USB drive]\provisioning\unattend.xml`, or just set new passwords for these accounts using the super account. + +We recommend using the normal user account for daily work. + + +Optimization for Production +--------------------------- +The default accounts created can be fully customized by editing the following files: + +- provisioning\customizer.ps1 +- provisioning\Unattend.xml.tmpl + +In addition, edit the `oemcustom-ref.json` to automate the customizer. If you provide all fields in the referance JSON file, the customizer will not +prompt for anything. diff --git a/docs/walkthrough.md b/docs/walkthrough.md new file mode 100644 index 0000000..18f42f6 --- /dev/null +++ b/docs/walkthrough.md @@ -0,0 +1,110 @@ +Walkthrough +=========== +First, you will need a *licensed* copy of the official Windows image. If you have subscribed to MSDN, you may be able to download the ISO +from [the MSDN website](https://msdn.microsoft.com). + +For the rest of this walkthrough, let's assume we are working with `en_windows_10_multi-edition_vl_version_1709_updated_sept_2017_x64_dvd_100090741.iso`. + +Run command prompt with administrative privileges (start menu > command prompt > right-click > run as 'Administrator'). Run the following commands: + +```batchfile +cd C:\ +md WindowsBuilder && cd WindowsBuilder +powershell -Command "& { wget https://raw.githubusercontent.com/buildcenter/WindowsBuilder/master/scaffold.ps1 -UseBasicParsing | iex } +build configure +``` + +Obviously, for the more vigilent, you should just download this repo on Github (Clone or download > Download ZIP) and copy +out the contents of the ZIP file to `C:\`. Don't forget to run `build configure`! + +Mount your ISO and copy out the contents of `[ISO]\source\install.wim` to `C:\WindowsBuilder\working\output`. + +Back to your command prompt: + +```batchfile +build mount .\working\output\install.wim +``` + +Your WIM image probably contains multiple versions of Windows. WindowsBuilder will analyze the WIM file and prompt you to select the version to mount. We +are using #3 (Windows Enterprise). Mounting and dismounting can take a long time, especially on magnetic hard disks. We strongly recommend doing this on an +SSD. + +Next, you will normally be making a copy of `C:\WindowsBuilder\src\global.bsd` to something meaningful. We have already made one `win10-1709.bsd`, so +let's work with that for now. Go ahead and open `C:\WindowsBuilder\src\win10-1709.bsd` with your favorite text editor. Follow our inline documentation +and make your changes. + +Your assets lives under `C:\WindowsBuilder\resource` by default. We have made some sample resources to get you started. + +When you are satisfied with your customization: + +```batchfile +build win10-1709 +``` + +Be patient and let WindowsBuilder do the legwork. Then dismount the image and save your changes: + +```batchfile +build dismount +``` + + +Embedding drivers +----------------- +The computer that you want to service will probably include some custom third party drivers. We can embed them right in, so everything +works right out of the box! + +We have included a sample configuration for Surface Pro 3. Go download your driver pack from [the official source](https://www.microsoft.com/en-us/download/details.aspx?id=38826). We +have tested `SurfacePro3_Win10_14393_1703702_1.zip` with Windows 10 (1709) and it works fine. Unzip to `C:\WindowsBuilder\resource\Driver-SurfacePro3`. + +Again, this repo has included a sample configuration under `src\surfacepro3.bsd`. Open it up with your favorite text editor and review the configuration. When you +are done: + +```batchfile +copy .\working\output\install.wim .\working\output\surfacepro.wim +build mount .\working\output\surfacepro.wim +build surfacepro3 +build dismount +``` + +Sometimes your PC manufacturer doesn't provide an easy way for you to download all drivers in a complete package. In that case, install WindowsBuilder on the PC you want to service, and +create a dump of all installed drivers: + +```batchfile +build driver dump +``` + + +Split Image +----------- +We're almost ready to install your customized image on the bare metal. If you are putting your image file on a USB drive, note that FAT32 filesystem cannot handle files bigger than +4GB, which your final WIM may well exceed. To work around that, we recommend splitting the image to 1GB pieces: + +```batchfile +build split .\working\output\surfacepro.wim +``` + +You will get `C:\WindowsBuilder\working\output\surfacepro.swm`, `C:\WindowsBuilder\working\output\surfacepro1.swm`, etc. + + +Optional +-------- +You can remove unused versions in the final image. This is mostly just to reduce confusion. + +```batchfile +powershell +Get-WindowsImage -Path .\working\output\install.wim +# This will remove all except entry 3 +Remove-WindowsImage -Path .\working\output\install.wim -Index 1 +Remove-WindowsImage -Path .\working\output\install.wim -Index 1 +Remove-WindowsImage -Path .\working\output\install.wim -Index 2 +Remove-WindowsImage -Path .\working\output\install.wim -Index 2 +Remove-WindowsImage -Path .\working\output\install.wim -Index 2 +``` + + +Ready to Go +----------- +If you are trying to install Windows on a bare metal PC, go to the tutorial on [building your Windows PE](./walkthrough-winpe.md) USB drive. + +If your computer has Windows Hyper-V installed, and you want to install your image on a virtual machine, go to the +tutorial on [installing WIM on VHD](./walkthrough-vm.md).