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 configuration 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. Section A.5.8, “SSL Encryption (Including HTTPS)” explains how to enable SSL encryption for the web port and the programming interface ports, client and admin.
Table A.1. VoltDB Port Usage
|Port||Default Value||How to Set|
|Client Port||21212||VoltDB start command|
|Admin Port||21211||VoltDB start command line or configuration file|
|Web Interface Port (httpd)||8080||VoltDB start command line or configuration file|
|Web Interface Port (with SSL enabled)||8443||VoltDB start command line or configuration file|
|Internal Server Port||3021||VoltDB start command line|
|Replication Port||5555||VoltDB start command line|
|Zookeeper port||7181||VoltDB start command line|
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
$ 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.
org.voltdb.client.Client voltclient; voltclient = ClientFactory.createClient(); voltclient.createConnection("myserver",12345);
boost::shared_ptr<voltdb::Client> client = voltdb::Client::create(); client->createConnection("myserver", 12345);
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 configuration file using the <admin-mode> tag or on the command line using the
--admin flag. For example, the following configuration file sets the admin port to
<deployment> ... <admin-mode port="2222" /> </deployment>
The same effect can be achieved using the --admin flag on the command line:
$ voltdb start -l ~/license.xml \ --dir=~/mydb -H serverA \ --admin=2222
When the admin port is set in both the configuration file and on the command line, the command line setting supersedes the configuration file.
The web interface port is the port that VoltDB listens to for web-based connections. This port is used for both the
JSON interface and access to the VoltDB Management Center. There are two related attributes associated with the web
interface. The first attribute is whether the port is enabled. If the port is not enabled, then neither the JSON interface
nor the Management Center are available from the cluster. The second attribute is which port to use. (Note that you can
also use the
--http flag on the command line to set the httpd port.) By default, the web interface is
enabled and the default port is 8080.
You can also enable SSL (Secure Sockets Layer) encryption on the web interface so that all interaction uses the HTTPS protocol. When SSL is enabled, the default port changes to 8443. See Section A.5.8, “SSL Encryption (Including HTTPS)” for information on enabling encryption in the configuration file.
In addition to the overall availability and port for the web interface, you can also specify separately whether the
JSON interface is available. 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. 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"/> </httpd>
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:
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. 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
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 configuration file.
On the command line, use the
--replication flag to specify a different port (and, optionally,
a different network interface):
$ voltdb start -l ~/license.xml \ --dir=~/mydb -H serverA \ --replication=6666
In the configuration file, specify the replication port number using the
port attribute of the
<dr id="3" port="6666" />
Adding the replication port to the configuration 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 configuration file and on the command line, the command line argument takes precedence.
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
VoltDB lets you enable Secure Socket Layer (SSL) encryption for all of its externally-facing interfaces: the web port, the client port, and the admin port. You can either enable SSL for just the web port or for all three external ports.
To enable SSL encryption you need an appropriate SSL certificate. How you configure SSL depends on whether you create a local SSL 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 SSL for security in the Using VoltDB manual for an example of creating your own certificate.)
You enable SSL 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>
By default, when you include the <ssl> element in the configuration file, SSL 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 SSL, the default web port changes from 8080 to 8443.
You can explicitly enable or disable SSL encryption by including the
attribute. (For example, if you want to include the key store and trust store in the configuration but not turn on SSL
during testing, you can include
enabled="false".) You can specify that the client and admin API ports
are also SSL encrypted by adding the
external attribute and setting it to
true. For example, the following configuration sample, explicitly enables SSL for all three
<ssl enabled="true" external="true"> <keystore path="/etc/mydb/keystore" password="twiddledee"/> <truststore path="/etc/mydb/truststore" password="twiddledum"/> </ssl>
Note that you cannot disable SSL encryption for the web port separately. SSL is always enabled for the web port if you enable encryption for the other two external ports.
 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.