XML-Based Cluster Configuration (Velocity)

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

By selecting the XML-based cluster configuration storage option in Microsoft project code named "Velocity," you have the flexibility to make configuration changes by using an XML file that is named the ClusterConfig.xml. This XML file is created automatically in the cluster configuration storage location during installation. "Velocity" uses this configuration file as the primary point of reference for defining the cache cluster, cache hosts, and named caches.

Note

You can change cluster configuration settings (XML attributes) in the ClusterConfig.xml file, but adding or removing named caches and cache hosts by inserting or removing XML elements is not supported. To add or remove named caches or cache hosts, use the PowerShell cache administration tool and the "Velocity" installer. For more information about the PowerShell cache administration commands, see Cache Administration with PowerShell (Velocity).

Storage Location Requirements

Before installing "Velocity" on the first cache server, you must create and configure a shared folder to act as the cluster configuration storage location. The installation program needs this shared folder to create or modify the cluster configuration files and folder structure. For this reason, all cache servers in the cluster must be able to access the cluster configuration shared folder.

The cluster configuration storage location can be a single point of failure for your distributed cache system. For this reason, we recommend that you use Microsoft Windows Server 2008 Failover Clustering to host a "clustered" folder resource for the cache cluster configuration storage location. Doing this optimizes the availability of your cluster's configuration data.

Note

Microsoft Windows XP, Microsoft Windows Server 2003, and the 32-bit version of Microsoft Windows Vista do not allow more than 10 concurrent connections to a shared network folder. We do not recommend that you use these operating systems to store the cache configuration settings for large clusters.

Permissions

The cluster configuration shared folder must have its share and security settings configured so that each cache server has read and write permission to the folder contents.

Note

For community technology preview 2 (CTP2), the Everyone identity needs owner permissions to the cluster configuration shared folder.

To simplify long-term administration of the cluster configuration folder, do not run the "Velocity" service under the credentials of a domain user account. By using the default installation settings, you can use the domain computer accounts of the cache servers instead and you can avoid password maintenance.

If you create a Windows security group to manage access to the cache configuration shared folder, you set up permissions on that folder only once. For example, if the Windows security group is named ClusterACacheServers, it indicates that the cache servers have permission to become part of the cache cluster named ClusterA.

After you create the ClusterACacheServers security group, grant the domain computer accounts of the applicable cache servers membership to this group (for example "domain\computername$"). Then grant ClusterACacheServers read and write permissions in the sharing and security settings of the cluster configuration shared folder. When this is set up, for each new server that you add to the cache cluster, add only the domain computer account of the new server to the security group.

File Structure

When you install "Velocity" for the first time with the XML-based configuration option, the installation program creates two files in the folder specified for the configuration storage location:

ClusterConfig.xml: The editable XML version of the configuration settings. When the cluster starts, these settings are used to instantiate the cluster.
ConfigStore.sdf: This SQL Server Compact data file is used by the cluster to store operational information.

Process Summary

To use the XML-based cluster configuration storage option, follow these steps:

Create the cluster configuration shared folder. Create a folder and configure the folder's sharing and security properties to allow each cache server to have read and write permissions across the network. Optionally, use Failover Clustering to host this folder and a Windows security group to manage access to the folder.
Install "Velocity" on a cache server. Select the XML-based configuration type during installation.
Start the cluster by running the PowerShell administration tool from the first cache server in the cluster. From PowerShell, use the start-cluster command. For more information about the PowerShell cache administration commands, see Cache Administration with PowerShell (Velocity).

Cache Cluster Settings

Regardless of which storage format you choose, "Velocity" uses the cluster configuration storage location to keep track of the same settings:

Cluster settings define the name and size of the cluster.
Cache settings define the name, type, and consistency value for the cache. The eviction and expiration policies are defined here also.
Host settings define the host name, size, ID, and whether the cache host has been designated as a lead host. The cache host service name and port information are also defined here.
Advanced Settings define the location of the ConfigStore.sdf file from the perspective of individual cache hosts.

