Remote Connection (SSH)

OpenShift Online uses the Secure Shell (SSH) network protocol to authenticate account credentials to the OpenShift Online servers for secure communication, and supports both RSA and DSA keys for SSH authentication.

OpenShift uses SSH for performing Git operations and to provide remote access to your application gear.

Setting up SSH Keys

When the client tools are installed and the rhc setup command is initially run to configure the client tools, the setup wizard generates a new pair of SSH keys in the default .ssh folder of your home directory.

For Windows users, rhc setup will only upload your public key if you’ve already installed Ruby and Git for Windows. Alternatively, you can use PuTTY to connect to your application with SSH.

As part of the initial configuration, you have the option of automatically uploading the public key to the remote server. Your account can have one or more public SSH keys associated with it, and you can access your account from any workstation that has the private SSH key on it.

Red Hat recommends that you use the interactive setup wizard to create and configure SSH keys so that your workstation can authenticate and communicate with the remote server. Run the interactive setup wizard with the rhc setup command.

Once rhc setup is run, you can log into your applications remotely from your computer, or connect and download the application source code via Git. If you have multiple computers, repeat the rhc setup procedure so that each computer has access to the application.

If you would prefer to manually create and upload an SSH key, you can follow this guide. SSH keys can be uploaded using the rhc sshkey add command or through the web console.

Connecting to an Application

Once you have created an application and set up your SSH keys (either by rhc setup or manual upload), you can SSH into the remote server using the rhc ssh command.

To SSH into a specific application:

$ rhc ssh <app_name>

You should then connect to your application’s primary gear:

    *********************************************************************

    You are accessing a service that is for use only by authorized users.
    If you do not have authorization, discontinue use at once.
    Any use of the services is subject to the applicable terms of the
    agreement which can be found at:
    https://www.openshift.com/legal

    *********************************************************************

    Welcome to OpenShift shell

    This shell will assist you in managing OpenShift applications.

    !!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!!
    Shell access is quite powerful and it is possible for you to
    accidentally damage your application.  Proceed with care!
    If worse comes to worst, destroy your application with "rhc app delete"
    and recreate it
    !!! IMPORTANT !!! IMPORTANT !!! IMPORTANT !!!

    Type "help" for more info.

Now that you’re connected, you can use the OpenShift shell to explore and modify your application.

Common Commands

The following commands are available to help control your OpenShift application and environment:

gear            control your application (start, stop, restart, etc)
                or deps with --cart      (gear start --cart mysql-5.1)
tail_all        tail all log files
export          list available environment variables (1)
rm              remove files / directories
ls              list files / directories
ps              list running applications
kill            kill running applications
mysql           interactive MySQL shell
mongo           interactive MongoDB shell
psql            interactive PostgreSQL shell
quota           list disk usage

Deprecated:
ctl_app         control your application (start, stop, restart, etc)
ctl_all         control application and deps like mysql in one command

1	Find more information on using Environment Variables

Using PuTTY on Windows

PuTTY is a popular free SSH client for Windows. This document shows how to install and configure PuTTY so that you can connect to your application with SSH on a Windows machine.

Using PuTTY is optional. If you’ve installed Ruby and Git for Windows as outlined here, you can use the rhc ssh command to access the OpenShift shell. See Connecting to Your Application for more details on the rhc ssh command.

Video Walkthrough

Download the PuTTY Installer

Get the installer from the PuTTY download page.

Make sure you download the latest stable release under the headers Binaries and then A Windows installer for everything except PuTTYtel. It should be named something like putty-0.63-installer.exe.

Running the Installer

After downloading the installer, double click on the icon to run it.

Step 1

You are greeted by the Welcome dialog. Click the Next button to continue:

Step 2

The wizard asks you to select a directory to install PuTTY. Use the default and click the Next button to continue.

Step 3:

The wizard prompts you for the Start Menu Folder name. Use the default and click the Next button to continue.

Step 4:

You can choose to create a desktop icon or a Quick Launch icon for easier access to PuTTY. It’s recommended that you keep the option for Associate .PPK files checked. Click the Next button to continue.

Step 5:

PuTTY is ready to install. Click the Install button to start the installation process.

Step 6:

Click the Finish button to exit the installer.

Importing your SSH Key

This section assumes that rhc setup was already run or that you have completed alternate steps to create an SSH key pair for use with OpenShift. We want to import that key for use with PuTTY.

If you have not run rhc setup, visit the Getting Started page and complete the Command Line setup steps before continuing.

Step 1: Launch PuTTYgen

Launch PuTTYgen, the PuTTY key manager. From the Start Menu type putty in the search box. A list of putty applications shows up. Click on PuTTYgen. On older versions of Windows navigate to the PuTTY folder and launch it from there.

Step 2: Import the SSH Key

Once PuTTYgen starts go to the Conversions menu and select the Import key item.

Alternatively, you can use the Generate button to create a new pair of keys. Just make sure to register any new public keys in your openshift account setting page.

Step 3: Select the SSH Key for Import

A file dialog should pop up. Navigate to the .ssh directory in your user folder C:<user name>\.ssh and select the id_rsa key that was generated for you by rhc setup.

Step 4: Save the Private Key as a .PPK File

PuTTYgen loads your key and displays it. Click the Save private key button in this dialog.

Step 5: Select a Key Name

Another file dialog pops up prompting you for a location to save the key. Again navigate to the .ssh directory in your user folder C:<user name>\.ssh. Name the key something you will remember and make sure you do not overwrite any files in this directory. Good names to use are default.ppk or id_rsa.ppk.

You’ve imported your SSH key and may close the PuTTYgen application.

Configuring a Session to Connect to Your Application

This section assumes you’ve already created an application on OpenShift and now want to configure PuTTY to easily connect to it with SSH.

Step 1: Launch PuTTY

If you selected the option to put an icon on the desktop or a button the start menu, launch PuTTY from there. Otherwise, click on the Start menu and in the search box type in putty. Select the PuTTY application to run. On older versions of windows you may need to navigate to the PuTTY directory in the Start Menu and launch it from there.

Step 2: Get the SSH Address

Now we need to get the SSH address of your application to enter into PuTTY. The easiest way to find the SSH address is find it in the applications list page of the web console and click on your application to reach the details page. Once on the details page, look under the Remote Access section on the right. This section includes the ssh command and the address. In the next step copy this text, removing the ssh command from the front of the string.

Step 3: Enter the Address into PuTTY

In the Session category, under the Host Name form, paste the text you copied from the previous step, remembering to remove the ssh command from the begining of the string.

Step 4: Associate Your SSH Key with the Session

In the Category tree, expand the Connection and then SSH categories and select Auth. Click on the Browse button and navigate to the .ssh directory in your user folder C:<user name>\.ssh and select the .ppk file you saved there.

Step 5: Save Your Session

In the Category tree go back to the Session category. In the Saved Sessions form name your session. We recommend using the name of your application. Click the Save button and watch it pop up in the list.

Click the Open button to connect to your application.

Whenever you wish to connect to your application, simply select your session in the list. Click on the Load button and then click on the Open button.

Now You Are Ready to Connect to Your OpenShift Application with SSH on Windows.

Click here for a list of common commands that can be used.