Project Darkstar Server Configuration Properties

This page documents the configuration properties supported by version 0.9.6.2 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.
com.sun.sgs.app.port for application and single nodes: The TCP port on which to listen for client connections.

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.

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.

Berkeley DB Properties

These properties are the subset of the properties supported by the DataService that control the implementation of the underlying Berkeley DB database. 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 (one second): 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 5 milliseconds and less than or equal to 10000 milliseconds (10 seconds). 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.

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.