Re-purposing remote-assistance

The remote-assistance service is designed to allow Güralp engineers to connect to Platinum systemA "platinum system" is any system running the Platinum operating system. This includes stand-alone acquisition systems such as EAMs and NAMs, DAS units such as the Affinity and DM24SxEAM and digital instruments with built-in acquisition systems such as the 3TDE, 40TDE or 5TDE.s for assistance and diagnostic purposes in situations where an incoming connection is impossible or not convenient. It can be re-purposed to provide a mechanism to contact an instrument connected to a network which does not provide incoming access. This document explains how.

Operational description

The remote assistance system uses a "well-known" intermediary server to allow Platinum systems behind restrictive firewalls to be contacted. The Platinum system makes a single out-going SSH connection to the intermediary server. This connection provides tunnels such that the SSH dæmon on the intermediary server exposes TCP sockets which clients can then use to connect to the Platinum system.

Upon connection to the intermediary server, the client uses SSH's shell-exec mode to invoke a restricted shell program with two arguments: its hostname, and its ID number. These aren't actually used by the restricted shell program but they are displayed in the output of e.g. ps to allow easy discovery of connected clients.

The restricted shell program will print the string Connected.\n. This is picked up by the client Platinum system and used as a key to change the state, as reported by Platinum, from connecting to connected.

Pre-requisites

The following is required:

• The Platinum system to be reconfigured; and

• A target system to act as the "well-known" intermediary server. A Linux PC is recommended but it may be possible to use the Windows Subsystem for Linux in order to use a Windows PC as the target system. The target system is typically located in a data-centre and must be accessible both by the Platinum system and by any data-consumers or administrators wishing to access the Platinum system - see Firewall configuration below.

Preparing the target system

Preparing the target system involves installing a small binary, creating a target user and configuring the SSH dæmon. To proceed:

1. Download the remote-assist server binary and copy it to /usr/local/bin/ with the commands

   cd /usr/local/bin/ sudo wget -o remote-assist http://www.guralp.com/download/linux/remote-assist

   This binary does nothing but hold the connection open and expose the command line options in a ps listing.

2. Make the binary executable with the command

   chmod 755 /usr/local/bin/remote-assist

3. Create the target user with the command

   useradd -s /usr/local/bin/remote-assist unpriviliged

4. Prepare the target user for ssh access with the command

   mkdir -m 700 /home/unpriviliged/.ssh

   chown unpriviliged:unpriviliged /home/unpriviliged/.ssh

5. Configure the SSH server dæmon, sshd.

   If you already have a version of /etc/ssh/sshd_config, installed, you will need to download the sample sshd configuration file and merge the two. Please contact if you need help with this.

   If you do not have an /etc/ssh/sshd_config file, copy the sample file into /etc/ssh/ with the command

   cd /etc/ssh sudo wget -o sshd_config http://www.guralp.com/download/linux/sshd_config

6. Start the ssh daemon with the command

   sudo systemctl start ssh

   If your system does not use systemctl, use the command

   sudo service ssh start
   instead.

Firewall configuration

The firewall protecting the target system needs to adapted to provide incoming access to both the Platinum system's connection and connections from any administrators or data-consumers needing to access the Platinum system.

Incoming access for the Platinum system is best provided with a port-forwarding rule. I recommend not using external port 22 in order to avoid tiresome bombardment by password-guessing attacks. The chosen port should be forwarded to port 22 on the target system and specified in the remote-assistance configuration over-ride file described below.

Incoming access for the administrators and/or data-consumers can be permitted as required. If the target system offers no services of its own, canonical port numbers can be used although, again, it is never wise to expose port 22 to the public Internet.

Preparing the Platinum system

Prepare the Platinum system as follows:

1. Create an ssh key pair by running the command

   ssh-keygen
   • when prompted for a file into which to save the key, enter
     /etc/remote-assist/vpn.key.local
   • when prompted for a passphrase, simply key enter (i.e. do not enter a passphrase).
   • when prompted to confirm the passphrase, simply key enter again.

2. Move the file /etc/remote-assist/vpn.key.local.pub from the Platinum system to the target system.

3. On the target system, move the vpn.key.local.pub file to the target user's authorized_keys file with the command

   sudo mv vpn.key.local.pub ~unpriviliged/.ssh/authorized_keys

4. Back on the Platinum system, create a remote-assistance configuration over-ride file by running

   cd /etc/remote-assist grep = client.cf >client.cf.local
   You can restore normal remote assistance operation at any time by moving or renaming the client.cf.local file.

5. Using either vi or nano, edit the /etc/remote-assist/client.cf.local file:

   • Change the ssh_key line to point to your new key - i.e.

     ssh_key = /etc/remote-assist/vpn.key.local

   • Change the server_list line to point to your target server and port. For example:

     server_list = vpn.example.com:2222

   • Change the ssh_options line, removing the %i tokens and specifying the desired port numbers for each service. For example, the argument-pair

     -R *:%i80:127.0.0.1:80

     could be replaced by

     -R *:8080:127.0.0.1:80

     to expose the Platinum system's web interface (port 80) via port 8080 on the target system. Please contact if you need help with this step.

     Only TCP ports can be forwarded in this manner so you cannot forward the Scream protocol over UDP, only over TCP.

   • Add additional argument-pairs to the ssh_options line if you wish to add support for other protocols, such as HTTPS, GCF, SEEDlink etc. You can use the existing line as a model. It currently provides support for:

     • outgoing RSYNC access (port 873) to rsync.guralp.com
     • incoming SSH (port 22) access
     • incoming HTTP (port 80) access

6. Enable the remote assistance server on the Platinum system with the command:

   remote-assist

   The client should connect to the target server and the status, displayed on the command line, should change to connected. You can return to the command line at any point by keying ctrl + C but the service will continue to run in the background.

The data-consumers can now connect and disconnect at will. The Platinum system will automatically restart the connection if it is severed or if the system is rebooted. To disable the link, enter (on the Platinum system), the command: