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.
This tag defines essential cache settings. 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: config-id:
Auto-generates unique Id for the modified configuration. config-version:
Used to determine whether the configuration is modified or not. This tag configures cache operation and execution. 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. (NCache Enterprise only) 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. 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. 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 When configured, NCache will update the published PerfMon counters. This tag allows you to automatically trigger data load balancing on nodes in a partitioned cluster. 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. This tag specifies whether the items greater than the specified threshold should be compressed/decompressed on the client side. 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. This tag enables batching several instructions over a TCP connection, reducing network cost and enhancing performance by sending bulk commands at specified intervals. 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. This tag allows the server to monitor if a client is disconnected from all cache servers in a clustered cache. 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. 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. 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. The cache-notifications tag specifies the registered event with the cache. All the flags in this tag are marked False by default. 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. This tag preodically removes items from cache. This tag specifies the storage-related details for cache. 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. This tag specifies whether to perform the eviction or not. 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: 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: eviction-ratio:
Specifies how much percentage of data should be evicted when eviction is performed. This tag specifies the basis under which the cache entries will expire and be removed from the cache. This tag will specify the exact time the cache entries will expire and be removed. 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. This tag helps you retain items in the cache by extending the accessed item’s lifespan by a specific interval of time. 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. 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. topology:
Specifies which topology the cluster follows, it can be either one of the following as provided by NCache: This tag manages cluster connectivity to monitor node connections. 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. 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. This tag specifies the details of port connectivity and other communication options among the cluster servers: 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. This tag when enabled, detects possible cluster split-brain issues. It is only in Partition-Replica topology. enable:
This flag is used to enable the Split-Brain Recovery feature. By default, its value is False. detection-interval:
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: This tag configures the persistence provider for the distributed cache. 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. This tag configures the operational parameters for data persistence. 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. This tag specifies all the modules and their respective parameters registered under a cache. It only appears if you've set your 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. This tag defines a list of parameters associated with the module. name:
Specifies the list of parameters added against a module. value: Specifies the value provided for the added parameter. If event notifications through email (Enterprise feature only) are required, then information for its setup is configured as follows. This tag contains all the information related to the email address. 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. This tag specifies at which event an automated email is to be generated. By default all values are 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. This tag specifies the queuing and service SQL notification architecture. (Enterprise only)<cache-config cache-name="demoCache" alias="" store-type="Distributed-Cache" config-id="6a49d9ce-9aa7-4312-ada6-4fec37a6e729" config-version="0">
<cache-settings>
<cache-settings inproc="False" last-modified="" auto-start="False" data-format="Serialized" serialization="Binary">
<logging>
<logging enable-logs="True" trace-errors="True" trace-notices="False" trace-warnings="False" trace-debug="False" log-path=""/>
%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>
<performance-counters enable-counters="True" snmp-port="0"/>
<data-load-balancing>
<data-load-balancing enabled="False" auto-balancing-threshold="60%" auto-balancing-interval="30sec"/>
<compression>
<compression enable-compression="False" threshold="100kb"/>
<pipelining>
<pipelining enabled="False" batch-interval="250usec"/>
<client-death-detection>
<client-death-detection enable="False" grace-interval="60sec"/>
<client-activity-notification>
<client-activity-notification enabled="False" retention-period="5sec"/>
<cache-notifications>
<cache-notifications item-remove="False" item-add="False" item-update="False" expiration-time="15sec"/>
<cleanup>
<cleanup interval="15sec"/>
<storage>
<storage type="heap" cache-size="1024mb"/>
<eviction-policy>
<eviction-policy enabled-eviction="True" default-priority="normal" policy="lru" eviction-ratio="5%"/>
<expiration-policy>
<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>
<absolute-expiration>
<absolute-expiration longer-enabled="False" longer-value="0" default-enabled="False" default-value="0"/>
<sliding-expiration>
<sliding-expiration longer-enabled="False" longer-value="0" default-enabled="False" default-value="0"/>
<cache-topology>
<cache-topology topology="partitioned-replica">
<cluster-settings operation-timeout="60sec" stats-repl-interval="2sec" use-heart-beat="True">
...
</cluster-settings>
</cache-topology>
<cluster-settings>
<cluster-settings operation-timeout="60sec" stats-repl-interval="2sec" use-heart-beat="True">
<data-replication>
<data-replication synchronous="False"/>
<cluster-connection-settings>
<cluster-connection-settings cluster-port="7806" port-range="1" connection-retries="2" connection-retry-interval="2secs" join_retry_count="24" join_retry_timeout="5"/>
<split-brain-recovery>
<split-brain-recovery enable="False" detection-interval="60"/>
detection-interval is the period interval after which the cluster will detect for split-brain condition. <cache-deployment>
<cache-deployment deployment-version="5">
<data-persistence>
<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>
<provider-settings>
<provider-settings provider-type="ncache-persistence" connection-string="lxxKK7Xqh0Tpm3rPvPOmYcCRYyeUV8f8NswyNRFum/uA0HXudbm6vWkXcnJ33GE9"/>
<operation-setting>
<operation-setting persistence-interval="1000ms" persistence-retries="3" persistence-interval-longer="60sec"/>
<module>
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>
<parameters>
<parameters name="IndexPath" value="C:\ProgramData\ncache\lucene-index\lucene"/>
<alerts>
<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>
<email-notification email-notification-enabled="False" sender="" smtp-server="" smtp-port="0" ssl="False" authentication="False" sender-login="" sender-password=""/>
<alerts-types>
<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"/>
<sql-dependency>
<sql-dependency use-default="False"/>
See Also
