Before you can use BranchCache in WinPE you need to generate a WinPE image that contains the services and binaries to enable this magic.

Note: If changing or updating the boot image is a major blocker, please contact us.

Generating a BranchCache enabled WinPE Boot Image

Generating a new WinPE Boot Image is done via a command line utility. This utility requires you to have administrator rights on the machine where you run the tool. The reason for this is that it mounts registry hives from the offline media, a privilege that requires administrative rights. In a locked down environment this can be run on a standalone non domain joined computer.

The WinPE images created can then be used as regular boot images in Configuration Manager or MDT (with Config Manager). This makes no difference to these processes, they simply have the inbuilt BranchCache & BITS functionality available if called upon.

Figure 1 shows WinPE images that have been enabled with BranchCache imported into Configuration Manager, ready for use.

The tool used to create a BranchCache enabled image (WinPEGen.exe) is simply run from the command line as shown below.

Figure 2 shows the generator tool command line help output.

WinPE Generator Command Line Options

The generator has the following mandatory configuration parameters:

• "Source.wim" – The full path and name of the OS source .wim file to use to get resource data.

• Index – The index number of the source.wim to use - Professional or Enterprise.

• "Boot.wim" – The full path and name of an existing WinPE boot WIM file

NOTE: The Boot.wim file is modified during this process, so ensure you have a backup!

• Index – The index number of the wim to use inside the .wim file, like DISM /Index:1 etc.

The following optional configuration options may also be provided:

• /Add-StifleR – Adds the StifleR client to the WinPE image under the %WINDIR%\System32\ path.

The StifleR Client files are added from within the WinPE Generator executable.

• /Add-StifleROnly – Adds only the StifleR client and does not add BranchCache and BITS to the image.

• /StifleRConfig – Defines the path to a StifleR client configuration file.

Providing a configuration file is essential in order to provide the StifleR Server name etc.

• /Remove-BITS - Removes BITS for Bandwidth Policy Aware Downloads in WinPE

• /Copy-BITSPolicy - Copies the local BITS policy into the WinPE Image

This overwrites the default BITS policy which is limited to 1Mb/s during business hours of Monday-Friday 08:00-17:00 and 2Mb/s during any other time. Ignoring speed limits on the LAN allows full throttle download for cached local content. Use GPEdit to create a local BITS policy which can then be copied automatically at build time.

Boot Image Generation Pre-Requisites

The generator does not need to install anything and stores/mounts temporary files in the %temp% folder of the user running the process.

• A workstation or Server with Windows 7/2008 or higher (x86 or x64) on which to run the process. The User must be a member of the Local Administrators group.

Administrative access is required in order to mount the registry hives in the source and boot media. This is a privileged operation which requires Administrative access to the machine.

• Access to the 2Pint Software "WinPEGen.exe"

This is freely downloadable from the website http://2pintsoftware.com as a part of the BranchCache for OSD Toolkit.

• A boot.wim image that has not been finalized (i.e. still allows changes to be made to it)

This can be acquired either from the Configuration Manager server or MDT or also through the WAIK/AIK directly.

• Access to Windows source media of either Enterprise or Professional

The media can be either Windows 7 (For Windows 7 versions of WinPE) or Windows 8.x for more up to date WinPE versions. This can be in the form of a DVD or ISO file, it can even be a captured WIM as long as the "Windows" directory exists on one of the indexed images.

NOTE: The Source.wim MUST BE ENTERPRISE media if using /Remove-BITS option, otherwise data transfers will not be BranchCache enabled.

IMPORTANT: The Source.wim MUST be the same release version, i.e. same build, as the Boot WIM that is to be modified. If you have a patched install.wim you need to patch your WinPE image. A script to do this can be found here: https://2pintsoftware.com/download/osdtoolkit-boot-image-scripts/ also you have a KB describing how its done: https://kb.2pintsoftware.com/help/winpegen-dot-exe-boot-image-not-working

Although the media does not have to be Enterprise, Professional requires BITS added in order to provide BranchCache functionality. Enterprise media adds native HTTP support for BranchCache.

Running WinPEGen.exe

The "WinPEGen.exe" is available in both x86 and x64 versions.

Start the process by launching a command shell. Navigate in the prompt to the path where the "WinPEGen.exe" file is located.

1. Run "WinPEGen.exe" without any command line arguments to see the parameters available (as per figure 2 above)

2. To create an Image, type in the appropriate WinPEGen.exe command line. E.G.:

"WinPEGen.exe" "C:\Temp\Windows8Ent\Sources\install.wim" 1 "C:\Temp\boot.wim" 1

1. Press Enter to start the process

2. The Generator will write progress to the screen as it mounts and customizes the boot image, any errors encountered will be visible on the screen.

Example Generation

Preparing

The following explorer window shows the setup of files in this example. We have copied the x64 generator executable to the C:\Temp\ folder

Source Media File:

Figure 3: Note that the source media can be a DVD image mounted with the Sources\install.wim or any other wim file with the correct architecture, version and folder structure.

Example command line (In this case adding StifleR to the image and defining the (required) path to the StifleR client configuration file):

Figure 4 shows the command line for running the generator.

Hint: If needed you can save the output by redirecting the standard out to a text file with the > character from a prompt. The > characters piping function is a function in cmd.exe so the command prompt must be executed as follows:

Cmd.exe /c "WinPEGen.exe" "C:\Temp\Windows8Ent\Sources\install.wim" 1 "C:\Temp\boot.wim" 1>C:\MyLogfile.txt

Assuming that all goes well, the executable will complete and generate the BranchCache enabled boot.wim file.

Sample output as follows:

Figure 5 shows the completed task of generating the boot images.

The full process of adding the new boot image to your deployment method is out of scope for this document but it is relatively simple. Right click the Boot Image node in Configuration Manager and select "Add Boot Image" and provide the path to your boot image.

Note: If using StifleR in WinPE you must include the Microsoft .NET optional component in your boot image.

BranchCache

BranchCache is a mature WAN bandwidth optimization technology that has been included in Microsoft Operating systems since Server 2008/Windows 7. To optimize WAN bandwidth, BranchCache downloads content from the main office content servers and caches that content locally on any suitable Windows PC. The cached content can then be shared with other client computers at branch offices via Peer to Peer rather than over the WAN.

BranchCache helps improve content query response times for clients and servers in branch offices, and also helps improve network performance by reducing traffic over WAN links.

Why BranchCache for OS Deployment?

This nifty bit of technology is perfect for optimizing very large file transfers such as those that are required for machine builds! Unfortunately, while machines are being built, they are not running under a full operating system and are not, by default, able to utilize the awesome power of BranchCache. Here at 2Pint Software we believe that BranchCache (in fact ALL P2P technologies) are the most under-utilized and powerful tools available to today’s Administrators. Our mission therefore was to enable BranchCache functionality in the Operating System Deployment (OSD) environment.

The end result of these efforts is the OSD Toolkit which allows administrators to enable clients to make use of the P2P sharing capabilities of BranchCache during the build process which in turn drastically reduces deployment times and can save you Gigabytes in expensive WAN network traffic.

Overview

The OSD Toolkit integrates fully with your existing Configuration Manager task sequences (not just OS Deployment). All regular options in Configuration Manager are available for you but with the added function that all content can be downloaded using BITS together with BranchCache. This kit has been developed to streamline deployments from Microsoft System Center Configuration Manager Current Branch

Through the magic of BranchCache, the OSD Toolkit allows you to deploy computers using standard Configuration Manager Task Sequences not only at your well connected Main Office sites but also at remote Branch Offices across slow WAN links. This allows you to use the same process for building every computer within the organization, regardless of placement, without any need to start moving hardware around. This greatly lowers the cost for break/fix rebuild and other Administrative heavy build and distribution scenarios.

By enabling BranchCache in a resource intensive process like OSD, more systems on the network can share the load, ensuring a fast and effortless deployment without hogging system resources from other computers or the network.

