# Connecting to a Linux VM serial console

{% note warning %}

When assessing the risks associated with enabling VM access via the serial console, keep in mind 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](https://console.yandex.cloud) and has the required [access permissions](../../security/index.md) for the VM will be able to access the serial console.
    
    One can also access the VM serial console via [SSH](../vm-connect/ssh.md) client applications, such as PuTTY, or through the [CLI](../../../cli/index.md) by authenticating with an SSH key. Therefore, make sure to prevent any unauthorized access to your SSH key and always end the web session to reduce interception risks.

* Your serial console 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 serial console session can be accessed by another user.

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

When you are done using the management console, do not forget to [ban](index.md#disable) access to it.

{% endnote %}

To connect to a VM's [serial console](../../concepts/serial-console.md), first [enable serial console access](index.md#enable) for the VM instance.

You can connect to the serial console through the [management console](https://console.yandex.cloud), as well as using the standard SSH client or via [OS Login](../../../organization/concepts/os-login.md).

Before connecting to the serial console, carefully read this section: [Security when using SSH](../../concepts/serial-console.md#security).

## Getting started {#before-you-begin}

Some operating systems may request local user data to access the VM serial console. Therefore, before connecting to the serial console of a VM running such an OS, create a local user password.

In the example below, you will create a new local Linux user account with password protection:

1. Connect to the VM [over SSH](../vm-connect/ssh.md) or [via OS Login](../vm-connect/os-login.md).
1. Create a new local user account with password protection:

    ```bash
    export NEW_USERNAME=<new_username>
    sudo useradd -m -d /home/$NEW_USERNAME -s /bin/bash $NEW_USERNAME \
    && sudo passwd $NEW_USERNAME
    ```

    The system will prompt you to enter and confirm the password for the new user:

    ```text
    New password:
    Retype new password:
    passwd: password updated successfully
    ```

{% note warning %}

How a serial console works depends on how the operating system is set up. Yandex Compute Cloud provides a channel between the user and the virtual machine's COM port and does not guarantee the stability of the console's operation from the OS side.

{% endnote %}

## Connecting via the management console {#connect-via-console}

{% list tabs %}

- Management console

  1. In the [management console](https://console.yandex.cloud), select the [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder) the VM instance resides in.
  1. Navigate to **Compute Cloud**.
  1. In the left-hand panel, select ![server](../../../_assets/console-icons/server.svg) **Virtual machines** and select the VM instance from the list that opens.
  1. In the left-hand menu, select **Serial console**.
  1. At the top of the screen, in the drop-down list, select the [serial port](../../concepts/serial-console.md#serial-ports) used by the serial console for VM connections.

      By default, serial port `COM1` is used on Linux VMs. To use a different port, configure it manually on your VM OS side.

  1. In the serial console window that opens, enter the username and password you set [earlier](#before-you-begin).

{% endlist %}

{% note warning %}

When you are done using the management console, do not forget to [ban](index.md#disable) access to it.

{% endnote %}

## Connecting using a standard SSH client {#connect-with-ssh-client}

{% note alert %}

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

{% endnote %}

Make sure you have the [Yandex Cloud CLI](../../../cli/index.md) installed and configured on your machine.

If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

Your next steps depend on whether [OS Login](../../../organization/concepts/os-login.md) access is enabled for the VM. With OS Login access [enabled](../vm-connect/enable-os-login.md), you can connect to the serial console using the exported SSH certificate. To connect to VMs with OS Login access disabled, use SSH keys.

{% list tabs group=os_login_type %}

- Connecting with an SSH key {#ssh-key}

  1. Enable metadata authorization when connecting to the serial console:
     
     ```bash
     yc compute instance update <VM_name_or_ID> \
       --serial-port-settings ssh-authorization=INSTANCE_METADATA \
       --metadata enable-oslogin=false,serial-port-enable=1,ssh-keys='<username>:<public_SSH_key>'
     ```
     
     Where:
     * `<VM_name_or_ID>`: To learn how to find out the VM name or ID, see [Getting information about a VM](../vm-info/get-info.md).
     * `--metadata`: VM [metadata](../../concepts/vm-metadata.md):
     
         * `ssh-keys`: Name of the local VM user and the contents of the [public SSH key](../vm-connect/ssh.md#creating-ssh-keys) that will allow this user to connect to the VM over SSH.
     
     Result:
     
     ```yaml
     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
     ```
     
     For more information about the `yc compute instance update` command, see the [CLI reference](../../../cli/cli-ref/compute/cli-ref/instance/update.md).
     
     {% note info %}
     
     If OS Login access is [enabled](../../../organization/operations/os-login-access.md) 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 OS Login access is disabled in the organization, the default value of this field will be `INSTANCE_METADATA`.
     
     {% endnote %}
  1. Connect to the VM's serial console:

      ```bash
      ssh -t \
        -p 9600 \
        -o IdentitiesOnly=yes \
        -i <path_to_private_SSH_key> \
        <VM_ID>.<username>.port=1@serialssh.cloud.yandex.net
      ```

      Where:

      * `private_SSH_key_path`: Path to the private part of the [SSH key](../vm-connect/ssh.md#creating-ssh-keys) you use to access the VM.
      * `VM_ID`: VM ID.
      * `user_name`: Username for SSH connections, as stated in the VM metadata.
      * `port=1`: Number of the [serial port](../../concepts/serial-console.md#serial-ports) used by the serial console for VM connections.

          By default, serial port `COM1` is used on Linux VMs. To use a different port, configure it manually on your VM OS side.

      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](#before-you-begin) to gain access to the VM instance.
  1. Finish using the serial console:
     
     1. Exit the local OS user profile:
     
         ```bash
         exit
         ```
     1. Close the serial console session. Do it by entering the following character sequence:
     
         ```text
         ~.
         ```

- Using a certificate via OS Login {#ssh-cert}

  1. Enable OS Login authorization when connecting to the serial console:
     
     ```bash
     yc compute instance update <VM_name_or_ID> \
       --serial-port-settings ssh-authorization=OS_LOGIN \
       --metadata enable-oslogin=true,serial-port-enable=1,ssh-keys='<username>:<public_SSH_key>'
     ```
     
     Where:
     * `<VM_name_or_ID>`: To learn how to find out the VM name or ID, see [Getting information about a VM](../vm-info/get-info.md).
     * `--metadata`: VM [metadata](../../concepts/vm-metadata.md):
     
         * `ssh-keys`: Name of the local VM user and the contents of the [public SSH key](../vm-connect/ssh.md#creating-ssh-keys) that will allow this user to connect to the VM over SSH if access via OS Login is disabled for this VM later.
     
     Result:
     
     ```yaml
     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
     ```
     
     For more information about the `yc compute instance update` command, see the [CLI reference](../../../cli/cli-ref/compute/cli-ref/instance/update.md).
     
     {% note info %}
     
     If OS Login access is [enabled](../../../organization/operations/os-login-access.md) 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 OS Login access is disabled in the organization, the default value of this field will be `INSTANCE_METADATA`.
     
     {% endnote %}
  1. [Export](../vm-connect/os-login-export-certificate.md) the OS Login certificate by specifying your organization [ID](../../../organization/operations/organization-get-id.md):

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

      Result:

      ```text
      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.
  1. Connect to the VM's serial console:

      ```bash
      ssh -t \
        -p 9600 \
        -i <SSH_certificate_path> \
        <VM_ID>.<OS_Login_username>.port=1@serialssh.cloud.yandex.net
      ```

      Where:
      * `<SSH_certificate_path>`: Path to the SSH certificate (`Identity`) you exported earlier.
      * `<VM_ID>`: VM ID.
      * `<OS_Login_username>`: OS Login username in the organization. You can find the OS Login username at the end of the exported certificate name, after the organization [ID](../../../organization/operations/organization-get-id.md).

          You can also get the username using the `yc organization-manager os-login profile list` [Yandex Cloud CLI](../../../cli/cli-ref/organization-manager/cli-ref/oslogin/profile/list.md) command or in the [Cloud Center interface](https://center.yandex.cloud/organization) in the user profile on the **OS Login Profiles** tab.

          {% note info %}
          
          The minimum required role allowing you to view the list of OS Login user profiles is the `organization-manager.osLogins.viewer` [role](../../../organization/security/index.md#organization-manager-osLogins-viewer) assigned for your organization. For information about other roles allowing you to view the list of OS Login profiles, see [Access management in Yandex Identity Hub](../../../organization/security/index.md#service-roles).

          {% endnote %}

      * `port=1`: Number of the [serial port](../../concepts/serial-console.md#serial-ports) used by the serial console for VM connections.

          By default, serial port `COM1` is used on Linux VMs. To use a different port, configure it manually on your VM OS side.

      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](#before-you-begin) to gain access to the VM instance.
  1. Finish using the serial console:
     
     1. Exit the local OS user profile:
     
         ```bash
         exit
         ```
     1. Close the serial console session. Do it by entering the following character sequence:
     
         ```text
         ~.
         ```

{% endlist %}

{% note warning %}

When you are done using the management console, do not forget to [ban](index.md#disable) access to it.

{% endnote %}

## Connecting via the Yandex Cloud CLI {#connect-with-yc-cli}

{% note alert %}

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

{% endnote %}

Make sure you have the [Yandex Cloud CLI](../../../cli/index.md) installed and configured on your machine.

If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

Your next steps depend on whether [OS Login](../../../organization/concepts/os-login.md) access is enabled for the VM. With OS Login access [enabled](../vm-connect/enable-os-login.md), you can connect to the serial console using short-lived SSH certificates. To connect to VMs with OS Login access disabled, use SSH keys.

{% list tabs group=os_login_type %}

- Connecting with an SSH key {#ssh-key}

  1. See the description of the CLI command for connecting to a serial console:

      ```bash
      yc compute connect-to-serial-port --help
      ```
  1. Enable metadata authorization when connecting to the serial console:
     
     ```bash
     yc compute instance update <VM_name_or_ID> \
       --serial-port-settings ssh-authorization=INSTANCE_METADATA \
       --metadata enable-oslogin=false,serial-port-enable=1,ssh-keys='<username>:<public_SSH_key>'
     ```
     
     Where:
     * `<VM_name_or_ID>`: To learn how to find out the VM name or ID, see [Getting information about a VM](../vm-info/get-info.md).
     * `--metadata`: VM [metadata](../../concepts/vm-metadata.md):
     
         * `ssh-keys`: Name of the local VM user and the contents of the [public SSH key](../vm-connect/ssh.md#creating-ssh-keys) that will allow this user to connect to the VM over SSH.
     
     Result:
     
     ```yaml
     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
     ```
     
     For more information about the `yc compute instance update` command, see the [CLI reference](../../../cli/cli-ref/compute/cli-ref/instance/update.md).
     
     {% note info %}
     
     If OS Login access is [enabled](../../../organization/operations/os-login-access.md) 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 OS Login access is disabled in the organization, the default value of this field will be `INSTANCE_METADATA`.
     
     {% endnote %}
  1. Connect to the VM's serial console:

      ```bash
      yc compute connect-to-serial-port \
        --instance-name <VM_name> \
        --ssh-key <path_to_private_SSH_key> \
        --port 1
      ```

      Where:
      * `--instance-name`: VM name. 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`.
      * `--port`: Number of the [serial port](../../concepts/serial-console.md#serial-ports) used by the serial console for VM connections.

          By default, serial port `COM1` is used on Linux VMs. To use a different port, configure it manually on your VM OS side.

      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 VM instance.

      For more information about the `yc compute connect-to-serial-port` command, see the [CLI reference](../../../cli/cli-ref/compute/cli-ref/connect-to-serial-port.md).
  1. Finish using the serial console:
     
     1. Exit the local OS user profile:
     
         ```bash
         exit
         ```
     1. Close the serial console session. Do it by entering the following character sequence:
     
         ```text
         ~.
         ```

- Using a certificate via OS Login {#ssh-cert}

  1. See the description of the CLI command for connecting to a serial console:

      ```bash
      yc compute connect-to-serial-port --help
      ```
  1. Enable OS Login authorization when connecting to the serial console:
     
     ```bash
     yc compute instance update <VM_name_or_ID> \
       --serial-port-settings ssh-authorization=OS_LOGIN \
       --metadata enable-oslogin=true,serial-port-enable=1,ssh-keys='<username>:<public_SSH_key>'
     ```
     
     Where:
     * `<VM_name_or_ID>`: To learn how to find out the VM name or ID, see [Getting information about a VM](../vm-info/get-info.md).
     * `--metadata`: VM [metadata](../../concepts/vm-metadata.md):
     
         * `ssh-keys`: Name of the local VM user and the contents of the [public SSH key](../vm-connect/ssh.md#creating-ssh-keys) that will allow this user to connect to the VM over SSH if access via OS Login is disabled for this VM later.
     
     Result:
     
     ```yaml
     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
     ```
     
     For more information about the `yc compute instance update` command, see the [CLI reference](../../../cli/cli-ref/compute/cli-ref/instance/update.md).
     
     {% note info %}
     
     If OS Login access is [enabled](../../../organization/operations/os-login-access.md) 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 OS Login access is disabled in the organization, the default value of this field will be `INSTANCE_METADATA`.
     
     {% endnote %}
  1. Connect to the VM's serial console:

      ```bash
      yc compute connect-to-serial-port \
        --instance-name <VM_name> \
        --port 1
      ```

      Where:
      
      * `--instance-name`: VM name. Instead of the VM name, you can provide its ID in the `--instance-id` parameter.
      * `--port`: Number of the [serial port](../../concepts/serial-console.md#serial-ports) used by the serial console for VM connections.

          By default, serial port `COM1` is used on Linux VMs. To use a different port, configure it manually on your VM OS side.

      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 VM instance.

      For more information about the `yc compute connect-to-serial-port` command, see the [CLI reference](../../../cli/cli-ref/compute/cli-ref/connect-to-serial-port.md).
  1. Finish using the serial console:
     
     1. Exit the local OS user profile:
     
         ```bash
         exit
         ```
     1. Close the serial console session. Do it by entering the following character sequence:
     
         ```text
         ~.
         ```

{% endlist %}

{% note warning %}

When you are done using the management console, do not forget to [ban](index.md#disable) access to it.

{% endnote %}

## Troubleshooting connection issues {#troubleshooting-ssh}

* 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])?`.

#### See also {#see-also}

* [VM serial console](../../concepts/serial-console.md)
* [Managing serial console access](index.md)
* [Connecting to the serial console of a Windows VM instance](windows-sac.md)