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:
the Peer name: this should match the server name configured on the
the Remote host: this is the DNS name or IP address of the GDI link client
the Remote service/port: the default is 1566 but, if you have configured a different port on the GDI link client, you should enter the same port here.
Enable at startup - this check-box controls whether
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:
the peer name: this should match the server name configured on the
the remote host: this is the DNS name or IP address of the GDI link server
the remote service/port: the default is 1565 but, if you have configured a different port on the GDI link server, you should enter the same port here.
enable at start-up
filtering: you can filter by sample rate or channel names
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:
Pick a private sub-network, not used elsewhere, to map to the clients. Nominate an address in this subnet to represent each client. For example, if you have seven clients, you could use addresses 10.99.0.1 through to 10.99.0.7 inclusive.
Configure all of these addresses as additional IP addresses on the sever. To do this, click on “Interfaces” under “Networking” in the “Configuration” section of the left-hand-side menu in the web interface or, if using the command line, choose “Networking” from the main menu in gconfig. Select the appropriate interface (typically eth0) and, on the resultant page, scroll to the bottom and click the “Expert” button. Scroll down to the “IP aliasing” table and enter all of these addresses in CIDR format, one per line, into the table. CIDR format requires that the number of “network bits” be entered after the IP address, separated by a slash (eg 10.99.0.1/24). Unless you have more than 256 clients, you should use 24 network bits. When the table is full, press the submit button to add extra entries if necessary.
Return to the GSTM server configuration page. For each combination of client and service/port that you wish to access, fill in a row of the table:
“Listen address” should contain the address of the client on the private subnet that you have just allocated.
“Listen service/port” should contain the service name or port number of the service to which you wish to connect. For example, to access a web server at a client, you would enter http or 80.
“Target client” should contain the username entered when configuring the GSTM client on the target CMG-EAM.
“Target service/port” should contain the same number as the second column: “Listen service/port”.
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.