Oracle Cloud Infrastructure Documentation

Creating an Instance Console Connection

On Compute Cloud@Customer, before you can connect to an instance VNC console or serial console, you need to create an instance console connection.

Note

Instance console connections are limited to one client at a time. If the client attempts to connect but fails to connect within five minutes, the connection is closed and a different client can connect. During the five-minute timeout, any attempt to connect a different client fails.

The instance console connection resource provides the command that you need to create the secure tunnel. The command is a little different depending on whether your local system is UNIX or Windows and whether you want to connect to the VNC console or the serial console on the instance.

Console Connection Prerequisites

Ensure that you have the following resources on the system that you plan to use to connect to the instance console.

  • SSH key pair

    If you don't already have an SSH key pair, you can use the ssh-keygen utility on UNIX systems or PuTTY puttygen.exe on Windows systems. Specify a key size of 2048 bits (this value should be the default). Give the key a name. You don't need to provide a passphrase; using a passphrase makes it more difficult to automate connecting.

  • Command-line shell and SSH client

    On Windows systems, use one of the following:

    • Windows PowerShell

      If you use PowerShell to connect to the VNC server on the instance, plink.exe is required. plink.exe is the command link connection tool included with PuTTY. You can install PuTTY or install plink.exe separately.

    • Git for Windows

      Git for Windows includes OpenSSH.

    • Windows Subsystem for Linux (WSL)

      WSL includes OpenSSH.

  • VNC viewer to connect to the VNC console

  • Ensure that you belong to a group that has the following permissions. Note – groups and policies are managed in your OCI tenancy, and not managed directly on Compute Cloud@Customer. See IAM Overview.

    Allow group group_name to manage instance-console-connection in tenancy
Allow group group_name to read instance in tenancy
    1. In the Compute Cloud@Customer Console navigation menu, click Compute, then click Instances.
    2. At the top of the page, select the compartment that contains the instance.

    3. Click the name of the instance where you want to create a console connection.

    4. On the instance details page, under Resources, click Console Connection.

    5. If a console connection doesn't already exist, click Create Console Connection.

    6. Provide the public key portion of your SSH key.

      In the Create Console Connection dialog box, do one of the following to enter your public SSH key:

      • Select the key file(s).

        • Click inside the Drag and Drop box to open a file browser and select the file.

        • Drag the file from your file browser listing and drop the file on the Drag and Drop box.

      • Paste the public key(s). Copy your public SSH key text, and paste the text into the field.

    7. Click Create Console Connection in the dialog.

      When the console connection is created and is available, the state changes to Active.

    What's Next

    Continue to Connecting to the VNC Console or Making a Local Connection to the Serial Console.

  • Use the oci compute instance-console-connection create command and required parameters to create a new serial console connection to the specified instance. Once the serial console connection is created and is available, you connect to the serial console using an SSH client.

    oci compute instance-console-connection create --instance-id <instance_OCID> --ssh-public-key-file public_SSH_key_path [OPTIONS]

    For a complete list of CLI commands, flags, and options, see the Command Line Reference.

    Procedure

    1. Get the following information:

      • The OCID of the instance where you want to create the console connection: oci compute instance list

      • Your SSH public key file.

    2. Determine whether a console connection already exists for this instance.

      oci compute instance-console-connection list -c compartment_OCID --instance-id instance_OCID

    3. Run the create console connection command.

      oci compute instance-console-connection create --instance-id ocid1.instance.unique_ID --ssh-public-key-file public_SSH_key_path
{
  "data": {
    "compartment-id": "ocid1.compartment.unique_ID",
    "connection-string": "ssh -i private_SSH_key_path -t -p 443 user_name@proxy_host tty@instance_OCID",
    "defined-tags": {},
    "fingerprint": "SHA256:unique_ID",
    "freeform-tags": {},
    "id": "ocid1.instanceconnectionconsole.unique_ID",
    "instance-id": "ocid1.instance.unique_ID",
    "lifecycle-state": "ACTIVE",
    "service-host-key-fingerprint": null,
    "vnc-connection-string": "ssh -i public_SSH_key_path -p 443 -L local_vnc_port:localhost:remote_vnc_port user_name@proxy_host vnc@ocid1.instance.unique_ID"
  },
  "etag": "afc7eb68-5f1a-40cc-8dc3-8a1cae237230"
}

      The value of connection-string is the SSH connection string for the instance serial console connection. The value of vnc-connection-string is the SSH connection string for the instance VNC console connection.

    4. When you're finished using this instance console connection, use the following command to delete the connection.

      $ oci compute instance-console-connection delete --instance-console-connection-id instance_console_connection_OCID

    What's Next

    Continue to Connecting to the VNC Console or Making a Local Connection to the Serial Console.

  • This task can't be performed using the API.

    For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.