NCache Server

NCache Server consists of multiple services and runtime processes that manage cache lifecycle, client connectivity, cluster communication, bridge operations, and background execution tasks. This section explains how these server-side components work together, where their configuration and log files are stored, and how service-level settings such as shutdown handling and IP binding affect cache operation.

Processes

The NCache server runs multiple processes, where each process is responsible for a specific server-side function such as cache management, cache hosting, bridge operations, or background execution. Together, these processes handle cache lifecycle operations, client connectivity, bridge management, and data loading tasks on a server node. The processes are:

Alachisoft.NCache.Service

The NCache Service is a core component of the configuration and management of caches. It manages all caches on that server, listens on the management port (default 8250), and acts as the entry point for all cache management and client connection operations on that node.

Role of NCache Service (NCacheSvc)

Upon startup, the NCache Service reads the configuration of all configured caches from the config.ncconf file. It manages cache lifecycle operations, including starting and stopping cache instances on that server.

When a cache is started, the NCache Service starts a dedicated CacheHost process (Alachisoft.NCache.CacheHost.exe) for that cache instance. Each running cache operates in its own CacheHost process, which provides process-level isolation between cache instances on the same server and reduces Garbage Collector (GC) pressure.

The NCache Service assigns each CacheHost process a unique management port for service-to-cache communication. This port mapping is maintained in the CacheHostPorts.xml file at %NCHOME%\bin\service, which is auto-generated and managed exclusively by the NCache Service and should not be manually edited.

The NCache Service is also responsible for stopping CacheHost processes. This occurs either through an explicit management operation, such as stopping a cache via NCache management tools, or when the CacheHost process receives a process termination notification during shutdown and initiates a graceful shutdown. In cases of abrupt failure, such as a power cut or hardware crash, no shutdown event is issued by the operating system, and the NCache Service has no opportunity to stop the CacheHost processes in a controlled manner. The Get-Caches cmdlet displays the process ID of each running cache host process.

The NCache Service also listens for incoming cache client connection requests on the default client port (9800). It accepts client connections and forwards them to the corresponding cache host process. After this initial handshake, all further communication occurs directly between the client and the cache host process, without involving the NCache Service. However, the NCache Service must remain running to accept all new client connections.

For configuration updates, it is recommended to use NCache management tools, such as NCache Management Center or PowerShell cmdlets, so that changes are applied consistently across the environment. Since the NCache Service loads configuration at startup, certain service-level configuration changes may require restarting the NCache Service to take effect.

Cache Node Exit Behavior

As discussed, a cache node can leave a cluster either gracefully or abruptly, and the NCache Service responds differently in each case. Understanding the difference is important because the two scenarios have significantly different outcomes for cluster stability and client availability.

  • Graceful Exit: When a node leaves gracefully through NCache management tools, it explicitly informs all peer nodes that it is leaving the cluster. The peer nodes immediately update the cluster view and redistribute data if required. The cache continues to operate in a stable manner, and active clients experience no disruption. The recommended approach for any planned maintenance, such as patching, restarting, or shutting down a machine, is to stop all caches on that node first using NCache management tools, and then proceed with the shutdown or restart. This ensures the node exits the cluster gracefully before the machine goes down.
Note

If the number of caches running on a node is high, stopping them all before shutdown may take additional time. Plan accordingly when scheduling maintenance windows.

  • Abrupt Exit: When a node leaves abruptly, due to a power cut, hardware failure, or any condition that does not allow for a controlled shutdown, it does not notify the cluster. The remaining nodes are not immediately aware that the node is gone. Instead, they rely on heartbeat and timeouts to detect the departure, which takes time. During this detection window, the cluster is in a vulnerable state. The hash map has not been updated, and client requests directed at the missing node begin to time out. This is the period of exposure that should be avoided wherever possible.

NCache includes dynamic clustering and self-healing capabilities that allow it to eventually recover from a vulnerable state automatically, though this process takes time.

Shutdown Event Handling

To reduce the chances of an abrupt exit during an operating system shutdown, NCache introduces shutdown event handling as an additional safety measure. On supported platforms, including Windows and Linux, the CacheHost process registers a callback for process termination notifications with the operating system.

When the operating system shuts down, it instructs running processes to terminate. The CacheHost process receives this termination notification and initiates a graceful shutdown of itself through NCache's management path, notifying peer nodes that it is leaving the cluster. This allows the remaining nodes to update their cluster view without waiting for heartbeat and timeouts, thus reducing the vulnerable window.

However, this is not always guaranteed. Operating systems provide only a limited time window for processes to complete their shutdown work after issuing the process termination event. If the caches do not finish their graceful shutdown sequence within that window, the node will still go down abruptly. Additionally, in cases of abrupt failure, such as a power cut, kernel crash, or forced power-off, no process termination event is issued by the operating system at all, and the CacheHost process has no opportunity to exit gracefully.

Warning

Shutdown event handling increases the chances of a graceful exit during a Windows or Linux shutdown, but it is not a reliable substitute for manually stopping caches before planned maintenance.

Important

Always stop caches on a node using NCache management tools before shutting down or restarting the machine. Shutdown event handling is a best-effort safety net and is not guaranteed to complete in all scenarios. Any situation that does not produce a process termination notification, including power cuts, crashes, and forced shutdowns, will result in an abrupt leave, and the cluster will enter a vulnerable state until heartbeat and timeouts detect the departure.

Alachisoft.NCache.ManagementCenter

The NCache Management Center (Alachisoft.NCache.ManagementCenter.exe) is the web-based graphical interface for administering NCache. It runs as a process on the cache server and is accessible from any browser at http://localhost:8251 or <server-ip>:8251. It communicates with the NCache Service on each node to perform management operations across the cluster.

The Management Center is the primary tool for interacting with NCache without writing any scripts or commands. All operations that affect cache configuration or runtime state are available through it.

Cache Operations

The Management Center covers the full lifecycle of a cache, including:

Cache Feature Configuration

Beyond basic lifecycle management, the Management Center provides configuration interfaces for advanced cache features, including:

  • Query Indexes: Configure query indexes on cached objects to enable searching and querying cached data using SQL-like queries instead of retrieving data only by cache key.

  • Read-Through and Write-Through Providers: Configure data source providers that allow the cache to automatically retrieve data from, and write data to an underlying data source during cache operations.

  • Cache Startup Loader and Refresher: Configure the Cache Startup Loader to preload data from an underlying data source when the cache starts, and configure the Cache Refresher to periodically synchronize cached data with the data source.

  • Security Settings: Configure cache security settings to control cache access by users and groups.

  • Expiration and Eviction Policies: Configure expiration policies to remove cache items automatically, and configure eviction policies to manage cache memory usage when the cache reaches its configured size limit.

  • Compression and Encryption: Configure data compression to reduce cache memory consumption and network traffic, and configure data encryption to secure cached data.

Note

The Management Center process must be running on the server for the web UI to be accessible. It communicates with the NCache Service via the management port (default 8250). If the NCache Service on a node is not running, that node will not be reachable from the Management Center.

Alachisoft.NCache.CacheHost

The CacheHost (Alachisoft.NCache.CacheHost.exe) is the dedicated runtime process responsible for hosting an individual cache instance on a server node. Each running cache operates within its own separate CacheHost process. The NCache Service manages the lifecycle of CacheHost processes and starts a dedicated process whenever a cache is started.

Server Communication with the Cache

The NCache Service communicates with each CacheHost process through its assigned Management Port. This port is dynamically allocated from the configured management port range when the CacheHost process starts.

All cache management operations are routed through this communication channel between the NCache Service and the CacheHost process.

Client Communication with the Cache

The initial communication of the client with a cache host is a two-hop communication:

  • It first interacts with the service, which connects the client to the cache host using the cache host port.

  • It then communicates directly with the cache. All future interactions for the client are made directly with the CacheHost process.

The NCache Service communicates with each CacheHost process through its assigned CacheHost port. This port is selected from the configured management port range when the cache is created or assigned, and the assignment remains associated with that cache instance.

