Merge pull request #242 from krisdale/kd-bare-metal-reorg

Get Started - bare metal org clean up
2026-07-07 21:25:48 +00:00 · 2018-09-27 14:17:09 -07:00
parent 0b961155d5 777af9aa97
commit 2f1ba1f36e
51 changed files with 250 additions and 258 deletions
@@ -1,16 +1,19 @@
 .. _bare-metal-install:

-Install Clear Linux OS on bare metal (automatic)
-################################################
+Install |CL-ATTR| on bare metal (automatic)
+###########################################

-These instructions guide you through the installation of |CLOSIA|
+These instructions guide you through the installation of |CL-ATTR|
 on bare metal using a bootable USB drive.

-Before you begin, run our :ref:`compatibility-check`.
+Before you begin, check that your system meets the requirements to install |CL|: 
+
+* :ref:`system-requirements` 
+* :ref:`compatibility-check`


-Download the latest Clear Linux installer image
-***********************************************
+Download the latest |CL| installer image
+****************************************

 Get the latest |CL| installer image from the `image`_ directory.
 Look for the :file:`clear-[version number]-installer.img.xz` file. You can also use this command:
@@ -31,8 +34,8 @@ Once you have downloaded the image, verify and uncompress the file.

 .. _install-on-target:

-Install Clear Linux on your target system
-*****************************************
+Install |CL| on your target system
+**********************************

 We formatted the previously created USB drive as a UEFI boot device. Our
 target system has a hard drive installed containing a single primary
@@ -54,25 +57,24 @@ Follow these steps to install |CL| on the target system:

 #. Reboot the target system.

-#. The |CL| Installer menu will start as shown in Figure 1.
+#. The |CL| boot menu will start as shown in figure 1.
   Select :guilabel:`Clear Linux OS for Intel Architecture` and press the
   :kbd:`Enter` key or wait five seconds to automatically select it.

   .. figure:: figures/bare-metal-install-1.png
      :scale: 50 %
-      :alt: Clear Linux boot menu
+      :alt: Boot menu

-      Figure 1: :guilabel:`Clear Linux boot menu`
+      Figure 1: :guilabel:`Boot menu`

