Cache Config (config.ncconf)

The cache configuration file contains information regarding all the registered caches/clusters. Modules that need to read the configurations first try to find config.ncconf in the application folder, i.e., alongside the Web.config. If config.ncconf is not found in the application folder, it then reads the configuration from the installation folder.

Note

This file is installed with NCache and is located at %NCHOME%\config in Windows and /opt/ncache/config in Linux.

Cache Config Syntax

The cache configuration file is explained below.

<!--
The configuration file (config.ncconf) contains the details of all the registered caches. All cache configurations are enclosed in the <configuration></configuration> tag. Whereas each cache detail is enclosed in <cache-config></cache-config>.
-->

<cache-config cache-name="demoCache" alias="" store-type="Distributed-Cache" config-id="6a49d9ce-9aa7-4312-ada6-4fec37a6e729" config-version="0">
  <cache-settings inproc="False" last-modified="" auto-start="False" data-format="Serialized" serialization="Binary">
    ...
  </cache-settings>
</cache-config>

Understanding the Cache Config Tags

The following section explains the tags mentioned as part of the file syntax.

<cache-config>

This tag defines essential cache settings.

<cache-config cache-name="demoCache" alias="" store-type="Distributed-Cache" config-id="6a49d9ce-9aa7-4312-ada6-4fec37a6e729" config-version="0">

  • cache-name: Specifies the cache name here. This is the same name as you specify while initializing the cache.

  • store-type: Specifies the purpose for which this cache will be used. Can have one of the following possible values:

    • Distributed-Cache
    • Distributed-Cache-Persistence
    • Pub/Sub-Messaging
    • Distributed-Lucene

  • config-id: Auto-generates unique Id for the modified configuration.

  • config-version: Used to determine whether the configuration is modified or not.

<cache-settings>

This tag configures cache operation and execution.

<cache-settings inproc="False" last-modified="" auto-start="False" data-format="Serialized" serialization="Binary">

  • inproc: Determines whether the cache will run as InProc (in your application process) or OutProc (in the NCache Service process). If set to False, the cache will run as OutProc and if set to True, then the cache will run as InProc. The default value is False.

  • last-modified: Contains information related to the last modification in the cache configuration.

  • auto-start: Enables the auto start of cache on cache startup. The default value is False.

  • data-format: The format with which data is stored in cache, can be Serialized or Object. The default value is Serialized.

  • serialization: Determines the serialization format for the cache. It can be either JSON or Binary. The default value is Binary.

<logging>

NCache maintains a log file to write traces for information and debugging purposes. The user can enable or disable the various traces using these tags. By default, only the “Error” trace is enabled, rest of the traces are disabled. Error trace does not affect the cache performance but for other traces. We recommend not enabling them in a production environment as they affect the performance of NCache.

<logging enable-logs="True" trace-errors="True" trace-notices="False" trace-warnings="False" trace-debug="False" log-path=""/>

  • enable-logs: Allows you to maintain a log file by specifying a Boolean value. By default, it is False as logging can create an overhead and degrade application performance.

  • trace-errors: Logs error traces, essential for identifying and troubleshooting critical issues. By default, it is True.

  • trace-notices: Logs notice traces for general informational messages. By default, it is False.

  • trace-warnings: Logs warning traces, useful for detecting and addressing potential issues. By default, it is False.

  • trace-debug: Logs detailed debug traces, helpful for diagnosing problems and analyzing system behavior during development or testing. By default, it is False.

  • log-path: By default, log files for each cache are created at %NCHOME%\config in Windows and /opt/ncache/config in Linux. However, you can specify a custom path if you want to save the logs elsewhere.

<performance-counters>

When configured, NCache will update the published PerfMon counters.

<performance-counters enable-counters="True" snmp-port="0"/>
  • enable-counters: When set to True, NCache will update the published PerfMon counters. If set to False, NCache will not update any of the published PerfMon counters. By default, it is True.

<data-load-balancing>

This tag allows you to automatically trigger data load balancing on nodes in a partitioned cluster.

<data-load-balancing enabled="False" auto-balancing-threshold="60%" auto-balancing-interval="30sec"/>

  • enabled: Specifies whether to enable data load balancing. By default, its value is False.

  • auto-balancing-threshold: Specifies the percentage data size above the average data size per node that triggers automatic load balancing when exceeded. By default, it is 60%.

  • auto-balancing-interval: Specifies the interval after which auto-balancing takes place. By default, it is 30 seconds.

<compression>

This tag specifies whether the items greater than the specified threshold should be compressed/decompressed on the client side.

<compression enable-compression="False" threshold="100kb"/>

  • enable-compression: To enable compression, set this attribute to True, otherwise, by default it is False.

  • threshold: Items greater than the value specified in the threshold attribute will only be compressed/decompressed on the client side if compression is enabled. As per above mentioned compression tag example, only items greater than 100kb in size will be compressed/decompressed on the client side.

<pipelining>

This tag enables batching several instructions over a TCP connection, reducing network cost and enhancing performance by sending bulk commands at specified intervals.

<pipelining enabled="False" batch-interval="250usec"/>

  • enabled: When set to True, pipelining allows clients to send multiple requests in a batch using a single TCP connection for better performance. By default it is False.

  • batch-interval: Specifies the interval for sending batched operations over the network. By default, it is 250 µs, the minimum value is 50µs and the maximum value is 5000µs.

<client-death-detection>

This tag allows the server to monitor if a client is disconnected from all cache servers in a clustered cache.

<client-death-detection enable="False" grace-interval="60sec"/>

  • enabled: Specifies whether client death detection is enabled or not. The default value is False.

  • grace-interval: It is the interval the server waits before determining that a disconnected client is dead and freeing up its resources. The default value is 60 seconds and can be extended up to 180 seconds.

<client-activity-notification>

This tag enables client connection\disconnection event notifications in a clustered cache environment. In order to avoid unnecessary disconnect notifications during brief network issues, a retention-period is also configured.

<client-activity-notification enabled="False" retention-period="5sec"/>

  • enabled: Enable this option to allow clients to receive notifications if another client connects or disconnects. By default it is False.

  • retention-period: The time interval after which a disconnected client is considered as disconnected. By default, it's valuse is 5 seconds.

<cache-notifications>

The cache-notifications tag specifies the registered event with the cache. All the flags in this tag are marked False by default.

<cache-notifications item-remove="False" item-add="False" item-update="False" expiration-time="15sec"/>

  • Item-add: This attribute can be set to True or False. If set to True, it will notify users when an item is added to the cache. Similarly if set to False, no notification will be fired if the item is added to the cache.

  • Item-remove: This attribute can be set to True or False. If set to True, it will notify users when an item is removed from the cache. Similarly if set to False, no notification will be fired if the item is removed from the cache.

  • Item-update: This attribute can be set to True or False. If set to True, it will notify users when an item is updated in the cache. Similarly if set to False, no notification will be fired if the item is updated in the cache.

  • expiration-time: This attribute specifies the expiration time for the cache notifications, it is the interval after which the item for expiration will be checked. By default, its value is 15 seconds.

<cleanup>

This tag preodically removes items from cache.

<cleanup interval="15sec"/>
  • interval: Specifies the interval after which the expiration check will be performed. By default, it is 15 seconds.

<storage>

This tag specifies the storage-related details for cache.

<storage type="heap" cache-size="1024mb"/>

  • type: This attribute can only be set to "heap" as currently NCache only supports heap-based storage.

  • cache-size: This attribute specifies the upper limit of cache size in MB. The default value is 1024 MB.

<eviction-policy>

This tag specifies whether to perform the eviction or not.

<eviction-policy enabled-eviction="True" default-priority="normal" policy="lru" eviction-ratio="5%"/>

  • enabled-eviction: If eviction is set to True then the cache will remove the existing item to accommodate new ones. Exiting items will be removed based on the eviction strategy. By default it is False.

  • default-priority: Specifies the default priority that is associated with an item if no priority is specified for that item. This attribute can be set to the following:

    • High
    • Above-normal
    • Normal
    • Below-normal
    • Low

This is only applicable in case of priority based eviction

  • policy: This attribute specifies the eviction policy to be used. Eviction policy can be one of the following:

    • LRU (Least recently used)
    • LFU (Least frequently used)
    • Priority based

  • eviction-ratio: Specifies how much percentage of data should be evicted when eviction is performed.

<expiration-policy>

This tag specifies the basis under which the cache entries will expire and be removed from the cache.

<expiration-policy enabled="False">
  <absolute-expiration longer-enabled="False" longer-value="0" default-enabled="False" default-value="0"/>
  <sliding-expiration longer-enabled="False" longer-value="0" default-enabled="False" default-value="0"/>
</expiration-policy>
  • enabled: Enables the expiration policy. By default, it is False.

<absolute-expiration>

This tag will specify the exact time the cache entries will expire and be removed.

  <absolute-expiration longer-enabled="False" longer-value="0" default-enabled="False" default-value="0"/>

  • longer-enabled: Specifies whether longer expiration is enabled. If True, the value should be provided.

  • longer-value: If set to True, this value will be used for expiration.

  • default-enabled: Specifies whether default expiration is enabled. If True, the value should be provided as well.

  • default-value: If set to True, this value will be used for expiration.

