Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Preparing a disk image

Written by
Updated at February 12, 2025

Note

You can only use images prepared following this guide.

You can also view out-of-the-box images in Yandex Cloud Marketplace.

You can use your own file with a Linux VM disk image. Once your image is prepared, upload it to Compute Cloud.

If you have developed software that might be helpful to others, consider listing it in Yandex Cloud Marketplace.

Configuring the OS to meet the requirements

Make sure the following requirements for boot disk images are met:

  • The virtio-net, virtio-blk, and virtio-pci drivers are installed. If you are going to attach file storages to your VM, you also need to install the virtiofs driver. For details, see this guide.
  • The ttyS0 terminal (COM1) is configured as the serial console. For details, see this guide.
  • The network interface runs correctly when starting the VM and gets the IP address via DHCP.
  • The cloud-init package is installed and configured to work with our metadata service. Run sudo yum install cloud-init to install the package for CentOS or sudo apt update && sudo apt install -y cloud-init to install it for Debian or Ubuntu.
  • For an image based on an AMI, cloud platform verification for the VM instance is disabled in the cloud-init settings. For details, see this guide.
  • The system firewall is configured to only allow the minimum ports required for your applications to run securely and the SSH port (by default, 22 TCP).
  • The SSH server starts automatically at VM startup.
  • The services running your application are resilient to VM reboots.
  • The boot disk uses MBR partitioning.
  • The disk is mounted by its UUID rather than by name.
  • The file system is not encrypted.

Installing virtio drivers

To successfully upload your image, make sure to install the virtio-blk, virtio-net, and virtio-pci drivers. To use Compute Cloud file storages, install virtiofs.

Most modern distributions include the virtio drivers by default. They can be compiled as separate .ko files or built into the kernel itself.

Follow the steps below to check if the drivers are installed in your OS. If not, add them.

  1. Check if the drivers are built into the kernel:

    How to check it

    Run this command:

    grep -E -i "VIRTIO_(BLK|NET|PCI|FS)" /boot/config-$(uname -r)

    If you see no lines starting with CONFIG_VIRTIO_BLK=, CONFIG_VIRTIO_NET=, CONFIG_VIRTIO_PCI=, and CONFIG_VIRTIO_FS= on your screen, recompile the Linux kernel with the virtio drivers. Otherwise, proceed to the next steps.

  2. If you get the CONFIG_VIRTIO_BLK=y, CONFIG_VIRTIO_NET=y, CONFIG_VIRTIO_PCI=y, and CONFIG_VIRTIO_FS=y lines in Step 1, make sure the drivers are included in the kernel:

    How to check if drivers are included in a kernel

    Run this command:

    grep -E "virtio(_blk|_net|_pci|fs)" /lib/modules/"$(uname -r)"/modules.builtin
    • If you get the lines with the virtio_net.ko, virtio_blk.ko, virtio_pci.ko and virtiofs.ko file names, the drivers are included in the kernel and you do not need to install them.
    • If you see no such lines on your screen, recompile the Linux kernel with the virtio drivers.

  3. If you get the CONFIG_VIRTIO_BLK=m, CONFIG_VIRTIO_NET=m, CONFIG_VIRTIO_PCI=m, and CONFIG_VIRTIO_FS=m lines in Step 1, check that the drivers are installed as kernel modules:

    How to check kernel modules

    Run this command:

    sudo lsinitrd /boot/initramfs-$(uname -r).img | grep -E "virtio(_blk|_net|_pci|fs)"

    • If you get the lines with the virtio_net.ko.xz, virtio_blk.ko.xz, virtio_pci.ko.xz, and virtiofs.ko.xz file names, the drivers are installed as kernel modules.

    • If you see no such lines on your screen, create a backup of the initramfs file and install the drivers:

      sudo cp /boot/initramfs-$(uname -r).img /boot/initramfs-$(uname -r).img.bak
sudo mkinitrd -f --with=virtio_blk --with=virtio_net --with=virtio_pci --with=virtiofs /boot/initramfs-$(uname -r).img $(uname -r)

      If you get an error saying Command 'mkinitrd' not found, use dracut to install the drivers:

      sudo dracut -f --add-drivers "virtio_blk virtio_net virtio_pci virtiofs" /boot/initramfs-$(uname -r).img $(uname -r)

      Then, reboot your system and check if the drivers are now included in the initramfs file and loaded:

      sudo lsinitrd /boot/initramfs-$(uname -r).img | grep -E "virtio(_blk|_net|_pci|fs)"
