A.5. Network Ports


VoltDB Home » Documentation » Administrator's Guide

A.5. Network Ports

A VoltDB cluster opens network ports to manage its own operation and to provide services to client applications. When using the command line, the network ports are configurable as part of the command that starts the VoltDB database process or through the deployment file. When specifying a port on the command line, you can specify just a port number or the network interface and the port number, separated by a colon.

Table A.1, “VoltDB Port Usage” summarizes the ports that VoltDB uses, their default value, and how to change the default. The following sections describe each port in more detail.

Table A.1. VoltDB Port Usage

PortDefault ValueWhere to Set (Community Edition)
Client Port21212VoltDB command line
Admin Port21211VoltDB command line or deployment file
Web Interface Port (httpd)8080VoltDB command line or deployment file
Internal Server Port3021VoltDB command line
JMX Port9090VoltDB command line
Replication Port5555VoltDB command line
Zookeeper port7181VoltDB command line

A.5.1. Client Port

The client port is the port VoltDB client applications use to communicate with the database cluster nodes. By default, VoltDB uses port 21212 as the client port. You can change the client port. However, all client applications must then use the specified port when creating connections to the cluster nodes.

To specify a different client port on the command line, use the --client flag when starting the VoltDB database. For example, the following command starts the database using port 12345 as the client port:

$ voltdb create -l ~/license.xml \
         -d deployment.xml -H serverA \

If you change the default client port, all client applications must also connect to the new port. The client interfaces for Java and C++ accept an additional, optional argument to the createConnection method for this purpose. The following examples demonstrate how to connect to an alternate port using the Java and C++ client interfaces.


org.voltdb.client.Client voltclient;
voltclient = ClientFactory.createClient();


boost::shared_ptr<voltdb::Client> client = voltdb::Client::create();
client->createConnection("myserver", 12345);

A.5.2. Admin Port

The admin port is similar to the client port, it accepts and processes requests from applications. However, the admin port has the special feature that it continues to accept write requests when the database enters admin, or read-only, mode.

By default, VoltDB uses port 21211 on the default external network interface as the admin port. You can change the port assignment in the deployment file using the <admin-mode> tag or on the command line using the --admin flag. For example, the following deployment file sets the admin port to 2222:

   <admin-mode port="2222" />

The same effect can be achieved using the --admin flag on the command line:

$ voltdb create -l ~/license.xml \
         -d deployment.xml -H serverA \

When the admin port is set in both the deployment file and on the command line, the command line setting supersedes the deployment file.

A.5.3. Web Interface Port (httpd)

The web interface port is the port that VoltDB listens to for web-based connections from the JSON interface. There are two related settings associated with the JSON interface. The first setting is whether the port is enabled; the second is which port to use, if the interface is enabled. The default httpd port is 8080.

  • To enable the httpd port but disable the JSON interface, specify the attribute enabled="false" in the <jsonapi> tag in the deployment file when starting VoltDB.

  • To change the web interface port, specify the alternate port using the port attribute to the <httpd> tag in the deployment file. Or, you can use the --http flag on the command line.

For example, the following deployment file fragment enables the web interface and the JSON interface, specifying the alternate port 8083.

<httpd port='8083'>
        <jsonapi enabled='true'/>

If you change the port number, be sure to use the new port number when connecting to the cluster using the JSON interface. For example, the following URL connects to the port 8083, instead of 8080:


For more information about the JSON interface and specifying the appropriate port when connecting to the VoltDB cluster, see the section on "How the JSON Interface Works" in the Using VoltDB manual.

A.5.4. Internal Server Port

A VoltDB cluster uses ports to communicate among the cluster nodes. This port is internal to VoltDB and should not be used by other applications.

By default, the internal server port is port 3021 for all nodes in the cluster[3]. You can specify an alternate port using the --internal flag when starting the VoltDB process. For example, the following command starts the VoltDB process using an internal port of 4000:

$ voltdb create -l ~/license.xml \
         -d deployment.xml -H serverA \

A.5.5. JMX Port

The use of JMX by the VoltDB Enterprise Edition is deprecated. The port is still available in the short-term for any users who may have used this feature in the past and need to migrate to one of the supported monitoring solutions described in Chapter 6, Monitoring VoltDB Databases. The JMX port will be shut off in a future release.

In the meantime, the default JMX port is 9090. You can change the port number used by JMX by adding the Java argument -Dvolt.rmi.agent.port to the command line. You do that by defining the environment variable VOLTDB_OPTS before starting the server. For example, the following command assigns the JMX port to port number 2345:

$ export VOLTDB_OPTS="-Dvolt.rmi.agent.port=2345"

There is no JMX port when using the VoltDB Community Edition.

A.5.6. Replication Port

During database replication, the replica uses a dedicated port to connect to the master database. By default, the replication port is port 5555. You can use a different port by specifying a different port number either on the voltdb command line or in the deployment file.

  • On the command line, use the --replication flag to specify a different port (and, optionally, a different network interface):

    $ voltdb create -l ~/license.xml \
             -d deployment.xml -H serverA \
  • In the deployment file, specify the replication port number using the port attribute of the <dr> tag:

    <dr id="3" port="6666" />

Adding the replication port to the deployment file is useful when setting the port for all nodes in the cluster. Using the command line option is useful for changing the default port for only one node in the cluster or for specifying a specific network interface. If you specify the replication port in both the deployment file and on the command line, the command line argument takes precedence.

A.5.7. Zookeeper Port

VoltDB uses a version of Apache Zookeeper to communicate among supplementary functions that require coordination but are not directly tied to database transactions. Zookeeper provides reliable synchronization for functions such as command logging without interfering with the database's own internal communications.

VoltDB uses a network port bound to the local interface ( to interact with Zookeeper. By default, 7181 is assigned as the Zookeeper port for VoltDB. You can specify a different port number using the --zookeeper flag when starting the VoltDB process. It is also possible to specify a different network interface, like with other ports. However, accepting the default for the zookeeper network interface is recommended where possible. For example:

$ voltdb create -l ~/license.xml \
         -d deployment.xml -H serverA \

[3] In the special circumstance where multiple VoltDB processes are started for one database, all on the same server, the internal server port is incremented from the initial value for each process.