Cache Config (config.ncconf)

The cache configuration file contains information regarding all the registered caches/clusters. Modules that need to read configurations first attempt to locate 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.

Note

Starting with NCache 5.3 SP7, the serialization format is fixed to Json and should not be treated as a configurable setting.

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. Each cache detail is enclosed in <cache-config></cache-config>.
-->

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

Understanding the Cache Config Tags

The following section explains the tags mentioned in the file syntax.

<cache-config>

This tag defines essential cache settings.

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

• cache-name: Specifies the unique name of the cache.

• store-type: Specifies the purpose or category of the cache store. This value helps identify whether the cache is used as a regular distributed cache, or for Pub/Sub messaging. Possible values include:

  • Distributed-Cache
  • Pub/Sub-Messaging

• environment: Specifies the deployment environment associated with the cache, such as Development, Production, and QA.

• config-id: Specifies the unique identifier assigned to the cache configuration. This auto-generated ID helps distinguish one cache configuration from another.

• config-version: Used to determine whether the configuration has been modified.

<cache-settings>

This tag configures cache operation and execution. It defines how the cache runs, whether it starts automatically, how data is stored, and the serialization format used for cached objects. Feature-specific settings such as logging, performance counters, storage, eviction, expiration, compression, pipelining, and topology are configured as child tags inside <cache-settings>.

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

• inproc: Determines whether the cache runs as InProc or OutProc. If set to True, the cache runs as InProc in the application process. If set to False, the cache runs as OutProc in a separate process. The default value is False.

• last-modified: Stores information about the last modification made to the cache configuration.

• auto-start: Specifies whether the cache should start automatically when the NCache Service starts. If set to True, the cache starts automatically with the service. If set to False, the cache must be started manually. The default value is False.

• data-format: Specifies the format in which data is stored in the cache. The default value is Serialized.

• serialization: Indicates the serialization format for the cache. The supported value is Json.

<logging>

NCache maintains a log file to write traces for information and debugging purposes. By default, only the Error trace is enabled; the rest of the traces are disabled. Error logs are useful for identifying critical issues, while notice, warning, and debug logs provide additional details for troubleshooting. Since detailed logging can affect performance, notice, warning, and debug traces should be enabled only when required.

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

• enable-logs: Specifies whether logging is enabled for the cache. By default, it is True. However, extensive logging can create overhead and degrade application performance.

• trace-errors: Specifies whether error messages are written to the cache log. Error logs help identify and troubleshoot critical issues. By default, it is True.

• trace-notices: Specifies whether notice-level messages are written to the cache log. These messages provide general runtime information about cache behavior. By default, it is False.

• trace-warnings: Specifies whether warning messages are written to the cache log. Warnings are useful for detecting and addressing potential issues. By default, it is False.

• trace-debug: Specifies whether detailed debug messages are written to the cache log. Debug logs provide detailed diagnostic information and are mainly used during development, testing, or troubleshooting. By default, it is False.

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

<performance-counters>

This tag controls whether NCache publishes runtime performance statistics for the cache. When configured, NCache will update the published PerfMon counters.

<performance-counters enable-counters="True" snmp-port="0"/>

• enable-counters: Specifies whether PerfMon counters are enabled for the cache. If set to True, NCache publishes performance counters for monitoring. If set to False, performance counters are not published for the cache. By default, it is True.

• snmp-port: It enables SNMP-based monitoring and defines the port through which SNMP data is communicated. If the value is set to 0, no SNMP port is configured for the cache.

<data-load-balancing>

This tag controls automatic data load balancing for partitioned cache topologies. Data load balancing helps distribute cached data more evenly across cluster nodes when one node contains more data than the configured threshold.

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

• enabled: Specifies whether to enable data load balancing. If set to True, NCache can automatically trigger data balancing when the configured threshold is exceeded. If set to False, automatic data load balancing is disabled. By default, this is set to False.

• auto-balancing-threshold: Specifies the percentage above the average data size per node that triggers automatic data load balancing. 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: Specifies whether compression is enabled for cached items. To enable compression, set this attribute to True; otherwise, by default, it is False.

• threshold: Specifies the minimum item size required for compression/decompression on the client-side. Only items larger than this value are compressed when compression is enabled. For example, if the threshold is set to 100kb, only items larger than 100 KB are compressed/decompressed.

<pipelining>

This tag controls operation pipelining for the cache by allowing multiple client operations to be collected and sent together in batches instead of being sent one by one. This helps reduce network round trips between the client and cache server.

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

