diff --git a/.gitignore b/.gitignore index 43790bbd..3316fc85 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,6 @@ source/_build *.swp *~ .*~ + +# ignore VS code settings +.vscode/ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/7zipwin.png b/source/clear-linux/get-started/virtual-machine-install/figures/7zipwin.png deleted file mode 100644 index 574a82b1..00000000 Binary files a/source/clear-linux/get-started/virtual-machine-install/figures/7zipwin.png and /dev/null differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-cd.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox-cd.png deleted file mode 100644 index a1978856..00000000 Binary files a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-cd.png and /dev/null differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-convert-image.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox-convert-image.png deleted file mode 100644 index f1e64ea1..00000000 Binary files a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-convert-image.png and /dev/null differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-create-vm.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox-create-vm.png deleted file mode 100644 index 307b45f4..00000000 Binary files a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-create-vm.png and /dev/null differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-efi.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox-efi.png deleted file mode 100644 index eb33bb79..00000000 Binary files a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-efi.png and /dev/null differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-hdisk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox-hdisk.png deleted file mode 100644 index 839fc9d0..00000000 Binary files a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-hdisk.png and /dev/null differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-memory-size.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox-memory-size.png deleted file mode 100644 index d8c5b71c..00000000 Binary files a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-memory-size.png and /dev/null differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-x.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox-x.png deleted file mode 100644 index 8357efa1..00000000 Binary files a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-x.png and /dev/null differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-first-login.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-first-login.png new file mode 100644 index 00000000..5e8ed691 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-first-login.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-remove-non-lts-kernels.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-remove-non-lts-kernels.png new file mode 100644 index 00000000..2a253748 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-cl-remove-non-lts-kernels.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-convert-raw-to-VDI.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-convert-raw-to-VDI.png new file mode 100644 index 00000000..3c20c833 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-convert-raw-to-VDI.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-disk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-disk.png new file mode 100644 index 00000000..7995d8d7 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-disk.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-choose-disk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-choose-disk.png new file mode 100644 index 00000000..c672ac9b Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-choose-disk.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-existing-disk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-existing-disk.png new file mode 100644 index 00000000..d8b4846a Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-existing-disk.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-new-disk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-new-disk.png new file mode 100644 index 00000000..7c2d1cc6 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-new-disk.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-no-disk.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-no-disk.png new file mode 100644 index 00000000..68f9dddf Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-create-vm-no-disk.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-IMG.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-IMG.png new file mode 100644 index 00000000..6aeb25e1 Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-IMG.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-ISO.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-ISO.png new file mode 100644 index 00000000..c9b8932f Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-extract-cl-ISO.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-new-vm.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-new-vm.png new file mode 100644 index 00000000..ae8929bb Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-new-vm.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox-no-vtx.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-no-vtx.png similarity index 100% rename from source/clear-linux/get-started/virtual-machine-install/figures/vbox-no-vtx.png rename to source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-no-vtx.png diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-shutdown-vm.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-shutdown-vm.png new file mode 100644 index 00000000..11ef90fe Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-shutdown-vm.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-start-vm.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-start-vm.png new file mode 100644 index 00000000..76c012ec Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-start-vm.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-created.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-created.png new file mode 100644 index 00000000..1e23ccbd Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-created.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-insert-ga-cd.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-insert-ga-cd.png new file mode 100644 index 00000000..4eae68ce Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-insert-ga-cd.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-EFI.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-EFI.png new file mode 100644 index 00000000..2dc55dff Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-EFI.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-browse-ISO.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-browse-ISO.png new file mode 100644 index 00000000..ed229d3f Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-browse-ISO.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-mount-ISO.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-mount-ISO.png new file mode 100644 index 00000000..765df5ca Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-mount-ISO.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-unmount-ISO.png b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-unmount-ISO.png new file mode 100644 index 00000000..4e08843f Binary files /dev/null and b/source/clear-linux/get-started/virtual-machine-install/figures/vbox/vbox-vm-settings-unmount-ISO.png differ diff --git a/source/clear-linux/get-started/virtual-machine-install/virtualbox-cl-installer.rst b/source/clear-linux/get-started/virtual-machine-install/virtualbox-cl-installer.rst new file mode 100644 index 00000000..a2ac6498 --- /dev/null +++ b/source/clear-linux/get-started/virtual-machine-install/virtualbox-cl-installer.rst @@ -0,0 +1,277 @@ +.. _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` + + +.. contents:: :local: + :depth: 2 + + +.. include:: virtualbox.rst + :start-after: vbox-prereqs-begin: + :end-before: vbox-prereqs-end: + + + +Download and extract the |CL| installer ISO image +************************************************* + +The appropriate |CL| installer image needs to be downloaded and extracted. + +.. 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`. + +#. Download the **installer ISO** image (:file:`clear--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: + + .. code-block:: bash + + curl -O https://download.clearlinux.org/image/$(curl https://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 + file to *Extract Here* (in the same directory) + + .. image:: ./figures/vbox/vbox-extract-cl-ISO.png + :alt: 7zip extract here command + + - On Linux : + + .. code-block:: bash + + xz -d clear--installer.iso.xz + + + + +#. The originally downloaded compressed archive file + (:file:`clear--installer.iso.xz`) can now be deleted. + + +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 +`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: **Create a virtual hard disk now** + + .. image:: ./figures/vbox/vbox-create-vm-new-disk.png + :alt: Create a new VM in VirtualBox with a new disk + + +#. Click the *Create* button. + +#. 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** + + .. image:: ./figures/vbox/vbox-create-disk.png + :alt: Create a new virtual hard disk in VirtualBox + +#. 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. + + +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. + +#. From the middle *Storage Devices* column, click the blue CD disk labeled + *Empty* 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 *Choose Virtual Optical + Disk File...* + + .. image:: ./figures/vbox/vbox-vm-settings-mount-ISO.png + :alt: Mounting an ISO in VirtualBox VM Settings + +#. A *choose a virtual optical disk file* browser window will appear. + Navigate to the extracted ISO file, select it, and click *Open*. + + .. image:: ./figures/vbox/vbox-vm-settings-browse-ISO.png + :alt: Mounting an ISO in VirtualBox VM Settings + +#. Click *OK* to exit the *VM Settings* menu and return to the main + |VBM|. + + + +Install |CL| using the installer +================================ + +#. 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 + +#. A new window of the VM console will appear and boot into the |CL| + installer. Follow the steps in the `Install Clear Linux OS`_ to + install |CL| 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 |VB| driver compatibility. + + +#. After |CL| installation is complete, the VM will reboot and return to the + |CL| 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 |CL| installer ISO needs to be unmounted to allow the VM to boot from the +virtual hard disk, which |CL| has been installed to. + + +#. Power off the |CL| VM. + + .. image:: ./figures/vbox/vbox-shutdown-vm.png + :alt: Powering off a VirtualBox VM + +#. 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 + left-hand side. + +#. From the middle *Storage Devices* column, click the blue CD disk labeled + *clear--installer.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* + + .. image:: ./figures/vbox/vbox-vm-settings-unmount-ISO.png + :alt: Unmounting an ISO in VirtualBox VM Settings + +#. Click *OK* to exit the *VM Settings* menu and return to the main + |VBM|. + + + + +.. include:: virtualbox.rst + :start-after: vbox-start-vm-and-lga-begin: + :end-before: vbox-start-vm-and-lga-end: + + + + + +.. include:: virtualbox.rst + :start-after: vbox-troubleshooting-begin: + :end-before: 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 + +.. _`Install Clear Linux OS`: https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install#install-cl-on-your-target-system\ + +.. _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 \ No newline at end of file diff --git a/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst b/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst index f30bdca8..3a8cdcc6 100644 --- a/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst +++ b/source/clear-linux/get-started/virtual-machine-install/virtualbox.rst @@ -1,198 +1,370 @@ .. _virtualbox: -Run pre-configured |CL-ATTR| as a VirtualBox\* guest OS -########################################################### +Run pre-configured |CL-ATTR| as a VirtualBox\* Virtual Machine +############################################################## -This instruction explains how to deploy a pre-configured |CL-ATTR| image as a guest on the `VirtualBox hypervisor`_ . +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. -Download VirtualBox -******************* +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` -VirtualBox\* is a type 2 hypervisor from Oracle. Download and use **version 5.0 or greater** from the `official VirtualBox website`_. +.. contents:: :local: + :depth: 2 -.. _create_vm_vbox: + + +.. _vbox-prereqs-begin: Prerequisites ************* -The instruction assumes that you have: +Before continuing make sure that you have: -#. Enabled virtualization technology in the host machine's BIOS. +#. 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--live.img.xz - vbox-img convert --srcfilename clear-XXXX-live.img --dstfilename clear-XXXX-live.vdi --srcformat raw --dstformat vdi +#. There originally downloaded compressed archive file + (:file:`clear--live.img.xz`) can now be deleted. - .. note:: Be sure you have VirtualBox directory in your PATH (i.e., on - Windows :file:`C:\\Program Files\\Oracle\\VirtualBox`). - + On windows: launch a **Command Prompt** program and type +Convert |CL| live image to a |VB| Disk Image +******************************************** - .. code-block:: console +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. - set PATH=%PATH%;"C:\Program Files\Oracle\VirtualBox" +#. Launch a terminal and navigate to the directory containing the + extracted live image. - .. image:: ./figures/vbox-convert-image.png - :alt: Convert image in Windows command propt -#. Create a virtual machine using the VirtualBox assistant: +#. Convert RAW live image to a :abbr:`VDI (VirtualBox Disk Image)` + format using the command-line VirtualBox Disk Utility. - a. Type: **Linux** + .. code-block:: bash + + VBoxManage convertfromraw clear--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--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: - b. Version: **Linux 2.6 / 3.x / 4.x (64-bit)** + - 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** - .. image:: ./figures/vbox-create-vm.png - :alt: Create a new image in VirtualBox + Click the folder icon next to the drop down menu: - c. Select default memory size. - - .. image:: ./figures/vbox-memory-size.png - - d. Attach the virtual disk created in step number 3 as a virtual hard - disk file. Click the folder icon (lower right) to browse to find the - VDI file. - - .. image:: ./figures/vbox-hdisk.png - -#. After it is created, go to settings to enable **EFI support** - - * System -> Enable EFI (special OSes only) - - .. image:: ./figures/vbox-efi.png - :alt: Enable EFI on VirtualBox + .. image:: ./figures/vbox/vbox-create-vm-existing-disk.png + :alt: Create a new VM in VirtualBox with an existing disk -Run your new VM -*************** +#. A new window will appear for choosing an existing disk. Click the *Add* + button, browse to the saved VDI file, and click *Choose*. -|CL| supports VirtualBox kernel modules used -by the Linux kernel 4.14 :abbr:`LTS (Long Term Support)` -(*kernel-lts bundle*).This kernel was selected because |CL| OS's main kernel -(``kernel-native``) bundle keeps up-to-date with the upstream Linux kernel, -and sometimes VirtualBox kernel modules aren't compatible with pre-kernel -releases. + .. image:: ./figures/vbox/vbox-create-vm-choose-disk.png + :alt: Create a new VM in VirtualBox with an existing disk -On the first boot, |CL| requests a user login. - -#. Type **root**. - -#. Enter a new password when prompted. - -To install the VirtualBox kernel modules, here are the steps: - -#. Install the bundle that supports VirtualBox modules:: - - swupd bundle-add kernel-lts - -#. Set a timeout in the bootmanager to shows a menu at boot time:: - - clr-boot-manager set-timeout 10 - -#. Update the bootloader entries with:: - - clr-boot-manager update - -#. Reboot your system with:: - - reboot - - and choose **clear-linux-lts-4.14.XX-YYY** kernel version. - -#. (*Optional*) Unset timeout to boot directly to LTS version:: - - clr-boot-manager set-timeout 0 - -#. (*Mandatory*) Update bootmanger to always use LTS version:: - - clr-boot-manager update - -Install Guest Additions -======================= - -The kernel modules are shipped with the ``kernel-lts`` bundle. Insert Guest -Additions CD image using *Devices* menu you'll need to install the *user* -Linux Guest Additions. To install the VirtualBox Guest Additions, -follow these steps: +#. Click the *Create* button. -#. Insert Guest Additions CD image using *Devices* menu +#. A new virtual machine will be created and appear in the |VBM|. Click + *Settings* to configure the |CL| VM. - .. image:: ./figures/vbox-cd.png + .. 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..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 + + .. 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 -#. Install Linux users Guest Additions:: +.. note:: + To release the mouse cursor from the VM console window, press the right Ctrl key on the keyboard. - install-vbox-lga -#. Reboot your system:: - - reboot +#. |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 -=============== +*************** -On Windows OS, *VirtualBox* cannot do a **Hardware Virtualization** when -*Hyper-V* is enabled. +#. **Problem:** Out of disk space inside of |CL| and not be able to install + additional bundles. -.. image:: ./figures/vbox-no-vtx.png - :alt: VirtualBox hardware acceleration error + **Solution:** The |CL| images are small to minimize download time and + initial disk space . -To disable *Hyper-V* you should execute:: + 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` - bcdedit /set {current} hypervisorlaunchtype off +#. **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.* -in an **Administrator: Command Prompt**, then reboot your system. -To enable Hyper-V again, you should execute:: + .. image:: ./figures/vbox/vbox-no-vtx.png + :alt: VirtualBox hardware acceleration error - bcdedit /set {current} hypervisorlaunchtype Auto + + **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/ -.. _latest: https://download.clearlinux.org/image/ + +.. _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 + +.. _`Install Clear Linux OS`: https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install#install-cl-on-your-target-system\ + .. _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