The OSD Toolkit enables native HTTP(s) & BITS BranchCache download support into WinPE, thus adding BranchCache support for Task Sequences. It also provides a command line 'Alternate Content Provider' (ACP) tool for downloading content using BranchCache where this would otherwise not be available.

There is no agent to install. All that is required is to enable the built-in Microsoft BranchCache function that has been a standard part of the Windows Operating Systems for nearly a decade. In the event that there is no BranchCache enabled computer already present with cached content available, the content can be downloaded from the server, retained through the process and then made available for other Peers when next required. The BranchCache for OSD kit works with both dynamic and hosted cache mode and is easy to integrate into your existing deployment method. In theory, the toolkit can work with any deployment solution out there that uses HTTP & BITS as the main delivery engine.

The OSD Toolkit package includes:

• WinPE Generator (Services & Binaries etc) for building a WinPE boot image that includes BITS and BranchCache functionality

• Task Sequence Command Line Tool (Enable BranchCache and then Move/Retain BranchCache Content for later use)

• Task Sequence Download Tool (ACP) For Windows Pro and WinPE.

Getting Started

There are a few simple steps and considerations that are required before you can start using BranchCache for OSD regardless of what deployment method you are using:

1. Generate a BranchCache enabled WinPE boot image

2. Change your deployment sequence to enable the BranchCache components in WinPE

3. Optionally edit the task sequence to move the cache content from the WinPE environment to the new Operating System being deployed making it available for Peer to Peer sharing going forward.

4. Optionally changing your deployment sequence to work with Image Downloads from a task Sequence in Windows Professional

5. Optionally change deployment sequence to detect an existing BranchCache Cache location from within WinPE

6. Optionally enable reporting of BranchCache data

Note: This document focuses mainly on MDT (with Configuration Manager) and Configuration Manager for deployment, but these should apply to any old deployment solution that uses WinPE for deployment and HTTP for downloads.

Note: This document does not cover the Bandwidth limitation/setting/configuration needed in order to make BranchCache and BITS work nicely together. Instead look online for that whitepaper: "Administrators Guide to BranchCache – Distributed Mode" on the http://2pintsoftware.com site, use "them search engines" to find it or just follow this handy link:-

https://2pintsoftware.com/download/administrators-guide-branchcache-distributed-mode/

OSD Toolkit

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:

1. Enabling BranchCache, setting the Cache location, identifying the Hash Version and specifying the Port number

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

Enabling BranchCache in a Deployment Sequence

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

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.

Enable - Enable and Configure BranchCache 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.

Move – Preserve the cached content for future use

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.

Example command lines

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 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"

Running BCEnabler.exe in a WinPE session

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.

Using Suspend and Resume feature

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

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.

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

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.

Consideration when moving the Cache

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.

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

The OSD Toolkit integrates seamlessly with your existing task sequence deployments in Configuration Manager. All options in Configuration Manager remain available without any need for modifications or changes.

If there is something that you feel is missing, then please let us know by email

To Cache or not to Cache?

There is no requirement to Pre-Cache content before deploying a computer however the download process will be shorter and can also allow for deployment to take place during business hours when there may be policies in place limiting WAN bandwidth use at these times.

Keep in mind that all Task Sequences executed by users are run under the "Foreground" BITS policy, which is not, by default, bandwidth limited from Configuration Manager. There are other reasons why you shouldn’t use the built-in policy for BITS in Configuration Manager such as local peer network sharing is also capped by this policy.

When it comes to download, there are two choices for the way that you can deploy a task sequence the names of which explain what they’re about:

• Download content locally when needed by running task sequence

or:

• Download all content locally before starting task sequence

Both options are explained in detail below.

Deploy using "Download all content locally before starting task sequence"

This setting is typically used only when pre-caching, as it downloads all the content locally. This means that every applications and package referenced by the task sequence will be downloaded locally. Usually a task sequence will have conditions to control which packages apply, these variables are not evaluated under this setting and therefore all data is downloaded.

Why can’t I set the Deployment Option to download all content before executing?

This is because these Deployments are for targeting PXE and Media. Since there is no need to "Precache" or deploy to PXE/Media with the setting you can divide it into 2 separate deployments. One for Pre-caching/Deployment and one for Deployment for Full OS/PXE/Media.

The default setup for a TS deployment created to target PXE & Media as well as the full client is to: "Download content locally when needed by running task sequence".

The following screen shots show the default settings:

Figure 10 The default values of the Deployment Settings.

With this setting the Distribution Point settings cannot be changed:

Figure 11: Deployment Options cannot be changed when the PXE & Media target flag has been set.

If you want to pre-cache content, you need to change this flag. The recommended method is to add a second Deployment, which is solely used for pre-caching tasks.

Deploy with "Download content locally when needed by running task sequence"

This is the recommended setting when you are deploying live systems as each task sequence step is evaluated and only the required data is downloaded. This speeds up the process when the TS is running, and since most data should be available locally the process is usually fairly quick. In order to avoid loading all driver packages on all machines you must filter them out by using the deployment variables as conditions.

The default setup for a TS deployment created to target PXE & Media as well as the full client is to "Download content locally when needed by running task sequence". In order to change this, you must change the Deployment option "Make available to the following:" in the deployment properties. Change it to "Only Configuration Manager Clients" and click Apply.

Figure 12 The available values – change to "Only Configuration Manager Clients".

Once you have changed the value (Don’t forget to hit the Apply button before switching tab) you can then go to the Distribution Points tab and change the Deployment options setting.

Figure 13 Available options have changed as PXE & Media is not set.

With this configured as above you can now pre-cache the entire content. Please make sure you have a valid condition on the Task Sequence (shown below) that will prevent the sequence from actually running. In the example below the PreCache variable is checked on the top folder, causing the underlying TS to not be executed. Since the download is initiated before the task sequence starts it will download all content, start the task sequence and then exit out as the PreCache variable is set.

Figure 14 How the PreCache variable should not exist for the TS to run.

You can use whatever mechanism of your liking to set the PreCache variable, as an example either use a Machine Variable or a Collection variable. The best way is probably to have a collection of your "best targeted" desktop systems with one or two machines per branch selected with a dynamic query.

Figure 15 How to set the PreCache variable on a collection.

What happens to the Cache Data during a push of the OS?

Content that is downloaded into the old Windows platform will not be saved by default. This is due to the fact that the process does not know whether or not the disk will be reformatted. Most packages will however be downloaded from other peers and then injected into the cache again, ensuring that many machines have the majority of the packages cached. If you require the cache to be migrated there are few simple steps needed.

1. Ensure that WinPE is of the right version, read more below about:

   1. Hash Versions and WinPE

   2. Cache Versions and WinPE

2. Ensure that the Format & Partition step has conditions on it

3. Ensure that the new OS supports the upgrade (You cannot go back in Cache format)

In place OS upgrade, can my cache come for the ride?

Yes: BranchCache Cache can be upgraded from 7 to Windows 10. The main rule is that the client content can only be upgraded or the left at the same version. If the disk is not reformatted during an upgrade the cache simply persists throughout.

Hash Versions and WinPE

The BranchCache for OSD components in WinPE can use the same feature as the full OS, and the downgraded Hash Version to V1 (Windows 7 & Server 2008). This means that Windows 7 machines can serve the WinPE downloads with content. Choosing V1 Hashes however removes the Data Deduplication functionality in BranchCache. Since De-Dupe and other V2 features greatly enhance BranchCache efficiency it’s worth skipping V1 if you can. Remember that you only need one V2 machines to service the branch during OSD. Therefore, for as long as the OSD process goes, you should always try to use V2. For regular deployments and in order to avoid 2x downloads over the wire it might be worth going with V1if needed but 2Pint Software recommends going with V2 directly wherever possible.

Note: For more information on the awesomeness of Data Deduplication head over to the 2PintSoftware website "All about BranchCache" section. Here’s the link to the Microsoft page that explains this worthwhile technology:-

