Creating an SSH Tunnel to a Port in the Virtual Machine


Options



Before You Begin

Purpose

This tutorial tells you how to create a secure shell (SSH) tunnel to access the services and resources provided by your Oracle Java Cloud Service instance's virtual machine (VM).

Time to Complete

Approximately 30 minutes.

Background

Oracle Cloud services such as Oracle Java Cloud Service and Oracle Database Cloud Service are built on top of infrastructure and functionality that are provided by Oracle Compute Cloud Service. When you create an instance of one of these services, all the Oracle Compute VMs required to support the service are provisioned and configured for you.

You can access the services and resources provided by the VMs by logging into the machine through a secure shell (SSH). If the port for a resource provided by a VM is not directly accessible through the internet, you can access that resource by creating an SSH "tunnel" to a port in the VM hosting the service instance. For example, a tunnel is required for connecting a local Integrated Development Environment (IDE) such as Eclipse to your Oracle Java Cloud Service instance.

Scenario

In this tutorial you will create tunnels in two ways: first by using the PuTTY for Windows application, and then by using the ssh command in a UNIX command shell. You will confirm that the tunnel was created by launching the remote WebLogic Server Administration Console on the VM as though it was local.

What Do You Need?

You need an SSH client to create an SSH tunnel. This tutorial describes two ways to create a tunnel, one using a Windows GUI client, called PuTTY, and one using the ssh utility at the command line. You don't have to do both, although you might want to learn both ways. You'll need one or both of the following:

  • PuTTY

    PuTTY is a free, open-source implementation of several network protocols, including SSH. It is available for Windows and for UNIX platforms. PuTTY includes several utilities including a terminal emulator, an SSH key generator, and a network transfer application. You'll need the Windows version for this tutorial.

    PuTTY is available from many sites, but you can reach the main download site http://www.putty.org.

  • An SSH client, including support for the SSH protocol and a command line shell. Many implementations of UNIX and UNIX-like operating systems already include ssh; so if you have one of those, you won't have to install ssh. Check the documentation for your operating system to see if you have ssh already (or simply try typing ssh at the command line to see if it is installed already).

    If you don't already have ssh installed, you can install OpenSSH on UNIX or Cygwin for Windows. OpenSSH is available from http://www.openssh.com/portable.html. Cygwin is available from https://cygwin.com/install.html.

You should also have:

  • Some knowledge of UNIX, for working at the command line.

  • An Oracle Java Cloud Service instance for which you have log-in credentials. For information about creating an Oracle Java Cloud Service instance, go to the tutorial Getting Started with Oracle Java Cloud Service.

  • An SSH private key file that matches the SSH public key used when the Oracle Java cloud Service instance was created. For PuTTY, you need a private key in the proprietary PuTTY (.ppk) format. For ssh at the command line, you need an SSH format such as OpenSSH.

Finding the IP Address of the VM

Whether you use PuTTY or a command line shell, you must find the IP address of the VM hosting your Oracle Java Cloud Service instance before you can create an SSH tunnel.

  1. Sign in to the My Services application by clicking the link in your Welcome email. Or, you can go to http://cloud.oracle.com, click Sign In, and select the Public Cloud Services value for your region from the My Services - Select Data Center dropdown list. Either way you must provide an identity domain, user name, and password to sign in.

    When logged in, you will see the My Services Dashboard.

  2. From the Menu Icon navigation menu at the top of the page, choose Java.

    The Oracle Java Cloud Service Console is displayed. An example is shown in the following illustration.

    Oracle Java Cloud Service Console
    Description of this image
  3. Find the service instance you want to manage and click the name.

    Instance on Oracle Java Cloud Service console
    Description of this image

    The service instance Overview page is displayed, showing details about the instance. An example is shown in the following illustration.

    Instance details page
    Description of this image
  4. Make a note of the IP address of the Administration Server and, if you have one configured, the load balancer.

    Virtual machines list
    Description of this image

