Automated Installation and Configuration (Windows Server AppFabric Caching)
This section explains the steps for automated installation and configuration of the Windows Server AppFabric caching features. In an unattended installation, the user does not see any user-interface, because all options are specified from the command-line. There is a specific sequence of commands required to either add a cache host to a cache cluster or remove a cache host from a cache cluster. This section describes the commands for both scenarios. Note that it is also possible to use the AppFabric Configuration Wizard to configure the caching features with a user interface. For more information on the AppFabric Configuration Wizard, see Configure Windows Server AppFabric.
This section divides the automated installation steps into five tasks:
Install Windows Server AppFabric caching features
Create a new cache cluster
Add a cache host
Remove a cache host
Remove a cache cluster
For PowerShell scripts that automate these steps, see these examples:
Tip
To learn the basics about launching and running Windows PowerShell commands, see Using Windows PowerShell to Manage Windows Server AppFabric Caching Features.
Tip
Although some of the following commands must run locally on the target cache host, Windows PowerShell supports running commands on remote machines. For more information, see Running Remote Commands
Install Windows Server AppFabric caching features
Before creating a new cache cluster or configuring AppFabric caching on a cache host, you must first install the Windows Server AppFabric caching features. For instructions about how to silently install AppFabric, see Automated Installation. The caching features include:
CachingService
CacheClient
CacheAdmin
For example, consider a scenario where the setup binary is named Setup.exe. Note that the actually binary name will vary depending on your chosen platform. The following example shows how to silently install the AppFabric caching features onto a server:
Setup.exe /install /i cachingservice,cacheclient,cacheadmin /l:c:\temp\setup.log
Note in this example, we are also directing the log file to the c:\temp\setup.log. You can examine this log file to investigate the results of the installation.
After AppFabric caching features are installed on a machine, you then need to configure them. The following sections describe the steps necessary for automating this process.
Create a new cache cluster
If you are creating a new cache cluster, you must first call the New-CacheCluster Windows PowerShell command. When you create a new cache cluster, you must decide where to store the cluster configuration settings. You can choose to use the System.Data.SqlClient provider, the XML provider, or a custom provider. For more information, see Configuration Model.
The following example creates a small cache cluster. It stores the configuration settings on a SQL Server machine named SQLServer1 with an existing database named CacheClusterConfigurationDB.
New-CacheCluster -Provider System.Data.SqlClient -ConnectionString "Data Source=SQLServer1;Initial Catalog=CacheClusterConfigurationDB;Integrated Security=True" -Size Small
Note
Note that if you use SQL Server database mirroring to increase availability of the cache cluster, you must specify the failover partner in the connection string. For more information, see SQL Server-Based Cluster Configuration.
The following example creates a large cache cluster. It stores the configuration settings in an XML file on a network share named \\Server1\CacheConfigShare.
New-CacheCluster -Provider XML -ConnectionString "\\Server1\CacheConfigShare" -Size Large
In both examples, the caller must have the adequate permissions on the configuration store location. For System.Data.SqlClient, the caller must be a db_owner on the target database or a member of the sysadmin role on the SQL Server instance. For XML, the caller must have owner permissions on the shared folder.
Add a cache host
To add a cache host to an existing cache cluster, you need to perform the following steps in order:
| Command/Step | Description |
|---|---|
Register-CacheHost |
Register the cache host with the cache cluster. |
Add-CacheHost |
Configure the cache host to be part of the cache cluster. |
Add-CacheAdmin |
Optionally configure Cache Administration on the current cache host. |
Configure the Firewall |
Allow the AppFabricCachingService service through the firewall. Also allow Remote Service Management. |
Start-CacheHost |
Start the new cache host. |
Register-CacheHost
You use the Register-CacheHost command to register a cache host with an existing cache cluster. This includes specifying port numbers and the Windows account for the Caching Service. The Provider and ConnectionString parameters specify the target cache cluster for the new cache host.
The following example adds the cache host machine, CacheServer1, to a cache cluster whose configuration store is located in an XML file at the file share \\Server1\CacheConfigShare. The built-in NT Authority\Network Service account is specified for the identity of the Caching Service.
Register-CacheHost -Provider XML -ConnectionString "\\Server1\CacheConfigShare" -Account "NT Authority\Network Service" -CachePort 22233 -ClusterPort 22234 -ArbitrationPort 22235 -ReplicationPort 22236 -HostName CacheServer1
Note that for the XML provider, the caller must have full control over the target network share. For the System.Data.SqlClient provider, the caller must have permissions to read, write, create SQL logins, and add permissions to the target database.
Unlike many other configuration commands, the Register-CacheHost command accepts a HostName parameter, so it can be run remotely.
Add-CacheHost
The Add-CacheHost command configures the cache host to become part of the existing cache cluster. The Provider and ConnectionString parameters specify the target cache cluster for the new cache host.
The following example demonstrates how to call Add-CacheHost.
Add-CacheHost -Provider XML -ConnectionString "\\Server1\CacheConfigShare" -Account "NT Authority\Network Service"
Note that this command must be run locally on the cache host that is being configured. You must also run this command from an elevated Windows PowerShell session with administrator privileges.
Warning
You must supply a value for the Account parameter for the Add-CacheHost command. If you do not specify an account, permissions will not be properly configured for the Caching Service. Note that in a domain environment with security enabled, the NT Autority\Network Service account must be used.
Add-CacheAdmin
You can optionally use the Add-CacheAdmin command to configure the Cache Administration feature on a cache host. This gives you the ability to administer the cache cluster from this machine by using Windows PowerShell commands. The Cache Administration feature must be installed on the machine.
The following example demonstrates how to call Add-CacheAdmin.
Add-CacheAdmin -Provider XML -ConnectionString "\\Server1\CacheConfigShare"
Note that this command must be run locally on the cache host that is being configured. You must also run this from an elevated Windows PowerShell session with administrator privileges.
Configure the Firewall
In order to successfully use the AppFabric caching features, you must configure the for the DistributedCacheService.exe service. By default this service installs to the C:\Windows\System32\AppFabric directory.
If you are using the Windows firewall, you can enable a firewall policy group that automatically gets installed with AppFabric. The following Windows Powershell commands enable the firewall policy group named "Windows Server AppFabric: AppFabric Caching Service". You should also enable the "Remote Service Management" firewall rules to enable the AppFabric Caching Service to be controlled remotely.
netsh advfirewall firewall set rule group="Windows Server AppFabric: AppFabric Caching Service" new enable=Yes
netsh advfirewall firewall set rule name="Remote Service Management (RPC)" profile=domain new enable=Yes
netsh advfirewall firewall set rule name="Remote Service Management (RPC-EPMAP)" profile=domain new enable=Yes
netsh advfirewall firewall set rule name="Remote Service Management (NP-In)" profile=domain new enable=Yes
Start-CacheHost
If you want to enable the new cache host to participate in the cache cluster, you must start the cache host. If the cache cluster is down, you must start the entire cache cluster. The cache cluster is down if all of the hosts are down. This can be assessed by calling Get-CacheHost with no parameters.
Get-CacheHost
If all the hosts show a service status of DOWN, then start the cache cluster with the Start-CacheCluster command.
Start-CacheCluster
However, if at least one host has a service status of UP, then the cache cluster is running. In this case, use the Start-CacheHost command.
Start-CacheHost -Hostname CacheServer2 -CachePort 22233
Note that after a cache host machine reboots, the Caching Service does not start automatically; you should use either Start-CacheHost or Start-CacheCluster depending on the state of the cache cluster.
You must also run this command from an elevated Windows PowerShell session with administrator privileges.
Warning
Always use the Windows PowerShell commands to start and stop the Caching Service. Never start or stop the AppFabricCachingService service directly from the Services program in Administrative Tools.
Remove a cache host
To remove a cache host from a cache cluster, you need to perform the following steps in order.
| Command/Step | Description |
|---|---|
Stop-CacheHost |
Stop the cache host if it is running. |
Unregister-CacheHost |
Unregister the cache host with the cache cluster. |
Remove-CacheHost |
Remove the cache host configuration from the machine. |
Remove-CacheAdmin |
Optionally remove the configuration of the Cache Administration feature. |
Configure the Firewall |
Remove any firewall exceptions for the Caching Service. |
Stop-CacheHost
If you want to remove a cache host from an existing cluster, you must first stop the cache host. You can determine whether the cache host is running by calling the Get-CacheHost command. The following example demonstrates how to view the cache host information for the local cache host.
Get-CacheHost -HostName localhost -CachePort 22233
Although the previous command gives you information about a specific cache host, you should always consider the status of the entire cache cluster before stopping any one cache host. This can be done by calling Get-CacheHost with no parameters.
Get-CacheHost
The following shows example output from this command for a two-server cache cluster.
HostName : CachePort Service Name Service Status Version Info
-------------------- ------------ -------------- ------------
CacheServer1:22233 AppFabricCachingService UP 1 [1,1][1,1]
CacheServer2:22233 AppFabricCachingService UP 1 [1,1][1,1]
In this example, both CacheServer1 and CacheServer2 are running. You can attempt to stop one of these cache hosts and leave the cache cluster operational through the other cache host. The following example shows how to stop CacheServer2 with the Stop-CacheHost command.
Stop-CacheHost -HostName CacheServer2 -CachePort 22233
Note that any data cached on the stopped cache host is lost. Also, attempting to stop the cache host will fail if it would result in the loss of quorum for either lead hosts or secondaries. For more information on lead hosts, see Lead Hosts and Cluster Management. For more information on secondaries, see High Availability. In these cases, you must stop the entire cluster with the Stop-CacheCluster command.
If stopping the cache host were to stop the cache cluster, then use the Stop-CacheCluster command instead. For example, consider the following sample output from the Get-CacheHost command.
HostName : CachePort Service Name Service Status Version Info
-------------------- ------------ -------------- ------------
CacheServer1:22233 AppFabricCachingService DOWN 1 [1,1][1,1]
CacheServer2:22233 AppFabricCachingService UP 1 [1,1][1,1]
In this example, CacheServer1 is stopped, and CacheServer2 is running. Stopping CacheServer2 would bring down the cluster. Instead of using the Stop-CacheHost command to stop CacheServer2, use the Stop-CacheCluster command instead.
Stop-CacheCluster
You must run this command from an elevated Windows PowerShell session with administrator privileges.
Unregister-CacheHost
The Unregister-CacheHost command removes the cache host from the cache cluster.
If this command is run before Remove-CacheHost, then you are not required to specify values for the Provider or ConnectionString parameters. If the command is run locally, you also not required to specify a value for the HostName parameter.
Unregister-CacheHost -RemoveServicePermissions
The following example unregisters a cache host by specifying the provider, connection string, and hostname. It removes a cache host named CacheServer2 from a cache cluster. This cache cluster uses the System.Data.SqlClient provider, so the connection string is a SQL Server connection string to a database server named SQLServer1 and a configuration database named CacheClusterConfigurationDB.
Unregister-CacheHost -Provider System.Data.SqlClient -ConnectionString "Data Source=SQLServer1;Initial Catalog=CacheClusterConfigurationDB;Integrated Security=True" + -HostName CacheServer2 -RemoveServicePermissions
Note that for the XML provider, the caller must have full control over the target network share. For the System.Data.SqlClient provider, the caller must have permissions to read, write, remove SQL logins, and remove permissions on the target database.
Unlike many other configuration commands, the Unregister-CacheHost command accepts a HostName parameter, so it can be run remotely.
Remove-CacheHost
The Remove-CacheHost command removes the cache host configuration from the server.
Remove-CacheHost
Note that this command must be run locally on the cache host that is being configured. You must also run this command from an elevated Windows PowerShell session with administrative credentials.
Remove-CacheAdmin
If the Cache Administration feature is configured on the cache host, you can remove it with the Remove-CacheAdmin command.
Remove-CacheAdmin
Note that this command must be run locally on the cache host that is being configured. You must also run this command from an elevated Windows PowerShell session with administrative credentials.
Configure the Firewall
You should remove or disable any exceptions in the firewall for the Caching Service, DistributedCacheService.exe. If you are using the Windows firewall, you should have previously enabled the installed firewall group "Windows Server AppFabric: AppFabric Caching Service". If so, you can disable this policy group by using the following PowerShell commands. If you also enabled the "Remote Service Management" rules, you can also disable those rules. However, other services or applications may have enabled the "Remote Service Management" rules. In this scenario, you would not disable the "Remote Service Management" rules.
netsh advfirewall firewall set rule group="Windows Server AppFabric: AppFabric Caching Service" new enable=No
netsh advfirewall firewall set rule name="Remote Service Management (RPC)" profile=domain new enable=No
netsh advfirewall firewall set rule name="Remote Service Management (RPC-EPMAP)" profile=domain new enable=No
netsh advfirewall firewall set rule name="Remote Service Management (NP-In)" profile=domain new enable=No
Remove a cache cluster
If you have removed the final cache host from the cluster, you can also choose to remove the cache cluster configuration store. To do this, use the Remove-CacheCluster command. If the cache cluster uses the XML provider, this command deletes the XML file that contains the configuration settings. If the cache cluster uses the System.Data.SqlClient provider, this command deletes the tables in the specified database. Note that the file share and the database are not removed.
Remove_CacheCluster -Provider System.Data.SqlClient -ConnectionString "Data Source=SQLServer1;Initial Catalog=CacheClusterConfigurationDB;Integrated Security=True"
See Also
Concepts
Deploying and Configuring Windows Server AppFabric Caching Features