Merge branch 'master' of github.com:clearlinux/clear-linux-documentation into rtd-theme

And fix of kernel-development.rst to match master Signed-off-by: Kevin Putnam <kevin.putnam@intel.com>
2026-09-06 13:51:40 +00:00 · 2019-05-03 11:11:05 -07:00
parent 065904177f 680eadb806
commit 9c1772e594
53 changed files with 541 additions and 286 deletions
@@ -37,6 +37,8 @@ Preliminary steps

   * :ref:`bootable-usb`

+.. _install-on-target-start:
+
 Install from live image
 ***********************

@@ -60,6 +62,8 @@ USB drive, follow these steps.

 #. Reboot the target system.

+.. _install-on-target-end:
+
 Launch the installer
 ====================

@@ -207,101 +211,58 @@ Configure the Keyboard

      Figure 6: Select Keyboard menu

-Configure Media
-===============
+Configure Installation Media
+============================

-#. From the Main Menu, select :guilabel:`Configure Media`.
+#. From the Main Menu, select :guilabel:`Configure Installation Media`.

-   .. note::
+#. Choose an installation method: `Safe Installation`_;
+   `Destructive Installation`_; or `Advanced Configuration`_

-      Available media appear by default.
-
-#. Navigate to the desired media until highlighted.

   .. figure:: figures/bare-metal-install-beta-7.png
      :scale: 100%
-      :alt: Configure Media menu
+      :alt: Select Installation Media

-      Figure 7: Configure Media menu
+      Figure 7: Select Installation Media

-      .. note::
+Safe Installation
+-----------------

-         Use additional options as necessary during partitioning:
+Use this method to safely install |CL| on media with available space,
+or alongside existing partitions, and accept the recommended partitioning
+schema. If an unallocated partition exists with enough space, safe
+installation is allowed.

-         * Select :guilabel:`Revert` to cancel changes and revert to the
-           original configuration.
-         * Select :guilabel:`Rescan` to show media connected to the host
-           machine.
+If a warning message appears that no media or space is available:

-#. Select :kbd:`Enter` or :kbd:`Spacebar` to select it.
+- Verify that target media has enough unallocated disk space
+- Confirm target media is properly connected or mounted
+- Review the size of existing partitions on the target media:

-   Two options for partitioning appear.
+  - Linux\* OS: :command:`lsblk -a`
+  - Windows\* OS:  :command:`diskpart`, then :command:`list disk`
+  - macOS\* platform: :command:`diskutil list`

-#. Select :guilabel:`Auto Partition` to accept the default configuration, or
-   :guilabel:`Add Partition` to add partitions manually. See instructions
-   below.
+Destructive Installation
+------------------------

-#. Select :kbd:`Enter` to :kbd:`Confirm`.
-
-#. Select one partitioning method and continue:
-
-   * `Auto Partition`_
-   * `Add Partition`_
-
-Auto Partition
-==============
-
-Auto partition will configure the media to meet the minimum requirements.
-
-#. Select :guilabel:`Auto Partition` as shown in Figure 8.
-
-#. Select :kbd:`Enter` or :kbd:`Spacebar` to highlight
-   :guilabel:`Auto partition`.
-
-#. Select :kbd:`Enter` to :kbd:`Confirm`.
-
-   This action returns you to the Main Menu.
-
-   .. figure:: figures/bare-metal-install-beta-8.png
-      :scale: 100%
-      :alt: Auto Partition
-
-      Figure 8: Auto Partition
-
-#. You may skip to the `Telemetry`_ section below.
-
-Disk encryption
-===============
-
-For greater security, disk encryption is supported using LUKS for all
-partitions **except boot** on |CL|. To encrypt a partition, see the example
-in `root partition`_ below. Encryption is optional.
-
-Encryption Passphrase
---------------------
-
-|CL| uses a single passphrase for all encrypted partitions. Therefore, if
-you turn on encryption for one partition, the same passphrase is used for
-all partitions. Additional or different keys may be configured
-post-installation using the ``cryptsetup`` tool.
+Use this method to destroy the contents of the target device, install |CL|,
+and accept the recommended partitioning schema. If no safe options exist,
+:guilabel:`Destructive Installation` will appear by default.

 .. note::

-   During installation, if you encrypt the `root` partition first and the
-   `swap` partition second, after you select encrypt for `swap`, the
-   :guilabel:`Encryption Passphrase` dialogue will show the same Passphrase that was assigned to `root`. Select :guilabel:`Confirm` and
-   press :kbd:`Enter` to use the same Passphrase.
+   From the :guilabel:`Select Installation Media` menu, select
+   :guilabel:`Enable Encryption` to encrypt the root filesystem for either option above. See also `Disk encryption`_ for more information.

-Add Partition
-=============
+Partition minimum requirements
+-------------------------------

-Minimum requirements
--------------------
+To add partitions manually, see `Advanced configuration`_ below and create
+partitions per requirements in Table 1.

-To add partitions manually, assign partitions per the minimum
-requirements shown in Table 1:
-
-.. list-table:: **Table 1. Disk Partition Setup**
+.. list-table:: **Table 1. Disk Partition Setup: Minimum requirements**
   :widths: 33, 33, 33
   :header-rows: 1

@@ -318,130 +279,150 @@ requirements shown in Table 1:
     - /
     - *Size depends upon use case/desired bundles.*

+Advanced Configuration
+----------------------

-#. In the Configure Media menu, select :guilabel:`Add Partition`.
+Use this method to manually configure partitions. Partitions
+must meet `Partition minimum requirements`_.
+You may also choose `Disk encryption`_ during partitioning.

-   .. note:: To change an existing partition, navigate to the partition,
-      and select :guilabel:`Enter`.
+.. note::

-boot partition
--------------
+   Advanced Configuration is available in the installer versions 1.2.0 and above.

-#. In the :guilabel:`File System` menu, select :kbd:`Up/Down` arrows to
-   select the file system type.  See Figure 9.
+#. In :guilabel:`Advanced Configuration`, press
+   :kbd:`Enter` to activate editing.

-#. In :guilabel:`Mount Point`, enter the ``/boot`` partition.
-
-#. In :guilabel:`Size`, enter an appropriate size (e.g., 150M) per Table 1.
-
-#. Navigate to :guilabel:`Confirm` until highlighted.
-
-#. Select :guilabel:`Enter` to confirm.
-
-   .. figure:: figures/bare-metal-install-beta-9.png
+   .. figure:: figures/bare-metal-install-beta-8.png
      :scale: 100%
-      :alt: boot partition
+      :alt: Advanced configuration menu

-      Figure 9: boot partition
+      Figure 8: Advanced configuration menu

-swap partition
--------------
+#. Choose one of these options:

-#. In the :guilabel:`File System` menu, select :kbd:`Up/Down` arrows to
-   select the file system type. See Figure 10.
+   :guilabel:`Auto Partition`

-#. In :guilabel:`Mount Point`, the field remains blank.
+   #. Select this option to accept the recommended partitioning schema.
+
+   #. Navigate to and press :guilabel:`Confirm`.
+
+   #. Continue with installation configuration.
+
+   :guilabel:`Manual Partition`
+
+   #. Continue below.
+
+Manual Partition
+----------------
+
+We provide a simple example below.
+
+#. Navigate to the unallocated media (e.g.,`sdb1`) until highlighted.
+
+#. Select :guilabel:`Enter` to edit the partition.
+
+#. The :guilabel:`Partition Setup` menu appears, shown in Figure 9.

   .. note::

-      The Mount Point field is disabled.
-
-#. In :guilabel:`Size`, enter an appropriate size (e.g., 256MB) per Table 1.
-
-#. Navigate to :guilabel:`Add`.
-
-#. Select :guilabel:`Enter` to continue.
-
-   .. figure:: figures/bare-metal-install-beta-10.png
-      :scale: 100%
-      :alt: swap partition
-
-      Figure 10: swap partition
+      After adding the first partition, select :guilabel:`Free Space` to add another partition.

 root partition
 --------------

-#. In the :guilabel:`File System` menu, select :kbd:`Up/Down` arrows to
-   select the file system type. See Figure 11.
+We configure the `root` partition as shown in Figure 9.

-   #. Optional: Select :guilabel:`[X] Encrypt` to encrypt the partition.
+.. figure:: figures/bare-metal-install-beta-9.png
+   :scale: 100%
+   :alt: root partition

-      .. figure:: figures/bare-metal-install-beta-11.png
-         :scale: 100%
-         :alt: Encrypt partition
+   Figure 9: root partition

-         Figure 11: Encrypt partition
+boot partition
+--------------

+We configure the `boot` partition as shown in Figure 10.

-   #. The :guilabel:`Encryption Passphrase` dialogue appears.
+.. figure:: figures/bare-metal-install-beta-10.png
+   :scale: 100%
+   :alt: boot partition

-      .. note::
+   Figure 10: boot partition

-         Minimum length is 8 characters. Maximum length is 94 characters.
+swap partition
+--------------

-      .. figure:: figures/bare-metal-install-beta-12.png
-         :scale: 100%
-         :alt: Encryption Passphrase
+#. In the :guilabel:`File System` pulldown menu, we select `swap`, and
+   enter its label. We enter the minimum required size (e.g., 256M).

-         Figure 12: Encryption Passphrase
+   .. figure:: figures/bare-metal-install-beta-11.png
+      :scale: 100%
+      :alt: swap partition

-   #. Enter the same passphrase in the first and second field.
+      Figure 11: swap partition

-   #. Navigate to :guilabel:`Confirm` and press :kbd:`Enter`.
+#. Next, navigate to :guilabel:`Confirm` and press :guilabel:`Enter`,
+   shown in Figure 12.

-      .. note::
+   .. figure:: figures/bare-metal-install-beta-12.png
+      :scale: 100%
+      :alt: Final configuration of disk partitions

-         :guilabel:`Confirm` is only highlighted if passphrases match.
+      Figure 12: Final configuration of disk partitions

-#. Optional: In :guilabel:`[Optional] Label:`, enter your desired
-   label for the partition.
+#. You may skip to the `Telemetry`_ section below.

-#. In :guilabel:`Mount Point`, enter ``/``. See Figure 11.
+Disk encryption
+===============

-#. In :guilabel:`Size`, enter an appropriate size per Table 1.
+For greater security, disk encryption is supported using LUKS for the
+any partition except `/boot` on |CL|. To encrypt the root partition, see the
+example below. Encryption is optional.

-   .. note::
+Encryption Passphrase
+---------------------

-      The remaining available space shows by default.
+|CL| uses a single passphrase for encrypted partitions. Additional or
+different keys may be configured post-installation using the ``cryptsetup``
+tool.

-#. Navigate to :guilabel:`Add` until highlighted.
-
-#. Select :guilabel:`Enter` to continue.
-
-   You are returned to the :guilabel:`Configure media` menu.
-
-#. Select :guilabel:`Confirm` to complete the media selection. See Figure 13.
-
-#. You are returned to the :guilabel:`Configure media` menu. Your partitions
-   should be similar to those shown in Figure 13.
+#. Optional: Select :guilabel:`[X] Encrypt` to encrypt the root partition,
+   as shown in Figure 13.

   .. figure:: figures/bare-metal-install-beta-13.png
      :scale: 100%
-      :alt: Partitions
+      :alt: Encrypt partition

-      Figure 13: Partitions
+      Figure 13: Encrypt partition

-#. Navigate to :guilabel:`Confirm` until highlighted.
+#. The :guilabel:`Encryption Passphrase` dialogue appears.

-#. Select :guilabel:`Enter` to complete adding partitions.
+   .. note::
+
+      Minimum length is 8 characters. Maximum length is 94 characters.
+
+   .. figure:: figures/bare-metal-install-beta-14.png
+      :scale: 100%
+      :alt: Encryption Passphrase
+
+      Figure 14: Encryption Passphrase
+
+#. Enter the same passphrase in the first and second field.
+
+#. Navigate to :guilabel:`Confirm` and press :kbd:`Enter`.
+
+   .. note::
+
+      :guilabel:`Confirm` is only highlighted if passphrases match.

 Telemetry
 =========

