Gateway Agent User Guide

The Tehama gateway agent establishes the gateway, a secure channel, between the Room and your network. All network traffic from the Room flows through the gateway agent.

Your instance of the gateway is uniquely identified by the unique access key provided to you during the Room creation or Room connection process.

Your instance of the gateway must be installed and run from behind your Organization's firewall. In order to administer your network properly, the agent will need to be placed in a network segment which has access to the resources you wish to administer remotely through Tehama.

Because Pythian loves your data, the Tehama agent is fully encrypted to ensure all communication with your Room is secure. Should you have any questions or concerns about the Agent, please feel free to reach out to a Tehama Concierge.

Obtain an Access Key

The Room connection process presents you with an Access Key you will need to initiate the connection to your Room.

Note: If you haven't connected your Room yet, you can find the current key on the Room's CONNECTION tab in the STATUS sidebar item.

As you are following the instructions to install the agent, you will either be prompted to paste-in the key or be required to place the Key file (secret.sck) in a specific location in order to initiate the connection.

You can transfer this key to the Tehama Agent in two ways:

Choose one option:

  1. Click the Copy button (found beside the key on the page) to place the unique encryption key on your clipboard
    • to be pasted into the Tehama Agent when prompted by the Automated-script

  2. Click Download (also found beside the key on the page) to save a copy of the Key file (secret.sck)
    • transfer it to your host where the Tehama Agent will reside. (This is the recommended option when using Docker)

Generate a new Access Key

If you lose your key or have internal policies regarding regular regenerating access keys, you can regenerate a new one on the Room's CONNECTION tab in the STATUS sidebar item.

Click the REGENERATE KEY button. The displayed key will be the regenerated key, ready for copying or downloading.

Install the Gateway Agent

For your convenience, there are two methods to install the Tehama Gateway Agent into your network:

Important - if your network has a firewall, please be sure to follow the firewall configuration steps after the gateway agent is installed and running.

Install using an Automated-script

The automated-script has been tested on the following Linux versions:

  1. Amazon Linux AMI release 2017.03
  2. Ubuntu 16.04 LTS
  3. CentOS 7.3.1611
  4. Red Hat Enterprise Server 7.3
  5. Fedora 25

It is likely that it works on a different Linux version. Contact Tehama Concierge at Tehama Support if you want to install on a different version.

Note: Although MacOS is based on BSD, there are incompatibilities with this method of installation of the Tehama Gateway Agent. (For installation on MacOS, use the Docker method.)

The get-agent.sh shell script can be used to automate the Tehama Gateway Agent installation process. The installation script automates the following tasks:

  1. Verifies prerequisite software packages are installed
    • wget and/or curl
    • unzip
    • nohup
  2. Automated download and Unpacking of the Tehama Gateway Agent
  3. Registering the Tehama Gateway Agent as a system service (via rc.local)
  4. Execute the Tehama Gateway Agent as a background task

Tehama Gateway Agent scripted install, from the Linux host::

  1. Create and enter a working directory for Tehama. (e.g.: /bin/tehama)
    • Type: mkdir /bin/tehama
    • Type: cd /bin/tehama
  2. Download and Launch the installation script:
    • Type:
      wget https://raw.githubusercontent.com/pythian/tehama_gateway_agent_install/master/get-agent.sh
    • Type: sudo chmod 755 get-agent.sh
    • Type: sudo ./get-agent.sh -d
Note: Please ensure the installation script conforms to your Organization's security policies prior to using the script. To view the script, please visit out Github repository: https://github.com/pythian/tehama_gateway_agent_install/blob/master/get-agent.sh


Note: If the Tehama gateway agent is stuck “Trying to connect”, please verify connectivity to the Tehama service:
  • At a bash prompt. Type: curl https://app.tehama.io/version
  • If the connection is successful, the current software version of the Tehama gateway agent appears

Install using Docker

Instructions to install the Gateway Agent using Docker:

Verify Connectivity with Tehama

To be completed on the Tehama Website.

Verify the connection to your network, and its associated IP address by navigating to your Room's CONNECTION tab's STATUS sidebar item.

  • A green dot will indicate a connection was established.
  • Two IP addresses will be displayed (indicating two Tehama routers assigned to your room).

Firewall Configuration

