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.
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.
Getting started
Before you enable serial console access on a VM:
-
Prepare a key pair (public and private keys) for SSH access to your VM. The serial console authenticates users via SSH keys.
-
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 thecat ~/.ssh/<public_key_name>.pub
command.
Enabling 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 in the CLI profile is used by default. You can specify a different folder through the --folder-name
or --folder-id
parameter.
-
See the description of the CLI command for creating a VM:
yc compute instance create --help
-
Select a public Linux-based image, e.g., Ubuntu.
To get a list of available images using the CLI, run this command:
yc compute image list --folder-id standard-images
Result:
+----------------------+-------------------------------------+--------------------------+----------------------+--------+ | ID | NAME | FAMILY | PRODUCT IDS | STATUS | +----------------------+-------------------------------------+--------------------------+----------------------+--------+ ... | fdvk34al8k5n******** | centos-7-1549279494 | centos-7 | dqni65lfhvv2******** | READY | | fdv7ooobjfl3******** | windows-2016-gvlk-1548913814 | windows-2016-gvlk | dqnnc72gj2is******** | READY | | fdv4f5kv5cvf******** | ubuntu-1604-lts-1549457823 | ubuntu-1604-lts | dqnnb6dc7640******** | READY | ... +----------------------+-------------------------------------+--------------------------+----------------------+--------+
Where:
-
ID
: Image ID. -
NAME
: Image name. -
FAMILY
: ID of the image family the image belongs to. -
PRODUCT IDS
: IDs of Yandex Cloud Marketplace products associated with the image. -
STATUS
: Current status of the image. It may take one of the following values:STATUS_UNSPECIFIED
: Image status is not defined.CREATING
: Image is being created.READY
: Image is ready to use.ERROR
: You cannot use the image due to an issue.DELETING
: Image is being deleted.
-
-
Create a VM in the default folder:
yc compute instance create \ --name first-instance \ --zone ru-central1-a \ --network-interface subnet-name=default-a,nat-ip-version=ipv4 \ --create-boot-disk image-folder-id=standard-images,image-family=ubuntu-1604-lts \ --metadata-from-file ssh-keys=sshkeys.txt \ --metadata serial-port-enable=1
This command will create a VM with the following parameters:
- OS: Ubuntu
- Name:
first-instance
- Availability zone:
ru-central1-a
- Serial console: Active
A user named
yc-user
with the specified public key will be automatically created in the VM OS.
Enabling 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
.
-
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 | +----------------------+-----------------+---------------+---------+----------------------+
-
Select
ID
orNAME
of the VM, e.g.,first-instance
. -
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 access
To configure serial console access, a VM must have a public IP address. You can look up the address in the management console
For the serial console to be accessible from the OS side, configure the OS accordingly.
Linux
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 authentication
Note
SSH connections using a login and password are disabled by default on public Linux images that are provided by Yandex Cloud.
If you are using a custom image, make sure SSH access with a username and password is disabled.
To disable SSH password authentication:
-
Open the SSH server configuration file (
/etc/ssh/sshd_config
by default). Only a superuser has read and write permissions for the file. -
Set
PasswordAuthentication
tono
. -
Restart the SSH server:
sudo systemctl restart ssh*
Creating 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.
-
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 | +----------------------+-----------------+---------------+---------+----------------------+
-
Select
ID
orNAME
of the VM, e.g.,first-instance
. -
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 ...
-
Connect to the VM. For more information, see Connecting to a VM.
-
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
-
Terminate the SSH session by running
exit
.
Enable the authorization method you need
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
.
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
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
.