OCI Console Connection when PowerShell Fails

TLDR – You followed the directions to create a Serial console connection but it failed, now what?  Break the command apart for troubleshooting, plus a list of issues and answers at the end

 Following the directions

Mr. Steve Nelson @ Oracle wrote some brilliant directions covering how to create a serial console connection in OCI. Steve’s directions cover how to create a private and public key pair in putty, how to create the console connection in the OCI web console, how to modify the command, and how to connect with VNC. 90% of the time this works every time. Out of the other 10% of the times, customers end up calling my team and asking for help often. In my year with OCI support, I’ve seen a number of failures with the commands. Enough to have come up with a list of common errors, and some basic troubleshooting suggestions.

Common troubleshooting – break up

First, you should understand some PowerShell basics and what the command provided by Oracle is doing. If we break the command down what it is doing is creating two ssh tunnels to OCI as follows:

1. The first tunnel establishes a connection to the serial console endpoint in the datacenter.  //starts like this// Start-Job { Echo N | plink.exe -i c:\bob\key.ppk -N -ssh -P 443 -l ocid1.instanceconsoleconnection.oc1.eu-frankfurt-
2. The second tunnel goes through the first tunnel connecting to the instance creating a connection between a local VNC server listening on port 5900 and the remote instance. //starts after the sleep command with //plink.exe -i c:\bob\key.ppk -N -L 5900:localhost:5900

The first tunnel connect is run as a powershell job – Start-job – If anything goes wrong in the job you do not see it in the PowerShell windows you’re working in because it’s run as a job in a bubble. Hence our number one troubleshooting tool is to break the command in half and create the first tunnel outside of the start-job. When we split the command out we can interact with the first command and enter keyphrases or say yes to store the key or we can see errors. Basically we stop hidding the problem. See below Example how the command looks after you receive it from Oracle and fix the key path, then how it would look split into sections.

The command provided // What the command should look like

Start-Job { Echo N | plink.exe -i c:\bob\key.ppk -N -ssh -P 443 -l ocid1.instanceconsoleconnection.oc1.eu-frankfurt-1.antheljrsdy6wiqcywr52u7zkjum5fh6mqqxnvq5mnkl7xtkfnhg34caw7ha -L 5905:ocid1.instance.oc1.eu-frankfurt-1.abtheljr4ixfhqm6g4da54ks2yjaxadmap47g3veaze2gici644alkihukga:5905 instance-console.eu-frankfurt-1.oraclecloud.com }; sleep 5; plink.exe -i c:\bob\key.ppk -N -L 5900:localhost:5900 -P 5905 localhost -l ocid1.instance.oc1.eu-frankfurt-1.abtheljr4ixfhqm6g4da54ks2yjaxadmap47g3veaze2gici644alkihukga

For troubleshooting, you break the command in half and run it in two separate admin PowerShell sessions. You run command 1, wait a few seconds after it is up, then run the second command in a seperate window.

Command 1 to establish the tunnel to the datacenter

plink.exe -i c:\bob\key.ppk -N -ssh -P 443 -l ocid1.instanceconsoleconnection.oc1.eu-frankfurt-1.antheljrsdy6wiqcywr52u7zkjum5fh6mqqxnvq5mnkl7xtkfnhg34caw7ha -L 5905:ocid1.instance.oc1.eu-frankfurt-1.abtheljr4ixfhqm6g4da54ks2yjaxadmap47g3veaze2gici644alkihukga:5905 instance-console.eu-frankfurt-1.oraclecloud.com

Command 2 to create the VNC endpoint – taken from after the sleep.

plink.exe -i c:\bob\key.ppk -N -L 5900:localhost:5900 -P 5905 localhost -l ocid1.instance.oc1.eu-frankfurt-1.abtheljr4ixfhqm6g4da54ks2yjaxadmap47g3veaze2gici644alkihukga

Running list of errors and common solutions

The following is a list of common issues and their solutions. I’ll update the list with new issues as I run into them. If you run into something not in this list leave a comment and I will add it to the list.

• Unable to open connection: Host not found – This is often caused by something going wrong with the first tunnel. Problems and Solutions as follows:
  • The path to the PPK file had spaces in it and was no blocked off with “” – Example | -i c:\bob is great\bob.ppk should be -i “c:\bob is great\bob.ppk”

• FATAL ERROR: Network error: Connection refused – There was an error running the first command. Problems and Solutions as follows:
  
  • The path to the PPK file was incorrect, or the file name was wrong – Different error then no quotes on a path with spaces
  • The PPK file does not have a correctly formatted key. The key is bad, or the key has a passphrase and Powershell never asked you to provide it – I’m providing a working public and private key pair you can use for testing. Click here to download the key pair I used for all of the screenshots.

• VNC reports connection refused by localhost – You’re trying to connect to 127.0.0.1:5900 or Localhost:5900 in VNC and the connection is refused.  Problems and Solutions as follows:
  • Most often caused by running the SSH connection command instead of the VNC connection make sure your command has a 5900 in it somewhere. Go back to the OCI web console and obtain the correct command.
• VNC reports  “Sorry, loopback connections are not enabled“ – You’re trying to connect to Localhost:5900 in VNC and it reports loopback connections are not enabled. Problems and Solutions as follows:
  • This is a setting inside of your VNC client blocking access to the name Localhost. The workaround for this, that works with most VNC clients, is to replace LocalHost with 127.0.0.1
• CategoryInfo : ObjectNotFound: (plink.exe:String) [], CommandNotFoundException ||+ FullyQualifiedErrorId : CommandNotFoundException – The command Plink is not found on your instance. Problems and Solutions as follows:
  • PLINK.EXE is not found in your session because the putty install folder is not in your folder path. Change your directory to a directory with PLINK.EXE in it. or add the folder to your path statement.