Server properties file

The server properties file contains several properties that define different settings for your server, such as trace settings, logging, and security configuration. The server properties file is used by both catalog service and container servers in both stand-alone servers and servers that are hosted in WebSphere® Application Server.

Sample server properties file

You can use the sampleServer.properties file that is in the wxs_home/properties directory to create your properties file.

Specifying a server properties file

Specifying a setting by using one of the items later in the list overrides the previous setting. For example, if you specify a system property value for the server properties file, the properties in that file override the values in the objectGridServer.properties file that is in the class path.

Server properties

General properties
diskOverflowCapBytes
Specifies the maximum amount of disk space that is used by this server for disk overflow, in bytes. The default value specifies that there is no limit on how much is stored on disk.

Default: Long.MAX_VALUE

diskStoragePath
Specifies the absolute path to a directory location used for storing overflow content.
diskOverflowMinDiskSpaceBytes
Specifies that entries are not moved to disk if there is less than this amount of space free in diskStoragePath, in bytes.

Default: 0

diskOverflowEnabled
Enables the native overflow disk feature. You must enable eXtreme Memory for this feature to work.

Default: false

enableMBeans
Enables ObjectGrid container Managed Beans (MBean). This property applies to both the container server and the catalog service.

Default: true

exitJVMOnTeardown
Specifies whether the JVM is also stopped when the eXtreme Scale server is stopped in an OSGi framework. By default, the JVM continues to run when each server in an OSGi framework is stopped in the xscmd utility with the -c teardown command. If you want to stop the JVM as well, set this property to true.

Default: false

haManagerPort
Specifies the port that is used by the high availability (HA) manager for heartbeat communication between peer container servers. The haManagerPort port is only used for peer-to-peer communication between container servers that are in same domain. If the haManagerPort property is not defined, then an ephemeral port is used. In WebSphere Application Server, this setting is inherited by the high availability manager port configuration.

Default: A dynamic port is chosen.

JMXConnectorPort
Defines the Secure Sockets Layer (SSL) port to which the Java™ Management Extensions (JMX) service binds. Only required if an SSL transport protocol is needed for JMX data.
JMXServicePort
Required only for WebSphere eXtreme Scale in a stand-alone environment. Specifies the port number on which the MBean server listens for communication with Java Management Extensions (JMX).

Default: 1099

jvmStatsFileName
Specifies the file name of the CSV statistics file for the JVM.

Default: jvmstats

jvmStatsLoggingEnabled
When set to true, enables log data for the JVM to be written to a CSV file.

Default: true

jvmStatsWriteRate
Specifies the write rate of the CSV statistics files for the JVM in writes per second.

Default: 10

listenerHost

Specifies the host name to which the Object Request Broker (ORB) transport protocol binds for communication. The value must be a fully qualified domain name or IP address. If your configuration involves multiple network cards, set the listener host and port to the IP address for which to bind. By setting the listener and host port, it allows the transport mechanism in the JVM know which IP address to use. If you do not specify which IP address to use, symptoms such as connection timeouts, unusual API failures, and clients that seem to hang can occur.

listenerPort (catalog server)
Specifies the port number to which the Object Request Broker transport protocol binds for communication.

Default: 2809

Note: When a data grid server is run inside and the ORB transport protocol is being used, another port ORB_LISTENER_ADDRESS must also be opened. The BOOTSTRAP_ADDRESS port forwards requests to this port.
listenerPort (container server)
Specifies the port number to which the ORB transport protocol binds for communication.

Default: An ephemeral port is chosen.

Note: When a data grid server is run inside WebSphere Application Server and the ORB transport protocol is being used, another port ORB_LISTENER_ADDRESS must also be opened. The BOOTSTRAP_ADDRESS port forwards requests to this port.
listenerPort (client)
Specifies the port number to which the ORB transport protocol binds for communication. This setting configures the client to communicate with the catalog and container service. If a listener is not configured with the ORB transport protocol, an ephemeral port is chosen at startup. This port can vary each time the client application is started.

Default: An ephemeral port is chosen.

Note: When a data grid client is run inside WebSphere Application Server and the ORB transport protocol is being used, another port ORB_LISTENER_ADDRESS must also be opened. The BOOTSTRAP_ADDRESS port forwards requests to this port.
mapStatsFileName
Specifies the file name of the CSV statistics file for the map.

Default: mapstats

mapStatsLoggingEnabled
When set to true, enables log data for the maps on the server to be written to a CSV file.

Default: true

mapStatsWriteRate
Specifies the write rate of the CSV statistics files for the map in writes per second.

Default: 10

maxJVMStatsFiles
Indicates the maximum number of CSV statistics files that are generated for the JVM.

Default: 5

maxJVMStatsFileSize
Indicates the maximum file size, in megabytes, of the CSV statistics files for the JVM.

Default: 100

maxMapStatsFileSize
Indicates the maximum file size, in megabytes, of the CSV statistics files for the map.

Default: 100

maxOGStatsFiles
Indicates the maximum number of CSV statistics files that are generated for the ObjectGrid instance.

Default: 5

maxOGStatsFileSize
Indicates the maximum file size, in megabytes, of the CSV statistics files for the ObjectGrid instance.

Default: 100

maxMapStatsFiles
Indicates the maximum number of CSV statistics files that are generated for the map.

Default: 5

maxThreads
Specifies the maximum number of threads that are used by the internal thread pool in the run time for built-in evictor and DataGrid operations.

Default: 50

minThreads
Specifies the minimum number of threads that are used by the internal thread pool in the run time for built-in evictor and DataGrid operations.

Default: 10

ogStatsFileName
Specifies the file name of the CSV statistics file for the ObjectGrid instance.

Default: ogstats

ogStatsLoggingEnabled
When set to true, enables log data for the ObjectGrid instance on the server to be written to a CSV file.

Default: false

ogStatsWriteRate
Specifies the write rate of the CSV statistics files for the ObjectGrid instance in writes per second.

Default: 10

serverName
Sets the server name that is used to identify the server. This property applies to both the container server and the catalog service.
systemStreamToFileEnabled
Enables the container to write the SystemOut, SystemErr, and trace output to a file. If this property is set to false, output is not written to a file and is instead written to the console.

Default: true

traceFile

Specifies a file name to write trace information. This property applies to both the container server and the catalog service.

Example: ../logs/c4Trace.log

Restriction: The traceFile property is not supported in the Liberty profile.
traceSpec
Enables trace and the trace specification string for the container server. Trace is disabled by default. This property applies to both the container server and the catalog service. Examples:
  • ObjectGrid=all=enabled
  • ObjectGrid*=all=enabled
Restriction: The traceSpec property is not supported in the Liberty profile.
workingDirectory
Specifies the location to where the container server output is written. When this value is not specified, the output is written to a log directory within the current directory. This property applies to both the container server and the catalog service.

Default: No value is defined.

zoneName
Set the name of the zone to which the server belongs. This property applies to both the container server and the catalog service.
Container server properties
catalogServiceEndPoints
Specifies the end points to connect to the catalog service domain. This value must be in the form host:port,host:port. The host value is the listenerHost value and the port value is the listenerPort value of the catalog server. This property applies to a container server only.
enableXM
When set to true, enables IBM® eXtremeMemory on the server and configures the server to use IBM eXtremeIO for synchronous and asynchronous replication. Cache entries for maps that are compatible with eXtremeMemory are stored in native memory instead of on the Java heap. All container servers in the data grid must use the same value for the enableXM property.

Default:false

maxXIONetworkThreads
Sets the maximum number of threads to allocate in the eXtremeIO transport network thread pool.

Default:50

maxXIOWorkerThreads
Sets the maximum number of threads to allocate in the eXtremeIO transport request processing thread pool.

Default:128

maxXMSize
Sets the maximum amount of memory, in megabytes, used by the server for eXtremeMemory storage.

Default: 25% of the total memory on the system.

memoryThresholdPercentage
Sets the memory threshold for memory-based eviction. The percentage specifies the maximum heap to be used in the Java virtual machine (JVM) before eviction occurs. The default value is -1, which indicates that the memory threshold is not set. If the memoryThresholdPercentage property is set, the MemoryPoolMXBean value is set with the provided value. For more information, see MemoryPoolMXBean interface in the Java API specification. However, eviction occurs only if eviction is enabled on an evictor. To enable memory-based eviction, see Plug-ins for evicting cache objects. This property applies to a container server only.

Default:-1

minXIONetworkThreads
Sets the minimum number of threads to allocate in the eXtremeIO transport network thread pool.

Default:50

minXIOWorkerThreads
Sets the minimum number of threads to allocate in the eXtremeIO transport request processing thread pool.

Default:128

statsSpec
Specifies the statistics specification for the container server.

Examples:

all=disabled: Disables all statistics.

all=enabled: Enables all statistics.

For more information about enabling statistics, see Enabling statistics.
xioChannel.xioContainerTCPNonSecure.Port
Deprecated feature Deprecated: This property is deprecated. The value that is specified by the listenerPort property is used instead.
Specifies the non-secure listener port number of eXtremeIO on the server. If you do not set the value, an ephemeral port is used. This property is used only when the transportType property is set to TCP/IP.
Restriction: The xioChannel.xioContainerTCPNonSecure.Port property is not supported in the Liberty profile.
xioChannel.xioContainerTCPSecure.Port
Deprecated feature Deprecated: This property is deprecated. The value that is specified by the listenerPort property is used instead.
Specifies the SSL port number of eXtremeIO on the server. This property is used only when the transportType property is set to SSL-Supported or SSL-Required.
Catalog service properties
[Version 8.5 and later] allowableShardOverrage
Specifies the allowable percentage in the number of container servers that one zone can have below another zone in a multi-zone deployment. If the percentage of catalog servers in one zone versus another zone is above the specified value, the catalog service attempts to move all replica shards from the unassigned to an assigned state. The replica shards are moved into a container server in the catalog service domain. Primary shards are always placed. For example, the allowableShardOverrage value is set to 0.75 (75 percent). If a zone has two containers, and another zone has three containers, the percentage of the container servers between the zones is 2/3 (67 percent). Because this percentage is less than the allowableShardOverrage valued of 75 percent, not all the replicas for the data grid are necessarily placed.
catalogClusterEndPoints
For stand-alone configurations only. Specifies a list of catalog service domain end points for the catalog service. This property specifies the catalog service end points to start the catalog service domain. Use the following comma-separated format:
serverName:hostName:clientPort:peerPort,<serverName:hostName:clientPort:peerPort>
serverName
Specifies the name of the catalog server.
hostName
Specifies the host name for the computer where the server is launched.
clientPort
Specifies the port that is used for peer catalog service communication.
peerPort
This value is the same as the haManagerPort. Specifies the port that is used for peer catalog service communication.
This property applies to the catalog service only. If you start more catalog servers, they must include the same servers in the catalogClusterEndPoints property. The order of the list can be different, but the servers that are contained in the list must be the same for each catalog server. Do not put any spaces in the list.
domainName
For stand-alone configurations only. Specifies the domain name that is used to uniquely identify this catalog service domain to clients when routing to multiple domains. This property applies to the catalog service only.
enableQuorum

Enables quorum for the catalog service. Quorum is used to ensure that most of the catalog service domain is available before partitions are moved to the available container servers. To enable quorum, set the value to true or enabled. The default value is disabled. This property applies to the catalog service only. For more information, see Catalog server quorums.

<foreignDomain>.endpoints
Specifies the connection information for the catalog servers of the foreign domains, such as domain B:
For example:
B.endPoints=hostB1:2809, hostB2:2809
If a foreign domain has multiple catalog servers, specify all of them.
foreignDomains
Specifies the names of catalog service domains to which you want to link in a multi-master replication topology. You can specify multiple catalog service domains with a comma-separated list. This property applies to the catalog service only.
foreignDomains=domain2,domain3,domain4
Restriction: The foreignDomains property is not supported in the Liberty profile.
heartBeatFrequencyLevel
Specifies how often a server failover is detected. An aggressive heartbeat interval can be useful when the processes and network are stable. If the network or processes are not optimally configured, heartbeats might be missed, which can result in a false failure detection. The heartbeat frequency level is a trade-off between use of resources and failure discovery time. The more frequent a heartbeat occurs, then more resources are used. However, failures are discovered more quickly. This property applies to the catalog service only.
Table 1. Valid heartbeat values
Value Action Description
-1 Aggressive Specifies an aggressive heartbeat level. With this value, failures are detected more quickly, but more processor and network resources are used. This level is more sensitive to missing heartbeats when the server is busy. Failovers are typically detected within 5 seconds.
0 Typical (default) Specifies a heartbeat level at a typical rate. With this value, failover detection occurs at a reasonable rate without overusing resources. Failovers are typically detected within 30 seconds.
1 Relaxed Specifies a relaxed heartbeat level. With this value, a decreased heartbeat frequency increases the time to detect failures, but also decreases processor and network use. Failovers are typically detected within 180 seconds.
isCatalog
For stand-alone configurations only. When set to true, the server process automatically starts a catalog service.
Default: false
placementDeferralInterval
Specifies the interval in milliseconds for deferring the balancing and placement of work items to the container servers. Increasing the deferral interval lowers processor utilization, but the placement of work items is completed over time. A decrease in the deferral interval increases short-term processor usage, but the placement of work items is more immediate and expedited.

Default: 15000 ms

Security server properties

The server properties file is also used to configure eXtreme Scale server security. You use a single server property file to specify both the basic properties and the security properties.
General security properties
credentialAuthentication
Indicates whether this server supports credential authentication. Choose one of the following values:
  • Never: The server does not support credential authentication.
  • Supported: The server supports the credential authentication if the client also supports credential authentication.
  • Required: The client requires credential authentication.
See Authenticating application clients for details about credential authentication.
securityEnabled
Enables the container server security when set to true. The default value is false. This property must match the securityEnabled property that is specified in the objectGridSecurity.xml file that is provided to the catalog server.
Transport layer security settings
transportType
Specifies the server transport type. Use one of the following values:
  • TCP/IP: Indicates that the server supports TCP/IP connections only.
  • SSL-Supported: Indicates that the server supports both TCP/IP and Secure Sockets Layer (SSL) connections. (Default)
  • SSL-Required: Indicates that the server requires SSL connections.
SSL configuration properties
alias
Specifies the alias name in the keystore. This property is used if the keystore has multiple key pair certificates and you want to select one of the certificates.

Default: No value is defined.

contextProvider
Specifies the name of the context provider for the trust service. If you indicate a value that is not valid, a security exception result that indicates that the context provider type is incorrect.

Valid values: IBMJSSE2, IBMJSSE, IBMJSSEFIPS, and so on.

customSecureTokenManagerProps
Specifies the custom SecureTokenManager implementation class properties. This property is used only if the secureTokenManagerType value is custom. The value is set to the SecureTokenManager Object with the setProperties(String) method.
customTokenManagerClass
Specifies the name of your SecureTokenManager implementation class, if you specified the SecureTokenManagerType property value as custom. The implementation class must have a default constructor to be instantiated.
keyStore
Specifies a fully qualified path to the keystore file.

Example: etc/test/security/client.private

keyStorePassword
Specifies the string password to the keystore. You can encode this value or use the actual value.
keyStoreType
Indicates the type of keystore. If you indicate a value that is not valid, a runtime security exception results.

Valid values: JKS, JCEK, PKCS12, and so on.

protocol
Indicates the type of security protocol to use for the client. Set this protocol value that is based on the Java Secure Socket Extension (JSSE) provider you use. If you indicate a value that is not valid, a security exception result that indicates that the protocol value is incorrect.

Valid values: SSL, SSLv2,SSLv3, TLS, TLSv1, and so on.

SecureTokenManager
The SecureTokenManager setting is used for protecting the secret string for server mutual authentications and for protecting the single sign-on token.
secureTokenManagerType
Specifies the type of SecureTokenManager setting. You must use the same secureTokenManagerType setting in all of the servers in the catalog service domain, and all servers in linked catalog service domains. You can use one of the following settings:
  • none: Indicates that no secure token manager is used. A secure token manager is required to protect the authenticationSecret attribute value when it is transmitted over the network. This setting also disables the use of a single sign-on token.
  • default: Indicates that a token manager that is supplied with the WebSphere eXtreme Scale product is used. You must provide a SecureToken keystore configuration.
  • custom: Indicates that you have your own token manager that you specified with the SecureTokenManager implementation class.
trustStore
Specifies a fully qualified path to the truststore file.

Example: etc/test/security/server.public

trustStorePassword
Specifies a string password to the truststore. You can encode this value or use the actual value.
trustStoreType
Indicates the type of truststore. If you indicate a value that is not valid, a runtime security exception results.

Valid values: JKS, JCEK, PKCS12, and so on.

Secure token keystore configuration
secureTokenKeyStore
Specifies the file path name for the keystore that stores the public-private key pair and the secret key.
secureTokenKeyStoreType
Specifies the keystore type, for example, JCKES. You can set this value that is based on the Java Secure Socket Extension (JSSE) provider that you use. However, the keystore must support secret keys.
secureTokenKeyPairAlias
Specifies the alias of the public-private key pair that is used for signing and verifying.
secureTokenKeyPairPassword
Specifies the password to protect the key pair alias that is used for signing and verifying.
secureTokenSecretKeyAlias
Specifies the secret key alias that is used for ciphering.
secureTokenSecretKeyPassword
Specifies the password to protect the secret key.
secureTokenCipherAlgorithm
Specifies the algorithm that is used for providing a cipher. You can set this value that is based on the Java Secure Socket Extension (JSSE) provider that you use.
secureTokenSignAlgorithm
Specifies the algorithm that is used for signing the object. You can set this value that is based on the JSSE provider that you use.
Authentication string
authenticationSecret
Specifies the secret string to challenge the server. When a server starts, it must present this string to the president server or catalog server. If the secret string matches what is in the president server, this server is allowed to join in. All of the servers in a catalog service domain, and the servers in any linked catalog service domains must use the same value this setting. The authenticationSecret value must be a long, hard to guess string. Do not use the authenticationSecret value that is in the sampleServer.properties in production deployments.