-#. This will take you into the :guilabel:`Clear Linux OS for Intel
-   Architecture Installer` menu as shown in figure 2 and explains how to
+#. This will take you into the |CL| installer menu as shown in figure 2 and explains how to
   navigate through the |CL| installer setup menus.

   .. figure:: figures/bare-metal-install-2.png
      :scale: 50 %
-      :alt: Clear Linux OS for Intel Architecture Installer
+      :alt: Installer menu

-      Figure 2: :guilabel:`Clear Linux OS for Intel Architecture Installer`
+      Figure 2: :guilabel:`Installer menu`

   Press the :kbd:`Enter` key.

@@ -97,7 +99,7 @@ The :guilabel:`Network Requirements` menu, the first step of the |CL|
 installer setup process, will attempt to connect to the |CL| update server
 where the installer image is located. Once the connection to the |CL| update
 server is established, you will see a screen similar to the one shown in
-figure 4:
+figure 4.

 .. figure:: figures/bare-metal-install-4.png
   :scale: 50 %
@@ -134,11 +136,11 @@ Once the connection to the |CL| udpate server is established, use the
 :kbd:`Tab` key to advance to the :guilabel:`< Next >` button and press
 :kbd:`Enter` to advance to the next |CL| installer setup menu.

-Choose Clear Linux installer action
-===================================
+Choose |CL| installer action
+============================

 The :guilabel:`Choose Action` menu is where you can choose to install, repair,
-open a shell, or exit the |CL| installer.  This menu is shown in figure 5:
+open a shell, or exit the |CL| installer.  This menu is shown in figure 5.

 .. figure:: figures/bare-metal-install-5.png
   :scale: 50 %
@@ -181,8 +183,8 @@ open a shell, or exit the |CL| installer.  This menu is shown in figure 5:
   information is collected. Please visit our website to
   `learn more about telemetry.`_

-Choose Clear Linux installation type
-************************************
+Choose |CL| installation type
+*****************************

 Figure 7 shows the next step of the |CL| installer:
 :guilabel:`Choose installation Type`. Chose whether to install |CL|
@@ -216,8 +218,8 @@ If you want to perform any of these additional tasks, select the
 :ref:`bare-metal-manual-install` to complete the |CL| manual installation
 process. Otherwise, you can follow the |CL| automatic installation steps.

-Clear Linux automatic installation
-**********************************
+|CL| automatic installation
+***************************

 #. To install the minimum components for your |CL| implementation, select the
   :guilabel:`< Automatic >` menu item shown in figure 7 and press the
@@ -279,7 +281,7 @@ Set up your root account
 ========================

 Once the |CL| installation is complete and the system boots, a full screen
-console requests your login: as shown in figure 12:
+console requests your login as shown in figure 12:

 .. figure:: figures/bare-metal-install-12.png
   :scale: 50 %
@@ -300,18 +302,15 @@ You have now set your root password and are logged in with root privileges.
 You have successfully installed |CL| on a bare metal system using the
 automatic installation method and set the password for the ``root`` user.

-The automatic installation of |CL| is designed to install with minimal
-software overhead. Therefore, some housekeeping and package installations
-could be needed before you can take full advantage of the |CL| operating
-system. These instructions are captured in the :ref:`enable-user-space`.
+Next steps
+**********

-* Create a new user
-* Update the OS to its most current version using `swupd`.
-* Install the most common applications for system administrators and
-  developers using bundles.
-* Setup a new user.
-* Setup `sudo` privileges for that new user.
-* Install a GUI using those `sudo` privileges.
+The automatic installation of |CL| is designed to install with minimal
+software overhead. Some housekeeping and package installations could be 
+needed before you can take full advantage of the |CL| operating system. 
+
+See the :ref:`enable-user-space` guide for additional information and
+instructions.


 .. _`information about stateless`:
@@ -1,9 +1,9 @@
 .. _bootable-usb-linux:

-Create a bootable USB drive on Linux
-####################################
+Create a bootable USB drive on Linux\*
+######################################

-Follow these instructions to create a bootable |CLOSIA| USB drive.
+Follow these instructions to create a bootable |CL-ATTR| USB drive.
 Use an **8GB** or larger USB drive. Download either a live image, 
 ``clear-<version>-live.img.xz`` or an installer image, 
 ``clear-<version>-installer.img.xz``, from our `image`_ download page. 
@@ -22,8 +22,8 @@ Instructions are also available for other operating systems:

 .. _copy-usb-linux:

-Burn the Clear Linux image onto a USB drive
-*******************************************
+Burn the |CL| image onto a USB drive
+************************************

 .. caution::

@@ -3,7 +3,7 @@
 Create a bootable USB drive on macOS
 ####################################

-Follow these instructions to create a bootable |CLOSIA| USB drive.
+Follow these instructions to create a bootable |CL-ATTR| USB drive.
 Use an **8GB** or larger USB drive. Download either a live image, 
 ``clear-<version>-live.img.xz`` or an installer image, 
 ``clear-<version>-installer.img.xz``, from our `image`_ download page. 
@@ -21,8 +21,8 @@ Instructions are also available for other operating systems:
   :start-after: verify-mac:


-Burn the Clear Linux image onto a USB drive
-*******************************************
+Burn the |CL| image onto a USB drive
+************************************

 .. caution::

@@ -35,7 +35,7 @@ Burn the Clear Linux image onto a USB drive

   .. code-block:: console

-      $ diskutil list
+      diskutil list

   .. figure:: figures/bootable-usb-mac-1.png
      :scale: 100 %
@@ -48,14 +48,14 @@ Burn the Clear Linux image onto a USB drive

   .. code-block:: console

-      $ diskutil umountDisk /dev/disk2
+      diskutil umountDisk /dev/disk2

 #. Burn the image onto the drive using the :command:`dd` command.  The 
   command-line example below burns an uncompressed image onto `/dev/disk2`:

   .. code-block:: console

-      $ sudo dd if=./clear-[version number]-[image type] of=/dev/rdisk2 bs=4m
+      sudo dd if=./clear-[version number]-[image type] of=/dev/rdisk2 bs=4m


   Adding an ‘r’ in front of the disk identifier should help speed up the 
@@ -67,7 +67,7 @@ Burn the Clear Linux image onto a USB drive

   .. code-block:: console

-      $ diskutil eject /dev/disk2
+      diskutil eject /dev/disk2

 Next steps
 **********
@@ -1,9 +1,9 @@
 .. _bootable-usb-windows:

-Create a bootable USB drive on Windows
-######################################
+Create a bootable USB drive on Windows\*
+########################################

-Follow these instructions to create a bootable |CLOSIA| USB drive.
+Follow these instructions to create a bootable |CL-ATTR| USB drive.
 Use an **8GB** or larger USB drive. Download either a live image, 
 ``clear-<version>-live.img.xz`` or an installer image, 
 ``clear-<version>-installer.img.xz``, from our `image`_ download page.
@@ -20,8 +20,8 @@ Instructions are also available for other operating systems:
 .. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst
   :Start-after: verify-windows:

-Burn the Clear Linux image onto a USB drive
-*******************************************
+Burn the |CL| image onto a USB drive
+************************************

 .. caution::

@@ -1,23 +1,23 @@
 .. _bootable-usb:

-Create a bootable Clear Linux USB drive
-#######################################
+Create a bootable |CL-ATTR| USB drive
+#####################################

-Instructions to create a |CLOSIA| USB drive vary depending on your operating
+Instructions to create a |CL-ATTR| USB drive vary depending on your operating
 system.

 .. _download-usb-image:

-Download the latest Clear Linux image
-*************************************
+Download the latest |CL| image
+******************************

 There are 2 types of |CL| images suitable for burning onto and running
 off a USB drive:

-   * Live image: :file:`clear-[version number]-live.img.xz`
-   * Installer image: :file:`clear-[version number]-installer.img.xz`
+* Live image: :file:`clear-[version number]-live.img.xz`
+* Installer image: :file:`clear-[version number]-installer.img.xz`

-Go to the Clear Linux `image`_ repository and download the desired type.
+Go to the |CL| `image`_ repository and download the desired type.

 With the appropriate image downloaded, choose the step-by-step instructions
 applicable to your system:
@@ -1,11 +1,11 @@
 .. _cgdisk-manual-install:

-Create partitions for Clear Linux\* using CGDISK
-################################################
+Create partitions for |CL-ATTR| using CGDISK
+############################################

-As part of the |CL| manual installation processThese instructions guide you through the initial setup of your hard drive
-partitions using the :command:`cgdisk` utility . If you do not wish to continue creating your own
-partitions, :ref:`return to the bare metal manual installation
+These instructions guide you through the initial setup of your hard drive
+partitions using the :command:`cgdisk` utility . If you do not wish to continue 
+creating your own partitions, :ref:`return to the bare metal manual installation
 <bare-metal-manual-install>`.

 Prerequisites
@@ -67,7 +67,7 @@ installation.

      Figure 4: :guilabel:`cgdisk`

-Linux Partition setup
+Linux partition setup
 *********************

 In order to properly set up the |CL| partitioning scheme, we create three
@@ -173,7 +173,7 @@ about it, review `Rod Smith's Partitioning advice about alignment`_.
      Figure 9: :guilabel:`cgdisk - swap partition defined`

 Create the Linux filesystem partition
-*************************************
+=====================================

 Lastly, we must create the the Linux filesystem partition to use it as the
 root mount point for you |CL| installation.
@@ -278,7 +278,7 @@ partitions and select to format them.
   
   You have completed the process of manually partitioning your target
   system. Now, :ref:`return to the bare metal manual installation 
-   <bare-metal-manual-install>` to complete installation of Clear Linux.
+   <bare-metal-manual-install>` to complete installation of |CL|.
   Continue at the section *Additional manual installer settings*.

 .. _`GPT fdisk tutorial`:
@@ -1,11 +1,11 @@
 .. _compatibility-check:

-Check processor and EFI firmware compatibility with Clear Linux\*
-#################################################################
+Check processor and EFI firmware compatibility with |CL-ATTR|
+#############################################################

-On a system that is currently running a Linux operating system, follow the
+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 |CLOSIA|. Otherwise,
+capable of running |CL-ATTR|. Otherwise,
 :ref:`run Clear Linux as a Live image <live-image>` and then perform the steps
 below.

@@ -19,13 +19,13 @@ below.

   .. code-block:: console

-      $ curl -O https://download.clearlinux.org/current/clear-linux-check-config.sh
+      curl -O https://download.clearlinux.org/current/clear-linux-check-config.sh

 #. Make the script executable.

   .. code-block:: console

-      $ chmod +x clear-linux-check-config.sh
+      chmod +x clear-linux-check-config.sh

 #. Run the script.

@@ -34,13 +34,13 @@ below.

      .. code-block:: console

-         $ ./clear-linux-check-config.sh host
+         ./clear-linux-check-config.sh host

   #. Check to see if the host is capable of running |CL| in a container.

      .. code-block:: console

-         $ ./clear-linux-check-config.sh container
+         ./clear-linux-check-config.sh container

   The script will print a list of test results similar to the output below.
   All items should return a `SUCCESS` status. This example indicates the
@@ -3,21 +3,33 @@
 Get started
 ###########

-This section contains information about the installation of |CLOSIA|.
+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 installation of |CL| 
+from bare metal to a live image.
+ 
+Pre-install
+***********
+
+* :ref:`system-requirements` 
+* :ref:`compatibility-check`
+* :ref:`bootable-usb` 
+
+Install |CL| 
+************
+
+* :ref:`bare-metal-install` 
+* :ref:`bare-metal-manual-install`
+* :ref:`virtual-machine-install`
+* :ref:`live-image`

-The :ref:`get-started` section provides step-by-step instructions to download
-and run |CL| on :ref:`bare metal <bare-metal-install>`, under
-a :ref:`virtual machine <virtual-machine-install>`, or by way of a
-:ref:`live image <live-image>`. Additionally, it provides useful pre-install
-information and instructions on how to complete pre-install tasks.

 .. toctree::
   :maxdepth: 2
+   :hidden:

-   ../reference/system-requirements
   bare-metal-install/bare-metal-install
-   bare-metal-install/bare-metal-manual-install
-   bare-metal-install/cgdisk-manual-install
+   bare-metal-manual-install/bare-metal-manual-install
+   cgdisk-manual-install/cgdisk-manual-install
   virtual-machine-install/virtual-machine-install
   live-image
   compatibility-check
@@ -1,12 +1,12 @@
 .. _live-image:

-Install Clear Linux as a live image
-###################################
+Install |CL-ATTR| as a live image
+#################################

-A live image contains the complete |CLOSIA| operating system and resides
+A live image contains the complete |CL-ATTR| operating system and resides
 on a bootable media such as a USB drive or in a virtual machine
-(see :ref:`virtual-machine-install`). This is a
-great way to use |CL| without modifying your computer's hard disk.
+(see :ref:`virtual-machine-install`). This is a great way to use |CL| 
+without modifying your computer's hard disk.

 To create a bootable USB drive with a live image, follow
 :ref:`our step-by-step instructions<bootable-usb>` and use the latest |CL|
@@ -15,8 +15,8 @@ live image from the `image`_ directory. Look for the

 .. _boot-live-image:

-Boot the Clear Linux live image
-*******************************
+Boot the |CL| live image
+************************

 #. Configure the BIOS/UEFI firmware settings of the target system:

@@ -3,7 +3,7 @@
 Use Hyper-V\*
 #############

-This section explains how to run |CLOSIA| inside a
+This section explains how to run |CL-ATTR| inside a
 `Windows Server Virtualization`_\* or **Hyper-V** environment.

 Please ensure you have enabled `Intel® Virtualization Technology
