virtualbox-cl-installer: Revise figures to match VirtualBox 6.0.8 and new live-server installer. (#502)

* Revises instruciton to match VirtualBox 6.0.8 and new live-desktop installer; -live.img deprecated.
- Incorporates LGA and Troubleshooting from virtualbox.rst
- Replaces virtualbox.rst.
- Refer also to GH-493.
- Closes #495 
- Closes #502
- Closes #498 

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Resizes figures; reassigns Troubleshooting section from virtualbox this doc.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Adds Troubleshooting section.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Removes ununsed figures, previously from virtualbox.rst.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Re-adds prev removed CAUTION in substitutions.txt

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Revises guide per reviewer feedback.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Adds note on file size if using live-desktop install--below Fig. 6.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Incorporates reviewer feedback.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Revert to use case of live-server per reviewer feedback.
- Revise all Figures
- Revise all steps

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Respond to reviewers' feedback.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Revise figures; add step for VBoxSVGA; move add desktop-autostart to post-install.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Respond to reviewer feedback re clarifying post-installation steps.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

Simplify steps; define context for steps; correct values in code-block.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

* Replaces step with note re kernel update in LGA section.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>
This commit is contained in:
michael vincerra
2019-05-31 11:10:29 -07:00
committed by GitHub
parent 3d6e624aa5
commit 52e8e1ff01
36 changed files with 295 additions and 527 deletions
Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 23 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 9.8 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 23 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 80 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 84 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 77 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 29 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 47 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 83 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 61 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 86 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 56 KiB

@@ -29,12 +29,11 @@ appropriate set of step-by-step instructions to proceed.
:maxdepth: 1
kvm
virtualbox
virtualbox-cl-installer
vmware-esxi-install-cl
vmware-esxi-preconfigured-cl-image
vmw-player
vmw-player-preconf
hyper-v
virtualbox-cl-installer
../../guides/maintenance/increase-virtual-disk-size.rst
@@ -1,258 +1,394 @@
.. _virtualbox-cl-installer:
Install |CL-ATTR| as a VirtualBox\* Virtual Machine
###################################################
VirtualBox\* is a type 2 hypervisor from Oracle. This document explains how
to create a virtual machine on the `VirtualBox hypervisor`_ with |CL-ATTR|
as the guest operating system.
These instructions make use of the |CL| installer to create a brand new |CL|
installation. A preinstalled disk image is also available to get started
with |CL| faster. See: :ref:`virtualbox`
Install a |CL-ATTR| VM in VirtualBox\*
######################################
Oracle\* VirtualBox\* is a type 2 hypervisor. This document explains how to
create a virtual machine on the `VirtualBox hypervisor`_ with |CL-ATTR| as
the guest operating system. These instructions support use of the |CL|
live-server installer to create |CL| virtual machine (VM).
.. contents:: :local:
:depth: 2
:depth: 1
Prerequisites
*************
.. include:: virtualbox.rst
:start-after: vbox-prereqs-begin:
:end-before: vbox-prereqs-end:
Before continuing, assure you have:
#. Enabled virtualization, such as Intel®
`Virtualization Technology`_ (Intel® VT), on the host system from
EFI/BIOS.
#. Downloaded and installed |VB| **version 6.0 or greater** from
the `official VirtualBox website`_ per the `appropriate instructions`_
for your platform.
Download and extract the |CL| installer ISO image
*************************************************
Download and extract the |CL| installer ISO
*******************************************
The appropriate |CL| installer image needs to be downloaded and extracted.
#. Download the :file:`clear-<VERSION>-live-server.iso.xz` of
|CL| on the `downloads page`_.
.. note::
The :file:`installer.iso` is for limited use on special cases where ISO
image format is required, such as |VB|. The preferred installer for |CL|
for UEFI systems is the :file:`-installer.img`.
#. Validate the integrity of the downloaded image by checking the file hash
and signatures. Refer :ref:`validate-signatures` for detailed steps.
#. Download the **installer ISO** image (:file:`clear-<VERSION>-installer.iso.xz`) of
|CL|. 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:
#. Decompress the downloaded image.
.. code-block:: bash
curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep installer.iso)
#. Validate the integrity of the downloaded image by checking the file hash
and signatures. Refer to the document on :ref:`validate-signatures` for
detailed steps.
#. Decompress the downloaded image. Uncompressed image size is ~ **5GB**.
- On Windows you can use `7zip`_ to extract the file by right-clicking the
- On Windows you can use `7zip`_ to extract the file by right-clicking the
file to *Extract Here* (in the same directory)
.. image:: ./figures/vbox/vbox-extract-cl-ISO.png
:alt: 7zip extract here command
.. figure:: figures/vbox/virtualbox-cl-installer-01.png
:scale: 100%
:alt: 7zip extract here command
Figure 1: 7zip extract here command
- On Linux :
.. code-block:: bash
xz -d clear-<VERSION>-installer.iso.xz
#. The originally downloaded compressed archive file
(:file:`clear-<VERSION>-installer.iso.xz`) can now be deleted.
xz -d clear-<VERSION>-live-server.iso.xz
#. Delete the originally downloaded compressed file.
Create a new |VB| virtual machine
*********************************
A new :abbr:`VM (Virtual Machine)` needs to be created in |VBM| for |CL| to be installed onto.
General instructions for creating a virtual machine and details about using
different settings are available on the
A new :abbr:`VM (Virtual Machine)` needs to be created in |VBM| where |CL|
will be installed. General instructions for creating a virtual machine and
details about using different settings are available on the
`VirtualBox manual section on Creating a VM`_.
#. Launch the |VBM| from your host system.
#. Click the *New* button to create a new VM.
#. Click the *New* button to create a new VM.
#. Choose :guilabel:`Expert mode`.
.. image:: ./figures/vbox/vbox-new-vm.png
:alt: Create a new VM in VirtualBox
#. In :guilabel:`Create Virtual Machine`, enter the following settings:
- **Name**: Choose name (e.g. ClearLinuxOS-VM).
- **Type**: Linux
- **Version**: **Linux 2.6 / 3.x / 4.x (64-bit)**
- **Hard disk**: `Create a virtual hard disk now`
- **Memory size default**: 2048 MB (Adjust appropriately.)
#. 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**
.. note::
Later, if you want to change the amount of RAM allocated, power down your VM. Return to :file:`Settings > System` and change
:guilabel:`Base Memory` to the desired size.
.. image:: ./figures/vbox/vbox-create-vm-new-disk.png
:alt: Create a new VM in VirtualBox with a new disk
.. figure:: figures/vbox/virtualbox-cl-installer-02.png
:scale: 100%
:alt: Create Virtual Machine
Figure 2: Create Virtual Machine
#. Click the *Create* button.
#. Select :guilabel:`Create`.
#. A *Create Virtual Hard Disk* window will appear.
Select the following settings:
#. In :guilabel:`Create Virtual Hard Disk`, select:
- File size: **8.00 GB** (this can be adjusted appropriately)
- Hard disk file type: **VDI (Virtual Box Disk Image)**
- **File location**
- **File size**: **32.00 GB**. Adjust size to your needs.
- **Hard disk file type**: `VDI (VirtualBox Disk Image)`
- **Storage on physical hard disk**:`Dynamically allocated`
- Storage on physical hard disk: **Dynamically allocated**
.. figure:: figures/vbox/virtualbox-cl-installer-03.png
:scale: 100%
:alt: Create Virtual Hard Disk
.. image:: ./figures/vbox/vbox-create-disk.png
:alt: Create a new virtual hard disk in VirtualBox
Figure 3: Create Virtual Hard Disk
#. Click the *Create* button.
#. Click *Create*.
#. A new virtual machine will be created and appear in the |VBM|. Click
*Settings* to configure the |CL| VM.
A new virtual machine will be created and appear in the |VBM|.
.. image:: ./figures/vbox/vbox-vm-created.png
:alt: A VM selected in VirtualBox Manager
#. Click *Settings* to configure the |CL| VM.
#. A *VM - Settings* window will appear. Navigate to the *System* pane from
the left-hand and select the following setting:
#. In the left-hand menu, navigate to the :guilabel:`System` menu.
#. In the :guilabel:`Motherboard` tab, select the `Chipset` pulldown menu,
and then select :guilabel:`ICH9`. See Figure 4.
.. note::
You can select which chipset will be presented to the virtual machine.
Consult the `VM VirtualBox User Manual`_ for more details.
#. In :guilabel:`Enabled Features`, check these boxes:
- **Enable I/O APIC**
- **Enable EFI (special OSes only)**
.. image:: ./figures/vbox/vbox-vm-settings-EFI.png
:alt: Enable EFI on a VirtualBox VM settings
.. figure:: figures/vbox/virtualbox-cl-installer-04.png
:scale: 100%
:alt: Settings > System
.. 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.
Figure 4: Settings > System
.. 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.
#. Select :guilabel:`OK`.
Install |CL| on the |VB| VM
***************************
|CL| 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 |CL| installer ISO needs to be mounted as a virtual
CD-ROM on the VM before powering the VM on.
#. From the *VM - Settings* window, navigate to the *Storage* pane from the
left-hand side.
The |CL| installer ISO needs to be mounted as a virtual CD-ROM on the VM
before powering the VM on.
#. From the middle *Storage Devices* column, click the blue CD disk labeled
*Empty* under the *Controller: IDE* from.
#. From the *ClearLinux-OS* :guilabel:`Settings` at left, select
:guilabel:`Storage`.
#. From the right-hand *Attributes* column, click the blue CD disk next to
the *Optical Drive* drop down menu and click *Choose Virtual Optical
#. From :guilabel:`Storage Devices`, middle column, click the blue
disk labeled *Empty*.
#. From the :guilabel:`Attributes` menu, click the blue CD disk next to
the *Optical Drive* drop down menu and click *Choose Virtual Optical
Disk File...*
.. image:: ./figures/vbox/vbox-vm-settings-mount-ISO.png
:alt: Mounting an ISO in VirtualBox VM Settings
.. figure:: figures/vbox/virtualbox-cl-installer-05.png
:scale: 100%
:alt: Choose Virtual Optical Disk Drive
#. A *choose a virtual optical disk file* browser window will appear.
Navigate to the extracted ISO file, select it, and click *Open*.
Figure 5: Choose Virtual Optical Disk Drive
.. image:: ./figures/vbox/vbox-vm-settings-browse-ISO.png
:alt: Mounting an ISO in VirtualBox VM Settings
#. Where there appears :guilabel:`Please choose a virtual optical disk file`,
select the ISO file and click *Open*.
#. Click *OK* to exit the *VM Settings* menu and return to the main
|VBM|.
.. figure:: figures/vbox/virtualbox-cl-installer-06.png
:scale: 100%
:alt: Mounting an ISO
Figure 6: Mounting an ISO
#. Select :guilabel:`OK` to exit and return to the main |VBM|.
Install |CL| using the installer
================================
Install |CL| with live-server installer
=======================================
#. Start the VM from the |VBM| by selecting the |CL| VM and
clicking *Start*
#. In the |VBM|, select virtual machine you created and click *Start*.
.. image:: ./figures/vbox/vbox-start-vm.png
:alt: Starting a VirtualBox VM
.. figure:: figures/vbox/virtualbox-cl-installer-07.png
:scale: 100%
:alt: Start the installer
#. A new window of the VM console will appear and boot into the |CL|
installer. Follow the steps in :ref:`bare-metal-install-desktop` to
install |CL| onto the VM virtual disk.
Figure 7: Start the installer
.. note::
Do not choose a different kernel from the installer. **kernel-lts**, the
Long Term Support (LTS) kernel is required for |VB| driver compatibility.
.. note::
To release the mouse cursor from the VM console window, press the right
:kbd:`Ctrl` key on the keyboard.
#. After |CL| installation is complete, the VM will reboot and return to the
|CL| installer.
#. When :guilabel:`Clear Linux Installer` in boot manager appears,
select :kbd:`Enter`. Do not install the bundle `desktop-autostart`.
.. note::
To release the mouse cursor from the VM console window, press the right Ctrl key on the keyboard.
#. Follow the steps in :ref:`bare-metal-install-server` to
install |CL| onto the VM virtual disk. Note:
#. In :guilabel:`Configure Installation Media`, navigate top
VBOX HARDDISK, and then select :guilabel:`Confirm`.
Unmount the installation ISO
============================
#. In :guilabel:`Advanced options` > :guilabel:`Manage User`, create an
administrative user.
#. Do not install the bundle `desktop-autostart`.
#. When |CL| installation is complete, select :guilabel:`Exit`.
#. At the prompt, enter:
.. code-block:: bash
shutdown now
Unmount the ISO
===============
The |CL| installer ISO needs to be unmounted to allow the VM to boot from the
virtual hard disk, which |CL| has been installed to.
virtual hard disk.
#. Power off the |CL| VM.
.. image:: ./figures/vbox/vbox-shutdown-vm.png
:alt: Powering off a VirtualBox VM
#. Return to the |VBM|.
#. Click *Settings* to configure the |CL| VM.
.. image:: ./figures/vbox/vbox-vm-created.png
:alt: A VM selected in VirtualBox Manager
#. From the *VM - Settings* window, navigate to the *Storage* pane from the
#. From the *VM - Settings* window, navigate to the *Storage* pane from the
left-hand side.
#. From the middle *Storage Devices* column, click the blue CD disk labeled
*clear-<VERSION>-installer.iso* under the *Controller: IDE* from.
#. From the middle *Storage Devices* column, click the blue CD disk labeled
*clear-<VERSION>-live-server.iso* under the *Controller: IDE* from.
#. 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*
#. From the *Attributes* column at right, in *Optical Drive*, select the
blue CD icon beside and click *Remove Disk from Virtual Drive*.
.. image:: ./figures/vbox/vbox-vm-settings-unmount-ISO.png
:alt: Unmounting an ISO in VirtualBox VM Settings
.. figure:: figures/vbox/virtualbox-cl-installer-08.png
:scale: 100%
:alt: Remove Disk from Virtual Drive
#. Click *OK* to exit the *VM Settings* menu and return to the main
Figure 8: Remove Disk from Virtual Drive
#. Click *OK* to exit the *VM Settings* menu and return to the main
|VBM|.
Install |VB| Linux Guest Additions
==================================
|CL| provides Linux Guest Additions drivers for full compatibility using an
install script in the **kernel-lts** (Long Term Support) bundle by |CL|.
#. From the |VBM| select the |CL| VM, and select :guilabel:`Start`.
.. include:: virtualbox.rst
:start-after: vbox-start-vm-and-lga-begin:
:end-before: vbox-start-vm-and-lga-end:
#. In the VM Console, log in as the administrative user previously created.
.. note::
A message may appear: "A kernel update is available: you may wish
to reboot the system."
To update the kernel, enter:
.. code-block:: bash
sudo reboot
.. include:: virtualbox.rst
:start-after: vbox-troubleshooting-begin:
:end-before: vbox-troubleshooting-end
At initial login, enter the administrative user's password and continue.
#. Validate the installed kernel is **kernel-lts** by checking the output
of the :command:`uname -r` command. It should end in **.lts** or **.lts2018**.
.. code-block:: bash
uname -r
<VERSION>.lts
.. |VB| replace:: VirtualBox
.. |VBM| replace:: VirtualBox Manager
If the running kernel is not **lts**: install the LTS kernel manually,
update the bootloader, and check again:
.. code-block:: bash
sudo swupd bundle-add kernel-lts
clr-boot-manager set-kernel $(basename $(realpath /usr/lib/kernel/default-lts))
clr-boot-manager update
reboot
#. Remove any kernel bundles that do not end in *-lts* or *kernel-install*
to simplify and avoid conflicts:
.. code-block:: bash
sudo swupd bundle-list | grep kernel
sudo swupd bundle-remove <NON-LTS-KERNEL>
#. In the VM Console top menu, click *Devices*, and select
*Insert Guest Additions CD image...* to mount the |VB| driver installation to the |CL| VM.
.. figure:: figures/vbox/virtualbox-cl-installer-09.png
:scale: 100%
:alt: Insert Guest Additions CD image
Figure 9: Insert Guest Additions CD image
#. If a dialogue appears, "VBx_GAs_6.0.8... Would you like to run it?",
select :guilabel:`Cancel`.
Instead, we provide a script to patch and install |VB| drivers on |CL|.
#. Open a Terminal and enter the script:
.. code-block:: bash
sudo install-vbox-lga
.. note::
Successful installation shows: "Guest Additions installation complete".
If drivers are already installed, don't re-install them.
#. Shut down the system. Select :guilabel:`Machine>ACPI Shutdown`.
.. figure:: figures/vbox/virtualbox-cl-installer-10.png
:scale: 100%
:alt: Powering off a VirtualBox VM
Figure 10: Powering off a VirtualBox VM
#. Select :guilabel:`Settings`, :guilabel:`Display`.
#. In :guilabel:`Graphics Controller`, select :guilabel:`VBoxSVGA`
to adjust screen size dynamically.
.. figure:: figures/vbox/virtualbox-cl-installer-11.png
:scale: 100%
:alt: Remove Disk from Virtual Drive
Figure 11: VirtualBox hardware acceleration error
#. In the |VBM|, select :guilabel:`Start`.
#. In the VM console, login and verify the |VB| drivers are loaded:
.. code-block:: bash
lsmod | grep ^vbox
You should see drivers loaded with names beginning with **vbox**:
(e.g., vboxvideo, vboxguest).
#. Add `desktop-autostart` for a full desktop experience.
.. code-block:: bash
sudo swupd bundle-add desktop-autostart
#. Reboot the VM and log in with the administrative user.
.. code-block:: bash
sudo reboot
The |CL| VM running on |VB| is ready to develop and explore.
Troubleshooting
***************
#. **Problem:** On a Microsoft\* Windows\* OS, |VB| encounters an error when
trying to start a VM indicating *VT-X/AMD-v hardware acceleration is not
available on your system.*
.. figure:: figures/vbox/virtualbox-cl-installer-12.png
:scale: 100%
:alt: Remove Disk from Virtual Drive
Figure 12: 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 |VB| 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:
.. code-block:: bash
bcdedit /set {current} hypervisorlaunchtype off
To enable Hyper-V again, execute this command in an
**Administrator: Command Prompt or Powershell**, and reboot the system:
.. code-block:: bash
bcdedit /set {current} hypervisorlaunchtype Auto
.. _appropriate instructions: https://www.virtualbox.org/manual/ch02.html
@@ -264,12 +400,8 @@ virtual hard disk, which |CL| has been installed to.
.. _`VirtualBox manual section on Creating a VM`: https://www.virtualbox.org/manual/UserManual.html#gui-createvm
.. _`VirtualBox manual section on Running a VM`: https://www.virtualbox.org/manual/ch01.html#intro-starting-vm-first-time
.. _`Virtual Media Manager`: https://www.virtualbox.org/manual/ch05.html#vdis
.. _7zip: http://www.7-zip.org/
.. _Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html
.. _`VirtualBox manual section on VBoxManage`: https://www.virtualbox.org/manual/ch08.html#vboxmanage-convertfromraw
.. _VM VirtualBox User Manual: https://docs.oracle.com/cd/E97728_01/E97727/html/settings-system.html
@@ -1,368 +0,0 @@
.. _virtualbox:
Run pre-configured |CL-ATTR| as a VirtualBox\* Virtual Machine
##############################################################
VirtualBox\* is a type 2 hypervisor from Oracle. This document explains how
to create a virtual machine on the `VirtualBox hypervisor`_ with |CL-ATTR|
as the guest operating system.
These instructions make use of a preinstalled |CL| disk image to setup a |CL|
virtual machine without manual installation. |CL| can also be installed from
scratch on a |VB| using the |CL| installed.
See: :ref:`virtualbox-cl-installer`
.. contents:: :local:
:depth: 2
.. _vbox-prereqs-begin:
Prerequisites
*************
Before continuing make sure that you have:
#. Enabled virtualization, such as Intel®
`Virtualization Technology`_ (Intel® VT), on the host system from
EFI/BIOS.
#. Downloaded and installed |VB| **version 6.0 or greater** from
the `official VirtualBox website`_ per the `appropriate instructions`_
for your platform.
.. _vbox-prereqs-end:
Download and extract |CL|
*************************
The |CL| live image needs to be downloaded and extracted. The live image will
be used to created a |VB| virtual disk image that can be used with a
:abbr:`VM (Virtual Machine)`.
#. Download the **live image** (:file:`clear-<VERSION-live.img.xz`) of
|CL|. On the `downloads page`_, this is listed as
**Clear Linux OS live boot image**.
You can also use this command to download from a terminal:
.. code-block:: bash
curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep live.img)
#. Validate the integrity of the downloaded image by checking the file hash
and signatures. Refer to the document on :ref:`validate-signatures` for
detailed steps.
#. Decompress the downloaded image. Uncompressed image size is ~ **5GB**.
- On Windows you can use `7zip`_ to extract the file by right-clicking the
file and selecting *Extract Here* (in the same directory)
.. image:: ./figures/vbox/vbox-extract-cl-IMG.png
:alt: 7zip extract here command
- On Linux :
.. code-block:: bash
xz -d clear-<VERSION>-live.img.xz
#. There originally downloaded compressed archive file
(:file:`clear-<VERSION>-live.img.xz`) can now be deleted.
Convert |CL| live image to a |VB| Disk Image
********************************************
The |CL| live image is in a RAW disk image. The live image needs to be
converted to a :abbr:`VDI (VirtualBox Disk Image)` format which |VB|
can utilize.
#. Launch a terminal and navigate to the directory containing the
extracted live image.
#. Convert RAW live image to a :abbr:`VDI (VirtualBox Disk Image)`
format using the command-line VirtualBox Disk Utility.
.. code-block:: bash
VBoxManage convertfromraw clear-<VERSION>-live.img clear-VM.vdi --format VDI
.. note::
The :command:`PATH` environment variable may need to be updated to make the
:command:`VBoxManage` command easily accessible from the terminal.
For example, using Windows PowerShell:
.. code-block:: bash
$env:PATH += ";C:\Program Files\Oracle\VirtualBox"
.. image:: ./figures/vbox/vbox-convert-raw-to-VDI.png
:alt: Convert image in Windows command prompt
For more information on the :command:`VBoxManage` command,
see the `VirtualBox manual section on VBoxManage`_.
#. The originally extracted live image file
(:file:`clear-<VERSION>-live.img`) can now be deleted.
#. Move the converted :file:`clear-VM.vdi` disk image file to a permanent
location. The VDI will be attached to the |VB| VM and should not be
deleted.
Create a new |VB| virtual machine
*********************************
A new VM needs to be created in |VBM| to attach the VDI with |CL| installed.
General instructions for creating a virtual machine and details about using
different settings are available on the
`VirtualBox manual section on Creating a VM`_.
#. Launch the |VBM| from your host system.
#. Click the *New* button to create a new VM.
.. image:: ./figures/vbox/vbox-new-vm.png
:alt: Create a new VM in VirtualBox
#. 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: **Use an existing virtual hard disk file**
Click the folder icon next to the drop down menu:
.. image:: ./figures/vbox/vbox-create-vm-existing-disk.png
:alt: Create a new VM in VirtualBox with an existing disk
#. A new window will appear for choosing an existing disk. Click the *Add*
button, browse to the saved VDI file, and click *Choose*.
.. image:: ./figures/vbox/vbox-create-vm-choose-disk.png
:alt: Create a new VM in VirtualBox with an existing disk
#. Click the *Create* button.
#. A new virtual machine will be created and appear in the |VBM|. Click
*Settings* to configure the |CL| VM.
.. image:: ./figures/vbox/vbox-vm-created.png
:alt: A VM selected in VirtualBox Manager
#. 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)**
.. image:: ./figures/vbox/vbox-vm-settings-EFI.png
:alt: 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.
.. _vbox-start-vm-and-lga-begin:
Start the |CL| VM
*****************
The |CL| VM can now be powered on and setup.
General instructions for using a |VB| virtual machine are available on the
`VirtualBox manual section on Running a VM`_.
#. Start the VM from the |VBM| by selecting the |CL| VM and clicking *Start*
.. image:: ./figures/vbox/vbox-start-vm.png
:alt: Starting a VirtualBox VM
#. |CL| will boot and prompt for login.
- Enter **root** for the username.
#. You will be immediately prompted to set a new password for the **root**
user. Reference :ref:`security` for more information about |CL| security
concepts.
.. image:: ./figures/vbox/vbox-cl-first-login.png
:alt: Initial login to Clear Linux OS on a VirtualBox VM
Install |VB| Linux Guest Additions
==================================
The |VB| Linux Guest Additions provide drivers for full compatibility and
functionality.
|CL| provides |VB| guest drivers and an install script in the **kernel-lts**
(Long Term Support) bundle by |CL|.
#. Validate the installed kernel is **kernel-lts** by checking the output
of the :command:`uname -r` command. It should end in **.lts**.
.. code-block:: bash
uname -r
4.<VERSION>.lts
If the running kernel is not **lts**: install the LTS kernel manually,
update the bootloader, and check again:
.. code-block:: bash
swupd bundle-add kernel-lts
clr-boot-manager set-kernel $(basename $(realpath /usr/lib/kernel/default-lts))
clr-boot-manager update
reboot
#. Remove any kernel bundles that are not *kernel-lts* or *kernel-install*
to simplify and avoid conflicts:
.. code-block:: bash
swupd bundle-list | grep kernel
swupd bundle-remove <NON-LTS-KERNEL>
.. image:: ./figures/vbox/vbox-cl-remove-non-lts-kernels.png
:alt: Initial login to Clear Linux OS on a VirtualBox VM
#. From the VM Console window, click *Devices* on the top menu bar, and
select *Insert Guest Additions CD image...* to mount the |VB| driver
installation to the |CL| VM.
.. image:: ./figures/vbox/vbox-vm-insert-ga-cd.png
:alt: VirtualBox CD
.. note::
To release the mouse cursor from the VM console window, press the right Ctrl key on the keyboard.
#. |CL| provides a script called :command:`install-vbox-lga` to help patch
and install |VB| drivers for |CL|. Inside |CL| VM run this command:
.. code-block:: bash
install-vbox-lga
#. After the script completes successfully, reboot the |CL| VM.
.. code-block:: bash
reboot
#. After the VM reboot, login and verify the |VB| drivers are loaded:
.. code-block:: bash
lsmod | grep ^vbox
You should see drivers loaded with names beginning with **vbox**: (vboxguest, vboxsf, vboxvideo).
The |CL| VM running on |VB| is ready to be used.
.. _vbox-start-vm-and-lga-end:
.. _vbox-troubleshooting-begin:
Troubleshooting
***************
#. **Problem:** Out of disk space inside of |CL| and not be able to install
additional bundles.
**Solution:** The |CL| images are small to minimize download time and
initial disk space .
Power off the VM and resize the virtual disk for the |CL| VM using the |VB|
`Virtual Media Manager`_ found under the File menu. Afterwards, power the
|CL| VM on and follow the instructions here to have |CL| detect the resized
disk. :ref:`increase-virtual-disk-size`
#. **Problem:** On a Microsoft Windows OS, |VB| encounters an error when
trying to start a VM indicating *VT-X/AMD-v hardware acceleration is not
available on your system.*
.. image:: ./figures/vbox/vbox-no-vtx.png
:alt: 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 |VB| 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:
.. code-block:: bash
bcdedit /set {current} hypervisorlaunchtype off
To enable Hyper-V again, execute this command in an
**Administrator: Command Prompt or Powershell**, and reboot the system:
.. code-block:: bash
bcdedit /set {current} hypervisorlaunchtype Auto
.. _vbox-troubleshooting-end:
.. |VB| replace:: VirtualBox
.. |VBM| replace:: VirtualBox Manager
.. _appropriate instructions: https://www.virtualbox.org/manual/ch02.html
.. _official VirtualBox website: https://www.virtualbox.org/wiki/Downloads
.. _VirtualBox hypervisor: https://www.virtualbox.org/
.. _downloads page: https://clearlinux.org/downloads
.. _`VirtualBox manual section on Creating a VM`: https://www.virtualbox.org/manual/UserManual.html#gui-createvm
.. _`VirtualBox manual section on Running a VM`: https://www.virtualbox.org/manual/ch01.html#intro-starting-vm-first-time
.. _`Virtual Media Manager`: https://www.virtualbox.org/manual/ch05.html#vdis
.. _7zip: http://www.7-zip.org/
.. _Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html
.. _`VirtualBox manual section on VBoxManage`: https://www.virtualbox.org/manual/ch08.html#vboxmanage-convertfromraw
@@ -34,8 +34,9 @@ latest :abbr:`LTS (Long Term Support)` Linux kernel. It is optimized for fast
booting and performs best on the Intel® architectures described on the
:ref:`supported hardware list<system-requirements>`. Additionally, this
kernel includes the VirtualBox\* kernel modules, see our
:ref:`instructions on using Virtualbox<virtualbox>` for more information.
The optimization patches are found in our `Linux-LTS`_ GitHub repo.
:ref:`instructions on using Virtualbox<virtualbox-cl-installer>` for more
information. The optimization patches are found in our `Linux-LTS`_ GitHub
repo.
Kernel KVM
==========
+4
View File
@@ -14,3 +14,7 @@
Not fully unmounting the USB drive before burning an image could cause
file system checksum errors in it. If this happens, burn the image again
ensuring all the USB drive partitions are unmounted first.
.. |VB| replace:: VirtualBox
.. |VBM| replace:: VirtualBox Manager