find /lib/modules/"$(uname -r)"/ -name "virtio*" | grep -E "(blk|net|pci|fs)"

      Each command should output lines with the virtio_net.ko.xz, virtio_blk.ko.xz, virtio_pci.ko.xz, and virtiofs.ko.xz file names.

    Run this command:

    lsinitramfs /boot/initrd.img-$(uname -r) | grep -E "virtio(_blk|_net|_pci|fs)"

    • If you get the lines with the virtio_net.ko, virtio_blk.ko, virtio_pci.ko, and virtiofs.ko file names, the drivers are installed as kernel modules.

    • If you see no such lines on your screen, install the drivers:

      echo -e "virtio_blk\nvirtio_net\nvirtio_pci\nvirtiofs" | sudo tee -a /etc/initramfs-tools/modules
sudo update-initramfs -u

      Then, reboot your system and check if the drivers are now included in the initrd file and loaded:

      lsinitramfs /boot/initrd.img-$(uname -r) | grep -E "virtio(_blk|_net|_pci|fs)"
find /lib/modules/"$(uname -r)"/ -name "virtio*" | grep -E "(blk|net|pci|fs)"

      Each command should output lines with the virtio_net.ko, virtio_blk.ko, virtio_pci.ko, and virtiofs.ko file names.

Configuring the serial console

A serial console enables accessing a VM regardless of the network or OS state. Use the serial console to troubleshoot your VM or when you have SSH access issues. For more information, see Getting started with a serial console.

To enable serial console access to your VM, configure the image to use ttyS0 (COM1) as the system console:

  1. In the /etc/default/grub file with GRUB settings, add console=ttyS0 to the GRUB_CMDLINE_LINUX parameter value. The line with this parameter should look like this:

    GRUB_CMDLINE_LINUX="foo=bar baz console=ttyS0"

  2. Make sure the /etc/securetty file with a list of terminals the root user can use to log in to the OS contains the ttyS0 line. If there is no such file, create one.

    Note

    In some operating systems, /etc/securetty is not used and the root user can access all terminals by default. To configure access using this file, add a specification for the pam_securetty.so module to the /etc/pam.d/login file. For more information, see man pam_securetty and man pam.d.

  3. Run the following commands:

    sudo stty -F /dev/ttyS0 9600 # Sets the recommended baud rate for the `ttyS0` terminal to 9600.
sudo grub2-mkconfig -o /boot/grub2/grub.cfg # Generates a GRUB configuration file.
sudo systemctl start getty@ttyS0 # Starts `getty` on `ttyS0`.
sudo systemctl enable getty@ttyS0 # Tells the system to start `getty` every time it boots up.

    sudo stty -F /dev/ttyS0 9600 # Sets the recommended baud rate for the `ttyS0` terminal to 9600.
sudo update-grub # Generates a GRUB configuration file.
sudo systemctl start getty@ttyS0 # Starts `getty` on `ttyS0`.
sudo systemctl enable getty@ttyS0 # Tells the system to start `getty` every time it boots up.

  4. Reboot the OS.

After creating a VM from your image, you need to additionally configure it for using the serial console.

Disabling cloud platform verification when creating an image in Amazon EC2

When using an AMI to create an image in Amazon EC2, cloud-init verifies that the VM is running within the Amazon EC2 environment. VMs launched in Yandex Compute Cloud will fail the verification and may run incorrectly.

To avoid this, disable metadata verification on your VMs: in the /etc/cloud/cloud.cfg.d directory, create a configuration file, e.g., 99-ec2-datasource.cfg, and add the following code to it:

#cloud-config
datasource:
  Ec2:
    strict_id: false

Installing drivers to enable GPU compatibility

If you need to use a GPU with your VM, make sure to install NVIDIA drivers while preparing the image.

Creating an image file

Supported formats: Qcow2, VMDK, RAW, and VHD.

We recommend using the Qcow2 format with an optimized cluster size for faster import. To convert your image from other formats, use qemu-img:

qemu-img convert -p -O qcow2 -o cluster_size=2M <your_image_file_name> <new_image_file_name>

Note

Do not use compression or archiving utilities when preparing the image file. To make creating VMs faster, optimize the image.

Previous
Removing a disk from a placement group
Next
Uploading a custom image