Remote Access

There are several ways to access running instances remotely. The most common is to use SSH to connect directly to an instance through an external IP address. Another approach is to assign external IPs only to some instances and connect through those "bastion hosts" to other instances through their private IP addresses. The steps for configuring access are similar in both cases.

You can also connect to the instance serial console through the web UI or CLI.

SSH

Cloud images from Linux distros made for NoCloud deployment usually come with all the prerequisites for SSH on the Oxide platform. Before creating an instance, be sure to add a public key in your account settings. It will be injected into the instance at create time with cloud-init.

First, use the web UI or CLI to obtain an external IP for your instance. If the instance has more than one, you can pick any of them.

In a terminal, run

ssh [username]@[external IP]

If you are unable to SSH into a Linux VM, you can check if any of the following requirements isn’t met:

  1. SSH service running in guest: Most cloud images available in Linux distros have an SSH server installed and configured to run at boot. For custom-built images, including Windows images built from install media, you may need to install an SSH server yourself.

  2. Cloud-init metadata service running in guest: The service allows SSH keys to be captured from your user profile and appended to the $HOME/.ssh/authorized_keys file automatically when an instance is provisioned.

  3. Matching key pair: The private key used for SSH must match with one of the public keys in the authorized_keys file. The keys come from the account used to create the instance at provisioning time. SSH key changes made after instance creation are not replicated to the authorized_keys file. If you want to use a SSH key outside of the original list of SSH keys set in the key file, you’ll have to modify the file in the guest directly.

  4. Valid username: Cloud images from distro providers normally come with a built-in cloud user for login (e.g., ubuntu, debian, cloud-user). If you have configured cloud-init to create a custom user, you should be able to SSH with that user as well. If you can’t log in as the user created with cloud-init, try logging in as the built-in user and using log files in /var/log to troubleshoot.

  5. Firewall Rules: The default VPC firewall rules allow inbound TCP access on port 22. If you have configured your SSH service to use a different port, you’ll need to modify the rule named allow-ssh accordingly.

Serial Console

The serial console provides direct access to a VM through a virtual serial port. Because it goes through virtual hardware, the serial console works even while the instance is booting and when guest networking is down, making it very useful for troubleshooting. You can also interact with the UEFI shell on the serial console if your image requires boot-time interventions.

There are two ways to connect to the serial console:

  1. Web UI: Use the Connect tab on the instance detail page

  2. CLI:

    1. oxide instance serial console to stream console output continuously, or

    2. oxide instance serial history to retrieve the serial console buffer based on a byte offset

Related API References

Remote Desktop (RDP)

Accessing Windows instances requires additional tools and configuration. Detailed instructions for setting up SSH and RDP can be found in the Windows Instances guide.

Last updated