Configuring Networking for s-Server

This topic contains information on configuring networking for s-Server, including a list of ports used by s-Server, configuring JDBC connections from other hosts, working with multiple NIC cards, and troubleshooting common network problems.

Configuring Ports for Guavus SQLstream

The following diagram summarizes the ports that operate between Guavus SQLstream components:

Guavus SQLstream uses the following ports:

s-Server

s-Server, the central component of the Guavus SQLstream system, listens on port 5570 (SDP2).

In order for applications (including s-Studio and webAgent) to access s-Server directly from a remote computer, the firewall on the host computer for s-Server must allow incoming traffic on port 5570. The firewall on the computer hosting the application must similarly allow outbound traffic on port 5570.

Clients receive data by means of SDP, on default port 5570. ( SDP is SQLstream's streaming data protocol.) SDP connections use TCP transport and require a valid route from the client driver to the server. However, a server can be configured to use a different port, as described below.

Note that the JDBC connection string refers to the SQLstream s-Server using a particular SDP port: jdbc:sqlstream:sdp://host:port. The suffix port is optional, since the SQLstream client driver automatically supplies "5570" as the default SDP port value. However, if the server is actually using a different SDP port, its number must appear explicitly in the connect string.

webAgent

webAgent, the HTTP server that exchanges data with s-Server, listens on port 5580. The firewall on its host computer must allow outbound traffic on port 5570.

In order for applications (including StreamLab and s-Dashboard) to access webAgent directly, the firewall on the host computer for webAgent must allow incoming traffic on port 5580. The firewall on the computer hosting the application must similarly allow outbound traffic on port 5580. Since webAgent handles connections to s-Server, these applications do not need to be open to s-Server (and likely should not be).

StreamLab

StreamLab listens on port 5585 (ROSE) and 5590. It uses webAgent to connect to s-Server. In order to communicate with webAgent, the firewall on its host computer must allow outbound traffic on port 5580.

In order for users to access StreamLab through a browser, the firewall on the host computer for StreamLab must allow outgoing traffic on ports 5585 and 5590.

s-Dashboard

s-Dashboard listens on port 5595. It uses webAgent to connect to s-Server. In order to communicate with webAgent, the firewall on its host computer must allow outbound traffic on port 5580.

In order for users to access s-Dashboard through a browser, the firewall on the host computer for s-Dashboard must allow outgoing traffic on port 5595.

Configuring JDBC Driver Connections from Other Hosts

The instructions in this section enable you to configure the SQLstream s-Server to accept JDBC driver connections from other hosts, even if the server is behind a NAT router.

SDP Requirements

The SQLstream JDBC driver connects to SQLstream s-Server using SDP. SDP requires that the hostnames match at both ends of a remote connection. That means that the server must have

  • An IP address reachable from client systems
  • A host name that resolves to that address for the client (either through DNS or an explicit host name mapping such as an entry in the client's /etc/hosts file)
  • Configuration files that use the resolvable host name or the explicit IP address

Here are the configuration requirements:

/etc/hosts

Many Linux systems will, by default, assign a system's host name to the loopback interface (IP address 127.0.0.1). For a server installation that other systems will connect to, you need to ensure that the host name is explicitly assigned to the external IP address:

127.0.0.1 localhost
a.b.c.d hostName.domain hostName

aspen.properties

The aspen.properties file needs to specify the host name of the server in a way that can be resolved by client systems or else use the IP address:

aspen.sdp.host=<hostName or a.b.c.d>

You can change this setting by editing aspen.custom.properties. See Configuring s-Server Parameters for more details.

JDBC URI

The client system connects to the server via a URI that uses the host name (or IP address) just as specified in aspen.properties:

jdbc:sqlstream:sdp://<hostName>:<port>, autoCommit=false
jdbc:sqlstream:sdp://<a.b.c.d>:<port>, autoCommit=false

The port specified in aspen.controlnode.url must match aspen.sdp.port. The hostName or IP address specified in aspen.controlnode.sdp.host and aspen.controlnode.url must be resolveable/visible from both the client and the server.

Configuration Properties

Both types of connections, for requesting or receiving data, can be configured by setting the properties listed in the table below.

Configuration properties can be found in either aspen.config or in the main properties file, aspen.properties. However, you should not edit these files directly. Instead, you should either create or edit aspen.custom.properties in $SQLSTREAM_HOME. A sample aspen.custom.properties file can be found in $SQLSTREAM_HOME/support).

Configuration Parameter Explanation
aspen.sdp.host Sets an optional hostname (or IP) for SDP. The default is the hostname of the machine or localhost if the hostname cannot be determined.
aspen.sdp.port Controls the port used by SQLstream for Streaming Data Protocol (SDP) connections. Typically, aspen.controlnode.url uses this same port. Defaults to 5570.
aspen.sdp.linkTimeoutMs Minimum number of milliseconds of idle time on a given link before timing out the link on the assumption that the connection is broken or that the peer has crashed. Defaults to 10000.
aspen.sdp.mtu Maximum transmission unit (MTU) for SDP connections. It is the maximum size of a TCP packet in a SDP connection. Defaults to 65536.
aspen.sdp.pingTimerMs Number of milliseconds between sending SDP EchoRequest frames. Echo frames are pings inside of an SDP connection. Defaults to 2000.
aspen.sdp.punctPingInterval Sets the default interval between "ping punctuation marks". To help the timely progress of rows inserted with an implicit rowtime (which is the current system time), the NetRxExecStream periodically emits a rowtime bound equal to the current time: this is truthful, since the rowtime of a forthcoming row will be a timestamp in the future. Because these pings cost a small amount of execution work, there is a cost to this liveness, and hence the interval between pings can be adjusted. Ideally this might be an attribute of each insert statement or of each stream. At present, there is a global value: set from this parameter. In milliseconds. Defaults to 40.
aspen.sdp.rxblocksize Number of independent blocks a driver can receive. Generally the number of statements running on a specific driver. This is rarely used. Minimum value is 2. Maximum value is maximum value of Java Integer class. Defaults to 4.
aspen.sdp.streamWindowHighWaterMarkRatio Defines the ratio of the current window to the maximum window at which point the window is published. Defaults to 0.75
aspen.sdp.throwOnProtocolError Throw exception: If true and link becomes mis-synchronized, exception is thrown. Exists for debugging; for production, should be set to false. Defaults to false.
aspen.cluster.uuid The magic cluster key. The UUID of the cluster to which this node belongs. Allows authentication of a node in the cluster and for multiple clusters to exist on the same network. Defaults to 12345678-90ab-cdef-1234-5678abcdef90.
aspen.sdp.blocksize Maximum size of a block of row data sent from the driver to the server. If multiple rows can fit inside of a buffer of size blocksize, then they will be packed into one TCP packet. MTU doesn't effect how many tuples are in a TCP packet, it only limits the maximum size of a TCP packet. Defaults to 65536, the maximum. Minimum value is 512.

Working with Multiple NIC Cards

SQLstream generally binds its server to the "ANY" TCP IP address (0.0.0.0) which allows it to listen for network connections from any IP for which the host is receiving traffic. Generally this is only one public IP address and one loopback IP address (usually 127.0.0.1).

On some more complex production server environments, machines can have multiple NIC cards which might handle traffic on different IP addresses and/or networks. In these environments, SQLstream can be configured to listen for network connections upon one and only one IP address if desired. The default is still to bind to all IPs.

To bind to a single IP, you must enter the desired IPv4 address in the aspen.custom.properties file as both the aspen.controlnode.sdp.host property and aspen.controlnode.url property. In the case of the aspen.controlnode.url property, enter the value in the following format

sdp://<IPv4 address>:<port>

The port may be omitted and in this case you should remove the trailing : as well.

Troubleshooting Common Network Problems

  • Firewalls. Make sure that the SDP ports used by SQLstream are open and that valid routes between the driver and server exist.
  • NATs. Drivers can be behind NATs but if the server is behind a NAT it will require port forwarding unless both the driver and server are behind the same NAT. This is because a driver must be able to open connections on the server.