-To fulfill the :guilabel:`Required options`, choose whether or not to
-participate in `telemetry`_.  :ref:`telem-guide` is a |CL| feature that
-reports failures and crashes to the |CL| development team for improvements.
-For more detailed information, visit our :ref:`telemetry-about` page.
+To fulfill :guilabel:`Required options`, choose whether to participate in
+the `telemetry option`_. :ref:`telem-guide` is a |CL| feature that reports
+failures and crashes to the |CL| development team for improvements. For more
+detailed information, visit our :ref:`telemetry-about` page.

 #. In the Main Menu, navigate to :guilabel:`Telemetry` and select
   :kbd:`Enter`.
@@ -450,11 +431,11 @@ For more detailed information, visit our :ref:`telemetry-about` page.

 #. Select :kbd:`Enter` to confirm.

-   .. figure:: figures/bare-metal-install-beta-14.png
+   .. figure:: figures/bare-metal-install-beta-15.png
      :scale: 100%
      :alt: Enable Telemetry

-      Figure 14: Enable Telemetry
+      Figure 15: Enable Telemetry

 Recommended options
 *******************
@@ -507,22 +488,22 @@ interface settings are automatically applied.

   .. note:: Multiple network interfaces may appear.

-   .. figure:: figures/bare-metal-install-beta-15.png
+   .. figure:: figures/bare-metal-install-beta-16.png
      :scale: 100%
      :alt: Configure Network Interfaces

-      Figure 15: Configure Network Interfaces
+      Figure 16: Configure Network Interfaces

 #. Notice :guilabel:`Automatic / dhcp` is selected by default (at bottom).

   Optional: Navigate to the checkbox :guilabel:`Automatic / dhcp` and select
   :kbd:`Spacebar` to deselect.

-   .. figure:: figures/bare-metal-install-beta-16.png
+   .. figure:: figures/bare-metal-install-beta-17.png
      :scale: 100%
      :alt: Network interface configuration

-      Figure 16: Network interface configuration
+      Figure 17: Network interface configuration

 #. Navigate to the appropriate fields and assign the desired
   network configuration.
@@ -558,11 +539,11 @@ instruction.

 #. Navigate to the field :guilabel:`HTTPS Proxy`.

-   .. figure:: figures/bare-metal-install-beta-17.png
+   .. figure:: figures/bare-metal-install-beta-18.png
      :scale: 100%
      :alt: Configure the network proxy

-      Figure 17: Configure the network proxy
+      Figure 18: Configure the network proxy

 #. Enter the desired proxy address and port using conventional syntax,
   such as: \http://address:port.
@@ -580,13 +561,13 @@ Test Network Settings
 To manually assure network connectivity before installing |CL|,
 select :guilabel:`Test Network Settings` and select :guilabel:`Enter`.

-A progress bar appears as shown in Figure 18.
+A progress bar appears as shown in Figure 19.

-.. figure:: figures/bare-metal-install-beta-18.png
+.. figure:: figures/bare-metal-install-beta-19.png
   :scale: 100%
   :alt: Testing Networking dialogue

-   Figure 18: Testing Networking dialogue
+   Figure 19: Testing Networking dialogue

 .. note::

@@ -606,11 +587,11 @@ Bundle Selection

 #. We recommend adding :file:`desktop-autostart` and :file:`user-basic`.

-   .. figure:: figures/bare-metal-install-beta-19.png
+   .. figure:: figures/bare-metal-install-beta-20.png
      :scale: 100%
      :alt: Bundle Selection

-      Figure 19: Bundle Selection
+      Figure 20: Bundle Selection

   .. note::

@@ -632,13 +613,13 @@ Add New User

 #. In Advanced Options, select :guilabel:`User Manager`.

-#. Select :guilabel:`Add New User` as shown in Figure 20.
+#. Select :guilabel:`Add New User` as shown in Figure 21.

-   .. figure:: figures/bare-metal-install-beta-20.png
+   .. figure:: figures/bare-metal-install-beta-21.png
      :scale: 100%
      :alt: Add New User, User Name

-      Figure 20: Add New User
+      Figure 21: Add New User

 #. Optional: Enter a :guilabel:`User Name`.

@@ -646,11 +627,11 @@ Add New User

      The User Name must be alphanumeric and can include spaces, commas, or hyphens. Maximum length is 64 characters.

-   .. figure:: figures/bare-metal-install-beta-21.png
+   .. figure:: figures/bare-metal-install-beta-22.png
      :scale: 100%
      :alt: User Name

-      Figure 21: User Name
+      Figure 22: User Name

 #. Enter a :guilabel:`Login`.

@@ -673,11 +654,11 @@ Add New User

      Selecting this option enables sudo privileges for the user.

-   .. figure:: figures/bare-metal-install-beta-22.png
+   .. figure:: figures/bare-metal-install-beta-23.png
      :scale: 100%
      :alt: Administrative rights

-      Figure 22: Administrative rights
+      Figure 23: Administrative rights

 #. Select :kbd:`Confirm`.

@@ -693,15 +674,15 @@ Modify / Delete User
 --------------------

 #. In User Manager, select :guilabel:`Tab` to highlight the user, as shown
-   in Figure 23.
+   in Figure 24.

 #. Select :kbd:`Enter` to modify the user.

-   .. figure:: figures/bare-metal-install-beta-23.png
+   .. figure:: figures/bare-metal-install-beta-24.png
      :scale: 100%
      :alt: Modify User

-      Figure 23: Modify User
+      Figure 24: Modify User

 #. Modify user details as desired.

@@ -735,11 +716,11 @@ new kernel.

 #. To add or remove arguments, choose one of the following options.

-   .. figure:: figures/bare-metal-install-beta-24.png
+   .. figure:: figures/bare-metal-install-beta-25.png
      :scale: 100%
      :alt: kernel command line

-      Figure 24: kernel command line
+      Figure 25: kernel command line

 #. To add arguments, enter the argument in :guilabel:`Add Extra Arguments`.

@@ -754,15 +735,15 @@ Kernel Selection
 ================

 #. Select a kernel option. By default, the latest kernel release is
-   selected. Native kernel is shown in Figure 25.
+   selected. Native kernel is shown in Figure 26.

 #. To select a differnt kernel, navigate to it using :guilabel:`Tab`.

-   .. figure:: figures/bare-metal-install-beta-25.png
+   .. figure:: figures/bare-metal-install-beta-26.png
      :scale: 100%
      :alt: Kernel selection

