Client Config (client.ncconf)

This client configuration file (client.ncconf) is used by the NCache client API to get the initial information required to establish a connection with the server. This file is universal for all client instances running on the client node. It is located at %NCHOME%\config in Windows or /opt/ncache/config in Linux. For modules that need to read the configurations, first they try to find the client.ncconf file in the application folder. If they do not find the client.ncconf in the application folder, they then read the configuration from the installation folder.

The client configuration file allows local and remote clients to connect to the caches. Moreover, remote clients also use this configuration file to connect to remote caches. This file automatically updates each time a new cache/cluster is created. Similarly, it updates every time new cache/cluster configuration settings are applied. However, this will only happen as long as NCache is installed on the machine and the NCache service is running.

Note

The same configurations can be specified via the CacheConnectionOptions API in the Alachisoft.NCache.Client SDK. For more details on how to use the API while initializing caches, please refer to the Connect to Cache page in the Programmers' Guide.

Important

The configurations specified through CacheConnectionOptions will override the configurations in the client.ncconf. Although, this is only true for the client that specifies them.

Client Config Syntax

The client configuration file is explained below.

<configuration>
  <ncache-server connection-retries="3" retry-connection-delay="0" retry-interval="1" load-balancer-connection-retries = "15" command-retries="3" command-retry-interval="0.1" client-request-timeout="90" connection-timeout="5" port="9800" local-server-ip="20.200.20.38" enable-keep-alive="False" keep-alive-interval="30" />
  <cache id="demoCache" client-cache-id="" client-cache-syncmode="optimistic" default-readthru-provider="" default-writethru-provider="" load-balance="False" enable-client-logs="False" log-level="error">
    <server name="20.200.20.38" is-load-balancer="True"/>
    <server name="20.200.20.23" is-load-balancer="True"/>
  </cache>
</configuration>

Understanding the Client Config Tags

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

<ncache-server>

This tag configures the connection settings between the client and NCache server and ensures communication.

<ncache-server connection-retries="3" retry-connection-delay="0" retry-interval="1" load-balancer-connection-retries = "15" command-retries="3" command-retry-interval="0.1" client-request-timeout="90" connection-timeout="5" port="9800" local-server-ip="20.200.20.38" enable-keep-alive="False" keep-alive-interval="30" />

  • connection-retries: Determines the number of retries the client makes on the whole list of servers mentioned in the client.ncconf file at the time when establishing a connection. It is the same if the connection breaks. By default, its value is 3.

  • retry-connection-delay: Specifies the time interval that the client API waits before going through another iteration of connection-retries. Delay is specified in seconds and the default value is 0 second.

  • retry-interval: If there is a disconnection and the client attempst to reconnect. This flag specifies the interval between each connection attempt. It is specified in seconds and the default value is 1 second. For instance, if the retry-interval is set to 3 seconds, then the client will wait 3 seconds before each retry atempt.

  • load-balancer-connection-retries: Specifies the number of attempts the load balancer makes to connect a client to the correct server for each connection retry. The defaut value is 15.

  • command-retries: Determines the number of times a command is executed after the connection between the client and the cache server is broken and re-established to ensure successful execution. By default, its value is 3.

  • command-retry-interval: Specifies the time gap between two successive command-retries. By default, it is 0.1 second.

  • client-request-timeout: Specifies the period for which the client API waits for a response for a command from the server. After this period is lapses an "OperationFailedException" is thrown. By default, this time period is 90 seconds and the minimum value is 60 seconds. If a time span is less than the minimum value it will automatically reset to the minimum value, i.e., 60 seconds.

  • connection-timeout: Determines the time period threads wait before throwing OperationFailedException during a connection-break, while one thread tries to establish a connection with the cache server. If the connection is successfully established, then all threads will complete their respective operations. Otherwise, they will throw an OperationFailedException. By default, it is 5 seconds.

  • port: Specifies the port that starts the NCache server and accepts connections from multiple clients. The default value of this port is 9800, which can be changed through the Service Configuration file.

  • local-server-ip: Specifies the IP address of the local server that runs a particular NCache Instance.

  • enable-keep-alive: Specifies whether the connection between the client and server should be kept "alive", i.e., if the client is inactive (not communicating with its connected servers), the client pings the server nodes after fixed intervals per the cache topology. This feature is particularly useful if there is a firewall that breaks idle network connections or if it detects disconnection proactively. By default, it is False.

  • keep-alive-interval: Determines the interval in seconds after which a heartbeat is sent from the idle client to the server to sustain the connection. The interval ranges between 1 and 7200 seconds with default set at 30 seconds. If any value is specified out of the range, NCache resorts to using the default value.

<cache>

This tag defines various settings for both remote and client caches.

