Configuration Parameters

ScaleOut StateServer’s configuration parameters are held in a text parameters file, called soss_params.txt, in the installation directory on each host. Additional configuration options for the GeoServer Option and for the Remote Client Support component are held in the soss_client_params.txt file, which is also stored in the installation directory. The StateServer service and management tools must have read/write access to both of these files; client applications need to have read access to the soss_client_params.txt file.

Note

ScaleOut In-Memory Database does not support Redis configuration files (redis.conf). You should use only the ScaleOut configuration file on each server to set configuration parameters with the management tools.

On Windows, the installer automatically starts the Management Console to allow you to modify ScaleOut StateServer’s parameters. On Linux, the Web Management Console can be used. Both platforms also offer Command-line Control Programs.

Note

While ScaleOut’s parameter files can be edited directly with a text editor, this is not recommended. Use a ScaleOut management tool whenever possible because this enables changes to global parameters to automatically propagate to all other hosts in the store. If you make changes manually with a text editor, they will not be propagated and could be overwritten by other hosts; you also need to restart the StateServer service for manual changes to take effect.

In most cases, you only have to enter your license key and select the network subnet that the StateServer service will use (using the net_interface and subnet_mask parameters), and this is required only if more than one subnet is available.

License Keys

When you license ScaleOut StateServer, you will receive one of three types of license keys:

• an evaluation key, which lets you run ScaleOut StateServer for a limited period of time (usually thirty days from the date that the key was generated) to evaluate its capabilities,

• a temporary key, which lets you run ScaleOut StateServer for a limited period of time (usually sixty days from the date that the key was generated) while ScaleOut Software awaits confirmation of payment for your perpetual license, and

• a permanent key, which lets you run ScaleOut StateServer without a time limit under a perpetual license.

Evaluation and temporary keys encode the following information:

• the maximum number of server unit licenses that your store can use,

• the maximum software version number that you are licensed to run,

• the expiration date for your temporary license, and

• whether you are licensed to run on hosts with four or more processors.

Permanent keys encode the following information:

• the maximum number of server unit licenses that your store can use,

• the maximum software version number that you are licensed to run,

• whether you have annual maintenance and its expiration date,

• whether you are licensed to run the ScaleOut GeoServer option,

• whether you are licensed to run ScaleOut ComputeServer, and

• whether you are licensed to run ScaleOut hServer.

Note

If you have an annual maintenance contract, you can always use the latest version of ScaleOut StateServer that is released prior to the date that your maintenance contract expires.

The license key must be recorded in the parameters file on all hosts in order for the hosts to create or join a store. When you install a valid, non-expired license key on one host using the management console or the command-line control program, the license key automatically propagates to all hosts in the host group and is stored in the soss_params.txt file on all hosts; offline hosts receive and store the key when they are next started and join the host group. A newly installed license key takes effect immediately on all active hosts without requiriing the host to be restarted.

Note

Starting with version 5.4.4, you can install an older license key to supersede a newer key. For example, you can revert to an older, permanent key after having previously installed a temporary key to test new functionality.

soss_params.txt

Changes to the soss_params.txt file are made independently for each host in an SOSS store. This lets you customize the parameters for each host as necessary. However, certain parameters must be set to the same value on all hosts, and therefore they are automatically updated on all hosts when changed using the management console or command-line control program. These parameters are noted below as “global” parameters.

Note

You should not simultaneously make changes to configuration parameters by running the management tools on different hosts. By doing so, it is possible that multiple hosts could record inconsistent parameter values. Management of ScaleOut StateServer’s configuration should only be done using a single management tool at a time.

Note

If you make changes to global parameters by directly editing the soss_params.txt file, these changes will not be propagated to all hosts. This can lead to inconsistent behavior of the SOSS store.

The configuration parameters are as follows:

net_interface

The net_interface parameter specifies either the IP address or the network subnet that the StateServer service will use to communicate with its peers on other hosts in the farm. All hosts must use the same network subnet. The net_interface is logically AND’ed with the subnet_mask parameter to determine the effective network interface to be used. You can use net_interface to select a specific IP address by setting the subnet mask to 255.255.255.255. You can also allow the StateServer service to select any local IP address on a subnet by setting net_interface and subnet_mask to the subnet’s IP address and network mask values. (For example, setting net_interface to 192.168.1.0 and subnet_mask to 255.255.255.0 would let the service choose any local IP address on the 192.168.1 class C subnet.) Selecting a network subnet instead of a specific IP address is useful when the servers use DHCP or other dynamic means to obtain IP addresses on the subnet. You can set net_interface to 127.0.0.1 to explicitly use the loopback IP address and create a single-host store without the use of a real network interface. Default value: 255.255.255.0 (automatically updated after installation)

Note