• enabled: Specifies whether pipelining is enabled for the cache. 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 True.

• 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 NCache to identify client applications that are no longer connected to the cache and release the server-side resources associated with those disconnected clients.

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

• enable: Specifies whether client death detection is enabled or not. The default value is False. You need to add this tag manually in config.ncconf file.

• 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. You need to add this tag manually in config.ncconf file.

<client-activity-notification>

This tag controls client activity notifications for the cache. When enabled, NCache notifies client applications when another client connects to or disconnects from the cache. 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: Specifies whether client activity notifications are enabled for the cache. If set to True, clients can receive notifications when other clients connect to or disconnect from the cache. If set to False, client activity notifications are disabled. The default value is False.

• retention-period: The time interval after which a disconnected client is considered disconnected. By default, its value is 5 seconds.

<cache-notifications>

The cache-notifications tag specifies the registered event with the cache. These notifications allow applications to receive events when items are added, updated, or removed from 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: Specifies whether notifications are generated when an item is added to the cache. If set to True, NCache notifies registered clients when a new item is added. If set to False, add notifications are not generated. The default value is False.

• item-remove: Specifies whether notifications are generated when an item is removed from the cache. If set to True, NCache notifies registered clients when an item is removed. If set to False, remove notifications are not generated. The default value is False.

• item-update: Specifies whether notifications are generated when an item is updated in the cache. If set to True, NCache notifies registered clients when an item is updated. If set to False, update notifications are not generated. The default value is False.

• 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 controls the cleanup interval for expired cache items. NCache uses this interval to periodically check the cache for items that have reached their expiration time and remove them from the 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 defines how much memory is allocated for storing cached data. It specifies the storage type used by the cache and the maximum cache size allowed.

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

• type: Specifies the storage type used for cached data. This attribute can only be set to "heap" as NCache currently supports heap-based storage only.

• cache-size: Specifies the maximum size of the cache in MB. Once the cache reaches this size, NCache may evict items according to the configured eviction policy if eviction is enabled. The default value is 1024 MB.

<eviction-policy>

This tag controls how NCache removes existing items from the cache when the configured cache size limit is reached. If eviction is enabled, NCache uses the selected eviction policy to decide which items should be removed so that space is available for new items.

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

• enabled-eviction: Specifies whether eviction is enabled for the cache. If eviction is set to True then the cache will remove existing items to accommodate new ones. Existing items will be removed based on the eviction strategy. By default, it is True.

• default-priority: Specifies the default eviction priority assigned to cache items when no priority is provided at the item level. This attribute can be set to the following:

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

  This is only applicable in the case of priority-based eviction.

• policy: Specifies the eviction policy used to determine which items are removed from the cache. Possible values include:

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

• eviction-ratio: Specifies the percentage of cache data that is removed during an eviction cycle. For example, if this value is set to 5%, NCache evicts up to 5% of the cache data when eviction is triggered.

<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: Specifies whether expiration policy settings are enabled. By default, it is False.

<absolute-expiration>

This tag defines absolute expiration settings. Absolute expiration removes cached items after a fixed period of time.

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

• longer-enabled: Specifies whether longer expiration is enabled. If set to True, NCache uses the value specified in longer-value.

• longer-value: Specifies the longer absolute expiration duration. This value is used only when longer-enabled is set to True.

• default-enabled: Specifies whether default expiration is enabled. If set to True, NCache uses the value specified in default-value.

• default-value: Specifies the default absolute expiration duration. This value is used only when default-enabled is set to True.

<sliding-expiration>

This tag defines sliding expiration settings. Sliding expiration removes cached items only if they remain inactive for the configured duration. Each time an item is accessed, its expiration time is extended by the sliding expiration interval.

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

• longer-enabled: Specifies whether the longer sliding expiration value is enabled. If set to True, NCache uses the value specified in longer-value.

• longer-value: Specifies the longer sliding expiration duration. This value is used only when longer-enabled is set to True.

• default-enabled: Specifies whether the default sliding expiration value is enabled. If set to True, NCache uses the value specified in default-value.

• default-value: Specifies the default sliding expiration duration. This value is used only when default-enabled is set to True.

<encryption>

This tag is used when encryption is enabled. When encryption is enabled, NCache encrypts cached data before storing it and decrypts it when the data is retrieved.

<encryption enable-encryption="True" key="AJtBe83Cy1og5ZjeWg5YxwqN3Q0ZFGng6z5hM5zA02o=" provider="AES 256"/>

