Netsh Commands for BranchCache in Windows Server 2008 R2

Applies To: Windows Server 2008 R2

This section contains the following commands.

  • exportkey

  • flush

  • importkey

  • reset

  • set cachesize

  • set key

  • set localcache

  • set publicationcache

  • set publicationcachesize

  • set service

  • show hostedcache

  • show localcache

  • show publicationcache

  • show status

  • smb

  • set latency

  • show latency

For information on how to interpret netsh command syntax, see Formatting Legend.

Important

Several netsh commands for BranchCache do not function properly when the Language for non-unicode programs setting is changed to a non-default value for Windows Server versions in the following languages: Chinese – simplified; Chinese – traditional; Greek; Japanese; Korean; and Russian. The following netsh branchcache commands are affected by this issue: netsh branchcache show status detail=ALL; netsh branchcache set service; netsh branchcache reset.

BranchCache commands

The following entries provide details for each command.

exportkey

Exports the key that the BranchCache service uses to publish content and generate content hashes. The key can then be imported on another computer by using the importkey command.

Syntax

exportkey [ outputfile= ] FilePath [ passphrase= ] PassPhrase

Parameters

  • outputfile
    Required. Specifies the file name and folder location to which the key is exported.
  • passphrase
    Required. Specifies the password that is required to import the key on another computer.

Examples

In the first example, the key is exported to a file named "secret.key" that is stored in the system temporary directory (%TMP%). The password used to import the file on another computer is "Key file password." In the second example, the file name and password are the same as in the first example, however the file is stored in the folder location C:\KeyDirectory.

exportkey %TMP%\secret.key "Key file password"

exportkey outputfile=C:\KeyDirectory\secret.key "Key file password"

flush

Deletes the contents of the local BranchCache cache.

Syntax

flush

importkey

Imports a new key from a file that was created by using the exportkey command. When you run the importkey command and the BranchCache service is already started, the service is stopped and then restarted. The BranchCache service uses this key to publish content and to generate content hashes.

Syntax

importkey [ outputfile= ] FilePath [ passphrase= ] PassPhrase

Parameters

  • outputfile
    Required. Specifies the file name and folder location from which the key is imported.
  • passphrase
    Required. Specifies the password that is required to import the key from file.

Examples

In the first example, the key is imported from a file named "secret.key" that is stored in the system temporary directory (%TMP%). The password used to import the file is "Key file password." In the second example, the file name and password are the same as in the first example, however the file is stored in the folder location C:\KeyDirectory.

exportkey %TMP%\secret.key "Key file password"

exportkey outputfile=C:\KeyDirectory\secret.key "Key file password"

reset

Resets the BranchCache service and flushes the local BranchCache cache, deleting all content in the cache. When this command is run, all configuration parameters are returned to default values.

Syntax

reset

set cachesize

Specifies the size of the local cache as either a percentage of the size of the hard disk where the cache is located or as an exact number of bytes.

Syntax

set cachesize [ size= ]{ DEFAULT | Number } [[percent= ]{ TRUE | FALSE } ]

Parameters

  • size
    Required. Specifies the desired size of the cache as a number, which is either a percentage of hard disk size or an exact number of bytes. If DEFAULT is specified, the BranchCache cache is restored to the default size, which is five per cent of the size of the disk where the cache is located.
  • percent
    Optional. Specifies whether the size parameter is treated as a percentage of the size of the hard disk or as an exact number of bytes. TRUE specifies that the value of the size parameter is a percentage of the hard disk size. FALSE, which is the default, specifies that the value of the size parameter is an exact number of bytes. If the size parameter value is DEFAULT, then the percent parameter value is ignored.

Examples

In the first example below, the cache size is set to the default, which is five percent of the hard disk size. In the second example below, the cache size is set to 20,971,520 bytes. In the third example below, the cache size is set to twenty percent of the hard disk size.

set cachesize DEFAULT

set cachesize 20971520

set cachesize size=20 percent=TRUE

set key

Generates a new key that the BranchCache service uses to publish content and generate content hashes. If the BranchCache service is already started when this command is run, the service is stopped and restarted.

Syntax

set key [ [passphrase= ] "Pass Phrase" ]

Parameters

  • passphrase
    Optional. Specifies a string that BranchCache uses to generate the encryption key. If you specify a passphrase, you can use the same passphrase to duplicate the same encryption key on another computer running BranchCache. Two keys that are generated using the same passphrase are always identical. If a passphrase is not specified, a random key is generated by BranchCache.

Examples

In the first example below, a random key is generated by BranchCache. In the second example below, a key is generated using the passphrase "I want my content to be secure."

set key

set key passphrase="I want my content to be secure"

set localcache

Specifies the location of the local cache for the BranchCache service on a client computer. This cache is also called a republication cache, and it contains both hashes that describe content and the actual content that the client can provide to other clients in the same branch office. If the BranchCache service is already started when this command is run, the service is stopped and then restarted. If before running the command there is content stored in the cache at a location other than the new location you specify when you run the set localcache command, then BranchCache moves the content to the new folder location.

Syntax

set localcache [ directory= ] { DEFAULT | FilePath }

Parameters

  • directory
    Required. Specifies a path name that is the folder location where you want to store the BranchCache cache on the local computer. If DEFAULT is specified, the BranchCache cache is stored in the default location at %WINDIR%\ServiceProfiles\NetworkService\AppData\Local\PeerDistRepub.

Examples

In the first example, the BranchCache cache is stored in the default location at %WINDIR%\ServiceProfiles\NetworkService\AppData\Local\PeerDistRepub. In the second example, the BranchCache cache is stored at the location C:\BranchCache\Localcache.

set localcache DEFAULT

set localcache directory=C:\BranchCache\Localcache