Hash upgrade path is generally the same as for cache content discussed below.

Cache Versions and WinPE

Most people use Windows 10 WinPE to deploy their desktop systems today. It's also very likely that, for your future deployments, WinPE will be of a higher version than the operating system being deployed. With that in mind it’s good to know that Cache information can be migrated to the same or higher versions of the OS.

This means that if you are using WinPE of build 9600 (Windows 8.1) to deploy Windows 7 (Build 920/1) the Cache that is generated under WinPE cannot be successfully migrated to the new OS. Even though you run the Cache Enabler tool with the Move command, the new OS will not understand the new Cache format and re-initiate the Cache. This is the case even if you are using the V1 Hash format. Cache format and Hash format are not the same.

To avoid this situation, you must deploy your Windows 7 machines using a Windows 7 version of WinPE. The WinPE Generator tool will create Windows 7 Boot .wim files. If you are deploying Windows 8.1 with an 8.1 WinPE then the cache is updated.

The following WinPE Versions are available and work with BranchCache for OSD:

The following upgrade paths in green work, and the ones in red do not work.

Note: Windows 10 is a fast moving beast and you should test yourself for all scenarios that include Windows 10 upgrades :-

Table 1 Upgrade scenarios. Typically you can only upgrade the cache to the same or higher versions of Windows, i.e. 1607 to 1703 will work but 1703 to 1607 will not.

Working around Cache Versions

There are 3 ways of dealing with a Cache version mismatch:

1. Create a saved copy that will be used in the new full OS after it has been deployed.

2. Do a "Download all content before..." - The Configuration Manager client will keep the Cache during the OSD process it can then be used to inject into the new full OS.

3. Do nothing and hope for the best - Most machines are likely to have bits and pieces of the OSD packages and it might just work ok.

One way of dealing with the Cache Version mismatch is to create 2 copies of the Cache. If you start in Windows 7 and end up with a new Windows 7 you can save that cache in 2 copies. One for the WinPE part (which will be upgraded but still used and thrown away after the PE phase) and then one copy for the new OS. It is planned to streamline this functionality in future releases so make sure that you subscribe to the 2Pint mail and media lists to get up to the minute functionality.

Can I re-use my already Distributed Content?

If you have already deployed/distributed lots of packages/applications/images out there then the answer is "Yes". Instead of clearing out the Configuration Manager Client Cache you can inject all of that data into the BranchCache Cache. This also applies to other third-party caching software or hardware. On the proviso that you have physical access to the files directly in a readable format, you can inject them into the cache.

The same applies if you have a Distribution Point that you would like to remove, simply inject the data into the caches instead.

Note: In order to inject data into the BranchCache Cache you need to have the server secret available, otherwise data will not be able to be shared with other clients on the subnet. Contact 2Pint Software for more information on this subject and we can point you in the right direction. Remember – we know this technology inside out and are always happy to help.

Setting up Pre-Caching

Setting up Pre-Caching is not a complex procedure. You should just keep the following in mind:

1. All content of the Task Sequence will be downloaded to the Configuration Manager client cache as well

   1. This means that a Task Sequence referencing 20 GB of data will take up 40GB of disk space without de-dupe taken into consideration. This is due to the fact that content will be stored in both the Configuration Manager cache as well as the BranchCache cache.

2. The Task Sequence will run, so ensure that you have set a Variable Condition to stop actual execution.

3. The Configuration Manager client will start caching as soon as the policy has been received for a run time in the future providing the task sequence policy has not been received before.

Note: Setting up a TS to download all content before starting is not recommended for OSD deployments.

Setting Up Cache-Injection

Cache Injection is a technique where content that is already available on a remote machine is injected into the cache. There are many options available for Cache Injection actions.

The following injections can be done:

1. Injecting the Configuration Manager client cache into the BranchCache Cache

2. Injecting the Office Offline installation media into the Cache

3. Creating a .wim of the local machine and injecting it into the cache

4. Injecting the entire hard drives, every file, into the drive

The last two ones are obviously great for de-dup. Contact 2Pint Software if you are interested in this as we are working on some upcoming tools to enable these actions.

The OSD Toolkit is designed to allow Peer-to-peer (P2P) at background speeds as well as high speeds using the Turbo features. However, in some cases the speed is not enough or cannot be used as intended. A download from a unused local server will typically run at around 1000Mb/s, which is very fast, therefore a speed that we have gotten used to. If this server is shared across 10 concurrent downloads though, the theoretical speed is divided by 10, which is 100Mb/s. This speed is typically lower than the P2P speed that can be achieved, so when speed is this low, it makes sense to use P2P and not hammer the server.

The OSD Toolkit has advanced logic which is designed for allowing;

1. Use the server directly for locations where there are servers, still filling up BranchCache or other P2P technologies, but using them in a local mode instead, which improves speed.

2. Detect when speeds from local servers are low, then dynamically enabling peer-to-peer.

This allows for the following scenarios to be improved;

1. A single machine is built at a main office/build center with good local servers, but the machine is to be shipped to a location where no servers are available, so we want to fill up the BranchCache cache. In this case the machine uses local BranchCache mode, and just fills up it's own disk, but still downloading at close to wire speed.

2. In a situation where 500 machines are to be built at the same time, in this case the local P2P speeds will greatly outnumber any server capabilities, so here we dynamically enable peer-to-peer.

3. It allows the best of both worlds, fast server speeds when available and P2P when required as the server is busy.

What is well connected anyway?

Well connected is a term borrowed from the StifleR product set which means a "well connected site" either has good enough bandwidth to servers that are typically locally to the site itself. But even a site with 200Mb/s can be considered "well connected".

How can I determine if a site has local servers?

In our world, this is done by StifleR, in your world, we don't know, but you can still benefit from the functionality by setting the right task sequence values if you find out when you have local servers or not.

Local Mode

The local mode means the client does not query the network, instead it builds it's own cache over time, just like a read only file cache. Once the machine is switched to any other mode, this cached data can be server to other peers.

How do I controls this?

The following task sequence variables control this behavior.

The WellConnected2PS task sequence variable

Ifs the WellConnected2PS task sequece variable is set to "true" the binaries will treat this location as well connected by default and set BranchCache to local mode for any download. If the speed from the server goes below 100Mb/s after 5s of transfer time, the machine switches to distributed mode.

If the package has more than 100 files, local mode is automatically enabled as 100 files will never peer to peer well.

The WellConnected2PSDisable variable

If this variable is set, the machine does not switch mode, and whatever mode was configured is kept.

1. Generate a new WinPE mage by running the BranchCache for OSD generator tool

   1. Decide if you want to use StifleR or not, if so, add the /Add-StifleR parameter on the command line

2. Modify the Task Sequence and add two steps:

   1. Run "BCEnabler.exe Enable" in your sequence to enable BranchCache and BITS services

   2. Run "BCEnabler.exe Move" in your sequence to move the data cache to the new full OS

   3. Set the SMSTSDownloadProgram variable to ‘BITSACP.exe’ to enable BITS downloads in the Task Sequence

3. Add the 2Pint Software OSD Toolkit Turbo license into a Task Sequence variable named "2PintTurboLicense" and set it to your license you have received.

4. Done!

Microsoft allows third parties to create an Alternate Content Provider (ACP) to allow downloads to be handed over to other technologies when the default Microsoft method may not work. The textbook definition from Microsoft:

"An Alternate Content Provider exposes a set of API calls and modifies the function of Data Transfer Services, such that an additional provider other than BITS can be used to retrieve the packages."

There are two types of alternative Content Provider (ACP) types:

• System – Which requires an install and replaces BITS as the download engine

• Task Sequence – Requires no installation on the system, and is only called during a Task Sequence, from a Task Sequence, using a Task Sequence variable

The OSD Toolkit uses a Task Sequence only ACP, for all other downloads, BITS is used in conjunction with BranchCache.

