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

Chapter 6. Configuring Networking

Platinum firmware includes comprehensive support for Ethernet networking. Features include VLAN (virtual network) support, an iptables firewall and IPV6 support

Minimal network configuration is described in section 2.2. and those steps will allow you to communicate with your device over a network. The configuration changes made in that way will not, however, survive a reboot: to make the configuration permanent, follow the procedures in this section.

6.1 Configuring physical network interfaces

The hardware of a CMG-DCM, CMG-EAM or CMG-DAS has a single physical network interface while CMG-NAMs may be equipped with multiple physical network interfaces. Platinum firmware follows the standard Linux convention of naming the first physical network interface present on a system eth0 and subsequent interfaces eth1, eth2, etc.

To configure a physical network interface from the web interface, select “Networking” from the “Configuration” → “All options” menu or select the “Interfaces” short-cut from the “Networking” menu. To configure a physical network interface from the command line, start gconfig and select “Networking” from the top level menu.

The following screen is displayed (only the web version is shown here: the character version is laid out and behaves identically):

The first link on this screen takes you to the configuration page for the first physical network interface. If your hardware has multiple physical interfaces, you may need to create configurations for them using the “Create a new interface” button. Once created, the can be configured in an identical manner to eth0, as described below.

6.1.1 Configurable parameters in standard mode

The configuration form is large and is shown here in parts.

The first field, Device, is not editable. It displays the name of the network interface being configured.

The MAC address field is also not editable. It shows the Media Access Control address of the adapter's hardware. It is often useful to know this when configuring DHCP servers: by binding an IP address to a particular MAC address, the DHCP administrator can ensure that the device retains the same IP address across reboots.

The Description field allows the operator to modify the description of this interface in configuration dialogues and error messages. This is of limited value when there is only a single interface but, for example, when a CMG-NAM has multiple interfaces, it may be useful to rename them in order to reflect their logical function rather than their physical position.

The Enable interface check-box can be ticked in order to enable the interface or cleared in order to disable it. No other configuration settings are changed when the interface is disabled, allowing use of the interface to be suspended without deleting the configuration.

The Startup enable check-box controls whether the interface is enabled automatically when the unit boots.

The Enact on submit check-box controls whether changes made using the rest of this form take effect immediately or are only written to the configuration files. When this box is cleared, changes will only take effect the next time the unit is booted or the interface is reconfigured with this box ticked.

The Configuration method drop-down menu offers the following choices:

The remainder of the screen looks like this:

The IP address field is only used if the Configuration method drop-down menu is set to “Static”. The address should be entered in CIDR format, where the address is followed by a slash and then the number of bits defining the netmask, e.g. 192.168.0.1/24 for IPV4 or 2001:db8::/32 for IPV6.

For more information about CIDR, please refer to http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing.

The Default route (gateway) field should be populated with the IP address of the default router. If more complicated routing configurations are required, these can be entered in expert mode.

6.1.2 Configurable parameters in expert mode

The following additional parameters are available when in expert mode.

Media type/speed - This is a drop-down menu offering the following options for controlling the communication speed and duplex mode of the network link:

MTU - This text field allows the Maximum Transfer Unit to be set for the network link. This parameter controls the maximum packet size used for outgoing network packets. If any segment of a link between two systems has a restriction on packet size, larger packets flowing across the link must be fragmented - broken into smaller parts - and then re-assembled on arrival. This is inefficient and can badly affect the throughput of a link. In such situations, it makes sense to restrict the maximum packet size at the sender (to match the limitation) so that all packets can pass unimpeded.

There is no method to empirically determine the optimum MTU for a given link from the CMG-EAM itself but, if the link is to a PC (or, in the case of, say, a link between two CMG-EAMs, one end can temporarily be replaced by a PC) the PC can be used to investigate the link properties and the correct value can be obtained.

For more information, please see http://www.dslreports.com/faq/695. Note that, if testing from a PC running Windows, the MTU of the Windows PC should be set to 1500 before starting the test.

The Extra dhcpcd arguments field can be used to change the operation of the DHCP client. Please see http://man-wiki.net/index.php/8:dhcpcd for information about what options can be added here.

The Extra ip addr arguments field can be used to tune the operation of the network interface. A non-standard broadcast address can be specified by entering broadcast broadcast_address. For other settings that can be used here, please see http://linux.die.net/man/8/ip.

The Nameserver field should be used to specify the IP address of the DNS server for your network. This field must be set correctly before internet firmware upgrades can be used. A secondary DNS server's address can be added in the Backup nameserver field.

