Tehama Gateway User Guide

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

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

Your instance of the Tehama Gateway must be installed and run from behind your Organization's firewall. In order to administer your network properly, the Tehama Gateway 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 Gateway is fully encrypted to ensure all communication with your Room is secure. Should you have any questions or concerns about the Tehama Gateway, please feel free to reach out to a Tehama Concierge.

1. The installation of a Tehama Gateway for a room is optional. You can configure your room's 'Network Access' to be either 'Internet Only' or 'Tehama Gateway'. The 'Internet Only' setting does not require the installation of a Tehama Gateway. The 'Network Status' setting is found on the Room's CONNECTION tab in the STATUS sidebar item.


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, when the 'Network Access' setting is 'Tehama Gateway'.

As you are following the instructions to install the Tehama Gateway, 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 Gateway 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 Gateway 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 Gateway 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, when the 'Network Access' setting is 'Tehama Gateway'.

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


Tehama Gateway Network Limitations

NOTE: Due to a limitation in the authentication framework used by Tehama, the Tehama Gateway cannot be installed on the 172.31.x.x network.

In addition, Tehama cannot connect to resources that are on the 172.31.x.x network directly.

If you have the following situation:

  • the Tehama Gateway is on a supported network; and
  • a resource is on the 172.31.x.x network

then a workaround would be to create a NAT on the network to NAT the address of the resource to an address that Tehama can see, like 10.x.x.x or something similar.


Install the Tehama Gateway from an automated-script

This is the recommended method for Linux-based systems. (For Windows systems, see the Docker method.)

Be aware of existing network limitations for the Tehama Gateway.

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

Note: Please ensure the installation script conforms to your Organization's security policies prior to using the script. To view the script, download it from: https://app.tehama.io/get-gateway.sh

Installation Requirements (get-gateway.sh)

  • The script has been tested on the following Linux versions on the Intel/AMD x64 platform:
    • Amazon Linux AMI (release 2017.09.1)
    • Amazon Linux 2 AMI
    • Ubuntu 16.04 LTS
    • Fedora 25

It should also work on other Linux versions. Contact Tehama Concierge at Tehama Support if you want to install on a different version.

Note MacOS: The Tehama Gateway will not run on Mac directly.

  • The following standard software is required:
    • wget and/or curl
    • unzip
    • tee
    • nohup
    • python
    • pgrep
    • ssh
    • sshd
    • ssh-keygen

NOTE: The Tehama Gateway will run without ssh, sshd and ssh-keygen, but the network performance will be degraded.

Installation Procedure (get-gateway.sh)

  1. Open a Linux terminal.

  2. Create and enter a working directory for Tehama. (e.g.: ~/tehama)
    • mkdir ~/tehama
    • cd ~/tehama

  3. Download and launch the installation script:
    1. wget https://app.tehama.io/get-gateway.sh
    2. chmod +x ./get-gateway.sh
    3. ./get-gateway.sh
      NOTE:
      The script automates the following tasks:
      1. It verifies required software is installed.
      2. It handles the automated download, verification and installation of the Tehama Gateway in the current directory.
      3. It starts the Tehama Gateway as a background task using nohup.
  4. Enter in the Access Key when prompted.
    1. First generate the key using the following steps:
      1. Log into the Tehama WebUI at: https://app.tehama.io/
      2. Navigate to your room (i.e.: Click on the ROOMS tab, then select the room for this Tehama Gateway from the rooms list)
      3. Navigate to the CONNECTION tab's STATUS sidebar item (with 'Network Access' set to 'Tehama Gateway').
      4. Click the REGENERATE KEY button (not necessary if this is the first time you have installed a Tehama Gateway for this room)
      5. Click the Copy button to copy the key to the clipboard
    2. Next enter the key:
      1. Return to the Linux terminal and paste in the Access Key when prompted
      2. Press Enter, and Confirm
    (The steps above to generate the key are summarized from Obtain an access key and Generate a new access key above.)

Once the Tehama Gateway is installed and successfully connected, you can register it for auto-start in the rc.local as follows: sudo ./get-gateway.sh -r

Manual update of the Tehama Gateway to the latest version

For instructions on how to update the Tehama Gateway to the latest version please see the 'Update Tehama Gateway' section below.


Install the Tehama Gateway using Docker

This is the Docker method used for both Linux and Windows. (Note that the recommended method for Linux systems is the automated-script.)

Be aware of existing network limitations for the Tehama Gateway.

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

Instructions to install, update or stop the Tehama Gateway using Docker:


Verify Connectivity with Tehama

Note: If the Tehama Gateway 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 appears

To be completed on the Tehama Client UI.

Verify the connection to your network, and its associated IP address by navigating to your Room's CONNECTION tab's STATUS sidebar item (with 'Network Access' set to 'Tehama Gateway').

  • 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

Read this section if you have a firewall in your network.

You can configure your outbound firewall rules so that the Tehama Gateway 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 Tehama Gateway to function properly, you must, at a minimum, choose one of the following firewall configuration options.