• enable-encryption: Specifies whether data encryption is enabled for the cache.

• key: Specifies the encryption key used to encrypt and decrypt cached 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="60sec" use-heart-beat="False">
    ...
  </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 defines cluster-level runtime settings for a clustered cache topology. It controls how cache servers communicate with each other, how long operations can wait before timing out, how frequently statistics are replicated between servers, and whether heartbeat-based node connectivity monitoring is used.

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

• 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: Specifies the interval at which cache statistics are replicated between cluster nodes. The default value is 60 seconds.

• use-heart-beat: Heartbeat is used to monitor connectivity between nodes. The default value is False.

<data-replication>

This tag defines the replication mode for cache data in a Partition-Replica topology. It determines whether updates made on an active partition are replicated to the replica node synchronously or asynchronously.

<data-replication synchronous="False"/>

• synchronous: This attribute can be set to True/False. If set to False, then data operations will be replicated asynchronously on the backup node. If set to True, then data operations will be replicated synchronously on the backup node. The default value is False.

<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="2" connection-retries="2" connection-retry-interval="2secs" join_retry_count="24" join_retry_timeout="5"/>

• cluster-port: Specifies the TCP port used by cache server nodes for cluster communication.

• port-range: When initializing, if the configured cluster port is already in use by another application, NCache will try to establish the connection on the next available TCP port by incrementing the port number by 1. This tag specifies the range within which NCache should search for an available port.

• connection-retries: Specifies how many times a cache server retries a failed connection attempt before treating the connection as failed. The default value is 2.

• connection-retry-interval: Specifies the time interval between connection retry attempts. 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 applicable 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: Specifies the interval after which NCache checks for a split-brain condition. The default value is 60.

<cache-deployment>

It refers to the configuration and setup of cache instances across servers.

<cache-deployment deployment-version="5">
  <servers>
    <server-node ip="20.200.20.39" active-mirror-node="False"/>
  </servers>
</cache-deployment>

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

• ip: Specifies the IP address of the server node where the cache is hosted.

• active-mirror-node: Indicates whether the node is acting as an active mirror node in the cluster. By default, this value is False.

<alerts>

If email-based event notifications are required, the following configuration is used.

<alerts>
  <email-notification email-notification="True" sender="" smtp-server="smtp.diya-tech.com" smtp-port="25" tls="True" security-protocol="tls12" authentication="False" sender-login="" sender-password="">
    <recipient email-id=""/>
  </email-notification>
  <alerts-types cache-stop="False" cache-start="True" node-left="False" node-joined="False" state-transfer-started="False" state-transfer-stop="False" state-transfer-error="False" partial-connectivity-detected="False" cache-size="False"/>
</alerts>

<email-notification>

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

<email-notification email-notification="True" sender="john_smith@alachisoft.com" smtp-server="smtp.alachisoft.com" smtp-port="25" tls="True" security-protocol="tls12" authentication="False" sender-login="" sender-password="">

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

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

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

• tls: Enables Transport Layer Security for secure encrypted email transmission.

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

• 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.

• security-protocol: Specifies which TLS version should be used for secure email communication in NCache alerts.

<alerts-types>

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

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

• 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: Upon 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 runtime.

• partial-connectivity-detected: When set to True, it triggers an email alert when one or more cache nodes experience limited or broken connectivity with others, indicating a possible network partition or communication issue within the cluster.

• state-transfer-error: When set to True, it notifies when a state transfer process encounters an error in a clustered cache environment.

<bridge>

This tag specifies the bridge connection details for a cache that participates in Bridge WAN replication.

<bridge id="demoBridge" environment="WestCoast" port="9900" status="active">
  <server name="20.200.20.39" is-load-balancer="False"/>
</bridge>

• id: Specifies the unique name of the bridge.

• environment: Specifies the environment associated with the bridge.

• port: Specifies the port used by the cache to connect with the bridge.

• status: Specifies whether the cache in question will replicate operations to the Bridge (active) or passively receive operations (passive).

<server>

This tag is specified under the <bridge> tag and defines the bridge endpoint used by the cache.

<server name="20.200.20.39" is-load-balancer="False"/>

• name: Specifies the bridge server IP address, host name, or Load Balancer endpoint.

• is-load-balancer: Specifies whether the value provided in name represents a Load Balancer endpoint. Set this value to True if the cache connects to the bridge service through a Load Balancer.

See Also

Client-side Configurations
Bridge Config
Security Config