mirror of
https://github.com/rbalsleyMSFT/FFU.git
synced 2026-06-13 18:07:20 -06:00
Captures FFU directly from host-mounted VHDX
By optimizing and mounting the VHDX directly on the host for image capture, the build process no longer needs to boot the VM into WinPE, create SMB network shares, generate temporary local accounts, or rely on complex Hyper-V switch IP configurations. This streamlines the workflow and eliminates multiple networking and permission-related points of failure. This change also removes the need to generate and attach WinPE capture media. All related parameters (`ShareName`, `Username`, `VMHostIPAddress`, `CreateCaptureMedia`, `CleanupCaptureISO`), UI controls, capture scripts, and documentation references have been removed or updated to reflect the simplified architecture.
This commit is contained in:
rbalsleyMSFT
@@ -57,7 +57,6 @@ This allows for you to create a dynamic task sequence via a PowerShell script wi
|
||||
},
|
||||
"BuildUSBDrive": false,
|
||||
"CleanupAppsISO": true,
|
||||
"CleanupCaptureISO": true,
|
||||
"CleanupDeployISO": true,
|
||||
"CleanupDrivers": false,
|
||||
"CompactOS": true,
|
||||
@@ -69,7 +68,6 @@ This allows for you to create a dynamic task sequence via a PowerShell script wi
|
||||
"CopyPEDrivers": false,
|
||||
"CopyPPKG": false,
|
||||
"CopyUnattend": false,
|
||||
"CreateCaptureMedia": true,
|
||||
"CreateDeploymentMedia": true,
|
||||
"CustomFFUNameTemplate": "{WindowsRelease}_{WindowsVersion}_{SKU}_{yyyy}-{MM}-{dd}_{HH}{mm}",
|
||||
"Disksize": 53687091200,
|
||||
@@ -101,7 +99,6 @@ This allows for you to create a dynamic task sequence via a PowerShell script wi
|
||||
"RemoveApps": false,
|
||||
"RemoveFFU": false,
|
||||
"RemoveUpdates": false,
|
||||
"ShareName": "FFUCaptureShare",
|
||||
"Threads": 5,
|
||||
"UpdateADK": true,
|
||||
"UpdateEdge": true,
|
||||
@@ -115,9 +112,7 @@ This allows for you to create a dynamic task sequence via a PowerShell script wi
|
||||
"USBDriveList": {},
|
||||
"UseDriversAsPEDrivers": false,
|
||||
"UserAppListPath": "C:\\FFUDevelopment\\Apps\\UserAppList.json",
|
||||
"Username": "ffu_user",
|
||||
"Verbose": false,
|
||||
"VMHostIPAddress": "192.168.1.169",
|
||||
"VMLocation": "C:\\FFUDevelopment\\VM",
|
||||
"VMSwitchName": "External",
|
||||
"WindowsArch": "x64",
|
||||
|
||||
+2
-46
@@ -79,26 +79,10 @@ Result: `Win11_24h2_Pro_Nov2025.ffu`
|
||||
|
||||
The FFU Capture Location sets the `-FFUCaptureLocation` parameter that determines where completed `.ffu` images are written. By default it points to `$FFUDevelopmentPath\FFU`, and the build script creates the folder automatically if it does not already exist.
|
||||
|
||||
When apps are installed in a VM, the host converts this folder into a temporary SMB share using the **Share Name** and **Username** fields. The capture WinPE environment maps that share as drive `W:` and streams the captured image directly into this folder. When the build finishes, the share and local account are removed, but the FFU files remain unless a cleanup option deletes them.
|
||||
When apps are installed in a VM, the build still uses the VM for application installs and sysprep, but the actual FFU capture now happens on the host after the VHDX is optimized and remounted. That means completed images are written directly to this folder without creating a temporary SMB share, temporary local account, or capture ISO.
|
||||
|
||||
Choose a path on fast storage with plenty of free space—the directory must be local to the host running `BuildFFUVM.ps1`, and large captures can easily exceed 25–30 GB. This location also feeds other options such as **Copy Additional FFU Files**, **Build USB Drive**, and **Remove FFU**, so keeping all finished images here keeps those workflows simple.
|
||||
|
||||
## Share Name
|
||||
|
||||
The Share Name sets the `-ShareName` parameter that defines the name of the temporary SMB share created during the FFU capture process. The default is `FFUCaptureShare`.
|
||||
|
||||
During the build, the host creates an SMB share that points to the **FFU Capture Location** and grants access to the temporary local user account defined in **Username**. The capture WinPE environment maps this share as drive `W:` using `net use` and streams the captured FFU image directly to it.
|
||||
|
||||
When the build completes, the share is automatically removed along with the temporary user account, leaving only the captured FFU files behind in the FFU Capture Location.
|
||||
|
||||
## Username
|
||||
|
||||
The Username field sets the `-Username` parameter that `BuildFFUVM.ps1` uses when creating the temporary SMB share user. The value becomes a local standard user account that is granted Full Control on the **FFU Capture Location** share (default C:\FFUDevelopment\FFU) so the capture WinPE session can copy the FFU over `net use `. The default `ffu_user` account name works for most scenarios, but you can supply any other local account name that meets your organization's policies.
|
||||
|
||||
When the build starts, the script ensures the account exists, rotates its password to a randomly generated GUID, and grants it access to the share. The Capture WinPE environment maps drive `W:` with those credentials, then writes the captured image directly into the FFU Capture Location.
|
||||
|
||||
After the build finishes, the share is removed and the temporary account is deleted, leaving only the FFU files stored in the capture folder.
|
||||
|
||||
## Threads
|
||||
|
||||
Controls the `-Threads` parameter, which sets the number of parallel threads used for concurrent operations throughout FFU Builder. The default value is **5**.
|
||||
@@ -471,28 +455,6 @@ VHDX caching trades disk space for speed. The `VHDXCache` folder can grow over t
|
||||
>
|
||||
> To force a full rebuild, delete the contents of `$FFUDevelopmentPath\VHDXCache` (or disable **Allow VHDX Caching**) and run the build again.
|
||||
|
||||
## Create Capture Media
|
||||
|
||||
Controls the `-CreateCaptureMedia` parameter.
|
||||
|
||||
When enabled, FFU Builder creates WinPE capture media that is used during VM-based builds (when apps are installed in the VM). FFU Builder attaches this media to the VM and adjusts boot order so the VM can reboot into WinPE and automatically capture the FFU to your **FFU Capture Location**.
|
||||
|
||||
The capture media uses the parameter values from `VMHostIPAddress`, `ShareName`, `UserName`, and `CustomFFUNameTemplate` and inserts them into `CaptureFFU.ps1` which is what is responsible for capturing the FFU from the guest VM to the Host.
|
||||
|
||||
**Default:** Enabled (`-CreateCaptureMedia $true`)
|
||||
|
||||
{: .note-title}
|
||||
|
||||
> Note
|
||||
>
|
||||
> This option is only relevant when **Install Apps** is enabled. If **Install Apps** is enabled, the build forces `-CreateCaptureMedia` to `$true` because capture media is required to capture an FFU from the VM.
|
||||
|
||||
{: .tip-title}
|
||||
|
||||
> Tip
|
||||
>
|
||||
> If you just need to re-create media, you can use the `Create-PEMedia.ps1` script to regenerate the capture or deploy ISO using `Create-PEMedia.ps1 -Capture $true` or `CreatePEMedia.ps1 -Deploy $true`.
|
||||
|
||||
## Create Deployment Media
|
||||
|
||||
Controls the `-CreateDeploymentMedia` parameter.
|
||||
@@ -513,7 +475,7 @@ The deployment media is saved as an ISO file at `$FFUDevelopmentPath\WinPE_FFU_D
|
||||
|
||||
> Tip
|
||||
>
|
||||
> If you just need to re-create media, you can use the `Create-PEMedia.ps1` script to regenerate the capture or deploy ISO using `Create-PEMedia.ps1 -Capture $true` or `CreatePEMedia.ps1 -Deploy $true`.
|
||||
> If you just need to re-create deployment media, you can use the `Create-PEMedia.ps1` script to regenerate the deploy ISO without running a full build.
|
||||
|
||||
## Inject Unattend.xml
|
||||
|
||||
@@ -604,12 +566,6 @@ You may want to disable Cleanup Apps ISO in the following scenarios:
|
||||
>
|
||||
> The Apps ISO is only created when applications are configured for installation. If no apps are being installed in the FFU, this option has no effect. Keeping this option enabled helps conserve disk space by removing temporary build artifacts.
|
||||
|
||||
## Cleanup Capture ISO
|
||||
|
||||
Controls the `-CleanupCaptureISO` parameter. When checked, the WinPE capture ISO file is automatically deleted after the FFU has been successfully captured. The default is **checked**.
|
||||
|
||||
It's recommended to keep this checked as each new build re-creates the local username account (e.g. `ffu_user`) and its password. If you were to retain the capture ISO from a previous build, it'd be using an old password and the capture would fail.
|
||||
|
||||
## Cleanup Deploy ISO
|
||||
|
||||
Controls the `-CleanupDeployISO` parameter. When checked, the WinPE deployment ISO file is automatically deleted after the FFU has been successfully captured. The default is **checked**.
|
||||
|
||||
+4
-10
@@ -9,7 +9,7 @@ parent: Helper Scripts
|
||||
---
|
||||
# Create PE Media
|
||||
|
||||
`Create-PEMedia.ps1` is a standalone helper script that creates WinPE capture or deployment ISO files outside the main build flow.
|
||||
`Create-PEMedia.ps1` is a standalone helper script that creates WinPE deployment ISO files outside the main build flow.
|
||||
|
||||
This is useful when admins need to quickly generate a deploy ISO for a share (or local staging folder) that technicians will use with `USBImagingToolCreator.ps1`.
|
||||
|
||||
@@ -40,25 +40,19 @@ Default output file:
|
||||
Create deploy ISO for x64:
|
||||
|
||||
```powershell
|
||||
.\Create-PEMedia.ps1 -Deploy $true -WindowsArch 'x64'
|
||||
.\Create-PEMedia.ps1 -WindowsArch 'x64'
|
||||
```
|
||||
|
||||
Create deploy ISO for ARM64:
|
||||
|
||||
```powershell
|
||||
.\Create-PEMedia.ps1 -Deploy $true -WindowsArch 'arm64' -DeployISO "$PSScriptRoot\WinPE_FFU_Deploy_arm64.iso"
|
||||
```
|
||||
|
||||
Create capture ISO only:
|
||||
|
||||
```powershell
|
||||
.\Create-PEMedia.ps1 -Capture $true -Deploy $false
|
||||
.\Create-PEMedia.ps1 -WindowsArch 'arm64' -DeployISO "$PSScriptRoot\WinPE_FFU_Deploy_arm64.iso"
|
||||
```
|
||||
|
||||
Create deploy ISO and include PE drivers from `.\PEDrivers`:
|
||||
|
||||
```powershell
|
||||
.\Create-PEMedia.ps1 -Deploy $true -CopyPEDrivers $true
|
||||
.\Create-PEMedia.ps1 -CopyPEDrivers $true
|
||||
```
|
||||
|
||||
## Stage output for USB imaging
|
||||
|
||||
@@ -15,11 +15,7 @@ parent: UI Overview
|
||||
|
||||
Drop down of detected VM Switches. There's also an **Other** option which allows you to specify a VM Switch Name. The other option is useful in scenarios where the machine you're running the UI from isn't going to be the machine where you plan to build the FFU from.
|
||||
|
||||
## VM Host IP Address
|
||||
|
||||
IP address of the selected Hyper-V switch that will be used for FFU capture. The UI will auto-detected this based on the VM Switch that was selected.
|
||||
|
||||
If `$InstallApps` is set to `$true`, this parameter must be configured.
|
||||
This setting is now optional for FFU capture itself. VM-based builds still capture from the host-side VHDX after the VM shuts down, so you only need a switch when the VM requires network connectivity during provisioning.
|
||||
|
||||
## Disk Size (GB)
|
||||
|
||||
|
||||
@@ -27,7 +27,6 @@ This table lists all top-level parameters in BuildFFUVM.ps1.
|
||||
| -BuildUSBDrive | bool | Build USB Drive | When set to $true, will partition and format a USB drive and copy the captured FFU to the drive. |
|
||||
| -Cleanup | switch | Monitor cancel build action (no direct control) | Switch to run cleanup-only mode. When specified, the script performs cleanup and exits without starting a new build. |
|
||||
| -CleanupAppsISO | bool | Cleanup Apps ISO | When set to $true, will remove the Apps ISO after the FFU has been captured. Default is $true. |
|
||||
| -CleanupCaptureISO | bool | Cleanup Capture ISO | When set to $true, will remove the WinPE capture ISO after the FFU has been captured. Default is $true. |
|
||||
| -CleanupCurrentRunDownloads | bool | Monitor cancel prompt option (no direct control) | When set to $true, cleanup mode will remove downloads created during the current run and restore backed up run JSON files. Default is $false. |
|
||||
| -CleanupDeployISO | bool | Cleanup Deploy ISO | When set to $true, will remove the WinPE deployment ISO after the FFU has been captured. Default is $true. |
|
||||
| -CleanupDrivers | bool | Cleanup Drivers | When set to $true, will remove the drivers folder after the FFU has been captured. Default is $true. |
|
||||
@@ -40,7 +39,6 @@ This table lists all top-level parameters in BuildFFUVM.ps1.
|
||||
| -CopyPEDrivers | bool | Copy PE Drivers | When set to $true, enables adding WinPE drivers. By default copies drivers from $FFUDevelopmentPath\PEDrivers to the WinPE deployment media unless -UseDriversAsPEDrivers is also $true. |
|
||||
| -CopyPPKG | bool | Copy Provisioning Package | When set to $true, will copy the provisioning package from the $FFUDevelopmentPath\PPKG folder to the Deployment partition of the USB drive. Default is $false. |
|
||||
| -CopyUnattend | bool | Copy Unattend.xml | When set to $true, will copy the $FFUDevelopmentPath\Unattend folder to the Deployment partition of the USB drive. Default is $false. |
|
||||
| -CreateCaptureMedia | bool | Create Capture Media | When set to $true, this will create WinPE capture media for use when $InstallApps is set to $true. This capture media will be automatically attached to the VM, and the boot order will be changed to automate the capture of the FFU. |
|
||||
| -CreateDeploymentMedia | bool | Create Deployment Media | When set to $true, this will create WinPE deployment media for use when deploying to a physical device. |
|
||||
| -CustomFFUNameTemplate | string | Custom FFU Name Template | Sets a custom FFU output name with placeholders. Allowed placeholders are: {WindowsRelease}, {WindowsVersion}, {SKU}, {BuildDate}, {yyyy}, {MM}, {dd}, {H}, {hh}, {mm}, {tt}. |
|
||||
| -Disksize | uint64 | Disk Size (GB) | Size of the virtual hard disk for the virtual machine. Default is a 50GB dynamic disk. |
|
||||
@@ -73,7 +71,6 @@ This table lists all top-level parameters in BuildFFUVM.ps1.
|
||||
| -RemoveApps | bool | Remove Apps Folder Content | When set to $true, will remove the application content in the Apps folder after the FFU has been captured. Default is $true. |
|
||||
| -RemoveFFU | bool | Remove FFU | When set to $true, will remove the FFU file from the $FFUDevelopmentPath\FFU folder after it has been copied to the USB drive. Default is $false. |
|
||||
| -RemoveUpdates | bool | Remove Downloaded Update Files | When set to $true, will remove the downloaded CU, MSRT, Defender, Edge, OneDrive, and .NET files downloaded. Default is $true. |
|
||||
| -ShareName | string | Share Name | Name of the shared folder for FFU capture. The default is FFUCaptureShare. This share will be created with rights for the user account. When finished, the share will be removed. |
|
||||
| -Threads | int | Threads | Controls the throttle applied to parallel tasks inside the script. Default is 5, matching the UI Threads field, and applies to driver downloads invoked through Invoke-ParallelProcessing. |
|
||||
| -UpdateADK | bool | Update ADK | When set to $true, the script will check for and install the latest Windows ADK and WinPE add-on if they are not already installed or up-to-date. Default is $true. |
|
||||
| -UpdateEdge | bool | Update Edge | When set to $true, will download and install the latest Microsoft Edge. Default is $false. |
|
||||
@@ -88,10 +85,8 @@ This table lists all top-level parameters in BuildFFUVM.ps1.
|
||||
| -UseDriversAsPEDrivers | bool | Use Drivers Folder as PE Drivers Source | When set to $true (and -CopyPEDrivers is also $true), bypasses the contents of $FFUDevelopmentPath\PEDrivers and instead builds the WinPE driver set dynamically from the $DriversFolder path, copying only the required WinPE drivers. Has no effect if -CopyPEDrivers is not specified. Default is $false. |
|
||||
| -UserAgent | string | CLI only (no UI control) | User agent string to use when downloading files. |
|
||||
| -UserAppListPath | string | Application Path (derived UserAppList.json) | Path to a JSON file containing a list of user-defined applications to install. Default is $FFUDevelopmentPath\Apps\UserAppList.json. |
|
||||
| -Username | string | Username | Username for accessing the shared folder. The default is ffu_user. The script will auto-create the account and password. When finished, it will remove the account. |
|
||||
| -VMHostIPAddress | string | VM Host IP Address | IP address of the Hyper-V host for FFU capture. If $InstallApps is set to $true, this parameter must be configured. You must manually configure this, or use the UI to auto-detect. |
|
||||
| -VMLocation | string | VM Location | Default is $FFUDevelopmentPath\VM. This is the location of the VHDX that gets created where Windows will be installed to. |
|
||||
| -VMSwitchName | string | VM Switch Name + Custom VM Switch Name (when Other selected) | Name of the Hyper-V virtual switch. If $InstallApps is set to $true, this must be set to capture the FFU from the VM. |
|
||||
| -VMSwitchName | string | VM Switch Name + Custom VM Switch Name (when Other selected) | Name of the Hyper-V virtual switch. Provide it when the VM needs network connectivity during provisioning. |
|
||||
| -WindowsArch | string | Windows Architecture | String value of 'x86', 'x64', or 'arm64'. This is used to identify which architecture of Windows to download. Default is 'x64'. |
|
||||
| -WindowsLang | string | Windows Language | String value in language-region format (e.g., 'en-us'). This is used to identify which language of media to download. Default is 'en-us'. |
|
||||
| -WindowsRelease | int | Windows Release | Integer value of 10, 11, 2016, 2019, 2021, 2022, 2024, or 2025. This is used to identify which Windows client/LTSC/server release to use. Default is 11. |
|
||||
|
||||
+1
-1
@@ -45,7 +45,7 @@ Follow the [prerequisites](/FFU/prerequisites.html) documentation before getting
|
||||
|
||||
Click the Hyper-V Settings tab
|
||||
|
||||
You should be able to keep these settings at the defaults. For VM Switch Name and VM Host IP Address, you'll want to make sure the switch you created in the prerequisites section is listed. FFU Builder should automatically figure out the IP address of the swtich for you.
|
||||
You should be able to keep these settings at the defaults. If the VM needs network connectivity during provisioning, make sure the switch you created in the prerequisites section is listed under VM Switch Name. If the build does not need VM networking, you can leave the switch unset.
|
||||
|
||||
One setting you might need to set is the Logical Sector Size. 512 is the default and that's what most physical disks use today. However 4kn drives and UFS drives use 4k sector sizes, which would require you to select 4096. For now, select 512. If you have issues during deployment, there is error logging that will tell you if you need to set to 4096 on your device.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user