Configure your firewall's network settings to allow the Tehama Gateway to access ...

  • Option A
    • any IPs through the following outbound ports: 80, 443 and 22.
      (recommended)
  • Option B
    • any IPs through the following outbound ports: 80 and 443; and
    • the two routers for the room (you can find the two router IP addresses listed in the room's STATUS page) through the outbound port 22.
  • Option C
    • the Tehama Gateway Proxy IPs (34.234.129.145 and 34.237.13.137) through the outbound port 443; and
    • the two routers for the room (you can find the two router IP addresses listed in the room's STATUS page) through the outbound port 22.
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 re-run the steps above in order to re-establish connectivity between your network and the Tehama servers.

Test Connections

Tehama provides a Connection Test Tool to test connections to specified targets through your room's Tehama Gateway. This tool is available from both the Tehama Client UI and the Desktop Agent on your room's desktops. See the Connection Test Tool User Guide for more details.


Best Monitoring Practices

This section outlines the best practices for monitoring your Tehama Gateway.

Once your room's Tehama Gateway has been installed, its connectivity verified and your firewall configuration for the Tehama Gateway 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 Tehama Gateway.

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

Monitor Tehama Gateway when installed via automated-script

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

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

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

Monitor Tehama Gateway when installed via docker

If you installed the Tehama Gateway using the docker method, you can check that the 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 Tehama Gateway 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 Tehama Gateway 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 Tehama Gateway log file

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

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

You can find the log file here:

  • your Tehama Gateway was installed via the automated-script:
    <your Tehama working directory>/tehama-gateway.log
  • your Tehama Gateway was installed via docker:
    <the docker logs directory)>/tehama-gateway.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 Tehama Gateway connectivity from the Tehama Client UI

Your monitoring of your room's Tehama Gateway in your network shows that it 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 (with 'Network Access' set to 'Tehama Gateway').

Verify that the status for the Tehama Gateway is green ('Connected').

Monitor changes to firewall configuration

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


Update a Tehama Gateway

There are two methods to update a Tehama Gateway that is installed in your network:

Trigger automated-update

Note, only available after Tehama Gateway version 3.0 has been installed. Use the manual update method until this version has been reached.

This has two steps:

1 - Receive notification of a pending update

Tehama will automatically detect when an update becomes available for a Tehama Gateway.

It will display a notice in the Tehama WebUI on the room's CONNECTION tab, under the STATUS sidebar item (with 'Network Access' set to 'Tehama Gateway'), for the room associated with that Tehama Gateway, visible to members of the room's connected organization.

To see the notice, you, a member of the room's connected organization, need to either:

  • navigate to the room's status page.

or, if already logged in and viewing the room's status page:

  • refresh the page.

Organization managers and staff-members will see:

Need to Update Notification for Managers and Staff-members

Click on the words "More Info" in the notice to display the UPDATE page, but as a manager or staff-member of the organization, you will be unable to trigger an update.

Alert your organization owner (the user in the organization with the Admin role) about the pending update for the room's Tehama Gateway.

Organization owners (the users with the Admin role for their respective organizations) will see:

Need to Update Notification for Admins

Click on the words "More Info" in the notice to display the UPDATE page. You, as the organization owner, can then proceed to trigger the update.

Note, it does not matter if the Tehama Gateway is currently connected or disconnected.

2 - View and/or trigger the pending update

Click on the room's CONNECTION tab and select the UPDATE sidebar item. (This is not visible if the 'Network Access' setting on the STATUS sidebar item page is not 'Tehama Gateway'.)

Organization managers and staff-members will see:

Update Page for Managers and Staff-members

You, as a manager or staff-member, will see that an update is required, but will be unable to trigger it. Alert your organization owner (the user in the organization with the Admin role).

Organization owners (the users with the Admin role for their respective organizations) will see:

Update Page for Admins

You, as the organization owner, should do the following:

  • Determine the best time to trigger the update.
    The update will cause a temporary interruption of the room's connectivity which may last up to a few minutes.
    It is best to pick a time when the update will cause the least disruption to users of the room.
  • At that time click on the UPDATE button to trigger the start of the automated-update.

Note, the automated-update will not work for Tehama Gateways installed using Docker. Please follow the Manual Update

The automated-update software will attempt to update your room's Tehama Gateway up to three times. If it has not been able to successfully complete the update after three attempts, you will see a note on the page advising you to attempt a manual update.

After a successful update, you will see:

Update Page after Successful Update

Manual update for legacy versions (before 3.0.0)

For legacy Tehama Gateways (1.0.0 and 2.0.0) running directly on Linux, you can manually update the Tehama Gateway in the console from PARENT of the directory where it is installed:

  1. Find the process ID for the running Tehama Gateway process:
    type: ps -ef | grep agent | grep -v grep

    Two things to take note of
    • the Process ID is the (number) second column
    • the Directory where the Tehama Gateway is located is the rightmost column

    If no results are returned, your Tehama Gateway is not running, so continue to step 3.

  2. Kill the Tehama Gateway process (if one was found) using the process ID found above.
    type: sudo kill <process_id> (e.g.: sudo kill 1225)

  3. Rename the directory where the Tehama Gateway is installed - append the suffix '.bak'.
    From the parent directory:

    type: mv <directory name> <directory name>.bak (e.g.: mv tehama tehama.bak)

  4. Remove the agent from your system's auto-start, which is normally located in /etc/rc.d/rc.local or /etc/rc.local

  5. Follow the steps for Installation Procedure above to install in a fresh new directory.

Manual update for modern versions (3.0.0 and above)

For Tehama Gateways version 3.0.0 and above running directly on Linux you can manually update the Tehama Gateway in the console from the directory where it is installed as follows:

  1. Determine that there is a running Tehama Gateway ps ax | grep tehama-gateway
  2. Kill the process:

    For versions 3.0.0 to 3.1.0:

    • sudo killall tehama-gateway

    For versions 3.2.0 and above:

    • ./stop-gateway.sh
  3. Start the update ./get-gateway.sh -u

Manual update for Tehama Gateways running inside a Docker container

For Tehama Gateways running inside the Docker container please follow instructions at the bottom of the page on https://hub.docker.com/r/pythian/tehama_gateway#docker-manual-update