BCEnabler Technical Reference
Last updated
Last updated
BCEnabler.exe is the tool that is used to Enable and Move the BranchCache in WinPE.
In order to customize a boot image to use BranchCache, 2Pint has provided the WinPEGen tool. 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:
Parameters:
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 formatted drive.
BCVersion - Number of the version of BranchCache to be used, v2 for Windows 8/10/11 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.
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.
If the BCPort option is used, the BCVersion option must also be defined.
Command line syntax:
Parameters:
NewOSDrive - Drive letter containing the new operating system. (Example: C: or %MYDRIVELETTER% in a valid Configuration Manager drive letter)
NewNonDefaultCachePath - Full Non Default path to the new location for the cache (Example: D:\MyCache)
There is no need to specify a default path: Windows\ServiceProfiles\NetworkService\AppData\Local, instead leave it blank.
The path might not be the same on the new computer, so use environment variables if possible.
BCEnabler.exe supports "Suspend" and "Resume" parameters. These parameters can be used to stop and restart the BranchCache service.
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.
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.
Typical "Enable" command line that uses the Configuration Manager variable of the %_SMSTSMDataPath% to specify the cache directory
Typical "Move" command lines, both using variables to set the cache directory to the new OS drive:
Note: If you followed the process referenced on the page: Customizing a Task Sequence to Support BranchCache, then the below steps are already included in the modules: Module- 2Pint Software OSD Toolkit Phase 1 and Module- 2Pint Software OSD Toolkit Phase 2. Edit those task sequence modules to customize the command line options referenced in this page.
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 Configuration Manager task sequence:
After the Format and Partition Disk step, add a "Run Command Line" step and type in your command line:
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 task sequence. We strongly recommend using variable paths, instead of hard coded paths.
During a running task sequence, 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.
This is to avoid issues around disk partitioning or other steps that may invalidate or change the BranchCache Cache location setup.
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
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
The image below displays the section of the task sequence 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.
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 registry subkeys in the path below:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\PeerDist\CacheMgr
The subkeys under the registry key above are Reg_Expand_Sz type registry keys, typically pointing to %Variable% locations. Default = No entry.
Note: Defaults are good. Don’t change the default values unless absolutely necessary.