<sliding-expiration>

This tag helps you retain items in the cache by extending the accessed item’s lifespan by a specific interval of time.

  <sliding-expiration longer-enabled="False" longer-value="0" default-enabled="False" default-value="0"/>

  • longer-enabled: Specifies whether longer expiration is enabled. If True, the value should be provided.

  • longer-value: If set to True, this value will be used for expiration.

  • default-enabled: Specifies whether default expiration is enabled. If True, the value should be provided as well.

  • default-value: If set to True, this value will be used for expiration.

<encryption>

This tag is used to when encryption is enabled.

<encryption enable-encryption="True" key="AJtBe83Cy1og5ZjeWg5YxwqN3Q0ZFGng6z5hM5zA02o=" provider="3DES 128"/>

  • enable-encryption: Specifies whether encryption is enabled or not.

  • key: Specifies the key used to encrypt or decrypt data.

  • provider: Specifies the encryption algorithm and key size.

<cache-topology>

This tag is used for specifying the cluster topology, it also contains a subtag, which further defines the communication details of the cluster. Please note, that this tag will not be present in Local Cache.

<cache-topology topology="partitioned-replica">
<cluster-settings operation-timeout="60sec" stats-repl-interval="2sec" use-heart-beat="True">
  ...
</cluster-settings>
</cache-topology>

  • topology: Specifies which topology the cluster follows, it can be either one of the following as provided by NCache:

    • Partition-Replica Topology
    • Replicated Topology
    • Partitioned Topology
    • Mirror Topology

<cluster-settings>

This tag manages cluster connectivity to monitor node connections.

<cluster-settings operation-timeout="60sec" stats-repl-interval="2sec" use-heart-beat="True">

  • operation-timeout: Determines the timeout of a connection among the servers if a server in the cluster fails to respond. The default value is 60 seconds.

  • stats-repl-interval: (Statistics Replication Interval) is the interval provided to the cluster at which to synchronize their information among its servers. The default value is 2 seconds.

  • use-heart-beat: HeartBeat is used to monitor the connectivity between nodes. The default value is True.

<data-replication>

In the case of Partition-Replica, you will find this tag in the cache configuration. This tag defines how data is replicated to the backup node.

<data-replication synchronous="False"/>
  • synchronous: This attribute can be set to True/False. If set to False, then data operation will be replicated asynchronously on the backup node. If set to True, then data operation will be replicated synchronously on the backup node.

<cluster-connection-settings>

This tag specifies the details of port connectivity and other communication options among the cluster servers:

 <cluster-connection-settings cluster-port="7806" port-range="1" connection-retries="2" connection-retry-interval="2secs" join_retry_count="24" join_retry_timeout="5"/>

  • cluster-port: Connection is channeled through a TCP port; this value defines the port which it occupies. The default value is 7806.

  • port-range: When initializing, if the port provided is taken by some other application then it will try to establish its connection on port incremented by 1, for this the range is provided, i.e., to what range should it search for an available TCP port.

  • connection-retries: If connection among the node(s) is failed, then this defines how many retries should be made to consider it a permanent failure. The default value is 2.

  • connection-retry-interval: The interval between connection retries is defined in this value. The default value is 2 seconds.

  • join_retry_count: Specifies the number of attempts a node makes to join the cluster. By default, it is 24 times.

  • join_retry_timeout: Specifies the time interval a node will wait before attempting to reconnect with other nodes in the cluster. The default value is 5.

<split-brain-recovery>

This tag when enabled, detects possible cluster split-brain issues. It is only in Partition-Replica topology.

<split-brain-recovery enable="False" detection-interval="60"/>

  • enable: This flag is used to enable the Split-Brain Recovery feature. By default, its value is False.

  • detection-interval: detection-interval is the period interval after which the cluster will detect for split-brain condition.

<cache-deployment> 

<cache-deployment deployment-version="5">
  • deployment-version: Specifies the number of updates made to the cache deployment, ensuring version consistency across all nodes.

<data-persistence>

This tag is used to determine the settings of your Distributed Cache with Persistence. It only appears if you've set your store-type as distributed-cache-persistence. It has the following parameters:

<data-persistence store-name="demoPersistenceCache_db">
  <provider-settings provider-type="ncache-persistence" connection-string="lxxKK7Xqh0Tpm3rPvPOmYcCRYyeUV8f8NswyNRFum/uA0HXudbm6vWkXcnJ33GE9"/>
  <operation-setting persistence-interval="1000ms" persistence-retries="3" persistence-interval-longer="60sec"/>