@@ -13,13 +13,13 @@ Please ensure you have enabled `Intel® Virtualization Technology
 (Intel® VT-d) in your BIOS/UEFI firmware configuration.

 Enable Hyper-V
-==============
+**************

 Please refer to the `Microsoft documentation`_ to enable and configure
 *Hyper-V* on your machine.

 Create a virtual network
-========================
+************************

 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
@@ -27,11 +27,11 @@ create a virtual network in the **Hyper-V Manager**.  Refer to the
 a virtual network.

 Create a virtual machine
-========================
+************************

 #. Download and uncompress the latest hyperv disk image
   :file:`clear-XXXXX-hyperv.img.gz`, where XXXXX is the latest 
-   available version of |CLOSIA| from our `downloads`_ section.
+   available version of |CL| from our `downloads`_ section.

 #. Create a virtual machine using the **Hyper-V Manager**:

@@ -41,7 +41,7 @@ Create a virtual machine
   c. When finished, open VM settings, select Firmware Section and in Secure
      Boot config, **uncheck** Enable Secure Boot.

-   .. note:: Currently, Clear Linux does not boot with `secure boot`
+   .. note:: Currently, |CL| does not boot with `secure boot`
      enabled.

 #. Connect to your new VM and start it. You should see a prompt:
@@ -52,7 +52,7 @@ Create a virtual machine

 #. Set a root user password.

-Your virtual machine running |CLOSIA| is ready!
+Your virtual machine running |CL| is ready!

 .. _Windows Server Virtualization: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/
 .. _Microsoft documentation: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v
@@ -1,13 +1,13 @@
 .. _kvm:

-Run Clear Linux as a KVM guest OS
-#################################
+Run |CL-ATTR| as a KVM guest OS
+###############################

-This section explains how to run |CLOSIA| in a virtualized environment using
+This section explains how to run |CL-ATTR| in a virtualized environment using
 :abbr:`KVM (Kernel-based Virtual Machine)`.

 Install QEMU-KVM
-================
+****************

 #. Enable the `Intel® Virtualization Technology`_ (Intel® VT) and the
   `Intel®Virtualization Technology for Directed I/O`_ (Intel® VT-d) in the
@@ -16,38 +16,38 @@ Install QEMU-KVM
 #. Log in, open a terminal emulator, and get root privilege on the host
   machine:

-   .. code-block:: console
+   .. code-block:: bash

-    $ sudo -s
+      sudo -s

 #. Install `QEMU*-KVM` on the host machine. Below are some example distros.

   * On |CL|:

-     .. code-block:: console
+     .. code-block:: bash

-        # swupd bundle-add desktop-autostart kvm-host
+        swupd bundle-add desktop-autostart kvm-host

   * On Ubuntu\* 16.04 LTS Desktop:

-     .. code-block:: console
+     .. code-block:: bash

-        # apt-get install qemu-kvm
+        apt-get install qemu-kvm

   * On Mint\* 18.1 “Serena” Desktop:

-     .. code-block:: console
+     .. code-block:: bash

-        # apt-get install qemu-kvm
+        apt-get install qemu-kvm

   * On Fedora\* 25 Workstation:

-     .. code-block:: console
+     .. code-block:: bash

-        # dnf install qemu-kvm
+        dnf install qemu-kvm

 Download and launch the virtual machine
-=======================================
+***************************************

 #. Download the latest pre-built |CL| KVM image file from
   the `image <https://download.clearlinux.org/image/>`_ directory. Look for