The Default route (gateway) field should be populated with the IP address of the gateway router, for access to other networks or to the Internet. This field must be set correctly before internet firmware upgrades can be used.

The ip route arguments field can be used to modify the invocation of the ip route add command in order to, e.g., set the route metric. The options that can be set here are mostly highly technical and should rarely be required. Please see http://linux.die.net/man/8/ip for more information.

Two tables appear at the the bottom of the form when in expert mode: the IP aliasing table and the Extra routes table. These are shown in the screen-shot below.

The IP aliasing table is used to add extra addresses to this interface, a practice known as multi-homing. By default, the table displays three blank rows but, should you need more, complete the first three and submit the form: it will be redrawn with extra blank rows. The columns in the table are:

The second table, Extra routes, is used to add extra network and host routes to allow access to networks other than those connected via the default router specified earlier, or to force packets to traverse a particular route despite the default router setting. By default, the table displays three blank rows but, should you need more, complete the first three and submit the form: it will be redrawn with extra blank rows. The columns in the table are:

6.2 Virtual network (VLAN) interfaces

Platinum firmware supports the use of Virtual Local Area Networks (VLANs) to partition network traffic on the same physical subnet. Virtual interfaces can be created and assigned to a particular VLAN tag (ID) and a particular physical interface. A full discussion of VLANs is beyond the scope of this document.

To configure a virtual network interface from the web interface, select “Networking” from the “Configuration” → “All options” menu or select the “Interfaces” short-cut from the “Networking” menu. To configure a physical virtual interface from the command line, start gconfig and select “Networking” from the top level menu.

The following screen is displayed (only the web version is shown here: the character version is laid out and behaves identically):

The second option, “Create a new VLAN interface” takes you to the following screen (shown here in parts):

6.2.1 Configurable parameters in standard mode

The Hosting Interface drop-down menu is populated with a list of the physical interfaces present on the system. Select the physical interface over which you wish this virtual interface's traffic to flow.

The VLAN tag text field should be populated with the required VLAN tag. This identifies packets sent over this interface as belonging to the specified VLAN.

The Description text field can be edited to provide a more useful name for the interface.

The Enable interface check-box can be ticked in order to enable the interface or cleared in order to disable it. No other configuration settings are changed when the interface is disabled, allowing use of the interface to be suspended without deleting the configuration.

The Startup enable check-box controls whether the interface is enabled automatically when the unit boots.

The Configuration method drop-down menu offers the following choices:

The remainder of the screen looks like this:

If DHCP is not being used, the IP address text field should be populated with the required address in CIDR format, where the address is followed by a slash and then the number of bits defining the netmask, e.g. 192.168.0.1/24 for IPV4 or 2001:db8::/32 for IPV6.

For more information about CIDR, please refer to http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing.

The Default route (gateway) field should be populated with the IP address of the default router for this VLAN. If more complicated routing configurations are required, these can be entered in expert mode.

6.2.2 Configurable parameters in expert mode

A set of additional parameters are available when in expert mode. These are identical to the additional parameters on the physical interface configuration screen, as described in section 6.1.2 on page 58 and are not discussed further here.

6.3 Network Time Protocol (NTP)

The Network Time Protocol (NTP) is a method of synchronising the clocks of computer systems over networks, including those with variable latency, such as packet-switched networks. Platinum firmware include a fully-featured NTP implementation, which can be used to keep the system clock synchronised to external time sources, such as Internet NTP servers, connected digitisers and connected GPS receivers.

CMG-EAM hardware includes a battery-backed real-time clock (RTC) module which can retain system time with tolerable accuracy during periods of power loss. This is also true of CMG-NAMs and CMG-DAS units incorporating CMG-EAM modules but not of CMG-DCMs and earlier CMG-DAS units with internal CMG-DCM modules - their system time will revert to January the 1st, 1970 after each power-cycle.

The system clock is used to provide time-stamps for log-file messages and can also be used to generate NMEA and PPS signals, emulating a GPS receiver, in order to synchronise external equipment, such as a CMG_DM24 digitiser module. This technique is described in section 8.5.

The NTP subsystem displays its status in a panel of the “System status” display of the web interface. This panel includes the current system date and time, the lock status, estimated error and current clock source.

To configure NTP from the web interface, select “Networking” from the “Configuration” → “All options” menu and then click on the link for “Network Time Protocol (NTP) daemon” or select the “NTP” short-cut from the “Networking” menu. To configure NTP from the command line, start gconfig, select “Networking” from the top level menu and then select “ Network Time Protocol (NTP) daemon”.