-      Figure 25: Kernel selection
+      Figure 26: Kernel selection

 #. Select :kbd:`Spacebar` to select the desired option.

@@ -781,11 +762,11 @@ If you have your own custom mirror of |CL|, you can add its URL.

 #. Select :kbd:`Confirm`.

-   .. figure:: figures/bare-metal-install-beta-26.png
+   .. figure:: figures/bare-metal-install-beta-27.png
      :scale: 100%
      :alt: Swupd Mirror

-      Figure 26: Swupd Mirror
+      Figure 27: Swupd Mirror

 Optional: Skip to `Finish installation`_.

@@ -802,11 +783,11 @@ Assign Hostname
      alphanumeric character but may also contain hyphens. Maximum length of
      63 characters.

-   .. figure:: figures/bare-metal-install-beta-27.png
+   .. figure:: figures/bare-metal-install-beta-28.png
      :scale: 100%
      :alt: Assign Hostname

-      Figure 27: Assign Hostname
+      Figure 28: Assign Hostname


 #. Navigate to :kbd:`Confirm` until highlighted.
@@ -819,17 +800,17 @@ Automatic OS Updates
 ====================

 In the rare case that you need to disable automatic software updates,
-follow the onscreen instructions.
+follow the onscreen instructions shown in Figure 29.

 #. In Advanced Options, select :guilabel:`Automatic OS Updates`.

 #. Select the desired option.

-   .. figure:: figures/bare-metal-install-beta-28.png
+   .. figure:: figures/bare-metal-install-beta-29.png
      :scale: 100%
      :alt: Automatic OS Updates

-      Figure 28: Automatic OS Updates
+      Figure 29: Automatic OS Updates

 You are returned to the :guilabel:`Main Menu`.

@@ -861,4 +842,4 @@ Next steps

 .. _Navigate to the image directory: https://cdn.download.clearlinux.org/image/
 .. _Autoproxy: https://clearlinux.org/features/autoproxy
-.. _telemetry: https://clearlinux.org/features/telemetry
+.. _telemetry option: https://clearlinux.org/features/telemetry
@@ -30,20 +30,12 @@ Look for the :file:`clear-[version number]-installer.img.xz` file.

   Figure 1: Visit Downloads

-Optionally, you can use this command:
-
-.. code-block:: bash
-
-   curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep "installer")
-
 #. Follow your OS instructions to create a bootable USB drive.

   * :ref:`bootable-usb`

 #. After downloading the image, verify and decompress the file per your OS.

-.. _install-on-target:
-
 Install |CL| on your target system
 **********************************

@@ -26,7 +26,13 @@ Install QEMU-KVM

     .. code-block:: bash

-        swupd bundle-add desktop-autostart kvm-host
+        swupd bundle-add kvm-host
+
+   * |CL| option: Add this bundle to lanch the GUI upon boot.
+
+     .. code-block:: bash
+
+        swupd bundle-add desktop-autostart

   * On Ubuntu\* 16.04 LTS Desktop:

@@ -51,7 +57,7 @@ Download and launch the virtual machine

 #. Download the latest pre-built |CL| KVM image file from
   the `image <https://cdn.download.clearlinux.org/image/>`_ directory. Look for
-   ``clear-<version>-kvm.img.xz``.  You can also use this command: 
+   ``clear-<version>-kvm.img.xz``.  You can also use this command:

   .. code-block:: bash

@@ -64,29 +70,30 @@ Download and launch the virtual machine
      unxz clear-<version>-kvm.img.xz

 #. Download the `OVMF file`_ file that provides UEFI support for
-   virtual machines from the `image <https://cdn.download.clearlinux.org/image/>`_ directory.
+   virtual machines.
+
+   .. code-block:: bash
+
+      curl -O https://cdn.download.clearlinux.org/image/OVMF.fd

 #. Copy :file:`OVMF.fd` to the working directory, as shown below.

   .. code-block:: bash

-      cp /usr/share/qemu/OVMF.fd <working_directory>
+      cp OVMF.fd <working_directory>

   .. note::

      Replace <working_directory> with your own.

-      For non-Clear Linux hosts, the preferred approach is to download it from https://cdn.download.clearlinux.org/image/OVMF.fd
-
 #. Download the sample `QEMU-KVM launcher`_ script from the
   `image <https://cdn.download.clearlinux.org/image/>`_ directory.  This script
   will launch the |CL| VM and provide console interaction within the same
   terminal emulator window.
-   
+
   .. code-block:: bash
-      
+
      curl -O https://cdn.download.clearlinux.org/image/start_qemu.sh
-   

 #. Make the script executable:

@@ -123,7 +130,7 @@ launched from, follow these steps.
      systemctl start sshd

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

   .. code-block:: bash

@@ -139,7 +146,7 @@ To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps:
   .. code-block:: bash

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

   * On Clear Linux:
@@ -234,7 +241,7 @@ To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps:
   .. code-block:: bash

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

 #. The default aspect ratio of the GDM GUI for the |CL| VM is 4:3.  To change
@@ -202,8 +202,8 @@ Install |CL| into the new VM

      Figure 9: VMware Workstation 14 Player - Power on virtual machine

-#. Follow the :ref:`install-on-target` guide to complete the installation of
-   |CL|.
+#. Follow the :ref:`install-on-target-start` guide to complete the
+   installation of |CL|.

 #. After the installation completes, reboot the VM. This reboot restarts the
   |CL| installer.
@@ -203,7 +203,7 @@ Install |CL| into the new VM

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

-#.  Follow the :ref:`install-on-target` guide to complete the installation of 
+#.  Follow the :ref:`install-on-target-start` guide to complete the installation of 
    |CL|.
 #.  After the installation is complete, follow the |CL| instruction to reboot it.  
    This will restart the installer again. 