@@ -59,9 +59,9 @@ Download and launch the virtual machine

 #. Uncompress the downloaded image:

-   .. code-block:: console
+   .. code-block:: bash

-      # unxz clear-<version>-kvm.img.xz
+      unxz clear-<version>-kvm.img.xz

 #. Download the `OVMF file`_ file that provides UEFI support for
   virtual machines from the `image <https://download.clearlinux.org/image/>`_
@@ -74,74 +74,75 @@ Download and launch the virtual machine

 #. Make the script executable:

-   .. code-block:: console
+   .. code-block:: bash

-      # chmod +x start_qemu.sh
+      chmod +x start_qemu.sh

 #. Start the |CL| KVM virtual machine:

-   .. code-block:: console
+   .. code-block:: bash

-      # ./start_qemu.sh clear-<version>-kvm.img
+      ./start_qemu.sh clear-<version>-kvm.img

 #. Log in as ``root`` user and set a new password.

 SSH access into the virtual machine
-===================================
+***********************************
+
 To interact with the |CL| VM through SSH instead of the console it was
 launched from, follow these steps.

 #. Enable SSH in the |CL| VM:

-   .. code-block:: console
+   .. code-block:: bash

-      # cat > /etc/ssh/sshd_config << EOF
+      cat > /etc/ssh/sshd_config << EOF
        PermitRootLogin yes
        EOF

 #. From the host, SSH into the |CL| VM.  The port number ``10022`` is defined
   in the ``start_qemu.sh`` script.  

-   .. code-block:: console
+   .. code-block:: bash

-      # ssh -p 10022 root@localhost
+      ssh -p 10022 root@localhost

 Add the GNOME Display Manager (GDM)
-===================================
+***********************************

 To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps:

 #. Shutdown the active |CL| VM.

-   .. code-block:: console
+   .. code-block:: bash

-      # shutdown now
+      shutdown now
          
 #. Install a VNC viewer on the host machine.  Below are some example distros.

   * On Clear Linux:

-     .. code-block:: console
+     .. code-block:: bash

-        # swupd bundle-add desktop-apps-extras 
+        swupd bundle-add desktop-apps-extras 

   * On Ubuntu\* 16.04 LTS Desktop:

-     .. code-block:: console
+     .. code-block:: bash

-        # apt-get install vncviewer
+        apt-get install vncviewer

   * On Mint\* 18.1 “Serena” Desktop:

-     .. code-block:: console
+     .. code-block:: bash

-        # apt-get install vncviewer
+        apt-get install vncviewer

   * On Fedora\* 25 Workstation:

-     .. code-block:: console
+     .. code-block:: bash