</data-persistence>
  • store-name: Specifies the store name for the Distributed Cache with Persistence.

<provider-settings>

This tag configures the persistence provider for the distributed cache.

  <provider-settings provider-type="ncache-persistence" connection-string="lxxKK7Xqh0Tpm3rPvPOmYcCRYyeUV8f8NswyNRFum/uA0HXudbm6vWkXcnJ33GE9"/>

  • provider-type: This parameter indicates the type of persistence provider you are using in your distributed-cache-persistence. It has value ncache-persistence.

  • connection-string: Specifies a valid connection string that determines the connection with the provider-type.

<operation-setting>

This tag configures the operational parameters for data persistence.

  <operation-setting persistence-interval="1000ms" persistence-retries="3" persistence-interval-longer="60sec"/>

  • persistence-interval: Specifies the interval after which the operations present in the persistence queue are applied to the persistence store. By default, it is 1000ms.

  • persistence-retries: Specifies the number of retries in case of persistence batch failures after which the persistence-interval is shifted to persistence-interval-longer. The default value is 3 seconds.

  • persistence-interval-longer: When several consecutive failures reach persistence-retries the interval is then set to persistence-interval-longer.

<module>

This tag specifies all the modules and their respective parameters registered under a cache. It only appears if you've set your store-type as distributed-lucene. It has the following parameters.

<caching-modules>
  <module name="lucene-net-4.8" enable="True">
    <parameters name="IndexPath" value="C:\ProgramData\ncache\lucene-index\lucene"/>
  </module>
</caching-modules>

  • name: Specifies the name of the module. The module will be identified by whatever name you provide here. This name needs to be unique.

  • enable: Enables/disables the provided module. By default it is True.

<parameters>

This tag defines a list of parameters associated with the module.

    <parameters name="IndexPath" value="C:\ProgramData\ncache\lucene-index\lucene"/>

  • name: Specifies the list of parameters added against a module.

  • value: Specifies the value provided for the added parameter.

<alerts>

If event notifications through email ( feature only) are required, then information for its setup is configured as follows.

<alerts>
    <email-notification email-notification-enabled="False" sender="" smtp-server="" smtp-port="0" ssl="False" authentication="False" sender-login="" sender-password=""/>
    <alerts-types cache-stop="False" cache-start="False" node-left="False" node-joined="False" state-transfer-started="False" state-transfer-stop="False" state-transfer-error="False" cache-size="False"/>
</alerts>

<email-notification>

This tag contains all the information related to the email address.

    <email-notification email-notification-enabled="False" sender="" smtp-server="" smtp-port="0" ssl="False" authentication="False" sender-login="" sender-password=""/>

  • email-notification-enabled: Enables notification through email. By default it is False.

  • sender: Specify the email account from whom the email notifications are sent.

  • smtp-server: Specify the gateway to send email notifications.

  • smtp-port: The port number used to forward emails.

  • ssl: Secure Socket Layer to enable SSL security. By default it is False.

  • authentication: If any authentication is required, this is to be True. By default it is False.

  • sender-login: If Authentication is required, specify the login name.

  • sender-password: The authentication password is entered here.

<alerts-types>

This tag specifies at which event an automated email is to be generated. By default all values are False.

    <alerts-types cache-stop="False" cache-start="False" node-left="False" node-joined="False" state-transfer-started="False" state-transfer-stop="False" state-transfer-error="False" cache-size="False"/>

  • cache-stop: If the cache is stopped at any moment, an email notification is generated.

  • cache-start: If the cache is started, an email notification is generated.

  • node-left: When a server node leaves the cluster or if a server node is inaccessible for any reason, an email notification will be sent if this is enabled.

  • node-joined: At the joining of any server node an email notification is generated.

  • state-transfer-started: When enabled, this tag initiates email alerts to notify customers whenever the state transfer process is started.

  • state-transfer-stop: When enabled, this tag initiates email alerts to notify customers whenever the state transfer process is stopped.

  • cache-size: When set to True, an email notification is generated whenever cache size is changed during run-time.

<sql-dependency>

This tag specifies the queuing and service SQL notification architecture. ( only)

<sql-dependency use-default="False"/>
  • use-default: If the attribute is set to True, then the default SQL Dependency service and queue will be created at run time. If the attribute is set to False, then the custom-defined SQL Dependency service and queue will be created and used by NCache. By default it is False.

See Also

Client-side Configurations
Bridge Config
Security Config