For your convenience, the StateServer Management Console automatically lists all available values for net_interface based on the current setting for subnet_mask. You can choose which host subnet to use by selecting the desired value from the pull down list. You can also select 127.0.0.1 to use the looppback address on a single host. Alternatively, you can directly enter the value for net_interface using the soss Command command-line program or by editing the parameters file.

Note

When it first runs after installation (and prior to your setting a value for the net_interface parameter), the StateServer service automatically selects the first available network interface if only one interface is detected. You should review this selection and modify it as necessary before enabling the service to join a store. If a selected network interface cannot be detected (or no interfaces are detected), the loopback address 127.0.0.1 will automatically be used to allow the creation of a single-host store. (The service automatically restarts to use the selected interface.)

subnet_mask

The subnet_mask parameter masks the net_interface parameter to determine the effective network interface, as explained above. If multiple network interfaces on the same subnet match the masked net_interface value, the first interface reported by the operating system will be selected. Default value: 255.255.255.0 (to select a class C address)

use_multicast

The use_multicast parameter selects the mode to be used for discovering other hosts on the network; if set to 1, UDP multicast is used; if set to 0, multicast is disabled and the list of group hosts is used. (global) Default value: 1

Note

Hosts configured for use without multicast will not discover each other and need to be explicitly added to an existing host group using the management commands. Also, a new host configured to use multicast by default will not discover and attempt to join an existing host group that has multicast disabled.

mcast_ip

The mcast_ip parameter selects the multicast IP address that the StateServer service will use to exchange multicast UDP packets with its peers on other hosts in the farm if multicast is enabled using the use_multicast parameter. All hosts must use the same value for mcast_ip. (global) Default value: 224.0.0.17

Note

The default value is chosen from a range of addresses reserved by IANA (www.iana.org) “for the use of routing protocols and other low-level topology discovery or maintenance protocols, such as gateway discovery and group membership reporting. Multicast routers should not forward any multicast datagram with destination addresses in this range.” You should verify that this multicast IP address does not conflict with other devices on the subnet.

int_port

The int_port parameter specifies the TCP port used by the StateServer service to communicate with other hosts. Each host can use a different value for int_port if desired. Default value: 722

Note

The default value has not been reserved for exclusive use by ScaleOut StateServer and could conflict with other applications. Please consult www.iana.org for current IP port assignments.

accept_secure

The accept_secure parameter specifies whether the StateServer service will also accept secure connections encrypted with SSL. If enabled, remote clients and ScaleOut GeoServer connections must also enable use_secure_conn during configuration and specify secure_svr_port and secure_mgt_port instead of svr_port and mgt_port, respectively. (global) Default value: 0 (disabled)

svr_port

The svr_port parameter specifies the TCP port used by the StateServer service to handle local access requests from application programs. Each host can use a different value for svr_port if desired. Default value: 721

Note

The default value has not been reserved for exclusive use by ScaleOut StateServer and could conflict with other applications. Please consult www.iana.org for current IP port assignments.

secure_svr_port

The secure_svr_port parameter specifies the TCP port used by the StateServer service to handle local access requests from application programs for secure connections. This port is used by remote clients if accept_secure is enabled on the host and the remote client is configured with use_secure_conn set to 1. All hosts must use the same value for secure_svr_port. (global) Default value: 724

Note

The default value has not been reserved for exclusive use by ScaleOut StateServer and could conflict with other applications. Please consult www.iana.org for current IP port assignments.

mgt_port

The mgt_port parameter specifies the UDP port used by the StateServer service to optionally exchange multicast UDP packets with other hosts and the TCP port used by the service to handle local management requests from the management console and command-line control program. All hosts must use the same value for mgt_port. (global) Default value: 720

Note

The default value has not been reserved for exclusive use by ScaleOut StateServer and could conflict with other applications. Please consult www.iana.org for current IP port assignments.

secure_mgt_port

The secure_mgt_port parameter specifies the TCP port used by the service to handle local management requests from the management console and command-line control program for secure connections. This port is used by remote clients if accept_secure is enabled on the host and the remote client is configured with use_secure_conn set to 1. All hosts must use the same value for secure_mgt_port. (global) Default value: 723

Note

The default value has not been reserved for exclusive use by ScaleOut StateServer and could conflict with other applications. Please consult www.iana.org for current IP port assignments.

license_key

license_key specifies the license key supplied to you by ScaleOut Software. The same value for license_key must be entered on every host. (This is typically accomplished using the management console after installation.) The license key authorizes you to create a store, and it encodes parameters regarding your software license. ScaleOut StateServer will not create or join a store without a valid license key. (global)

Note

After you have entered the license key for the first host, additional hosts will automatically obtain and record the license key entered for the first host when they detect that host on the subnet. This automatic detection requires that all hosts are correctly configured to use the same mcast_ip and mgt_port parameters. When the StateServer service first starts, it will scan all other hosts on the subnet and automatically obtain a newly entered license key. If you replace the license key on one host with a different, valid key using the management tools, all other hosts will immediately save and switch to the newer key. This is useful when replacing a temporary key with a permanent key.

