Enabling BranchCache in the Deployment
Last updated
Last updated
Once you have a BranchCache enabled WinPE image it’s time to edit the task sequence to enable BranchCache and configure the Cache Location.
Note: You cannot use WinPE RAM Drive (X:) as the Cache Location for obvious reasons, trying to do so will result in a Cachemgr Blue Screen of Death (BSOD). So don’t do it!
The process of enabling BranchCache can be split into 2 steps:
Enabling BranchCache, setting the Cache location, identifying the Hash Version and specifying the Port number
Moving the BranchCache cache onto to the newly built machine, so that downloaded data is not lost when leaving WinPE. This way machines can serve others as soon as possible even before the OSD process finishes. BOOM!
Advanced Tip: In the future we will also detect existing caches on hard drives offline in WinPE. This can be achieved today by a script if required. Just detect and do a file move/copy depending on your OSD setup or simply point the cache location to this path.
This section covers how to implement for Configuration Manager. The concept is the same for MDT (with config Manager) except for the Download part.
BCEnabler.exe is the tool that is used to Enable and Move the BranchCache in WinPE
Figure 6 : Command line tool BCEnable.exe help output.
WinPEGen.exe injects BCEnabler.exe into the Windows\System32 directory of the WinPE image. This can then be called from the task sequence to perform certain actions.
BCEnabler.exe is executed with either the "Enable" command parameter + options or the "Move" command parameter + options.
Command line syntax:
BCEnabler.exe Enable CachePath [BCVersion] [BCPort]
Where:
CachePath is the full path to the new location for the cache. This cannot be located on a RAM drive like X: but USB media works fine as long as it’s an NTFS formated drive.
BCVersion: Number of the version of BranchCache to be used, v2 for Windows 8/10 and v1 for Windows 7. If you don’t specify a version it will use the default for the WinPE version that you are using, i.e. v1 for Windows 7 and version v2 for anything else.
BCPort: (Optional but recommended) - The number of a custom port to be used. If left blank it will default to Port 80 which obviously can cause issues.
Note: If you want to specify Port you must specify the Version.
Command line syntax:
BCEnabler.exe Move NewOSDrive [NewNonDefaultCachePath]
Where:
NewOSDrive: Drive letter containing the new operating system. EG:- C: or %MYDRIVELETTER% in a valid Configuration Manager drive letter.
NewNonDefaultCachePath: Full Non Default path to the new location for the cache like D:\MyCache
Note: No need to specify default path Windows\ServiceProfiles\NetworkService\AppData\Local, instead leave it blank.
Note: The path might not be the same on the new computer, so use environment variables if possible.
Typical "Enable" command line that uses the Configuration Manager variable of the %_SMSTSMDataPath% to specify the cache directory
BCEnabler.exe Enable %_SMSTSMDataPath%\BCCache
Typical "Move" command lines, both using variables to set the cache directory to the new OS drive:
BCEnabler.exe Move %OSDTargetSystemDrive%
BCEnabler.exe Move %OSDISK%
BCEnabler.exe Enable %_SMSTSMDataPath%\BCCache 2 443
BCEnabler.exe Enable "D:\Cache\My Cache" 1 81
BCEnabler.exe Move %OSDISK% "D:\New Cache"
BCEnabler.exe Move %OSDISK% "%OTHERDRIVEVARIABLE%:\New Cache"
BCEnabler.exe Move %OSDISK% "%SystemDrive%:\MyBananaBoat"
Add a step to add BranchCache support as early as possible into your deployment sequence. Exactly where depends on your sequence. The following example shows a very simple MDT enabled Configuration Manager sequence.
Add a "Run Command Line" step and type in your command line:
BCEnabler.exe Enable %_SMSTSMDataPath%\BCCache
This will enable the BC components, set the new Cache Location to the variable defined in %_SMSTSMDataPath% and use the default BranchCache Version and Port.
Note: The path specified does not have to exist but, be aware of paths to folders that change ownership like the C:\_SMSTaskSequence directory. If you are moving content into this folder it must be done as a part of the sequence. We strongly recommend using variable paths, instead of hard coded paths.
Figure 7 The Enable step in the task sequence that starts the BranchCache components. It is run directly after the Partition step, allowing caching to start as soon as the disk is active.
When BCEnabler.exe runs it logs all actions to the %WINDIR%\Temp folder, which is typically the X:\Windows\Temp folder when running under WinPE.
Figure 8 The BCEnabler.exe command running as part of the Task Sequence.
BCEnabler.exe supports "Suspend" and "Resume" parameters. These parameters can be used to stop and restart the BranchCache service. This is to avoid issues around disk partitioning or other steps that may invalidate or change the BranchCache Cache location setup.
Suspend
This command stops BranchCache service and sets the service to Disabled. Any download after this step will not BranchCache, this means that steps that format and delete an existing BranchCache cache location can be run.
Resume
This command enables the service and starts BranchCache. Any download after this will BranchCache. If a new BranchCache database was put into the default or defined location it will be upgraded/used, or a new one will be created if none is present.
Example Logic
Step 1: Disk Partitioning
Step 2: BCEnabler.exe Enable C:\_SMSTaskSequence\BCCache
Step 3: Download a Package
Step 4: BCEnabler.exe Suspend
Step 5: Disk Partitioning
Step 6: BCEnabler.exe Resume
Step 7: Download a Package
…Is a bad idea. BCEnabler is designed to run in WinPE. Please do not try to use it to enable BranchCache in a full OS environment. Contact us for info on why and how you are looking to do this.
BCEnable.exe can be used to move the cache location (and therefore the content also) as one of the last steps in a task sequence. It should be executed after the disk and imaging tasks are complete to avoid accidental deletion.
The steps performed by the Move command are:
Stop the BranchCache Service
Create Folder Structures for the new folder path
Move the physical Cached Files to the new location (default is under Windows directory unless specified on the command line)
Transfer the BC Cache encryption key from WinPE to the full OS
Write new paths for the target Operating System should another cache location be used (Not recommended)
Write policy registry keys to allow Firewall exceptions for BranchCache and BranchCache startup (Same policy as specified on the Enable command line)
Write an "Automatic Startup" registry keys for BranchCache in to the new OS.
Transfer the Firewall policy keys to allow the BranchCache service to serve others during the rest of the build process.
Write new cache paths for the WinPE BranchCache process to continue to work
Enable the startup of BranchCache during the OSD Process
Start the BranchCache Service to serve the last pieces of the Configuration Manager TS that downloads the CCM client etc.
For Configuration Manager the best variable is %OSDTargetSystemDrive% which comes as an output from the “Apply Operating System” step. Actual installation of Windows is started by the “Setup Windows and Configuration Manager” task sequence step. After the “Apply Operating System” task sequence action has run, the OSDTargetSystemDrive task sequence variable is set to the drive letter of the partition containing the operating system files.
More information is available here: https://technet.microsoft.com/en-us/library/6b116f87-a1df-4194-ad57-f01d797b7d13#BKMK_ApplyOperatingSystemImage
Figure 8 How to add a BranchCache Move step, note that in this case it’s the last step in this Task Sequence. It doesn’t have to be last, but it must be after the Apply Image Step.
Please note that the Cache format is "per OS" version, and it significantly changed both from Windows 7 to 8 and from 8 to 8.1 and 10. However, upon BranchCache service startup, any Windows 7 or Windows 8.0/8.1 cache (present in the configured/default cache location) is automatically migrated to the current/latest format.
Once the cache is moved (Using the "BCEnable.exe Move" command) into the Windows 10 expected location, the cache is automatically imported/migrated to the most recent format.
The effect of this is that there is no backward compatibility should you drop the Cache from a Windows 10 to a Windows 7 machine. In that case a Windows 7 Boot image should be used. Since Windows 7 is close to retirement and most new machines today get images with Windows 10 this has not been a focus area for development and lacks testing. If you find that this is a showstopper to you, please let us know through info@2pintsoftware.com and we will see what we can do.
For a more thorough overview of Cache versions and which to use in a Windows 7/Windows 10 mixed environment please see Appendix A.
Keep in mind that logical drive letters might change between WinPE and the full Windows installation. e.g. WinPE might deploy the OS to E: and the final system drive will be visible as C: in Windows. In other words if you specify a cache location with the BCEnabler.exe "Move" command, pointing the cache to D:\MyCache it might be E:\MyCache in Windows. To avoid such issues use one partition for Windows and another for the cache.
Use variables as much as possible. But keep in mind that even variables are not forever.
TIP: If needed you can add steps to update the paths in the Full OS. The cache location paths are stored in sub keys here:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\PeerDist\CacheMgr
as Reg_Expand_Sz type registry keys, typically pointing to %Variable% locations. Default = No entry.
NOTE: Defaults are good. Don’t change the defaults unless absolutely necessary.