<cache id="demoCache" client-cache-id="" client-cache-syncmode="optimistic" default-readthru-provider="" default-writethru-provider="" load-balance="False" enable-client-logs="False" log-level="error">
    <server name="20.200.20.38" is-load-balancer="True"/>
    <server name="20.200.20.23" is-load-balancer="True"/>
  </cache>

  • cache id: Specifies a unique ID to a remote cache.

  • client-cache-id: Specifies a unique ID to the client cache.

  • client-cache-syncmode: Defines the synchronization mode for the client cache. It can be Optimistic or Pessimistic. By default, it is optimistic.

  • skip-client-cache-if-unavailable: Defines whether cache operations are performed on the cluster cache in case of client cache unavailability. By default, it is True.

  • reconnect-client-cache-interval: Specifies the interval in seconds that the client node will wait to try connecting to the client cache again. By default, it is 10 seconds.

  • default-readthru-provider: Gets/Sets the ID of the default-readthru-provider. If the provider is specified through API, this value will be overwritten with the value passed from API.

  • default-writethru-provider: Gets/Sets the ID of the default-writethru-provider. If the provider is specified through API, this value will be overwritten with the value passed from API.

  • load-balance: When this flag is set, the client tries to connect to the optimum server in terms of the number of connected clients. This way an almost equal number of clients are connected to every node in the clustered cache and no single node is overburdened. By default, it is False.

  • enable-client-logs: When this flag is set to True, logs client activities for different purposes. By default, it is False as logging can create an overhead and degrade performance.

  • log-level: This flag helps to define the level of logging that you want to use. It can be set as Info, Debug, or Error as required. By default, it is set to error.

<server>

  • name: Specifies the IP addresses of the servers that run the NCache instance.

  • is-load-balancer: This flag ensures that the client connects to all the machines in the cluster. By default it is False.

Public IP Configuration

If you have subscribed to NCache Cloud and chosen the Public IP connectivity option, you will need to provide these public IP's in the server section of the client.ncconf. This is necessary despite the fact that the cache servers also have private IP's. However, these private IP's are only used within the cache cluster. This is a special situation because normally both the client.ncconf and the config.ncconf use private ips for cache servers.

Note

Please note that the server ips mentioned below are all public ips.

<!-- Please note that the server ips mentioned below are public ips and not private ips -->
<configuration>
  <ncache-server connection-retries="3" retry-connection-delay="0" retry-interval="1" command-retries="3" command-retry-interval="0.1" client-request-timeout="90" connection-timeout="5" port="9800"/>
  <cache id="demoCache" client-cache-id="" client-cache-syncmode="optimistic" default-readthru-provider="" default-writethru-provider="" load-balance="True"  enable-client-logs="False" log-level="error">
    <server name="44.241.59.205" />
    <server name="44.242.59.210" />
  </cache>
</configuration>

Port Forwarding Configuration

Note

If your cache servers and client applications are on the same subnet, you don't need to configure port forwarding.

If your cache servers and clients are on a different subnet or network, your client application might not be able to access your cache servers directly on the basis of IP addresses. In this case, you'll have to configure port forwarding and modify your client.ncconf file accordingly.

Client Config Syntax for Port Forwarding

The client configuration file for port forwarding is explained below.

<configuration>.
...
<server-end-point>
      <end-point public-ip="172.19.0.11" public-ports="9801" private-ip="20.200.20.38" private-ports="9800"/>
      <end-point public-ip="172.19.0.11" public-ports="1250-1260" private-ip="20.200.20.38" private-ports="8250-8260"/>
      <end-point public-ip="172.19.0.11" public-ports="1300-1400" private-ip="20.200.20.38" private-ports="8300-8400"/>
      <end-point public-ip="172.19.0.11" public-ports="9802" private-ip="20.200.20.23" private-ports="9800"/>
      <end-point public-ip="172.19.0.11" public-ports="2250-2260" private-ip="20.200.20.23" private-ports="8250-8260"/>
      <end-point public-ip="172.19.0.11" public-ports="2300-2400" private-ip="20.200.20.23" private-ports="8300-8400"/>
    </server-end-point>
</configuration>

Understanding the Client Config Tags for Port Forwarding

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

<server-end-point>

These represent the endpoints that will be used to communicate with the NCache servers. The following is a sample client.ncconf file with port forwarding configured.

  • end-point: Specifies the end-point of the ncache server. A combination of an IP address and port.

  • public-ip: Specifies address that is publicly accessible or present outside of the local network.

  • public-ports: Specifies the publicports that will be used to access the private ports.

  • private-ip: Specifies address that is present within the local network and is not directly accessible. This is the IP address that is used by the NCache server.

  • private-ports: These are the ports that are not directly accessible. These are the ports used by the NCache server.

See Also

EF Caching Config
Server-side Configurations
Cache Server Settings
General Cache Settings