Skip to main content

Reference articleTehama Gateway - Installation and Management

  • Updated

Tehama Gateway - Installation and Management

The purpose of this article is to provide instructions for installing and managing a 'Tehama Gateway' for a Tehama Gateway Room in a private network.

Overview

A Tehama Gateway is a software agent (binary) that you install in the infrastructure of your private network to establish a secure channel between your Tehama Gateway Room, a Room with network access set to 'Tehama Gateway', and the private network. If your Room follows the Service-provider Room model, this is the private network of the Room's connected organization. All network traffic from the Room flows through this Gateway.

This software agent is referred to as the "Tehama Gateway", or simply as the "Gateway".

See the Tehama Gateway Room Connectivity User Guide for more information on Tehama Gateway Rooms.

A Gateway will not connect to a Room that does not have network access set to 'Tehama Gateway'.

By default, a Tehama Gateway Room allows you to connect one Gateway to it. However, you can opt to enable the 'Multiple Gateways' option to provide redundancy for your Room's network access. When enabled, this provisions infrastructure in your Room for a second Gateway instance, which you must install in your network's infrastructure - on a different host to than the default Gateway instance. The two Gateways will run simultaneously.

The 'Multiple Gateways' option is an added expense for your Room.

The Gateway(s) uses the Room's Access Key to configure the connection to the Room. This is an encryption key unique to your Room. As you follow the instructions to install a Tehama Gateway for the Room, 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. Access keys are unique.

The same Access key is used for all the Gateways connected to the Room.

If you lose your key or have internal policies regarding regular regenerating access keys, you can regenerate a new one, and then reconfigure/restart all the Gateways connected to your Room.

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

The Gateway communications are fully encrypted to ensure all communication with your Room is secure. Should you have any questions or concerns about the Tehama Gateway, feel free to reach out to Tehama Support.

This is a list of actions to install and manage Gateway instances in your private network:

Install in your network and configure your network's firewall:

Verify and monitor connectivity between your network and your Room:

Keep your Tehama Gateway version up-to-date:

Tehama Gateway Network Limitations

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 AWS AMI

This is the recommended method for AWS cloud-based networks.

Note: Please ensure the Tehama Gateway AWS AMI is appropriate for your environment. To view the AMI, go to the AWS Marketplace and search for Tehama.

Install the Tehama Gateway AWS AMI as follows:

Step 1 - Subscribe to the Tehama Gateway AWS AMI from the AWS Marketplace

  1. Open a browser and log in to your AWS account.
  2. Navigate to the list of products on AWS Marketplace: https://console.aws.amazon.com/marketplace/home?region=us-east-1#/search
    AWS Marketplace products are exclusively located in the us-east-1 region.
  3. Enter "Tehama" (without quotes) into the search bar.
  4. Click on the "Tehama Gateway AMI" entry.

    Here you can view the "Tehama Gateway AMI" product. Read through the product overview, pricing and usage information before continuing.

  5. Click on Continue to Subscribe.
  6. Read the subscription information through carefully before accepting the terms and proceeding.
  7. Click on Continue to Configure.
  8. Select the Region that you require.
  9. Click on Continue to Launch.

The last step will download the Tehama Gateway AWS AMI into your list of AWS AMIs and begin the launch steps. Continue to Step 2.

Step 2 - Launch the Tehama Gateway AWS AMI

From the screen presented to you after launching the instance:

  1. Choose Action.
    • Select the action "Launch through EC2" from the list.
    • Click Launch.
  2. Verify Instance Type.
    • Verify that the instance type 't3.medium' is pre-selected for you.
    • Click Next: Configure Instance Details.
  3. Configure Instance.
    • Select the VPC and subnet where you wish the instance to run in the Network and Subnet fields.
    • Select "Enable" in the Auto-assign Public IP field.
    • Click Next: Add Storage.
  4. Add Storage.
    • Encrypt the "Root" volume by selecting an encryption key from the dropdown under the Encryption column.
      It is strongly recommended that you encrypt the instance storage in this way to protect the Access Key for the Room, which will be stored in the instance.
    • Click Next: Add Tags.
  5. Add Tags.
    You may opt to add tags to your Tehama Gateway AWS AMI instance. Tags help to manage your AWS resources.
    It is strongly recommended that you add a tag with the key "Name" so that you can easily find your instance in the list of running EC2 instances, for maintenance/monitoring activities.
    • Click Add Tag to add a tag, if desired.
    • Click Next: Configure Security Group.
  6. Configure Security Group. By default, a new security group will be created for your instance. This new security group contains a rule that will allow you to SSH into instance from any source. Either
    • Set up a security group for the instance:
      Either:
      • Edit the source of the default SSH rule in the new security group to constrain it to a trusted source, and perhaps click Add Rule to add a rule to the new security group to allow other types of access.
        Or:
      • Select "Select an existing security group" and select an existing security group suitable to control access into the instance. (It is recommended that the security group contains at least one rule that will allow you to SSH into the instance from a trusted source.)
    • Click Review and Launch.
  7. Review.
    • Review the configuration settings for the instance and make any changes needed.
    • Click Launch. A popup dialog will appear.
  8. In the popup dialog:
    • Choose an existing SSH key pair, or generate a new one.
    • Read and check the acknowledge statement in the popup.
    • Click Launch Instances.

