A.5. Network Ports

Documentation

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. The network ports are configurable as part of the command that starts the VoltDB database process. 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 and their default value. The following sections describe each port in more detail and how to set them. Section A.5.7, “TLS/SSL Encryption (Including HTTPS)” explains how to enable TLS encryption for the web and the programming interface ports, client and admin.

Table A.1. VoltDB Port Usage

PortDefault Value
Client Port21212
Admin Port21211
Web Interface Port (httpd)8080
Web Interface Port (with TSL/SSL enabled)8443
Internal Server Port3021
Replication Port5555
Zookeeper port7181

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 start -l ~/license.xml \
         --dir=~/mydb -H serverA \
         --client=12345

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.

Java

org.voltdb.client.Client voltclient;
voltclient = ClientFactory.createClient();
voltclient.createConnection("myserver",12345);  

C++

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 on the command line using the --admin flag. For example, the following command sets the admin port to 2222:

$ voltdb start -l ~/license.xml \
         --dir=~/mydb -H serverA \
         --admin=2222

A.5.3. Web Interface Port (http)

The web interface port is the port that VoltDB listens to for web-based connections. This port is used for both the JSON programming interface and access to the VoltDB Management Center.

By default, VoltDB uses port 8080 on the default external network interface as the web port. You can change the port assignment on the command line using the --http flag. For example, the following command sets the port to 8888:

$ voltdb start -l ~/license.xml \
         --dir=~/mydb -H serverA \
         --http=8888

If you change the port number, be sure to use the new port number when connecting to the cluster using either the VoltDB Management Center or the JSON interface. For example, the following URL connects to the JSON interface using the reassigned port 8888:

http://athena.mycompany.com:8888/api/1.0/?Procedure=@SystemInformation

If you do not want to use the http port of the features it supports (the JSON API and VoltDB Management Center) you can disable the port in the configuration file. For example, for following configuration option disables the default http port:

<httpd enabled="false"/>

If the port is not enabled, neither the JSON interface nor the Management Center are available from the cluster. By default, the web interface is enabled.

Another aspect of the http port, when it is enabled, is whether the port transmits using http or https. You can enable TLS (Transport Layer Security) encryption on the web interface so that all interaction uses the HTTPS protocol. When TLS is enabled, the default port changes to 8443. See Section A.5.7, “TLS/SSL Encryption (Including HTTPS)” for information on enabling encryption in the configuration file.

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 t1he cluster[1]. 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 start -l ~/license.xml \
         --dir=~/mydb -H serverA \
          --internal=4000

A.5.5. Replication Port

During database replication, producer databases (that is, the master database in passive DR and all clusters in XDCR) use a dedicated port to share data to their consumers. By default, the replication port is port 5555. You can use a different port by specifying a different port number on the voltdb command line using the --replication flag. For example, the following command changes the replication port:

$ voltdb start -l ~/license.xml \
         --dir=~/mydb -H serverA \
        --replication=6666

Note that if you set the replication port on the producer to something other than the default, you must notify the consumers of this change. The replica or other XDCR clusters must specify the port along with the network address or hostname in the src attribute of the <connection> element when configuring the DR relationship. For example, if the server nyc2 has changed its replication port to 3333, another cluster in the XDCR relationship might have the following configuration:

<dr id="1" role="xdcr" >
   <connection source="nyc1,nyc2:3333" />
</dr>

Finally, in some cloud environments, such as Kubernetes, remote clusters may not be able to access the producer cluster by its internal network interface. Consumers can specify the location of the producer in the DR configuration using a remapped IP address. But once they initialize contact with the producer, the producer sends a list of IP addresses to use for ongoing replication. By default, these are the internal addresses the producer cluster knows about.

You can tell the producer to advertise a different interface (and port) for this second phase by specifying the alternate interface using the --drpublic argument in the voltdb start command. If you do not specify a port on the --drpublic argument, the internal replication port is used. For example:

$ voltdb start --drpublic=some.external.addr

A.5.6. 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 (127.0.0.1) 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 start -l ~/license.xml \
         --dir=~/mydb -H serverA \
         --zookeeper=2288

A.5.7. TLS/SSL Encryption (Including HTTPS)

VoltDB lets you enable Transport Layer Security (TLS) — the recommended upgrade from Secure Socket Layer (SSL) encryption — for all of its externally-facing interfaces: the web port, client port, admin port, and replication (DR) port. When you enable TLS, you automatically enable encryption for the web port. You can then optionally enable encryption for the external ports (client and admin) and/or the replication port.

To enable TLS encryption you need an appropriate certificate. How you configure TLS depends on whether you create a local certificate or receive one from an authorized certificate provider, such as VeriSign, GeoTrust and others. If you use a commercial certificate, you only need to identify the certificate as the key store. If you create your own, you must specify both the key store and the trust store. (See the section on using TLS/SSL for security in the Using VoltDB manual for an example of creating your own certificate.)

You enable TLS encryption in the deployment file using the <ssl> element. Within <ssl> you specify the location and password for the key store and, for locally generated certificates, the trust store in separate elements like so:

<ssl>
   <keystore path="/etc/mydb/keystore" password="twiddledee"/>
   <truststore path="/etc/mydb/truststore" password="twiddledum"/>
</ssl>

When you enable the <ssl> element in the configuration file, TLS encryption is enabled for the web port and all access to the httpd port and JSON interface must use the HTTPS protocol. When you enable TLS, the default web port changes from 8080 to 8443.

You can explicitly enable or disable TLS encryption by including the enable attribute. (For example, if you want to include the key store and trust store in the configuration but not turn on TLS during testing, you can include enabled="false".) You can specify that the client and admin API ports are also TLS encrypted by adding the external attribute and setting it to true. Similarly, you can enable TLS encryption for the DR port by adding the dr attribute. For example, the following configuration sample, explicitly enables TLS for all externally-facing ports:

<ssl enabled="true" external="true" dr="true">
   <keystore path="/etc/mydb/keystore" password="twiddledee"/>
   <truststore path="/etc/mydb/truststore" password="twiddledum"/>
</ssl>

Note that you cannot disable TLS encryption for the web port separately. TLS is always enabled for the web port if you enable encryption for any ports.



[1] 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.