VirtualBox* is a type 2 hypervisor from Oracle. This document explains how to create a virtual machine on the VirtualBox hypervisor with Clear Linux* OS as the guest operating system.

These instructions make use of the Clear Linux OS installer to create a brand new Clear Linux OS installation. A preinstalled disk image is also available to get started with Clear Linux OS faster. See: Run pre-configured Clear Linux* OS as a VirtualBox* Virtual Machine

Prerequisites

Before continuing make sure that you have:

  1. Enabled virtualization, such as Intel® Virtualization Technology (Intel® VT), on the host system from EFI/BIOS.
  2. Downloaded and installed VirtualBox version 6.0 or greater from the official VirtualBox website per the appropriate instructions for your platform.

Download and extract the Clear Linux OS installer ISO image

The appropriate Clear Linux OS installer image needs to be downloaded and extracted.

Note

The installer.iso is for limited use on special cases where ISO image format is required, such as VirtualBox. The preferred installer for Clear Linux OS for UEFI systems is the -installer.img.

  1. Download the installer ISO image (clear-<VERSION>-installer.iso.xz) of Clear Linux OS. On the downloads page, this is listed as Clear Linux OS for Virtual Provisioning.

    You can also use this command to download from a terminal:

    curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep installer.iso)
    
  2. Validate the integrity of the downloaded image by checking the file hash and signatures. Refer to the document on Validate signatures for detailed steps.

  3. Decompress the downloaded image. Uncompressed image size is ~ 5GB.

    • On Windows you can use 7zip to extract the file by right-clicking the file to Extract Here (in the same directory)

      7zip extract here command
    • On Linux :

      xz -d clear-<VERSION>-installer.iso.xz
      
  4. The originally downloaded compressed archive file (clear-<VERSION>-installer.iso.xz) can now be deleted.

Create a new VirtualBox virtual machine

A new VM needs to be created in VirtualBox Manager for Clear Linux OS to be installed onto.

General instructions for creating a virtual machine and details about using different settings are available on the VirtualBox manual section on Creating a VM.

  1. Launch the VirtualBox Manager from your host system.

  2. Click the New button to create a new VM.

    Create a new VM in VirtualBox
  3. A Create Virtual Machine window will appear. Select the following settings:

    • Type: Linux
    • Version: Linux 2.6 / 3.x / 4.x (64-bit)
    • Memory size: 1024 MB (this can be adjusted appropriately)
    • Hard disk: Create a virtual hard disk now
    Create a new VM in VirtualBox with a new disk
  4. Click the Create button.

  5. A Create Virtual Hard Disk window will appear. Select the following settings:

    • File size: 8.00 GB (this can be adjusted appropriately)
    • Hard disk file type: VDI (Virtual Box Disk Image)
    • Storage on physical hard disk: Dynamically allocated
    Create a new virtual hard disk in VirtualBox
  6. Click the Create button.

  7. A new virtual machine will be created and appear in the VirtualBox Manager. Click Settings to configure the Clear Linux OS VM.

    A VM selected in VirtualBox Manager
  8. A VM - Settings window will appear. Navigate to the System pane from the left-hand and select the following setting:

    • Enable I/O APIC
    • Enable EFI (special OSes only)
    Enable EFI on a VirtualBox VM settings

Note

By default, only 1 virtual CPU is allocated to the new VM. Consider increasing the number of virtual processors allocated to the virtual machine under Settings –> System –> Processor for increased performance.

Install Clear Linux OS on the VirtualBox VM

Clear Linux OS is ready to be installed.

Mount the installation ISO

At this point, the newly created VM has a blank virtual hard disk with no operating system.The Clear Linux OS installer ISO needs to be mounted as a virtual CD-ROM on the VM before powering the VM on.

  1. From the VM - Settings window, navigate to the Storage pane from the left-hand side.

  2. From the middle Storage Devices column, click the blue CD disk labeled Empty under the Controller: IDE from.

  3. From the right-hand Attributes column, click the blue CD disk next to the Optical Drive drop down menu and click Choose Virtual Optical Disk File...

    Mounting an ISO in VirtualBox VM Settings
  4. A choose a virtual optical disk file browser window will appear. Navigate to the extracted ISO file, select it, and click Open.

    Mounting an ISO in VirtualBox VM Settings
  5. Click OK to exit the VM Settings menu and return to the main VirtualBox Manager.

Install Clear Linux OS using the installer

  1. Start the VM from the VirtualBox Manager by selecting the Clear Linux OS VM and clicking Start

    Starting a VirtualBox VM
  2. A new window of the VM console will appear and boot into the Clear Linux OS installer. Follow the steps in Install Clear Linux* OS from the live desktop to install Clear Linux OS onto the VM virtual disk.

Note

Do not choose a different kernel from the installer. kernel-lts, the Long Term Support (LTS) kernel is required for VirtualBox driver compatibility.

  1. After Clear Linux OS installation is complete, the VM will reboot and return to the Clear Linux OS installer.

Note

To release the mouse cursor from the VM console window, press the right Ctrl key on the keyboard.

Unmount the installation ISO

The Clear Linux OS installer ISO needs to be unmounted to allow the VM to boot from the virtual hard disk, which Clear Linux OS has been installed to.

  1. Power off the Clear Linux OS VM.

    Powering off a VirtualBox VM
  2. Click Settings to configure the Clear Linux OS VM.

    A VM selected in VirtualBox Manager
  3. From the VM - Settings window, navigate to the Storage pane from the left-hand side.

  4. From the middle Storage Devices column, click the blue CD disk labeled clear-<VERSION>-installer.iso under the Controller: IDE from.

  5. From the right-hand Attributes column, click the blue CD disk next to the Optical Drive drop down menu and click Remove Disk from Virtual Drive

    Unmounting an ISO in VirtualBox VM Settings
  6. Click OK to exit the VM Settings menu and return to the main VirtualBox Manager.

Start the Clear Linux OS VM

The Clear Linux OS VM can now be powered on and setup.

General instructions for using a VirtualBox virtual machine are available on the VirtualBox manual section on Running a VM.

  1. Start the VM from the VirtualBox Manager by selecting the Clear Linux OS VM and clicking Start

    Starting a VirtualBox VM
  2. Clear Linux OS will boot and prompt for login.

    • Enter root for the username.
  3. You will be immediately prompted to set a new password for the root user. Reference OS Security for more information about Clear Linux OS security concepts.

    Initial login to Clear Linux OS on a VirtualBox VM

Install VirtualBox Linux Guest Additions

The VirtualBox Linux Guest Additions provide drivers for full compatibility and functionality.

Clear Linux OS provides VirtualBox guest drivers and an install script in the kernel-lts (Long Term Support) bundle by Clear Linux OS.

  1. Validate the installed kernel is kernel-lts by checking the output of the uname -r command. It should end in .lts.

    uname -r
    4.<VERSION>.lts
    

    If the running kernel is not lts: install the LTS kernel manually, update the bootloader, and check again:

    swupd bundle-add kernel-lts
    clr-boot-manager set-kernel $(basename $(realpath /usr/lib/kernel/default-lts))
    clr-boot-manager update
    reboot
    
  2. Remove any kernel bundles that are not kernel-lts or kernel-install to simplify and avoid conflicts:

    swupd bundle-list | grep kernel
    swupd bundle-remove <NON-LTS-KERNEL>
    
    Initial login to Clear Linux OS on a VirtualBox VM
  3. From the VM Console window, click Devices on the top menu bar, and select Insert Guest Additions CD image... to mount the VirtualBox driver installation to the Clear Linux OS VM.

    VirtualBox CD

Note

To release the mouse cursor from the VM console window, press the right Ctrl key on the keyboard.

  1. Clear Linux OS provides a script called install-vbox-lga to help patch and install VirtualBox drivers for Clear Linux OS. Inside Clear Linux OS VM run this command:

    install-vbox-lga
    
  2. After the script completes successfully, reboot the Clear Linux OS VM.

    reboot
    
  3. After the VM reboot, login and verify the VirtualBox drivers are loaded:

    lsmod | grep ^vbox
    

    You should see drivers loaded with names beginning with vbox: (vboxguest, vboxsf, vboxvideo).

The Clear Linux OS VM running on VirtualBox is ready to be used.

Troubleshooting

  1. Problem: Out of disk space inside of Clear Linux OS and not be able to install additional bundles.

    Solution: The Clear Linux OS images are small to minimize download time and initial disk space .

    Power off the VM and resize the virtual disk for the Clear Linux OS VM using the VirtualBox Virtual Media Manager found under the File menu. Afterwards, power the Clear Linux OS VM on and follow the instructions here to have Clear Linux OS detect the resized disk. Increase virtual disk size of a Clear Linux* OS image

  2. Problem: On a Microsoft Windows OS, VirtualBox encounters an error when trying to start a VM indicating VT-X/AMD-v hardware acceleration is not available on your system.

    VirtualBox hardware acceleration error

    Solution: First, double check the Prerequisites section to make sure Hardware accelerated virtualization extensions have been enabled in the host system’s EFI/BIOS.

    Hardware accelerated virtualization, may get disabled for VirtualBox when another hypervisor, such as Hyper-V is enabled.

    To disable Hyper-V execute this command in an Administrator: Command Prompt or Powershell, and reboot the system:

    bcdedit /set {current} hypervisorlaunchtype off
    

    To enable Hyper-V again, execute this command in an Administrator: Command Prompt or Powershell, and reboot the system:

    bcdedit /set {current} hypervisorlaunchtype Auto