set publicationcache

Sets the location of the local publication cache for the BranchCache service on a content server. The publication cache contains the hashes that describe the content that is available for download by client computers in branch offices. If the BranchCache service is already started when this command is run, the service is stopped and then restarted.

Syntax

set publicationcache [ directory= ] { DEFAULT | FilePath }

Parameters

  • directory
    Required. Specifies a path name that is the folder location where you want to store the BranchCache publication cache on the local computer. If DEFAULT is specified, the BranchCache publication cache is stored in the default location at %WINDIR%\ServiceProfiles\NetworkService\AppData\Local\PeerDistPub.

Examples

In the first example below, the publication cache is stored in the default location at %WINDIR%\ServiceProfiles\NetworkService\AppData\Local\PeerDistPub. In the second example below, the publication cache is stored at the folder location C:\BranchCache\PublicationCache.

set publicationcache DEFAULT

set publicationcache directory=C:\BranchCache\PublicationCache

set publicationcachesize

Sets the size of the publication cache on the local computer.

Syntax

set publicationcachesize [ size= ] { DEFAULT | Number } [ [ percent= ] { TRUE | FALSE } ]

Parameters

  • size
    Required. Specifies the desired size of the cache as a number, which is either a percentage of hard disk size or an exact number of bytes. If DEFAULT is specified, the publication cache is restored to the default size, which is 1% of the size of the disk where the cache is located.
  • percent
    Optional. Specifies whether the size parameter is treated as a percentage of the size of the hard disk or as an exact number of bytes. TRUE specifies that the value of the size parameter is a percentage of the hard disk size. FALSE, which is the default, specifies that the value of the size parameter is an exact number of bytes. If the size parameter value is DEFAULT, the percent parameter value is ignored.

Examples

In the first example below, the publication cache size is set to the default, which is 1% of the hard disk size. In the second example below, the cache size is set to 20,971,520 bytes. In the third example below, the cache size is set to 20% of the hard disk size.

set publicationcachesize DEFAULT

set publicationcachesize 20971520

set publicationcachesize size=20 percent=TRUE

set service

Configures the BranchCache service. When you run this command, BranchCache also configures the firewall on the local computer for the selected mode of operation.

Syntax

set service [mode= ] { DISABLED | LOCAL | DISTRIBUTED | HOSTEDSERVER | HOSTEDCLIENT } [ [location= ] HostName ] [ [clientauthentication= ] { DOMAIN | NONE } ] [ [serveonbattery= ] { TRUE | FALSE } ]

Parameters

  • mode
    Required. Configures the BranchCache service to operate in one of the following modes. DISABLED disables the BranchCache service. LOCAL uses caching on the local computer only. DISTRIBUTED enables distributed cache mode, allowing authorized client computers in branch offices to download and republish content. HOSTEDSERVER configures the local computer as a hosted cache server. HOSTEDCLIENT configures the local computer as a hosted cache client.
  • location
    Required if the mode parameter's value is HOSTEDCLIENT. Specifies the location of the hosted cache server if the mode parameter's value is HOSTEDCLIENT. Use of a fully qualified domain name as the value for the location parameter is recommended. If the mode parameter's value is not HOSTEDCLIENT, BranchCache does not process this parameter.
  • clientauthentication
    Optional. Specifies whether a hosted cache server authenticates client computers. If unspecified, the default value is DOMAIN. If DOMAIN is specified, the server authenticates client computers before allowing them to download content. For authentication to succeed, client computers and the hosted server must be members of the same domain. If client computers are not members of the same domain as the hosted server, the server rejects the content request. If NONE is specified, client computers are not authenticated. If the mode parameter's value is not HOSTEDSERVER, BranchCache does not process this parameter.
  • serveonbattery
    Optional. Specifies whether the local computer can respond to client computer queries for cached data when the computer is running on battery power. If unspecified, the default value is FALSE. If TRUE is specified, the portable client can respond to queries for cached content. If FALSE is specified, the portable client cannot respond to queries for cached content. If the mode parameter's value is not DISTRIBUTED, BranchCache does not process this parameter.

Examples

In the first example, the BranchCache service is disabled. In the second example, the local client computer in a branch office is configured to operate in distributed mode, allowing it to obtain and republish content. In the third example, the local computer is configured as a hosted cache client with a hosted cache server location of SERVER123.example.com. In the final example, the local computer is configured as a hosted cache server and is configured to authenticate client computers that request content and that are members of the same domain.

set service DISABLED

set service mode=DISTRIBUTED

set service mode=HOSTEDCLIENT location=SERVER123.example.com

set service mode=HOSTEDSERVER clientauthentication=DOMAIN

show hostedcache

Displays the folder location of the hosted cache on the local computer.

Syntax

show hostedcache

show localcache

Displays the status of the local cache.

Syntax

show localcache

show publicationcache

Displays the status of the publication cache.

Syntax

show publicationcache

show status

Displays the status of the BranchCache service.

Syntax

show status [detail= ] { BASIC | ALL }

Parameters

  • detail
    Optional. Specifies whether to display basic information or all available information. If BASIC is specified, only basic information is displayed. This setting is the default. If ALL is specified, all available information is displayed.

smb

Changes to the smb subcontext of the branchcache context.

Syntax

smb

SMB Subcontext Commands

The following commands are run at the smb subcontext of the branchcache context.

set latency

Specifies the minimum allowed network link latency, in milliseconds, between the branch office and the content source office.

Syntax

set latency [latency= ] Number

  • latency
    Required. Specifies the minimum network link latency between the branch office and the content source office before Server Message Block (SMB) uses BranchCache caching. The value for Number is expressed in milliseconds.

show latency

Displays the configured minimum link latency value in milliseconds.

Syntax

show latency