store_weight

The store_weight parameter specifies the estimated, relative amount of memory that this host would like to use for storing data objects as an input to the load-balancer. Each host can use a different value ranging from 0 to 254. This parameter should not be changed from its default value under most circumstances. For more details, please see the section Load-Balancing. Default value: 100

Note

The store_weight parameter does not set or limit the total amount of memory that the StateServer service allocates to objects on the local host. Also, the load-balancer’s actual usage of this parameter is highly dynamic and should not be relied upon to closely follow these guidelines or deliver specific results.

auto_join

auto_join specifies whether the local host will activate its StateServer service and join the distributed store when the service starts. Accepted values for this parameter are 1 (to indicate TRUE) or 0 (to indicate FALSE). In most cases, this parameter should be set to 1 after verifying that all parameters are correctly configured. Default value: 0

max_memory

The max_memory parameter specifies the maximum amount of memory (in KB) that the StateServer service may use to create objects and object replicas on the local host. If the default value of 0 is specified, the StateServer service will set maximum memory to 90% of the amount of physical memory currently available, and this serves as the upper limit on memory usage regardless of this parameter’s value; this limit is updated every three seconds. If memory usage exceeds the max_memory limit, the StateServer service will not allow new objects to be created in the store. (However, existing objects will continue to be updated and deleted, and object replicas may be created on behalf of other hosts.) ScaleOut StateServer will again allow new objects to be created once memory usage drops down below 90% of the max_memory limit. Default value: 0

Note

The StateServer service consumes approximately 3MB additional memory for its internal data structures, and it uses additional memory for object metadata and due to buffer fragmentation associated with each stored object or replica. The actual number of stored objects and replicas may vary over time due to dynamic load balancing. Be sure to provision ample physical memory so that physical memory is available at all times.

Note

Setting this parameter does not guarantee that memory exhaustion will not occur because the actual amount of physical memory that the operating system makes available to the StateServer service may change after the service starts running. It is important to provision ample physical memory for all applications so that the StateServer service does not run out of physical memory. This situation could seriously impact performance and destabilize the distributed store.

max_cache

The max_cache parameter specifies the maximum amount of cache memory (in KB) that the StateServer service may use to cache recently accessed objects on the local host. If the value 0 is specified, the StateServer service will disable the local host’s cache. Default value: 10000 (10 MB)

Note

With recent optimizations to the client libraries, the server cache is no longer needed, and this parameter is now ignored.

max_client_cache

max_client_cache specifies the maximum amount of cache memory (in KB) that the StateServer .NET/Java/C++ client library may use to cache recently accessed, deserialized objects on the local host. If the value 0 is specified, the StateServer service will disable the client cache. Each application domain has a separate client cache. Default value: 100000 (100 MB)

Note

The max_client_cache parameter is not used by the newer ScaleOut .NET libraries that are delivered as NuGet packages (Scaleout.Client, Scaleout.AspNet, Scaleout.AspNetAsync, and Scaleout.AspNetCore).

These newer libraries do not require an installation of the ScaleOut Product Suite and are configured through standard .NET config files. See the documentation in the NuGet package links above for details.

max_replicas

The max_replicas parameter specifies the maximum number of additional replica objects that the StateServer service may create when a new object is stored. Allowed values are 1 and 2. Note that all SOSS hosts must use the same value. If a host attempts to join the store with a different value, this parameter will be ignored, and the host will switch to the value currently in use by other joined SOSS hosts. (global) Default value: 1 (i.e., two copies of each object in total are stored)

net_perf_factor

net_perf_factor specifies the network’s expected performance available to the StateServer service as an abstract value that ranges from 0 to 100. Higher values indicate that the network is less congested and less susceptible to transient network delays. This parameter is used to adapt ScaleOut StateServer for use on heavily congested networks by adjusting ScaleOut StateServer’s sensitivity to transient delays. (Network congestion can block heartbeat messages, and ScaleOut StateServer interprets this as a remote server’s outage.) If auto_npf is disabled, it may be necessary to adjust this parameter upwards or downwards as needed to maintain fast recovery after server failures while avoiding unnecessary membership changes, especially when running ScaleOut StateServer within a virtual server running on a heavily loaded physical server. (global) Default value: 10 (suitable for highly congested networks or initial evaluation)

Note

Lower values for this parameter increase the time required by ScaleOut StateServer to identify a server or network outage. Raising this parameter on a congested network could destabilize the store’s membership and should be made with care.

Note

When running ScaleOut StateServer on physical servers attached to a high performance gigabit switch, setting net_perf_factor to 100 will provide the fastest recovery after a server failure.

auto_npf

The auto_npf parameter specifies whether the StateServer service will dynamically adjust net_perf_factor based on real-time heuristic performance measurements. If enabled, the StateServer service samples heartbeat delays for 24 hours before raising net_perf_factor to the lowest value recommended by all hosts, and it lowers net_perf_factor immediately upon experiencing a server outage. These changes are recorded in the soss_params.txt file on all hosts. (global) Default value: 1 (enabled)