The following screen is displayed:

6.3.1 Configurable parameters in standard mode

The Acquire time from connected GPS check-box tells the system that a GPS receiver has been attached to one of the serial ports and is to be used as a clock source. The serial port used must be configured with a “Port function” of “NMEA in. Receive GPS data for NTP” and, when used with Güralp supplied GPS receivers, must be set to 4,800 baud operation, as described in 8.5 on page 93. No further configuration is required.

The Acquire time from connected digitisers check-box tells the system that one or more attached digitisers are to be considered as accurate clock sources. For this to work, the digitiser must produce “RTSTATUS” packets. CMG-CD24 digitisers and digital sensors incorporating them, such as the CMG-6TD, will do this unconditionally when running firmware version 279 or later. CMG_DM24 digitisers can have these packets enabled or disabled via software. They are automatically enabled if the digitiser is ever configured via the interface in Platinum.

The Server address table allows a number of Internet or network-accessible NTP servers to be listed for use as clock sources. You can specify these servers by either IP address or hostname. If names are used, they must either be listed in the local hosts file (/etc/hosts) or resolvable via the Domain Name Service (DNS). Entries in this table can be deleted by ticking the associated check-box and submitting the form.

6.3.2 Configurable parameters in expert mode

The only difference between standard and expert mode on this screen is the addition of a Server options column to the NTP servers table.

This text field can be used to provide additional control over how the NTP daemon uses the server. The options are described in the standard ntp.conf manual page, available on-line at http://linux.die.net/man/5/ntp.conf.

6.4 Email configuration

Platinum firmware is capable of sending system alerts via email over the Internet or over a local area network.

This feature is currently unused but is provided for future expansion.

To configure email from the web interface, select “Networking” from the “Configuration” → “All options” menu and then click on the link for “Mail Transfer Agent (e-mail service)” or select the “Mail” short-cut from the “Networking” menu. To configure NTP from the command line, start gconfig, select “Networking” from the top level menu and then select “Mail Transfer Agent (e-mail service)”.

The following screen is displayed:

6.4.1 Configurable parameters

The Enable MTA check-box is used to control whether the mail transfer agent is started automatically at boot time. If this check-box is left clear, the MTA can still be started manually from the services menu (see section 13.2.4 on page 181).

Most email configurations use a “smart host” to route mail. This can greatly simplify the administration: only one node on a network, the smart host, needs to be configured to know about any intricacies of the system and all other machines need only know the location of the smart host. If the Smart host text field is populated with the name or address of of such a host, all mail is sent directly to that host for further routing. If this field is left blank, the MTA will attempt to use DNS to discover the mail host(s) for any given address and then deliver mail directly.

The optional Mail host identity text field specifies the hostname from which outgoing emails should appear to originate. If this field is left blank, the real hostname is used.

The Postmaster alias text field allows you to specify the address to which all internally generated mail should be sent: This should be set to the email address of the CMG-EAM's administrator.

6.5 Configuring the SSH Server

The CMG-EAM has an ssh server running on its Ethernet port which allows remote terminal access.

The ssh server, sshd, can not currently be configured using gconfig although it can be configured via the web interface. If web access is unavailable, it is possible to configure sshd from the command line by directly editing the configuration files.

6.5.1 Configuring sshd via the web interface

From the main screen of the web interface, under Configuration, Networking, select “SSH server”. The screen is not reproduced in this document as it is particularly large, due to the amount of explanatory text. Each option is, however, discussed below.

The version of sshd installed (openSSH) supports both version 1 and version 2 of the ssh protocol. Version 1 has some well-known weaknesses and should be avoided if at all possible, but some commercially available systems still do not support v2, so v1 is supported here for compatibility. The Enable SSH Protocol v1 check-box should be cleared unless your ssh client cannot support v2 or cannot be upgraded to support it. Click the Change server options button to commit this change.

If you want to download the ssh server's public key to allow the connecting host to check and verify the CMG-EAM's identity, use the relevant Download server public key button – there is one each for protocol versions 1 and 2. There is also the capability to command the CMG-EAM to create a new private/public key pair from this screen.

To configure password-less login to the CMG-EAM, you can upload the public key of the connecting machine to the CMG-EAM using the New client key section. Browse the connecting host's file system for the key file (usually named id_dsa.pub) and upload it here. This will allow password-less root access to the system from that machine.

Client keys which have been uploaded are displayed in the Authorised client keys section. Any existing authorised keys can be removed: Select the check-box next to the key you wish to remove and click Remove selected keys.

Note: password-less login via ssh v2 is, perhaps counter-intuitively, the most secure way to access your CMG-EAM. There is a useful discussion of the ssh protocol and full details of its usage at the site http://tinyurl.com/whyssh

Note: Systems are shipped with a pre-authorised client key to which Güralp Systems' support staff have the matching key. This allows us to access you unit and reset the root password should you forget it. You are free to delete this key if you wish.

There is a second (and significantly more complicated) way of resetting the root password if you have physical access to the system. Please contact support if you find yourself in this situation.

6.5.2 Configuring sshd from the command line

This is a complex issue and use of the web interface is strongly encouraged unless you are familiar with Linux text editors, configuration files and sshd itself. The configuration file is located at /etc/ssh/sshd_config and its syntax and semantics are described at http://man-wiki.net/index.php/5:sshd_config. More detailed discussion is beyond the scope of this document.

6.6 Working with PPP

PPP, or Point-to-Point Protocol, is a data link protocol that can carry IP packets over a serial link between two networking nodes. It can provide connection authentication, transmission encryption privacy, and compression. Platinum firmware includes an implementation of PPP which can be used to provide network links between sites or to connect to an Internet Service Provider (ISP). A number of “chat scripts” are provided, allowing connection negotiation and establishment over PSTN, GPRS and satellite modems.

6.6.1 Setting up a PPP Connection

To configure a PPP connection, you will need a user ID and authentication code (the PAP secret) as required by the remote server. In addition, a dial up (chat) script specific to the service you are using must be created. If one does not already exist for your service, please contact Güralp support.

To set up this connection, connect to the CMG-EAM configuration system via either the web interface or by using gconfig from the command line interface. From the main screen select “Serial ports” and select the port to which the modem is connected. Change the function of the port to “PPP. PPP network connection”, with the correct baud rate for the modem. Click “Submit” to save these changes. Go back to the configuration of the serial port and click on “PPP network configuration”.

You will see this screen (shown in parts):

Choose the required Connection type from the following list:

The choices available from this menu reflect the chat scripts installed on your system. If you wish to use a satellite modem or GPRS with an ISP other than those listed, please contact Güralp Systems Ltd technical support.

In the Number of seconds to power down modem between calls text field, set the desired time-out for the modem, if required.

The “IP addresses and routing” section of this page handles the network configuration. In active/client mode or when connecting to an ISP, the remote PPP daemon will set these parameters, in which case this section can be left blank.

If you are using PPP between, say, two CMG-EAMs, one should be designated the client and the other the server. The “IP addresses and routing” parameters for the client should be left blank and those for the server completed as follows:

If using IPv4 networking, the Local IP address field should be populated with an IP address from an otherwise unused reserved class C network address range, such as 192.168.123.1 (with no CIDR postfix) and the Remote IP address field should be populated with an IP address from the same network, such as 192.168.123.2 - this address is provided to the client at connection initiation.

If using IPv6 networking, the Local IP address IPv6 and Remote IP address IPv6 fields should be used instead.

If the Default route check-box is ticked, the PPP daemon will modify the routing table on successful connection, setting the remote end of the PPP link as the default gateway.

The final section of this page handles PPP security:

Enter the User ID and PAP secret given to you by your service provider in the appropriate fields. Click “Submit” to save the changes.

The standard Linux commands ppp-on, ppp-off, ip, ping, and traceroute are available from the command line for use in controlling and testing PPP connections but it is also possible to configure a “watchdog” service to monitor a PPP connection and automatically restart it should it fail. This is described in the next section.

6.6.2 Monitoring a PPP connection

PPP connections can be monitored and, should they fail for any reason, automatically restarted. To configure this facility, connect to the CMG-EAM configuration system via either the web interface or by using gconfig from the command line interface. From the “All options” menu, select “System services” and then, under Network Utilities, select “pppd-watchdog -- PPP link watchdog”.

You can create a number of watchdogs if you are running PPP on several ports. This screen allows you to select any of the existing watchdog services for re-configuration or to create a new watchdog service.

In this instance, no services are configured, so the only option is to create a new service.

When “Create a new service instance” is selected, the following screen is displayed:

If you are configuring a number of watchdogs, you can use the User description field to give each of them memorable names.

The Enable check-box should normally be ticked but can be left clear if you only want to use the associated PPP connection occasionally.

An existing watchdog service can be stopped and its configuration deleted by selected the Delete check-box and then clicking the “Submit” button.