When a cache is started in its own separate process, it is assigned a Management Port on which the service will communicate with it. This port is dynamically generated from a range (default 8300–8400, configurable in service.exe.config) at the time the cache is created, and the assignment persists for the lifetime of that cache instance.

When the CacheHost process stops, the assigned port is no longer in use at the operating system level. However, the port assignment for that cache does not change simply because the process has stopped. The assignment remains associated with the cache instance unless the cache is deleted or the configuration is changed.

Alachisoft.NCache.ExecutionService

The NCache Execution Service (Alachisoft.NCache.ExecutionService.exe) is responsible for managing tasks and loading data from the data source into caches on cache startup. It works with the Cache Startup Loader and Cache Refresher to preload application data into the cache and periodically synchronize that data with the underlying data source.

In earlier versions of NCache, the cache and the Cache Loader used to run in the same process. This overburdened the cache process, particularly at loading time, and resulted in temporary degradation in the performance of the overall cache. To address this, NCache introduced a dedicated NCache Execution Service for handling loader operations separately.

The Execution Service runs on all cache servers in a clustered topology, where each node has a dedicated service responsible for loading data into its cache. The Cache Loader also runs in parallel on all cache servers, and datasets are distributed among nodes in a round-robin fashion. Within the InProc topology, the task still executes in the same process instead of using the dedicated Execution Service.

Note

If the Cache Loader fails to load data due to a connectivity issue or an error in the user-provided implementation, the error is recorded in the Execution Service logs. Check these logs to diagnose startup loading failures.

Alachisoft.NCache.BridgeService

The NCache Bridge Service is the core component responsible for facilitating asynchronous multi-site replication between geographically dispersed cache clusters. It manages all Bridge caches on that server, listens on the management port (default 8260), and acts as the entry point for all Bridge management and cache connection operations on that node.

Unlike cache clusters, where the NCache Service manages external CacheHost processes, Bridge caches reside within the Bridge Service itself.

Role of the Bridge Service

Upon startup, the Bridge Service reads the configuration of all configured Bridge caches from the bridge.ncconf file. The Bridge Service is responsible for starting and stopping Bridge cache instances and assigns each a unique port drawn from a dedicated range (default 10000–11000) for internal communication. The Bridge Service supports the following management operations, performed via the NCache Management Center or PowerShell tools over the management port (8260):

Bridge Communication

The Bridge Service uses dedicated communication ports for management and replication operations.

  • Management Port: The ManagementPort setting specifies the port on which the Bridge Management Server listens for management and monitoring connections. The default value is 8260. Bridge management operations, such as creating, configuring, starting, and stopping bridge instances, are performed through this communication channel.

  • Bridge Client Port: This port specifies the port on which the Bridge Service listens for incoming client connections. The default value is 9900.

  • Bridge Cluster Communication: Bridge nodes also communicate with each other using a dedicated cluster communication port range (default 10000-11000) for synchronization between bridge nodes.

Configuration Files

NCache configuration files are located at %NCHOME%\config on Windows or /opt/ncache/config on Linux.

  • config.ncconf: Contains information regarding all registered caches and clusters. The NCache Service reads this file on startup; changes require a service restart to take effect.

  • client.ncconf: Used by the NCache client API to get the initial information required to establish a connection with the server. It contains client connection settings such as retries, timeouts, ports, and cache server information.

  • security.ncconf: Stores the security information used by server nodes to provide security services to clients.

  • tls.ncconf: Stores TLS settings used to manage secure communication.

  • bridge.ncconf: Contains information regarding all registered bridges. Bridge configuration can be managed through the NCache Management Center or the bridge.ncconf file.

  • monitoring.ncconf: Stores NCache monitoring configuration and is used to enable NCache monitoring.

  • emails-template.xml: Defines the email templates used for NCache email alerts.

Log Files