@@ -0,0 +1,80 @@
+.. _fix-broken-install:
+
+Fix a broken installation of |CL-ATTR|
+######################################
+
+This guide explains how to fix a broken installation of |CL| using a live
+desktop image on a USB. It's assumed you already installed |CL| on a
+target system, but your operating system does not boot or function properly.
+
+This process can only verify and fix files that :ref:`swupd<swupd-guide>`
+owns in :file:`/usr`. Files outside of this path, such as /home/, /etc,
+/var, etc., cannot be repaired by this process.
+
+Prerequisites
+*************
+
+* :ref:`Download and install the live desktop image on a USB <bare-metal-install-beta>`
+
+Boot a live desktop image to fix target system
+**********************************************
+
+#. Boot the |CL| live desktop image.
+
+.. include:: ../../get-started/bare-metal-install-beta/bare-metal-install-beta.rst
+   :start-after: install-on-target-start:
+   :end-before: install-on-target-end:
+
+Mount root partition, verify, and fix
+*************************************
+
+#. Open a Terminal window.
+
+#. Assure the system is connected to the network.
+
+#. Mount the system’s root partition.
+
+   #. To find the root partition, run:
+
+      .. code-block:: bash
+
+         lsblk
+
+      We'll use `/dev/sda3/` as the root partition example.
+
+   #. Next, mount the partition to the `/mnt` folder.
+
+      .. code-block:: bash
+
+         sudo mount /dev/sda3 /mnt
+
+#. Verify that you mounted the correct root partition by checking for some 
+   files commonly found on |CL| systems.
+
+   .. code-block:: bash
+
+      cat /mnt/usr/lib/os-release
+      ls /mnt/usr/share/clear/bundles
+
+#. Next, run swupd to fix any issues on the target system.
+
+   .. code-block:: bash
+
+      sudo swupd verify --fix --picky --path=/mnt
+
+   :ref:`Learn more about how swupd works <swupd-guide>`.
+
+#. After the process is complete, unmount the root partition:
+
+   .. code-block:: bash
+
+      sudo umount /mnt
+
+#. Reboot the system, remove the live desktop USB drive,
+   and boot into the repaired system.
+
+   .. code-block:: bash
+
+      sudo reboot
+
+**Congratulations!** You successfully restored |CL|.
@@ -45,7 +45,7 @@ Then make changes to the kernel, build it, and install it.
 Install the |CL| development tooling framework
 ==============================================

-.. include:: ../clearlinux/autospec.rst
+.. include:: ../tooling/autospec.rst
   :start-after: install-tooling-after-header:
   :end-before: install-tooling-end:

@@ -262,15 +262,15 @@ set to get a smaller kernel image, which will also be faster to load.
   Look in ~/mixer/update/image/<mix version>/full for the full chroot after the
   :command:`build` command completes.

-#. Build update content. Browse to your http://localhost site and you'll see
+#. Build update content. Browse to your \http://localhost site and you'll see
   the web page is now up, but with no update content. Build the update content:

   .. code-block:: bash

      mixer build update

-   Refresh your http://localhost site and now you can see the update content for
-   mix version 10.
+   Refresh your \http://localhost site and now you can see the update
+   content for mix version 10.

   Look in ~/mixer/update/www/<mix version> to see the update content in your
   workspace.
@@ -333,7 +333,7 @@ set to get a smaller kernel image, which will also be faster to load.

      mixer build delta-packs --from 10 --to 20

-   Refresh your http://localhost site and now you can see the update content for
+   Refresh your \http://localhost site and now you can see the update content for
   mix version 20.

   Look in ~/mixer/update/www/<mix version> to see the update content in your
@@ -16,8 +16,8 @@ Description
 :command:`swupd` has two main functions:

 #. It manages software replacing APT or YUM, installing bundles
-   rather than packages. 
-#. It checks for system updates and installs them. 
+   rather than packages.
+#. It checks for system updates and installs them.

 :ref:`Bundles <bundles>` are the smallest granularity component that is
 managed by |CL| and contain everything needed to deliver a software
@@ -78,7 +78,7 @@ patch to be as small as 15 KB. Using binary deltas, the |CL| is able to
 apply only what is needed.

 To get a more detailed understanding of how to generate update content for
-|CL| see the :ref:`mixer <mixer>` tool. 
+|CL| see the :ref:`mixer <mixer>` tool.

 How it works
 ************
@@ -203,13 +203,13 @@ Example 2: Find and install Kata\* Containers
 Kata Containers is a popular container implementation. Unlike other
 container implementations, each Kata Container has its own
 kernel instance and runs on its own :abbr:`Virtual Machine (VM)` for
-improved security. 
+improved security.

 |CL| makes it very easy to install, since you only need to add
 `one bundle`_ to use `Kata Containers`_: `containers-virt`, despite a
 number of dependencies.  Also, check out our tutorial: :ref:`kata`.

-#. Find the right bundle. 
+#. Find the right bundle.

   * To return all possible matches for the search string enter
     :command:`swupd search`, followed by 'kata':
@@ -223,7 +223,7 @@ number of dependencies.  Also, check out our tutorial: :ref:`kata`.
     .. code-block:: console

        Bundle with the best search result:
-             
+
             containers-virt - Run container applications from Dockerhub in lightweight virtual machines

        This bundle can be installed with:
@@ -231,7 +231,7 @@ number of dependencies.  Also, check out our tutorial: :ref:`kata`.
             swupd bundle-add  containers-virt

        Alternative bundle options are
-             
+
             cloud-native-basic - Contains ClearLinux native software for Cloud

     .. note::
@@ -268,8 +268,8 @@ number of dependencies.  Also, check out our tutorial: :ref:`kata`.
      Calling post-update helper scripts.
      Successfully installed 1 bundle

-Example 3: Verify and correct sytem file mismatch
-=================================================
+Example 3: Verify and correct system file mismatch
+==================================================

 :command:`swupd` can determine whether system directories and files have
 been added to, overwritten, removed, or modified (e.g., permissions).
@@ -334,7 +334,7 @@ swupd --help
   For additional :command:`swupd` commands.

 man swupd
-   To reference the :command:`swupd` man page, or see the 
+   To reference the :command:`swupd` man page, or see the
   `source documentation`_ available on github.

 Related topics
@@ -18,4 +18,3 @@ features.
   compatible-kernels
   system-requirements
   image-types
-   
@@ -208,7 +208,7 @@ other instances available, they are also listed but not selected.

      ssh -i "AWSClearTestKey.pem" clear@ec2-34-209-39-184.us-west-2.compute.amazonaws.com

-#. A message appears on the terminal stating the authenticty of the host can't
+#. A message appears on the terminal stating the authenticity of the host can't
   be established and prompts you with the message:

   .. code-block:: console
@@ -52,7 +52,7 @@ running the individual commands as follows:

 .. code-block:: bash

-   $ python --version
+   python --version

 .. code-block:: console

@@ -60,7 +60,7 @@ running the individual commands as follows:

 .. code-block:: bash

-   $ openssl version
+   openssl version

 .. code-block:: console

@@ -68,7 +68,7 @@ running the individual commands as follows:

 .. code-block:: bash

-   $ ls -l /usr/lib64/libffi*
+   ls -l /usr/lib64/libffi*

 .. code-block:: console

@@ -80,7 +80,7 @@ sysadmin-basic software bundle using the :command:`swupd` command:

 .. code-block:: bash

-   $ sudo swupd bundle-add sysadmin-basic
+   sudo swupd bundle-add sysadmin-basic

 .. note::

@@ -97,7 +97,7 @@ Install MS Azure CLI 2.0 on |CL|

   .. code-block:: bash

-      $ curl -L https://aka.ms/InstallAzureCli | bash
+      curl -L https://aka.ms/InstallAzureCli | bash

   If you get an error message from :command:`curl` related to the -L
   parameter or an error message is generated that includes the text "Object
@@ -105,7 +105,7 @@ Install MS Azure CLI 2.0 on |CL|

   .. code-block:: bash

-      $ curl https://azurecliprod.blob.core.windows.net/install | bash
+      curl https://azurecliprod.blob.core.windows.net/install | bash

 #. The installation script begins and prompts you several times during
   execution for information.
@@ -136,7 +136,7 @@ Install MS Azure CLI 2.0 on |CL|

      ===> Modify profile to update your $PATH and enable shell/tab completion now? (Y/n): Y

-   Type :kbd:`y` and press the :kbd:`Enter` key to allow this modification.
+   Type :kbd:`Y` and press the :kbd:`Enter` key to allow this modification.

   .. code-block:: console

@@ -163,14 +163,14 @@ Install MS Azure CLI 2.0 on |CL|

   .. code-block:: bash

-      $ exec -l $SHELL
+      exec -l $SHELL

 With the MS Azure CLI 2.0 executable successfully built and installed, run
 the :command:`az` command.

 .. code-block:: bash

-   $ az
+   az

 The output from the :command:`az` command is shown below:

@@ -258,7 +258,7 @@ Log into your Microsoft Azure account

   .. code-block:: bash

-      $ az login
+      az login

   The output from this command is:

@@ -317,7 +317,7 @@ of resources within MS Azure.

   .. code-block:: bash

-      $ az group create -n ClearResourceGroup -l westus
+      az group create -n ClearResourceGroup -l westus

 #. When the command has completed, the output from this command is similar to
   the following:
@@ -345,7 +345,7 @@ For this tutorial, we are using the |CL| Basic SKU for our VM.

   .. code-block:: bash

-      $ az vm image list --offer clear-linux --sku basic --all --output table
+      az vm image list --offer clear-linux --sku basic --all --output table

   This command may take some time to finish. The output lists all available
   |CL| Basic images available in the Microsoft Azure marketplace as shown
@@ -384,7 +384,7 @@ For this tutorial, we are using the |CL| Basic SKU for our VM.

   .. code-block:: bash

-      $ az vm create --resource-group ClearResourceGroup --name ClearVM --image clear-linux-project:clear-linux-os:basic:latest --generate-ssh-keys
+      az vm create --resource-group ClearResourceGroup --name ClearVM --image clear-linux-project:clear-linux-os:basic:latest --generate-ssh-keys

   .. note::

@@ -420,7 +420,7 @@ For this tutorial, we are using the |CL| Basic SKU for our VM.

   .. code-block:: bash

-      $ ssh [user]@13.91.4.245
+      ssh [user]@13.91.4.245

   You may see the following message about the authenticity of the host. If
   this appears, type `yes` to proceed connecting to your new |CL| VM.
@@ -436,11 +436,11 @@ For this tutorial, we are using the |CL| Basic SKU for our VM.

   You are now logged into your new |CL| VM as [user], where [user] is your
   user name. To check which software bundles are included with
-   this image, run the :command:`swupd bundle-list` command:
+   this VM image, run the :command:`sudo swupd bundle-list` command inside the VM:

   .. code-block:: bash

-      [user]@ClearVM ~ $ sudo swupd bundle-list
+      sudo swupd bundle-list

   The output shown should be similar to:

@@ -484,7 +484,7 @@ incurring charges for them, you must deallocate the resources as well.

   .. code-block:: bash

-      $ az vm stop --resource-group ClearResourceGroup --name ClearVM
+      az vm stop --resource-group ClearResourceGroup --name ClearVM

   This will stop the VM and then output text similar to:

@@ -503,7 +503,7 @@ incurring charges for them, you must deallocate the resources as well.

   .. code-block:: console

-      $ az vm deallocate --resource-group ClearResourceGroup --name ClearVM
+      az vm deallocate --resource-group ClearResourceGroup --name ClearVM

 **Congratulations!**

@@ -54,9 +54,20 @@ If you need to install the `containers-basic` or `cloud-native-basic`, enter:

   sudo swupd bundle-add containers-basic cloud-native-basic

+Note that docker is not started upon installation of the containers-basic bundle.  To start docker, enter:
+
+
+.. code-block:: bash
+
+   sudo systemctl start docker
+
+
+
 To ensure that Kubernetes is correctly installed and configured, follow
 :ref:`kubernetes`.

+
+
 We have validated these steps against the following software package
 versions:

@@ -87,19 +98,19 @@ TensorFlow.

      Launching the docker image with the :command:`-i` argument will put
      you into interactive mode within the container. You will enter the
-      following commands in the running container.
+      following commands in the running container. The following commands are executed within the scope of the container.

-#. Clone the benchmark repository:
+#. Clone the benchmark repository in the container:

   .. code-block:: bash

