BCEnabler Technical Reference

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.

Running BCEnabler.exe in a Full Windows OS

…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.

Usage

BCEnabler.exe is executed with either the "Enable" command parameter + options or the "Move" command parameter + options.

Enable - Enable and Configure BranchCache options

Command line syntax:

BCEnabler.exe Enable CachePath [BCVersion] [BCPort]

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. 2Pint recommends using port 1337 which is used if implementing OSD Toolkit TS Module Phase 1.

If the BCPort option is used, the BCVersion option must also be defined.

Move – Preserve the cached content for future use

Command line syntax:

BCEnabler.exe Move NewOSDrive [NewNonDefaultCachePath]

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.

Suspend and Resume

BCEnabler.exe supports "Suspend" and "Resume" parameters. These parameters can be used to stop and restart the BranchCache service.

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.

BCEnabler.exe Suspend

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.

BCEnabler.exe Resume

Example Commands

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%

Advanced example command lines:

BCEnabler.exe Enable %_SMSTSMDataPath%\BCCache 2 1337
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"

Running BCEnabler.exe in a Task Sequence

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:

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 task sequence. We strongly recommend using variable paths, instead of hard coded paths.

The BCEnabler.exe 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.

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.

The BCEnabler.exe task running during a Task Sequence.

Using Suspend and Resume Feature

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

Using the BCEnable.exe Move Command to retain the cached content

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.

Paths

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.