Project Darkstar Server Configuration Properties

This page documents the configuration properties supported by version 0.9.9.6 of the Project Darkstar Server. Configuration properties may be specified by system properties (using -Dproperty=value) or in the application properties file named on the command line. Any changes to configuration properties from previous releases will be noted in the release documentation.

By default, the Project Darkstar Server consists of a single node, as described in Configuring a Single Node System. Alternatively, multiple nodes can be configured to work together, as described in Configuring a Multi-Node System.

The type of node being configured is specified by the following property:

com.sun.sgs.node.type singleNode

Indicates which type of node is being started, and has valid settings of

singleNode
coreServerNode
appNode

For example configuration files of the different node types, see the single-node.properties, core-server.properties, and app-node.properties files.

Configuring a Single Node System

A single node systems consists of a Darkstar Server running in a single Java Virtual Machine. This is the default server type for Project Darkstar. Note that the Required Properties will also need to be specified.

Configuring a Multi-Node System

The Project Darkstar Server can be run on multiple nodes configured to work together in a cluster. This multi-node configuration requires a special core server node to run critical Project Darkstar operations, with the remaining nodes, the application nodes, cooperating to run the application. Application nodes can be dynamically added or removed from the cluster.

The core server node must be running before starting the application nodes.

Properties in this section specify which node is the core server node, which are the application nodes, and how the application nodes discover the core node. Note that some Required Properties will also need to be specified.

Core Server Node Properties

These properties control the configuration of the Project Darkstar core server node if a multi-node configuration is being used. Currently, there is only one core server per cluster of Project Darkstar nodes; if multiple core servers are started, then each will be associated with its own independent Project Darkstar cluster.

The node.type property must be set to coreServerNode to start the core server.

Application Node Properties

These properties control the configuration of the Project Darkstar application nodes if a multi-node configuration is being used.

The node.type property must be set to appNode to start an application node.

com.sun.sgs.server.host for application nodes: The name of the host the core Project Darkstar Server node is running on.

Required Properties

These properties are required for some or all node types.

com.sun.sgs.app.name: The name of the application. If running in a multi-node configuration, this name must be the same for each node.
com.sun.sgs.app.root: The root directory for the application, which specifies local file system space available for Project Darkstar use.
com.sun.sgs.app.listener for application and single nodes: The AppListener for the application, specified as a fully qualified class name. See the class javadoc for requirements of valid class implementations.

Other Common Properties

These properties control various general facilities in the Project Darkstar Server, and can be used in any node configuration unless otherwise specified.

Application Server Port Properties

By default, the application server uses a TCP transport for client communications. This property can be used by application nodes to specify the port to be used for the client listeners.

com.sun.sgs.impl.transport.tcp.listen.port 62964: The TCP port on which to listen for client connections when the TCP transport is configured.

Core Server Port Properties

These properties can be used by either core server or application nodes in a multi-node configuration. The core server node may be configured to specify ports to be used on the core server machine. If these properties are used, they must be set to the same value on each application node.

com.sun.sgs.impl.service.data.store.net.server.port 44530: The TCP port for the data service's shared network server.
com.sun.sgs.impl.service.watchdog.server.port 44533: The TCP port for the watchdog service's internal server.
com.sun.sgs.impl.service.nodemap.server.port 44535: The TCP port for the node mapping service's internal server.

DataService Properties

These properties control the implementation of the DataService.

DataStore Properties

These properties are the subset of the properties supported by the DataService that control the implementation of the underlying DataStore. Setting these properties has no effect on application nodes.

com.sun.sgs.impl.service.data.store.DataStoreImpl.directory ${com.sun.sgs.app.root}/dsdb: The directory in which to store database files. Each single node or core server node requires its own, unique directory.
com.sun.sgs.impl.service.data.store.db.environment.class com.sun.sgs.impl.service.data.store.db.bdb.BdbEnvironment: The name of the class that implements the underlying database. The default value selects a database implementation based on Berkeley DB. Specifying com.sun.sgs.impl.service.data.store.db.je.JeEnvironment selects a database implementation based on Berkeley DB Java Edition. Other values should specify the fully qualified name of a non-abstract class that implements com.sun.sgs.service.store.db.DbEnvironment, and that has a public constructor with three parameters: a java.util.String, which specifies the directory containing database files, a java.util.Properties, which specifies configuration options, and a com.sun.sgs.impl.service.data.store.Scheduler, which the implementation can use to run asynchronous, periodic tasks.
Note that persistent data created using Berkeley DB is incompatible with data created using Berkeley DB Java edition