-      docker exec -t <docker_name> bash -c 'git clone http://github.com/tensorflow/benchmarks -b cnn_tf_v1.12_compatible'
+      git clone http://github.com/tensorflow/benchmarks -b cnn_tf_v1.12_compatible

 #. Next, execute the benchmark script to run the benchmark.

   .. code-block:: bash

-      docker exec -i <docker_name> bash -c 'python benchmarks/scripts/tf_cnn_benchmarks/tf_cnn_benchmarks.py --device=cpu --model=resnet50 --data_format=NHWC '.
+      python benchmarks/scripts/tf_cnn_benchmarks/tf_cnn_benchmarks.py --device=cpu --model=resnet50 --data_format=NHWC

 .. note::

@@ -277,7 +288,7 @@ Run a TFJob
 This will replicate and deploy three test setups in your Kubernetes cluster.

 Results of Running this Tutorial
-********************************
+================================

 You need to parse the logs of the Kubernetes pod to get the performance
 numbers. The pods will still be around post completion and will be in
@@ -285,6 +296,84 @@ numbers. The pods will still be around post completion and will be in
 benchmark results. More information about `Kubernetes logging`_ is available
 from the Kubernetes community.

+Use Jupyter Notebook
+********************
+
+We will use the `PyTorch with OpenBLAS`_ container image for these steps. Once it is downloaded, run the docker image with :command:`-p` to specify the shared port between the container and the host.  For this example we will use port 8888.
+
+.. code-block:: bash
+
+  docker run --name pytorchtest --rm -i -t -p 8888:8888 clearlinux/stacks-pytorch-oss bash
+
+After you've started the container, you can launch the Jupyter Notebook. This command is executed inside the container image.
+
+.. code-block:: bash
+
+  jupyter notebook --ip 0.0.0.0 --no-browser --allow-root
+
+Once the notebook has loaded, you will see output similar to the following:
+
+.. code-block:: console
+
+   To access the notebook, open this file in a browser: file:///.local/share/jupyter/runtime/nbserver-16-open.html
+   Or copy and paste one of these URLs:
+   http://(846e526765e3 or 127.0.0.1):8888/?token=6357dbd072bea7287c5f0b85d31d70df344f5d8843fbfa09
+
+From your host system, or any system that can access the host's IP address, start a web browser with the following.  If you are not running the browser on the host system, replace :command:`127.0.0.1` with the IP address of the host.
+
+.. code-block:: bash
+
+  http://127.0.0.1:8888/?token=6357dbd072bea7287c5f0b85d31d70df344f5d8843fbfa09
+
+Your browser will display the following:
+
+.. figure:: figures/dlrs-fig-1.png
+   :scale: 50 %
+   :alt: Jupyter Notebook
+
+Figure 1: :guilabel:`Jupyter Notebook`
+
+
+To create a new notebook, click on :guilabel:`New` and select :guilabel:`Python 3`
+
+.. figure:: figures/dlrs-fig-2.png
+   :scale: 50%
+   :alt: Create a new notebook
+
+Figure 2: Create a new notebook
+
+You will be presented with a new, blank notebook, with a cell ready for input.
+
+.. figure:: figures/dlrs-fig-3.png
+   :scale: 50%
+   :alt: New blank notebook
+
+
+To verify that PyTorch is working, copy the following snippet into the blank cell, and run the cell.
+
+  .. code-block:: console
+
+     from __future__ import print_function
+     import torch
+     x = torch.rand(5, 3)
+     print(x)
+
+.. figure:: figures/dlrs-fig-4.png
+   :scale: 50%
+   :alt: Sample code snippet
+
+When you run the cell, your output will look something like this:
+
+.. figure:: figures/dlrs-fig-5.png
+   :scale: 50%
+   :alt: code output
+
+You can continue working in this notebook, or you can download existing notebooks to take advantage of the Deep Learning Reference Stack's optimized deep learning frameworks. More information on `Jupyter Notebook`_.
+
+
+
+
+
 .. _TensorFlow: https://www.tensorflow.org/

 .. _Kubeflow: https://www.kubeflow.org/
@@ -321,3 +410,4 @@ from the Kubernetes community.

 .. _PyTorch benchmark results: https://clearlinux.org/stacks/deep-learning-reference-stack-pytorch

+.. _Jupyter Notebook: https://jupyter.org/
@@ -98,6 +98,8 @@ More information on installing and using  the *kata-runtime* may be found at :re
   need to continue reading. The following sections are provided here for
   sake of completeness.

+.. _additional-docker-configuration:
+
 Additional Docker configuration
 *******************************

@@ -117,13 +119,22 @@ exist by default.
      Refer to the `Docker documentation on daemon configuration`_ for the
      full list of available configuration options and examples.

-      A minimal configuration would be:
+#. For production systems, we follow Docker's recommendation to use the
+   `OverlayFS storage driver`_ `overlay2`, shown below:

-      .. code-block:: json
+   .. code-block:: json

-         {
-            "storage-driver": "devicemapper"
-         }
+      {
+         "storage-driver": "overlay2"
+      }
+
+   .. note::
+
+      A testing version is found in `Docker Device Mapper storage driver`_.
+      If using this storage driver, a warning message may appear: "usage of
+      loopback devices is strongly discouraged for production use".
+
+#. Save and close :file:`daemon.json`.

 #. Once you've made any required changes, be sure to restart the
   Docker daemon through systemd manager by running this command:
@@ -228,3 +239,9 @@ Related topics
 .. _Docker documentation on swarm key concepts: https://docs.docker.com/engine/swarm/key-concepts/

 .. _Docker documentation on creating a swarm: https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/
+
+.. _Configure direct lvm mode for production: https://docs.docker.com/storage/storagedriver/device-mapper-driver/
+
+.. _OverlayFS storage driver: https://docs.docker.com/storage/storagedriver/overlayfs-driver/
+
+.. _Docker Device Mapper storage driver: https://docs.docker.com/storage/storagedriver/device-mapper-driver/
@@ -27,24 +27,14 @@ Before you install any new packages, update |CL| with the following command:
 Install Kata Containers
 ***********************

-Kata Containers is included in the :file:`containers-virt` bundle. To install the
-framework, enter the following command:
+Kata Containers is included in the :file:`containers-virt` bundle.
+To install the framework, enter the following command:

 .. code-block:: bash

   sudo swupd bundle-add containers-virt

