New Cluster Test (cluster deployment and test tool)

Skip to end of metadata
Go to start of metadata
This documentation is NOT for the latest version of GraphDB.

Latest version - GraphDB 7.1

GraphDB Documentation

Next versions

GraphDB 6.6
GraphDB 7.0
GraphDB 7.1

Previous versions

GraphDB 6.4
GraphDB 6.3
GraphDB 6.2
GraphDB 6.0 & 6.1

[OWLIM 5.4]
[OWLIM 5.2]
[OWLIM 5.1]
[OWLIM 5.0]
[OWLIM 4.4]
[OWLIM 4.3]
[OWLIM 4.2]
[OWLIM 4.1]
[OWLIM 4.0]

The project new-cluster-test is used to deploy a GraphDB cluster through a configuration file. The scenario is, that you have several physical (or virtual) machines, called boxes, and on each of them you want to run one or more GraphDB nodes. (A "node" here means GraphDB master or GraphDB worker instance). Each node is run in а tomcat, and several nodes can share one tomcat (depending on the configuration).

The tool can be used on one command-and-control machine, which may or may not participate in the cluster itself.

The Test Help Tool

The Test Help Tool was specially created to run cluster tests. It installs and runs test-help-tool.jar on each box. This tool has several roles as described below:

  • Installation package
    It consists of tomcat, GraphDB-Enterprise and their dependencies, packed in the jar. During deployment, they are unpacked in the appropriate places.
  • Remote command executioner
    It executes commands on the machine where it is running. The commands are used during deployment and testing (e.g. starting or stopping a specific tomcat instance). Although this role can be handled by SSH (and, in fact, it is during deployment), it is harder to be configured for testing on Windows machines. Therefore the tests execute the remote commands exclusively through a proxy.
  • IP port redirection (proxy)
    The cluster can be deployed in a way that the communication between nodes passes through the proxies. This allows test scripts to simulate various network problems such as latency and disconnection.
The tool's remote exec is a security hole, so it is not advisable to open it on an external network or on machines containing sensitive information!

Configuration file

The configuration file must be called test.config and it should be located in the user's home directory or in the tools directory on the command machine.

Format and semantics

The file is read and interpreted one line at a time.

Comments and blank lines

Lines with the hash symbol ('#') in the first column are treated as comments and are ignored. These are the only "officially" recognized comments.

Blank lines are skipped.

Proxy configuration

By default, the nodes in the cluster are configured to communicate through the proxy. This can be switched off by the following command:

This command should come before the masters/workers description, and it makes sense to be the first non-comment line in the file.

Box declarations

The box declaration line looks like this:

It should start with the word "box", followed by a number. Boxes must have unique names, but in case of duplicates, the last one will be used.

The next part is the box's name or IP address ("server-or-ip").

Then, the user ("onto") who runs GraphDB on this machine. The command-and-control machine must have SSH access without password to this user/machine.

The next part is the absolute path where all GraphDB instances will be installed on this machine ("/space1/OWLIM").

The last parameter is the JMX port on which the proxy will listen. Don't use port numbers >= 20000 because they are already used for redirects.

Master/worker declaration

The master and worker declarations look like this:

Again, the line should start with the word "master" or "worker", followed by a number. The bar symbols ("|") add optional aliases, which can be used in the tests.

The next part is the box on which the node should be installed ("box1").

Then is the repository name ("master"), followed by the tomcat port (10080), and the tomcat box's home directory.

The main caveat here is that these lines declare the tomcat instances as well. For example, the first line means that there will be tomcat on box1 running on port 10080. The home.master1 directory is relative to the box's home directory.

Here is how it will look:

  • /
    • space1
      • OWLIM
        • home.master1
          • apache-tomcat
            • ...
          • data (the sesame data dir)
            • openrdf-sesame
              • conf
              • logs
              • repositories
                • master (the repository name from the configuration line)
                • SYSTEM
For each box, only one tomcat can run on port 10080. So if another node specifies the same box and port, it should also specify the same home dir but should have a different repository name.

Link declarations

Master worker links are declared as follows:

Java Options

Additional Java options can be specified for all masters and for all workers as follows:


All commands are run through ant. The main commands are:

to deploy the cluster.

to get the cluster status.

to start the cluster.

to stop the cluster.

to remove the deployment.


  • When using this tool, the cluster can be deployed only on Linux machines. The command & control machine can run Windows, Linux, or OS X.
  • Unrecognised configuration lines are ignored. Recognized, but bad configuration lines may or may not be reported.
  • Other configuration errors may or may not be detected, reported, or handled.
  • The proxy tool creates a log file named /tmp/test-help-tool.log. It is not automatically deleted, so it can grow quite large.


This tool was created to improve our test installations. It has many hard-coded assumptions, bad configuration file syntax, very bad error handling and reporting, and probably quite a few bugs. Use at your own risk.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.