You may occasionally run into issues with a Windows 2022 (or later) compute VM in Oracle Cloud Infrastructure (OCI) that require you to access the VM via the graphical recovery console. This article describes how to connect to a graphical recovery console, based on VNC using MacOS 15.3 Sequoia.
The latest MacOS 15.3 ships with OpenSSH_9.8p1/LibreSSL 3.3.6. It does not come with a suitable VNC client software which you need to access the console. You need to get one yourself. Unfortunately, MacOS’s own Screen Sharing app does not seem to be able to connect to the recovery (VNC) console.
Prerequisites
Most users require a graphical console connection to an OCI VM running Windows, a serial console won’t do the job. OCI offers 2 console types:
- serial
- graphical
Windows VMs typically requires the latter. This article assumes you completed the prerequisites as per the documentation. You also need to the appropriate IAM permissions, also described in the documentation.
Creating the OCI console connection
The OCI CLI provides a convenient way to create the console connection. You can of course create the local console connection from the OCI GUI, too. The command line is much more straight forward though.
First, get the instance’s Oracle Cloud ID (OCID) and store it in an environment variable INSTANCE_OCID. If you don’t have the OCID available, you can get it from the following CLI query, store your compartment OCID in COMPARTMENT_OCID first.
oci compute instance list \
--compartment-id $COMPARTMENT_OCID \
--query 'data [].{id:id,"status":"lifecycle-state",name:"display-name"}' \
--output table
Use the OCID to create the console connection. You need to specify the public key file you want to use as well.
oci compute instance-console-connection create \
--instance-id ${INSTANCE_OCID} \
--ssh-public-key-file /path/to/ssh/key.pub
Take a note of the JSON returned by the command, it contains the vnc-connection-string you will need later.
If you haven’t already, add the corresponding private key to the SSH agent.
ssh-add /path/to/ssh/key
ssh-add
You should see your key in the output of the last command.
Obtain the VNC connection string
If you don’t have access to the output of the oci compute instance-console-connection create command you can get the VNC connection string from the CLI. The following command queries the compartment for active console connections connected to your VM instance.
oci compute instance-console-connection list \
--compartment-id ${COMPARTMENT_OCID} \
--query "data [?\"instance-id\" == '${INSTANCE_OCID}' && \"lifecycle-state\" == 'ACTIVE' ].\"vnc-connection-string\""
The command prints the SSH command you need for the VNC console connection. Repeat the command a few times if you get nothing back, it might take a minute to activate the console connection.
Connecting to the VNC Console
You are nearly there, only two more steps remain:
- Creating the SSH tunnel for the VNC connection
- Establish Connecting to the VNC Console
MacOS 15 users cannot use the VNC connection string as it’s returned by the CLI without adding a couple of options. This is necessary because the SSH version shipping with MacOS 15 (Sequoia) no longer understands the ssh-rsa authentication methods required by OCI.
The initial SSH command as per the OCI CLI will look similar to this, reformatted for readability:
ssh \
-o ProxyCommand='ssh -W %h:%p -p 443 ocid1.instanceconsoleconnection.oc1.eu-frankfurt-1...4ra@instance-console.eu-frankfurt-1.oci.oraclecloud.com' \
-N -L localhost:5900:ocid1.instance.oc1.eu-frankfurt-1.a...wtya:5900 \
ocid1.instance.oc1.eu-frankfurt-1.a...nwtya
It defines a jump host by means of providing a ProxyCommand. It doesn’t run any actual commands or starts a login shell, as indicated by -N. Finally, as part of the command your local port 5900 os forwarded to your cloud VM instance’s port 5900. The local forwarding command uses localhost as its bind address.
Depending if you have Apple’s Remote Management enabled, port 5900 is going to be in use and you should perhaps avoid a port conflict by forwarding a different local port. The corrected SSH command including the ssh-rsa support, therefore, looks as follows for MacOS 15:
ssh -v \
-o HostkeyAlgorithms="+ssh-rsa" -o PubkeyAcceptedAlgorithms="+ssh-rsa" \
-o ProxyCommand='ssh -W %h:%p -p 443 ocid1.instanceconsoleconnection.oc1.eu-frankfurt-1.a...4ra@instance-console.eu-frankfurt-1.oci.oraclecloud.com' \
-N -L localhost:5910:ocid1.instance.oc1.eu-frankfurt-1.a...wtya:5900 \
ocid1.instance.oc1.eu-frankfurt-1.a...wtya
The SSH session will appear to be “stuck” – but it isn’t. It’s merely sitting there waiting for VNC connections to port 5910. Using a VNC client of your choice (except Mac’s Screen Sharing.app) to connect to the VNC console.
You will have to add the machines ssh is connecting to to your ${HOME}/.ssh/known_hosts file. If you get SSH errors like this one …
ocid1.instanceconsoleconnection.oc1.eu-frankfurt-1.a...b4ra@instance-console.eu-frankfurt-1.oci.oraclecloud.com: Permission denied (publickey).
kex_exchange_identification: Connection closed by remote host
… you forgot to add the SSH key to the SSH agent. You should add it now, or alternatively modify the SSH command to add -i /path/to/private/key to both the initial SSH command as well as the ProxyCommand.
Summary
Creating a graphical recovery console connection to an OCI Windows compute VM isn’t hard, provided you follow a few extra steps outlined in this article. Please note the steps are specific for MacOS 15 Sequoia. Whilst they are very similar for Linux-based systems you might need extra ssh arguments.
Happy Troubleshooting!
Martins Blog 