BITSACP.exe – The 2PintSoftware Task Sequence ACP

BranchCache is used for Task Sequences in the full OS when they are set to "Download all content locally before starting task sequence" as this means that they are scheduled via BITS. The BITS downloader supports BranchCache on all operating systems. An issue arises when a Deployment is set to "Download when required".

In this case only Enterprise clients can utilize BranchCache as these downloads use HTTP for content transfer and only these systems have native HTTP support for BranchCache. Although Enterprise can work without the ACP, we recommend the use of it for better speed and reliability.

Note: The necessary TS Deployment configuration is modified via a PowerShell script as this is not configurable directly in Configuration Manager. See the next section for details.

On Windows Pro machines custom configuration is required in order to make a "Download content locally when needed by running task sequence" distribution BranchCache enabled. This is configured via BITSACP.exe. This can be seamlessly integrated into any Configuration Manager 2012 task sequence deployment via the use of the Alternative Content Provider (ACP) support.

Note: If you want to use the same downloader on Enterprise in order to utilize the BITS bandwidth mechanism there is nothing stopping you. StifleR customers should always use the BITSACP to allow better monitoring. The BranchCache speed is also greatly improved by using the BITSACP with the turbo function.

Use BranchCache on Windows Pro

As already mentioned, Windows Pro only supports BranchCache through BITS, or any other third party program communicating with BranchCache directly. This means that the "Download all content locally before starting task sequence" settings on Task Sequences Deployments will force the use of BranchCache as the content is downloaded by BITS before the task sequence is executed.

The snag with that setup is that ALL packages referenced by the task sequence are downloaded, even packages that have conditions on them, because the download engine does not evaluate these conditions. To get around this, you can set the Task Sequence deployment instead to: "Download content locally when needed by running task sequence", which makes the task sequence start and then only download packages when the conditions have been evaluated. The problem with this solution is that the Task Sequence downloader uses it’s own download engine rather than BITS.

This means two things:

1. Downloads are NOT throttled and likely to fail over limited bandwidth WAN pipes.

2. Downloads are NOT BranchCache enabled on Windows Pro machines as there is no native HTTP support for BranchCache.

The 2Pint Software BITS BC TS Download component BITSACP.exe addresses these issues by:

1. Acting as an Alternative Content Provider through the Extension provided by Microsoft to allow such third party download providers

2. Redirecting all Downloads to BITS with BranchCache support & bandwidth management

NOTE: When running a task sequence with an Alternative Content Provider, all downloads are first tried with the ACP. If this returns an error or if the data is not valid the client will automatically fall back to the regular built-in downloader.

Figure 16 A Windows Pro Machine is downloading packages in a task sequence using BITS & BranchCache. Although scheduled to run at 1Mb/s (WAN) it is caching local content at 61Mb/s from already cached content from its peers.

Using an Alternate Content Provider

In an Operating System Deployment scenario, distribution point locations that are stored in task sequence variables are currently inaccessible to an Alternate Content Provider. This means that applications in System Center 2012 Configuration Manager that are written to use the Alternate Content Provider APIs are affected.

Microsoft recognized this short coming in functionality and issued an update. Information on this update and Microsoft Support for ACPs is available in the following knowledge base article:

The above article describes the update to support Alternate Content Providers in Task Sequences in System Center 2012 Configuration Manager.

To support an Alternate Content Provider in a Task Sequence, this update introduces the SMSTSDownloadProgram task sequence environment variable.

The SMSTSDownloadProgram task sequence environment variable is specified as follows:

• A predefined environment variable that contains the path of the downloader program (.exe file) will be set in the SMSTSDownloadProgram task sequence environment variable.

During the download process, the task sequence download library will check the environment variable to verify that there is a defined downloader program. If there is, then this program will be used to perform the download.

The BITSACP.EXE is available in the boot.wim file generated by WinPEGen.exe so there is no need to copy it into the boot image. The "BCEnabler.exe Move" command also moves this to \Windows\System32 for the deployed Operating System.

The following command line parameters are passed to the external downloader program:

• Package ID

• Absolute path of the download folder

Notes

• The Configuration Manager client expects at least one location. The location will be passed to the Alternate Content Provider as it can use the Configuration Manager Distribution Point in certain situations.

• The Alternate Content Provider can return a fallback code or an error code. When a nonzero code is returned, the Configuration Manager client will fall back to Content Transfer Manager and Data Transfer Service.

• An Alternate Content Provider will work only inside a Task Sequence. It cannot be called outside of a task sequence.

Implementing the Alternate Content Provider

After all the explanation and environmental tweaks the actual configuration required to kick off the ACP is done in minutes.

First, find the appropriate place in the Task Sequence to add the step that enables the Task Sequence ACP. To ensure that all content is downloaded using the new downloader this would normally be one of the first actions, before any Packages are referenced. When you have determined the best place add a "Set Task Sequence Variable" action from the Add menu. Then give it a name of your liking and set the Task Sequence Variable name to: SMSTSDownloadProgram and set the Value to BITSACP.exe.

Already running computers

If you want to use the ACP for task sequences set to "Download on demand" for already running operating systems you must ensure that the executable is available on the machines on which it is to be run. This can be achieved by either putting the executable in a separate package/program which is then distributed to all machines before reimaging or by copying it to the machine as a part of the task sequence. In order to be safe you can do both - distribute the executable to all systems and also add a step in the task sequence to copy it to Windows if it’s missing.

When the Task Sequence executes, the downloader executable will be called and will start the download. The downloader updates the Task Sequence progress bar accordingly. The following picture shows it in action:

Figure 17 The downloader in action. This shows both the number of files and number of Bytes left to download.

The Downloader creates BITS jobs for each package that is requested by the task sequence. This can be verified by running BITSADMIN.EXE or PowerShell cmdlets to list the download jobs.

Figure 18 BITSADMIN listing active downloads as the Task Sequence is running.

Logging

Event Viewer

Figure 19 The event logged by BITS after a download. Note the BranchCache data information.

Registry keys

Not logging as such but when BITSACP and BCEnabler run they do write some very useful information to the registry. This happens in WinPE as well as in the full operating system.

The information is written to the HKLM\Software\2Pint Software key.

Under the BCEnabler sub key the following values are written:

• BCPort - Port for BranchCache to operate on. Default will show 80 (decimal).

• PreferedContentInformationVersion - Version of BranchCache. Unless specified this will show (2) for a Win8 or later WinPE or (1) for a Win7 (3.1) version of WinPE.

• CacheRootFolder - the directory under which the cache data is stored.

Figure 20 The port and path to the files being used by BranchCache. These are updated at Boot and at Enable and Move steps.

The ACP writes package information to a separate key for each located under the BITSTS key.

Figure 21 Generic information written under the main key. Each package then has its own key underneath the BITSTS key in HKLM\Software\2Pint Software\BITSTS

For each package the following information from the BITS job is written to a key underneath the BITS registry key. The name of the value is in the format of the ContentID such as R1101234.

The data stored is:

• Number of bytes from the DP

• Number of bytes downloaded from peers (also de-duplicated data)

• Total bytes of the content

• Total bytes downloaded

• Number of files in the content

• Number for files transferred in the content

NOTE: This data may be used to create custom or other action in the task sequence.

Figure 22 Data and statistics for a package being downloaded. Note that the BranchCache statistics are not available until the download has completed.

Troubleshooting

• The status of a package can be monitored directly from the registry as it downloads.

• If no data is coming from BranchCache check clients and firewall settings.

• From the command prompt enter

>netsh.exe BranchCache show status all

while the download is happening. If data is being loaded into the cache but not from BranchCache Peers it is likely to be a firewall/port issue. (Assuming that the other clients have the required data cached)

• To view the attempted network connection type "netstat –n", it should list the attempted BranchCache connections.

Custom WinPE Language

Customizing the Boot Image with Non-Default (EN-US) language options is supported but requires access to source media with the same language.

