diff --git a/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02X.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02X.png new file mode 100644 index 00000000..2903118d Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02X.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-18.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-18.png new file mode 100644 index 00000000..d6ac2d52 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-18.png differ diff --git a/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-19.png b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-19.png new file mode 100644 index 00000000..a82cb2a6 Binary files /dev/null and b/source/clear-linux/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-19.png differ diff --git a/source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst b/source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst index 3a3b6068..1915d298 100644 --- a/source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst +++ b/source/get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst @@ -4,9 +4,9 @@ Install |CL-ATTR| from the live desktop ####################################### The live desktop allows you to boot |CL-ATTR| in a GNOME desktop without -modifying the host system, offering the chance to explore developing -on |CL|. Better yet, launch the |CL| installer to install on your target -system. +modifying the host system, offering you the chance to explore developing +on |CL| or install it. In this document, we show how to install |CL| on a +target system. .. contents:: :local: :depth: 1 @@ -22,7 +22,10 @@ Assure that your target system supports the installation: Preliminary steps ***************** -#. Visit our `Downloads`_ page and download the file :file:`clear--live-desktop.iso` +#. `Visit our Downloads page`_. + +#. Download the file :file:`clear--live-desktop.iso`, + also called the |CL| Desktop. .. note:: @@ -64,44 +67,8 @@ these steps. .. _install-on-target-end: -Confirm network connection -========================== - -Confirm there is a network connection before launching the installer. -Choose a method: `Wired Connection`, or `WiFi Connected`. This guide shows -an example of a **Wired Connection**. - -#. In the upper right of the top menu bar, select the square icon to view - Network settings, shown in Figure 2. - -#. Select :guilabel:`Wired Connected` and then :guilabel:`Wired Settings`. - - .. figure:: figures/bare-metal-install-desktop-02.png - :scale: 100% - :alt: Software icon, Network settings - - Figure 2: Software icon, Network settings - -#. View the :guilabel:`Wired` menu to assure that you're target system and - installer are connected to a network. - -#. Optional: Configure Proxy settings. - - #. To view :guilabel:`Network Proxy`, select its :guilabel:`Gear` icon. - - #. Select from `Automatic`, `Manual` or `Disabled` as desired. - - #. Close the dialogue box. - -#. Select the :guilabel:`Gear` icon to view Network settings. - -#. If desired, select :guilabel:`Connect automatically`. - Select other options as desired. - -#. Select :guilabel:`Apply` button to confirm change to settings. - -Software (Optional) -------------------- +Software (optional) +=================== Explore |CL| bundles and other software. Double-click the :guilabel:`Software` icon from the Activities menu, shown in Figure 2. @@ -115,30 +82,62 @@ Assure a network connection exists before launching `Software`. Launch the |CL| installer ========================= -#. After the live desktop image boots, find the |CL| installer icon in - the :guilabel:`Activities` menu at left, shown in Figure 3. +#. After the live desktop image boots, scroll over the vertical + :guilabel:`Activities` menu at left. -#. Click the |CL| penguin icon to launch the installer. +#. Click the |CL| penguin icon to launch the installer, shown in Figure 2. - .. figure:: figures/bare-metal-install-desktop-03.png + .. figure:: figures/bare-metal-install-desktop-02.png :scale: 100% :alt: Install Clear Linux OS icon - Figure 3: |CL| installer icon + Figure 2: |CL| installer icon -#. The installer is launched, as shown in Figure 4. +#. After the installer is launched, it will appear as shown in Figure 3. - .. figure:: figures/bare-metal-install-desktop-04.png + .. figure:: figures/bare-metal-install-desktop-03.png :scale: 100% :alt: |CL| Desktop Installer - Figure 4: |CL| OS Desktop Installer + Figure 3: |CL| OS Desktop Installer #. In :guilabel:`Select Language`, select a language from the options, or type your preferred language in the search bar. #. Select :guilabel:`Next`. +Checking prerequisites +====================== + +The installer automatically launches :guilabel:`Checking Prerequisites`, +which checks your target system for compatibility and network connectivity. + +After the installer shows `Prerequisites passed`, select :guilabel:`Next` to +proceed with installation. + +.. figure:: figures/bare-metal-install-desktop-04.png + :scale: 100% + :alt: Checking Prerequisites + + Figure 4: Checking Prerequisites + +Network Proxy (optional) +------------------------ + +#. Configure :guilabel:`Network Proxy` settings. + +#. In the top right menu bar, select the :guilabel:`Power button`. + +#. Select :guilabel:`Wired Connected` and then :guilabel:`Wired Settings`. + + #. In :guilabel:`Network Proxy`, select the :guilabel:`Gear` icon to view + options. + + #. Select an option from `Automatic`, `Manual` or `Disabled`. + + #. Close :guilabel:`Network Proxy`. + +#. Close :guilabel:`Settings`. .. _incl-bare-metal-beta-start: @@ -153,7 +152,7 @@ To fulfill minimum installation requirements, complete the * The :kbd:`Install` button is only highlighted **after** you complete `Required options`_. - * Checkmarks indicate a selection has been made. + * Check marks indicate a selection has been made. * An Internet connection is required. You may want to launch a browser prior to installation to verify your Internet connection. @@ -164,7 +163,7 @@ To fulfill minimum installation requirements, complete the The |CL| Desktop Installer Main Menu appears as shown in Figure 5. To meet the minimum requirements, enter values in all submenus for the :guilabel:`Required options`. After you complete them, your selections appear -below submenus and a checkmark appears at right. +below submenus and a check mark appears at right. .. figure:: figures/bare-metal-install-desktop-05.png :scale: 100% @@ -180,7 +179,7 @@ Navigation * Use :kbd:`Tab` key to navigate between :guilabel:`Required options` and :guilabel:`Advanced options` -* Use :kbd:`Up` or :kbd:`Down` arrow keys to navigate submenu list. +* Use :kbd:`Up` or :kbd:`Down` arrow keys to navigate the submenus. * Select :kbd:`Confirm`, or :kbd:`Cancel` in submenus. @@ -194,7 +193,7 @@ Select Time Zone by default. #. In :guilabel:`Select Time Zone`, navigate to the desired time zone. - Or start typing the region and then city. + Or start typing the region and then the city. (.e.g., :file:`America/Los_Angeles`). #. Select :guilabel:`Confirm`. @@ -237,6 +236,7 @@ Select Installation Media Safe Installation ----------------- + Use this method to safely install |CL| on media with available space, or alongside existing partitions, and accept the `Default partition schema`_. If enough free space exists, safe installation is allowed. @@ -254,7 +254,8 @@ If enough free space exists, safe installation is allowed. Destructive Installation ------------------------ -Use this method to destroy the contents of the target device, install |CL| on it, and accept the `Default partition schema`_. +Use this method to destroy the contents of the target device, install |CL| +on it, and accept the `Default partition schema`_. Disk encryption =============== @@ -370,11 +371,9 @@ After you complete the `Required options`_, we recommend completing customizes your development environment, so you're ready to go immediately after reboot. -* `Bundle Selection`_ +.. note:: -* `Assign Hostname`_ - -As for bundles, you can always add more later with :ref:`swupd-guide`. + You can always add more bundles later with :ref:`swupd-guide`. Bundle Selection ================ @@ -420,38 +419,73 @@ Assign Hostname alphanumeric character but may also contain hyphens. Maximum length of 63 characters. -#. Navigate to :kbd:`Confirm` until highlighted. - #. Select :kbd:`Confirm`. Optional: Skip to `Finish installation`_. +Kernel Configuration +==================== + +#. In :guilabel:`Kernel Configuration`, navigate to select your desired + kernel. :guilabel:`Native` is selected by default. + + .. figure:: figures/bare-metal-install-desktop-16.png + :scale: 100% + :alt: Kernel Configuration + + Figure 16: Kernel Configuration + +#. To add arguments, enter the argument in :guilabel:`Add Extra Arguments`. + +#. To remove an argument, enter the argument in :guilabel:`Remove Arguments`. + +#. Select :kbd:`Confirm`. + +Software Updater Configuration +============================== + +#. In Advanced Options, select :guilabel:`Software Updater Configuration`. + +#. In :guilabel:`Mirror URL`, follow the instructions if you wish to + specify a different installation source. + +#. :guilabel:`Enable Auto Updates` is selected by default. If you **do not** + wish to enable automatic software updates, uncheck the box. + + .. figure:: figures/bare-metal-install-desktop-17.png + :scale: 100% + :alt: Software Updater Configuration + + Figure 17: Software Updater Configuration + +#. Select :kbd:`Confirm`. + Finish installation ******************* #. When you are satisfied with your installation configuration, select :guilabel:`Install`. - .. figure:: figures/bare-metal-install-desktop-16.png + .. figure:: figures/bare-metal-install-desktop-18.png :scale: 100% :alt: Assign Hostname - Figure 16: Finish installation + Figure 18: Finish installation .. note: - All checkmarks must be visible in :guilabel:`Required Options` for you to select :guilabel:`Install`. + All check marks must appear in :guilabel:`Required Options` for the + :guilabel:`Install` button to be enabled. #. If you do not enter a selection for all :guilabel:`Required Options`, - the :guilabel:`Install` button remains greyed out, as shown - in Figure 17. Return to `Required Options`_ and make selections. + the :guilabel:`Install` button remains disabled, as shown + in Figure 19. Return to `Required Options`_ and make selections. - - .. figure:: figures/bare-metal-install-desktop-17.png + .. figure:: figures/bare-metal-install-desktop-19.png :scale: 100% :alt: Required Options - Incomplete - Figure 17: Required Options - Incomplete + Figure 19: Required Options - Incomplete #. After installation is complete, select :guilabel:`Exit`. @@ -465,14 +499,14 @@ Finish installation Allow time for the graphical login to appear. A login prompt shows the administrative user that you created. -#. Log in as the adminstrative user. +#. Log in as the administrative user. Congratulations. You successfully installed |CL|. Default partition schema ======================== -Table 1 shows the defult partition schema with the exception of root, +Table 1 shows the default partition schema with the exception of root, which varies. .. list-table:: **Table 1. Disk Partition Setup** @@ -497,6 +531,6 @@ Next steps :ref:`guides` -.. _Downloads: https://clearlinux.org/downloads -.. _Autoproxy: https://clearlinux.org/features/autoproxy +.. _Visit our downloads page: https://clearlinux.org/downloads + diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02.png b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02.png index 2903118d..bce97b57 100644 Binary files a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02.png and b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-02.png differ diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-03.png b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-03.png index bce97b57..a2650b35 100644 Binary files a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-03.png and b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-03.png differ diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-04.png b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-04.png index a2650b35..0ae7d397 100644 Binary files a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-04.png and b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-04.png differ diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-14.png b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-14.png index ed4edeea..f47bd702 100644 Binary files a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-14.png and b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-14.png differ diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-16.png b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-16.png index d6ac2d52..9560bf24 100644 Binary files a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-16.png and b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-16.png differ diff --git a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-17.png b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-17.png index a82cb2a6..d51a0fa7 100644 Binary files a/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-17.png and b/source/get-started/bare-metal-install-desktop/figures/bare-metal-install-desktop-17.png differ diff --git a/source/get-started/bootable-usb/bootable-usb.rst b/source/get-started/bootable-usb/bootable-usb.rst index 2379bb50..995cf3f5 100644 --- a/source/get-started/bootable-usb/bootable-usb.rst +++ b/source/get-started/bootable-usb/bootable-usb.rst @@ -3,8 +3,8 @@ Create a bootable USB drive ########################### -Instructions to create a |CL-ATTR| USB drive vary depending on your operating -system. Follow the instructions applicable to your system: +Follow the instructions applicable to your system to create a bootable |CL-ATTR| +USB drive: * :ref:`bootable-usb-linux` * :ref:`bootable-usb-mac` @@ -14,7 +14,7 @@ Prerequisites ************* * Use an **8GB** or larger USB drive. -* Download the |CL| live boot image or interactive installer image from the +* Download the |CL| live boot image or interactive installer image from the `Downloads`_ page. .. _bootable-usb-linux: diff --git a/source/get-started/compatibility-check.rst b/source/get-started/compatibility-check.rst index c6c3ff24..ff17e55e 100644 --- a/source/get-started/compatibility-check.rst +++ b/source/get-started/compatibility-check.rst @@ -3,16 +3,23 @@ Check processor and EFI firmware compatibility ############################################## -On a system that is currently running a Linux\* operating system, follow the -instructions below to determine if your system's processor and EFI firmware is -capable of running |CL-ATTR|. Otherwise, -:ref:`bare-metal-install-desktop` and then perform the steps -below. +Before installing |CL-ATTR|, check your host system's processor and EFI firmware +compatibility. To check compatibilty, choose one of the following paths: + +* From a system with a Linux\* OS installed, follow the instructions to :ref:`check-compatibility-steps`. + +* From a non-Linux OS, first :ref:`bare-metal-install-desktop` and then follow + the instructions to :ref:`check-compatibility-steps`. .. note:: This does not check other system components (for example: storage and graphics) for compatibility with |CL|. +.. _check-compatibility-steps: + +Check compatibility +******************* + #. Download the `clear-linux-check-config.sh`_ file. If a browser is not available, use: @@ -42,7 +49,7 @@ below. ./clear-linux-check-config.sh container - The script will print a list of test results similar to the output below. + The script prints a list of test results similar to the output below. All items should return a `SUCCESS` status. This example indicates the host's processor and EFI firmware support running |CL|. diff --git a/source/get-started/get-started.rst b/source/get-started/get-started.rst index 0ed84dff..a0ff24fd 100644 --- a/source/get-started/get-started.rst +++ b/source/get-started/get-started.rst @@ -3,9 +3,8 @@ Get started ########### -The Get Started section will get you up and running fast with |CL-ATTR|. Use -these step-by-step instructions to guide you through the installing |CL| -from a live desktop or to a virtual machine. +The Get Started section guides you through the requirements and installation of +|CL-ATTR|. Follow these step-by-step intructions to get started with |CL|, fast. Pre-install *********** diff --git a/source/get-started/install-configfile.rst b/source/get-started/install-configfile.rst index 860e28d7..60a1bf75 100644 --- a/source/get-started/install-configfile.rst +++ b/source/get-started/install-configfile.rst @@ -3,13 +3,17 @@ Install using clr-installer and a configuration file #################################################### -This guide describes how to install |CL-attr| using the clr-installer tool +This page explains how to install |CL-ATTR| using the clr-installer tool with a configuration file. The configuration file (:file:`clr-installer.yaml`) -can be used to duplicate the same installation configuration on more machines. +can be reused to duplicate the same installation configuration on additional +machines. +.. contents:: + :local: + :depth: 1 -System requirements -******************* +Prerequisites +************* Ensure that your target system supports the installation: diff --git a/source/get-started/virtual-machine-install/gce.rst b/source/get-started/virtual-machine-install/gce.rst index 0579648b..c94913b0 100644 --- a/source/get-started/virtual-machine-install/gce.rst +++ b/source/get-started/virtual-machine-install/gce.rst @@ -3,10 +3,11 @@ Launch |CL-ATTR| Compute Engine on Google Cloud Platform\* ########################################################## -This tutorial walks you through the steps to create a virtual machine -instance of |CL-ATTR| on `Google Cloud Platform`_ (:abbr:`GCP (Google Cloud Platform)`). +This page explains the steps to create a virtual machine instance of +|CL-ATTR| on `Google Cloud Platform`_ (:abbr:`GCP (Google Cloud Platform)`). -.. contents:: :local: +.. contents:: + :local: :depth: 1 Prerequisites @@ -17,9 +18,8 @@ Prerequisites * Generate and install a user SSH key in the Linux PCs that will connect to the VMs in GCP. - -Process -******* +Setup |CL| VM on GCP +******************** #. Sign in to your Google\* account on the `Google Cloud Console `_: @@ -51,10 +51,10 @@ Process #. Create a *Storage Bucket* for hosting the |CL| image source archive downloaded in the previous step: - * Click the *Navigation menu* icon on the upper left screen menu. + * Click the :guilabel:`Navigation menu` icon on the upper left screen menu. - * Select the *Storage* item from the side bar on the left. You will - be sent to the Storage Browser tool or the Cloud Storage overview page. + * Select the :menuselection:`Storage` item from the side bar on the left. You + will be sent to the Storage Browser tool or the Cloud Storage overview page. .. figure:: figures/gce/01-cloud-storage.png :scale: 50 % @@ -72,12 +72,12 @@ Process Figure 3: Cloud Storage Browser tool - * Click the ``CREATE BUCKET`` button to enter the bucket creation tool. + * Click the :guilabel:`CREATE BUCKET` button to enter the bucket creation tool. The bucket name must be unique because buckets in the Cloud Storage share a single global namespace. - Leave the remaining options set to the defaults, and select the - ``Create`` button at the bottom to create a *Bucket*. + Leave the remaining options set to the defaults, and click the + :guilabel:`Create` button at the bottom to create a *Bucket*. .. figure:: figures/gce/03-create-bucket.png :scale: 50 % @@ -85,7 +85,7 @@ Process Figure 4: Set bucket name -#. Once the bucket is created, click the ``Upload files`` button +#. Once the bucket is created, click the :guilabel:`Upload files` button on the Bucket details page to upload the |CL| GCE image archive to the named bucket: @@ -109,9 +109,10 @@ Process #. Browse the Compute Engine Image library page: - * Click the *Navigation menu* icon on the upper left screen menu. + * Click the :guilabel:`Navigation menu` icon on the upper left screen menu. - * Hover your mouse over the *Compute Engine* menu and select *Images*. + * Select the :menuselection:`Compute Engine --> Images` from the side bar on + the left. .. figure:: figures/gce/20-gce-image.png :scale: 50 % @@ -119,7 +120,7 @@ Process Figure 8: Image library -#. On the Compute Engine Image library page, click the ``[+] CREATE IMAGE`` +#. On the Compute Engine Image library page, click the :guilabel:`[+] CREATE IMAGE` menu item to create a custom image: .. figure:: figures/gce/20-image-library.png @@ -131,7 +132,7 @@ Process #. In the VM image creation page, change the image source type to *Cloud Storage file*. -#. Under :guilabel:`Cloud Storage file`, select :guilabel:`Browse`. +#. Under :guilabel:`Source`, select :guilabel:`Browse`. #. Locate the :file:`clear--gce.tar.gz` file, and click :guilabel:`Select`. @@ -142,7 +143,7 @@ Process Figure 10: Create image using imported object - Accept all default options, and click the ``Create`` button + Accept all default options, and click the :guilabel:`Create` button at the bottom to import the Clear Linux GCE image to the image library. .. figure:: figures/gce/22-image-list.png @@ -154,10 +155,10 @@ Process #. After the |CL| image is imported, you can launch a VM instance running |CL|: - * Click the *Navigation menu* icon on the upper left screen menu. + * Click the :guilabel:`Navigation menu` icon on the upper left screen menu. - * Hover your mouse over the *Compute Engine* menu group and select - the *VM instances* item. + * Select :menuselection:`Compute Engine --> VM Instances` from the side bar on + the left. .. figure:: figures/gce/30-vm-instances.png :scale: 50 % @@ -168,7 +169,7 @@ Process #. If no VM instance was created in this project, you will be prompted to create one. -#. Alternatively, click the ``CREATE INSTANCE`` button on the VM +#. Alternatively, click the :guilabel:`CREATE INSTANCE` button on the VM instances page to create a VM instance. .. figure:: figures/gce/30-vm-none.png @@ -183,10 +184,10 @@ Process Figure 14: VM instances list - * In :guilabel:`Region`, choose a region based on the + * Under :guilabel:`Region`, choose a region based on the `Best practices for Compute Engine regions selection`_. - * Under *Boot disk*, click the ``Change`` button. + * Under :guilabel:`Boot disk`, click the :guilabel:`Change` button. .. figure:: figures/gce/30-create-vm.png :scale: 50 % @@ -194,7 +195,7 @@ Process Figure 15: Use custom image - * Select the *Custom images* tab for using Clear Linux OS GCE image. + * Select the :menuselection:`Custom images` tab for using Clear Linux OS GCE image. .. figure:: figures/gce/31-select-boot-disk.png :scale: 50 % @@ -203,7 +204,8 @@ Process Figure 16: Select Clear Linux boot disk to create a VM instance * Scroll down to the bottom of the VM instance creation page, - expand the *Management, security, disks, networking, sole tenancy* group. + expand the :guilabel:`Management, security, disks, networking, sole tenancy` + group. .. figure:: figures/gce/40-clear-vm-security.png :scale: 50 % @@ -218,7 +220,7 @@ Process Refer to :ref:`security` for more details. - * Click the *Security* tab, copy and paste your SSH public key: + * Click the :menuselection:`Security` tab, copy and paste your SSH public key: .. figure:: figures/gce/40-ssh-key.png :scale: 50 % @@ -233,7 +235,7 @@ Process because it is an invalid character while creating user accounts in |CL|. - * Click the ``Create`` button to create the |CL| VM. + * Click the :guilabel:`Create` button to create the |CL| VM. #. The Clear Linux VM instance is created and assigned a public IP address: @@ -255,8 +257,6 @@ Process Related topics ************** -The following tutorials describe a similar process and may be useful references: - * :ref:`azure` * :ref:`aws-web` diff --git a/source/get-started/virtual-machine-install/hyper-v.rst b/source/get-started/virtual-machine-install/hyper-v.rst index 5f3baee5..45e00741 100644 --- a/source/get-started/virtual-machine-install/hyper-v.rst +++ b/source/get-started/virtual-machine-install/hyper-v.rst @@ -3,14 +3,20 @@ Use Hyper-V\* ############# -This section explains how to run |CL-ATTR| inside a +This page explains how to run |CL-ATTR| inside a `Windows Server Virtualization`_\* or **Hyper-V** environment. -Please ensure you have enabled `Intel® Virtualization Technology -`_ -(Intel® VT) and `Intel® Virtualization Technology for Directed I/O -`_ -(Intel® VT-d) in your BIOS/UEFI firmware configuration. +.. contents:: + :local: + :depth: 1 + +Prerequisites +************* + +* Enable `Intel® Virtualization Technology`_ (Intel® VT) + +* Enable `Intel® Virtualization Technology for Directed I/O`_ (Intel® VT-d) in + your BIOS/UEFI firmware configuration. Enable Hyper-V ************** @@ -21,7 +27,7 @@ Please refer to `Install Hyper-V on Windows 10`_ to enable and configure Create a virtual network ************************ -Once *Hyper-V* has been enabled on your Windows system you will need to +Once *Hyper-V* has been enabled on your Windows system you will need to create a virtual network in the **Hyper-V Manager**. Refer to the `Create a virtual network`_ documentation to create and configure a virtual network. @@ -30,7 +36,7 @@ Create a virtual machine ************************ #. Download and decompress the latest hyperv disk image - :file:`clear-XXXXX-hyperv.img.gz`, where XXXXX is the latest + :file:`clear-XXXXX-hyperv.img.gz`, where XXXXX is the latest available version of |CL| from our `Downloads`_ page. #. Create a virtual machine using the **Hyper-V Manager**: @@ -58,3 +64,5 @@ Your virtual machine running |CL| is ready! .. _Install Hyper-V on Windows 10: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v .. _Create a virtual network: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/connect-to-network .. _Downloads: https://cdn.download.clearlinux.org/image/ +.. _Intel® Virtualization Technology: http://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html +.. _Intel® Virtualization Technology for Directed I/O: https://software.intel.com/en-us/articles/intel-virtualization-technology-for-directed-io-vt-d-enhancing-intel-platforms-for-efficient-virtualization-of-io-devices \ No newline at end of file diff --git a/source/get-started/virtual-machine-install/kvm.rst b/source/get-started/virtual-machine-install/kvm.rst index ad31d381..8678e5eb 100644 --- a/source/get-started/virtual-machine-install/kvm.rst +++ b/source/get-started/virtual-machine-install/kvm.rst @@ -3,9 +3,13 @@ Run |CL-ATTR| as a KVM guest OS ############################### -This guide explains how to run |CL-ATTR| in a virtualized environment using +This page explains how to run |CL-ATTR| in a virtualized environment using :abbr:`KVM (Kernel-based Virtual Machine)`. +.. contents:: + :local: + :depth: 1 + Install QEMU-KVM **************** diff --git a/source/get-started/virtual-machine-install/virtual-machine-install.rst b/source/get-started/virtual-machine-install/virtual-machine-install.rst new file mode 100644 index 00000000..5becd2f2 --- /dev/null +++ b/source/get-started/virtual-machine-install/virtual-machine-install.rst @@ -0,0 +1,40 @@ +.. _virtual-machine-install: + +Install |CL-ATTR| in a virtual machine +###################################### + +This page explains the available kernel options to help you decide which +kernel to use when installing |CL-ATTR| in a VM. + +.. contents:: + :local: + :depth: 1 + +Compatible kernels +****************** + +The |CL| provides the following Linux kernels with a respective +:ref:`bundle ` for VMs. For each bundle, the specific use cases +and links to the bundle source code are provided. + +.. include:: ../../reference/compatible-kernels.rst + :Start-after: vm-kernels: + +Next steps +********** + +After making a kernel selection, install using the appropriate set of +installation instructions for your kernel selection. + +.. toctree:: + :maxdepth: 1 + + gce + kvm + virtualbox-cl-installer + vmware-esxi-install-cl + vmware-esxi-preconfigured-cl-image + vmw-player + vmw-player-preconf + hyper-v + ../../guides/maintenance/increase-virtual-disk-size.rst diff --git a/source/get-started/virtual-machine-install/virtualbox-cl-installer.rst b/source/get-started/virtual-machine-install/virtualbox-cl-installer.rst index c7af119f..2a25674d 100644 --- a/source/get-started/virtual-machine-install/virtualbox-cl-installer.rst +++ b/source/get-started/virtual-machine-install/virtualbox-cl-installer.rst @@ -3,25 +3,23 @@ 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). +This page explains how to create a virtual machine on the `VirtualBox`_ +hypervisor with |CL-ATTR| as the guest operating system. These instructions +support the |CL| live-server installer to create the |CL| virtual machine (VM). -.. contents:: :local: - :depth: 1 +.. contents:: + :local: + :depth: 1 Prerequisites ************* -Before continuing, assure you have: +#. Enable virtualization, such as `Intel® Virtualization Technology`_ + (Intel® VT), on the host system from EFI/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 - `VirtualBox`_ using the `VirtualBox Installation Instructions`_ for your platform. +#. Download and install |VB| **version 6.0 or greater** from + `VirtualBox`_ using the `VirtualBox Installation Instructions`_ for your + platform. Download and extract the |CL| installer ISO ******************************************* @@ -30,7 +28,7 @@ Download and extract the |CL| installer ISO |CL| on the `Downloads`_ page. #. Validate the integrity of the downloaded image by checking the file hash - and signatures. Refer :ref:`validate-signatures` for detailed steps. + and signatures. Refer to :ref:`validate-signatures` for detailed steps. #. Decompress the downloaded image. @@ -60,11 +58,11 @@ details about using different settings are available in the VirtualBox manual se #. Launch the |VBM| from your host system. -#. Click the *New* button to create a new VM. +#. Click the :guilabel:`New` button to create a new VM. #. Choose :guilabel:`Expert mode`. -#. In :guilabel:`Create Virtual Machine`, enter the following settings: +#. On the :guilabel:`Create Virtual Machine` screen, enter the following settings: - **Name**: Choose name (e.g. ClearLinuxOS-VM). - **Type**: Linux @@ -82,9 +80,9 @@ details about using different settings are available in the VirtualBox manual se Figure 2: Create Virtual Machine -#. Select :guilabel:`Create`. +#. Click :guilabel:`Create`. -#. In :guilabel:`Create Virtual Hard Disk`, select: +#. On the :guilabel:`Create Virtual Hard Disk` screen, select: - **File location** - **File size**: **32.00 GB**. Adjust size to your needs. @@ -97,16 +95,16 @@ details about using different settings are available in the VirtualBox manual se Figure 3: Create Virtual Hard Disk -#. Click *Create*. +#. Click :guilabel:`Create`. A new virtual machine will be created and appear in the |VBM|. -#. Click *Settings* to configure the |CL| VM. +#. Click :guilabel:`Settings` to configure the |CL| VM. -#. In the left-hand menu, navigate to the :guilabel:`System` menu. +#. In the left-hand menu, navigate to the :menuselection:`System` menu. -#. In the :guilabel:`Motherboard` tab, select the `Chipset` pulldown menu, - and then select :guilabel:`ICH9`. See Figure 4. +#. On the :guilabel:`Motherboard` tab, select the :guilabel:`Chipset` menu, and + then select :menuselection:`ICH9`. See Figure 4. .. note:: @@ -131,7 +129,7 @@ details about using different settings are available in the VirtualBox manual se machine under Settings > System > Processor for increased performance. -#. Select :guilabel:`OK`. +#. Click :guilabel:`OK`. Install |CL| on the |VB| VM *************************** @@ -144,15 +142,15 @@ Mount the installation ISO The |CL| installer ISO needs to be mounted as a virtual CD-ROM on the VM before powering the VM on. -#. From the *ClearLinux-OS* :guilabel:`Settings` at left, select +#. From the *ClearLinux-OS* :guilabel:`Settings` menu at left, select :guilabel:`Storage`. #. From :guilabel:`Storage Devices`, middle column, click the blue - disk labeled *Empty*. + disk labeled :guilabel:`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...* + the :guilabel:`Optical Drive` drop down menu and click + :guilabel:`Choose Virtual Optical Disk File...` .. figure:: figures/vbox/virtualbox-cl-installer-05.png :scale: 100% @@ -169,12 +167,12 @@ before powering the VM on. Figure 6: Mounting an ISO -#. Select :guilabel:`OK` to exit and return to the main |VBM|. +#. Click :guilabel:`OK` to exit and return to the main |VBM|. Install |CL| with live-server installer ======================================= -#. In the |VBM|, select virtual machine you created and click *Start*. +#. In the |VBM|, select virtual machine you created and click :guilabel:`Start`. .. figure:: figures/vbox/virtualbox-cl-installer-07.png :scale: 100% @@ -196,12 +194,12 @@ Install |CL| with live-server installer #. In :guilabel:`Configure Installation Media`, navigate top VBOX HARDDISK, and then select :guilabel:`Confirm`. - #. In :guilabel:`Advanced options` > :guilabel:`Manage User`, create an + #. In :menuselection:`Advanced options --> Manage User`, create an administrative user. #. Do not install the bundle `desktop-autostart`. -#. When |CL| installation is complete, select :guilabel:`Exit`. +#. When |CL| installation is complete, click :guilabel:`Exit`. #. At the prompt, enter: @@ -217,16 +215,18 @@ virtual hard disk. #. Return to the |VBM|. -#. Click *Settings* to configure the |CL| VM. +#. Click :guilabel:`Settings` to configure the |CL| VM. -#. From the *VM - Settings* window, navigate to the *Storage* pane from the - left-hand side. +#. From the VM :guilabel:`Settings` window, navigate to the :guilabel:`Storage` + pane in the left menu. -#. From the middle *Storage Devices* column, click the blue CD disk labeled - *clear--live-server.iso* under the *Controller: IDE* from. +#. From the middle :guilabel:`Storage Devices` column, click the blue CD disk + labeled :guilabel:`clear--live-server.iso` under the + :guilabel:`Controller: IDE`. -#. From the *Attributes* column at right, in *Optical Drive*, select the - blue CD icon beside and click *Remove Disk from Virtual Drive*. +#. From the :guilabel:`Attributes` column at right, in :guilabel:`Optical Drive`, + select the blue CD icon beside and click + :guilabel:`Remove Disk from Virtual Drive`. .. figure:: figures/vbox/virtualbox-cl-installer-08.png :scale: 100% @@ -234,8 +234,8 @@ virtual hard disk. Figure 8: Remove Disk from Virtual Drive -#. Click *OK* to exit the *VM Settings* menu and return to the main - |VBM|. +#. Click :guilabel:`OK` to exit the :guilabel:`VM Settings` menu and return to + the main |VBM|. Install |VB| Linux Guest Additions ================================== @@ -285,8 +285,9 @@ install script in the **kernel-lts** (Long Term Support) bundle by |CL|. sudo swupd bundle-list | grep kernel sudo swupd bundle-remove -#. 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. +#. In the VM Console top menu, click :guilabel:`Devices`, and select + :guilabel:`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% @@ -310,7 +311,7 @@ install script in the **kernel-lts** (Long Term Support) bundle by |CL|. 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`. +#. Shut down the system. Select :menuselection:`Machine --> ACPI Shutdown`. .. figure:: figures/vbox/virtualbox-cl-installer-10.png :scale: 100% diff --git a/source/get-started/virtual-machine-install/vmw-player-preconf.rst b/source/get-started/virtual-machine-install/vmw-player-preconf.rst index be3a4229..0e2287d2 100644 --- a/source/get-started/virtual-machine-install/vmw-player-preconf.rst +++ b/source/get-started/virtual-machine-install/vmw-player-preconf.rst @@ -3,24 +3,25 @@ Run pre-configured |CL-ATTR| image as a VMware\* Workstation Player guest OS ############################################################################ -`VMware Workstation 14 Player`_ is a type 2 hypervisor. It runs on top of +This page explains how to deploy a pre-configured |CL| VMware image on +`VMware Workstation 14 Player`_. + +.. contents:: + :local: + :depth: 1 + +Overview +******** + +VMware Workstation 14 Player is a type 2 hypervisor. It runs on top of another operating system such as Windows\* or Linux\*. With VMware ESXi, you can create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)` on your local system. -This section shows how to deploy a pre-configured |CL| VMware image on -VMware Workstation 14 Player. - -In this tutorial, we perform the following steps: - -.. contents:: :local: - :depth: 1 - .. note:: - The screenshots on this document show the Windows version of the - VMware Workstation 14 Player. The menus and prompts are similar to those - in the Linux version save some minor wording differences. + Screenshots in this document show VMware Workstation 14 Player for Windows. + Menus and prompts in the Linux version have minor wording differences. Install the VMware Workstation Player hypervisor ************************************************ diff --git a/source/get-started/virtual-machine-install/vmw-player.rst b/source/get-started/virtual-machine-install/vmw-player.rst index 268f5161..af317287 100644 --- a/source/get-started/virtual-machine-install/vmw-player.rst +++ b/source/get-started/virtual-machine-install/vmw-player.rst @@ -3,23 +3,26 @@ Install |CL-ATTR| as a VMware\* Workstation Player guest OS ########################################################### +This page explains how to create a new VM and install |CL| on it with the +VMware Workstation 14 Player hypervisor. + +.. contents:: + :local: + :depth: 1 + +Overview +******** + `VMware Workstation 14 Player`_ is a type 2 hypervisor. It runs on top of another operating system such as Windows\* or Linux\*. With VMware ESXi, you can create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)` on your local system. -This section shows how to create a new VM and install |CL| into it with the -VMware Workstation 14 Player hypervisor. Installing |CL| into a new VM -provides you flexibility when configuring the VM. You can configure the VM's -size, number of partitions, installed bundles, etc. +Installing |CL| into a new VM provides you flexibility when configuring the VM. +You can configure the VM's size, number of partitions, installed bundles, etc. -In this tutorial, we perform the following steps: - -.. contents:: :local: - :depth: 1 - -If you prefer to use a pre-configured |CL| VMware image instead, -see our :ref:`vmw-player-preconf` guide. +If you prefer to use a pre-configured |CL| VMware image instead, see our +:ref:`vmw-player-preconf` guide. VMware offers a type 1 hypervisor called `VMware ESXi`_ designed for the cloud environment. For information on how to install |CL| as guest OS on @@ -27,9 +30,8 @@ it, see :ref:`vmware-esxi-install-cl`. .. note:: - The screenshots on this document show the Windows version of the - VMware Workstation 14 Player. The menus and prompts are similar to those - in the Linux version save some minor wording differences. + Screenshots in this document show VMware Workstation 14 Player for Windows. + Menus and prompts in the Linux version have minor wording differences. Install the VMware Workstation Player hypervisor ************************************************ diff --git a/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst b/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst index 2e18bbe3..ac7129fa 100644 --- a/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst +++ b/source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst @@ -3,34 +3,34 @@ Install |CL-ATTR| as a VMware\* ESXi guest OS ############################################# -`VMware ESXi`_ is a type 1 bare-metal hypervisor which runs directly on top +This page explains how to create a new :abbr:`VM (Virtual Machine)` and +manually install |CL-ATTR| on the new VM with VMware ESXi 6.5. + +.. contents:: + :local: + :depth: 1 + +Overview +******** + +`VMware ESXi`_ is a type 1 bare-metal hypervisor that runs directly on top of server hardware. With VMware ESXi, you can create, configure, manage, and -run |CL-ATTR| virtual machines in the cloud. +run |CL| virtual machines in the cloud. -This section shows you how to create a new :abbr:`VM (Virtual Machine)` and -manually install |CL| into it with VMware ESXi 6.5. +Manually installing |CL| on a new VM gives additional configuration flexibility +during installation. For example: alternate disk sizes, number of partitions, +pre-installed bundles, etc. -Manually installing |CL| into a new VM provides you some additional -configuration flexibility during installation. For example: alternate -disk sizes, number of partitions, pre-installed bundles, etc. - -If you would prefer to use a preconfigured |CL| VMware image instead, -see :ref:`vmware-esxi-preconfigured-cl-image`. +If you prefer to use a preconfigured |CL| VMware image instead, refer to +:ref:`vmware-esxi-preconfigured-cl-image`. .. note:: - VMware also offers a type 2 hypervisor called `VMware Workstation Player`_ - which is designed for the desktop environment. - - See :ref:`vmw-player-preconf` or see :ref:`vmw-player` - - Visit :ref:`image-types` to learn more about all available images. - -Install steps: - -.. contents:: :local: - :depth: 1 + VMware also offers a type 2 hypervisor designed for the desktop environment, + called `VMware Workstation Player`_. Refer to :ref:`vmw-player-preconf` or + :ref:`vmw-player` for more information. + Visit :ref:`image-types` to learn more about all available images. Download the latest |CL| installer ISO ************************************** diff --git a/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst b/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst index 71f10066..373c545f 100644 --- a/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst +++ b/source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst @@ -3,36 +3,37 @@ Run preconfigured |CL-ATTR| image as a VMware\* ESXi guest OS ############################################################# +This page explains how to deploy a preconfigured |CL| VMware +:abbr:`VM (Virtual Machine)` image on a VMware ESXi 6.5 host. + +.. contents:: + :local: + :depth: 1 + +Overview +******** + `VMware ESXi`_ is a type 1 bare-metal hypervisor which runs directly on top of server hardware. With VMware ESXi, you can create, configure, manage, and run |CL-ATTR| virtual machines at scale. -This section shows you how to deploy a preconfigured |CL| VMware -:abbr:`VM (Virtual Machine)` image on a VMware ESXi 6.5 host. +We provide a preconfigured |CL| VMware image that can be run on a VMware ESXi +6.5 host. -If you would prefer to perform a manual installation of |CL| into a new -VMware ESXi :abbr:`VM (Virtual Machine)` instead, see -:ref:`vmware-esxi-install-cl`. +If manuall installation is preferred, refer to :ref:`vmware-esxi-install-cl`. .. note:: - VMware also offers a type 2 hypervisor called `VMware Workstation Player` - which is designed for the desktop environment. - - See :ref:`vmw-player-preconf` or see :ref:`vmw-player`. - - -Install steps: - -.. contents:: :local: - :depth: 1 + VMware also offers a type 2 hypervisor designed for the desktop environment, + called `VMware Workstation Player`_. Refer to :ref:`vmw-player-preconf` or + :ref:`vmw-player` for more information. Download the latest |CL| VMware image ************************************* Get the latest |CL| VMware prebuilt image from the `image`_ repository. Look for :file:`clear-[version number]-vmware.vmdk.xz`. You can also use -this command: +this command: .. code-block:: bash diff --git a/source/guides/kernel/kernel-development.rst b/source/guides/kernel/kernel-development.rst index 9dbbaaaf..cab3e0a5 100644 --- a/source/guides/kernel/kernel-development.rst +++ b/source/guides/kernel/kernel-development.rst @@ -3,29 +3,30 @@ Kernel development ################## -This document shows how to obtain and compile a Linux* kernel source +This guide shows how to obtain and compile a Linux* kernel source using |CL-ATTR| development tooling. -The `kernels available`_ in |CL| aim to be performant and practical. In some -cases, it may be necessary to modify the kernel to suit your specific needs -or test new kernel code as a developer. +The :ref:`compatible-kernels` available in |CL| aim to be performant and +practical. In some cases, it may be necessary to modify the kernel to suit your +specific needs or test new kernel code as a developer. .. contents:: :local: :depth: 1 :backlinks: top -Source RPM files (SRPM) are also available for all |CL| kernels, and can be -used for development instead. Select this link to view the latest `source RPM files`_. +`Source RPMs (SRPMS)`_ are also available for all |CL| kernels, and can be +used for development instead. Request changes be included with the |CL| kernel ************************************************ If the kernel modification you need is already open source and likely to be useful to others, consider submitting a request to include it in the -|CL| kernels.If your change request is accepted, you do not need to maintain your own modified kernel. +|CL| kernels.If your change request is accepted, you do not need to maintain +your own modified kernel. -Make enhancement requests to the |CL| `distribution on GitHub`_ . +Make enhancement requests to the |CL| `Distribution Project`_ on GitHub. Set up kernel development environment ************************************* @@ -56,7 +57,7 @@ Clone the existing kernel package repository from |CL| as a starting point. #. Clone the Linux kernel package from |CL|. Using the :command:`make clone_` command in the :file:`clearlinux/` directory clones the package from the - `clearlinux-pkgs GitHub`_. + `clearlinux-pkgs`_ repo on GitHub. .. code-block:: bash @@ -73,7 +74,7 @@ Clone the existing kernel package repository from |CL| as a starting point. The "linux" package is the kernel that comes with |CL| in the `kernel-native` bundle. Alternatively, you can use a different kernel variant as the base for modification. For a list of kernel package names which you can clone instead, -see the `clearlinux-pkgs GitHub`_. +see the `clearlinux-pkgs`_ repo on GitHub. .. note:: @@ -261,7 +262,7 @@ consider using a patch management tool in addition to Git such as #. Generate a patch file based on your git commits. represents the number of local commits to create patch file. - See the `git-format-patch Documentation`_ for detailed information + See the `git-format-patch`_ documentation for detailed information on using :command:`git format-patch` .. code-block:: bash @@ -355,7 +356,7 @@ are persistent and distributed with a customized kernel. #. Commit and save the changes to the :file:`cmdline` file. -See the `Kernel parameters documentation`_ for a list of available +See the `kernel parameters`_ documentation for a list of available parameters. Build and install the kernel @@ -374,7 +375,9 @@ isolate building of packages in a sanitized workspace. make build .. note:: - The `ccache plugin for mock`_ can be enabled to help speed up any future rebuilds of the kernel package by caching compiler outputs and reusing them. + The mock plugin `ccache`_ can be enabled to help speed up any future + rebuilds of the kernel package by caching compiler outputs and reusing + them. #. The result will be multiple :file:`.rpm` files in the :file:`rpms` @@ -426,22 +429,18 @@ Related topics * :ref:`kernel-modules` * :ref:`mixer` -.. _kernels available: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels +.. _Distribution Project: https://github.com/clearlinux/distribution/issues/new/choose -.. _distribution on GitHub: https://github.com/clearlinux/distribution/issues/new/choose - -.. _source RPM files: https://cdn.download.clearlinux.org/current/source/SRPMS/ +.. _Source RPMs (SRPMS): https://cdn.download.clearlinux.org/current/source/SRPMS/ .. _Quilt: http://savannah.nongnu.org/projects/quilt -.. _clearlinux-pkgs GitHub: https://github.com/clearlinux-pkgs +.. _clearlinux-pkgs: https://github.com/clearlinux-pkgs .. _kernel.org: https://www.kernel.org/ -.. _Kernel parameters documentation: https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt +.. _kernel parameters: https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt -.. _ccache plugin for mock: https://fedoraproject.org/wiki/Mock/Plugin/CCache?rd=Subprojects/Mock/Plugin/CCache +.. _ccache: https://fedoraproject.org/wiki/Mock/Plugin/CCache?rd=Subprojects/Mock/Plugin/CCache -.. _git-format-patch Documentation: https://git-scm.com/docs/git-format-patch - -.. _user-setup script: https://github.com/clearlinux/common/blob/master/user-setup.sh \ No newline at end of file +.. _git-format-patch: https://git-scm.com/docs/git-format-patch diff --git a/source/guides/kernel/kernel-modules-dkms.rst b/source/guides/kernel/kernel-modules-dkms.rst index 8c8ca6ad..524a5c66 100644 --- a/source/guides/kernel/kernel-modules-dkms.rst +++ b/source/guides/kernel/kernel-modules-dkms.rst @@ -8,12 +8,10 @@ kernel modules that are not part of the Linux source tree, you may need to build out-of-tree kernel modules. Use this guide to add kernel modules with :abbr:`DKMS (Dynamic Kernel Module System)` or refer to :ref:`kernel-modules`. - .. contents:: :local: :depth: 1 :backlinks: top - Description *********** @@ -110,7 +108,7 @@ Build, install, and load an out-of-tree module Follow the steps in this section if you are an individual user or testing, and you need an out-of-tree kernel module that is not available through |CL|. For a more scalable and customizable approach, we recommend using the -`mixer tool`_ to provide a custom kernel and updates. +:ref:`mixer` tool to provide a custom kernel and updates. Prerequisites @@ -218,10 +216,10 @@ Here are some additional resources that can be used for reference: * DKMS manual page (:command:`man dkms`) shows detailed syntax in the DKMS.CONF section. -* `Ubuntu community wiki`_ shows an example where a single package contains - multiple modules. +* Ubuntu community wiki entry for the `Kernel DKMS Package`_ shows an example + where a single package contains multiple modules. -* `Sample dkms.conf file`_ in the GitHub\* repository for the DKMS project. +* Sample `dkms.conf`_ file in the GitHub\* repository for the DKMS project. .. note:: @@ -315,20 +313,14 @@ Examples Related topics ************** -* `Dynamic Kernel Module System (DKMS) project on GitHub `_ +* `Dynamic Kernel Module System (DKMS)`_ * `Dell Linux Engineering Dynamic Kernel Module Support: From Theory to Practice `_ * `Linux Journal: Exploring Dynamic Kernel Module Support `_ +.. _Dynamic Kernel Module System (DKMS): https://github.com/dell/dkms -.. _`on GitHub`: https://github.com/clearlinux/distribution - -.. _`mixer tool`: https://clearlinux.org/features/mixer-tool - -.. _`Dynamic Kernel Module System (DKMS)`: https://github.com/dell/dkms - -.. _Ubuntu community wiki: https://help.ubuntu.com/community/Kernel/DkmsDriverPackage#Configure_DKMS - -.. _Sample dkms.conf file: https://github.com/dell/dkms/blob/master/sample.conf +.. _Kernel DKMS Package: https://help.ubuntu.com/community/Kernel/DkmsDriverPackage#Configure_DKMS +.. _dkms.conf: https://github.com/dell/dkms/blob/master/sample.conf diff --git a/source/guides/kernel/kernel-modules.rst b/source/guides/kernel/kernel-modules.rst index 357bc405..74c4cdc3 100644 --- a/source/guides/kernel/kernel-modules.rst +++ b/source/guides/kernel/kernel-modules.rst @@ -56,7 +56,8 @@ If the kernel module you need is already open source (for example, in the Linux upstream) and likely to be useful to others, consider submitting a request to add or enable it in the |CL| kernel. -Make enhancement requests to the |CL| distribution `on GitHub`_. +Make enhancement requests to the |CL| +`Distribution Project `_ on GitHub. .. _kernel-modules-availability-end: @@ -67,7 +68,7 @@ Build, install, and load an out-of-tree module Follow the steps in this section if you are an individual user or testing, and you need an out-of-tree kernel module that is not available through |CL|. For a more scalable and customizable approach, we recommend using the -`mixer tool`_ to provide a custom kernel and updates. +:ref:`mixer` to provide a custom kernel and updates. Prerequisites @@ -216,6 +217,5 @@ Related topic * :ref:`kernel-modules-dkms` - .. _`on GitHub`: https://github.com/clearlinux/distribution -.. _`mixer tool`: https://clearlinux.org/features/mixer-tool + diff --git a/source/guides/maintenance/architect-lifecycle.rst b/source/guides/maintenance/architect-lifecycle.rst index bf9e8787..f166e542 100644 --- a/source/guides/maintenance/architect-lifecycle.rst +++ b/source/guides/maintenance/architect-lifecycle.rst @@ -38,7 +38,8 @@ Description Coordinated infrastructure is deployed to automate the life-cycle of your |CL| derivative. We divide deployment of this infrastucture in two -parts: *Content Workflow*; and *Release Workflow*, shown in Figure 1. Distro Factory manages the *Release Workflow* while capturing the requirements for +parts: *Content Workflow*; and *Release Workflow*, shown in Figure 1. Distro +Factory manages the *Release Workflow* while capturing the requirements for maintaining a long-term release cadence. .. figure:: figures/architect-lifecycle-1.png @@ -51,7 +52,12 @@ Content workflow **************** The *Content Workflow* (Figure 1) orchestrates the processes used to manage -the creation of content for the distribution. This includes everything from detecting a new release in a custom software repository to generating RPM package files. The RPM files serve as intermediary artifacts that track software dependencies and provide file-level data consumed in a *Release Workflow*. The `Watcher Pipeline`_ checks |CL| and a content provider, such as Koji, to determine if a new release is necessary. +the creation of content for the distribution. This includes everything from +detecting a new release in a custom software repository to generating RPM +package files. The RPM files serve as intermediary artifacts that track software +dependencies and provide file-level data consumed in a *Release Workflow*. The +`Watcher Pipeline`_ checks |CL| and a content provider, such as Koji, to +determine if a new release is necessary. Release workflow **************** @@ -67,9 +73,10 @@ new releases. Implementation ************** -Distro factory implements the *Release workflow*. To get started on a full implementation, visit |CL| `Distro factory documentation`_. +Distro factory implements the *Release workflow*. To get started on a full +implementation, visit |CL| `Distro Factory`_ documentation. -.. _Distro factory documentation: https://github.com/clearlinux/clr-distro-factory/wiki#clear-linux-distro-factory +.. _Distro Factory: https://github.com/clearlinux/clr-distro-factory/wiki#clear-linux-distro-factory .. _Release Pipeline: https://github.com/clearlinux/clr-distro-factory/wiki/Release diff --git a/source/guides/maintenance/bulk-provision.rst b/source/guides/maintenance/bulk-provision.rst index 6b52e760..9d3affc2 100644 --- a/source/guides/maintenance/bulk-provision.rst +++ b/source/guides/maintenance/bulk-provision.rst @@ -41,7 +41,7 @@ Configuration ============= #. Install **ICIS** by following the getting started guide on the - `ICIS GitHub repository`_. + `ICIS`_ GitHub repository. #. Create an Ister installation file and save it to the :file:`static/ister` directory within the web hosting directory for @@ -116,7 +116,7 @@ Configuration location of the Ister configuration file. #. Write a cloud-init document to customize the instance of the installation - according to your requirements. The `cloud-init Read the Docs`_ provides a + according to your requirements. The `cloud-init`_ documentation provides a guide on how to write a cloud-init document. The guide covers the customization options provided by cloud-init after an installation. @@ -158,8 +158,8 @@ Configuration **Congratulations!** You have successfully performed a bulk provision of |CL|. -.. _ICIS GitHub repository: +.. _ICIS: https://github.com/clearlinux/ister-cloud-init-svc -.. _cloud-init Read the Docs: +.. _cloud-init: https://cloudinit.readthedocs.io diff --git a/source/guides/maintenance/cpu-performance.rst b/source/guides/maintenance/cpu-performance.rst index 10eedb6e..3a400e3c 100644 --- a/source/guides/maintenance/cpu-performance.rst +++ b/source/guides/maintenance/cpu-performance.rst @@ -33,8 +33,8 @@ C-states aim to reduce power utilization by increasingly reducing clock frequency, voltages, and features in each state. Although C-states can typically be limited or disabled in a system's UEFI or -BIOS configuration, these settings are overridden when the `intel_idle -driver`_ is in use. +BIOS configuration, these settings are overridden when the `intel_idle driver`_ +is in use. To view the current cpuidle driver run this command in a terminal: @@ -48,7 +48,8 @@ or completely disabled with :command:`idle=poll`. .. note:: - * :command:`processor.max_cstate=0` is changed to :command:`processor.max_cstate=1` by the kernel to be a valid value. + * :command:`processor.max_cstate=0` is changed to :command:`processor.max_cstate=1` + by the kernel to be a valid value. * :command:`intel_idle.max_cstate=0` disables the Intel Idle driver, not set it to C-state 0. @@ -137,8 +138,8 @@ To change the CPU frequency scaling governor: echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor -The list of all governors can be found in the `Linux kernel documentation on -CPUFreq Governors`_. +The list of all governors can be found in the Linux kernel documentation on +`CPUFreq Governors`_. .. note:: @@ -185,7 +186,7 @@ bundle and add your user account to the power group: .. _`Intel P-state driver`: https://www.kernel.org/doc/Documentation/cpu-freq/intel-pstate.txt -.. _`Linux kernel documentation on CPUFreq Governors`: https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt +.. _`CPUFreq Governors`: https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt .. _thermald: https://01.org/linux-thermal-daemon diff --git a/source/guides/maintenance/developer-workstation.rst b/source/guides/maintenance/developer-workstation.rst index 765c44c3..0e6e1a32 100644 --- a/source/guides/maintenance/developer-workstation.rst +++ b/source/guides/maintenance/developer-workstation.rst @@ -24,7 +24,8 @@ responds to this need. Use Table 1, *Developer Profiles*, to identify the *minimum required bundles* to get started developing based on your role or project. -While your role may not neatly fit in one of these categories, consider using Table 1 as a starting point. +While your role may not neatly fit in one of these categories, consider using +Table 1 as a starting point. .. list-table:: **Table 1. Developer Profiles** :widths: 20, 20, 20, 20 @@ -102,8 +103,8 @@ Other resources for developers ----------------------------------- * `Developer Tooling Framework`_ for |CL| -* `Bundle definition files`_ +* `Bundle Definition Files`_ -.. _Bundle definition files: https://github.com/clearlinux/clr-bundles +.. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles .. _Developer Tooling Framework: https://github.com/clearlinux/common diff --git a/source/guides/maintenance/enable-user-space.rst b/source/guides/maintenance/enable-user-space.rst index 1ed1fcb1..0c1fc9e7 100644 --- a/source/guides/maintenance/enable-user-space.rst +++ b/source/guides/maintenance/enable-user-space.rst @@ -52,7 +52,8 @@ To be able to execute all applications with root privileges, add the Install and update the OS software to its current version ********************************************************* -The |CL| software utility :ref:`swupd ` allows you to perform system updates while reaping the benefits of upstream development. +The |CL| software utility :ref:`swupd ` allows you to perform +system updates while reaping the benefits of upstream development. To update your newly installed OS, run: @@ -69,13 +70,15 @@ to running :command:`apt-get` or :command:`yum install` for package management. Yet |CL| manages packages at the level of bundles, which are integrated stacks of packages. -For example, the `sysadmin-basic` bundle installs the majority of applications useful to a system administrator. To install it, enter: +For example, the `sysadmin-basic` bundle installs the majority of applications +useful to a system administrator. To install it, enter: .. code-block:: bash swupd bundle-add sysadmin-basic -View a full list of bundles and packages installed with the `sysadmin-basic`_ bundle. You can also view `all bundles`_ for |CL|, active or deprecated. +View a full list of bundles and packages installed with the `sysadmin-basic`_ +bundle. You can also view all `bundles`_ for |CL|, active or deprecated. Expand your knowledge of :command:`swupd` and check out our developer resources: @@ -93,7 +96,7 @@ Check out our guides and tutorials. .. _`sysadmin-basic`: https://github.com/clearlinux/clr-bundles/blob/master/bundles/sysadmin-basic -.. _`all bundles`: +.. _`bundles`: https://github.com/clearlinux/clr-bundles/tree/master/bundles .. _`wheel group`: diff --git a/source/reference/compatible-kernels.rst b/source/reference/compatible-kernels.rst new file mode 100644 index 00000000..d2a6b929 --- /dev/null +++ b/source/reference/compatible-kernels.rst @@ -0,0 +1,87 @@ +.. _compatible-kernels: + +Compatible kernels +################## + +The |CL-ATTR| provides the following Linux kernels with a respective bundle. +This document describes the specific use cases these `bundles`_ serve +and provides links to their source code. + +Kernel native +============= + +The *kernel-native* bundle focuses on the bare metal platforms. It is optimized +for fast booting and performs best on the Intel® architectures described on the +:ref:`supported hardware list`. + +The optimization patches are found in the `Linux`_ GitHub\* repo. + +.. _vm-kernels: + +Kernel LTS +========== + +The *kernel-lts* bundle focuses on the bare metal platforms but uses the 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`. This kernel also includes +the VirtualBox\* kernel modules. See the +:ref:`instructions on using Virtualbox` for more +information. + +The optimization patches are found in the `Linux-LTS`_ GitHub repo. + +Kernel KVM +========== + +The *kernel-kvm* bundle focuses on the Linux +:abbr:`KVM (Kernel-based Virtual Machine)`. It is optimized for fast booting +and performs best on virtual machines running on the Intel® architectures +described in the :ref:`supported hardware list`. +Use this kernel when running |CL| as the guest OS on top of *qemu/kvm* or with +**cloud orchestrators** using *qemu/kvm* internally as +their **hypervisor**. This kernel can be used as a standalone |CL| VM. See +the :ref:`instructions on using KVM` for more information. + +The optimization patches are found in the `Linux-KVM`_ GitHub repo. + +Kernel Hyper-V\* +================ + +The *kernel-hyperv* bundle focuses on running Linux on Microsoft\* +Hyper-V. It is optimized for fast booting and performs best on Virtual +Machines running on the Intel® architectures described on the +:ref:`supported hardware list`. +Use this kernel when running |CL| as the guest OS of **Cloud Instances** in +projects such as Microsoft `Azure`_\*. This kernel can be used in a +standalone |CL| VM. See the :ref:`instructions on using Hyper-V` for +more information. + +The optimization patches are found in the `Linux-HyperV`_ GitHub repo. + +Kernel Hyper-V LTS +================== + +The *kernel-hyperv-lts* bundle focuses on running Linux on Microsoft +Hyper-V but uses the latest :abbr:`LTS (Long Term Support)` Linux kernel. It +is optimized for fast booting and performs best on virtual machines running on +the Intel® architectures described on the +:ref:`supported hardware list`. Use this kernel when +running |CL| as the guest OS of **Cloud Instances** in projects such as +Microsoft `Azure`_. This kernel can be used in a standalone |CL| VM. See our +:ref:`instructions on using Hyper-V` for more information. + +The optimization patches are found in the `Linux-HyperV-LTS`_ GitHub repo. + + +.. _Linux: https://github.com/clearlinux-pkgs/linux +.. _Linux-LTS: https://github.com/clearlinux-pkgs/linux-lts +.. _Linux-KVM: https://github.com/clearlinux-pkgs/linux-kvm +.. _Linux-HyperV: https://github.com/clearlinux-pkgs/linux-hyperv +.. _Linux-HyperV-LTS: https://github.com/clearlinux-pkgs/linux-hyperv-lts +.. _Linux-Container: https://github.com/clearlinux-pkgs/linux-container +.. _bundles: https://github.com/clearlinux/clr-bundles +.. _CIAO: https://github.com/01org/ciao +.. _Azure: + https://azuremarketplace.microsoft.com/en-us/marketplace/apps/clear-linux-project.clear-linux-os + diff --git a/source/reference/system-requirements.rst b/source/reference/system-requirements.rst index 3c3a13da..415e0f06 100644 --- a/source/reference/system-requirements.rst +++ b/source/reference/system-requirements.rst @@ -4,7 +4,7 @@ Recommended minimum system requirements ####################################### |CL-ATTR| can run on most modern hardware and is capable of running with -modest hardware resources. Out of the box |CL| can run on a single CPU core, 1 +modest hardware resources. Out of the box, |CL| can run on a single CPU core, 1 GB RAM, and 2 GB of disk space. For use cases requiring minimal resources, |CL| :ref:`tooling ` can @@ -29,7 +29,7 @@ System requirements ******************* |CL| requires an x86 64-bit processor which supports Intel® Streaming SIMD -Extensions 4.1 (Intel® SSE 4.1), and it requires a system that supports UEFI\*. +Extensions 4.1 (Intel® SSE 4.1), and it requires a system that supports UEFI. The |CL| installer performs a system compatibility check upon booting. To manually verify system compatibility with |CL|, run the :ref:`compatibility @@ -54,8 +54,8 @@ The following processor families have been verified to run |CL|: * Intel® Xeon® E3-xxxx processor * Intel® Xeon® E5-xxxx processor * Intel® Xeon® E7-xxxx processor -* Intel® Atom® Processors C Series -* Intel® Atom® Processors E Series +* Intel® Atom® processor C Series +* Intel® Atom® processor E Series Recommended configurations diff --git a/source/tutorials/dars.rst b/source/tutorials/dars.rst index f0baa10a..a134c938 100644 --- a/source/tutorials/dars.rst +++ b/source/tutorials/dars.rst @@ -28,6 +28,10 @@ We recommend you view the latest component versions for each image in the distribution, the package version numbers in the |CL|-based containers may not be the latest released by |CL|. +.. note:: + + The Data Analytics Reference Stack is a collective work, and each piece of software within the work has its own license. Please see the `terms of use`_ for more details about licensing and usage of the Data Analytics Reference Stack. + Using the Docker Images @@ -104,3 +108,4 @@ provided :file:`Dockerfile`. .. _DARS with OpenBLAS: https://hub.docker.com/r/clearlinux/stacks-dars-openblas/ .. _DARS with MKL: https://hub.docker.com/r/clearlinux/stacks-dars-mkl/ .. _DARS architecture and performance benchmarks: https://clearlinux.org/stacks/data-analytics-stack-v1 +.. _terms of use: https://clearlinux.org/stacks/data-analytics/terms-of-use