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:
- 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
- to be pasted into the Tehama Agent when prompted by the Automated-script
- 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:
- Automated-script - for Linux-based systems (Recommended method)
- Docker - for Linux / Windows / MacOS
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:
- Amazon Linux AMI release 2017.03
- Ubuntu 16.04 LTS
- CentOS 7.3.1611
- Red Hat Enterprise Server 7.3
- 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:
- Verifies prerequisite software packages are installed
- wget and/or curl
- Automated download and Unpacking of the Tehama Gateway Agent
- Registering the Tehama Gateway Agent as a system service (via rc.local)
- Execute the Tehama Gateway Agent as a background task
Tehama Gateway Agent scripted install, from the Linux host::
- Create and enter a working directory for Tehama. (e.g.: /bin/tehama)
- Download and Launch the installation script:
sudo chmod 755 get-agent.sh
sudo ./get-agent.sh -d
- At a bash prompt. Type:
- 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).
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.
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).
If you do not see an entry for 'agent', then the agent is not running.
$ ps -e | grep "agent" . . . 2054 ? 00:14:21 agent . . .
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.
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 --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 . . .
$ 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:
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
<the docker logs directory)>/gateway-agent.log
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.