Connecting to a VM serial console using the CLI

Written by

Yandex Cloud

Updated at February 12, 2025

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

After enabling access, you can connect to the serial console to manage your VM.

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.

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 serial console, use the CLI.

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.

Your next steps depend on the operating system and whether OS Login access is enabled for the VM. With OS Login access enabled, you can connect to the serial console using short-lived SSH certificates. To connect to VMs with OS Login access disabled, use SSH keys.

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.

Linux with an SSH key

Linux via OS Login

Windows

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.
See the description of the CLI command for connecting to a serial console:
```
yc compute connect-to-serial-port --help
```

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 |
+----------------------+-----------------+---------------+---------+----------------------+

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 serial console of the VM you need:
```
yc compute connect-to-serial-port \
  --instance-name <VM_name> \
  --ssh-key ~/.ssh/id_ed25519
```
Where:
- --instance-name: VM name. This is a required parameter.
  Instead of the VM name, you can provide its ID in the --instance-id parameter.
- --ssh-key: Path to the private key for SSH access to the VM, e.g., ~/.ssh/id_ed25519. This is an optional parameter. If you omit it, the yc_serialssh_key SSH key will be generated.
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.

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.

For more information about the yc compute connect-to-serial-port command, see the CLI reference.

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

See the description of the CLI command for connecting to a serial console:
```
yc compute connect-to-serial-port --help
```
Connect to the serial console of the VM in question:
```
yc compute connect-to-serial-port \
  --instance-name <VM_name>
```
Where --instance-name is the VM name. This is a required parameter. Instead of the VM name, you can provide its ID in the --instance-id parameter.

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.

For more information about the yc compute connect-to-serial-port command, see the CLI reference.

See the description of the CLI command for connecting to a serial console:
```
yc compute connect-to-serial-port --help
```

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 |
+----------------------+-----------------+---------------+---------+----------------------+

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

Connect to the Windows SAC of the VM in question:
```
yc compute connect-to-serial-port \
  --instance-name <VM_name> \
  --port 2
```
Where:
- --instance-name: VM name. This is a required parameter. Instead of the VM name, you can provide its ID in the --instance-id parameter.
- --port: Number of the port to use for connecting to the serial console. This is an optional parameter. When connecting to the Windows serial console (SAC), specify 2.
When prompted by the system, enter your username, domain (VM name), and password. For more information, see Starting the command shell in the Windows SAC.

For more information about the yc compute connect-to-serial-port command, see the CLI reference.

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).

Disconnecting from a serial console

To disconnect from a serial console:

Press Enter.
Enter ~. in succession.

Connecting to a VM serial console using the CLI

Connecting to a serial consoleConnecting to a serial console

TroubleshootingTroubleshooting

Disconnecting from a serial consoleDisconnecting from a serial console

Was the article helpful?

Connecting to a serial console

Troubleshooting

Disconnecting from a serial console