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