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.
- For servers that run in WebSphere Application Server:
- Use a well-named file in the class path, for example was_root/properties. If you put this
well-named file in the current directory, the file is not found unless the current directory is in
the class path. The name that is used
follows:
objectGridServer.properties
- Specify a system property that specifies a file in the system current directory. Put the file in
the was_root/properties directory.
The file cannot be in the class path:
-Dobjectgrid.server.props=file_name
- Use a well-named file in the class path, for example was_root/properties. If you put this
well-named file in the current directory, the file is not found unless the current directory is in
the class path. The name that is used
follows:
- For servers that run in the Liberty:
- In server.xml file, specify a server properties file by setting the
serverProps attribute of the xsServer element; for
example:
<xsServer ... serverProps="${server.config.dir}/server.properties" ... />
For eXtreme Scale servers that run in the Liberty, specify a server properties file to configure security. You can configure other properties in the server.xml file. For more information, see Liberty configuration files.
- In server.xml file, specify a server properties file by setting the
serverProps attribute of the xsServer element; for
example:
- For stand-alone servers:
- Use a well-named file in the class path, for example wxs_home/properties. If you put this
well-named file in the current directory, the file is not found unless the current directory is in
the class path. The name that is used
follows:
objectGridServer.properties
- Specify the server properties file as a parameter when you run the start server command. You can
specify an absolute path or a path that is relative to the directory from which you run the start
server command.
-serverProps file_name
- Use a well-named file in the class path, for example wxs_home/properties. If you put this
well-named file in the current directory, the file is not found unless the current directory is in
the class path. The name that is used
follows:
- For embedded, stand alone servers:
Use the embedded server API. Use the ServerFactory.getServerProperties and ServerFactory.getCatalogServerProperties methods. The data in the object is populated with the data from the properties files.
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.
- hpelEnable
- Specifies whether High Performance Extensible Logging (HPEL) is enabled. HPEL logging is enabled
when the property is set to true.
Default: false
- hpelRepositoryPath
- Specifies the HPEL logging repository location.
Default: "." (the runtime location)
- hpelEnablePurgeBySize
- Indicates whether the HPEL purges log files by size. You can set the size of the files with the
hpelMaxRepositorySize property.
Default: true (enabled)
- hpelEnablePurgeByTime
- Indicates whether the HPEL purges log files by time. Set the amount of time with the
hpelMaxRetentionTime property.
Default: true (enabled)
- hpelEnableFileSwitch
- Indicates whether the HPEL file is enabled to create a new file at a specified hour. Use the
hpelFileSwitchHour property to specify the hour at which to create a new file.
Default: false (disabled)
- hpelEnableBuffering
- Indicates whether the HPEL buffering is enabled.
Default: false (disabled)
- hpelIncludeTrace
- Indicates whether the HPEL text files include tracing.
Default: false (disabled)
- hpelOutOfSpaceAction
- Indicates the action to take when the disk space is exceeded.
Default: PurgeOld
Possible values: PurgeOld, StopServer, StopLogging
- hpelOutputFormat
- Indicates the format of the log files to be generated.
Default: Basic
Possible values: Basic, Advanced, CBE-1.0.1
- hpelMaxRepositorySize
- Indicates the maximum size of files, in megabytes. This value is used when you able the
hpelEnablePurgeBySize property.
Default: 50
- hpelMaxRetentionTime
- Indicates the maximum retention time to hold files, in hours.
Default: 48
- hpelFileSwitchHour
- Indicates the hour at which to create a new file. This value is used when the
hpelEnableFileSwitch property is enabled.
Default: 0
- 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.Note: If you want to collect JMX data, then a JMXServicePort port must also be opened.Note: If SSL is enabled and a value for JMXConnectorPort is not defined, an ephemeral port is chosen. This port can vary each time that the server is restarted.
- 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. This file is in or relative to
the log directory of the workingDirectory
property.
Default: jvmstats
- jvmStatsLoggingEnabled
- When set to true, enables log data for the JVM to be written to a CSV
file.
Default: true
- listenerHost
-
Specifies the host name to which the Object Request Broker (ORB) or eXtremeIO (XIO) 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 or the eXtremeIO (XIO) transport protocol binds for communication. The port number that is defined for listenerPort is for communication
between a client and a catalog server in the same domain. It is also used for communication between
a container server and a catalog server that are in the same domain. This port is also used for
inter-domain and intra-domain communication between catalog servers.
Default: 2809
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. If you are using the XIO transport protocol, the XIO_ADDRESS port must be opened. - listenerPort (container server)
- Specifies the port number to which the ORB or the XIO transport protocol binds for communication. The port number that is defined for listenerPort is used for bidirectional
communication between a client and a container server that are in the same domain. It is also used
for communication between a catalog server and a container server that are in the same domain. This
port is also used for intra-domain replication between primary and replica shards, and inter-domain
replication between primary shards.
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. If you are using the XIO transport protocol, the XIO_ADDRESS port must be opened. - listenerPort (client)
- Specifies the port number to which the ORB or the XIO 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. This file is in or relative to
the log directory of the workingDirectory
property.
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
- 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. This file is in
or relative to the log directory of the workingDirectory
property.
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
- serverName
- Sets the server name that is used to identify the server. This property applies to both the container server and the catalog service.
- statsWriteRate
- Specifies the write rate of the CSV statistics files in seconds.
Default: 30
- syslogEnabled
- Enables remote logging for analysis of historical data. You must have a syslog server available
to listen for and capture events.
Default: false
- syslogHostName
- Specifies the host name or IP address of the remote server on which you want to log historical data.
- syslogHostPort
- Specifies the port number of the remote server on which you want to log historical data.
Valid values: 0-65535
Default: 512
- syslogFacility
- Indicates the type of remote logging facility that is being used.
Valid values: kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, sys0, sys1, sys2, sys3,local0, local1, local2, local3, local4, local5, local6, local7
Default: user
- syslogThreshold
- Specifies the threshold of the severity of messages that you want to send to the remote logging
server. To send both warning and severe messages, enter a value of WARNING.
To send severe messages only, enter SEVERE.
Valid values: SEVERE, WARNING
Default: WARNING
- 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.
- xioTimeout
- Sets the timeout for server requests that are using the IBM® eXtremeIO (XIO) transport in seconds. The value can be set to any value greater than or
equal to 1 second.
Default: 30 seconds.
- 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
- allowableShardOverrage
- Specifies the percentage of container servers that a zone must have compared to the other zones in a multi-zone deployment before all the replica shards are placed in that zone. If the percentage of container servers in the zone is below the specified value, only a relative subset of the replicas available are placed. After the percentage exceeds the specified value, all the replicas are placed. Primary shards are always placed. For example, the allowableShardOverrage value is set to 0.75 (75 percent). If zone1 has two container servers, and zone2 has three container servers, the percentage of the container servers between the zones is 2/3 (67 percent). Because this percentage is less than the allowableShardOverrage value of 75 percent, not all the replicas for the data grid are necessarily placed until the zones have an equal number of container servers.
- 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:256
- maxXIOWorkerThreads
- Sets the maximum number of threads to allocate in the eXtremeIO transport request processing
thread pool.
Default:256
- 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:1
- minXIOWorkerThreads
- Sets the minimum number of threads to allocate in the eXtremeIO transport request processing
thread pool.
Default:128
Default:1
- 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: 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: 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
- 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.
- 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.
- compressionType
- Specifies the compression type that is set for a catalog server when data is replicated between catalog servers in the same domain. The compression type can be turned off by setting the compression to None, or it can be set to a different compression type. The default compression type is Compatible. In a large-scale environment, such as 1000 container servers, changing the compression type can improve the catalog server performance. If you require performance tuning during replication between larger data sets, then change the compression type to Optimized1. When you change the compression type, the same setting must be used for all catalog servers at startup within the same domain. Valid settings are Compatible, Optimized1, and None.
- 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.
- enableManagementConcentrator
- Specifies whether the catalog server is a hub for the message center. This property is enabled
by default. To disable the hub, set the value to false.
Default: true
- 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:
If a foreign domain has multiple catalog servers, specify all of them.B.endPoints=hostB1:2809, hostB2:2809
- 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. Values from -1
for aggressive heartbeat to1
for relaxed heartbeat specify how often a server failover is detected.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. -10 Semi-aggressive Failovers are typically detected within 15 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. 10 Semi-relaxed Failovers are typically detected within 90 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.
- logNotificationFilter
- Specifies a regular expression that filters all messages, including the information level log
messages. This filter determines which messages generate health monitoring events. If you do not
specify a regular expression, information level log messages are not published through the health
monitoring framework. By default, only WARNING and SEVERE level messages generate health monitoring
events.
Example:
logNotificationFilter=.*DYNACACHE.*
- placementDeferralInterval
- Specifies the interval in milliseconds for deferring the balancing and placement of shards on
the container servers. Placement does not start until after the time specified in the property has
passed. 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.
If multiple container servers are starting in succession, the deferral interval timer is reset if a new container server starts within the given interval. For example, if a second container server starts 10 seconds after the first container server, placement does not start until 15 seconds after the second container server started. However, if a third container server starts 20 seconds after the second container server, placement has already begun on the first two container servers.
When container servers become unavailable, placement is triggered as soon as the catalog server learns of the event so that recovery can occur as quickly as possible.
Default: 15000 ms (15 seconds)
- transport
-
Specifies the type of transport to use for all the servers in the catalog service domain. You can set the value to XIO or ORB.
When you use the startOgServer or startXsServer commands, you do not need to set this property. The script overrides this property. However, if you start servers with another method, the value of this property is used.
This property applies to the catalog service only.
If you have both the -transport parameter on the start script and the transport server property that is defined on a catalog server, the value of the -transport parameter is used.
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.