Berkeley DB Properties

These properties are the subset of the properties supported by the DataService that control the behavior of the Berkeley DB database, when it has been specified as the implementation of the underlying database using the


com.sun.sgs.impl.service.data.store.db.environment.class

property. Setting these properties has no effect on application nodes.

com.sun.sgs.impl.service.data.store.db.bdb.cache.size 128000000: The size in bytes of the Berkeley DB cache. The value must not be less than 20000. Using a cache that is too small can introduce a significant reduction in performance.
com.sun.sgs.impl.service.data.store.db.bdb.remove.logs false: Whether to automatically remove database log files that are no longer needed. Note that automatic log file removal is likely to make catastrophic recovery of the database impossible, because log files that may be needed will not have been backed up.

Watchdog Service Properties

These properties control the implementation of the WatchdogService. Setting these properties has no effect on application nodes.

com.sun.sgs.impl.service.watchdog.server.renew.interval 1000 (for a multi-node configuration) or Integer.MAX_VALUE (for a single node configuration): The time interval, in milliseconds, in which application nodes must contact the watchdog service's internal server in order to be considered alive. This time interval is sent to each application node during start up, when the application node registers with the watchdog's internal server. The interval must be greater than or equal to 100 milliseconds. Using a renew interval that is too small may cause some application nodes to be considered failed by the WatchdogService when they are very busy. Using an interval that is too large will increase the amount of time the system takes to respond to failed nodes.

ClientSessionService Properties

These properties control the implementation of the ClientSessionService.

com.sun.sgs.impl.service.session.allow.new.login false: Whether to permit or deny a new login request for a user that is already logged in. If the property is false, a new user with the same identity as an existing user is not permitted to log in. If the property is true, the user's existing session is disconnected, and the new login is allowed to proceed.
com.sun.sgs.impl.service.session.disconnect.delay 1000: The time, in milliseconds, in which a disconnecting client is allowed to close a connection before it is closed by the server. The delay must be greater than or equal to 200 milliseconds.

System Properties

These properties control the implementation of the core components of the system including identity management, profiling, and task scheduling.

com.sun.sgs.app.authenticators com.sun.sgs.impl.auth.NullAuthenticator

A colon separated list of IdentityAuthenticators to use for the application. The order defines the precedence when authenticating an identity. The default authenticator simply accepts any name-password pair.

com.sun.sgs.impl.kernel.profile.level min

The profiling level. Valid levels are

min - minimal profiling data is collected.
medium - more data is collected, but is still appropriate for monitoring a production system.
max - all available profiling data is collected. This level may only be appropriate for debugging systems in development.

com.sun.sgs.impl.kernel.profile.listeners

A colon separated list of profile listeners, which consume profile output. To configure the available listeners, see the individual class javadoc for profile listener implementations.

com.sun.sgs.impl.kernel.transaction.threads 4

The number of initial threads used to process transactional tasks, such as those started through the TaskManager.

com.sun.sgs.impl.kernel.task.threads 4

The number of initial threads used to process non-transactional tasks.

Debug and Test Properties

These properties are most useful for debugging and testing, and are not typically useful for production deployments.

com.sun.sgs.txn.timeout 100: The maximum amount of time in milliseconds that a transaction will be permitted to run before it is a candidate for being aborted. Increasing this timeout is useful when attaching a debugger to a node, but can increase game latency.

Monitoring and Management Properties

The Project Darkstar Server exposes internal data through standard Java Management Extensions (JMX) MXBeans. The following properties are system properties, and must be specified on the command line when a Project Darkstar Server node is started, rather than in the application configuration properties file.

In order to enable monitoring on a remote machine, the following properties must be used. By default, only local monitoring is enabled.

com.sun.management.jmxremote.port: The port number through which JMX RMI connections are enabled.

Remote management requires security. To disable all security, useful for testing only, set the following properties to false:

com.sun.management.jmxremote.authenticate=false
com.sun.management.jmxremote.ssl=false

For more information, please refer to the Java SE Monitoring and Management Guide, especially Chapter 2, Monitoring and Management Using JMX Technology.