For more information on how to create a localized image please review:

Example of command lines using DISM.EXE to create a Swedish WinPE version with the language ID of: sv-se

copype amd64 c:\temp\win10amd64

dism.exe /mount-wim /wimfile:C:\temp\win10amd64\media\sources\boot.wim /index:1 /mountdir:C:\temp\win10amd64\mount

Dism /Add-Package /image:C:\temp\win10amd64\mount /PackagePath:"C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Preinstallation Environment\amd64\WinPE_OCs\sv-se\lp.cab"

Dism /image:C:\temp\win10amd64\mount /set-allIntl:sv-se

REM Dism /image:C:\temp\win10amd64\mount /Set-UILang:sv-se

REM Dism /image:C:\temp\win10amd64\mount /Set-SysLocale:sv-se

REM Dism /image:C:\temp\win10amd64\mount /Set-UserLocale:sv-se

REM Dism /image:C:\temp\win10amd64\mount /Set-InputLocale:041d:0000041d

REM Dism /image:C:\temp\win10amd64\mount /Set-TimeZone:"W. Europe Standard Time "

dism.exe /image:C:\temp\win10amd64\mount /add-package /packagepath:"C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Preinstallation Environment\amd64\WinPE_OCs\winpe-wmi.cab"

dism.exe /image:C:\temp\win10amd64\mount /add-package /packagepath:"C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Preinstallation Environment\amd64\WinPE_OCs\winpe-scripting.cab"

dism.exe /image:C:\temp\win10amd64\mount /add-package /packagepath:"C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Preinstallation Environment\amd64\WinPE_OCs\winpe-wds-tools.cab"

dism.exe /image:C:\temp\win10amd64\mount /add-package /packagepath:"C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Preinstallation Environment\amd64\WinPE_OCs\WinPE-SecureStartup.cab"

dism.exe /image:C:\temp\win10amd64\mount /add-package /packagepath:"C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Preinstallation Environment\amd64\WinPE_OCs\sv-se\WinPE-SecureStartup_sv-se.cab"

dism.exe /image:C:\temp\win10amd64\mount /add-package /packagepath:"C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Preinstallation Environment\amd64\WinPE_OCs\sv-se\WinPE-WMI_sv-se.cab"

dism.exe /image:C:\temp\win10amd64\mount /add-package /packagepath:"C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Preinstallation Environment\amd64\WinPE_OCs\sv-se\WinPE-Scripting_sv-se.cab"

dism.exe /image:C:\temp\win10amd64\mount /add-package /packagepath:"C:\Program Files (x86)\Windows Kits\10\Assessment and Deployment Kit\Windows Preinstallation Environment\amd64\WinPE_OCs\sv-se\WinPE-WDS-Tools_sv-se.cab"

dism.exe /unmount-wim /mountdir:C:\temp\win10amd64\mount /commit

Running the generator is the same as a regular English version, but it will show the non-default language. If the language is not matching the WinPE version it will error.

The OSD Toolkit is pretty easy to troubleshoot following the guidelines here:

Logging order

The following list is the order of logs to check:

1. If using iPXE, make sure that the iPXE WinPE Client succeeded by checking the 2PXiPXEWinPEClient.log in the X:\Windows\Temp directory.

2. Make sure that the BCEnabler.exe step was run and completed OK

3. For each package that is downloaded, the following order of logs are created/overwritten, please see Appendix D for successful log examples:

   1. BITSACP_Startup.log is written to the directory where the TS logs to, in WinPE this is typically in X:\Windows\Temp\SMSTSLog\ folder.

Task Sequence does not use the ACP

When running a task sequence and you want to use the ACP, ensure the following:

1. If in WinPE, make sure that you have build the WinPE with the help of WinPEGen.exe

2. If not in WinPE, make sure that the BITSACP.EXE binary is present on the Windows computers running the Task Sequence.

3. If in WinPE, make sure that the ACP variable is set correctly, if it's not set, due to different paths in your TS, it's obvious as the smsts.log does not mention that its executing the TS ACP itself. If the TS ACP is called, it will have a line like this:

Using download program: BitsACP.exe

The full logging entry for a package should look as the following:

Trying https://someserver.your.biz/NOCERT_SMS_DP_SMSPKG$/CP100209.

Using download program: BitsACP.exe

BitsACP.exe X:\Windows\TEMP\SMSTSDownload.INI CP100209 C:\_SMSTaskSequence\Packages\CP100209

Command line for extension .exe is "%1" %*

Set command line: "BitsACP.exe" X:\Windows\TEMP\SMSTSDownload.INI CP100209 C:\_SMSTaskSequence\Packages\CP100209

Executing command line: "BitsACP.exe" X:\Windows\TEMP\SMSTSDownload.INI CP100209 C:\_SMSTaskSequence\Packages\CP100209

1. The next line is key, as that is the return code from the ACP:

Process completed with exit code 2147942421

1. The return code is in decimal, but convert it to hex, and the value is this: 80070015, the 8007 indicates that it’s a Windows return code of some sort, so remove that and convert back 15 from hex to dec (21). The console command "net helpmsg <nr>" will tell you what it really means:

1. In this case, there is also a logfile, called BITSACP_Startup, that contains the error itself and some more information:

1. So open up the log an it will have the following lines (as an example):

Command-line arguments:

BitsACP.exe BITS Pro Downloader

X:\Windows\TEMP\SMSTSDownload.INI

CP100209 BITS Pro Downloader

C:\_SMSTaskSequence\Packages\CP100209

Checking to see if we are running in WinPE.

Initializing COM...

Failed to Create BITS COM Object.

The error that it cannot Create a BITS COM object is due to the fact that the BCEnabler.exe Enable command is not executed before the ACP is run.

1. The following log applies in WinPE (This is mentioned in the guide above)

   1. Run "BCEnabler.exe Enable" EACH TIME you enter WinPE

   2. If you have a complicated TS, make sure that the ACP is set AFTER BCEnabler command line has run.

   3. Before ending the WinPE session, and after the OS image is applied, make sure you run BCEnabler.exe to move the cache etc. into the full OS.

BITSACP fails to download package

This can happen for many reasons, but a typical one is that the Network Access Account is not set. This can be spotted in the main BITSACPSVC_<PackageID>.log file:

Connecting with path: /NOCERT_SMS_DP_SMSPKG$/AP200003

Successfully set QueryInterface on Download Job...

Connecting to server...

Trying to connect...

Server replies with Status: 401

The server requires authentication. Sending searcing credentials...

Trying NAC: _SMSTSReserved1-000

UserName:

Empty value for account

NAC is not valid, cannot authenticate, add valid NAC please:000

Returning: FALSE

Returned from GetPropFindXML

Failed to get HTTP XML Data with PROPFIND webdav request.

The following keys are written to the registry under HKLM\Software\2pint Software\BITSTS\<DeploymentID>\<ContentID> registry path.

3.0.6.0 - 2022-12-08

1. Changes to registry keys for download statistics for improved tracking.

2. Changed incorrect error log level entry to informational level.

3. Changed incorrect error log level entry to warning level.

3.0.5.0 - 2022-11-23

1. Fix for broken Turbo, the Turbo now retries without the risk of breaking the hash of the file being downloaded.

2. Updated reporting of the Turbo feature. We now write each Turbo exit code to the content registry key.

3. Updated with more information on registry keys for each download for post deployment troubleshooting.

4. Support for setting BranchCache into local mode vs distributed mode depending on speed of transfer.

5. Fixes an issue where Windows 11 WinPE media creates a BranchCache database that is then wrongly imported into Windows 10. We recommend using Windows 10 WinPE media for deploying Windows 10. Databases are now never transferred if WinPE version is higher than the target OS.

6. The BITSACP now supports switching servers if runtime servers are not responding correctly and other servers are available.

7. Fixes an issue where special ACL's are written to the download folder when content is downloaded for individual accounts.

8. Updated script for reporting on download times and execution times available here:

3.0.3.0 - 2022-10-06

1. Added support for detecting sites with great bandwidth moving client to non BranchCache.

2. Fixes an issues for Turbo in networks generating a large amount of timeouts. We have another better potential in testing in testing now.

3.0.2.0 - 2022-07-18

1. Fixes an issue where modern CPU's seems to overload the network when using Turbo feature, causing the BranchCache API's report that no more data is available on peers in some circumstances (even though it's available on peers).

3.0.1.0 - 2022-07-04

1. Fix for ACP Turbo feature to work with CCMTOKEN based authentication.

3.0.0.8 - 2022-02-04

1. Fixes an issue where HashGen.exe (Turbo feature) caused hash mismatches.

2. Fixes an issue where HashGen.exe was not providing progress.

3. Fixes an issue where HashGen.exe was providing progress even if it was disabled.

4. Fixes an issue where BCEnabler.exe sometime failed to configure BranchCache.

5. BCEnabler support for Windows 11 PE versions.

6. BCEnabler.exe has improved logging.

7. BCEnabler.exe will now return an error code if BranchCache fails to initialise properly.

8. Added support for Upload Jobs on the BITSACP. More coming on this.

9. Reworked BITS logic for modern Windows 10/11 PE versions.

10. Fixes an issue if the Network Access Account is not required for WebDav access but is required for the BITS jobs.

11. Support for restarting bits Jobs in the Error state.

2.9.4.0 - 2021-08-23

2. Fixes an issue with the BITSACP if several Network Access Accounts are used and the password is expired on one of them, leading the BITSACP into a never ending loop.

3. Fixes an issue if BITSACP service is left behind due to app crash.

2.9.3.7 - 2021-06-11

1. Fixes an issue where only the x86 version of WinPEGen.exe is available.

2. Fixes an issue where x86 WinPEGen cannot create x64 media properly when StifleR is integrated in the boot image.

2.9.3.6 - 2021-06-01

1. Fixes an issue where logging is not reporting OK if BITS job status stays in "Connecting" mode and never transfers to "Transferring" state although the job is transferring.

2. Fixes a division by zero issue that can happen under certain scenarios which crashes the ACP.

3. Fixes a potential integer overrun for very large files and very slow networks.

2.9.3.5 - 2021-04-27

1. Adds functionality to avoid having to run BCEnabler.exe after reboots in WinPE.

2. Updated logging for certain cases.

3. Ensures BCEnabler.exe cannot run in Full OS.

2.9.2.25 - 2020-11-26

1. Minor release allowing for future phone tethering capabilities.

2.9.2.22

This release incorporates important bug fixes.

1. Fixes issues where system registry is not unmounted properly due to handle still active when using BranchCache version 1 (For Windows 7, yes that still exist).

2. Resolves a logging issue where a log statement crashes the BCEnabler if port and BCVersion is not specified on the command line. (Not that anyone runs BranchCache on default port 80 right???).

3. Fixes a cache issue where the NTFS ACL's are not set correct in some circumstances. This leaves the cache dead in the water and BranchCache is not working correctly in the full OS. This issue was introduced in 2.8.2.9 and later versions and the results depends on several factors as disk layout etc. For machines built on these versions, check that the cache is set correct, and if not, the fix is to run the following commands (as an example)

   Netsh BranchCache Reset

   Netsh BranchCache set service mode=distributed

4. OSD Toolkit version and BCEnabler binary versions are now being transferred to the full operating system registry under HKLM\Software\2Pint Software\BCEnabler

2.9.2.19

Release to fix some of the functionality we broke in the 2.9.2.6 release as well as disabling the WinHTTP intergration with BranchCache to help with our customers using ConfigMgr with Enhanced HTTP. (Contact us for more info on this issue)

1. Fixes regression when cache is present in OS image being applied, which breaks BCEnabler MOVE step.

2. Fixes for HTTPS ConfigMgr environments where we select the wrong virtual directory to authenticate with.

3. Improved handling where Turbo takes a second to release file handles. Improved work to troubleshoot hash issues.

4. WINHTTP is disabled in WinPE to improve reliability in CCMTOKEN scenarios.

5. Removed last entries for policies for BranchCache.

6. Fixed issue where BranchCache would cause a BSOD with "CACHE MANAGER" on reboots in WinPE.

7. Fixed issue where the improved logic to change the cache location causing issues to re-initiate old caches on reboots.

2.9.2.9 - Introducing 'Turbo Edition'

This was a quick release to fix some previous issues in 2.9.2.6 around HTTPS and CCMTOKEN paths and to enable licensing for the Turbo feature.

2. Turbo now also work on HTTPS with PKI scenarios

4. Allow HTTPS override in full OS where no Network Access Account is available and BITSACP fails due to lack of credentials, we then redirect to HTTPS on SMS_DP_SMSPKG paths.

5. Fix for bugs when HTTPS usage in full operating system environments where no Network Access Account is present.

6. Fix for StifleR Service not started in all scenarios by BCEnabler.exe.

2.9.2.6

This was a major rework of the OSD Toolkit to improve stability and performance of both the BCEnabler as well as the BITSACP. Please test in QA/Test environments before deploying in production to make sure that all your scenarios are working.

1. Changes to BCEnabler logic for improved stability

2. Changes to Firewall transfer rules to full operating system

3. Fixes bug if version is not specified on the BCEnabler Enable command line

4. Changes to allow turbo for 5 files, largest first if over 100MB in size

5. BITSACP: Improved progressbar to also who peer data

6. Improved support for PSD

7. Fixed hash issues where small packages might fail

8. Fixed BCEnabler Move issue when moving from other disks

9. Improved logging to roll over if log files are over 1MB in size

10. All logging is now in to the SMSTSLog folder

11. Improved spelling and grammar in log files, thank you Mikael Nyström for going through all logs

12. Turbo feature completes download if 100% of files are available locally

13. The BITSACP.EXE, HashGen.exe and BranchCacheTool.exe are all signed

14. BITSACP.EXE, HashGen.exe and BranchCacheTool.exe are all moved to full OS disk as part of the BCEnabler MOVE command line options.

1.9.7

This is the 1.9.7 release version of the executables, future binaries and capabilities might differ greatly.

This release contains the following features:

1. BranchCache WinPE Generator - For creating BranchCache enabled WinPE Images

   1. There are two versions, one x86 and one x64

      1. Both versions can be used to create x86 and x64 images. Only difference is of course that the x86 version of the tool does not run on a x64 system.

   2. To reiterate, the tool architecture has nothing to do with the generated architecture of the boot images.

2. BITS & BranchCache WinPE Enabler – For enabling BranchCache in WinPE task sequences/command line deployments

   1. Both x86 and x64 versions are included

   2. These are automatically injected into WinPE versions created by the Generator tool.

   3. Initializes BITS and starts dependent services

3. Alternate Content Provider for WinPE and Task Sequences

   1. BranchCache BITS BranchCache Downloader with BITS & BC Integration (BITSACP.exe)

   2. Both x86 and x64 executables are available, although x86 should work on x64 in most circumstances as well (not in WinPE as syswow is not included)

   3. Runs in both WinPE as well as full OS

   4. Generates the same reporting structure if the BITS Reporter is on the system

Happy Caching!

//The 2Pint Team

BranchCache First Timer?

If you are not familiar with BranchCache we recommend that you take a look at our BranchCache page before continuing with this document as it covers several key factors of BranchCache.

The following is an edited version of a blog post from the 2Pint Software Web Site. Please visit the Web Site for the latest advice and tips on managing this issue.

Managing BranchCache Cache Versions in a Windows 7/Windows 10 mixed environment or “When to downgrade BranchCache clients and how”

The other day I was asked to clarify when to use which of the two hashing versions in BranchCache, so thought I would write it all down in one place for future reference.

To give a bit of background. BranchCache comes in two version; V1 that came with Windows 7/Vista and V2 that came with Windows 8 and subsequently Windows 10. A V2 machine can operate as either V2 or V1. Which to use is a not-so-straight-forward policy decision for your organization. In addition to the client operating systems the OS version of the server handing out the BranchCache hashes also requires consideration. V2 hashing was only introduced in Server 2012. A Server 2008 R2 can only serve V1 hashes and a V2 client will be auto downgraded to V1 when it contacts a V1 server.

You can downgrade a client manually by setting the following group policy option:

Now to the crunchy question: If an organization has a mix of both Windows 7 and Windows 10 clients, which version should they use?

The answer is of course - It depends!

A V2 client can be downgraded to V1, which means it can then P2P with a Windows 7 V1 client just fine. All good there. The problem is that V2 is much, much more efficient than V1, so once you start having more and more V2 machines, it makes sense to start shifting to V2. But there are some technical considerations that come into play.

1. A V2 client can, at any time (even when its operating as native V2), respond to V1 requests for content as long as it has that content in its database.

2. A V2 client can inject files as V1 into a V2 database

2Pint’s StifleR product, has a feature that enables a V2 client to generate V1 content on the fly. In the scenario where a V2 client is downloading Office for instance it can, at the same time, cache that same content as V1.

Smart huh? Yes! But what does it really mean?

It means that for all apps and other cacheable content, the V2 clients can generate V1 content for older clients while taking advantage of the fact that the V2 delta content is much smaller than V1 and thus keep the bytes on the wire to a minimum.

Ok, but what if I don’t have StifleR? How can I deal with all of this? Well, you can still inject that data as V1 content into your V2 BC data cache and then you need to run our BranchCacheTool.exe with the correct command line switches, or use our Cache Injector script logic. So far so good.

We then have another issue to overcome, which is seen when building machines using our OSD Toolkit. If you are deploying new Windows 7 clients, using a WinPE image created from Windows 10 (as you do) this defaults to BranchCache V2. When that machine reboots from WinPE the Windows 7 V1 machine cannot recognize the V2 cache content. BranchCache can only upgrade, never downgrade, which means that all that cache data is invalidated and purged.

The OSD Toolkit allows for the BranchCache version to be set using BCEnabler.exe with conditions/and/or variables on the command line:

In the above example, the 2.0 command line option tells the BCEnabler.exe binary to configure BranchCache to use Version 2.0. If it’s changed to 1.0 the tool will downgrade the client to V1 which is then compatible with Windows 7 peers.

So, why would we ever use V2 hashes when deploying Windows 7? Well typically the answer is, we don’t. But since V2 is so much more efficient than V1, there are benefits of using it when syncing large files, like .wim files. For this reason staying on Windows 10 V2 hashing can make sense, as all the other Windows 10 clients around can be used as source, using V2 hashing, grabbing device drivers etc. But if the Windows 7 build has a lot of content that is unique to the Windows 7 stage, that content should never be on Windows 10 boxes, and will have to be pulled down over the wire again. Problem!

So what’s the best compromise? Typically, if you are deploying new Windows 7 machines (Why????) you should set the version in the OSD Toolkit option to use V1, getting content from the other V1 clients, and possibly V2 that have V1 data injected on them. All great. Then switch to V2 the day when you stop deploying Windows 7 and never look back. Done!

Yes but… remember what I said about that the BranchCache data can only be upgraded otherwise it is purged. Well, it actually applies to the database version, not the content inside it. So, when the Win10 DB is moved to Windows 7, it’s purged right into space… all data gone! But… how do we solve that? Well, the workaround is to have a step at the end of the sequence to dump all of the content from the Packages\ folder from the _SMSTS folder right back into the cache, just before exiting the sequence. More on that in another upcoming blog post.

Problem solved, BC forever!

OSD Toolkit 1.9.9.3

1. Fix where ACP did not handle DNS resolve fails well when requesting the webdav information.

OSD Toolkit 1.9.9.2

1. Fix where ACP did not handle HTTP errors well when requesting the webdav information.

2. Fix where ACP did not handle network timeouts when requesting webdav information.

3. Fix where ACP hung on empty packages with zero files or folders.

OSD Toolkit 1.9.9.1

1. Fix where ConfigMgr CCMTOKENAUTH is wrongly handed to the ACP, causing downloads to stall.

OSD Toolkit 1.9.9.0

1. Updated StifleR client with version number 1.9.9.0

2. Fixes where filter driver not always applies the right policy where the device has no IP address at service startup.

3. Fix where the OSD BranchCache Turbo was not initiated properly.

4. WinPE client was missing iperf and other binaries which could cause issues for new locations.

5. Fix where "BCEnabler.exe Move" command did not transfer the StifleRulez.xml to newly build clients.

OSD Toolkit 1.9.7.3

1. Updated StifleR client for StifleR server 1.9.7.3

OSD Toolkit 1.9.7.0

1. Fixes issues with StifleR starting too early and fails to detect DNS availability.

2. Fixes issues where wrong version of Stifler filter drivers are used.

3. Fixes issues where StifleR is set to start manually in full OS.

4. Fixes where StifleR service was not started correctly when restart steps are in the sequence.

OSD Toolkit 1.9.6.0

1. Fixes issues with TS Helper crashing, causing high CPU load, driving down P2P speeds.

2. New StifleR client using Filter driver, working in WinPE and subsequent OS deployment steps in full OS.

3. Fixes where StifleR service was not started automatically when restart steps are in the sequence or when not using iPXE Anywhere.

4. ACP no longer controls the priority of jobs when StifleR is available.

5. Fixes where the turbo function of the BITS ACP is not working.

OSD Toolkit 1.9.2.0

1. Fixes issues were jobs complete before the monitoring thread is started, hanging jobs

2. Fixes issues were failed downloads clog the queue, failing subsequent jobs

3. Improved logging and fix for logging to Windows directory when CCM client is present on the machine

OSD Toolkit 1.9.0.0

Fixes issues were jobs would stop randomly when BC was disabled

1. Fixes issues where ACP would crash if BranchCache service was stopped

2. StifleR 1.9 is added

3. StifleR adds a variable of WellConnected2PS to the TSEnv if site has good connectivity and is marked as "Well Connected" in StifleR

OSD Toolkit 1.7.6.0

1. Fixes issues where a custom port is used for BranchCache and clients cant share in WinPE

2. Remove black box from wpeutil.exe when booting to WinPE

3. Showing progressbar when dowloading policies in WinPE when using StifleR

OSD Toolkit 1.7.5.0

1. Fixed issue where small jobs failed with the BITSACP when running on fast hardware.

2. Fixes issues where the BITS policy times are not accurate from StifleR.

OSD Toolkit 1.7.3.0

1. Includes fix where BITSACP failes under Windows 7.

OSD Toolkit 1.7.2.0

1. Includes StifleR 1.7.11 client which has fixes for bandwidth stuck to 1Mb/s

2. Fix for BITSACP.EXE supports working BETA version of BranchCache Turbo for single file downloads over 100Mb (Broken before)

3. Fix where BranchCache were not set up properly in full OS by the "BCEnabler Move" command

4. Fix for BranchCache Enabler to work in reboots in to WinPE from WinPE

OSD Toolkit 1.7.1.0

1. Includes StifleR 1.7.7 client

2. BITSACP.EXE supports BETA version of BranchCache Turbo for single file downloads over 1Mb

3. Fixes bug where BITSACP failed to create directories sometimes, and where BCEnabler failed if reference image had BC enabled

OSD Toolkit 1.7.0.0

1. BITSACP.EXE now creates FOREGROUND jobs by default (Better speed)

2. BITSACP.EXE supports Internet facing DP's

3. Bug fixes

OSD Toolkit 1.6.0.0

1. Rename to OSD Toolkit to support future Delivery Optimization features without to much confusion.

2. BITSFIST.EXE renamed to BITSACP.EXE

3. BITSACP.EXE supports download from Internet DPs in WinPE

4. StifleR 1.6.2.6 Upgrade

5. BCEnabler supports additional command lines

6. Changes to service managment for better reliability

7. Improved BITS policy for BITSACP jobs, jobs are now foreground

8. Sample scripts removed

BranchCache for OSD 1.5.0.0

1. iPXE Client is removed and not longer needed to be injected into the WinPE image as iPXE does that for you.

2. iPXE Client no longer called as first command line

3. StifleR is included if you add /Add-StifleR to the command line

4. BCEnabler changes

   1. BCEnabler sets BranchCache as automatic startup in the “BCEnabler.exe Move” step

   2. If StifleR is used and not in the base image, it will transfer the service to the full OS to be available during the rest of the task sequence

   3. Writes the Completed registry value when BranchCache is enabled

5. BITSFist reports progress slightly better

BranchCache for OSD 1.4.2.0

1. Fixed scenarios en-GB media (and possibly others) would fail to generate due to missing .mui files in media source.

2. All binaries are now signed.

BranchCache for OSD 1.4.1.0

1. Fixed scenarios where BTISFist would fail in newly deployed OS. Ensure that BCEnable.exe MOVE command is run and it should work nicely now.

BranchCache for OSD 1.4.0.0

1. Support for localized images

2. Support for N media types

3. Support for Education media

4. Updated binaries for iPXE Anywhere

5. Bugs from iPXE media Solved

6. Improved Support for custom BranchCache port

7. Updated .sms files for simple import into ConfigMgr

8. Updated Sample TS for enabling BranchCache on a custom port

WinPE Generator 1.3.0.0

1. Support for Windows 10 240 and above builds

2. Changed BITS and iPXE to be included by default

3. New version of binaries in Generated WinPE images

4. Support for iPXE WinPE images

WinPE Generator 1.2.0.2

1. Updated log file location for Service Logs under WinPE to be in the SMSTSLog folder

2. Fixed bug where folder failed to create under some scenarios, causing Service to exit

WinPE Generator 1.2.0.0

1. Added support for https environments

2. Added support Windows 10 WinPE

3. Added support for Windows 10

4. Added support for proxies

5. Added support for multiple network access accounts

6. Changed http engine from WinInet to WinHttp

WinPE Generator 1.1.0.0

1. Added BITS components to WinPE to support bandwidth aware and scheduled downloads from WinPE

2. Complete re-work of the code, improving speed and image dismount. Image creation now takes 2mins!

3. Support for Windows 7 SP1-> WinPE 3.1 image creation with BITS & BranchCache

4. Support for Windows Pro media with BITS & BranchCache integration (No need for Enterprise media)

5. Initial support for iPXE (Don't test this as it doesn’t work without the server Stifle:R component)

6. Sorted bugs where image index was hardcoded... doh!

7. WinPE StatGen.exe added to all WinPE image generated.

Download Enginge (BITSFist.exe)

1. BITSProTSDL.exe replaced by ->BITSFist.exe

2. WinPEDL.exe replaced by ->BITSFist.exe

3. Added reporting for WinPE downloads.

4. Same tool for both full OS (Any version) as well as WinPE, allowing for BITS downloads for ALL task sequences set to download on demand.

5. Sorted issues with BranchCache not starting on certain hardware.

The OSD Turbo feature is a way to speed up deployments (typically OSD) related content transfers. Normally these are done via BITS, which can run at a slower rate than what is optimal. It's a numbers game right, sometimes people just want to go faster. A detailed explanation on this is available here: https://2pintsoftware.com/the-updated-osd-toolkit-turbo-feature/

The TL;DR version is that we call the native BranchCache API's with bigger buffers to get better speed.

Going fast comes at a price

The CPU of both pulling and service source machines matter. The faster the CPU's, the faster the download is. But since the data has to be decrypted, it will peg your CPU of the machine downloading more than the machine serving the content.

Rules for going fast

1. Use maximum 5 files in your package source (The Turbo only transfers 5 files). But the Turbo still runs for the largest 5 files for any package.

2. Keep the size over 50MB per file, Turbo will not run for files smaller than 50MB.

3. Don't include small .txt files in the source, this will lead to the Turbo downloading the big files and then using BITS to transfer the small files after, which is not so fast.

Enable/Disable

Simple, set a variable named “2PintTurboLicense” to the license key that you got from us. The if you want to disable it, set the license key variable to a blank value (which removes the value).

Reporting status

The Turbo feature writes a log file and also updates the registry keys with information about duration etc. The following registry keys and values are written when the Turbo components runs, they can be used for reference to troubleshoot BranchCache issues.

All TS keys are created under the HKLM\Software\2pint Software\BITSTS\<DeploymentID>\<ContentID> registry path. Each folder is has the following key registry values and return codes. Where <FileId> is mentioned, this is the local file name for the file inside the content.

Value: TurboReturnCode_<filename>

The following known return codes are available:

Any other errors than above typically indicates an issue with the error code as an indidation of what went wrong.

Please note that these logs only show the beginning and ends of the logs, as they can be very large.

In WinPE, the typical log file to look in is the BITSACPSvc_<ContentId>.log file. This can be found in X:\Windows\temp\smstslog\

BITSACPStartup.log

Command-line arguments: BitsACP.exe X:\Windows\TEMP\SMSTSDownload.INI AP200003 C:\_SMSTaskSequence\Packages\AP200003

Checking to see if we are running in WinPE.

Initializing COM...

Created BITS COM Object.

Creating Download Job...

Writing BITS JobId Registry Key:{5ECDD140-041D-4138-A0AD-1D2569B094FB}

Successfully found a download Job from Registry...

We are running in WinPE or PreLogin Stage of OSD, will start Service.

Writing Registry Keys!

Writing PackageID Registry Key:AP200003

Writing ConfigFile Registry Key:X:\Windows\TEMP\SMSTSDownload.INI

Writing DownloadPath Registry Key:C:\_SMSTaskSequence\Packages\AP200003

Changing Log File Location to: X:\Windows\TEMP\smstslog\BITSACP_AP200003.log

BITSACP_<ContentId>.log

When in WinPE, this logs only tracks and shows the start of the BITSPE servce (BITSACP_ServiceMain.log and BITSACPService_<ContentId>.log progress, but when in full OS this log has the information for the actual download work.

The following is the start of a log in WinPE:

Releasing the Download job Pointer.

Checking is BITSPE Service is present on system.

OpenSCManager for:BITSPE

ERROR: OpenService failed:1060

Starting a new BITSPE Service instance.

Service installed successfully

Starting the Download Monitor Function.

Got _SMSTSNextInstructionPointer and _SMSTSInstructionTableSize from TS Env...

Registring UI

Successfully Registered UI

Calculating data size...

Progress UI Update returned errror code: 0

Initializing COM...

Getting BITS Job.

BITSACP_ServiceMain.log

This log typically only contains Service type information and can mostly be ignored:

ServiceMain: Entry

ServiceMain: Performing Service Start Operations

ServiceMain: Starting Worker Thread to complete

ServiceMain: Waiting for Worker Thread to complete

BITSACPSvc_<ContentId>.log

Getting the TS Environment port information

Setting the ports from TS Environment

Found advert ID, will use this for reporting: AP12008A

Cracking the URL...

Port: 443

Extra URL part:

Mode (HTTP=1, HTTPS=2): 2

URL is cracked, now putting back the pieces...

URL is HTTPS, setting the right authenticators and ports.

URL HTTPS port is set from TS Env: 443

Hostname:<server>.your.biz

Getting Download Job...

Successfully created Download Job...

Adding Description to the Download Job...

Connecting to server:

someserver.your.biz

443

Connecting with SSL: 1

Connecting with path: /NOCERT_SMS_DP_SMSPKG$/AP200003

Successfully set QueryInterface on Download Job...

Connecting to server...

Trying to connect...

Server replies with Status: 401

The server requires authentication. Sending searching credentials...