The Tehama Gateway AWS AMI instance will be launched.

Continue to Step 3.

Step 3 - Connect to the Tehama Gateway AWS AMI (with secret Room Access Key)

 

If you want to reconnect to the Tehama Gateway in the AWS AMI with a regenerated Room Access Key:

Decommission (stop and terminate) your existing Tehama Gateway AWS AMI instance and launch a new one, as in Step 2.

Connect to the instance of the Tehama Gateway AWS AMI that you launched in Step 2 as follows:

  1. Open a browser and log in to your AWS account.
  2. Navigate to the list of running AWS EC2 instances.
    • Go to Services.
    • Click on EC2 (under Compute).
    • Click on EC2 Dashboard (at the top of the left sidebar menu).
    • Click on "Running Instances".
      You will see a list of running EC2 resources you have access to.
  3. Find the instance with the "Name" you gave your Tehama Gateway AWS AMI instance it when you launched it. (See the "Add Tags" step above.)
  4. Click on the checkbox next to the entry for your instance to select it.
  5. Click Connect. A popup dialog will appear.
  6. In the popup dialog:
    • Select "EC2 Instance Connect" from the I would like to connect with options.
    • Edit the User name field to be: ec2-user
    • Click Connect. A terminal window for the instance will appear.
  7. Observe the prompt asking you to finish configuring the Tehama Gateway AWS AMI instance with the Access Key for your Room.
  8. Enter the Access Key for your Room into the instance's terminal window, when prompted, as follows:
    1. First generate the key using the following steps:
      1. Log into the Tehama Web UI 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 and click on the 'View' link beside the Access Key field (only visible with 'Network Access' set to 'Tehama Gateway'). The ACCESS KEY dialog will appear.
      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 terminal for the Tehama Gateway AWS AMI instance and paste in the Access Key at the prompt.
      2. Press Enter, and confirm.
    (The steps above to generate the key are summarized from View/Regenerate a new access key above.)

The Tehama Gateway AWS AMI instance will now attempt to connect to your Room. Continue to Step 4.

 

Step 4 - Configure your network firewall (for a Tehama Gateway AWS AMI instance)

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

Step 5 - Maintain and update a Tehama Gateway AWS AMI instance

For instructions on how to monitor a Tehama Gateway AWS AMI instance please see 'Monitor Tehama Gateway AWS AMI instance.

For instructions on how to update a Tehama Gateway AWS AMI instance to the latest version please see the 'Update Tehama Gateway' section below and select an appropriate update option for modern Tehama Gateways.

Install the Tehama Gateway from an automated-script

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

Note: Please ensure the get-gateway.sh 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

Install the Tehama Gateway from Tehama's automated get-gateway.sh installation script as follows:

Step 1 - Configure your Gateway host (for automated-script installations)

  1. Select a host in your network for your Gateway.

    The Tehama Gateway does not require a dedicated host. You can run the Gateway on an existing host in your infrastructure as long as it can be configured as required, instead of setting up a host specifically for the purpose (which may require an additional OS license).

    Important - Be aware of existing network limitations for the Tehama Gateway, and make changes to your network if necessary.

    Note: Tehama does not currently support running more than one Gateway per host.

    Choose a Gateway host that has the following minimum specification:

    • # of vCPUs: 2 @ 2.3 GHz
    • Memory: 4 GB
    • Network Performance: 250 MBit/s
      (The above specs are equivalent to the specs of the hosts for the Tehama Room routers. Testing has determined that a Gateway's performance is optimal when its host's specs are similar or better than those of the Room router hosts.)
    • Operating system: Select an OS from the following table.
      Minimum Linux Host OS Recommended Linux Host OS
      • Ubuntu 14.04
      • Ubuntu 16.04
      • Ubuntu 17.1
      • Ubuntu 18.04
      • RHEL/CentOS/Rocky/AlmaLinux v8.5
      • RHEL/CentOS/Rocky/AlmaLinux v8.5
      Contact Tehama Support if you want to install on a different version.

      Note MacOS: The Tehama Gateway will not run on Mac directly.
  2. Run the following commands at a terminal prompt to verify that the required standard software is installed on your Gateway host:
    Note: the get-gateway.sh script will check for missing required software.
    • wget
      • (looks for wget) It should complain that the URL is missing. If it says not found, it is not installed.
    • curl
      • (looks for curl) It should tell you to look at the manual. If it says not found, it is not installed.
    • unzip
      • (looks for unzip) It should show a help file. If it says not found, it is not installed.
    • tee
      • (looks for tee) It should not give an error but show an empty line. If it does, do CTRL+C to go back to the command line. If it says not found, it is not installed.
    • python -V
      • (looks for python - we want version between 2.4 and 3.6) It will show the version number. Verify that it falls between 2.4 and 3.6, inclusive. If it says not found, it is not installed.
    • netstat
      • (looks for net-tools) If it says not found, it is not installed.
    • ldd --version
      • (looks for glibc - we want glibc >gt=2.15) It will show the version number. Verify that it is version 2.15 or higher. If it says not found, it is not installed.
    • nohup
      • (looks for nohup) It should show a usage statement. If it says not found, it is not installed.
    • pgrep
      • (looks for pgrep) It should show a usage statement. If it says not found, it is not installed.
    • secure shell utilities:
      NOTE: The Tehama Gateway will run without the secure shell utilities, ssh, sshd and ssh-keygen, but the network performance will be degraded.
      • ssh
        • (looks for ssh) It should show a usage statement. If it says not found, it is not installed.
      • sshd
        • (looks for sshd) It should complain that the path is missing. If it says not found, it is not installed.
      • ssh-keygen --help
        • (looks for ssh-keygen) It should show an error followed by a usage statement. If it says not found, it is not installed.

Step 2 - Download and launch the automated script (get-gateway.sh) to install Tehama Gateway

IMPORTANT: Do not perform the following steps as root. The gateway is designed to run without elevated privileges and will not deliver optimum performance if installed as root.

  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
      Note: If this command fails, it may be because your network's firewall is not configured to allow downloads from https://app.tehama.io.

       

      If that is the case, skip ahead to configure your firewall before returning here to try again.

       

      If you choose to implement Option C, you will need to download the script from one of the gateway proxies (instead of from https://app.tehama.io):
      • First try: wget https://gwa-proxy1.app.tehama.io/get-gateway.sh
      • Then try: wget https://gwa-proxy2.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 Web UI 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 and click on the 'View' link beside the Access Key field (only visible with 'Network Access' set to 'Tehama Gateway'). The ACCESS KEY dialog will appear.
      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 View/Regenerate a new access key above.)

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

Step 3 - Configure your network firewall (for automated-script installations)

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

Step 4 - Maintain and update a Tehama Gateway installed from the automated installation script

For instructions on how to monitor an automated-script installation of Tehama Gateway please see 'Monitor Tehama Gateway when installed via automated script.

For instructions on how to update an automated-script installation of Tehama Gateway to the latest version please see the 'Update Tehama Gateway' section below and select one of the options for Gateways installed via the automated-script, based on the version of your Gateway. 

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.)

Install the Tehama Gateway in a Docker container as follows:

Step 1 - Configure your Gateway host (for Docker installations)

  • Select a host in your network for your Gateway.

The Tehama Gateway does not require a dedicated host. You can run the Gateway on an existing host in your infrastructure as long as it can be configured as required, instead of setting up a host specifically for the purpose (which may require an additional OS license).

Choose a Gateway host that has the following minimum specification:

  • # of vCPUs: 2 @ 2.3 GHz
  • Memory: 4 GB
  • Network Performance: 250 MBit/s
    (The above specs are equivalent to the specs of the hosts for the Tehama Room routers. Testing has determined that a Gateway's performance is optimal when its host's specs are similar or better than those of the Room router hosts.)
  • Operating system: See the supported OSs at: https://hub.docker.com/r/tehama/tehama_gateway/

Important - Be aware of existing network limitations for the Tehama Gateway, and make changes to your network if necessary.

Step 2 - Install Gateway in Docker container

Follow the instructions to install the Tehama Gateway using Docker found here:

Note: Instructions to stop or update the Tehama Gateway using Docker are found on the same site.

Step 3 - Configure your network firewall (for Docker installations)

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

Step 4 - Maintain and update a Tehama Gateway installed in a Docker container

For instructions on how to monitor a Docker installation of Tehama Gateway please see 'Monitor Tehama Gateway when installed via Docker'.

For instructions on how to update a Docker installation of Tehama Gateway to the latest version please see 'Command line update for Gateways running inside a Docker container' found under the 'Update Tehama Gateway' section towards the end of this page.

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 instance(s) is/are only able to connect to a list of known/approved IP addresses. This will enable you to allow TCP and/or UDP traffic to specific IP addresses.

In order for the Tehama Gateway instance(s) 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
    • all IPs through the following outbound ports: 443 and 22 (and 40002, 40003 and 40004 if you have enabled the >> 'Multiple Gateways' feature).see note >
  • Option B (recommended)
    • all IPs through the following outbound port: 443; and
    • the Room's two static IP addresses, listed in the Room's STATUS page, through the outbound port 22 (and ports >> 40002, 40003 and 40004 if you have enabled the 'Multiple Gateways' feature). >> see note >
  • Option C
    • the Tehama Gateway Proxy IPs (34.234.129.145 and 34.237.13.137) through the outbound port 443; and
    • the Room's two static IP addresses, listed in the Room's STATUS page, through the outbound port 22 (and ports >> 40002, 40003 and 40004 if you have enabled the 'Multiple Gateways' feature). >> see note

Note: For Gateways with version < 3.3.0, ICMP must also be permitted.

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 for each Tehama Gateway instance in order to re-establish connectivity between your network and the Tehama servers.

Verify Connectivity with Tehama from the Tehama Web UI

The Org Admin user, the Org Managers and all Room members (including Room Managers who are members of the Room) from any of the organizations in a Room can see the Room's connectivity status. Check the description of your custom role, to see if you can see the Room's connectivity status.

Verify the connection of your Tehama Room to your network, and its associated IP address as follows:
(Note: 'Network Access' must be set to 'Tehama Gateway'.)

  1. Log in to the Tehama Web UI.
  2. Click on the ROOMS tab.
  3. Click on the name of the Room you want to verify connectivity for. You will see the user interface for the Room.
  4. Click on the Room's CONNECTION tab.
  5. Click on the STATUS sidebar item.
    • A green dot will indicate a connection was established.
    • IP addresses will be displayed (referring to the Tehama routers assigned to the Tehama Gateway instance(s) for your Room, two per instance). (You may have two Tehama Gateway instances running if your Room has the 'Multiple Gateways' option enabled.)
    • For each entry in the table of Tehama Gateways for the Room, a Room connected icon Room connected icon will appear.

Note: If the Tehama Gateway is stuck "Trying to connect", or if you experience any other connectivity issues, please verify connectivity to the Tehama service using the Gateway diagnostic tool.

You can also quickly run the following simple check from your Gateway host:

  • 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.

Tehama Gateway Diagnostic Tool

The Tehama Gateway diagnostic tool is a script: gateway-diagnostic.sh

You should run this script to help diagnose connectivity issues you may be having with your Gateway. The script provides output that can be used to help track down your Gateway's issues.

This script performs the following diagnostic checks (not a complete list):

  • It validates the installed versions of glibc, python and net-tools.
  • It checks the connection to https://app.tehama.io from the Gateway's host machine.
  • It tries to get the public IP address for the Gateway's host machine from 'checkip.amazonaws.com'.
  • It pings both of the Room's router IPs for this Gateway instance (it only pings one if you supply its IP on the command line) and then tries to establish ssh connectivity to the router instances from the Gateway's host machine. (Note: The ping is only done for Gateways with version less than 3.3.0.).

Install gateway-diagnostic.sh

This script is installed on your Gateway host machine automatically if you installed a modern version of the Gateway via the automated-script. Otherwise, consider updating your Gateway to the latest version to obtain this script.

Run gateway-diagnostic.sh

Run the script as follows, on the Gateway host machine:

  • ./<version>/gateway-diagnostic.sh <router IP parameter>

parameter: the IP for one of the Room's routers for the Gateway running on this host

You can find the router IP addresses listed in the Room's STATUS page (two per Gateway instance).

Run the script with the IP of one of the Room's routers. The script will test the connectivity of the Gateway to only that router. If you have the Multiple Gateways feature enabled for the Room, be sure to test with one of the routers for the Gateway that is running on this host machine. If the Gateway is successfully connected to the selected router, then the script will return a success message. Otherwise, it will return a failure message.

Note: When run without a parameter, the script is unable to perform the test and always returns a failure message.

Gateway connectivity to the Room is always achieved through only one of the two routers at a time. The second router is provided for redundancy. If the script returns a failure message for one of the routers, try again with the second router for the Gateway. Successful Gateway connectivity with the Room only requires connectivity through one of the routers.

If your connectivity issues persist, contact Tehama Support and provide the output from the script to the support team.

Tehama Gateway Troubleshooting

Having Gateway connectivity issues in your Room? See the Connectivity Troubleshooting section in the Room/Desktop Connectivity Troubleshooting Guide.

Tehama Gateway Log and Setup File Collection

The Tehama Support team may collect the following Tehama Gateway log and setup files, located in the directory where the Gateway is installed (or in the Docker container, if installed via that method):

  • .env
  • authorized_keys
  • gateway-diagnostic.log
  • gateway-version.json
  • get-gateway.log
  • get-gateway.sh
  • known_hosts
  • nohup.out
  • ssh_config
  • ssh_rsa_host_key
  • ssh_rsa_host_key.pub
  • sshd_config
  • sshd.log
  • tehama-gateway.log

View/Regenerate the Access Key

Only the Org Admin user and Org Managers and Room Managers (who are members of the Room) of a Room's connected organization (owner+connected or connected-only) can view/regenerate/copy/download the Room's 'Access Key'. Check the description of your custom role, to see if you can perform this action.

The Room's Access Key is used to configure the connection to the Room for all the Tehama Gateways provisioned in the Room. This is an encryption key unique to your Room. This option is only available if your Room has 'Network Access' set to 'Tehama Gateway'. As you follow the instructions to install a Tehama Gateway for the Room, 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. If you lose your key or have internal policies regarding regular regenerating access keys, you can regenerate a new one, and then reconfigure/restart the Tehama Gateway(s) in your Room.

  1. Log in to the Tehama Web UI.

  2. Click on the ROOMS tab.

  3. Click on the name of the Room you want to regenerate the access key for. You will see the user interface for the Room.

  4. Click on the Room's CONNECTION tab, if you are not already on this tab.

  5. Click on the STATUS sidebar item.

  6. Locate the Access Key field on the page.

    If you still do not see this field even when 'Network Access' is set to 'Tehama Gateway', then you do not have permission to view or regenerate this key.

  7. You will see a text link in the field that either says 'Regenerate' or 'View'. Click on the link to display the ACCESS KEY dialog.

    When you navigate to the STATUS page, this text link will always say 'Regenerate'. After (re)generating an access key, this text will change to 'View'. Once you have refreshed the page in your browser, or you have navigated away from the page and then back again, the link will revert to 'Regenerate'. This is a security feature.

  8. Generate a new Access Key or view the existing key:
  9. If the text link was 'Regenerate', then the access key is in need of regenerating - or must be generated for the first time. Click REGENERATE KEY to generate a new access key. It will be shown in a text box that will appear in the dialog.

  10. If the text link is 'View', then the last-generated access key will be shown in a text box in the dialog. You may opt to regenerate the key by clicking on the 'Regenerate' button.

    NOTE: If you already have a gateway running with the old key, that gateway will lose connectivity to the Room and people working on Desktops in the Room will experience downtime after the Access Key has been regenerated until you have reconfigured/restarted your gateway to use the new Access Key. This process takes approximately ten minutes. (If you have the 'Multiple Gateways' feature enabled, then you must reconfigure/restart both gateways.)

  11. Transfer the current access key in one of two ways. Choose one option:
  12. Click the Copy button (found beside the key on the dialog) to place the key on your clipboard - ready to be pasted into the Tehama Gateway when prompted by the Automated-script.

  13. Click Download (also found beside the key on the dialog) 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.)

    IMPORTANT: Keep your copy of the Access Key secure. For example, restrict access to your Gateway host to only essential personnel and remove any extraneous copies of the key from your systems.

  14. Proceed to install/activate your Tehama Gateway instance (both instances, with the same Access Key, if you have the 'Multiple Gateways' feature enabled).

    The dialog contains a link, Show User Guide, that links to this page ( Tehama Gateway - Installation and Management) where you can find information on how to install a Tehama Gateway with the Access Key and connect it to your Room. _(The same link is available in the text under the Network Access field on the STATUS page.)

    In brief, follow one of these installation options that are documented in this page:

  15. Click DONE on the dialog to dismiss it, if you have not already done so.

Test Connections

Tehama provides a Connection Test Tool to test connections to specified targets through your Room's Tehama Gateway instance(s). This tool is available from both the Tehama Web 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 instance(s).

Once your Room's Tehama Gateway instance(s) has/have been installed, the 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 the Tehama Gateway instance(s) will stay running.

Best practice is to set up a process, either manual or automated, to monitor each Tehama Gateway instance.

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

Monitor a Tehama Gateway AWS AMI instance

If you launched a Tehama Gateway AWS AMI, you can check that the process is running as follows:

  1. Open a browser and log in to your AWS account.
  2. Navigate to the list of running AWS EC2 instances.
    • Go to Services.
    • Click on EC2 (under Compute).
    • Click on EC2 Dashboard (at the top of the left sidebar menu).
    • Click on "Running Instances".
      You will see a list of running EC2 resources you have access to.
    • Find the instance with the "Name" you gave your Tehama Gateway AWS AMI instance it when you launched it.
  3. Click on the checkbox next to the entry for the "Tehama Gateway AWS AMI" to select it.
  4. Click Connect. A popup dialog will appear.
  5. In the popup dialog:
    • Select "EC2 Instance Connect" from the I would like to connect with options.
    • Edit the User name field to be: ec2-user
    • Click Connect. A terminal window for the instance will appear.
  6. Observe the status of the Tehama Gateway process in the status-check result that is printed out in the terminal.

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:

  1. Open a terminal session on the Linux host (either remotely or locally) and run the command:

    ps ax | grep tehama-gateway

  2. 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:

  1. Open a terminal session on the host (either remotely or locally) and run the command:

    docker ps --filter "name=tehama_gateway"

  2. Check the output for evidence that the Tehama Gateway is running. It will show up as an entry with image name "tehama/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 tehama/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 tehama/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 the access key for your Tehama Gateway is updated, a log is generated asking you to restart the Tehama Gateway.

You can find the log file here:

  • your Tehama Gateway is running in a Tehama Gateway AWS AMI instance: /opt/tehama/tehama-gateway.log
  • 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/tehama/tehama_gateway/) is <current directory>/logs

Monitor Tehama Gateway connectivity from the Tehama Web UI

Your monitoring of your Room's Tehama Gateway instance in your network shows that it is running. To check up on its connectivity:

  1. Log in to the Tehama Web UI.
  2. Click on the ROOMS tab.
  3. Click on the name of the Room you want to monitor connectivity for. You will see the user interface for the Room.
  4. Click on the Room's CONNECTION tab.
  5. Click on the STATUS sidebar item.
  6. Verify that the status for the Room is green ('Connected') and that the status for the Tehama Gateway instance in the table is connected ('Room connected icon').

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

Choose the appropriate method to update the Tehama Gateway instance(s) installed in your network based on the instance's version and method of installation:

  • Automated update
    • available from Tehama Gateway version 3.0.0 onwards (modern versions of the Gateway), both installed via the automated-script and also running on Tehama Gateway AMI instances. Note: Automated update does not work with docker installed gateways. Do not enable it if a docker installed gateway is connected to your Room.
  • Manually triggered update
    • available from Tehama Gateway version 3.0.0 onwards (modern versions of the Gateway), both installed via the automated-script and also running on Tehama Gateway AMI instances.
  • Command line update for legacy versions
    • for Tehama Gateways with version below 3.0.0 installed via the automated-script
  • Command line update for modern versions
    • for Tehama Gateways with version 3.0.0 and later, installed via the automated-script (use when the manually triggered update fails)
  • Command line update for Gateways running inside a Docker container
    • for Tehama Gateways running inside a Docker container

Automated update for modern Gateway versions (3.0.0 and later)

