SSH Access to Services

Last Updated October 2014

SSH Access is a staple of traditional hosting, providing a way to use many handy tools. This kind of access in a distributed cloud environment is equally valuable. Pagoda Box gives you the ability to enable SSH access for services within your application, allowing you to open a direct connection to your app's environment the way you would on a traditional host. This doc walks through enabling and using the Pagoda SSH Portal. After reading it, you should be familiar with:

  • Enabling SSH Access to a service
  • Connecting to a service through SSH
  • Maximizing your command-line awesomeness

The SSH Portal

SSH access is a valuable tool to have in your developer tool-belt. It allows you to remotely manage services on Pagoda Box, providing a way to connect to and manage a MongoDB database for example. Or SSH into a PHP web instance and run PHP commands.

There is no central SSH access point for your entire app. SSH Portals are enabled per service. Once enabled, you're able to SSH directly into a single instance within that service.

SSH'ing into web, worker, and network storage services will drop you into a shell prompt inside the home directory of a single instance within that service. When SSH'ing into database and cache services, you will be dropped into one of the service's instances, however you will not get a native shell prompt. More on interacting with services below.

Enabling SSH Access

To enable SSH access to a service, click on the service in your dashboard to expand its options. Under the "SSH" tab, click the "Enable SSH Portal" button.

Connecting Through SSH

Once SSH Access is enabled for a service, the necessary SSH connection details are provided.

Use the provided SSH "User," "Host," and "Port" to open an SSH connection.

Using SSH to Connect to a Service Terminal

  # Pattern
  $ ssh [user]@[host]:[port]
   
  #Example
  $ ssh gopagoda@123.45.67.89:1234

SSH Authentication

When opening an SSH connection, the SSH keys tied to your Pagoda Box user account are used to authenticate access to an application's services. You will not be able to SSH into a service belonging to an app of which you are not a collaborator.

If SSH'ing in from a new machine, you must add that machine's public SSH key to your user account in order to successfully connect.

Interacting with Code Services

When connecting to code services (webs & workers), you're dropped into a native shell prompt from which you can run commands. What executables are available in the service depends on the service type. The Available Executables doc provides a list of the most commonly used executables in services, however these lists are not exhaustive. It is also possible to use any command line tools deployed with your service.

Be aware, there are important things to take note of when SSH'ing into webs & workers.

Interacting with Data Services

If you SSH directly into a data service (database, cache, network storage), you will not be given a native shell prompt and will not be able to directly interact with the service. This limitation is in place to protect the data housed in these services from misguided, root-level commands and human-error. However, it is possible to interact with your data services through other means:

  1. SSH'ing into one of your code services, then connecting to and interacting with your data service from there.

  2. Using SSH port forwarding or the Pagoda Tunnel

Interacting through a Code Service

Because all code services are able to connect to data services within the same application, it's possible to SSH into a code service, then connect to the data service from the command line. Simply open the SSH connection, then use the proper command-line client and connection credentials provided for your database in your dashboard to connect to and interact the data service.

Below is an example of SSH'ing to a web service, then connecting to and interacting with a MySQL database.

Example of Interacting through a Web Service Terminal

  # Open an SSH connection to the web service
  $ ssh gopagoda@123.45.67.89:1234
   
  # Connect to the db using the connection creds provided in the dashboard
  $ mysql -h 123.45.67.89 -P 3306 -u dbuser -pdbpass dbname
   
  ##OR## 
   
  # Use environment variables to connect
  $ mysql -h$DB1_HOST -P $DB1_PORT -u $DB1_USER -p$DB1_PASS $DB1_NAME
   
  # Once connected, interact with MySQL
  mysql> show databases;

SSH Port Forwarding

SSH port forwarding allows you to remotely connect to data services through ports on your localhost and manage data using clients installed on your machine. In fact, most modern database GUIs will setup port forwarding for you through some kind SSH connection option. The screenshot below shows Sequel Pro's SSH connection UI.

The database/cache host, port, username, password, and name are found under the "Credentials" tab of your data service. The SSH user, host, and port or provided under the SSH tab of your data service.

The Pagoda CLI's "tunnel" command is also an easy way to setup port forwarding.

Manually setting up SSH port fowarding on OSX and Linux is pretty simple (sorry Windows users, it's a little harder for you). Below is the command to set it up

SSH Port Forwarding from the Command Line Terminal

  # Pattern
  $ ssh -L [local port]:[remote server]:[remote port] [user]@[remote ip]
   
  # Example
  $ ssh -L 6379:123.45.67.89:1234 gopagoda@123.45.67.89

Note:The "remote server," "remote port," "user," and "remote ip" are the SSH host, port, and user found in your dashboard.

Below is a real-world example of setting up port forwarding for a Redis cache, then connecting to the Redis service using a locally installed redis-cli and listing the keys inside Redis.

Example of SSH Port Forwarding & Redis Management Terminal

  # Create port forwarding on the local port 6379
  $ ssh -L 6379:123.45.67.89:1234 gopagoda@123.45.67.89
   
  # Use the redis-cli to connect on local port 6379
  $ redis-cli -h localhost -p 6379
   
  # List the keys inside redis
  redis localhost:6379> KEYS *
  (empty list or set)

Things to Note When Using the SSH Portal

You're Only SSH'd Into a Single Instance at a Time

It's important to note when SSH'ing into a multi-instance service, you're only connecting to a single instance within that service. Any filesystem changes will be unique to that instance.

Webs & Workers are Rebuilt on Each Deploy

On each deploy, web and worker services are completely rebuilt. Any changes made to the filesystem within webs & workers will be wiped out on your next deploy.

Changing File Permissions

While changing file permissions is possible through the SSH portal, it is not recommended. If a directory needs writable permissions, it should be listed as a network directory in your Boxfile and stored on a Network Storage service.

Pagoda Box is Not Liable for Damage Caused Through the SSH Portal

SSH access gives you a lot of power, but "with great power comes great responsibility" ~Uncle Ben.

Pagoda Box is not liable for any damage caused through the SSH portal. The most we can do is repair the service based on settings in your Boxfile. App collaborators are responsible for any data loss or data corruption resulting from actions performed through the SSH portal. It is up to you to know the risk of actions taken while SSH'd into services.

If you have any questions, suggestions, or corrections, let us know.