Getting started with a serial console

A serial console enables accessing a VM regardless of the network or OS state. For example, you can use the console to troubleshoot your VM or when you have SSH access issues.

To use the serial console, you need the compute.admin or editor role.

By default, serial console access is disabled.

Getting startedGetting started

Before you enable serial console access on a VM:

1. Prepare a key pair (public and private keys) for SSH access to your VM. The serial console authenticates users via SSH keys.

2. Create a text file, e.g., sshkeys.txt, and specify the following:

   <username>:<public_SSH_key_for_user>
   

   Example of a text file for yc-user:

   yc-user:ssh-ed25519 AAAAB3Nza......OjbSMRX yc-user@example.com
   

   By default, user SSH keys are stored in the user's ~/.ssh folder. You can get a public key by running the cat ~/.ssh/<public_key_name>.pub command.

Enabling the console when creating a VM from a public imageEnabling the console when creating a VM from a public image

To enable serial console access when creating a VM, set the serial-port-enable parameter in the metadata to 1.

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

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

Enabling the console when updating a VMEnabling the console when updating a VM

To enable serial console access when updating a VM, set the serial-port-enable parameter in the metadata to 1.

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

2. Select ID or NAME of the VM, e.g., first-instance.

3. Set serial-port-enable=1 in the VM metadata:

   yc compute instance add-metadata \
     --name first-instance \
     --metadata-from-file ssh-keys=sshkeys.txt \
     --metadata serial-port-enable=1
   

   The command will start activating the serial console on the VM named first-instance.

Configuring a VM to enable serial port accessConfiguring a VM to enable serial port access

To configure serial console access, a VM must have a public IP address. You can look up the address in the management console in the Compute Cloud section, the Virtual machines page. If you created a VM without a public IP address, you can assign one. Once the configuration is complete, you can unassign the address as you will not need it for connecting via the serial console.

For the serial console to be accessible from the OS side, configure the OS accordingly.

LinuxLinux

To connect to a Linux serial console, make sure SSH password authentication is disabled and set a password for the OS user, if required.

Disabling SSH password authenticationDisabling SSH password authentication

If you are using a custom image, make sure SSH access with a username and password is disabled.

To disable SSH password authentication:

1. Open the SSH server configuration file (/etc/ssh/sshd_config by default). Only a superuser has read and write permissions for the file.

2. Set PasswordAuthentication to no.

3. Restart the SSH server:

   sudo systemctl restart ssh*
   

Creating a password for a Linux userCreating a password for a Linux user

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

To create a local password, use the CLI.

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

2. Select ID or NAME of the VM, e.g., first-instance.

3. Get the public IP address of your VM:

   yc compute instance get first-instance
   

   In the command output, find the VM address in the one_to_one_nat section:

   ...
   one_to_one_nat:
     address: <public_IP_address>
     ip_version: IPV4
   ...
   

4. Connect to the VM. For more information, see Connecting to a VM.

5. Create a local password. In Linux, you can set a password using the passwd command:

   sudo passwd <username>
   

   Example for yc-user:

   sudo passwd yc-user
   

6. Terminate the SSH session by running exit.

Enable the authorization method you needEnable the authorization method you need

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

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

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

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