Clear Linux* OS on KVM

This page explains how to run Clear Linux* OS in a virtualized environment using KVM.

Install QEMU-KVM

  1. Enable the Intel® Virtualization Technology (Intel® VT) and the Intel® Virtualization Technology for Directed I/O (Intel® VT-d) in the host machine’s BIOS.

  2. Log in and open a terminal emulator.

  3. Install QEMU*-KVM on the host machine. Below are some examples using different distros:

    Host OS Installation command
    Clear Linux OS sudo swupd bundle-add kvm-host
    Ubuntu* and Mint* sudo apt-get install qemu-kvm
    Fedora dnf install qemu-kvm

Download and launch the virtual machine image

  1. Download the latest pre-built Clear Linux OS KVM image file from the image directory. Look for clear-<version>-kvm.img.xz. You can also use this command:

    curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep '[0-9]'-kvm'\.')
    
  2. Uncompress the downloaded image:

    unxz -v clear-<version>-kvm.img.xz
    
  3. Download the 3 OVMF files (OVMF.fd, OVMF_CODE.fd, OVMF_VARS.fd) that provides UEFI support for virtual machines.

    curl -O https://cdn.download.clearlinux.org/image/OVMF.fd
    curl -O https://cdn.download.clearlinux.org/image/OVMF_CODE.fd
    curl -O https://cdn.download.clearlinux.org/image/OVMF_VARS.fd
    

    Note

    The default OVMF files from Clear Linux OS may not work for some non-Clear Linux OS distro version(s). You may get an ASSERT in the debug.log file when starting the VM. If you encounter this, use the distro-specific OVMF files instead.

  4. Download the start_qemu.sh script from the image directory. This script will launch the Clear Linux OS VM and provide console interaction within the same terminal emulator window.

    curl -O https://cdn.download.clearlinux.org/image/start_qemu.sh
    
  5. Make the script executable:

    chmod +x start_qemu.sh
    
  6. Start the Clear Linux OS KVM virtual machine:

    sudo ./start_qemu.sh clear-<version>-kvm.img
    
  7. Log in as root user and set a new password.

Optional: Enable SSH access

To interact with the Clear Linux OS VM remotely through SSH instead of the console it was launched from, follow these steps.

  1. Enable and configure SSH in the Clear Linux OS VM to allow root login as described in Enable and configure SSH service.

  2. SSH into the Clear Linux OS VM using the port 10022. This port number is set in start_qemu.sh and passed through to the SSH service running on port 22

    ssh -p 10022 root@<ip-addr-of-kvm-host>
    

Optional: Install a graphical user interface (GUI)

To add GDM to the Clear Linux OS VM, follow these steps:

  1. Shutdown the active Clear Linux OS VM.

    poweroff
    
  2. Install the Spice viewer on the localhost or remote system. Below are some examples using different distros:

    Host OS Installation command
    Clear Linux OS sudo swupd bundle-add virt-viewer
    Ubuntu* and Mint* sudo apt-get install virt-viewer
    Fedora dnf install virt-viewer
  3. Modify the start_qemu.sh script to increase memory (-m), add graphics driver (-vga), and add Spice (-spice, -usb, and -device) support.

    qemu-system-x86_64 \
        -enable-kvm \
        ${UEFI_BIOS} \
        -smp sockets=1,cpus=4,cores=2 -cpu host \
        -m 4096 \
        -vga qxl \
        -nographic \
        -spice port=5924,disable-ticketing \
        -usb \
        -device usb-tablet,bus=usb-bus.0 \
        -drive file="$IMAGE",if=virtio,aio=threads,format=raw \
        -netdev user,id=mynet0,hostfwd=tcp::${VMN}0022-:22,hostfwd=tcp::${VMN}2375-:2375 \
        -device virtio-net-pci,netdev=mynet0 \
        -debugcon file:debug.log -global isa-debugcon.iobase=0x402 $@
    
  4. Due to changes in the start_qemu.sh script from the previous step, having previously used OVMF files will result in the VM not booting properly and you returning to the UEFI shell. The easiest way to avoid this is to delete the 3 OVMF files and reobtain originals before relaunching the VM:

    rm -v OVMF*.fd
    curl -O https://cdn.download.clearlinux.org/image/OVMF.fd
    curl -O https://cdn.download.clearlinux.org/image/OVMF_CODE.fd
    curl -O https://cdn.download.clearlinux.org/image/OVMF_VARS.fd
    
  5. Increase the size of the VM by 10GB to accommodate the GDM installation:

    qemu-img resize -f raw clear-<version>-kvm.img +10G
    
  6. Relaunch the Clear Linux OS VM:

    sudo ./start_qemu.sh clear-<version>-kvm.img
    
  7. Determine the IP address of the host on which you will launch the VM. Substitute <ip-addr-of-kvm-host> in the next step with this information.

    ip a
    
  8. From the local host or remote system, open a new terminal emulator window and connect into the Clear Linux OS VM using the Spice viewer:

    remote-viewer spice://<ip-address-of-kvm-host>:5924
    
  9. Log in as root user into the Clear Linux OS VM.

  10. Follow these steps from Increase virtual disk size of an image to resize the partition of the virtual disk of the VM.

  11. Add GDM to the Clear Linux OS VM:

    swupd bundle-add desktop-autostart
    
  12. Reboot the Clear Linux OS VM to start GDM:

    reboot
    
  13. Go through the GDM out-of-box experience (OOBE).

  14. The default aspect ratio of the GDM GUI for the Clear Linux OS VM is 4:3. To change it, use GDM’s Devices > Displays setting tool (located at the top-right corner).