SSH portal

The SSH portal allows you to manage your VM without having to contact support. This can be very useful if your VM is unreachable over the network (e.g. due to enabling a firewall without an exception for SSH), or when a reboot initiated from outside the VM is necessary to add more RAM or disk space.

Connecting

To access the portal, use your SSH client to connect to <vmname>@sshportal.sos.ethz.ch. For example, if the hostname of your VM is example.vsos.ethz.ch, the command would be ssh example@sshportal.sos.ethz.ch.

If you are not using the default keyfile, make sure to pass -i path/to/private/key so the correct keyfile gets used.

If you are connecting to the SSH portal for the first time, make sure that the host key fingerprint displayed by your SSH client matches one of the following, and paste the matching fingerprint into the SSH client prompt:

384 SHA256:p0rVm7ztNmuUBS75M/wWqG49Vy4XF8+eSXLpup0Y8DU ssh_host_ecdsa_key.pub (ECDSA)
256 SHA256:bYhkUA32VVH3Q4IfaLdHk1o4FA0DmLGYfrSxO53m6R0 ssh_host_ed25519_key.pub (ED25519)
4096 SHA256:06sUK5mBDqP3DJDDvImALNJDu20XirK8XoQoDRuQnxA ssh_host_rsa_key.pub (RSA)

There is a rate limit in place. You may receive an error message similar to the following:

kex_exchange_identification: read: Connection reset by peer
Connection reset by 2001:67c:10ec:49c3::23 port 22

In that case, wait at least ten seconds before your next connection attempt.

If you get a Permission denied error, make sure you are using the right keyfile. It is also possible that your VM was disabled upon request of ETH IT Services, in which case you should have received an email with additional information.

If your VM is very old (5+ years), it may lack some internal information or hardware that is necessary for the SSH portal to function. If you wish to use this feature, please .

The title line displays the hostname of the VM you are currently managing. The line above the options displays the current VM status (running or stopped).

The options in the main menu are as follows:

  • Attach to the serial console. This detaches the serial console from any other session that is currently attached.
  • Start the VM, if it isn’t already running.
  • Reboot the VM. This will prompt for a reboot type: Graceful or forced. A graceful reboot shuts down the VM cleanly, where as a forced reboot immediately resets it. Graceful reboots may not work if the guest OS has not booted successfully. You may also cancel at this prompt, but this does not cancel any reboots that are already in progress.
  • Shut down the VM. This behaves identically to the reboot option, except it does not start the VM back up.
  • View or edit the authorized_keys.
  • Set the password for the ubuntu or debian user.
  • Exit, closing the SSH session.
  • Refresh the VM status.

Serial Console

The serial console defaults to 80 columns by 24 lines. You can tell the shell to resize using the following command:

stty cols WIDTH rows HEIGHT

Replace WIDTH and HEIGHT with the desired numbers. You can also run the resize command without any arguments if you have the xterm package installed.

It is normal for the login prompt not to appear until you press Enter.

Log with username debian or ubuntu depending on the OS of the VM. If you have not set a password, you must do so first before being able to log in via the serial console.

It is possible to access the UEFI menu via the serial console.

Only one session can be attached to the serial console at any given time. Attaching from one session will detach the serial console from all other sessions.

To detach from the serial console and go back to the main menu, press the Ctrl-] key combination.

Note: Detaching will not log out the shell session! Use the exit command first.

Key Management

Any changes made in this menu apply to the SSH portal itself immediately. Make sure to test if you are still able to log in before closing your existing session.

The changes do not immediately apply inside the VM, a reboot is needed for them to become effective. This will only ever add keys to the authorized_keys file inside the VM, but never remove any - that needs to be done manually. When making any changes via the SSH portal, any keys not present in authorized_keys on the VM will be re-added automatically, so be sure to remove any keys you don’t want from the SSH portal as well to prevent them from reappearing unexpectedly.

Modifications here will also cause the SSH host keys to be regenerated when the changes are applied on the next reboot, so you will have to re-validate them.

SSH keys with options (e.g. from for source IP address allowlisting) can currently not be used to log into the SSH portal.

The order of the keys listed in this menu is random.

Adding the same key twice is prevented by the system.

The system distinguishes between user keys and the support key. User keys are provided by the user during signup or via the SSH portal, whereas the support key is added automatically when the VM is created and is intended to allow access by VSOS admins in case of a support request. You may remove the support key if you wish to do so, and re-add it using the Grant support access option, should you later decide to change your mind.

The Remove key option ensures that at least one user key is always present, to provide a basic safeguard against locking yourself out. This does not help if you no longer have access to any of the active user keys, in which case you will have to .

Password

This operation only affects the debian or ubuntu user, depending on the OS of the VM.

Logging in via the serial console requires a password to be set. Selecting the Set password option from the main menu will prompt you to enter a new password twice. The password will not echo, not even with asterisks.

The new password will apply on reboot, and the SSH host keys will be regenerated, so you will have to re-validate them the next time you connect to your VM over SSH.

Note that the guest OS needs to have cloud-init installed for this option to work. On our official Debian and Ubuntu images, this is already the case - If you overwrite it with a custom OS, you need to set this up yourself.

SSH Host Key Regeneration

Whenever changes to the authorized_keys or the password are applied by rebooting, the SSH host keys of the VM will be regenerated. This is a cloud-init quirk.

Your SSH client will display a security warning at the next connection attempt. Follow its instructions to remove the offending lines from ~/.ssh/known_hosts on your client, then connect again and verify the new host keys.

To do so, use the serial console to run the following commands as root:

ssh-keygen -l -f /etc/ssh/ssh_host_ecdsa_key
ssh-keygen -l -f /etc/ssh/ssh_host_ed25519_key
ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key

Find the fingerprint matching the one shown by your SSH client and paste it into the prompt. If none of the fingerprints match, you are the victim of a Man-in-The-Middle attack and should not continue.

UEFI Menu Access

You may access the UEFI menu of the VM. This is only useful when support has set up a second boot device (e.g. for recovery) and you want to switch boot options.

To do this, start the VM, then immediately attach to the serial console and repeatedly press the ESC key until you are presented with the menu. If you have difficulty with this, it might help to start the VM from one session and attach via serial from another.