If the PPP connection relies on a modem link for its transport, there may be a significant delay between instructing the PPP link to start and the connection being established. So that the watchdog does not falsely detect a failed link during this period, it can be instructed to sit idle for a number of seconds before it begins to test the link. The length of the required delay should be entered into the Daemon startup delay field.

Once the start-up delay time has elapsed, the watchdog periodically tests the connection. To ensure that there is a valid end-to-end connection where, for example, a multi-hop link is in use, the exact method of testing is user-configurable: any valid command can be entered into the Test command field and its exit status is taken to represent the link status (zero for link up, non-zero for down). The most common method used is to use the ping command to verify ICMP connectivity to the ultimate remote host, but you are free to use the command or script of your choice here, so long as it returns a non-zero exit status on link failure.

Note: When using ping, you should always use the -c count option or the command will never return.

The contents of the Time between tests field determines how often the configured test is applied. It can be set high to conserve bandwidth or set low to improve failure response times. It can also be used to keep a sparsely-used link alive where a “disconnect-on-inactivity” feature would otherwise interrupt it.

If the link test fails repeatedly, the CMG-EAM is rebooted. The number of failed tests before this happens is controlled by the “Reboot fail count” field.

The ppp watchdog service can be started, stopped and restarted using the “Services” page under the “Control” menu. See section 13.2.4.

6.7 Configuring TCP to serial converters

The CMG-EAM can act as a TCP to serial converter, effectively transporting data between one (or more) of its serial ports and a TCP connection. There are two different modes of operation, as detailed below. Any number of serial ports can be configured as TCP converters, as long as the TCP port numbers do not clash.

In “Simple server” mode, the CMG-EAM listens for incoming TCP connections and, should it receive one that matches its configured rules, accepts the connection and begins copying data between the serial port and the TCP connection.

The CMG-EAM can be configured to only listen on particular addresses and ports, to only accept connections from certain addresses or blocks of addresses and to reject connections from certain addresses or blocks of addresses.

In “Simple client mode”, the CMG-EAM will connect to an external TCP server on a particular address and port and then copy data bidirectionally between the serial port and the network port.

To configure the converter, select “Serial Ports” in the configuration menu, then choose the required port. Set the function to “tcp serial converter”, select the baud rate, and save the settings. You can then use the “TCP serial converter settings” button at the bottom of the page to configure the converter.

The converter's configuration page allows you to choose the mode at the top (“Operation mode”). The other options on the page are only required in certain modes; see below for which modes require which options.

6.7.1 Simple server mode

In Simple server mode, the converter opens the serial port and creates a TCP server socket. Whenever a client connects to the socket, the converter reads raw data from the serial port and writes it to the client, and reads raw data from the client and writes it to the serial port. The serial port hardware control lines cannot be read or altered in this mode.

Simple server mode has two relevant options: the list of addresses to listen to, and an optional list of addresses to filter. The server can listen on multiple simultaneous local ports and addresses (although only one client can be active at a time).

The “Bind host” option is usually left blank. If specified, it is the name or IP address on which this server socket will listen. For example, if you specify “localhost” here, then this socket will only listen for incoming connections on the loopback address, and not on the external Ethernet port. Leave it blank to listen to all addresses.

The “Bind service” option must be specified. It is the TCP port number (1-65535) or service name (such as “tcpserial”) for the socket. This can be anything you choose, although we recommend that you use the names tcpserial, tcpserial1, tcpserial2 and so on through to tcpserial15, which are pre-defined to correspond to port numbers 10002, 10003, through to 10017.

The mapping from port names to port numbers is configured by the conventional Linux file /etc/services which can be edited from the command line if required.

If desired, you can configure a list of addresses from which to accept connections. If no addresses are configured, then all incoming addresses will be accepted. Otherwise, connections will only be accepted if they match an entry in the table with its Reject box unticked. Entries are matched in order; as soon as a match is made, the connection is accepted or rejected, and no further processing is done.

The “IP addresses” fields can each specify a host name, an IP address or an IP address range (given in CIDR format). For example, to accept connections from LAN addresses, you can add the addresses:

6.7.2 Simple client mode

This mode of operation is similar to simple server, except that the CMG-EAM establishes an outgoing TCP client connection rather than listening on a socket. It writes raw data from the serial port to the remote server, and writes raw data from the remote server to the serial port. It does not support the querying or setting of the serial port hardware control lines.

In this mode, only a single option needs to be provided: the contact details for the remote server (IP address and port). The format of this option is “host,service”. The host may be a hostname or an IP address. The service may be a TCP port number or a service name from /etc/services.