Connecting to a Database Cloud Service (DBaaS) Instance Through an SSH Tunnel

Overview

Purpose

This tutorial covers how to connect to database instances in an Oracle Database Cloud Service - Database as a Service (DBaaS) account using SSH tunneling.  

Last Updated

March 2016, Release 16.1.5

Please note that Oracle develops its cloud services in an agile manner and makes rapid changes to meet our users' needs. Therefore this tutorial may not reflect all of the changes since the last update to this service. For the very latest information see Oracle Database Cloud Service on Oracle Help Center.

Time to Complete

Approximately 30 minutes.

Introduction

When a DBaaS database instance is created, network access to the instance is limited to Secure Shell (SSH) connections on port 22. This access restriction ensures that the instance is secure by default. You can either ask your cloud service administrator to open ports or, as you will learn in this tutorial, you can use SSH client software to create an SSH tunnel to connect securely to the database and its tools. Several SSH clients are freely available, including the SSH utility on Linux platforms and the PuTTY utility on Windows platforms.

unblock or tunnel

For more detailed information on connecting to a database instance and its tools in Oracle Database Cloud Service, see Accessing Database Cloud Service in Using Oracle Database Cloud Service.

Scenario

In this tutorial, you will use the PuTTY utility on Windows to tunnel through an SSH connection to your Database Cloud Service instance hosted on a VM. With that connection established, you can then use your local PC to perform work on the DBaaS database and its tools. In this tutorial, you will use port forwarding to connect from your local PC browser to the Enterprise Manager Express tool in your DBaaS database instance.

SSH Connectivity Steps Required Prior to Performing this Tutorial:

  1. Before your DBaaS database was created, you or a coworker generated a private and public SSH key pair, perhaps using PuTTY Key Generator.

Note: If you plan to use PuTTY as your SSH client tool on Windows, you must generate the private key using the PuTTY Key Generator (PuTTYgen) utility, to create a PuTTY-compatible version of the private key.

PuTTY Key Generator

Note: For details on generating an SSH private/public key pair, see Generating a Secure Shell (SSH) Private/Public Key Pair in Using Oracle Database Cloud Service.

  1. The public key was specified when your database instance was created; a copy of that public key was stored in the VM hosting your database:
public key used when creating instance

Note: For details on creating a database, see Creating a Database Deployment in Using Oracle Database Cloud Service.

SSH Key Authentication Steps You Will Perform in this Tutorial:

When you define in PuTTY an SSH connection to the VM hosting your database, you will specify a copy of the private key stored on your local PC. When you initiate a PuTTY connection, the VM compares the private key to the matching public key stored in the VM. The VM permits the connection when the private and public key match as a valid key pair: 

key based authentication

Software Requirements

  • PuTTY SSH client for Windows
  • You need one of the supported browsers listed in the following table: 
     Browser  Version
     Microsoft Internet Explorer  9 or 10; set Browser Mode to IE9 or IE10
     Mozilla Firefox  24 and later
     Google Chrome  29 and later
     Apple Safari  6

Note: This release does not support mobile browsers.

Prerequisites

Before starting this tutorial, you should:

  • Have already procured and activated a trial or paid subscription to the Oracle Database Cloud Service (DBaaS).
  • Have generated a secure shell (SSH) private/public key pair, with a copy of the private key file on your local computer. Your SSH public key was specified when your database instance was created. For details on generating an SSH private/public key pair, see Generating a Secure Shell (SSH) Private/Public Key Pair in Using Oracle Database Cloud Service.
  • Have already created a database instance. For details on creating a database, see Creating a Database Deployment in Using Oracle Database Cloud Service.
  • Have been given the administrative password that was specified when the database instance was created. In the tutorial, you will need this password to log in to Enterprise Manager Express.

Finding the Connection Details for Your Database Instance

Before you can use the PuTTY program to connect to your database, you need to find the IP address (and SID of your database if you will be connecting to the database with tools such as SQL Developer.)
  1. Log in to the Oracle Database Cloud Service (DBaaS) console using the credentials provided by your Oracle Cloud account administrator.

    • Your administrator may provide you a link to the My Services console, from which you can choose Oracle Database Cloud Service (DBaaS).
    • Or, your administrator may provide you a direct link to the Oracle Database Cloud Service (DBaaS) console.  

    database console
  2. Click the name of the database to which you want to connect.

    click database name
  3. Write down the IP address and SID name. (You will not need the SID if you are connecting to the database with Enterprise Manager as in this tutorial, but you would need the SID name if you would be connecting to the database with tools such as SQL Developer.)

    connection information

