Open main menu
SUPPORT DOCUMENTATION

Networking with Scream

Scream uses its own protocol for transmitting seismic data over the Internet. The Network Control window within Scream! lets you manage a seismic array with multiple data sources, using this protocol.

There are two ways a Scream! client can receive data from a server.

“Server push”

For this method, the Scream! server keeps a list of clients and periodically sends them data in UDP packets.

Scream-server-protocol-1

If the client is behind a firewall, as in the diagram, you must open the relevant UDP port in the firewall before any data will be received. Most firewalls are configured to allow outgoing packets through, so the server does not need special configuration. However, it is likely that you will want the server to be able to aid in gap recovery (see below), for which you need to open the TCP port with the same number.

To configure Scream! to push data to a client, click the My Server tab on the Network Control window, right-click in the top box (the client list), and choose Add… from the context menu:

Scream's client context menu

Into the resulting dialogue, enter the client’s IP address and a port number, separated by a colon (':'). The port number will be used as the destination port for data sent to the remote consumer. Port 1567 is often a good choice but you can pick any valid, unused port that you wish.

Scream's 'add client' dialogue

Once you have entered the correct information, click the 'OK' button to close the dialogue.

Back in the Network Control window, tick one or both of the Transmit data from local _Com ports and Transmit data from _Network check-boxes, as appropriate:

Scream's 'My server' pane in the network control window

Open the port chosen above for both outgoing UDP and incoming TCP connections on the server’s firewall, if applicable.

On the client side, view the My Client tab, and tick the Receive UDP Data box.

the 'My client' tab

Set the Port used for all network communications to the port number you used above. Configure the client’s firewall to unblock this port for UDP.

“Client pull”

In this method, the client keeps track of its own servers and requests them to send it data using the commands GCFSEND and GCFSTOP. Both commands and data are sent over UDP.

Scream-server-protocol-2

In this situation, UDP ports need to be unblocked at both the server and the client side, since the server must be able to receive these UDP commands.

To configure Scream! to request data from a server, click the My Client tab of the Network Control window, right-click in the top box (the server list), and choose Add UDP Server…. Enter the server’s IP address and port number, and click OK.

On the server side, view the My Server tab, and tick the Transmit data from local Com ports box. Check that the Port used for all network communications matches the port number you used on the client. Unblock this port for UDP connections on both server and client firewalls. Also unblock the TCP port with the same number on the server’s firewall (see below.)

Scream! will normally only transmit data it receives from directly-connected instruments, and not data it receives over the network. This helps to prevent network loops. A command-line option is available which allows you to override this behaviour: see the Scream! manual for more details.

Forwarding Network Data

When Scream! receives data over a network connection, it is configured by default not to forward it back out over the network. This is to prevent the inadvertent creation of forwarding loops which could rapidly consume sufficient system resources to render the host computer unusable.

If you wish to forward data which has been received over a network, you should invoke Scream with the -nettx option, which removes this safeguard. A check-box labelled “Transmit Data from Network” will appear in the “My Server” pane of the “Network Control” window. When ticked, packets received by Scream! over the network will be forwarded on to network clients. Please take particular care when planning the data routes in order to avoid any loops.

The -nettx option has been removed in Scream! 4.5 and later but it is still necessary to tick the Transmit Data from Network check-box if you want to forward data which has been received over a network.

If you intend to use this option regularly, it is convenient to provide it in a start-up script under Linux or, under Windows, create a new application shortcut with this argument embedded. To do this, right-click on the desktop and select New… and then Shortcut. In the dialogue box that appears, click the “Browse” button and navigate to the Scream! directory (typically C:Program Files (x86)\Guralp Systems\Scream4.6). Double-click on the Scream! executable and then add a space and -nettx after the application path. The result should look like this:

shortcut creation screen-shot

Click the “Next” button to continue and give the shortcut a suitable name. If desired, the resulting shortcut can be dragged and dropped onto the start button in order to provide a start-menu icon.

Gap recovery

When gaps occur in the data stream, for whatever reason, Scream! clients will attempt to recover them by connecting to the server over a TCP link and requesting data. These attempts occur at the same time as normal data reception. When the server receives a TCP re-transmit request, it replies (if it can) with the relevant data over the same TCP connection. Thus, for a “server-push” system:

Scream-server-protocol-3

Because the gap recovery process uses TCP connections, you must open a TCP port on the server’s firewall in addition to the UDP port(s). The port number is the same as for UDP. If you do not open this TCP port, data will still be received, but any gaps that occur will not be filled in.

Unlike UDP connections, TCP connections persist even when data are not being sent. After the client initiates the TCP connection, the server can send the requested data over the same connection. Because of this, you do not need to open a TCP port on the client side.

Network Address Translation (NAT)

Many firewalls and cable modems are set up with Network Address Translation"Network Address Translation" is technique most often used in routers to allow multiple systems with private IP addresses to appear to the public Internet as if they were multiple ports on a virtual system with a single, public I.P address. See Wikipedia's "Network Address Translation" page for more information. active. With NAT, hosts behind the firewall are given addresses on a local IP network, sharing a single outward-facing IP address. When a host behind the firewall creates a TCP connection, the NAT software ensures that the relevant packets are forwarded to the correct host.

When a host on the outside of the firewall attempts to send a packet through, the NAT software cannot tell which host on the inside to send the packets to, so they are blocked. Thus, hosts behind a NAT firewall in its default configuration cannot receive UDP packets at all (since there is no persistent connection), and cannot accept TCP connections from outside. Because of this, a NAT firewall is very effective at preventing attacks from outside.

In order to receive Scream! data from behind a NAT firewall, you must explicitly tell the firewall to forward UDP packets from the Scream! server to the client. This is done using port forwarding. The details of how to set up port forwarding depend on the particular firewall, but they all work by maintaining a list of listening ports and specifying the destination host and port to which traffic arriving there should be forwarded.

Thus if your Scream! client is listening on port 1567, you should manually configure your firewall to pass all UDP packets on port 1567 to the Scream! client’s local IP address.

Scream-server-protocol-4

The TCP recovery procedure is unaffected by NAT, since the client initiates the TCP connection. This means the firewall can automatically determine where to send the received packets.

You can normally configure a NAT firewall to forward several ports to different hosts. As long as each client uses a distinct port (since there is only one outward-facing IP address), you can provide data to any number of clients this way, subject only to the limitations of the firewall.