Connecting to an Instance

You can connect to a running instance by using a Secure Shell (SSH) or Remote Desktop connection. Most UNIX-style systems include an SSH client by default. Windows 10 and Windows Server 2019 systems should include the OpenSSH client, which you'll need if you created your instance using the SSH keys generated by Oracle Cloud Infrastructure. For other Windows versions, you can download a free SSH client called PuTTY from http://www.putty.org.

Required IAM Policy

To connect to a running instance with SSH, you don't need an IAM policy  to grant you access. However, to SSH you need the public IP address of the instance (see Prerequisites below). If there's a policy that lets you launch an instance, that policy probably also lets you get the instance's IP address. The simplest policy that does both is listed in Let users launch Compute instances.

For administrators: Here's a more restrictive policy that lets the specified group get the IP address of existing instances and use power actions on the instances (e.g., stop, start, etc.), but not launch or terminate instances. The policy assumes the instances and the cloud network are together in a single compartment (XYZ):

Allow group InstanceUsers to read virtual-network-family in compartment XYZ
Allow group InstanceUsers to use instance-family in compartment XYZ
If you're new to policies, see Getting Started with Policies and Common Policies. For reference material about writing policies for instances, cloud networks, or other Core Services API resources, see Details for the Core Services.

Prerequisites

You'll need the following information to connect to the instance:

  • The public IP address of the instance. You can get the address from the Instance Details page in the Console. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances. Then, select your instance. Alternatively, you can use the Core Services API ListVnicAttachments and GetVnic operations.
  • The default username for the instance. If you used an Oracle-provided Linux, CentOS, or Windows image to launch the instance, the username is opc. If you used the Ubuntu image to launch the instance, the username is ubuntu.
  • For Linux instances: The full path to the private key portion of the SSH key pair that you used when you launched the instance. For more information about key pairs, see Managing Key Pairs on Linux Instances.
  • For Windows instances: If you're connecting to the instance for the first time, you will need the initial password for the instance. You can get the password from the Instance Details page in the Console.

Connecting to a Linux Instance

You connect to a Linux instance using SSH.

To connect to a Linux instance from a Unix-style system
  1. Use the following command to set the file permissions so that only you can read the file:

    chmod 400 <private_key_file>

    <private_key_file> is the full path and name of the file that contains the private key associated with the instance you want to access.

  2. Use the following SSH command to access the instance.

    ssh –i <private_key_file> <username>@<public-ip-address>

    <private_key_file> is the full path and name of the file that contains the private key associated with the instance you want to access.

    <username> is the default username for the instance. For Oracle Linux and CentOS images, the default username is opc. For Ubuntu images, the default username is ubuntu.

    <public-ip-address> is your instance IP address that you retrieved from the Console.

To connect to a Linux instance from a Windows system using OpenSSH

If the instance uses a key pair that was generated by Oracle Cloud Infrastructure, use the following procedure.

  1. If this is the first time you are using this key pair, you must set the file permissions so that only you can read the file. Do the following:

    1. In Windows Explorer, navigate to the private key file, right-click the file, and then click Properties.
    2. On the Security tab, click Advanced.
    3. Ensure that the Owner is your user account.
    4. Click Disable Inheritance, and then select Convert inherited permissions into explicit permissions on this object.
    5. Select each permission entry that is not your user account and click Remove.
    6. Ensure that the access permission for your user account is Full control.
    7. Save your changes.
  2. To connect to the instance, open Windows PowerShell and run the following command:

    ssh –i <private_key_file> <username>@<public-ip-address>

    <private_key_file> is the full path and name of the file that contains the private key associated with the instance you want to access.

    <username> is the default username for the instance. For Oracle Linux and CentOS images, the default username is opc. For Ubuntu images, the default username is ubuntu.

    <public-ip-address> is your instance IP address that you retrieved from the Console.

To connect to a Linux instance from a Windows system using PuTTY

SSH private key files generated by Oracle Cloud Infrastructure are not compatible with PuTTY. If you are using a private key file generated during the instance creation process you need to convert the file to a .ppk file before you can use it with PuTTY to connect to the instance.

Convert a generated .key private key file:

  1. Open PuTTYgen.

  2. Click Load, and select the private key generated when you created the instance. The extension for the key file is .key.

  3. Click Save private key.

  4. Specify a name for the key. The extension for new private key is .ppk.

  5. Click Save.

Connect to the Linux instance using a .ppk private key file:

If the instance uses a key pair that you created using PuTTY Key Generator, use the following procedure.

  1. Open PuTTY.
  2. In the Category pane, select Session and enter the following:

    • Host Name (or IP address):

      <username>@<public-ip-address>

      <username> is the default username for the instance. For Oracle Linux and CentOS images, the default username is opc. For Ubuntu images, the default username is ubuntu.

      <public-ip-address> is your instance public IP address that you retrieved from the Console

    • Port: 22
    • Connection type: SSH
  3. In the Category pane, expand Window, and then select Translation.
  4. In the Remote character set drop-down list, select UTF-8. The default locale setting on Linux-based instances is UTF-8, and this configures PuTTY to use the same locale.
  5. In the Category pane, expand Connection, expand SSH, and then click Auth.
  6. Click Browse, and then select your .ppk private key file.

  7. Click Open to start the session.

    If this is your first time connecting to the instance, you might see a message that the server's host key is not cached in the registry. Click Yes to continue the connection.

Tip

If the connection fails, you may need to update your PuTTY proxy configuration.

Connecting to a Windows Instance

You can connect to a Windows instance using a Remote Desktop connection. Most Windows systems include a Remote Desktop client by default.

To enable Remote Desktop Protocol (RDP) access to the Windows instance, you need to add a stateful ingress security rule for TCP traffic on destination port 3389 from source 0.0.0.0/0 and any source port. You can implement this security rule in either a network security group that the Windows instance belongs to, or a security list that is used by the instance's subnet.

To enable RDP access
  1. Open the navigation menu. Under Core Infrastructure, go to Networking and click Virtual Cloud Networks.
  2. Choose a compartment you have permission to work in (on the left side of the page). The page updates to display only the resources in that compartment. If you're not sure which compartment to use, contact an administrator.

  3. Click the cloud network that you're interested in.
  4. To add the rule to a network security group that the instance belongs to:

    1. Under Resources, click Network Security Groups. Then click the network security group that you're interested in.
    2. Click Add Rules.
    3. Enter the following values for the rule:

      • Stateless: Leave the check box cleared.
      • Source Type: CIDR
      • Source CIDR: 0.0.0.0/0
      • IP Protocol: RDP (TCP/3389)
      • Source Port Range: All
      • Destination Port Range: 3389
      • Description: An optional description of the rule.
    4. When done, click Add.
  5. Or, to add the rule to a security list that is used by the instance's subnet:

    1. Under Resources, click Security Lists. Then click the security list you're interested in.
    2. Click Add Ingress Rules.
    3. Enter the following values for the rule:

      • Stateless: Leave the check box cleared.
      • Source Type: CIDR
      • Source CIDR: 0.0.0.0/0
      • IP Protocol: RDP (TCP/3389)
      • Source Port Range: All
      • Destination Port Range: 3389
      • Description: An optional description of the rule.
    4. When done, click Add Ingress Rules.
Connecting to a Windows Instance from a Remote Desktop Client
  1. Open the Remote Desktop client.
  2. In the Computer field, enter the public IP address of the instance. You can retrieve the public IP address from the Console.
  3. The User name is opc. Depending on the Remote Desktop client you are using, you might have to connect to the instance before you can enter this credential.
  4. Click Connect to start the session.
  5. Accept the certificate if you are prompted to do so.
  6. If you are connecting to the instance for the first time, enter the initial password that was provided to you by Oracle Cloud Infrastructure when you launched the instance. You will be prompted to change the password as soon as you log in. Your new password must be at least 12 characters long and must comply with Microsoft's password policy.

    Otherwise, enter the password that you created. If you are using a custom image, you might need to know the password for the instance that the image was created from. For details about Windows custom images, see Creating Windows Custom Images.

  7. Press Enter.

Troubleshooting the SSH Connection

If you're unable to connect to your instance using SSH, follow these troubleshooting steps to identify common problems.

  • Verify your connection: In your terminal window, run nc <public ip> 22.
    • If the SSH banner displays: You successfully connected to your instance using SSH. The underlying problem might be related to permissions. As a next step, verify your credentials. If the credentials you're using to SSH to the instance are incorrect, the connection fails.

      For Linux instances, you need the full path to the private key portion of the SSH key pair that you used when you launched the instance. For more information about key pairs, see Managing Key Pairs on Linux Instances. For Windows instances, if you're connecting to the instance for the first time, you need the initial password for the instance. You can get the password from the Instance Details page in the Console.

    • If the SSH banner does not display: A network issue might be preventing the SSH connection from succeeding. Review the following suggestions.
  • Add a public IP address: If your connection is routed over the internet, your instance must have a public IP address in order for you to connect to the instance. Without a public IP address, the instance is not reachable. For more information about how to manage public IPv4 addresses on instances, see Public IP Addresses.
  • Verify the network security lists: Oracle Cloud Infrastructure provisions each cloud network with a default set of security lists to permit SSH traffic. If the security list that permits SSH connections is removed, you can't access your instance. Ensure a security list that opens port 22 is present. You can use the Console to view and manage your security lists. For more information about security lists, see Security Lists.
  • Confirm that SSH is running on the instance: The steps for confirming that SSH is running vary depending on the operating system. Review the documentation for your operating system to find information explaining how to confirm that SSH is running.
  • Capture serial console history: To capture your instance's serial console data history, use the console-history resource in the CLI. This information can help determine the cause of connectivity problems. For more information, see console-history and Command Line Interface (CLI).

    When using the CLI to capture the instance's serial console data history, you need to include the following option to ensure that full history is captured. Without this option, the data might be truncated: --length 10000000.

  • Connect to the serial console: Serial console connections allow you to remotely troubleshoot malfunctioning instances. For more information, see Troubleshooting Instances Using Instance Console Connections.