Only the Org Admin user and Org Managers and Room Managers (who are members of the Room) of a Room's connected organization (owner+connected or connected-only) can enable/disable the automated update feature in the Room. Check the description of your custom role, to see if you can perform this action.

Tehama offers an automated update feature for Tehama Gateways that is enabled on a per-Room basis. When Gateway updates are detected, updates are automatically scheduled for Gateways in Rooms that have this feature enabled.

Note: Automated update does not work with docker installed gateways. Do not enable it if a docker installed gateway is connected to your Room.

By default, the automatically scheduled updates are configured to occur in the wee hours of the next morning, between 3am and 4am in the time zone where the Room's infrastructure is located. This is expected to be a time of low usage for the Room. (Follow instructions in the View a Room's region section in the Room/Desktop Connectivity - Types, Status and Settings guide to find out where your Room's infrastructure is located.)

You can see the configured update time interval in the text next to the Gateway Auto-Update field in the Room's CONNECTION tab. The time is specified in the time zone where the Room's infrastructure is located.

You are able to customize the update time interval's start time to a time that is more convenient for you. See below.

(For updates that become available close to the configured time interval, say up to half an hour before the start of the interval, the automatically scheduled update may be delayed until the next occurrence of the time interval.)

You can enable/disable the automated update feature in your Room from your Room's CONNECTION page.

Enable/disable the feature as follows:

  1. Log in to the Tehama Web UI.

     

  2. Click on the ROOMS tab.

     

  3. Click on the name of the Room you want to enable the automated update feature in. You will see the user interface for the Room.

     

  4. Click on the Room's CONNECTION tab.

     

  5. Click on the STATUS sidebar item.

     

  6. Click on the toggle in the Gateway Auto-Update field to enable or disable it.
    Note: if an automatically scheduled update is pending when the feature is disabled, the update will be cancelled.

When an update is automatically scheduled by the feature, a notification is sent to the Org Admin user of the Room's connected organization and a text link - (Update scheduled) - will appear next to the version of the affected Tehama Gateway in the list of Tehama Gateways for the Room in the CONNECTION page. The (Update scheduled) text link will disappear when the update starts.

Change the update time interval start time as follows:

Note: changing the update time interval start time when an update is already scheduled does not affect the currently scheduled update.

  1. Log in to the Tehama Web UI.

     

  2. Click on the ROOMS tab.

     

  3. Click on the name of the Room you want to reconfigure the automated update time interval in. You will see the user interface for the Room.

     

  4. Click on the Room's CONNECTION tab.

     

  5. Click on the STATUS sidebar item.

     

  6. Click on the words Change Time found in the text beside the Gateway Auto-Update field. A time selecting dialog will appear.
  7. Enter the start time for the interval and accept it. The new update time interval will be specified in the text beside the Gateway Auto-Update field.

You can see if an automatically scheduled update is pending as follows:

  1. Log in to the Tehama Web UI.

     

  2. Click on the ROOMS tab.

     

  3. Click on the name of the Room you want to check for an automatically scheduled update in. You will see the user interface for the Room.

     

  4. Click on the Room's CONNECTION tab.

     

  5. Click on the STATUS sidebar item.

     

  6. Locate the entry for the Tehama Gateway instance in the Gateway table.
    The table is only visible when 'Network Access' is set to 'Tehama Gateway'.

     

  7. Look at the Status column. If an update has been automatically scheduled, the status will display the warning icon in front of the status, e.g.: Connected warning icon, and you will see an (Update scheduled) link beside the Gateway's version.
  8. Click on the (Update scheduled) link to display a dialog listing the details of the scheduled update, including the time it is to start.

If you are already viewing the above page, you may need to refresh the page to see the correct status.

Note: the Tehama Gateway must be connected for the automated update feature to schedule an update.

The automatically scheduled update, when it occurs, 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 command line update.

After a successful update, the Gateway's version in its entry in the table will be updated. (The (Update scheduled) text link will have disappeared when the update started.) (You may need to refresh the page.)

Note: the automated update feature will only schedule updates for Tehama Gateways with version at least 3.0.0, modern Gateways. (This includes all Tehama Gateway AMI instances.) Use the command line update method for legacy versions to bring them up to the currently available version. If an automatically scheduled update fails, try a manually triggered update. If the manually triggered update fails, use the command line method for modern versions.