If you have a firewall in your network, the gateway agent may not be able to connect to the router. Take note of the two router IP addresses listed in the STATUS page. Configure the network settings in your firewall to allow traffic between the gateway agent and the two router IPs. The gateway agent needs to be able to access port 22 of the router instances (SSH) as well as to ping (ICMP) them.

You can configure your outbound firewall rules so that the gateway agent is only able to connect to a list of known/approved IP addresses. This will enable you to deny generic outbound Web traffic, as well as outbound DNS requests. In order for the gateway agent to function properly with such a configuration, the list of known/approved IP addresses must include:

  • the two router IPs for your room mentioned above; and
  • the proxy IPs for two of Tehama's components to which the gateway agent must send requests. Contact the Tehama Concierge to get these IPs.
Note: Generating a new Access Key will break the link between your network and your room. You will need to re-execute the configuration and run steps above in order to re-establish connectivity between your network and the Tehama servers.

Best Monitoring Practices

This section outlines the best practices for monitoring your gateway agent.

Once your room's gateway agent has been installed, its connectivity verified and your firewall configuration for the agent completed, you are done — almost. Like any other piece of continuously running software in your network, you will need to ensure that it stays running.

Best practice is to set up a process, either manual or automated, to monitor the agent.

The process can become part of your network's regular health checks.

Monitor Agent when installed via automated-script

If you installed the agent using the automated-script on a Linux host, you can check that the agent process is running as follows:

  • Open a terminal session on the Linux host (either remotely or locally) and run the command:
    ps -e | grep "agent"
  • Check the output for evidence that the agent is running. It should show up as "agent", (possibly preceded by the path to your Tehama working directory).

    e.g.:
    $ ps -e | grep "agent"
      . . .
     2054 ?        00:14:21 agent
      . . .
    If you do not see an entry for 'agent', then the agent is not running.

Monitor Agent when installed via docker

If you installed the agent using the docker method, you can check that the agent process is running as follows:

  • Open a terminal session on the host (either remotely or locally) and run the command:
    $ docker ps --filter "name=tehama_gateway"
  • Check the output for evidence that the agent is running. It will show up as an entry with image name "pythian/tehama_gateway:latest", and show the current "Up" time under the status.

    e.g.:
    $ docker ps --filter "name=tehama_gateway"
    CONTAINER ID        IMAGE                           COMMAND                  CREATED             STATUS              PORTS               NAMES
    . . .
    8aefdba03526        pythian/tehama_gateway:latest   "/app/docker-entry..."   36 seconds ago      Up 35 seconds                           tehama_gateway
    . . .
    If you do not see an entry for tehama_gateway, then the agent is not running.

    For more information, try the command again, with the '-a' option, to see information on all docker containers, running or not running. If the tehama_gateway has stopped running, it will show up with status "Exited".
    $ docker ps -a --filter "name=tehama_gateway"
    CONTAINER ID        IMAGE                           COMMAND                  CREATED             STATUS                     PORTS                   NAMES
    . . .
    8aefdba03526        pythian/tehama_gateway:latest   "/app/docker-entry..."   10 minutes ago      Exited (1) 3 minutes ago                           tehama_gateway
    . . .

Monitor Agent log file

The gateway agent generates logs into a log file. Monitor your gateway agent's log file for messages that may require you to take action.

For example, when your gateway agent's access key is updated, a log is generated asking you to restart the agent.

You can find the log file here:

  • your agent was installed via the automated-script:
    <your Tehama working directory>/gateway-agent.log
  • your agent was installed via docker:
    <the docker logs directory)>/gateway-agent.log
    where the docker logs directory is specified in the 'docker run' command. The default value in the docker instructions (https://hub.docker.com/r/pythian/tehama_gateway/) is
    <current directory>/logs

Monitor Agent connectivity from the Tehama Client UI

Your monitoring of your room's gateway agent in your network shows that the agent is running. To check up on its connectivity, login to the Tehama client and navigate to the room.

From there, open the CONNECTION tab and select the STATUS sidebar item.

Verify that the status for the gateway agent is green ('Connected').

Monitor changes to firewall configuration

If your network has a firewall and you had to configure it for the gateway agent, remember to update your network's firewall processes to be aware of and maintain these configuration changes.