-Configure Docker\* to use Kata Containers by default.
-
-.. code-block:: bash
-
-   sudo mkdir -p /etc/systemd/system/docker.service.d/
-   cat <<EOF | sudo tee /etc/systemd/system/docker.service.d/51-runtime.conf
-   [Service]
-   Environment="DOCKER_DEFAULT_RUNTIME=--default-runtime kata-runtime"
-   EOF
-
-Restart the Docker and Kata Containers systemd services.
+Restart the Docker\* and Kata Containers systemd services.

 .. code-block:: bash

@@ -97,10 +87,30 @@ environment:
 You do not need to manually configure the runtime for Docker, because
 it automatically uses the runtime supported by the system.

-Check which runtime your system is using with the command:
+Troubleshooting
+===============

-.. code-block:: bash
+- To change the Docker storage driver, see
+  :ref:`additional-docker-configuration`.
+
+- For some |CL| versions before 27000, you may need to manually
+  configure Docker\* to use Kata Containers by default.
+
+  To do so, enter:
+
+  .. code-block:: bash
+
+     sudo mkdir -p /etc/systemd/system/docker.service.d/
+     cat <<EOF | sudo tee /etc/systemd/system/docker.service.d/50-runtime.conf
+     [Service]
+     Environment="DOCKER_DEFAULT_RUNTIME=--default-runtime kata-runtime"
+     EOF
+
+- To check the version of |CL| on your system, enter:
+
+  .. code-block:: bash
+
+     sudo swupd verify

-   sudo docker info | grep runtime

 .. _Kata Containers: https://katacontainers.io/
@@ -239,6 +239,11 @@ Read the Kubernetes documentation to learn more about:

 * `Joining your nodes`_

+Cloud native setup automation (optional)
+****************************************
+
+Clone the `cloud-native-setup`_ repository on your system and follow the instructions. This repository includes helper scripts to automate configuration.
+
 Package configuration customization (optional)
 **********************************************

@@ -405,3 +410,5 @@ Troubleshooting

 .. _documentation: https://clearlinux.org/documentation/clear-linux

+.. _cloud-native-setup: https://github.com/clearlinux/cloud-native-setup
+
@@ -31,8 +31,7 @@ Install the LTS kernel and DKMS
 *******************************

 The Long Term Support (LTS) kernel variant is most likely to remain
-compatible with NVIDIA drivers. The `Dynamic Kernel Module System (DKMS)
-<kernel-modules-dkms>`_ allows the NVIDIA kernel modules to be automatically
+compatible with NVIDIA drivers. The :ref:`Dynamic Kernel Module System (DKMS) <kernel-modules-dkms>` allows the NVIDIA kernel modules to be automatically
 integrated when kernel updates occur in |CL|. Install both using the
 instructions below:

@@ -0,0 +1,80 @@
+.. _smb-desktop:
+
+Connect to Windows\* shared location from |CL-ATTR| desktop
+###########################################################
+
+This tutorial explains how to access an existing shared drive on
+Windows\* via Server Message Block (SMB) / Common Internet File System (CIFS)
+from the |CL| GNOME desktop.  CIFS filesystem is generally used to access
+shared storage locations, or share files.
+
+Prerequisites
+*************
+
+* You have already `set up a shared location on Windows`_
+
+Connect to Windows shared location with Nautilus
+************************************************
+
+#. From the desktop, select :guilabel:`Files` from the application menu.
+
+   .. note::
+
+   	  GNOME Files is also known as `Nautilus`.
+
+#. In :guilabel:`Files`, select :guilabel:`Other Locations`.
+
+   .. figure:: figures/smb-desktop-1.png
+      :scale: 100%
+      :alt: Files, Other Locations
+
+      Figure 1: Files, Other Locations
+
+#. In the lower taskbar, beside :guilabel:`Connect to Server`,
+   enter the file-sharing address using the Windows sharing schema:
+
+   .. code-block:: bash
+
+	    smb://servername/Share
+
+   .. figure:: figures/smb-desktop-2.png
+      :scale: 100%
+      :alt: Connect to Server
+
+      Figure 2: Connect to Server
+
+#. Optional: If there are issues with DNS, you can use an IP address in
+   place of the `servername` above. You must still specify the share.
+
+#. Optional: On the Windows machine, in a CLI, retrieve the IP address by
+   entering the command:
+
+   .. code-block:: bash
+
+      ifconfig
+
+   .. note::
+
+      If using the IP address, assure that it is accessible and secure.
+
+#. Select :guilabel:`Connect`.
+
+#. The server will request authentication, as shown in Figure 3.
+
+   .. figure:: figures/smb-desktop-3.png
+      :scale: 100%
+      :alt: Authentication
+
+      Figure 3: Authentication
+
+#. Log in with the same Windows system credentials for which you granted
+   access to the share.
+
+#. Select the appropriate checkbox to save your credentials. Consider
+   carefully the security risks as a result of your selection.
+
+
+.. _set up a shared location on Windows: https://www.howtogeek.com/176471/how-to-share-files-between-windows-and-linux/
+
+
+
@@ -3,13 +3,6 @@
 Tutorials
 #########

-This section offers a range of tutorials that demonstrate:
-
-* |CL-ATTR| features for cloud, client, distributed processing,
-  and virtual environments
-* Use of |CL| with third-party tools
-* Development possibilities of |CL| with specific use cases
-
 Explore our tutorials to discover what you can do with |CL|!

 .. toctree::
@@ -25,12 +18,12 @@ Explore our tutorials to discover what you can do with |CL|!
   hadoop
   fmv
   aws-web/aws-web
-   smb/smb
+   smb/smb*
   spark
   kata
   kata_migration
   kubernetes/kubernetes*
   greengrass
-   dlrs
+   dlrs/dlrs
   yubikey-u2f
   nvidia
@@ -74,7 +74,7 @@ YubiKey with Linux

   .. code:: bash
      
-      sudo udevadm control --reload-rules && udevadm trigger
+      sudo udevadm control --reload-rules && sudo udevadm trigger


 #. Plugin and validate the YubiKey appears as a USB device:
@@ -1,2 +1,2 @@
-Jinja2==2.10
+Jinja2==2.11.dev0
 GitPython==2.1.11