Configuration Elements

The following XML elements are used to configure the cache cluster in the ClusterConfig.xml configuration file.

<configSections>: Required for "Velocity" to use the application configuration file, and must be the first element in the configuration file.
<dcache>: The primary element used to configure the cache cluster, and the parent to the elements that describe the caches (caches), the hosts (hosts), and the advanced properties for the hosts (advancedProperties). The cluster attribute states the name of the cluster, and the size attribute indicates to the cluster how many lead hosts are needed.
<caches>: The parent to the cache elements that specify the caches and a child of the dcache element.
<cache>: Each cache element describes one of the caches in the cluster, and all cache elements are children of the caches element. The attributes of this element describe the cache name, type, and consistency. When high availability is enabled, the replicas and minWriteQuorum attributes are larger than one. Within each cache element, a policy element is used to specify the policies applicable for each corresponding cache.
<policy>: A child of the cache element, the policy element describes the eviction and expiration policies applicable to a cache by using the eviction and expiration child elements.
<eviction>: A child of the policy element that uses the type attribute to describe the type of eviction for the cache.
<expiration>: A child of the policy element that describes the default expiration settings for objects stored in the cache. By default, the defaultTTL setting describes how long objects remain in the cache. The isExpirable attribute enables expiration to occur on items in the cache.
<hosts>: A parent to the host elements that specify the cache hosts and a child of the dcache element.
<host>: Defines the configuration for one cache host by specifying the host name, port numbers, service name, configured memory size, and whether the host has been designated to be a lead host. The host is a child of the hosts element.
<advancedProperties>: Defines the location of the ConfigStore.sdf file from the perspective of each cache host.

For more information about the settings that are used to configure the cluster, see Cluster Configuration Settings (Velocity).

Example

The following code is an example of what a cluster configuration file looks like when you use it to specify the cache cluster settings. This example specifies a single cache host, CacheServer1, the default cache that was created during installation, and a named cache, NamedCache1, that has the high availability feature enabled.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="dcache"
             type="System.Data.Caching.DCacheSection, 
                 CacheBaseLibrary, Version=1.0.0.0, 
                 Culture=neutral, 
                 PublicKeyToken=63118e5b4b42c36a" />
  </configSections>

  <dcache cluster="ClusterName1" size="Small">

    <caches>
      <!-- Specifies the default cache -->
      <!-- (High Availablity disabled)-->
      <cache type="partitioned"
             consistency="strong"
             name="default"
             replicas="1"
             minWriteQuorum="1">
        <policy>
          <eviction type="lru" />
          <expiration
            defaultTTL="10"
            isExpirable="true" />
        </policy>
      </cache>
      <!-- Specifies the default cache -->
      <!-- (High Availablity enabled)-->
      <cache type="partitioned"
             consistency="strong"
             name="NamedCache1"
             replicas="2"
             minWriteQuorum="2">
        <policy>
          <eviction type="lru" />
          <expiration
            defaultTTL="10"
            isExpirable="true" />
        </policy>
      </cache>
    </caches>

    <hosts>
      <host
        clusterPort="22234"
        hostId="182887601"
        size="32"
        quorumHost="true"
        name="CACHESERVER1"
        cacheHostName="DistributedCacheService"
        cachePort="22233" />
    </hosts>

    <advancedProperties>
      <partitionStoreConnectionSettings
        providerName="System.Data.SqlServerCe.3.5"
        connectionString="\\clusterConfigPath\ConfigStore.sdf"/>
    </advancedProperties>
  </dcache>
</configuration>

XML-Based Cluster Configuration (Velocity)

Storage Location Requirements

Permissions

File Structure

Process Summary

Cache Cluster Settings

Configuration Elements

Example

See Also

Concepts

Other Resources

Additional resources