startup_delay

startup_delay specifies the delay (in seconds) during the StateServer’s service startup before connecting to the network (0-255). Default value: 5

max_event_tries

The max_event_tries parameter specifies the maximum number of times that the StateServer service will attempt to deliver an object’s event to the local client application before removing the object. The service attempts to deliver the event once per minute. This parameter is used to allow a client application to terminate and restart without losing objects in case events could not be delivered. Higher values will increase object lifetimes. (global) Default value: 1

factory_param

factory_param specifies a parameter value provided by ScaleOut Software. This parameter encodes internal settings that may need to be adjusted in some installations; it must always be set to the same value on all hosts in the distributed store. The default value should not be changed except as directed by ScaleOut Software. (global) Default value: 0

lru_threshold

The lru_threshold parameter specifies the percentage of the maximum memory allocated to the StateServer service on the local host that must be in use before object reclamation is triggered. Once the StateServer service has allocated this amount of memory to store objects, the least recently accessed objects that are marked as reclaimable will be removed as needed to keep memory consumption below the specified threshold. Object reclamation is concurrently triggered on all store hosts when any host reaches the threshold. The default value disables LRU object reclamation. Note that the maximum memory allocated to the StateServer service is determined by the max_memory parameter. (global) Default value: 100

Note

ASP.NET session objects are subject to reclamation.

repl_threshold

(ScaleOut GeoServer only) The repl_threshold parameter specifies the percentage of the maximum memory allocated to the StateServer service on the local host that must be in use before outbound data replication is suspended. Once the StateServer service has allocated this amount of memory, data replication will be suspended and memory used for buffering outbound objects awaiting replication will be removed as needed to keep memory consumption below the specified threshold. The suspension of data replication is concurrently triggered on all store hosts when any host reaches the threshold. Note that the maximum memory allocated to the StateServer service is determined by the max_memory parameter. (global) Default value: 60

Note

If GeoServer replication is suspended due to reaching this memory threshold, object updates to remote stores will be permanently lost. These updates will not be completed when memory has been released and data replication resumes.

gateway_ip

(ScaleOut GeoServer only) The gateway_ip parameter specifies the local host’s gateway IP address for inbound data replication to the local SOSS store. This value specifies the IP address that remote SOSS stores should use to connect to this SOSS host to send it replicated data. The gateway IP address should be reachable from remote stores using a virtual private network or other secure communications channel to connect to the local SOSS store. The default value (255.255.255.255) specifies that the gateway IP address is the same as the local host’s effective network interface; this is useful when DHCP is used to dynamically determine the host’s network interface. Otherwise, a static IP address can be supplied for this parameter, or the value 0 can be used to disable the gateway address. Default value: 255.255.255.255

gateway_port

(ScaleOut GeoServer only) The gateway_port parameter specifies the local host’s gateway server port for inbound data replication to the local SOSS store. This value specifies the TCP port that remote SOSS stores should use to connect to this SOSS host to send it replicated data. The gateway port should be reachable from remote stores using a virtual private network or other secure communications channel to connect to the local SOSS store. Default value: 721

Note

Each host’s gateway IP address and port values are communicated to all remote stores that connect to the local SOSS store to deliver replicated data. The gateway IP address may be on a different subnet from the host’s network interface. It is necessary that that remote SOSS stores be able to reach the local host’s server port using the specified gateway IP address and port combination. All hosts in the local SOSS store must have different gateway addresses (i.e., gateway IP address and port combinations). The gateway port must not be firewalled.

geos_local_name

geos_local_name specifies the name of the local store for use by ScaleOut GeoServer to access objects from remote stores. Default value: NULL

group_host

The group_host parameter specifies the IP address of a host to be polled to determine whether an SOSS store is active on this host; more than one group host can be specified. When the use_multicast parameter is set to 0, these IP addresses are used to discover other SOSS hosts as an alternative to multicast discovery. (global)

query_index_mode

query_index_mode specifies the mode to be used for indexing metadata used in query searches. When set to 0, no query indexing is used; when set to 1, query indexing is optimized for querying by index values; when set to 2, query indexing is optimized for querying by object property values. (global) Default value: 2 (optimize for property-based queries)

hash_tbl_factor

The hash_tbl_factor specifies a multiplier for the size of the hashtable that is used internally by the SOSS service for tracking object storage. Values in the range of 1 to 4 are valid. A higher value can increase throughput for large numbers of objects but will require additional memory in the SOSS service. (global) Default value: 1 (suitable for datasets with up to 1 million objects per SOSS host)

lock_timeout

lock_timeout specifies the timeout value in seconds for object locks. Values in the range of 10 to 120 seconds are valid. (global) Default value: 90 (for compatibility with ASP.NET)

disable_perf_ctrs

