Simulacron - An Apache Cassandra® Native Protocol Server Simulator

Build Status

A native protocol server simulator that helps facilitate the testing of scenarios that are difficult to reliably reproduce in driver clients and applications.

Inspired by Scassandra, simulacron is a pure java implementation with increased emphasis on testing with many simulated native protocol endpoints.



  1. Java 8+ - Simulacron is a Java-based application built on Java 8.
  2. Apache Maven 3.3+ - For building the project.
  3. MacOS only: To be able to define more than a single node cluster, multiple loopback aliases should be added.

    This is not required on Linux or Windows since these are implicitly defined. The following script will add

    for sub in {0..4}; do
       echo "Opening for 127.0.$sub"
       for i in {0..255}; do sudo ifconfig lo0 alias 127.0.$sub.$i up; done

    Note that this is known to cause temporary increased CPU usage in OS X initially while mDNSResponder acclimates itself to the presence of added ip addresses. This lasts several minutes.

    Also note that on reboot these ip addresses need to be re-added.

Getting Started with the Standalone Jar

To use simulacron with its included HTTP server, one may use the standalone jar.

Pre-built versions of the standalone jar can be downloaded from the releases page.

The jar is executed in the following manner:

java -jar simulacron-standalone-<VERSION>.jar

If you'd like to build simulacron, follow these instructions:

  1. Set up your maven settings.xml to use artifactory (see java-api doc)
  2. mvn package - Compiles, Tests, and packages the project. Produces standalone jar in standalone/target/
  3. java -jar standalone/target/simulacron-standalone-<VERSION>.jar - Runs the standalone app.
  4. Navigate to http://localhost:8187/doc to access the interactive documentation.


    --disable-activity-log, -d
      Disables activity logging by default
      Default: false
    --httpintf, -t
      Interface address to bind HTTP server on
      Default: localhost
    --httpport, -p
      HTTP port to bind on
      Default: 8187
    --ip, -i
      Starting IP address to create simulated C* nodes on
    --loglevel, -l
      Logging level to use
      Default: INFO
    --starting-port, -s
      Starting Port to assign Nodes to.  Note that if this is used multiple
      nodes can be assigned on one IP (which mimics C* 4.0+ peering)
      Default: -1
    --verbose, -v
      Whether or not to enable verbose http logging (also enables DEBUG
      Default: false

Using the Java API

As simulacron is a java project, it includes a Java API that bypasses the need to use the HTTP interface all together.

See the Java API User's Guide for using this API.


┬ę DataStax, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

DataStax is a registered trademark of DataStax, Inc. and its subsidiaries in the United States and/or other countries.

Apache Cassandra, Apache, Tomcat, Lucene, Solr, Hadoop, Spark, TinkerPop, and Cassandra are trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries.