Troubleshooting (Velocity)
[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]
In case mistakes are made during the deployment of Microsoft project code named "Velocity," this topic lists things to check while troubleshooting in order to help resolve some of the more common issues.
Note
We highly recommend that you see the "Velocity" readme file and product blog for known issues and other information. You can find the code_name_velocity_readme.txt file, installation programs, and the URL of the product blog on the "Velocity" download page.
The most common issues are summarized in the following table and described in the following headings.
| Issue Type | For Additional Information |
|---|---|
Using PowerShell administration tool. |
|
Communications or firewall related. |
|
Cache host issues. |
|
High availability issues. |
|
Configuration storage location permissions. |
|
Known Issues. |
|
Cache Administration with PowerShell
On Microsoft Windows Vista and Microsoft Windows Server 2008 operating systems, you must right-click the "Velocity" PowerShell shortcut and select Run as administrator for the cache administration tool to work correctly.
Parameter values for the commands are case sensitive. For example, if you create a cache called NamedCache1, the command Get-CacheConfig -CacheName namedcache1 will not work. You must match the case, like this: Get-CacheConfig -CacheName NamedCache1.
When running the PowerShell cache administration tool on a cache host, you must have administrator permissions on all cache hosts in the cluster for the commands to function properly.
The PowerShell cache administration cmdlets require the AllSigned execution policy. The cache administration tool prompts to be configured to this policy the first time it is run. To set it manually, run the command Set-ExecutionPolicy -executionPolicy AllSigned.
Problems running PowerShell commands may also result from issues described in the following sections.
Firewall Exceptions and Port Configuration
It is important that all cache servers have firewall exceptions for the cache, cluster, and arbitration ports. The "Velocity" installation program can automatically configure these firewall exceptions; but, you may want to confirm these exceptions when troubleshooting communication issues.
We recommend that the firewall exceptions are based on the application name, DistributedCache.exe. Explicitly specifying exceptions based on the port numbers helps eliminate any question that issues may be caused by an incorrectly configured firewall exception. For example, an explicit port exception eliminates the chance that the wrong executable name was selected by mistake while configuring the application-based firewall exception manually.
The computer that is running the cache-enabled application does not need a firewall port exception configured. It contains the information that tells the client application which port to use in order to communicate with the cache host. If the application configuration file lists the wrong port number, the client will not be able to communicate with the host. By checking the port exceptions on the cache host and verifying the application and cluster configuration files, you can help exclude firewall configuration issues. For more information about the configuration files, see Configuration (Velocity).
The following table shows the default values for each port, and where the details are stored in each configuration file, as applicable.
Note
Each cache host refers the cluster configuration settings to determine the appropriate ports to use in order to communicate with the cluster. Use the PowerShell get-cacheconfig command to see which ports are being used by each cache host. For more information, see Cache Administration with PowerShell (Velocity).
| Port Name | Default Value | Application Configuration File Attribute | Cluster Configuration File Attribute |
|---|---|---|---|
cache port ( |
22233 |
|
|
cluster port |
22234 |
Not applicable |
|
arbitration port |
22235 (Cluster Port + 1) |
Not applicable |
Always the |
Cache Host Issues
When lead hosts perform the cluster management role, a majority of lead hosts must remain running in the cache cluster. If a majority of lead hosts stop running, the entire cluster will stop running. If a non-lead host fails, the cache cluster will continue to function. If high availability is not enabled, cached objects that were stored on that cache host will be lost.
If there is a question about which cache hosts have been designated as lead hosts, use the Get-CacheConfig command with the HostName parameter. It is designated as a lead host when the quorumHost property is true. For more information about PowerShell, see Cache Administration with PowerShell (Velocity).
It is important that all cache host services start and stop at the same time. For this reason, the Start-CacheCluster, Stop-CacheCluster, and Restart-CacheCluster commands are the only supported means of changing the cache host service state on the cache servers. Prior to shutting down individual cache servers for maintenance, you can also use the Stop-CacheHost command.
Note
The Stop-CacheHost command will not stop a cache host Windows service if it is performing the cluster management role and the stop will cause the entire cluster to shut down.
If you must use a simple client, we recommend that you configure two or more lead hosts in the application configuration settings. Because simple clients do not have routing tables, they must perform all communication with the cluster through one of the cache hosts configured in the application configuration settings. If only one cache host is listed and that cache host fails, your simple client will not be able to access the cache cluster. For more information about configuring cache hosts for a cache client, see Application Configuration Settings (Velocity).
High Availability Issues
For the high availability feature to help insulate your application from the failure of a cache host, at least three cache hosts must be members of the cache cluster. This is due to a strong consistency requirement stating that there must always be two copies of a cached object or region in a high availability-enabled cache. In order to maintain two copies of a cache or region, a high availability-enabled cache requires at least two cache hosts to function. For more information about the high availability feature, see High Availability (Velocity).
Cluster Configuration Storage Location Permissions
All cache hosts must be able to access the cluster configuration storage location. Each time a new cache host is added to the cluster, the installation program must grant the cache host permissions to the configuration storage location. The cache cluster must also be restarted to recognize new cache hosts for the first time. For more information about the necessary permissions that are required for your cache cluster, see How to: Prepare a Shared Network Folder for How to: Prepare a Shared Network Folder for Cluster Configuration Settings (Velocity) and How to: Prepare a SQL Server Database for Cluster Configuration Settings (Velocity).
Known Issues
Known issues not resolved before the release will be documented in the "Velocity" readme file. After the release, important issues will be documented in the product blog. You can find the code_named_velocity_readme.txt file, installation programs, and the URL of the product blog on the "Velocity" download page.
See Also
Concepts
Cluster Configuration Storage Options (Velocity)
Shared Folder-Based Cluster Configuration (Velocity)
SQL Server-Based Cluster Configuration (Velocity)
Configuration (Velocity)
Cache Administration with PowerShell (Velocity)
Other Resources
Installation and Deployment (Velocity)
Cache Concepts (Velocity)
Programming Guide (Velocity)