The disable_perf_ctrs parameter disables collection of data for performance counters to reduce overhead. Allowed values are 0 and 1. (global) Default value: 0 (performance counters are enabled)

disable_lstats

The disable_lstats parameter disables collection of latency statistics to reduce overhead. Allowed values are 0 and 1. (global) Default value: 0 (latency statistics are enabled)

disable_vmstats

The disable_vmstats parameter disables collection of VMWare statistics in case an incompatibility arises that impacts behavior or performance. Allowed values are 0 and 1. (global) Default value: 0 (VM statistics are enabled)

disable_allcontig

The disable_allcontig parameter disables the use of heap-based memory allocation for large objects and reverts to the buffer-based memory allocation technique used by version 5.4 and earlier. This parameter should not be required other than to minimize the number of calls to heap allocation. Allowed values are 0 and 1. A global restart should be performed after changing this parameter. (global) Default value: 0 (contiguous, heap-based memory allocation is enabled)

enable_geosopt

The enable_geosopt parameter enables the use of ScaleOut GeoServer optimizations that can accelerate replication to a remote store running version 5.5 or higher. These optimizations are disabled by default to maintain compatibility with remote stores running version 5.4 and lower. Allowed values are 0 and 1. (global) Default value: 0 (ScaleOut GeoServer optimizations are disabled.)

Note

The net_interface, subnet mask, mcast_ip, svr_port, or mgt_port parameters can only be changed when the StateServer service on the corresponding host is inactive, and the service must be restarted for the changes to take effect. If you change these parameters using the management console or the command-line control program, the service is automatically restarted.

Note

The mcast_ip and mgt_port parameters must have the same value on all hosts. Changing these parameters requires that the distributed store be fully restarted.

disable_pings

Each ScaleOut StateServer host periodically sends short messages to all other hosts to measure network latency. The disable_pings parameter disables this functionality to conserve network bandwidth. Allowed values are 0 and 1. (global) Default value: 0 (Network pings are enabled.)

enable_statslog

The enable_statslog parameter enables logging of periodic network ping measurements to the soss_stats_log0.txt file in the installation folder. When this file reaches its maximum allowed size, its contents are copied to soss_stats_log1.txt, and the file is cleared. Accumulated statistics are reset approximately every six hours. Allowed values are 0 and 1. (global) Default value: 0 (Statistics logging is disabled.)

Note

Network ping latency can be affected by load on the servers. High server load can increase ping latency due to additional delay in handling ping requests.

ignore_key_appid

When true, specifies that the service should not use an object key’s application identifier (its cache/namespace membership) when selecting a location for an object. Setting this value to true allows objects with the same key to be stored on the same server even if they belong to different named caches. Default value: false.

soss_client_params.txt

Additional Parameters for the GeoServer Option

If you have licensed the ScaleOut GeoServer option, the parameters describing remote ScaleOut StateServer stores to which data will be replicated are stored in a separate parameters file called soss_client_params.txt. This file is stored in the installation directory and is accessed and updated by the StateServer service. This file may separately be used by the optional Remote Client option for remote client access. It is never used by both components at the same time.

Unlike the file soss_params.txt, whose contents may differ on each host in an SOSS store, the soss_client_params.txt must be identical on all hosts. This ensures that all hosts can uniformly participate in replicating data to remote stores. Whenever an update is made to the soss_client_params.txt file using the management tools described in the Introduction to Management section, the update is also sent to all hosts (active or inactive) within the store. Likewise, when the StateServer service starts running, it checks the other hosts for a later version of this parameters file and updates its local file if necessary.

Note

Versioning information is kept in the soss_client_params.txt file to ensure that all hosts always have the latest updates to the file. You should not directly edit this file; please use the management tools instead.

Step-by-step instructions for configuring the GeoServer option can be found in the section Configuring the GeoServer Option.

Additional Parameters for Local and Remote Clients

The soss_client_params.txt file contains additional configuration parameters used by local clients, remote clients (licensed using the ScaleOut Remote Client option), and the ScaleOut GeoServer option. If you have licensed the ScaleOut Remote Client option, the parameters describing the remote ScaleOut StateServer store to which the remote client will connect are stored in this configuration file, which is stored in the installation directory and is accessed and updated by the Remote Client libraries. This file may separately be used by the GeoServer option to hold configuration information for replication to remote stores. It is never used by both components at the same time.

Note

The soss_client_params.txt file is not used by the newer ScaleOut .NET libraries that are delivered as NuGet packages (Scaleout.Client, Scaleout.AspNet, Scaleout.AspNetAsync, and Scaleout.AspNetCore).

These newer libraries do not require an installation of the ScaleOut Product Suite and are configured through standard .NET config files. See the documentation in the NuGet package links above for details.

Step-by-step instructions for configuring the Remote Client option can be found in the section Configuring the Remote Client Option.

In addition, the soss_client_params.txt file contains the following configuration parameters used by local and remote clients:

max_lcl_retries

max_lcl_retries specifies the maximum number of retries that a local client will make to connect to an SOSS server or to retry a request once connected. Values from 0 to 100 are allowed. Note that each request takes approximately one second. Default value: 30

Note

This parameter should be set using the soss Command command-line program so that it will be automatically propagated to all SOSS servers for use by all local clients. This parameter is ignored by remote clients.

max_rem_retries

The max_rem_retries parameter specifies the maximum number of retries that a remote client will make to connect to an SOSS server or to retry a request once connected. Values from 0 to 100 are allowed. Note that each request takes approximately one second. Default value: 2

Note

This parameter should be set using the soss Command command-line control program. However, its value is not propagated to other servers. This parameter is ignored by local clients.

max_access_time

max_access_time specifies the maximum time in seconds that a client will use to make an access request to an SOSS server. Values from 0 to 255 are allowed, and a value of 0 disables this parameter. If the maximum access time is exceeded, the current access request is aborted, the client’s connection to the server is closed, and an exception is returned to the caller. Default value: 0

Note

This parameter should be set using the soss Command command-line control program. However, its value is not propagated to other servers.

Note

This parameter is used separately for each network request to the server, and multiple network requests may be needed to complete a client access. Hence, the total access time observed by the requesting client may exceed the value supplied in this parameter.

Note

Access times are typically lengthened during membership changes, load-balancing, and recovery from failures. Setting max_access_time to a very low value (e.g., 1 second) can result in a large number of exceptions; consider starting with a value of 5 seconds or higher until experience with this parameter is gained.

not_ready_timeout

not_ready_timeout specifies the maximum amount of time (in seconds) that a client will spend retrying add/update operations if the ScaleOut service is low on memory (or reports that it is otherwise not ready to handle the request due to heavy load or environmental delays). A value of 0 (zero) disables the retry behavior, in which case a not-ready or low-memory exception may be thrown immediately from an add/update call. Default: 2 seconds.

max_svr_conn

The max_svr_conn parameter specifies the maximum number of server connections that the client can use to connect to each SOSS server. Values from 2 to 32 are allowed. Higher values enable a client application to achieve higher access throughput, especially when performing bulk inserts. However, when many remote clients are used, care should be taken to avoid allowing too many TCP connections from the clients to each SOSS server. Default: 4

Note

In previous releases, the fixed, default value was set to 2.

use_secure_conn

use_secure_conn specifies whether the client (or ScaleOut GeoServer) will use secure connections encrypted with SSL for each SOSS server when connecting to an on-premise (i.e., not cloud-hosted) store. The SOSS store must also be configured with accept_secure enabled. If enabled, the client must also specify the host’s secure_svr_port and secure_mgt_port instead of svr_port and mgt_port, respectively. Default: 0 (disabled)

Note

This parameter also specifies the remote client or remote GeoServer store. It should only be set using the management tools.

Note

When connecting to a cloud-hosted store, the use of secure connections is specified by an attribute in the connection string generated by the management tools.

br_timeout

The br_timeout parameter specifies the maximum allowed time (in minutes) for backup/restore operations. Values from 0 to 255 are allowed; 0 indicates an indefinite timeout. Default: 60

notify_config

The notify_config parameter configures the Java Named Cache client to use the ScaleOut GeoServer Pro notify coherency policy in pull access mode for a selected remote store and cache name. This avoids the need to perform the corresponding configuration steps within application code.

The parameter has the form:

<remote_store_name>, <cache_name>, 0|1

where 0 indicates that this directive will not override settings in application code, and 1 indicates that existing application-defined settings will be overwritten to configure the selected name space for pull mode with the notify coherency policy. All objects created in this named cache will be configured to use the notify coherency policy, allow remote access, and allow replication. In addition, the server will be notified to allow remote access to the specified remote store for this named cache.

Note

ScaleOut GeoServer Pro pull access mode must also be configured for the specified remote store using the management commands. To learn more about the ScaleOut GeoServer Pro pull access mode, please consult the section GeoServer Option.

stats_interval

The stats_interval parameter specifies the interval (in hours) for logging latency statistics. Values from 0 to 255 are allowed; 0 disables tracking latency statistics. Default: 6

ASP.NET Session Provider

Note

The settings discussed in this section only apply to the ASP.NET session provider that ships with the ScaleOut Product Suite installer. ScaleOut also offers newer session providers that are available as NuGet packages:

• Scaleout.AspNet

• Scaleout.AspNetAsync

• Scaleout.AspNetCore

These newer libraries do not require an installation of the ScaleOut Product Suite and are configured through standard .NET config files. See the documentation in the NuGet package links above for details.

soss_SharedAppName

By default, ScaleOut StateServer does not share session objects between multiple ASP.NET applications. If session data needs to be shared across two or more applications, then the soss_SharedAppName setting can be added to each application’s web.config file. This setting specifies a common application name space that ScaleOut StateServer will use for storing ASP.NET session objects, and it overrides ScaleOut StateServer’s default use of the Web application’s name for this purpose. For example, all ASP.NET applications that need to share session objects in the name space called MyName should add the following lines to web.config:

 <configuration>
   <appSettings>
     <add key="soss_SharedAppName" value="MyName"/>
   </appSettings>
 <!-- ... -->
 </configuration>

soss_SessionPreemptionPriority

ScaleOut StateServer marks ASP.NET session objects as subject to memory reclamation on a least recently used basis if memory consumption reaches the parameterized limit set by the lru_threshold parameter. You can override this behavior and make session objects immune from memory reclamation by adding the setting soss_SessionPreemptionPriority with the value NotRemovable to each application’s web.config file, as follows:

 <configuration>
   <appSettings>
     <add key="soss_SessionPreemptionPriority" value="NotRemovable"/>
   </appSettings>
 <!-- ... -->
 </configuration>

By default, this setting has the value Normal, which allows for memory reclamation of the application’s session objects.

soss_RegisterForEvents

ScaleOut StateServer’s session provider will automatically register for expiration events in order to fire a web application’s Session_End event in Global.asax. To prevent this registration and stop events from being delivered to Session_End, add the setting soss_RegisterForEvents with the value False to the application’s web.config file, as follows:

 <configuration>
   <appSettings>
     <add key="soss_RegisterForEvents" value="False"/>
   </appSettings>
 <!-- ... -->
 </configuration>

This option is useful, for example, when event handling is handled by local clients instead of by Web servers running as local clients.

soss_ClientCachePartitionCount

ScaleOut StateServer’s session provider uses a fully coherent, in-process client cache to reduce serialization and network overhead. This in-process cache is split up into a number of internal partitions—more partitions allow more threads in a client application to access this near cache concurrently. Use the soss_ClientCachePartitionCount setting in the application’s configuration file to adjust the number of partitions, as follows:

 <configuration>
   <appSettings>
     <add key="soss_ClientCachePartitionCount" value="8"/>
   </appSettings>
 <!-- ... -->
 </configuration>

More partitions will slightly reduce the accuracy of the the client cache’s least-recently-used (“LRU”) eviction algorithm when memory pressure on the cache is high in a client process. Values in the range of 1 to 1000 are valid, and a value of “auto” will set the count to 50 partitions per logical processor. The default value is 1.

Tip

The default value of 1 is sufficient for most ASP.NET session state workloads—the client cache will typically only experience concurrency bottlenecks when under very heavy workloads on systems with a large number (16+) of CPU cores performing over 100,000 reads/sec. Users who perform heavy data analysis using ScaleOut’s Parallel Method Invocation feature, for example, may benefit from setting the soss_ClientCachePartitionCount to “auto”.

soss_RemoteStoreName

The ScaleOut ASP.NET session provider allows session objects to be created with a notify coherency policy for ScaleOut GeoServer Pro. When two ScaleOut StateServer stores are configured for bi-directional pull replication using ScaleOut GeoServer Pro, this enables object updates to be replicated between both stores while allowing synchronized access to the objects. Use the soss_RemoteStoreName setting in the application’s configuration file to specify the remote store to which session objects will be replicated:

 <configuration>
   <appSettings>
     <add key="soss_RemoteStoreName" value="NewYork"/>
   </appSettings>
 <!-- ... -->
 </configuration>

ASP.NET Output Cache Provider

Configuration Settings

ScaleOut’s ASP.NET Output Cache Provider allows you to use your ScaleOut StateServer data grid to store ASP.NET output cache data when using ASP.NET 4.0 or higher. This custom provider is enabled by adding it to the <providers> element in your web.config’s <outputCache> element. For example:

<caching>
  <outputCache defaultProvider="SossOutputCacheProvider">
    <providers>
      <add name="SossOutputCacheProvider"
           type="Soss.Web.SossOutputCacheProvider, soss_storeprovider, Version=5.0.0.0, Culture=neutral, PublicKeyToken=a1ec0b86f746a476"
           namespace="MyName"
           throwOnError="false"
           sossAccessTimeoutMilliseconds="250" />
    </providers>
  </outputCache>
</caching>

The provider supports the following configuration settings:

name

(Required.) The name attribute is the user-friendly identifier for the custom ScaleOut Output Cache Provider. This ID is used by the <outputCache> element’s defaultProvider attribute to reference the ScaleOut provider.

type

(Required.) The type attribute must always be set to the string listed in the example above:

Soss.Web.SossOutputCacheProvider, soss_storeprovider, Version=5.0.0.0, Culture=neutral, PublicKeyToken=a1ec0b86f746a476

namespace

