Guralp Systems Limited
MAN-EAM-0001 - Platinum User's Guide

PreviousNext

1. Introduction 2. First Steps 3. Configuration System Overview 4. Firmware Upgrades 5. Data Handling Overview 6. Configuring Networking 7. Digitiser Configuration 8. Digitiser Synchronisation 9. Receiving Data 10. Recording and Retrieving Data 11. Transmitting Data 12. Building Networks 13. Monitoring Operations 14. Appendices 15. Revision history

Section Index: 12.1. GDI-link 12.2. Güralp Secure TCP Multiplexer

Chapter 12. Building Networks

12.1 GDI-link

The GDI-link protocol provides the most efficient means of exchanging data between two systems running Platinum firmware. GDI is the native data format of the central data multiplexer, the gdi-base module, and GDI-link allows highly efficient, low latency data exchange between two such multiplexers without the overhead of any additional protocol conversion. State of health information is attached to samples before transmission.

GDI links have transmitters, which send data, and receivers which receive it. These terms do not refer to the direction of initiation of the network connection: a receiver can initiate a connection to a transmitter and vice versa.

A single GDI-link receiver can accept data from multiple transmitters and a single transmitter can send data to multiple receivers, allowing maximum flexibility in configuring seismic networks.

12.1.1 The GDI-link transmitter

To configure a GDI-link transmitter, connect to the CMG-EAM configuration system via either the web interface (select “All options”) or by using gconfig from the command line interface. From the main screen select “services”, then “GDI link transmitter”. The next screen shows a list of all GDI link transmitter instances that have been configured on the CMG-EAM.

In most circumstances you will only need a single GDI link transmitter but this screen allows you to create more if desired.

To configure the transmitter, click on the link corresponding to the required instance. You will see the following screen (only the top part of which is shown here):

The description of the instance can be changed if desired. This may be useful if you have multiple instances. This description is seen when viewing running services or configuring instances. It is not seen by the clients.

Subsequent instances can be enabled or disabled with a check-box but this is absent from the page for the default instance because the default instance is always enabled.

The instance name, as seen by the client, can be set in the first field under “Network settings”. A suitable default is used if this field is left blank.

If the CMG-EAM has multiple network addresses, it can be restricted to listen for incoming connections on only one of them by entering its address here. If left blank, the transmitter will listen on all available instances.

The default service (port) for the transmitter is 1565 but an alternative port can be entered here if required.

Backfill is the process whereby missing data is recovered. It can be disabled if desired but, in most cases, you should leave this enabled.

The remainder of the screen contains a table within which you can configure the GDI link clients to which this transmitter should send data.

For each client, you should set:

12.1.1.1 Additional options available in expert mode

The following additional options appear when in Expert mode:

When you have entered all the required information, press Submit.

12.1.2 The GDI link receiver

To configure a GDI link receiver, connect to the CMG-EAM configuration system via either the web interface (select “All options”) or by using gconfig from the command line interface. From the main screen select “services”, then “GDI link receiver”. The next screen shows a list of all GDI link receiver instances that have been configured on the CMG-EAM.

In most cases, you will only need a single instance and you can enable and reconfigure the Default Instance for your requirements.

Clicking on the Default Instance link brings up the screen shown overleaf.

You can enter a descriptive name for the instance: this is useful if you are configuring multiple instances but, in most cases, this can be set to the hostname of the CMG-EAM.

The Network Settings section allows you to set an optional “client name” which will be visible from the GDI link server.

If the GSL-EAM has multiple network addresses, you can limit the GDI link receiver to use only one of them by entering it in the “Local IP address” field. If left blank, the receiver will listen on all configured addresses.

The default GDI link port is 1566 but this can be over-ridden if desired - you would want to do this if you had multiple instances running on the same address - by entering a port name or number in the “Local port/service” field.

Backfill is the process whereby missing data is recovered. It can be disabled if desired but, in most cases, you should leave this enabled.

The remainder of the screen contains a table within which you can configure the GDI link servers to which this receiver should listen.

For each server, you should set:

When you have entered all the required information, press Submit.

12.2 Güralp Secure TCP Multiplexer

The Güralp Secure TCP Multiplexer (GSTM) is a method by which TCP and UDP connections can be tunnelled in both directions over a single TCP connection. It is an essential tool in situations where local network service providers cannot provide fixed (static) IP addresses.

For example, in an installation involving a single, central data collection point and multiple, remote sensor sites it is sometimes impractical for the sensor sites to be allocated static IP addresses. Using GSTM allows the remote sites to initiate a single GSTM TCP connection to the central site. Once established, further TCP and UDP connections can be initiated in either direction: their packets are tunnelled over the GSTM link.

If no sites in an array can be assigned fixed IPs, including the central data collection point, a GSL-EAM or GSL-NAM can be installed anywhere that has a fixed IP address and used as a communications hub. All sites initiate GSTM connections to the hub, which can then act as a communications router, forwarding individual connections as required.

The initial link is established from a GSTM client to a GSTM server.

12.2.1 The GSTM Client

To set up a GSTM client on the CMG-EAM, connect to the CMG-EAM configuration system via web or terminal. From the main screen select “Services”, then “Guralp secure TCP multiplexor client”. The next screen shows a list of all GSTM client instances that have been configured on the CMG-EAM.

To configure a GSTM client, click “Create new service instance”. The resulting screen allows you to configure the parameters of the new instance.