Using PuTTY to Create an SSH Tunnel

  1. Find putty.exe in the PuTTY folder on your computer, for example, C:\Program Files (x86)\PuTTY. Double-click putty.exe. to open it.

    The PuTTY Configuration window is displayed, showing the Session panel.

    PuTTY Configuration -  Session panel
    Description of this image
  2. In the Host Name (or IP address) box, enter the IP address of the VM. Leave the port number at the default 22.

    Host URL
    Description of this image
  3. Confirm that the Connection type option is set to SSH.

    Connection type is SSH
    Description of this image
  4. In the Category tree, expand Connection if necessary and then click Data.

    The Data panel is displayed.

    PuTTY Configuration - Data panel
    Description of this image
  5. In Auto-login username box, enter opc.

    Auto-login username prompt
    Description of this image
  6. Confirm that the When username is not specified option is set to Prompt.

    Use Prompt for unspecified username
    Description of this image
  7. In the Category tree, click SSH.

    The Options controlling SSH connections panel is displayed.

    PuTTY Configuration - Authentication panel
    Description of this image
  8. Under Protocol options, check Don't start a shell command at all.

    PuTTY Configuration - Authentication panel
    Description of this image

    This optional step ensures that only the SSH tunnel is enabled. You will not be able to use the SSH session to run commands in the command shell (although you will be able to enter the passphrase for your SSH key, as described later in this tutorial).

  9. In the Category tree, expand SSH, and then click Auth.

    The Options controlling SSH authentication panel is displayed.

    PuTTY Configuration - Authentication panel
    Description of this image
  10. Under Private key file for authentication, click Browse

    Give private key for authorizaton prompt
    Description of this image
  11. In the Select private key file window, click PuTTY Private Key Files (.ppk) to find and open the private key file that matches the public key used when the instance was created.

    Find and open private key
    Description of this image

    Note: The .ppk extension indicates that the private key is in PuTTY's proprietary format. You must use a key of this format when using PuTTY. If you have to use a key saved in a different format, see the PuTTY documentation.

  12. In the Category tree, click Tunnels.

    The Options controlling SSH port forwarding panel is displayed.

    PuTTY Configuration - Port forwarding panel
    Description of this image
  13. In the Destination box, enter admin_server_ip:9001, where admin_server_ip is the public IP address for the Administration Server that you found and recorded earlier in this tutorial. Also select Local and Auto, if they aren't already selected.

    Note: Port 9001 is the default port created specifically for connecting to the Administration Server via SSH tunnels.

    Remote IP desitination
    Description of this image
  14. In the Source Port box, type 9001, to match the the VM's port number.

    Note: It is not a general requirement of SSH tunnels that the port numbers match. However, it is a requirement of the JMX/RMI protocol that is used for communicating with the port on the Administration Server.

    Source port
    Description of this image
  15. Click Add to add the forwarded port. The local and remote ports appear in the Forwarded ports list.

    Forwarded port
    Description of this image
  16. In the Category tree, click Session. to display the Session panel again.

    PuTTY Configuration -  Session panel
    Description of this image
  17. In the Saved Sessions box, enter a name for this connection configuration. For the tutorial, type vm_session, and then click Save. When you open PuTTY the next time, you can load this configuration by selecting it and clicking Load.

    Save or load a session
    Description of the image
  18. Click Open to open the connection to the VM. If this is the first time you are connecting to the VM, the PuTTY Security Alert window is displayed, prompting you to confirm the public key.

    Click Yes to continue connecting.

    Authenticate key prompt
    Description of this image

    The PuTTY Configuration window closes and the PuTTY command window is displayed. The user name is the value you supplied earlier, in the Auto-login username box in step 5.

    Enter SSH key passphrase
    Description of this image
  19. When prompted, enter the passphrase for the key, if one was defined.

  20. The tunnel is now created. Any packets sent to the client's port 9001 will reach the VM's port 9001. In this tutorial, you established a connection between port 9001 on your client and port 9001 on the VM that hosts WebLogic Server. So you can now access port 9001 on the Administration Server (on the VM) by connecting to your client's port 9001.

    Note: This "port forwarding" established by the tunnel is different from a regular SSH session, which simply provides the secure shell for logging into and issuing commands on a remote computer.

  21. You can see that the tunnel is working by displaying the WebLogic Server Administration Console for the service instance. Enter the following into a web browser's address bar:

        localhost:9001/console

    The WebLogic Server Administration Console log-in page is displayed.

  22. Log in with your usual WebLogic Server administration log-in credentials for the Oracle Java Cloud Service instance.

    URL in address bar starts with localhost:9001
    Description of this image

    The WebLogic Server Administration Console is displayed. You can see from the localhost:9001 in the address that the tunnel is working. The local port is being forwarded to the remote host (VM) and port.

    Also, under Domain Structure in the Administration Console, you can see the name of the WebLogic Server domain in your Oracle Java Cloud Service instance.

    URL in address bar starts with localhost:9001
    Description of this image

Creating an SSH Tunnel at the Command Line

  1. In a command line shell, set the file permissions of the private key file so that only you have access to it:

        $ chmod 600 private-key-file

    where private-key-file is the path to the SSH private key file that matches the public key used when your Oracle Java Cloud Service instance was created.

  2. Run the ssh utility:

        $ ssh -i private-key-file -L local-port:vm-ip-address:vm-port opc@vm-ip-address -N

    where:

    • -L specifies that the local (client) port is to be forwarded to the remote host and port. This allocates a socket to listen to the local port. Whenever a connection is made to the local port, it is forwarded over the secure channel, and a connection is made to the host port from the remote machine.
    • private-key-file is the path to the SSH private key file that matches the public key used when your instance was created.

      Note: When using an SSH client at the command line, you cannot use a private key saved in PuTTY (.ppk) format. If the only private key you have is in PuTTY (.ppk) format, see the PuTTY documentation for instructions on how to convert it to OpenSSH format.

    • local-port is the port number on your client.

      Because the VM uses 9001 as the listen port for the Administration Server, and because the client and the VM port numbers must match, use 9001 for local-port.

    • vm-ip-address is the IP address of the VM in x.x.x.x format. For an Oracle Java Cloud Service instance, you can use the IP address of the Administration Server or the IP address of the load balancer, if one is enabled.

    • vm-port is the port number on the VM to which you want to create a tunnel. Oracle Java Cloud Service uses 9001 as the listen port for the Administration Server. Therefore, use 9001 as the vm-port.

    • opc@vm-ip-address is the user account (opc) and the VM's IP address.

    • -N ensures only the SSH tunnel is enabled. You will not be able to use the SSH session to run commands in the command shell.

    For example:

        $ ssh -i keys/id_rsa -L 9001:192.0.2.100:9001 opc@192.0.2.100

  3. If this is the first time you are connecting to the VM, the ssh utility prompts you to confirm the public key. In response to the prompt, enter yes.

    Authenticate key for host
    Description of this image
  4. At the prompt, enter the passphrase for the SSH key, if one was created.

    Enter passkey and logged in
    Description of this image
  5. Now you are logged in, and you can use any resources of that server as if it were local.

  6. You can see that the tunnel is working by displaying the WebLogic Server Administration Console for the service instance. Enter the following into a web browser's address bar:

        localhost:9001/console

    The Weblogic Server Administration Console log-in page is displayed.

  7. Log in with your usual WebLogic Server administration log-in credentials for the Oracle Java Cloud Service instance. The WebLogic Server Administration Console for your instance is displayed.

    URL in address bar starts with localhost:9001
    Description of this image

Want to Learn More?