NCache log files help diagnose cache, service, bridge, execution service, client, and performance-related activity. Error logging creates timestamped log files by default under %NCHOME%\log-files on Windows or /opt/ncache/log-files on Linux. A custom log path can be specified for a cache through the log-path attribute in config.ncconf, or from the NCache Management Center under the cache's Advanced Settings.

Server-side error logging is enabled by default, while detailed logging is disabled by default. Logging can be configured per cache from the NCache Management Center, or by editing the <logging> tag under <cache-settings> in config.ncconf. The cache must be stopped before logging configuration changes are made. After manual configuration changes, restart the NCache Service.

Client-side logging is configured separately through client.ncconf or through client connection options.

Server-Side Log Files and Folders

The following server-side log files and folders can be generated in the NCache log directory.

Log Files

  • Cache log files: Generated for each cache when cache logging is enabled. The file name includes the cache name, timestamp, and server IP address. These logs record cache-related messages according to the logging options configured for the cache.

  • Bridge cache log files: Generated for bridge caches. These logs are created at the root of the log directory and use the bridge cache name in the file name. Bridge-related logging is controlled through bridge configuration settings.

  • ncache-feature-usage.xml: Records node-level feature usage information, including cache environment, connected client information, cache topology, and features used by configured caches.

Log Folders

  • ServiceLogs: Contains NCache Service log files. These files include the service process ID, timestamp, and server IP address in the file name, and a new file is created when the service restarts. These logs are used for service-level diagnostics.

  • ExecutionService: Contains NCache Execution Service log files. These logs are useful for diagnosing Cache Startup Loader and Refresher failures.

  • PerfmonLogs: Contains performance counter logs for server-side and client-side monitoring, including in-process, out-of-process, client, and client-cache counters.

Enabling and Disabling Logging

Server-Side Logging

Server-side error logging can be enabled or disabled from the NCache Management Center. Open the cache details, go to Advanced Settings > Options, and configure logging from there. Error logging is enabled by default, while detailed logging can be enabled when deeper diagnostics are required.

Logging can also be configured manually in config.ncconf:

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

If logging is configured manually, apply the change consistently where required, start the cache and restart the NCache Service.

Client-Side Logging

Client-side logging can be configured in client.ncconf:

<cache id="demoCache"
       enable-client-logs="True"
       log-level="error">
  <server name="20.200.20.40"/>
</cache>

Client-side logging can also be enabled programmatically through cache connection options. When both client.ncconf and connection options are used, the values provided through connection options take priority.

Log Levels

NCache logging is controlled by enabling logging and selecting the required trace level. By default, error logging is enabled, while notice, warning, and debug traces are disabled. Error logging is suitable for production troubleshooting with minimal overhead, but additional trace levels write more data to disk and can affect performance.

Important

Enable detailed or debug-level logging only when needed for diagnostics, and disable it before returning the cache to normal production load.

IP Binding with Multiple NICs

NCache supports separating client-server communication from server-to-server cluster communication by binding each type of traffic to a different network interface. This segregation can help reduce network contention and improve communication efficiency in high-traffic environments.

The NCache Service uses IP binding to determine which network interface is used for cluster communication and which interface is used for client-server communication. The configured IP bindings are stored in the NCache Service configuration file:

  • Windows: Alachisoft.NCache.Service.dll.config in %NCHOME%\bin\service
  • Linux: Alachisoft.NCache.Daemon.dll.config in /opt/ncache/bin/service

The NCache Service uses the following settings:

  • BindToClusterIP: Specifies the IP address used for cluster-wide server-to-server communication.
  • BindToClientServerIP: Specifies the IP address used for client communication with the server.

By default, the IP address selected during installation is used for both client-server and server-to-server communication. These communication types serve different purposes and can be separated later by configuring BindToClientServerIP and BindToClusterIP.

If IP binding is configured through NCache Management Center, the required configuration updates are handled automatically. If the service configuration file is updated manually, ensure the change is applied consistently where required and restart the NCache Service for the updated settings to take effect.

Important

If one node is part of multiple clusters, any IP binding change is reflected on all clusters because the NCache Service configuration file is updated accordingly.

See Also

Cache Management
Client Management