The “User description” field allows you to enter a mnemonic description of this instance, which may be useful if you intend to run multiple instances. The client can be set to start automatically when the CMG-EAM boots by clicking the “Enable” check-box, or deleted from the system entirely by clicking the “Delete” check-box.

The client will automatically connect to a GSTM server who's DNS name or IP address is specified in the “Server” field, using a port who's service name or number is specified in the “Port/service” field. The client identifies itself to the server using a username: this can usefully be set to the hostname of the CMG-EAM.

Note: The username is the means by which the server refers to this client.

GSTM communication is encrypted using TLS. Each end of any GSTM link needs to be configured with the same pre-shared key. If the server has already been configured, the server administrator will give you a value for the “Encryption Key” field; Otherwise, enter a random string into this field and let the person administering the server know what you have used.

If the GSTM link fails for any reason, it is automatically restarted. There may be situations where the link cannot be restarted so, to prevent almost continuous restart attempts and consequent processor thrashing, a time delay is implemented between a link failure and a restart attempt. This defaults to thirty seconds but a different value can be configured if desired by entering it in the “Exit delay” field.

If a configured link carries no traffic for an extended period, the client will send “watchdog” packets to the server. This serves two functions: it reassures the client that the link is still usable and it defeats any “automatic disconnect on idle” mechanisms which may be active on some links. The time, in seconds, between such watchdog probes can be configured by entering a value in the “Watchdog interval” field.

If the watchdog packets do not elicit a response from the server, the link is assumed to have failed and, optionally, an additional service can be started in response. This will typically be another GSTM client in order to establish a back-up link. The GSTM client to be started should be identified here by its service descriptor, which takes the form gstm-client.n where n is an integer: 0 denotes the first configured client instance, 1 the second and so on.

When the GSTM link is established or re-established, it is possible to run an arbitrary command. Any text entered in the “Link established command” field is passed to the Linux shell for execution, so this can be a single command or the path to a shell script to execute multiple commands. Please contact Güralp support if you need assistance with this feature.

12.2.2 The GSTM Server

GSTM clients initiate connections to GSTM servers. To configure a GSTM server on the CMG-EAM, connect to the CMG-EAM configuration system via web or terminal. From the main screen select “Services”, then “Guralp secure TCP multiplexor server”. The next screen shows a list of all GSTM client instances that have been configured on the CMG-EAM.

This screen lists all currently configured server instances. Click on any server in the list to reconfigure it or, to create a new instance, click on “Create new service instance”.

The following screen appears (shown here in parts):

The “User description” field is useful if several instances are to be created. Enter meaningful names here to help distinguish between them.

An instance can be set to start automatically when the CMG-EAM boots by ticking the “Enabled” check-box and deleted entirely by ticking the “Delete” check-box.

If the CMG-EAM has multiple IP addresses, the GSTM server can be constrained to listen on only one of them by entering its address in the “Bind host” field. If this field is left empty, the server will listen on all available IP addresses.

In the “Service port” field, enter the service name or port number on which you want the server instance to listen. If you are configuring multiple server instances, each needs a unique service/port. The service name to port number mapping is stored in the standard Linux file /etc/services, which can be edited from the command line.

The server is capable of generating TCP keep-alive packets in order to defeat any automatic “disconnect on idle” mechanisms which may be present on the link. Tick the “TCP keepalive” check-box to enable this feature.

Like the GSTM client, the GSTM server also generates watchdog packets to monitor for link failure. These may also be more effective at maintaining a link than TCP keep-alives because some network devices automatically block and/or spoof keep-alive packets. Watchdog packets are sent after a certain amount of time when the link appears to be idle and at regular intervals thereafter until traffic is detected. This time interval can be configured by entering an integer value, in seconds, in the “Watchdog interval” field.

A single GSTM server instance can accept simultaneous connections from multiple clients. For each client, a row in the “Client setting” table needs to be filled in.

The “Client name” column should contain the username, as configured in the GSTM client. The encryption key should match that configured in the client (see the notes in the client configuration section on page 161.for more information).

The GSTM server can run an arbitrary command when a client successfully initiates communication. Any text entered into the “Startup command” column is passed to the Linux shell for execution. The path to a shell script can be entered here if it is required to run multiple commands. Contact Güralp support if you need assistance with this feature.

An active GSTM link can forward arbitrary TCP connections to the clients from any host that can access the server. The system is very flexible but complex configurations can become confusing. We suggest you adopt the following strategy:

When the table is full, press the submit button to add extra entries if necessary.

Remote machines wishing to access services on clients via the GSTM server then need only configure a route to the appropriate new address. Default port numbers can then be used in applications such as browsers and Scream!, reducing the amount of configuration required.

Another strategy would use a single address and port-number mapping to achieve the same goals. This is equally effective but requires that remote machines wishing to access services on clients via the GSTM server use non-standard ports for those services. Many people find address mapping with direct port correspondence, as described above, easier to work with.

PreviousNext

1. Introduction 2. First Steps 3. Configuration System Overview 4. Firmware Upgrades 5. Data Handling Overview 6. Configuring Networking 7. Digitiser Configuration 8. Digitiser Synchronisation 9. Receiving Data 10. Recording and Retrieving Data 11. Transmitting Data 12. Building Networks 13. Monitoring Operations 14. Appendices 15. Revision history