Defining the PuTTY Connection


Define a PuTTY connection to your database, using the connection information you wrote down in the previous step.
  1. Open the PuTTY utility in your local Windows PC. In the initial dialog, enter the IP address you just noted into the Host Name field. For connection type, choose SSH.

    putty ip and ssh
  2. In the Connection category, select Data. For Auto-login username, specify oracle.

    select data specify oracle

    Note: Connect as the user oracle to perform most operations; this user does not have root access to the VM. For situations in which you need root access, such as when performing backup and restore operations not covered in this tutorial, you would specify the opc user for the Auto-login name; the opc user can use the sudo command to gain root access to the VM.

  3. In the Connection category, select SSH. Under Protocol Options, check the box Don't start a shell or command at all. (This will allow your PuTTY connection to bypass the PuTTY command line shell and utilize port forwarding to take you directly to the log in screen for Enterprise Manager Express.)

    do not start shell or command

  4. In the Connection category, expand SSH and select Auth. Click Browse to select the private SSH key file that was generated and stored on your local PC.

    click browse to select key

    select private key file

    Note: This tutorial shows you to use PuTTY as your SSH client tool on Windows. To create a PuTTY-compatible version of the private key (which requires a .ppk file extension), you can generate the private key using the PuTTY Key Generator (PuTTYgen) utility.
  5. Select Tunnels.
    1. For the source port, specify an available port on your local PC. For convenience in identifying this PuTTY connection definition, it is recommended that you use the same port number as the destination port to which you are forwarding. For this tutorial, specify Source port 5500, since you are port-forwarding to Enterprise Manager Express, whose port on the DBaaS VM is 5500.
    2. For the target port, specify the IP address you noted for the cloud VM, and append it with :5500.

    tunnels source target port forwarding
  6. Click Add. The Forwarded ports field is populated. In the screenshot below, the local port 5500 is forwarding to the destination port 5500 on a cloud database VM whose IP address is 129.152.145.60.
    Your IP address will be different from this example.

    click add for port forwarding

  7. Scroll back up the Category panel on the left side of the dialog, and click Session. In the Saved Sessions field, provide a name for this PuTTY connection definition, for example Connect to EM Express, and click Save.

    click save

Connecting to Enterprise Manager Express for Your  Cloud Database Instance

You have created a PuTTY definition for connecting through an SSH tunnel to Enterprise Manager Express for your  Database Cloud Service (DBaaS) database instance. Now open this definition to connect to Enterprise Manager Express.
  1. Click Open.

    click open

  2. Because this is the first time you are connecting to the VM, the SSH utility prompts you to confirm the public key. Click Yes.

    keep ssh tunnel open

  3. Because you specified Don't start a shell or command at all, PuTTY performs the port forwarding and presents a window without a command line prompt. Keep this PuTTY window open to maintain the SSH tunneling from your local PC to Enterprise Manager Express in your Database Cloud Service instance. If you wish, you can minimize this window.

    keep ssh tunnel open

Logging In to Enterprise Manager Express

You have created an SSH tunnel to port 5500. While keeping your PuTTY session open, you can now access Enterprise Manager Express. 

  1. Direct your browser to the URL https://localhost:5500/em. After the Enterprise Manager Express log in page is displayed, enter SYSTEM as the user name. For the password, enter the administration password that was specified when the database instance was created. Then click Login.

    log in to em express

  2. em express logged in

    Note: Some database access products, such as Oracle SQL Developer 4.0.3 or later, include functionality to connect to a database through an SSH tunnel. When using these products, you create the SSH tunnel within the product and you do not need to use the instructions shown in this tutorial.

Summary

In this tutorial, you learned to:

  • Use the PuTTY utility to connect to a  Database Cloud Service (DBaaS) database instance through an SSH tunnel
  • Specify port forwarding in your PuTTY connection, to connect from your local PC browser to Enterprise Manager Express in your DBaaS database instance

Resources

Credits

  • Lead Curriculum Developer: Rick Green
  • Other Contributors: Mike Fitch, Ben Gelernter, Dom Lindars, Brian Spendolini

To navigate this Oracle by Example tutorial, note the following:

Topic List:
Click a topic to navigate to that section.
Expand All Topics:
Click the button to show or hide the details for the sections. By default, all topics are collapsed.
Hide All Images:
Click the button to show or hide the screenshots. By default, all images are displayed.
Print:
Click the button to print the content. The content that is currently displayed or hidden is printed.

To navigate to a particular section in this tutorial, select the topic from the list.