-        # dnf install tigervnc
+        dnf install tigervnc

 #. Modify the :file:`start_qemu.sh` script to increase memory (``-m``), add
   graphics driver (``-vga``), and add VNC (``-vnc``, ``-usb``, and
@@ -169,48 +170,48 @@ To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps:

   #. Relaunch the |CL| VM.  The UEFI shell will appear.

-      .. code-block:: console
+      .. code-block:: bash

-         # ./start_qemu.sh clear-<version>-kvm.img
+         ./start_qemu.sh clear-<version>-kvm.img

   #. At the UEFI shell, delete the :file:`NvVars` file:

-      .. code-block:: console
+      .. code-block:: bash

         Shell> del FS0:\NvVars

   #. Exit out of the UEFI shell:

-      .. code-block:: console
+      .. code-block:: bash

         Shell> reset -s

   #. Relaunch the |CL| VM:

-      .. code-block:: console
+      .. code-block:: bash

-         # ./start_qemu.sh clear-<version>-kvm.img
+         ./start_qemu.sh clear-<version>-kvm.img

 #. From the host machine, open a new terminal emulator window and VNC into the
   |CL| VM:

-   .. code-block:: console
+   .. code-block:: bash

-      # vncviewer 0.0.0.0
+      vncviewer 0.0.0.0

 #. Log in as ``root`` user into the |CL| VM.

 #. Add GDM to the |CL| VM:

-   .. code-block:: console
+   .. code-block:: bash

-      # swupd bundle-add desktop-autostart
+      swupd bundle-add desktop-autostart

 #. Reboot the |CL| VM to enable GDM:

-   .. code-block:: console
+   .. code-block:: bash

-      # reboot
+      reboot
      
 #. Go through GDM's out-of-box experience (OOBE).

@@ -1,26 +1,26 @@
 .. _virtual-machine-install:

-Install Clear Linux in a virtual machine
-########################################
+Install |CL-ATTR| in a virtual machine
+######################################

-There are some considerations to make when installing |CL| in a VM.
+There are some considerations to make when installing |CL-ATTR| in a VM.
 First, you need to decide which kernel to use. This document
 will walk you through the available kernel options to help this decision. At
 the end of this document, you will be able to select the set of installation
 steps most suitable to you and install |CL| under a VM.

 Compatible kernels
-==================
+******************

-The |CLOSIA| provides the following Linux kernels with a respective
+The |CL| provides the following Linux kernels with a respective
 :ref:`bundle <bundles-about>` for VMs. Specific use cases these bundles serve
 are provided along with links to their source code.

 .. include:: ../../reference/compatible-kernels.rst
   :Start-after: vm-kernels:

-Next steps:
-===========
+Next steps
+**********

 Now that you have read about the |CL| compatible kernels, choose the
 appropriate set of step-by-step instructions to proceed.
@@ -6,14 +6,14 @@ Run pre-configured |CL-ATTR| as a VirtualBox\* guest OS
 This instruction explains how to deploy a pre-configured |CL-ATTR| image as a guest on the `VirtualBox hypervisor`_ .

 Download VirtualBox
-===================
+*******************

 VirtualBox\* is a type 2 hypervisor from Oracle. Download and use **version 5.0 or greater** from the `official VirtualBox website`_.

 .. _create_vm_vbox:

 Prerequisites
-=============
+*************

 The instruction assumes that you have: 

@@ -29,7 +29,7 @@ The instruction assumes that you have:
 If you have not completed the above steps, do so before continuing. 

 Create a virtual machine in VirtualBox
-======================================
+**************************************

 #. Log in to your host and open a terminal emulator.

@@ -103,7 +103,7 @@ Create a virtual machine in VirtualBox


 Run your new VM
-===============
+***************

 |CL| supports VirtualBox kernel modules used
 by the Linux kernel 4.14 :abbr:`LTS (Long Term Support)` 
@@ -147,7 +147,7 @@ To install the VirtualBox kernel modules, here are the steps:
     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* 
@@ -170,7 +170,7 @@ follow these steps:


 Troubleshooting
---------------
+===============

 On Windows OS, *VirtualBox* cannot do a **Hardware Virtualization** when
 *Hyper-V* is enabled.
@@ -1,11 +1,11 @@
 .. _vmw-player-preconf:

-Run pre-configured Clear Linux image as a VMware\* Workstation Player guest OS
-##############################################################################
+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
 another operating system such as Windows\* or Linux\*. With VMware ESXi, you
-can create, configure, manage, and run |CLOSIA| :abbr:`VMs (Virtual Machines)`
+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
@@ -13,18 +13,12 @@ VMware Workstation 14 Player.

 In this tutorial, we perform the following steps:

-#. Install the VMware Workstation Player hypervisor
-#. Download the latest |CL| pre-configured image
-#. VMware image Verify the integrity of the |CL| image
-#. Uncompress the |CL| image
-#. Create and configure a new VM
-#. Attach the pre-configured VMware |CL| image
-#. Enable EFI boot support
-#. Power on the VM
+.. contents:: :local:
+   :depth: 1

 .. note::

-   The screenshots on this document show the Windows\* version of the
+   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.

@@ -61,14 +55,8 @@ Install the VMware Workstation Player hypervisor

 For additional help, see the `VMware Workstation Player guide`_.

-Clear Linux image types
-***********************
-
-.. include:: ../../reference/image-types.rst
-   :Start-after: image-types-content:
-
-Download the latest Clear Linux VMware image
-********************************************
+Download the latest |CL| VMware image
+*************************************

 Get the latest |CL| VMware image from the `image`_ repository.
 Look for :file:`clear-[version number]-vmware.vmdk.xz`. You can also use
@@ -78,6 +66,8 @@ this command:

   curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-vmware.vmdk.xz

+Visit :ref:`image-types` for additional information about all available |CL| images.
+
 .. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst
   :Start-after: verify-windows:

@@ -189,8 +179,8 @@ Create and configure a new VM

 #. Click the :guilabel:`Finish` button.

-Attach the pre-configured Clear Linux VMware image
-**************************************************
+Attach the pre-configured |CL| VMware image
+*******************************************

 #. Move the downloaded and uncompressed pre-configured |CL| VMware image file
   :file:`clear-[version number]-basic.vmdk` to the directory where your
@@ -304,6 +294,9 @@ After configuring the settings above, power on your |CL| virtual machine.

 #. Click :guilabel:`Play virtual machine`.

+Related topics
+**************
+
 For other guides on using the VMWare Player and ESXi, see:

 * :ref:`vmw-player`
@@ -1,11 +1,11 @@
 .. _vmw-player:

-Install Clear Linux as a VMware\* Workstation Player guest OS
-#############################################################
+Install |CL-ATTR| as a VMware\* Workstation Player guest OS
+###########################################################

 `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 |CLOSIA| :abbr:`VMs (Virtual Machines)` on
+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
@@ -15,17 +15,8 @@ size, number of partitions, installed bundles, etc.

 In this tutorial, we perform the following steps:

-#. Install the VMware Workstation Player hypervisor
-#. Download the latest |CL| installer ISO
-#. Verify the integrity of the |CL| image
-#. Uncompress the |CL| image
-#. Create and configure a new VM
-#. Attach the |CL| installer ISO to the VM
-#. Install |CL| into the new VM
-#. Detach the |CL| installer ISO from the VM
-#. Power off the VM
-#. Enable EFI boot support
-#. Power on the VM
+.. contents:: :local:
+   :depth: 1

 If you prefer to use a pre-configured |CL| VMware image instead,
 see our :ref:`vmw-player-preconf` guide.
@@ -36,7 +27,7 @@ it, see :ref:`vmware-esxi-install-cl`.

 .. note::

-   The screenshots on this document show the Windows\* version of the
+   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.

@@ -55,35 +46,30 @@ Install the VMware Workstation Player hypervisor

   * On supported Linux distros:

-      #. Enable a GUI desktop.
-      #. Start a terminal emulator.
-      #. Start the installer by issuing the command below and follow the
-          guided steps.
+     #. Enable a GUI desktop.
+     #. Start a terminal emulator.
+     #. Start the installer by issuing the command below and follow the
+        guided steps.

-          .. code-block:: console
+        .. code-block:: console

-            $ sudo sh ./VMware-Player-[version number].x86_64.bundle
+           sudo sh ./VMware-Player-[version number].x86_64.bundle

   * On Windows:

-      #. Start the installer.
-      #. Follow the setup wizard.
+     #. Start the installer.
+     #. Follow the setup wizard.

 For additional help, see the `VMware Workstation Player guide`_.

-Clear Linux image types
-***********************
-
-.. include:: ../../reference/image-types.rst
-   :Start-after: image-types-content:
-
-
-Download the latest Clear Linux installer ISO
-*********************************************
+Download the latest |CL| installer ISO
+**************************************

 Get the latest |CL| installer ISO image from the `image`_ repository.
 Look for :file:`clear-[version number]-installer.iso.xz`.

+Visit :ref:`image-types` for additional information about all available |CL| images.
+
 .. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst
   :Start-after: verify-windows:

@@ -204,8 +190,8 @@ Create and configure a new VM

 #. Click the :guilabel:`Finish` button.

-Install Clear Linux into the new VM
-***********************************
+Install |CL| into the new VM
+****************************

 #. Select the newly-created VM and click the :guilabel:`Play virtual machine`
   button. See Figure 9.
@@ -267,7 +253,7 @@ Enable UEFI boot support
 |CL| needs UEFI support to boot. To enable UEFI, add the
 following line to the end of your VM's :file:`.vmx` file:

-.. code-block:: bash
+.. code-block:: console

   firmware = "efi"

@@ -294,6 +280,9 @@ After configuring the settings above, power on your |CL| virtual machine.

 #. Click :guilabel:`Play virtual machine`.

+Related topics
+**************
+
 For other guides on using the VMWare Player and ESXi, see:

 * :ref:`vmw-player-preconf`
@@ -1,18 +1,15 @@
 .. _vmware-esxi-install-cl:

-Install Clear Linux as a VMware\* ESXi guest OS
-###############################################
+Install |CL-ATTR| as a VMware\* ESXi guest OS
+#############################################

 `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 |CLOSIA| virtual machines in the cloud.  
+run |CL-ATTR| 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. 

-If you would prefer to use a preconfigured |CL| VMware disk image 
-instead, see :ref:`vmware-esxi-preconfigured-cl-image`. 
-
 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. 
@@ -35,8 +32,8 @@ Install steps:
   :depth: 1


-Download the latest Clear Linux installer ISO
-*********************************************
+Download the latest |CL| installer ISO
+**************************************

 Get the latest |CL| installer ISO image from the `image`_ repository.
 Look for :file:`clear-[version number]-installer.iso.xz`.
@@ -50,8 +47,8 @@ For alternative instructions on other operating systems, see:
 * :ref:`download-verify-uncompress-mac`
 * :ref:`download-verify-uncompress-windows`

-Upload the Clear Linux installer ISO to the VMware server
-*********************************************************
+Upload the |CL| installer ISO to the VMware server
+**************************************************

 #.  Connect to the VMware server and log into an account with sufficient 
    permission to create and manage VMs.  
@@ -188,8 +185,8 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I
 #.  Click the :guilabel:`Next` button.
 #.  Click the :guilabel:`Finish` button.

-Install Clear Linux into the new VM
-***********************************
+Install |CL| into the new VM
+****************************

 #.  Power on the VM.
    
@@ -211,8 +208,8 @@ Install Clear Linux into the new VM
 #.  After the installation is complete, follow the |CL| instruction to reboot it.  
    This will restart the installer again. 

-Reconfigure the VM's settings to boot the newly-installed Clear Linux
-*********************************************************************
+Reconfigure the VM's settings to boot the newly-installed |CL|
+**************************************************************

 After |CL| has been installed using the installer ISO, it must be detached so
 it will not run again.  Also, in order to boot the newly-installed |CL|, you must
@@ -268,8 +265,8 @@ enable UEFI support.

 #.  Click the :guilabel:`Save` button.

-Power on the VM and boot Clear Linux
-************************************
+Power on the VM and boot |CL|
+*****************************

 After configuring the settings above, power on the VM.  

@@ -286,8 +283,8 @@ After configuring the settings above, power on the VM.

      Figure 16: VMware ESXi - Navigator > Virtual Machines > Power on VM

-See Also:
-=========
+Related topics
+**************

 * :ref:`vmware-esxi-preconfigured-cl-image`

@@ -1,11 +1,11 @@
 .. _vmware-esxi-preconfigured-cl-image:

-Run preconfigured Clear Linux\* image as a VMware\* ESXi guest OS
-#################################################################
+Run preconfigured |CL-ATTR| image as a VMware\* ESXi guest OS
+#############################################################

 `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 |CLOSIA| virtual machines at scale.
+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.
@@ -21,15 +21,14 @@ VMware ESXi :abbr:`VM (Virtual Machine)` instead, see

   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

-Download the latest Clear Linux VMware image
-********************************************
+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
@@ -39,6 +38,8 @@ this command:

   curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-vmware.vmdk.xz

+Visit :ref:`image-types` for additional information about all available |CL| images.
+
 .. include:: ../../guides/maintenance/download-verify-uncompress-linux.rst
   :Start-after: verify-linux:
   :end-before: To uncompress a GZ
@@ -48,8 +49,8 @@ For alternative instructions on other operating systems, see:
 * :ref:`download-verify-uncompress-mac`
 * :ref:`download-verify-uncompress-windows`

-Upload the Clear Linux image to the VMware server
-*************************************************
+Upload the |CL| image to the VMware server
+******************************************

 Once the |CL| VMware prebuilt image has been downloaded and 
 uncompressed on your local system, it must be uploaded to a datastore 
@@ -94,8 +95,8 @@ The steps in this section can also be referenced from the `VMware documentation
 #. Select the uncompressed |CL| VMware image file
   :file:`clear-[version number]-vmware.vmdk` and upload it.

-Convert the Clear Linux image to an ESXi-supported format
-*********************************************************
+Convert the |CL| image to an ESXi-supported format
+**************************************************

 Once the |CL| VMware prebuilt image has been uploaded to the VMware ESXi
 datastore, it must be converted to a format for usable with VMware's ESXi 
@@ -258,8 +259,8 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support.
 #. Click the :guilabel:`Next` button.
 #. Click the :guilabel:`Finish` button.

-Power on the VM and boot Clear Linux
-************************************
+Power on the VM and boot |CL|
+*****************************

 After configuring the settings above, power on the VM.

@@ -276,8 +277,8 @@ After configuring the settings above, power on the VM.

      Figure 13: VMware ESXi - Navigator > Virtual Machines > Power on VM

-See Also:
-=========
+Related topics
+**************

 * :ref:`vmware-esxi-install-cl`

@@ -1,11 +1,11 @@
 .. _image-types:

-Clear Linux\* image types
+|CL-ATTR| image types
 #########################

 .. _image-types-content:

-|CLOSIA| offers many types of `images`_ for different platforms and environments.
+|CL-ATTR| offers many types of `images`_ for different platforms and environments.

 .. _incl-image-filename:

@@ -28,7 +28,7 @@ The naming convention of a |CL| image filename is:
 Table 1 lists the currently available images that are platform independent.
 Table 2 lists the currently available images that are platform specific.

-.. list-table:: Table 1: Types of platform-independent Clear Linux images
+.. list-table:: Table 1: Types of platform-independent |CL| images
   :widths: 15, 85
   :header-rows: 1

@@ -36,15 +36,15 @@ Table 2 lists the currently available images that are platform specific.
     - Description

   * - installer.img 
-     - Preferred image of Clear Linux with interactive installer. 
+     - Preferred image of |CL| with interactive installer. 

   * - installer.iso
-     - ISO of Clear Linux with interactive installer. Only for special cases where ISO image format is required (not for use with a USB key)
+     - ISO of |CL| with interactive installer. Only for special cases where ISO image format is required (not for use with a USB key)

   * - live.img
-     - image for live booting into memory, without requiring installaton. 
+     - Image for live booting into memory, without requiring installaton. 

-.. list-table:: Table 2: Types of platform-specific Clear Linux images
+.. list-table:: Table 2: Types of platform-specific |CL| images
   :widths: 15, 85
   :header-rows: 1