Connecting to a VM serial console via SSH

Written by

Updated at February 12, 2025

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

Alert

You can only connect to a VM serial console via SSH using a passwordless key. Attempting to use a password will terminate the connection.

After enabling access, you can connect to the serial console to manage your VM. Before connecting to a serial console, carefully read the security section.

Security

Warning

When assessing the risks associated with enabling serial console access, consider the following:

The VM will remain manageable over the internet even without an external IP address.
A user who has successfully authenticated in the Yandex Cloud management console and has the required permissions for the VM will be able to access the VM serial console from the Yandex Cloud management console. One can also access the VM serial console via SSH client applications, such as PuTTY, or through the YC CLI by authenticating with an SSH key. To reduce the risk of session hijacking, you should securely manage your SSH key and terminate web sessions.
Your session will simultaneously be shared by all users who have access to the serial console.
Users will be able to see each other's actions if concurrently viewing the serial console output.
A valid session can be accessed by another user.

We recommend enabling the serial console only when absolutely necessary, granting access permissions to a limited group of users, and using strong VM passwords.

Make sure to 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 establish a secure connection, you can use the following methods:

Download the current SHA256 fingerprint of the SSH key before each VM connection.

The first time you connect to a VM, the client shows the SSH key fingerprint and awaits confirmation to establish a connection:
- YES: Establish a connection.
- NO: Reject.
Make sure the fingerprint from the link matches the fingerprint given by the client.

Download the host's public SSH key before each serial console connection.

Use the public SSH key you got 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.

Regularly check the specified files. Download them 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 issues, your browser will display a warning.

Connecting to a serial console

Note

How a serial console works depends on how the operating system is set up. Compute Cloud provides a communication channel between the user and VM's COM port; however, it does not guarantee that the console works properly on your OS.

To connect to a 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. With OS Login access enabled, you can connect to the serial console using the exported SSH certificate. SSH keys are used to connect to VMs with OS Login access disabled.

Some operating systems may prompt you for your user credentials to access the VM. So, before connecting to the serial console of VMs running on such systems, create a local user password.

With an SSH key

With an SSH certificate via OS Login

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder through the --folder-name or --folder-id parameter.
Create a local user password on the VM:
1. Connect to the VM via 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 new username, e.g., yc-user.
  
  When prompted by the system, enter your user password and confirm it.
  
  Result:
```
passwd: password updated successfully
```
3. Disconnect from the VM. To do this, enter the logout command.

Specify the VM name and enable metadata authorization when connecting to the serial console:

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

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: INSTANCE_METADATA
gpu_settings: {}
fqdn: sample-vm.ru-central1.internal
scheduling_policy:
  preemptible: true
network_settings:
  type: STANDARD
placement_policy: {}
hardware_generation:
  legacy_features:
    pci_topology: PCI_TOPOLOGY_V1

If OS Login access is enabled at the organization level, all new VMs created in this organization will get the OS_LOGIN value in the serial_port_settings.ssh_authorization field by default. If the OS Login access is disabled, the default value of this field will be INSTANCE_METADATA.

Connect to the VM.

Here is a 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: Admin 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 prompt you for a login and password to authenticate to 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 CLI yet, install and initialize it.

The folder specified in the CLI profile is used by default. You can specify a different folder through the --folder-name or --folder-id parameter.
Create a local user password on the VM:
1. Connect to the 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 new username, e.g., yc-user.
  
  When prompted by the system, enter your user password and 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: {}
hardware_generation:
  legacy_features:
    pci_topology: PCI_TOPOLOGY_V1

Note

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.

Here is a 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 at the end of the exported certificate name, after the organization ID.
  
  You can also get the username using the yc organization-manager os-login profile list Yandex Cloud CLI command or in the Cloud Center interface in the user profile on the OS Login profiles tab.
  
  Note
  
  To view the list of OS Login profiles, a user must have the organization-manager.osLogins.viewer role or higher for the organization.
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 prompt you for a login and password to authenticate to 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 on the VM for serial console connections and the certificate is valid. Enable OS Login authorization on the VM for serial console connections or re-export the SSH certificate as required.
If you get the Connection closed by 2a0d:d6c1:0:**::*** port 9600 error when connecting using an SSH certificate, open the known_hosts file on your local machine and delete all lines that start with [serialssh.cloud.yandex.net]:9600. Then try connecting again and respond with yes to Are you sure you want to continue connecting (yes/no/[fingerprint])?.

Disconnecting from a serial console

To disconnect from a serial console:

Press Enter.
Enter ~. in succession.

Connecting to a VM serial console via SSH

SecuritySecurity

Connecting to a serial consoleConnecting to a serial console

TroubleshootingTroubleshooting

Disconnecting from a serial consoleDisconnecting from a serial console

Was the article helpful?

Security

Connecting to a serial console

Troubleshooting

Disconnecting from a serial console