Note: the automated update feature will not trigger updates for Tehama Gateways installed using Docker. Please follow the Command line Update for Tehama Gateways running inside a Docker container

Manually Triggered update for modern Gateway versions (3.0.0 and later)

Only the Org Admin user of a Room's connected organization (owner+connected or connected-only) can manually trigger updates of the Room's Gateways.

Note: Manually triggered updates are only available after Tehama Gateway version 3.0.0 has been installed, a modern Gateway. (This includes all Tehama Gateway AMI instances.) Use the command line update method for legacy versions to bring them up to the currently available version. If the manually triggered update fails for a modern Gateway, use the command line method for modern versions.

The Org Admin user of a Room's connected organization can manually trigger an update for a Gateway that has an update available.

To update a Gateway using the manually triggered update method, there are two basic steps:

Step 1 - Detect a pending update

Tehama will automatically detect when an update becomes available for a Tehama Gateway. It will display an indication that an update is available in the Tehama Web UI, visible to the Org Admin user and Org Managers and Room Managers (who are members of the Room) of both the Room's connected organization and its owner organization.

Look to see if an update is available as follows:

  1. Log in to the Tehama Web UI.

     

  2. Click on the ROOMS tab.

     

  3. Click on the name of the Room you want to check for a Gateway update in. You will see the user interface for the Room.

     

  4. Click on the Room's CONNECTION tab.

     

  5. Click on the STATUS sidebar item.

     

  6. Locate the entry for the Tehama Gateway instance in the Gateway table.
    The table is only visible when 'Network Access' is set to 'Tehama Gateway'.

     

  7. Look at the Status column. If an update is required, the status display the warning icon in front of the status, e.g.: Connected warning icon, and an 'Update' action will be available under the action menu for the Gateway.

If that 'Update' action is present, then there is a pending update. Select this 'Update' action to display a dialog listing the details of the latest available update.

If you are already viewing the above page, you may need to refresh the page to see the correct status.

Note: the Tehama Gateway must be connected in order to manually trigger an update.

Step 2 - Trigger the pending update

continued from step 1...

In step 1 you navigated to the STATUS page in the Room's CONNECTION tab and found an 'Update' action is available for a Gateway instance (under the Actions column for the entry).

  1. Click on the 'Update' action in the actions menu for the Gateway entry to display the UPDATE dialog. This dialog lists the details of the latest available update.

     

    Org Managers and Room Managers (who are members of the Room) of the connected organization and the Org Admin user and Org Managers and Room Managers (who are members of the Room) of the owner organization will:
    see information about the update in the dialog but will be unable to trigger it. Alert the Org Admin user for the connected organization.

    The Org Admin user of the connected organization will:
    see information about the update in the dialog and be able to trigger the update.

     

    The Org Admin user of the connection organization can continue on:

     

  2. Choose a time to trigger the update. (The update will occur shortly after you trigger it.)
    IMPORTANT: 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 to trigger the update when the update will cause the least disruption to users of the Room.

     

  3. At that time click on the UPDATE button on the UPDATE dialog to trigger the start of the update. An (Update scheduled) text link will appear beside the Gateway's version for the short time before the update starts.

The manually-triggered 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 command line update.

After a successful update, the Gateway's version in its entry in the table will be updated and the '(Update scheduled)' text link will disappear. (You may need to refresh the page.)

Note: the manually triggered update will not work for Tehama Gateways installed using Docker. Please follow the Command line Update for Tehama Gateways running inside a Docker container

Note: if the Room has the 'Multiple Gateways' option enabled and there are two Tehama Gateways that both need updating, it is good practice to update one Gateway at a time, ensuring that the first update has completed successfully before starting the second. This way the Room will be able to maintain connectivity throughout the update process.

Command line update for legacy Gateway versions (before 3.0.0)

For legacy Tehama Gateways (1.0.0 and 2.0.0) running directly on Linux, you can update the Tehama Gateway from the command line (in a 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 (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 .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.

Command line update for modern Gateway versions (3.0.0 and above)

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

  1. Determine that there is a running Tehama Gateway by running the following command:
    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

Command line update for Gateways running inside a Docker container

For Tehama Gateways running inside the Docker container you can update the gateway via the command line. Instructions to do so can be found at the bottom of Tehama's page for the tehama-gateway on dockerhub at this link: https://hub.docker.com/r/tehama/tehama_gateway#docker-manual-update

Related articles