ScaleOut Product Suite Help
Installation

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. 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. Alternatively, you can directly enter the value for net_interface on the command line using soss.exe (see Command-line Control Programs) 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 more than one network interface is detected (or no interfaces are detected), the management tools display the loopback IP address, 127.0.0.1, for the local host’s identifier and will not join the store until you select a network interface. (The service automatically restarts to use the selected interface.)

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)

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.

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.

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.

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)

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.

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.

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.

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

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

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.

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 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)

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

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 specifies the delay (in seconds) during the StateServer’s service startup before connecting to the network (0-255). Default value: 5

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

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.

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

(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

(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 specifies the name of the local store for use by ScaleOut GeoServer to access objects from remote stores. Default value: NULL

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 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)

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 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)

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)

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)

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)

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)

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.

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.exe command-line program (see Command-line Control Programs) so that it will be automatically propagated to all SOSS servers for use by all local clients. This parameter is ignored by remote clients.

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.exe command-line control program. However, its value is not propagated to other servers. This parameter is ignored by local clients.

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

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

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

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

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>

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.

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.

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

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:

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:

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: