Troubleshooting Instances Using Instance Console Connections

Tip

For steps to connect to a running instance by using a Secure Shell (SSH) or Remote Desktop connection, see Connecting to an Instance.

The Oracle Cloud Infrastructure Compute service provides console connections that enable you to remotely troubleshoot malfunctioning instances, such as:

  • An imported or customized image that does not complete a successful boot.
  • A previously working instance that stops responding.

There are two types of instance console connections:

  • Serial console connections

  • VNC console connections

Creating the Instance Console Connection

Before you can connect to the serial console or VNC console, you need to create the instance console connection.

To create the console connection for an instance
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
  2. Click the instance that you're interested in.
  3. Under Resources, click Console Connection.

  4. Click Create Console Connection.
  5. Upload the public key (.pub) portion for the SSH key. You can browse to a public key file on your computer or paste your public key into the text box.
  6. Click Create Console Connection.

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

Connecting to the Serial Console

After you have created the console connection for the instance, you can then connect to the serial console by using a Secure Shell (SSH) connection. When you are finished with the serial console and have terminated the SSH connection, you should delete the serial console connection. If you do not disconnect from the session, Oracle Cloud Infrastructure terminates the serial console session after 24 hours and you must reauthenticate to connect again.

Supported Instance Types for Serial Console Connections

Serial console connections are supported on the following types of instances:

  • Virtual machine (VM) instances launched in September 2017 or later
  • Bare metal instances launched in November 2017 or later

Connecting from Mac OS X and Linux Operating Systems

You connect to the serial console by using an SSH client. Mac OS X and most Linux distributions by default include the SSH client OpenSSH.

To connect to the serial console for an instance using OpenSSH on Mac OS X or Linux
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
  2. Click the instance that you're interested in.
  3. Under Resources, click Console Connection.
  4. Click the Actions icon (three dots), and then click Copy Serial Console Connection for Linux/Mac.
  5. Paste the connection string copied from the previous step to a terminal window on a Mac OS X or Linux system, and then press Enter to connect to the console.

    If you are not using the default SSH key or ssh-agent, you can modify the serial console connection string to include the identity file flag, -i, to specify the SSH key to use. You must specify this for both the SSH connection and the SSH ProxyCommand, as shown in the following line:

    ssh -i /<path>/<ssh_key> -o ProxyCommand='ssh -i /<path>/<ssh_key> -W %h:%p -p 443...
  6. Press Enter again to activate the console.

Connecting from Windows Operating Systems

Windows does not include an SSH client by default, so you need to install one. You can use PuTTY, or there are options that include a version of OpenSSH such as:

The steps to connect to the serial console from the PuTTY client are different from the steps for OpenSSH.

To connect to the serial console for an instance on Microsoft Windows
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
  2. Click the instance that you're interested in.
  3. Under Resources, click Console Connection.
  4. Click the Actions icon (three dots). Depending on which SSH client you are using, do one of the following:
    • If you are using PuTTY, click Copy Serial Console Connection for Windows.

    • If you are using OpenSSH, click Copy Serial Console Connection for Linux/Mac.

  5. Paste the connection string copied from the previous step to PuTTY or your OpenSSH client, and then press Enter to connect to the console.
  6. Press Enter again to activate the console.

Connecting to the VNC Console

Caution

The VNC console connection uses SSH port forwarding to create a secure connection from your local system to the VNC server attached to your instance's console. While this is a secure way to use VNC over the internet, owners of multiuser systems should be aware that opening a port on the local system makes it available to all of the users on that system until a VNC client connects. For this reason, we don't recommend using this product on a multiuser system unless you take proper actions to secure the port or you isolate the VNC client by running it in a virtual environment, such as Oracle VM VirtualBox.

After you create the console connection for the instance, you need to set up a secure tunnel to the VNC server on the instance, and then you can connect with a VNC client.

Supported Instance Types for VNC Console Connections

VNC console connections are supported on the following types of instances:

  • VM instances launched on October 13, 2017 or later
  • Bare metal instances that use one of the following shapes:

    • BM.Standard2.52 - launched on February 21, 2019 or later
    • BM.Standard.E2.64 - launched after September 17, 2020 in the Oracle Cloud Infrastructure commercial realm
    • BM.Standard.E3.128 - launched on February 21, 2019 or later
    • BM.DenseIO2.52 - launched on February 21, 2019 or later
    • BM.GPU2.2 - launched on February 21, 2019 or later
    • BM.GPU3.8 - launched on February 21, 2019 or later
    • BM.GPU.4.8 - launched on February 21, 2019 or later
    • BM.HPC2.36 - launched on February 21, 2019 or later

Setting up a Secure Tunnel to the VNC Server

To set up a secure tunnel to the VNC server on the instance using OpenSSH on Mac OS X or Linux
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
  2. Click the instance that you're interested in.
  3. Under Resources, click Console Connection.
  4. Click the Actions icon (three dots), and then click Copy VNC Connection for Linux/Mac.
  5. Paste the connection string copied from the previous step to a terminal window on a Mac OS X or Linux system, and then press Enter to set up the secure connection.
  6. After the connection is established, open your VNC client and specify localhost as the host to connect to and 5900 as the port to use.
Note

Mac OS X Screen Sharing.app Not Compatible with VNC Console Connections

The Mac OS X built-in VNC client, Screen Sharing.app does not work with VNC console connections in Oracle Cloud Infrastructure. Use another VNC client, such as Real VNC Viewer or Chicken.

To set up a secure tunnel to the VNC server on the instance using PowerShell on Windows
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
  2. Click the instance that you're interested in.
  3. Under Resources, click Console Connection.
  4. Click the Actions icon (three dots), and then click Copy VNC Connection for Windows.
  5. Paste the connection string copied from the previous step to Windows Powershell, and then press Enter to set up the secure connection.
  6. After the connection is established, open your VNC client and specify localhost as the host to connect to and 5900 as the port to use.

Note

Secure Connection Warning

When you connect, you may see a warning from the VNC client that the connection is not encrypted. Since you are connecting through SSH, the connection is secure, so this is not an issue.

Tagging Resources

You can add tags to your resources to help you organize them according to your business needs. You can add tags at the time you create a resource, or you can update the resource later with the desired tags. For general information about applying tags, see Resource Tags.
To manage tags for an instance console connection
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
  2. Click the instance that you're interested in.

  3. Under Resources, click Console Connection.

  4. For the console connection that you're interested in, click the Actions icon (three dots) and then click Add Tags. To view existing tags, click View Tags.

Troubleshooting Instances from Instance Console Connections

After you are connected with an instance console connection, you can perform various tasks, such as:

  • Edit system configuration files.
  • Add or reset the SSH keys for the opc user.

Both of these tasks require you to boot into a bash shell, in maintenance mode.

Note

The following tasks describe steps specific to instances running Oracle Autonomous Linux 7 and Oracle Linux 8, connecting from OpenSSH. Other OS versions and SSH clients may require different steps.

To boot into maintenance mode
  1. Reboot the instance from the Console.
  2. When the reboot process starts, switch back to the terminal window, and you see Console messages start to appear in the window. As soon as you see the GRUB boot menu appear, use the up/down arrow key to stop the automatic boot process, enabling you to use the boot menu.
  3. In the boot menu, highlight the top item in the menu, and type e to edit the boot entry.
  4. In edit mode, use the down arrow key to scroll down through the entries until you reach the line that starts with either linuxefi for instances running Oracle Autonomous Linux 7.x, Oracle Linux 8.x, and Oracle Linux 7.x, or kernel for instances running Oracle Linux 6.x.
  5. At the end of that line, add the following:
    init=/bin/bash
  6. Reboot the instance from the terminal window by entering the keyboard shortcut CTRL+X.

When the instance has rebooted, you'll see the Bash shell command line prompt, and you can proceed with either of the following procedures.

To edit the system configuration files
  1. From the Bash shell, run the following command to load the SELinux policies to preserve the context of the files you are modifying:
    /usr/sbin/load_policy -i
  2. Run the following command to remount the root partition with read/write permissions:
    /bin/mount -o remount, rw /
  3. Edit the configuration files as needed to try to recover the instance.
  4. After you have finished editing the configuration files, to start the instance from the existing shell, run the following command:
    exec /usr/lib/systemd/systemd

    Alternatively, to reboot the instance, run the following command:

    /usr/sbin/reboot -f
To add or reset the SSH key for the opc user
  1. From the Bash shell, run the following command to load the SELinux policies to preserve the context of the files you are modifying:
    /usr/sbin/load_policy -i
  2. Run the following command to remount the root partition with read/write permissions:
    /bin/mount -o remount, rw /
  3. From the Bash shell, run the following command to change to the SSH key directory for the opc user:
    cd ~opc/.ssh
  4. Rename the existing authorized keys file with the following command:
    mv authorized_keys authorized_keys.old
  5. Replace the contents of the public key file with the new public key file with the following command:
    echo '<contents of .pub key file>' >> authorized_keys
  6. Restart the instance by running the following command:
    /usr/sbin/reboot -f

Exiting the Instance Console Connection

To exit the serial console connection

When using SSH, the ~ character at the beginning of a new line is used as an escape character.

  • To exit the serial console, enter:

    ~.
  • To suspend the SSH session, enter:

    ~^z

    The ^ character represents the CTRL key

  • To see all the SSH escape commands, enter:

    ~?
To exit the VNC console connection
  1. Close the VNC client.
  2. In the Terminal or Powershell window, type CTRL C

When you are finished using the console connection, delete the connection for the instance.

To delete the console connection for an instance
  1. Open the navigation menu. Under Core Infrastructure, go to Compute and click Instances.
  2. Click the instance that you're interested in.
  3. Under Resources, click Console Connection.
  4. Click the Actions icon (three dots), and then click Delete. Confirm when prompted.