Connecting to a VM serial console via SSH

Written by

Updated at November 8, 2024

Security
Connecting to the serial console
- Troubleshooting
Disconnecting from the serial console

Alert

You can only connect to a VM's serial console via SSH using a non-password-protected key. Otherwise, the connection will be terminated after you enter a password.

After enabling access, you can connect to the serial console to interact with the VM. Before connecting to the serial console, carefully read the Security section.

Security

Warning

When assessing the risk of enabling access via the serial console, consider the following:

The VM can still be managed from the internet even if there is no external IP address.
To access the VM serial console from the Yandex Cloud management console, a user must be authenticated in the Yandex Cloud management console and have the proper permissions to the VM. One can access the VM serial console from an SSH client application, such as PuTTY, or the YC CLI via SSH key authentication. To reduce the risk of web session hijacking, you should closely monitor your SSH key and make sure you terminate the web session.
The session will be simultaneously shared by all users who have access to the serial console.
Users will be able to see each other's actions if concurrently watching the serial console's output.
A valid session can be exploited by another user.

We recommend using the serial console only when absolutely necessary, grant access to a narrow group of people, and use strong VM passwords.

Make sure you disable access after you finish using the serial console.

For remote access, it is important to ensure protection against MITM attacks. To do that, you can use client/server encryption.

To set up a secure connection:

You can download the current SHA256 fingerprint of the SSH key before each connection to the VM.

The first time you connect to the VM, the client sends the SSH key fingerprint to the server and awaits a decision on establishing a connection:
- YES: Establish a connection.
- NO: Reject.
Make sure the fingerprint from the link matches the fingerprint received from the client.
You can download the host's public SSH key before each connection to the serial console.

Use the public SSH key you receive when connecting to the serial console.

Recommended startup options:
```
ssh -o ControlPath=none -o IdentitiesOnly=yes -o CheckHostIP=no -o StrictHostKeyChecking=yes -o UserKnownHostsFile=./serialssh-knownhosts -p 9600 -i ~/.ssh/<private_SSH_key_name> <VM_ID>.<username>@serialssh.cloud.yandex.net
```
The host's public SSH key may be changed in the future.

Check the specified files often. Download these files only via HTTPS after verifying the validity of the https://storage.yandexcloud.net website certificate. If the website cannot securely encrypt your data due to certificate problems, the browser will warn you about that.

Connecting to the serial console

Note

How the serial console works depends on the operating system settings. Compute Cloud provides a communication channel between the user and COM port on the VM, but it does not guarantee that the console works properly on the OS.

To connect to the VM, you need its ID. For info on how to get the VM ID, see Getting information about a VM.

Your next steps depend on whether OS Login access is enabled for the VM. If OS Login access is enabled for the VM, you can connect to the serial console using an exported SSH certificate. SSH keys are used to connect to VMs with OS Login access disabled.

Some OS's may request user credentials to access a VM. In such cases, you need to create a local user password before connecting to the serial consoles of such VMs.

With an SSH key

With an SSH certificate via OS Login

Create a local user password on the VM:
1. Connect to the VM over SSH.
2. Create a user to authenticate on the VM through the serial console and set a local password for it:
```
sudo useradd <username> && sudo passwd <username>
```
  Where <username> is the name of the new user, e.g., yc-user.
  
  When prompted by the system, enter your user password, then confirm it.
  
  Result:
```
passwd: password updated successfully
```
3. Disconnect from the VM. To do this, enter the logout command.
Connect to the VM.

Connection command example:
```
ssh -t -p 9600 -o IdentitiesOnly=yes -i <path_to_private_SSH_key> <VM_ID>.<username>@serialssh.cloud.yandex.net
```
Where:
- private_SSH_key_path: Path to the private part of the SSH key obtained when creating the VM.
- VM_ID: VM ID. For info on how to get the VM ID, see Getting information about a VM.
- username: Administrator name specified when creating the VM.
```
ssh -t -p 9600 -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 fhm0b28lgfp4********.yc-user@serialssh.cloud.yandex.net
```
When connecting, the system may request a username and password to authenticate on the VM. Enter the username and password you created earlier to gain access to the serial console.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.
Create a local user password on the VM:
1. Connect to a VM via OS Login.
2. Create a user to authenticate on the VM through the serial console and set a local password for it:
```
sudo useradd <username> && sudo passwd <username>
```
  Where <username> is the name of the new user, e.g., yc-user.
  
  When prompted by the system, enter your user password, then confirm it.
  
  Result:
```
passwd: password updated successfully
```
3. Disconnect from the VM. To do this, enter the logout command.

Get a list of VMs in the default folder:

yc compute instance list

Result:

+----------------------+-----------------+---------------+---------+----------------------+
|          ID          |       NAME      |    ZONE ID    | STATUS  |     DESCRIPTION      |
+----------------------+-----------------+---------------+---------+----------------------+
| fhm0b28lgfp4******** | first-instance  | ru-central1-a | RUNNING | my first vm via CLI  |
| fhm9gk85nj7g******** | second-instance | ru-central1-a | RUNNING | my second vm via CLI |
+----------------------+-----------------+---------------+---------+----------------------+

Enable OS Login authorization for the VM when connecting to the serial console by specifying the VM name:

yc compute instance update \
  --name <VM_name> \
  --serial-port-settings ssh-authorization=OS_LOGIN

Result:

done (6s)
id: fhm0b28lgfp4********
folder_id: b1g9d2k0itu4********
created_at: "2024-03-28T19:53:23Z"
name: first-instance
zone_id: ru-central1-a
platform_id: standard-v3
resources:
  memory: "1073741824"
  cores: "2"
  core_fraction: "20"
status: RUNNING
metadata_options:
  gce_http_endpoint: ENABLED
  aws_v1_http_endpoint: ENABLED
  gce_http_token: ENABLED
  aws_v1_http_token: DISABLED
boot_disk:
  mode: READ_WRITE
  device_name: epdu3ce920e7********
  auto_delete: true
  disk_id: epdu3ce920e7********
network_interfaces:
  - index: "0"
    mac_address: d0:0d:5c:**:**:**
    subnet_id: e2luhnr3rhf8********
    primary_v4_address:
      address: 192.168.1.21
      one_to_one_nat:
        address: 51.250.***.***
        ip_version: IPV4
    security_group_ids:
      - enpjauvetqfb********
serial_port_settings:
  ssh_authorization: OS_LOGIN
gpu_settings: {}
fqdn: sample-vm.ru-central1.internal
scheduling_policy:
  preemptible: true
network_settings:
  type: STANDARD
placement_policy: {}

Export the OS Login certificate, specifying your organization ID:

yc compute ssh certificate export \
  --organization-id <organization_ID>

Result:

Identity: /home/myuser/.ssh/yc-organization-id-bpfaidqca8vd********-yid-orgusername
Certificate: /home/myuser/.ssh/yc-organization-id-bpfaidqca8vd********-yid-orgusername-cert.pub

The exported certificate is valid for one hour.

Connect to the VM.

Connection command example:
```
ssh -t -p 9600 -i <SSH_certificate_path> <VM_ID>.<OS_Login_username>@serialssh.cloud.yandex.net
```
Where:
- <SSH_certificate_path>: Path to the exported SSH certificate, the value of the Identity field.
- <VM_ID>: ID of the virtual machine whose serial console you want to connect to.
- <OS_Login_username>: OS Login user ID in the organization. You can find the OS Login username towards the end of the exported certificate's name after the organization ID.
  You can also get the username in Yandex Cloud Organization in the user profile on the OS Login profiles tab.
Example for a user with the yid-orgusername username and a VM with the epd22a2tj3gd******** ID:
```
ssh -p 9600 -i /home/myuser/.ssh/yc-organization-id-bpfaidqca8vd********-yid-orgusername epd22a2tj3gd********.yid-orgusername@serialssh.cloud.yandex.net
```
When connecting, the system may request a username and password to authenticate on the VM. Enter the username and password you created earlier to gain access to the serial console.

You can also connect to the serial console using SSH keys for other users.

Troubleshooting

If you connect to the serial console and nothing appears on the screen:
- Press Enter.
- Restart the VM (for VMs created before February 22, 2019).
If you get the Warning: remote host identification has changed! error when connecting with an SSH key, run the ssh-keygen -R <VM_IP_address> command.
If you get the Permission denied (publickey). error when connecting with an SSH certificate, make sure OS Login authorization is enabled for the VM when connecting to the serial console and that the certificate is still valid. If required, enable OS Login authorization for the VM when connecting to the serial console or re-export the SSH certificate.

Disconnecting from the serial console

To disconnect from the serial console:

Press Enter.
Enter the following characters in succession: ~..

Connecting to a VM serial console via SSH

SecuritySecurity

Connecting to the serial consoleConnecting to the serial console

TroubleshootingTroubleshooting

Disconnecting from the serial consoleDisconnecting from the serial console

Was the article helpful?

Security

Connecting to the serial console

Troubleshooting

Disconnecting from the serial console