(Optional.) By default, ScaleOut StateServer does not share output cache entries between multiple ASP.NET applications. If output cache entries needs to be shared across two or more applications then the namespace attribute can be used to enable sharing. This attribute specifies a common application name space that ScaleOut StateServer will use for storing ASP.NET output cache entries, and it overrides ScaleOut StateServer’s default use of the app’s path in the IIS metabase for this purpose.

For example, all ASP.NET applications that need to share output cache entries in the name space called MyName can set the namespace attribute to “MyName” in order to access each other’s entries.

throwOnError

(Required.) If an error occurs when accessing the ScaleOut StateServer service (for example, if a network problem prevents a web server from accessing the ScaleOut data grid) then setting the throwOnError attribute to "true" will cause the ScaleOut Output Cache provider to raise an exception that causes the HTTP request to fail. Setting the throwOnError attribute to "false" will prevent exceptions from being thrown from the provider, and the provider will simply inform ASP.NET pipeline that the requested output cache entry does not exist. The resulting “cache miss” will cause ASP.NET to execute the full request handler instead.

Tip

Suppressing exceptions should be done with care, when you are certain that circumventing the output cache is more desirable than handling an error or displaying an error message to your users. If you do suppress exceptions, be sure to use the Output Cache Instrumentation features to ensure that errors do not go unnoticed by your site’s administrators.

sossAccessTimeoutMilliseconds

(Required.) The sossAccessTimeoutMilliseconds attribute specifies the maximum time (in milliseconds) that the Output Cache Provider will wait to receive a response from the ScaleOut data grid. If the timeout is elapsed, the provider will simply inform the ASP.NET pipeline that the output cache entry does not exist, and the resulting “cache miss” will cause ASP.NET to execute the full request handler instead. A value of 0 will cause the provider to wait indefinitely, causing the web request to be blocked until a result is returned.

Setting a timeout can be useful when re-running your handler is preferable to waiting for a result (or an error). For example, it can take several seconds for an error to occur if the ScaleOut data grid becomes unreachable, so you may choose to use this attribute to bypass output caching instead of waiting. A value of 250 milliseconds is a reasonable timeout for most situations—it is more than enough time for almost any ScaleOut accesses, but allows you to fall back to your request handler to maintain site availability in case of a slowdown or a problem.

Tip

Bypassing the output cache with the sossAccessTimeoutMilliseconds can mask serious problems in your environment. If you do use this attribute, be sure to use the Output Cache Instrumentation features to ensure that timeouts do not go unnoticed by your site’s administrators.

Output Cache Instrumentation

Performance Counters

The following Windows performance counters are available under the ScaleOut Output Cache Provider counter group in Perfmon. They can be used to track the health and effectiveness of the ScaleOut Output Cache provider:

Output Cache Hits/sec

The rate of output cacheable requests that were served from the output cache.

Output Cache Misses/sec

The rate of output cacheable requests that were not served from the output cache.

Output Cache Additions/sec

The number of additions to the output cache per second.

Output Cache Timeouts/sec

The rate of output cache timeouts per second. Timeouts occur when the time to access the ScaleOut StateServer service exceeds the ScaleOut provider’s sossAccessTimeoutMilliseconds threshold set in web.config.

Output Cache Errors/sec

The rate of output cache errors per second, typically caused by problems accessing the ScaleOut StateServer data grid.

Tracing

In addition to performance counters, the output cache provider can perform event tracing if detailed information is needed. The provider implements a standard .NET trace source that is named SossOutputCacheProvider, allowing you to log diagnostic information to the trace listener of your choosing. For example, to configure a listener that logs all output cache warnings and errors to a file called “SossOutputCache.log”, you would add the following section to your web.config file:

<system.diagnostics>
  <sources>
    <source name="SossOutputCacheProvider"
            switchName="outputCacheSwitch"
            switchType="System.Diagnostics.SourceSwitch">
      <listeners>
        <add name="textFileListener"
             type="System.Diagnostics.TextWriterTraceListener"
             initializeData="C:\MyTraces\SossOutputCache.log" />
        <remove name="Default" />
      </listeners>
    </source>
  </sources>
  <switches>
    <add name="outputCacheSwitch" value="Warning" />
  </switches>
  <trace autoflush="true"/>
</system.diagnostics>

Tip

The .NET Framework provides several trace listeners, including an EventLogTraceListener that can write to the Windows Event Log. Additionally, the Essential Diagnostics project on CodePlex offers a wide variety of listeners that can meet most organizations’ instrumentation needs.

The output cache’s trace source offers support for the following trace switch levels:

Error

Records information about errors that occur in the output cache provider, even if the provider’s throwOnError attribute is set to false in web.config. A full stack trace of each exception is sent to the trace listener.

Warning

Records timeouts that occur in the output cache if the sossAccessTimeoutMilliseconds attribute is configured in web.config and the threshold is hit. Errors are also recorded at this switch level.

Verbose

Traces every access to the ScaleOut data grid by the output cache provider. Warnings and errors are also traced. This switch level should only be used during development due to the large amount of trace information that is produced.