Create greetings.yml

Create a greetings message to show users who submit their first Issue or first PR to the repo.

.github/workflows/greetings.yml

@@ -0,0 +1,13 @@
+name: Greetings
+
+on: [pull_request, issues]
+
+jobs:
+  greeting:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/first-interaction@v1
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        issue-message: 'Welcome to Clear Linux OS Docs. Thanks for submitting your first issue. :thumbsup:'
+        pr-message: 'Welcome to Clear Linux OS Docs. Thanks for submitting your first PR. :thumbsup:'

README.rst

@@ -65,7 +65,7 @@ to view the rendered documentation.
 
 If you want to build the documentation exactly as seen on the website, use
 ``make py`` followed by ``make htmlall``. This builds some
-external dependenices and all supported languages.
+external dependencies and all supported languages.
 
 Additional help
 ***************
@@ -98,6 +98,6 @@ To stop the web server simply use ``ctrl-c``.
 .. _Clear Linux\* OS documentation:  https://docs.01.org/clearlinux/
 .. _Sphinx: http://sphinx-doc.org/
 .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
-.. _contribution guidelines: https://clearlinux.org/documentation/clear-linux/reference/collaboration
+.. _contribution guidelines: https://docs.01.org/clearlinux/latest/collaboration/collaboration.html
 .. _instructions for installing Sphinx: https://www.sphinx-doc.org/en/master/usage/installation.html
 

source/FAQ/index.rst

@@ -16,7 +16,7 @@ Why did you make another distro?
 ================================
 
 The |CL| team felt that performance was left on the table with Linux software.
-|CL| takes a holistic approach to improving performance across the stack. We
+|CL| takes a holistic approach to improve performance across the stack. We
 also wanted to take more modern approaches with OS updates and tooling.
 
 |
@@ -31,7 +31,7 @@ Yes, we absolutely love open source reuse and upstreaming improvements.
 How often do you update?
 ========================
 
-The |CL| team puts out multiple releases a week, often releasing 2 or more
+The |CL| team puts out multiple releases a week, often releasing two or more
 times a day. This rolling release approach allows |CL| to remain agile to
 upstream changes and security patches.
 
@@ -137,7 +137,7 @@ Is Microsoft\* Visual Studio Code\* available?
 
 Yes. Find the CLI command for installing `VS Code`_ and other Flatpak apps in
 the `software store`_. Installing Flatpak apps is also covered in our
-:ref:`tutorial <flatpak-tutorial>`. 
+:ref:`tutorial <flatpak-tutorial>`.
 
 The |CL| team is working on a natively packaged version of Visual Studio Code
 for future release.

source/_scripts/_python/linkcheck/link-whitelist.txt

@@ -12,4 +12,8 @@ https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html
 http://www.intel.com/content/www/us/en/nuc/nuc-kit-nuc6i5syh.html
 https://software.intel.com/en-us/mkl
 https://www.intel.com/content/www/us/en/architecture-and-technology/turbo-boost/turbo-boost-technology.html
-https://www.nvidia.com/download/index.aspx
+https://www.nvidia.com/download/index.aspx
+https://www.intel.com/content/www/us/en/architecture-and-technology/optane-technology/optane-for-data-centers.html
+https://downloadcenter.intel.com/download/28695/Intel-Server-Board-S2600WF-Family-BIOS-and-Firmware-Update-Package-for-UEFI
+https://software.intel.com/en-us/articles/quick-start-guide-configure-intel-optane-dc-persistent-memory-on-linux
+https://software.intel.com/en-us/articles/configure-manage-and-profile-intel-optane-dc-persistent-memory-modules

source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css

@@ -175,7 +175,7 @@ th,td {
 
 .content-collapse {
   overflow: hidden;
-  transition: max-height 0.2s ease-out;
+  /*transition: max-height 0.2s ease-out;*//*removed as it was breaking nested collapsible sections*/
 }
 
 /*Fix for permalinks to collapsible sections*/
@@ -374,7 +374,16 @@ div.highlight-console .highlight:before{
   white-space: pre;
 }
 
-div.highlight-rst, div.highlight-rest .highlight:before{
+div.highlight-rst .highlight:before{
+  background: #909090;
+  color: white;
+  content: " reStructuredText ";
+  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
+  font-size: 14px;
+  white-space: pre;
+}
+
+div.highlight-rest .highlight:before{
   background: #909090;
   color: white;
   content: " reStructuredText ";
@@ -471,3 +480,43 @@ div.linenodiv:before { /*add extra new line to make sure code and line numbers a
 
 /*End support for labeled code-blocks*/
 
+/*Begin support for multi-column sections*/
+
+.column {
+  float: left;
+  width: 350px;
+  padding: 10px;
+  margin: 10px;
+  border: 10px;
+  background: white;
+}
+
+.column.featurecard {
+  background: #CCE9F5;
+}
+
+.column.verticalcard {
+  height: 615px;
+  overflow: auto;
+}
+
+/* Clear floats after the columns */
+.multicolumns:after {
+  content: "";
+  display: table;
+  clear: both;
+}
+
+.colh2 {
+  font-size: 150%;
+  font-weight: 700;
+  font-family: "Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif;
+}
+
+.video.docutils.container {
+  margin: 10px;
+  width:720px;
+  height:405px;
+}
+
+/*End support for multi-column sections*/

source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.js

@@ -1,60 +1,76 @@
-var i;
-var contents = document.getElementsByClassName("content-collapse section");
-
-var bashDollarDivs = document.getElementsByClassName("bash-dollars highlight-bash"); 
-
-for (i = 0; i< bashDollarDivs.length; i++) {
-    _pre = bashDollarDivs[i].querySelectorAll("pre");
-    for (j = 0; j < _pre.length; j++) {
-      console.log(_pre[j]);
-      _pre[j].innerHTML="<span class='bash-dollar'>"+(_pre[j].textContent.split("\n").filter(Boolean).join("</span>\n<span class='bash-dollar'>"))+"</span>";
-    }
-}
-
-for (i = 0; i < contents.length; i++) {
-
-  //Make sure the "content-collapse section" class is occurring in <div>
-  if (contents[i].tagName.toLowerCase() == 'div') {
-    var element = contents[i].children[0];
-    var element_type = element.tagName.toLowerCase();
-    var btn_id;
-    var divElement;
-
-    divElement = contents[i];
-    btn_id = contents[i].id;
-
-    //if the next element is a span skip to the header
-    if (element_type == 'span') {
-      element = contents[i].children[1];
-      element_type = element.tagName.toLowerCase();
-    } else {
-      divElement.id = "";
-    }
-
-    var btn = document.createElement("BUTTON");
-    //If it is a header capture which level and pass on to button
-    if (element_type.length == 2 && element_type[0] == 'h') {
-      var newClass = 'clps' + element_type[1];
-      //collapses the section by default only if javascript is working
-      contents[i].style.maxHeight = 0;
-      //Build the button and define behavior
-      btn.className += " " + newClass;
-      btn.innerHTML = element.innerHTML;
-      btn.className += " collapsible";
-      btn.id = btn_id;
-      btn.addEventListener("click", function() {
-        this.classList.toggle("active");
-        var content = this.nextElementSibling;
-        if (content.style.maxHeight != "0px"){
-          content.style.maxHeight = 0;
-        } else {
-          content.style.maxHeight = content.scrollHeight + "px";
-        } 
-      });
-
-      //Add the button to the page and remove the header
-      contents[i].parentNode.insertBefore(btn, contents[i]);
-      contents[i].removeChild(element);
-    }
-  }
-}
+var i;
+var contents = document.getElementsByClassName("content-collapse section");
+
+var bashDollarDivs = document.getElementsByClassName("bash-dollars highlight-bash"); 
+
+for (i = 0; i< bashDollarDivs.length; i++) {
+    _pre = bashDollarDivs[i].querySelectorAll("pre");
+    for (j = 0; j < _pre.length; j++) {
+      console.log(_pre[j]);
+      _pre[j].innerHTML="<span class='bash-dollar'>"+(_pre[j].textContent.split("\n").filter(Boolean).join("</span>\n<span class='bash-dollar'>"))+"</span>";
+    }
+}
+
+//needed for nested collapsible sections - otherwise the top container 
+//won't resize after expanding a child.
+function resetActiveCollapsedSections() {
+
+  var sections = document.getElementsByClassName("content-collapse section");
+
+  //for (i = 0; i < sections.length; i++) {
+  for (i = sections.length -1; i >= 0; i-- ){
+
+    if (sections[i].style.maxHeight != "0px"){
+       sections[i].style.maxHeight = sections[i].scrollHeight + "px";
+    }
+  }
+}
+
+for (i = 0; i < contents.length; i++) {
+
+  //Make sure the "content-collapse section" class is occurring in <div>
+  if (contents[i].tagName.toLowerCase() == 'div') {
+    var element = contents[i].children[0];
+    var element_type = element.tagName.toLowerCase();
+    var btn_id;
+    var divElement;
+
+    divElement = contents[i];
+    btn_id = contents[i].id;
+
+    //if the next element is a span skip to the header
+    if (element_type == 'span') {
+      element = contents[i].children[1];
+      element_type = element.tagName.toLowerCase();
+    } else {
+      divElement.id = "";
+    }
+
+    var btn = document.createElement("BUTTON");
+    //If it is a header capture which level and pass on to button
+    if (element_type.length == 2 && element_type[0] == 'h') {
+      var newClass = 'clps' + element_type[1];
+      //collapses the section by default only if javascript is working
+      contents[i].style.maxHeight = 0;
+      //Build the button and define behavior
+      btn.className += " " + newClass;
+      btn.innerHTML = element.innerHTML;
+      btn.className += " collapsible";
+      btn.id = btn_id;
+      btn.addEventListener("click", function() {
+        this.classList.toggle("active");
+        var content = this.nextElementSibling;
+        if (content.style.maxHeight != "0px"){
+          content.style.maxHeight = 0;
+        } else {
+          content.style.maxHeight = content.scrollHeight + "px";
+        } 
+        resetActiveCollapsedSections(); //reset the size of parent containers
+      });
+
+      //Add the button to the page and remove the header
+      contents[i].parentNode.insertBefore(btn, contents[i]);
+      contents[i].removeChild(element);
+    }
+  }
+}

source/about.rst

@@ -44,7 +44,7 @@ Ease of Use
   environments without needing to be configured.
 
 * Being :ref:`stateless` means that configuration settings are easier to manage
-  and remain untouched when system sofware is updated.
+  and remain untouched when system software is updated.
 
 * :ref:`swupd-guide` simplifies managing software and maintaining compatibility.
 

source/collaboration/structure-formatting.rst

@@ -55,7 +55,7 @@ For example, the :ref:`collaboration` page toctree looks like:
 Additionally, each page must include a uniquely named reST label directly before
 the page title, to enable the `Sphinx ref role`_ for linking to a page.
 
-For example, this page "Structure and formating" has the label
+For example, this page "Structure and formatting" has the label
 ``.. _structure-formatting``:
 
 .. code-block:: rest

source/collaboration/writing-guide.rst

@@ -18,7 +18,7 @@ Use simple English
 
 Write using simple English: Be brief and communicate only the information that
 is needed. Be friendly and informative. Emphasize clarity and avoid
-unecessary complicated or technical terms. Make the content accessible to
+unnecessary complicated or technical terms. Make the content accessible to
 non-native speakers.
 
 Be brief
@@ -93,7 +93,7 @@ what they need quickly, and to understand the information more efficiently.
   document first, and organize supporting information towards the end of the
   page.
 * **Write scannable headings.** Expect readers of documentation to skim and scan
-  the content, and to leave if they dont find what they need quickly. Good
+  the content, and to leave if they don't find what they need quickly. Good
   headings add organization to your content and help the reader to find and
   understand content more effectively. Follow our guidelines for writing
   effective `Headings`_.

source/get-started/bare-metal-install-desktop.rst

@@ -19,6 +19,8 @@ installation:
 * :ref:`system-requirements`
 * :ref:`compatibility-check`
 
+.. _preliminary-steps-install-desktop:
+
 Preliminary steps
 *****************
 
@@ -56,6 +58,8 @@ these steps.
 
 #. Reboot the target system.
 
+.. _preliminary-steps-install-desktop-end:
+
 #. Select :guilabel:`Clear Linux OS` in the boot menu, shown in Figure 1.
 
    .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-01.png

source/get-started/bare-metal-install-server.rst

@@ -468,6 +468,99 @@ be configured post-installation using the ``cryptsetup`` tool.
 
       :guilabel:`Confirm` is only highlighted if passphrases match.
 
+Manage User
+===========
+
+Add New User
+------------
+
+#. In Required Options, select :guilabel:`Manage User`.
+
+#. Select :guilabel:`Add New User` as shown in Figure 18.
+
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-18.png
+      :scale: 100%
+      :alt: Add New User, User Name
+
+      Figure 18: Add New User
+
+#. Optional: Enter a :guilabel:`User Name`.
+
+   .. note:
+
+      The User Name must be alphanumeric and can include spaces, commas, underscores or hyphens. Maximum length is 64 characters.
+
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-19.png
+      :scale: 100%
+      :alt: User Name
+
+      Figure 19: User Name
+
+#. Enter a :guilabel:`Login`.
+
+   .. note::
+
+      The User Login must be alphanumeric and can include hyphens and underscores. Maximum length is 31 characters.
+
+#. Enter a :guilabel:`Password`.
+
+   .. note:
+
+      Minimum length is 8 characters. Maximum length is 255 characters.
+
+#. In :guilabel:`Confirm`, enter the same password.
+
+#. The :guilabel:`Administrator` checkbox is selected by default.
+
+   .. note::
+
+      Selecting Administrator enables sudo privileges for the user. For the installation to proceed, at least one user must be assigned as an Administrator.
+
+#. Select :kbd:`Confirm`. To reset the form, select :guilabel:`Reset`.
+
+#. In :guilabel:`Manage User`, navigate to :guilabel:`Confirm`.
+
+#. With :guilabel:`Confirm` highlighted, select :kbd:`Enter`.
+
+Modify / Delete User
+--------------------
+
+#. In :guilabel:`Manage User`, navigate to the user you wish
+   to modify until highlighted, as shown in Figure 20.
+
+#. Select :kbd:`Enter` to modify the user.
+
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-20.png
+      :scale: 100%
+      :alt: Modify User
+
+      Figure 20: Modify User
+
+#. Modify user details as desired.
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+   .. note::
+
+      Optional: Select :guilabel:`Reset` to rest the form.
+
+#. Select :guilabel:`Confirm` to save the changes you made.
+
+#. Optional: In :guilabel:`Modify User`, to delete the user, navigate to
+   the :guilabel:`Delete` button and select :kbd:`Enter`.
+
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-21.png
+      :scale: 100%
+      :alt: Delete User
+
+      Figure 21: Delete User
+
+You are returned to :guilabel:`Manage User`.
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+#. Select :guilabel:`Enter` to complete :guilabel:`Manage User` options.
+
 Telemetry
 =========
 
@@ -483,19 +576,18 @@ Select your desired option on whether to participate in telemetry.
 
 #. Select :kbd:`Enter` to confirm.
 
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-18.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-22.png
       :scale: 100%
       :alt: Enable Telemetry
 
-      Figure 18: Enable Telemetry
+      Figure 22: Enable Telemetry
 
 Recommended options
 *******************
 
 After you complete the `Required options`_, we highly recommend completing
-these selected `Advanced options`_ at minimum:
+some `Advanced options`_:
 
-* `Manage User`_ Assign a new user with administrative rights
 * `Assign Hostname`_ Simplify your development environment
 
 Skip to finish installation
@@ -533,22 +625,22 @@ interface settings are automatically applied.
 
    .. note:: Multiple network interfaces may appear.
 
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-19.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-23.png
       :scale: 100%
       :alt: Configure Network Interfaces
 
-      Figure 19: Configure Network Interfaces
+      Figure 23: 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-server/bare-metal-install-server-20.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-24.png
       :scale: 100%
       :alt: Network interface configuration
 
-      Figure 20: Network interface configuration
+      Figure 24: Network interface configuration
 
 #. Navigate to the appropriate fields and assign the desired
    network configuration.
@@ -584,11 +676,11 @@ instruction.
 
 #. Navigate to the field :guilabel:`HTTPS Proxy`.
 
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-21.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-25.png
       :scale: 100%
       :alt: Configure the network proxy
 
-      Figure 21: Configure the network proxy
+      Figure 25: Configure the network proxy
 
 #. Enter the desired proxy address and port using conventional syntax,
    such as: \http://address:port.
@@ -609,13 +701,13 @@ select :guilabel:`Test Network Settings` and select :guilabel:`Enter`.
 .. note::
    If using the :command:`off-line installer`, this option is not available.
 
-A progress bar appears as shown in Figure 22.
+A progress bar appears as shown in Figure 26.
 
-.. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-22.png
+.. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-26.png
    :scale: 100%
    :alt: Testing Networking dialog
 
-   Figure 22: Testing Networking dialog
+   Figure 26: Testing Networking dialog
 
 .. note::
 
@@ -636,11 +728,11 @@ Bundle selection is disabled if no network connection exists.
 
 #. Select :kbd:`Spacebar` to select the checkbox for each desired bundle.
 
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-23.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-27.png
       :scale: 100%
       :alt: Bundle Selection
 
-      Figure 23: Bundle Selection
+      Figure 27: Bundle Selection
 
 #. Optional: To start developing with |CL|, we recommend
    adding :file:`os-clr-on-clr`.
@@ -651,107 +743,6 @@ Bundle selection is disabled if no network connection exists.
 
 Optional: Skip to `Finish installation`_.
 
-Manage User
-===========
-
-Add New User
-------------
-
-#. In Advanced Options, select :guilabel:`Manage User`.
-
-#. Select :guilabel:`Add New User` as shown in Figure 24.
-
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-24.png
-      :scale: 100%
-      :alt: Add New User, User Name
-
-      Figure 24: Add New User
-
-#. Optional: Enter a :guilabel:`User Name`.
-
-   .. note:
-
-      The User Name must be alphanumeric and can include spaces, commas, or
-      hyphens. Maximum length is 64 characters.
-
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-25.png
-      :scale: 100%
-      :alt: User Name
-
-      Figure 25: User Name
-
-#. Enter a :guilabel:`Login`.
-
-   .. note::
-
-      The User Login must be alphanumeric and can include hyphens and underscores. Maximum length is 31 characters.
-
-#. Enter a :guilabel:`Password`.
-
-   .. note:
-
-      Minimum length is 8 characters. Maximum length is 255 characters.
-
-#. In :guilabel:`Confirm`, enter the same password.
-
-#. Optional: Navigate to the :guilabel:`Administrative` checkbox and select
-   :kbd:`Spacebar` to assign administrative rights to the user.
-
-   .. note::
-
-      Selecting this option enables sudo privileges for the user.
-
-#. Select :kbd:`Confirm`.
-
-   .. note::
-
-      If desired, select :guilabel:`Reset` to reset the form.
-
-#. In :guilabel:`Manage User`, navigate to :guilabel:`Confirm`.
-
-#. With :guilabel:`Confirm` highlighted, select :kbd:`Enter`.
-
-Modify / Delete User
---------------------
-
-#. In :guilabel:`Manage User`, navigate to the user you wish
-   to modify until highlighted, as shown in Figure 26.
-
-#. Select :kbd:`Enter` to modify the user.
-
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-26.png
-      :scale: 100%
-      :alt: Modify User
-
-      Figure 26: Modify User
-
-#. Modify user details as desired.
-
-#. Navigate to :kbd:`Confirm` until highlighted.
-
-   .. note::
-
-      Optional: Select :guilabel:`Reset` to rest the form.
-
-#. Select :guilabel:`Confirm` to save the changes you made.
-
-#. Optional: In :guilabel:`Modify User`, to delete the user, navigate to
-   the :guilabel:`Delete` button and select :kbd:`Enter`.
-
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-27.png
-      :scale: 100%
-      :alt: Delete User
-
-      Figure 27: Delete User
-
-You are returned to :guilabel:`Manage User`.
-
-#. Navigate to :kbd:`Confirm` until highlighted.
-
-#. Select :guilabel:`Enter` to complete :guilabel:`Manage User` options.
-
-Optional: Skip to `Finish installation`_.
-
 Kernel Command Line
 ===================
 
@@ -849,7 +840,7 @@ Optional: Skip to `Finish installation`_.
 Automatic OS Updates
 ====================
 
-Automatical OS updates are enabled by default. In the rare case that you
+Automatic OS updates are enabled by default. In the rare case that you
 need to disable automatic software updates, follow the onscreen instructions,
 shown in Figure 32.
 

source/get-started/compatibility-check.rst

@@ -4,7 +4,7 @@ Check processor and EFI firmware compatibility
 ##############################################
 
 Before installing |CL-ATTR|, check your host system's processor and EFI firmware
-compatibility. To check compatibilty, choose one of the following paths:
+compatibility. To check compatibility, choose one of the following paths:
 
 * From a system with a Linux\* OS installed, follow the instructions to :ref:`check-compatibility-steps`.
 

source/get-started/index.rst

@@ -4,7 +4,7 @@ Get started
 ###########
 
 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.
+|CL-ATTR|. Follow these step-by-step instructions to get started with |CL|, fast.
 
 Pre-install
 ***********
@@ -15,7 +15,7 @@ There are a couple of things to take care of before you install.
 * :ref:`compatibility-check`
 * :ref:`bootable-usb`
 
-When installing |CL-ATTR| in a VM, consider which kernel to use. 
+When installing |CL-ATTR| in a VM, consider which kernel to use.
 
 * :ref:`Compatible VM kernels <vm-kernels>`
 
@@ -55,4 +55,4 @@ Deploy to the cloud
    :maxdepth: 1
    :glob:
 
-   cloud-install/*
+   cloud-install/*

source/get-started/virtual-machine-install/hyper-v.rst

@@ -4,7 +4,7 @@
 ################################
 
 This page explains how to run a |CL-ATTR| :abbr:`VM (virtual machine)` on a
-a Microsoft Hyper-V\* hypervisor.
+Microsoft\* Hyper-V\* hypervisor.
 
 .. contents::
    :local:
@@ -15,41 +15,41 @@ Overview
 ********
 
 Hyper-V is a type 1 bare-metal hypervisor that runs directly on system
-hardware.
+hardware. It is available for `Windows\* server`_ and client operating systems,
+including `Windows 10`_.
 
-Hyper-V is available both on server and client Windows operating systems as
-`Hyper-V on Windows Server`_ and `Hyper-V on Windows 10`_.
+|CL| provides a virtual disk image for Hyper-V, which also includes
+a :ref:`Hyper-V specific kernel <compatible-kernels>` and drivers.
 
 Prerequisites
 *************
 
-* Enable virtualization, such as `Intel® Virtualization Technology`_
-  (Intel® VT) and `Intel® Virtualization Technology for Directed I/O`_ (Intel®
-  VT-d), on the host system from EFI/BIOS.
+* Enable virtualization on the host system from EFI/BIOS, such as:
 
-* Hyper-V installed on a capable Windows operating system. Refer to the
-  Microsoft documentation on `Install the Hyper-V role on Windows Server`_ or
-  `Install Hyper-V on Windows 10`_.
+  * `Intel® Virtualization Technology`_ (Intel® VT)
+  * `Intel® Virtualization Technology for Directed I/O`_ (Intel® VT-d)
 
-* Configure appropriate virtual networking in Hyper-V. Refer to the Microsoft
-  documentation on `Create a virtual network on Window Server`_ or `Create a
-  virtual network on Window 10`_.
+* Install Hyper-V on the appropriate Windows operating system:
+
+  * `Install the Hyper-V role on Windows Server`_
+  * `Install Hyper-V on Windows 10`_
+
+* Configure the appropriate virtual networking in Hyper-V:
+
+  * `Create a virtual network on Windows Server`_
+  * `Create a virtual network on Windows 10`_
 
 
 Download the |CL| disk image for Hyper-V
 ****************************************
 
-|CL| provide a virtual disk image for Hyper-V with |CL| pre-installed. This
-includes a |CL| :ref:`Hyper-V specific kernel <compatible-kernels>` with
-Hyper-V Linux drivers ready-to-go. Get the latest |CL| image for Microsoft*
-Hyper-V from the `downloads`_ website. The file is named
-:file:`clear-[VERSION]-hyperv.vhdx.gz`.
+#. Download the :file:`clear-[VERSION]-hyperv.vhdx.gz` for Microsoft* Hyper-V
+   from the `downloads`_ website.
 
-We also provide instructions for downloading and verifying a Clear Linux
-images. For more information, refer to :ref:`download-verify-decompress`.
+#. Verify and extract the image using these instructions:
+   :ref:`download-verify-decompress`.
 
-After extraction, the file should be named
-:file:`clear-[VERSION]-hyperv.vhdx`.
+   After extraction, the file should be named :file:`clear-[VERSION]-hyperv.vhdx`.
 
 
 Create and configure new VM
@@ -64,9 +64,8 @@ Create and configure new VM
    Figure 1: Hyper-V Manager from the Start menu
 
 
-#. Create a *New Virtual Machine* by clicking the :guilabel:`Action` menu and
-   selecting the :guilabel:`New` submenu, and selecting :guilabel:`Virtual
-   Machine...`.
+#. Create a *New Virtual Machine* by clicking the :guilabel:`Action` menu,
+   then selecting :guilabel:`New` and :guilabel:`Virtual Machine...`.
 
    .. figure:: figures/hyper-v/hyper-v-02.png
       :scale: 100%
@@ -77,54 +76,55 @@ Create and configure new VM
 #. Follow the *New Virtual Machine Wizard* to create a new virtual machine
    specifying the options below:
 
-   - **Name**: Choose name (e.g. ClearLinuxOS-VM).
+   - **Name**: Choose name (for example, ClearLinuxOS-VM)
    - **Generation**: Generation 2
    - **Startup memory**: 2048 MB or more
-   - **Connect Virtual Hard Disk**: select :guilabel:`Use an existing virtual
+   - **Connect Virtual Hard Disk**: Select :guilabel:`Use an existing virtual
      hard disk` and browse to find the :file:`clear-[VERSION]-hyperv.vhdx`
      file.
 
    After finishing the wizard, the VM will be created but not powered on.
 
-#. Go to *Virtual Machine Settings* by right-clicking the newly created |CL|
-   VM in the Hyper-V Manager and selecting :guilabel:`Settings...`
+#. Configure the VM by right-clicking it in the Hyper-V Manager and selecting
+   :guilabel:`Settings...`.
+   Figure 3 shows the Settings page after configuration selections.
 
    - Under :guilabel:`Firmware`, select the Virtual disk and click
-     :guilabel:`Move Up...` until it is at the top of the list. 
+     :guilabel:`Move Up...` until it is at the top of the list.
 
    - Under :guilabel:`Security`, uncheck the :guilabel:`Enable Secure Boot`
      checkbox.
 
    - Under :guilabel:`Processor`, consider increasing the number of virtual
-     processors assigned to the |CL| VM for performance.
+     processors assigned to the |CL| VM to improve performance.
 
    .. figure:: figures/hyper-v/hyper-v-03.png
       :scale: 100%
       :alt: |CL| VM Settings in Hyper-V Manager
 
-   Figure 3: |CL| VM Settings page after selections
+   Figure 3: |CL| VM Settings page after configuration
 
 #. Click :guilabel:`Apply` at the bottom of the VM Settings screen.
 
-#. Click :guilabel:`OK` at the bottom of the VM Setting screen.
+#. Click :guilabel:`OK` at the bottom of the VM Settings screen.
 
 
 Start the VM
 ************
 
 #. Start the |CL| VM by right-clicking the VM in Hyper-V Manager and selecting
-   :guilabel:`Start`
+   :guilabel:`Start`.
 
 #. Connect to the VM console by right-clicking the VM in Hyper-V Manager and
    selecting :guilabel:`Connect...`. A new *Virtual Machine Connection* window
-   will appear.
+   is displayed.
 
-#. After |CL| is booted, login to the console with user *root*. You will be
-   prompted to set a new password immediately. 
+#. After |CL| is booted, log in to the console with user *root*. You are
+   prompted to set a new password immediately.
 
    .. code-block:: console
 
-      > User: root   
+      > User: root
 
 |CL-ATTR| on Microsoft Hyper-V\* is ready for use.
 
@@ -135,13 +135,13 @@ Related topics
 
 
 
-.. _`Hyper-V on Windows Server`: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/hyper-v-on-windows-server
-.. _`Hyper-V on Windows 10`: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/index
+.. _`Windows\* Server`: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/hyper-v-on-windows-server
+.. _`Windows 10`: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/index
 .. _`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
 .. _`Install the Hyper-V role on Windows Server`: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/get-started/install-the-hyper-v-role-on-windows-server
 .. _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 on Window Server`: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/get-started/create-a-virtual-switch-for-hyper-v-virtual-machines
-.. _`Create a virtual network on Window 10`: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/connect-to-network
+.. _`Create a virtual network on Windows Server`: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/get-started/create-a-virtual-switch-for-hyper-v-virtual-machines
+.. _`Create a virtual network on Windows 10`: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/connect-to-network
 .. _downloads: https://clearlinux.org/downloads
 

source/get-started/virtual-machine-install/virt-manager.rst

@@ -0,0 +1,223 @@
+.. _virt-manager:
+
+|CL-ATTR| using virt-manager
+############################
+
+This page explains how to create a |CL-ATTR| virtual machine using the
+`virt-mgr`_ desktop application with |CL| as the guest operating system.
+These instructions support the |CL| live-server installer to create the |CL|
+:abbr:`VM (Virtual Machine)`.
+
+.. contents::
+   :local:
+   :depth: 1
+
+Prerequisites
+*************
+
+#. Enable virtualization, such as `Intel® Virtualization Technology`_
+   (Intel® VT), on the host system from the UEFI firmware setup.
+
+#. Install the software bundles kvm-host and virt-manager-gui using
+   :command:`swupd`:
+
+   .. code-block:: bash
+
+      sudo swupd bundle-add kvm-host virt-manager-gui
+
+#. Add your userid to the `kvm` and `libvirt` groups.
+
+   .. code-block:: bash
+
+      sudo usermod -G kvm -a $USER
+      sudo usermod -G libvirt -a $USER
+
+#. Enable the `libvirtd` daemon and reboot the system to complete the
+   process.
+
+   .. code-block:: bash
+
+      sudo systemctl enable libvirtd
+      sudo reboot
+
+
+Download the |CL| installer ISO
+*******************************
+
+There are several options available to set up and use a |CL| VM with
+:command:`virt-manager`. You can either download the `KVM` image and run it
+as-is or download the installer ISO and run it to create a new installation of
+|CL|.
+
+This example uses the live-server-installer ISO to create a new installation.
+
+#. Download the `Clear Linux* OS Server` from the `Downloads`_ page.
+
+#. (Optional) Validate the integrity of the downloaded image by checking the
+   file hash and signatures. Refer to :ref:`validate-signatures` for detailed
+   steps.
+
+Launch and set up virt-manager
+******************************
+
+Virt-manager is a GUI-based virtual machine manager that runs in your desktop
+environment. This example uses the Gnome\* desktop.
+
+#. Launch the Virtual Machine Manager from the applications window. The
+   application window opens as shown in Figure 1.
+
+   .. figure:: figures/virtmgr/virt-manager-01.png
+      :scale: 100%
+      :alt: Virtual Machine Manager
+
+      Figure 1: Virtual Machine Manager
+
+#. In the `Name` field, select and highlight the `QEMU/KVM` item, then select
+   :menuselection:`Edit > Connection Details`. A dialog box with
+   `QEMU/KVM Connection Details` opens as shown in Figure 2.
+
+   .. figure:: figures/virtmgr/virt-manager-02.png
+      :scale: 100%
+      :alt: QEMU/KVM Connection Details
+
+      Figure 2: QEMU/KVM Connection Details
+
+#. On the `Overview` tab, check the `Autoconnect` field. Select the `Virtual
+   Networks` tab and in the lower left of the dialog window, select the
+   :guilabel:`+` key to add a new network connection. The `Create a new virtual
+   network` dialog window opens as shown in Figure 3. To accept the default
+   values, select the :guilabel:`Finish` button.
+
+   .. figure:: figures/virtmgr/virt-manager-03.png
+      :scale: 100%
+      :alt: Create a new virtual network
+
+      Figure 3: Create a new virtual network
+
+#. Close the `QEMU/KVM Connection details` dialog box and return to the Virtual
+   Machine Manager main console. You are ready to create your VM.
+
+Create a new virt-manager virtual machine
+*****************************************
+
+In the Virtual Machine Manager main console, either select
+:menuselection:`File > New Virtual Machine` or click the `Create a
+new virtual machine` icon. This launches the `New VM` wizard, shown in Figure 4.
+
+.. figure:: figures/virtmgr/virt-manager-04.png
+   :scale: 100%
+   :alt: New VM
+
+   Figure 4: New VM dialog box, step 1
+
+#. Select `Local install media (ISO image or CDROM)` and select the
+   :guilabel:`Forward` button.
+
+#. In step 2 of the `New VM` wizard, you can choose ISO or CDROM install
+   media.
+
+   a. Uncheck `Automatically detect from the installation media / source`
+      field and select the :guilabel:`Browse...` button as shown in Figure 5.
+
+      .. figure:: figures/virtmgr/virt-manager-05.png
+         :scale: 100%
+         :alt: New VM
+
+         Figure 5: New VM dialog box, step 2: Choose media
+
+   #. In the `Choose Storage Volume` dialog, select the
+      :guilabel:`Browse Local` button as shown in Figure 6. Browse to
+      the ISO image that you downloaded earlier and open it.
+
+      .. figure:: figures/virtmgr/virt-manager-06.png
+         :scale: 100%
+         :alt: Choose storage volume
+
+         Figure 6: Choose storage volume dialog box
+
+   #. In the `Choose the operating system you are installing` search field,
+      type `generic` and select the `Generic default` value when it is displayed.
+      Select the :guilabel:`Forward` button as shown in Figure 7.
+
+      .. figure:: figures/virtmgr/virt-manager-07.png
+         :scale: 100%
+         :alt: New VM
+
+         Figure 7: New VM dialog box, step 2: Choose operating system
+
+      .. note::
+
+         A message may be displayed that says the emulator does not have
+         search permissions for the ISO image path. Select :guilabel:`Yes` to
+         proceed to the next step.
+
+#. Step 3 of the `New VM` wizard allocates the memory and CPUs for
+   the new VM. Choose settings that are valid for the resources on your host
+   system. This example sets `Memory` to 2048GB and `CPUs` to 1. Once complete,
+   select the :guilabel:`Forward` button as shown in Figure 8.
+
+   .. figure:: figures/virtmgr/virt-manager-08.png
+      :scale: 100%
+      :alt: New VM Choose Memory and CPU settings dialog box
+
+      Figure 8: New VM dialog box, step 3: Choose Memory and CPU settings
+
+#. Step 4 of the `New VM` wizard sets up the storage media for your VM. You
+   can create a new disk image or use an existing image. This example selects
+   `Enable storage for this virtual machine` and creates a 20GB image for it.
+   Once complete, select the :guilabel:`Forward` button as shown in Figure 9.
+
+   .. figure:: figures/virtmgr/virt-manager-09.png
+      :scale: 100%
+      :alt: New VM Enable storage dialog box
+
+      Figure 9: New VM dialog box, step 4: Enable storage
+
+#. Step 5 of the `New VM` wizard displays the selections you made and allows
+   you to customize the configuration before running the installation. Select the
+   `Customize configuration before install` checkbox and select the
+   :guilabel:`Finish` button as shown in Figure 10.
+
+   .. figure:: figures/virtmgr/virt-manager-10.png
+      :scale: 100%
+      :alt: New VM Ready to begin the installation dialog box
+
+      Figure 10: New VM dialog box, step 5: Ready to begin the installation
+
+#. Customize the installation process by changing the firmware from `BIOS` to
+   `UEFI x86_64`. |CL| requires UEFI firmware. In the `Firmware` field, select
+   the :file:`UEFI x86_64:/usr/share/qemu/OVMF.fd` entry as shown in Figure 11
+   and select the :guilabel:`Apply` button.
+
+   .. figure:: figures/virtmgr/virt-manager-11.png
+      :scale: 100%
+      :alt: vm1 on QEMU/KVM dialog box
+
+      Figure 11: vm1 on QEMU/KVM dialog box
+
+#. Begin the installation by selecting the :guilabel:`Begin Installation` in
+   the upper left corner of the `vm1 on QEMU/KVM` dialog box.
+
+Install |CL| in the virt-manager VM
+***********************************
+
+To install |CL| in your VM, follow the instructions in the getting started
+guide :ref:`bare-metal-install-server`.
+
+.. note::
+
+   You do not need to set up the network as described in the installation
+   guide, because you already downloaded the ISO image and connected to your
+   VM. Your network will show up as a wired connection.
+
+Congratulations! You have successfully installed |CL| in your new VM and can
+begin using it immediately. The `virt-manager` tool is maintained on GitHub\*
+at `virt-manager-github`_.
+
+.. _virt-mgr: https://www.virt-manager.org
+
+.. _Downloads: https://clearlinux.org/downloads
+
+.. _virt-manager-github: https://github.com/virt-manager/virt-manager
+
+.. _Intel® Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html

source/get-started/virtual-machine-install/vmware-esxi-install-cl.rst

@@ -44,45 +44,45 @@ For more information, refer to :ref:`download-verify-decompress`.
 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.  
-#.  Under the :guilabel:`Navigator` window, select :guilabel:`Storage`. 
+#.  Connect to the VMware server and log into an account with sufficient
+    permission to create and manage VMs.
+#.  Under the :guilabel:`Navigator` window, select :guilabel:`Storage`.
     See Figure 1.
-#.  Under the :guilabel:`Datastores` tab, click the :guilabel:`Datastore browser` 
-    button.   
-    
+#.  Under the :guilabel:`Datastores` tab, click the :guilabel:`Datastore browser`
+    button.
+
     .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-1.png
       :scale: 100 %
-      :alt: VMware ESXi - Navigator > Storage 
+      :alt: VMware ESXi - Navigator > Storage
 
-      Figure 1: VMware ESXi - Navigator > Storage 
+      Figure 1: VMware ESXi - Navigator > Storage
 
 #.  Click the :guilabel:`Create directory` button and name the directory `ISOs`.
     See Figure 2.
 
     .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-2.png
       :scale: 100 %
-      :alt: VMware ESXi - Datastore > Create directory 
+      :alt: VMware ESXi - Datastore > Create directory
+
+      Figure 2: VMware ESXi - Datastore > Create directory
 
-      Figure 2: VMware ESXi - Datastore > Create directory 
-   
 #.  Select the newly-created directory and click the :guilabel:`Upload` button.
     See Figure 3.
 
     .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-3.png
       :scale: 100 %
-      :alt: VMware ESXi - Datastore > Upload ISO 
+      :alt: VMware ESXi - Datastore > Upload ISO
 
-      Figure 3: VMware ESXi - Datastore > Upload ISO 
-   
-#.  Select the decompressed |CL| installer ISO file :file:`clear-[version number]-installer.iso` 
+      Figure 3: VMware ESXi - Datastore > Upload ISO
+
+#.  Select the decompressed |CL| installer ISO file :file:`clear-[version number]-installer.iso`
     and upload it.
 
 Create and configure a new VM
 *****************************
 
-In this section, you will create a new VM, configure its basic parameters such 
-as drive size, number of CPUs, memory size, and then attach the |CL| installer ISO. 
+In this section, you will create a new VM, configure its basic parameters such
+as drive size, number of CPUs, memory size, and then attach the |CL| installer ISO.
 
 #.  Under the :guilabel:`Navigator` window, select :guilabel:`Virtual Machines`.
     See Figure 4.
@@ -93,9 +93,9 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I
       :alt: VMware ESXi - Navigator > Virtual Machines
 
       Figure 4: VMware ESXi - Navigator > Virtual Machines
-   
+
 #.  On the :guilabel:`Select creation type` step:
-    
+
     #.  Select the :guilabel:`Create a new virtual machine` option.
         See Figure 5.
     #.  Click the :guilabel:`Next` button.
@@ -105,11 +105,11 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I
           :alt: VMware ESXi - Create a new virtual machine
 
           Figure 5: VMware ESXi - Create a new virtual machine
-   
+
 #.  On the :guilabel:`Select a name and guest OS` step:
 
     #.  Give the new VM a name in the :guilabel:`Name` field. See Figure 6.
-    #.  Set the :guilabel:`Compatability` option to :guilabel:`ESXi 6.5 virtual machine`.
+    #.  Set the :guilabel:`Compatibility` option to :guilabel:`ESXi 6.5 virtual machine`.
     #.  Set the :guilabel:`Guest OS family` option to :guilabel:`Linux`.
     #.  Set the :guilabel:`Guest OS version` option to :guilabel:`Other 3.x or later Linux (64-bit)`.
     #.  Click the :guilabel:`Next` button.
@@ -126,15 +126,15 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I
     #.  Click the :guilabel:`Next` button.
 
 #.  On the :guilabel:`Customize settings` step:
-    
+
     #.  Click the :guilabel:`Virtual Hardware` button. See Figure 7.
-    #.  Expand the :guilabel:`CPU` setting and enable :guilabel:`Hardware virtualization` by 
+    #.  Expand the :guilabel:`CPU` setting and enable :guilabel:`Hardware virtualization` by
         checking :guilabel:`Expose hardware assisted virtualization to the guest OS`.
 
         .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-7.png
           :scale: 100 %
           :alt: VMware ESXi - Enable hardware virtualization
-      
+
           Figure 7: VMware ESXi - Enable hardware virtualization
 
     #.  Set :guilabel:`Memory` size to 2048MB (2GB). See Figure 8.
@@ -145,12 +145,12 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I
 
           Figure 8: VMware ESXi - Set memory size
 
-        .. note:: 
+        .. note::
 
           The |CL| installer ISO needs a minimum of 2GB of RAM to work properly.
-          You can reduce the memory size after the installation completes if you want, 
+          You can reduce the memory size after the installation completes if you want,
           because a minimum |CL| installation can function on as little as 128MB of RAM.
-          See :ref:`system-requirements` for more details.  
+          See :ref:`system-requirements` for more details.
 
     #.  Set :guilabel:`Hard disk 1` to the desired capacity. See Figure 9.
 
@@ -162,12 +162,12 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I
 
         .. note::
 
-          A minimum |CL| installation can exist on 600MB of drive space.  
-          See :ref:`system-requirements` for more details.       
+          A minimum |CL| installation can exist on 600MB of drive space.
+          See :ref:`system-requirements` for more details.
 
-    #.  Attach the |CL| installer ISO.  For the :guilabel:`CD/DVD Drive 1` setting, 
+    #.  Attach the |CL| installer ISO.  For the :guilabel:`CD/DVD Drive 1` setting,
         click the drop-down list to the right of it and select the :guilabel:`Datastore ISO file`
-        option.  Then select the |CL| installer ISO :file:`clear-[version number]-installer.iso` 
+        option.  Then select the |CL| installer ISO :file:`clear-[version number]-installer.iso`
         that you previously uploaded to the VMware server. See Figure 10.
 
         .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-10.png
@@ -183,13 +183,13 @@ Install |CL| into the new VM
 ****************************
 
 #.  Power on the VM.
-    
+
     #.  Under the :guilabel:`Navigator` window, select :guilabel:`Virtual Machines`.
         See Figure 11.
     #.  In the right window, select the newly-created VM.
-    #.  Click the :guilabel:`Power on` button.  
+    #.  Click the :guilabel:`Power on` button.
     #.  Click on the icon representing the VM to bring it into view and maximize
-        its window.  
+        its window.
 
         .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-11.png
           :scale: 100 %
@@ -197,23 +197,23 @@ Install |CL| into the new VM
 
           Figure 11: VMware ESXi - Navigator > Virtual Machines > Power on VM
 
-#.  Follow the :ref:`install-on-target-start` 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. 
+#.  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 |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
-enable UEFI support. 
+enable UEFI support.
 
 #.  Power off the VM.
 
-    #.  Click the :guilabel:`Actions` button - located on the top-right corner 
-        of the VM's windows - and go to the :guilabel:`Power` setting and  
-        select the :guilabel:`Power off` option. See Figure 12. 
+    #.  Click the :guilabel:`Actions` button - located on the top-right corner
+        of the VM's windows - and go to the :guilabel:`Power` setting and
+        select the :guilabel:`Power off` option. See Figure 12.
 
         .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-12.png
           :scale: 100 %
@@ -223,7 +223,7 @@ enable UEFI support.
 
 #.  Edit the VM settings.
 
-    #.  Click the :guilabel:`Actions` button again and select :guilabel:`Edit settings`.  
+    #.  Click the :guilabel:`Actions` button again and select :guilabel:`Edit settings`.
         See Figure 13.
 
         .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-13.png
@@ -233,9 +233,9 @@ enable UEFI support.
           Figure 13: VMware ESXi - Actions > Edit settings
 
 #.  Disconnect the CD/DVD to stop it from booting the |CL| installer ISO again.
-    
+
     #.  Click the :guilabel:`Virtual Hardware` button.  See Figure 14.
-    #.  For the :guilabel:`CD/DVD Drive 1` setting, uncheck the 
+    #.  For the :guilabel:`CD/DVD Drive 1` setting, uncheck the
         :guilabel:`Connect` checkbox.
 
         .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-14.png
@@ -248,7 +248,7 @@ enable UEFI support.
 
     #.  Click the :guilabel:`VM Options` button. See Figure 15.
     #.  Expand the :guilabel:`Boot Options` setting.
-    #.  For the :guilabel:`Firmware` setting, click the drop-down list to the right 
+    #.  For the :guilabel:`Firmware` setting, click the drop-down list to the right
         of it and select the :guilabel:`EFI` option.
 
         .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-15.png
@@ -262,14 +262,14 @@ enable UEFI support.
 Power on the VM and boot |CL|
 *****************************
 
-After configuring the settings above, power on the VM.  
+After configuring the settings above, power on the VM.
 
 #.  Under the :guilabel:`Navigator` window, select :guilabel:`Virtual Machines`.
     See Figure 16.
 #.  In the right window, select the VM.
-#.  Click the :guilabel:`Power on` button.  
+#.  Click the :guilabel:`Power on` button.
 #.  Click on the icon representing the VM to bring it into view and maximize
-    its window.  
+    its window.
 
     .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-16.png
       :scale: 100 %

source/get-started/virtual-machine-install/vmware-esxi-preconfigured-cl-image.rst

@@ -20,7 +20,7 @@ and run |CL-ATTR| virtual machines at scale.
 We provide a pre-configured |CL| VMware image that can be run on a VMware ESXi
 6.5 host.
 
-If manuall installation is preferred, refer to :ref:`vmware-esxi-install-cl`.
+If manual installation is preferred, refer to :ref:`vmware-esxi-install-cl`.
 
 .. note::
 
@@ -47,8 +47,8 @@ For more information, refer to :ref:`download-verify-decompress`.
 Upload the |CL| image to the VMware server
 ******************************************
 
-Once the |CL| VMware prebuilt image has been downloaded and 
-decompressed on your local system, it must be uploaded to a datastore 
+Once the |CL| VMware prebuilt image has been downloaded and
+decompressed on your local system, it must be uploaded to a datastore
 on the VMware ESXi server.
 
 The steps in this section can also be referenced from the VMware documentation
@@ -57,11 +57,11 @@ The steps in this section can also be referenced from the VMware documentation
 #. Connect to the VMware ESXi server and login to an account with sufficient
    permission to create and manage VMs.
 
-#. Under the :guilabel:`Navigator` window on the left side, 
+#. Under the :guilabel:`Navigator` window on the left side,
    select :guilabel:`Storage`.
    See Figure 1
 
-#. Under the :guilabel:`Datastores` tab, click 
+#. Under the :guilabel:`Datastores` tab, click
    the :guilabel:`Datastore browser` button.
 
    .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-1.png
@@ -95,8 +95,8 @@ 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 use with VMware's ESXi 
-hypervisor. 
+datastore, it must be converted to a format for use with VMware's ESXi
+hypervisor.
 
 The steps in this section can also be referenced from the VMware documentation on `Cloning and converting virtual machine disks with vmkfstools`_
 
@@ -105,11 +105,11 @@ The steps in this section can also be referenced from the VMware documentation o
 
    .. note::
 
-      If there is no :abbr:`vMA (vSphere Management Assistant)` appliance or :abbr:`vCLI (vSphere CLI)` configured and available, 
+      If there is no :abbr:`vMA (vSphere Management Assistant)` appliance or :abbr:`vCLI (vSphere CLI)` configured and available,
       you can temporarily enable SSH directly on the ESXi host by following the
       steps described in `Enable the Secure Shell (SSH) in the VMware Host Client`_.
 
-      As a security best practice, remember to disable SSH access after following the steps in this section. 
+      As a security best practice, remember to disable SSH access after following the steps in this section.
 
 
 #. Locate the uploaded image, which is typically found in
@@ -134,10 +134,10 @@ Create and configure a new VM
 *****************************
 
 In this section, you will create a new VM, configure its basic parameters
-such as number of CPUs, memory size, and then attach the converted |CL| 
-VMware image. Also, in order to boot |CL|, you must enable UEFI support. 
+such as number of CPUs, memory size, and then attach the converted |CL|
+VMware image. Also, in order to boot |CL|, you must enable UEFI support.
 
-#. Under the :guilabel:`Navigator` window, select 
+#. Under the :guilabel:`Navigator` window, select
    :guilabel:`Virtual Machines`. See Figure 4.
 
 #. In the right window, click the :guilabel:`Create / Register VM` button.
@@ -165,10 +165,10 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support.
 
 #. Give the new VM a name in the :guilabel:`Name` field. See Figure 6.
 
-#. Set the :guilabel:`Compatability` option to
+#. Set the :guilabel:`Compatibility` option to
    :guilabel:`ESXi 6.5 virtual machine`.
 #. Set the :guilabel:`Guest OS family` option to :guilabel:`Linux`.
-#. Set the :guilabel:`Guest OS version` option to 
+#. Set the :guilabel:`Guest OS version` option to
    :guilabel:`Other 3.x or later Linux (64-bit)`.
 #. Click the :guilabel:`Next` button.
 
@@ -186,8 +186,8 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support.
 #. On the :guilabel:`Customize settings` step:
 
    #. Click the :guilabel:`Virtual Hardware` button. See Figure 7.
-   #. Expand the :guilabel:`CPU` setting and enable 
-      :guilabel:`Hardware virtualization` by checking 
+   #. Expand the :guilabel:`CPU` setting and enable
+      :guilabel:`Hardware virtualization` by checking
       :guilabel:`Expose hardware assisted virtualization to the guest OS`.
 
    .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-7.png
@@ -205,8 +205,8 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support.
 
       Figure 8: VMware ESXi - Remove hard drive
 
-   #. Since a pre-configured image will be used, 
-      the :guilabel:`CD/DVD Drive 1` setting will not be needed.  Disable it 
+   #. Since a pre-configured image will be used,
+      the :guilabel:`CD/DVD Drive 1` setting will not be needed.  Disable it
       by unchecking the :guilabel:`Connect` checkbox. See Figure 9.
 
    .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-9.png
@@ -228,14 +228,14 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support.
       Figure 10: VMware ESXi - Add an existing hard drive
 
       #. Select the converted :file:`clear-[version number]-esxi.vmdk`
-         file. Do not use the original unconverted 
+         file. Do not use the original unconverted
          :file:`clear-[version number]-vmware.vmdk` file. See Figure 11.
 
    .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-11.png
       :scale: 100 %
       :alt: VMware ESXi - Select the converted `vmdk` file
 
-      Figure 11: VMware ESXi - Select the converted 
+      Figure 11: VMware ESXi - Select the converted
       :file:`clear-[version number]-esxi.vmdk` file
 
 #. |CL| needs UEFI support in order to boot.  Enable UEFI boot support.
@@ -260,7 +260,7 @@ Power on the VM and boot |CL|
 
 After configuring the settings above, power on the VM.
 
-#. Under the :guilabel:`Navigator` window, select 
+#. Under the :guilabel:`Navigator` window, select
    :guilabel:`Virtual Machines`. See Figure 13.
 #. In the right window, select the newly-created VM.
 #. Click the :guilabel:`Power on` button.

source/guides/clear/stateless.rst

@@ -34,20 +34,22 @@ between user-owned areas and |CL|-owned areas.
 
    Figure 2: With stateless, user and system files are separated on the filesystem.
 
-System areas
-============
-File under the :file:`/usr` directory are managed by |CL| as system files.
+System area
+===========
+Files under the :file:`/usr` directory are managed by |CL| as system files
+(except :file:`/usr/local`).
 Files written under the :file:`/usr` directory by users can get removed
 through system updates with :ref:`swupd <swupd-guide>`. This operating
 assumption allows |CL| to verify and maintain integrity of system files.
 
 User areas
 ==========
-Files under the :file:`/etc/`, :file:`/home`, and :file:`/var` directories are
-owned and managed by the user. A freshly installed |CL| system will only have
-a minimal set of files in the :file:`/etc/` directory and software installed
-by |CL| does not write to :file:`/etc`. This operating assumption allows |CL|
-users to clearly identify the configuration that makes their system unique.
+Files under the :file:`/usr/local`, :file:`/etc/`, :file:`/opt`, :file:`/home`,
+and :file:`/var` directories are owned and managed by the user. A freshly
+installed |CL| system will only have a minimal set of files in the
+:file:`/etc/` directory and software installed by |CL| does not write to
+:file:`/etc`. This operating assumption allows |CL| users to clearly identify
+the configuration that makes their system unique.
 
 
 Software configuration

source/guides/clear/telemetrics.rst

@@ -176,7 +176,7 @@ Enable or disable telemetry
    the telemetry software bundle is not added to your system. If you do
    choose to join the program, the installer will automatically enable
    telemetry on your system by installing the telemetrics bundle, creating
-   the file :file:`/etc/telemetrics/opt-in`, and enabling the telemtrics
+   the file :file:`/etc/telemetrics/opt-in`, and enabling the telemetrics
    systemd services to run after installation is complete and the system is
    restarted.
 
@@ -282,7 +282,7 @@ Use :command:`-h` or :command:`--help` to view usage options.
 
 
 Set up a backend server to collect telemetry records
-=====================================================
+====================================================
 
 For this example, start with a clean installation of |CL| on a new system
 using the :ref:`bare-metal-install-server` getting started guide and:
@@ -745,7 +745,7 @@ The telemetry client will look for the configuration file located at
 :file:`/etc/telemetrics/telemetrics.conf` and use it if it exists. If the
 file does not exist, the client will use the default configuration defined
 at build time. There is a sample configuration file located at
-:file:`/usr/share/defaults telemetrics/telemetrics.conf` and represents the
+:file:`/usr/share/defaults/telemetrics/telemetrics.conf` and represents the
 default values that are used when the programs are built. To modify or
 customize the configuration, copy the file from
 :file:`/usr/share/defaults/telemetrics/telemetrics.conf` to the file

source/guides/maintenance/architect-lifecycle.rst

@@ -34,7 +34,7 @@ Maintaining a |CL| derivative requires:
 * Integrating Quality Assurance for testing and validation
 
 Coordinated infrastructure is deployed to automate the life-cycle
-of your |CL| derivative. We divide deployment of this infrastucture in two
+of your |CL| derivative. We divide deployment of this infrastructure in two
 parts: *Content Workflow*; and *Release Workflow*, shown in Figure 1.
 
 .. figure:: figures/architect-lifecycle-1.png

source/guides/maintenance/enable-systemd-boot-menu.rst

@@ -0,0 +1,25 @@
+.. _enable-systemd-boot-menu:
+
+Enable systemd-boot Menu
+########################
+
+The default installation of |CL| does not set a timeout value for the systemd-boot 
+bootloader. At boot time, you will not be presented with the systemd-boot menu. Without 
+a menu, you cannot interact with systemd-boot such as selecting a different kernel,
+editing kernel command line parameters, etc. 
+
+To set a timeout value for the systemd-boot menu, follow these steps:
+
+
+#. Boot up |CL|.
+
+#. Log in.
+
+#. Set a timeout (for example: 20 seconds).
+
+   .. code-block:: bash
+      
+      sudo clr-boot-manager set-timeout 20
+      sudo clr-boot-manager update
+
+#. Reboot.

source/guides/maintenance/resource-limits.rst

@@ -8,7 +8,7 @@ service for system resources and contain rogue processes.
 
 These limits are layered at the system-level and user-level. If these limits
 need to be modified, it is useful to understand the different limit
-configurations.  
+configurations.
 
 .. contents:: :local:
     :depth: 2
@@ -16,13 +16,13 @@ configurations.
 
 System-wide limits
 ==================
- 
+
 Some global resource limits are implemented in the Linux kernel and are
-controllable with kernel parameters. 
+controllable with kernel parameters.
 
 For example, a global limit for the maximum number of open files is set with
 the *fs.file-max* parameter. This limit applies to all processes and users an
-cannot be exceeded other limit values. 
+cannot be exceeded other limit values.
 
 Checking limit
 **************
@@ -31,15 +31,15 @@ You can check a current value with :command:`sysctl -n <PARAMETER>`. For
 example:
 
 .. code:: bash
-   
+
    sysctl -n fs.file-max
-   
+
 
 This *fs.file-max* value is set intentionally high on |CL| systems by
 default. You can check the maximum value supported by the system with:
 
 .. code::
-   
+
    cat /proc/sys/fs/file-max
 
 
@@ -52,7 +52,7 @@ example:
 .. code:: bash
 
    sudo sysctl -w fs.file-max=<NUMBER>
-   
+
 If needed permanently, the value can be set by creating a
 :file:`/etc/sysctl.d/*.conf` file (see :command:`man sysctl.d` for details).
 For example:
@@ -84,16 +84,16 @@ number of open file descriptors for the current user:
 
    ulimit -S -n <NUMBER>
 
-See :command:`man limits.conf` for details. 
+See :command:`man limits.conf` for details.
 
 
 Service limits
 ==============
 
 Resource limits for services started with systemd units do not follow normal
-user limits because the process is started in a seperate `Linux control group
+user limits because the process is started in a separate `Linux control group
 (cgroup) <https://www.kernel.org/doc/Documentation/cgroup-v2.txt>`_ Linux
-cgroups associate related process groups and provide resource accounting. 
+cgroups associate related process groups and provide resource accounting.
 
 Resource limits for individual systemd services can be controlled inside their
 unit files or its configuration drop-in directory with the resource Limit
@@ -102,22 +102,13 @@ directives. See `process properties section of the systemd.exec man page
 
 Resource limits for all systemd services can be controlled with a file in the
 :file:`/etc/systemd/system.conf.d/` directory. For example, to have no
-restriction on the number of open files: 
+restriction on the number of open files:
 
 .. code::
-   
+
    sudo mkdir -p /etc/systemd/system.conf.d/
 
    sudo tee /etc/systemd/system.conf.d/50-nfiles.conf  > /dev/null <<'EOF'
    [Manager]
    DefaultLimitNOFILE=infinity
    EOF
-
-
-
-
-
-
-
-
-

source/guides/network/dpdk.rst

@@ -32,13 +32,13 @@ This example uses the following DPDK components:
 Prerequisites
 *************
 
-*  Two platforms using |CL-ATTR| release `13330`_ or higher.
+*  Two platforms using |CL-ATTR| release `31130`_ or higher.
 *  Both images must include the :command:`kernel-native` bundle.
-*  Install the :command:`network-basic-dev` bundle with the command:
+*  Install the following packages:
 
    .. code-block:: bash
 
-      sudo swupd bundle-add network-basic-dev
+      sudo swupd bundle-add network-basic-dev dpdk devpkg-dpdk
 
 *  Each platform must have at least one :abbr:`NIC (Network Interface Card)`.
    Check the `DPDK project`_ for the list of supported `dpdk.org NICs`_.
@@ -65,14 +65,14 @@ Install dpdk and build l3fwd example (Platform B)
 
    .. code-block:: bash
 
-      sudo export RTE_TARGET=x86_64-native-linuxapp-gcc
+      sudo export RTE_TARGET=x86_64-native-linux-gcc
 
 #. Build the `l3fwd` application and add the configuration header to
    the :makevar:`CFLAGS` variable.
 
    .. code-block:: bash
 
-      sudo make CFLAGS+="-include /usr/include/rte_config.h"
+      sudo make
 
 
 Build pktgen (Platform A)
@@ -92,7 +92,7 @@ Build pktgen (Platform A)
 
    .. code-block:: bash
 
-      sudo export RTE_TARGET=x86_64-native-linuxapp-gcc
+      sudo export RTE_TARGET=x86_64-native-linux-gcc
 
 #. Build the `pktgen` project and set the :makevar:`CONFIG_RTE_BUILD_SHARED_LIB` variable
    to "n".
@@ -224,7 +224,7 @@ Run pktgen application (Platform A)
 
    .. code-block:: bash
 
-      sudo ./app/app/x86_64-native-linuxapp-gcc/pktgen -c 0xf -n 4 -- -p 0xf -P -m "1.0, 2.1"
+      sudo ./app/app/x86_64-native-linux-gcc/pktgen -c 0xf -n 4 -- -p 0xf -P -m "1.0, 2.1"
 
 #. Enable active colorful output (optional).
 
@@ -343,7 +343,7 @@ machines control the NICs on the host.
 #. Run the :file:`start_qemu.sh` script.
 
 
-.. _13330: https://cdn.download.clearlinux.org/releases/13330/
+.. _31130: https://cdn.download.clearlinux.org/releases/31130/clear/
 .. _DPDK project: http://dpdk.org
 .. _dpdk.org NICs: http://dpdk.org/doc/nics
 .. _pktgen tar package: http://dpdk.org/browse/apps/pktgen-dpdk/refs

source/guides/network/ipxe-install.rst

@@ -41,6 +41,11 @@ Prerequisites
 
 Before booting with iPXE, make the following preparations.
 
+Your PXE client system must meet the requirements to run |CL| and have a boot
+order where the network boot option is prioritized before the disk boot
+option. To determine if your PXE client system meets the minimum requirements
+for |CL|, review the :ref:`compatibility-check`.
+
 Connect the PXE server and PXE clients to a switch on a private network, as
 shown in figure 2.
 
@@ -49,9 +54,6 @@ shown in figure 2.
 
    Figure 2: Network topology.
 
-Your PXE client must have a boot order where the network boot option is
-prioritized before the disk boot option.
-
 Your PXE server must have:
 
 * Ethernet/LAN boot option.

source/guides/network/openssh-server.rst

@@ -155,7 +155,7 @@ Enable X11-forwarding
 *********************
 
 X11 forwarding allows you to securely run graphical applications (that is, X
-clients) over the SSH conection. This enables remote GUI apps without the need
+clients) over the SSH connection. This enables remote GUI apps without the need
 for full VNC or remote desktop setup. To enable X11-forwarding via SSH,
 perform the following steps:
 

source/guides/network/vnc.rst

@@ -24,17 +24,13 @@ To configure VNC to work on your |CL| host, install these bundles:
 
 Follow these steps:
 
-#. Log into your |CL| host and get root privileges.
-
-   .. code-block:: bash
-
-      sudo -s
+#. Open a terminal window.
 
 #. Install the |CL| bundles.
 
    .. code-block:: bash
 
-      swupd bundle-add desktop-autostart vnc-server
+      sudo swupd bundle-add desktop-autostart vnc-server
 
 #. Reboot your |CL| host.
 
@@ -59,18 +55,18 @@ your |CL| host:
      - The system administrator sets up a systemd service script for you with
        a pre-assigned display ID.  You make a VNC connection and supply
        your pre-assigned display ID.
-     - The system adminstrator configures GDM to accept connection requests.
+     - The system administrator configures GDM to accept connection requests.
        When you make a VNC connection to the |CL| host, you see
        the GDM login screen and authenticate as if you are local.
    * - Who configures VNC settings?
      - You
-     - System adminstrator
-     - System adminstrator
+     - System administrator
+     - System administrator
    * - Who starts VNC session?
      - You
      - Set to start automatically on boot by system administrator
      - Set to start automatically on boot by system administrator
-   * - Who ends VNC sesssion?
+   * - Who ends VNC session?
      - You
      - You
      - System administrator can disable VNC service altogether
@@ -92,7 +88,9 @@ Method 1: Manually start a VNC session
 You (and each user) must perform these steps to initialize your VNC settings.
 
 #. Log in.
-#. Open a terminal emulator.
+
+#. Open a terminal window.
+
 #. Start VNC with the :command:`vncserver` command.  Since this is your
    first time starting VNC, it adds default configuration files and asks you
    to set a VNC password.
@@ -154,25 +152,20 @@ To configure VNC for this method, you must have root privileges.  You will
 set up a systemd service file for all intended VNC users with their own
 preassigned unique display ID.
 
-#. Log in and get root privileges.
-
-   .. code-block:: bash
-
-      sudo -s
+#. Log in.
 
 #. Make sure the user accounts already exist.  Use the following command to
    list all users.
 
-
    .. code-block:: bash
 
-      cut -d: -f1 /etc/passwd
+      sudo cut -d: -f1 /etc/passwd
 
 #. Create the path :file:`/etc/systemd/system`.
 
    .. code-block:: bash
 
-      mkdir -p /etc/systemd/system
+      sudo mkdir -p /etc/systemd/system
 
 #. Create a systemd service script file :file:`vncserver@:[X].service`,
    where [X] is the display ID, for each user in :file:`/etc/systemd/system`
@@ -180,9 +173,9 @@ preassigned unique display ID.
    username is entered in the :guilabel:`User` field. The example below shows user
    vnc-user-b who is assigned the display ID 5.
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # cat > /etc/systemd/system/vncserver@:5.service << EOF
+      sudo tee -a /etc/systemd/system/vncserver@:5.service << EOF
 
       [Unit]
       Description=VNC Remote Desktop Service for "vnc-user-b" with display ID "5"
@@ -210,9 +203,9 @@ preassigned unique display ID.
 
    .. code-block:: bash
 
-      systemctl daemon-reload
-      systemctl start vncserver@:[X].service
-      systemctl enable vncserver@:[X].service
+      sudo systemctl daemon-reload
+      sudo systemctl enable vncserver@:[X].service
+      sudo systemctl start vncserver@:[X].service
 
 #. After starting the services, verify they are running.
 
@@ -225,7 +218,7 @@ preassigned unique display ID.
 
    .. code-block:: console
 
-      # systemctl | grep vnc
+      systemctl | grep vnc
 
       vncserver@:5.services   loaded active running  VNC Remote Desktop Service for "vnc-user-b" with display ID "5"
       vncserver@:6.services   loaded active running  VNC Remote Desktop Service for "vnc-user-c" with display ID "6"
@@ -240,23 +233,19 @@ make a VNC connection to your |CL| host, you are presented with the GDM login
 screen and you authenticate as if you are local.  You must have root privileges
 to perform this configuration.
 
-#. Log in and get root privileges.
-
-   .. code-block:: bash
-
-      sudo -s
+#. Log in.
 
 #. Create the path :file:`/etc/systemd/system`.
 
    .. code-block:: bash
 
-      mkdir -p /etc/systemd/system
+      sudo mkdir -p /etc/systemd/system
 
-#. Create a systemd socket file :file:`xvnc.socket` and add the following:
+#. Create a systemd socket file :file:`xvnc.socket` with the following content:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # cat > /etc/systemd/system/xvnc.socket << EOF
+      sudo tee -a /etc/systemd/system/xvnc.socket << EOF
 
       [Unit]
       Description=XVNC Server on port 5900
@@ -270,11 +259,11 @@ to perform this configuration.
 
       EOF
 
-#. Create a systemd service file :file:`xvnc@.service` and add the following:
+#. Create a systemd service file :file:`xvnc@.service` with the following content:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # cat > /etc/systemd/system/xvnc@.service << EOF
+      sudo tee -a  /etc/systemd/system/xvnc@.service << EOF
 
       [Unit]
       Description=Daemon for each XVNC connection
@@ -291,14 +280,14 @@ to perform this configuration.
 
    .. code-block:: bash
 
-      mkdir -p /etc/gdm
+      sudo mkdir -p /etc/gdm
 
 
-#. Create a GDM :file:`custom.conf` file and add the following:
+#. Create a GDM :file:`custom.conf` file with the following content:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # cat > /etc/gdm/custom.conf << EOF
+      sudo tee -a /etc/gdm/custom.conf << EOF
 
       [xdmcp]
       Enable=true
@@ -310,9 +299,9 @@ to perform this configuration.
 
    .. code-block:: bash
 
-      systemctl daemon-reload
-      systemctl start xvnc.socket
-      systemctl enable xvnc.socket
+      sudo systemctl daemon-reload
+      sudo systemctl enable xvnc.socket
+      sudo systemctl start xvnc.socket
 
 #. After starting the socket, verify it is running.
 
@@ -324,7 +313,7 @@ to perform this configuration.
 
    .. code-block:: console
 
-      # systemctl | grep vnc
+      systemctl | grep vnc
 
       xvnc.socket 		loaded active listening	XVNC Server on port 5900
       system-xvnc.slice 	loaded active active	system-xvnc.slice
@@ -347,19 +336,19 @@ On |CL|:
 
 .. code-block:: bash
 
-   swupd bundle-add desktop-autostart
+   sudo swupd bundle-add desktop-autostart
 
 On Ubuntu\*, Mint\*:
 
 .. code-block:: bash
 
-   apt-get install xtightvncviewer
+   sudo apt-get install xtightvncviewer
 
 On Fedora\*:
 
 .. code-block:: bash
 
-   dnf install tigervnc
+   sudo dnf install tigervnc
 
 On Windows\*:
 
@@ -397,7 +386,7 @@ SSH into your host and launch VNC
 
 #. SSH into your |CL| host
 
-   #. On Linux distros and macOS:
+   a. On Linux distros and macOS:
 
       .. code-block:: bash
 
@@ -405,7 +394,7 @@ SSH into your host and launch VNC
 
    #. On Windows:
 
-      #. Launch Putty.
+      i. Launch Putty.
       #. Under the :guilabel:`Category` section, select :guilabel:`Session`.
          See Figure 1.
       #. Enter the IP address of your |CL| host in the
@@ -413,7 +402,7 @@ SSH into your host and launch VNC
       #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`.
       #. Click the :guilabel:`Open` button.
 
-         .. figure:: figures/vnc/vnc-1.png
+         .. figure:: ../../_figures/vnc/vnc-1.png
             :scale: 90 %
             :alt: Putty - configure SSH session settings
 
@@ -470,7 +459,7 @@ the instructions below use the fully-qualified VNC port number.
 
 **On Linux distros:**
 
-#. Open a terminal emulator and enter:
+#. Open a terminal window and enter:
 
    .. code-block:: bash
 
@@ -497,7 +486,7 @@ the instructions below use the fully-qualified VNC port number.
    The following screenshot shows connecting to |CL| host
    192.168.25.54 with a fully-qualified VNC port number 5902.
 
-   .. figure:: figures/vnc/vnc-2.png
+   .. figure:: ../../_figures/vnc/vnc-2.png
       :scale: 90 %
       :alt: RealVNC Viewer
 
@@ -526,7 +515,7 @@ value. Follow these steps:
 #. Right-click a connection node and select :guilabel:`Properties...`.
    See Figure 3.
 
-   .. figure:: figures/vnc/vnc-3.png
+   .. figure:: ../../_figures/vnc/vnc-3.png
       :scale: 90 %
       :alt: RealVNC Viewer - change connection node properties
 
@@ -537,7 +526,7 @@ value. Follow these steps:
 #. Select the :guilabel:`ColorLevel` setting and change it to your
    preferred setting.
 
-   .. figure:: figures/vnc/vnc-4.png
+   .. figure:: ../../_figures/vnc/vnc-4.png
       :scale: 90 %
       :alt: RealVNC Viewer - change ColorLevel
 
@@ -551,7 +540,7 @@ on your |CL| host even if you close your VNC viewer app. If you want to
 truly terminate an active VNC session, follow these steps:
 
 #. SSH into your |CL| host.
-#. Open a terminal emulator.
+#. Open a terminal window.
 #. Find the active VNC session display ID with the command
    :command:`vncserver -list`.
 
@@ -571,8 +560,8 @@ truly terminate an active VNC session, follow these steps:
 
    .. code-block:: bash
 
-      systemctl stop xvnc.socket
-      systemctl disable xnvc.socket
+      sudo systemctl stop xvnc.socket
+      sudo systemctl disable xnvc.socket
 
 
 Encrypt VNC traffic through an SSH tunnel
@@ -581,7 +570,7 @@ Encrypt VNC traffic through an SSH tunnel
 By default, VNC traffic is not encrypted.  Figure 6 shows an example warning
 from RealVNC Viewer.
 
-.. figure:: figures/vnc/vnc-6.png
+.. figure:: ../../_figures/vnc/vnc-6.png
    :scale: 90 %
    :alt: RealVNC Viewer - Connection not encrypted warning
 
@@ -650,8 +639,8 @@ For Method 2:
 
    .. code-block:: bash
 
-      systemctl daemon-load
-      systemctl restart vncserver@:5.service
+      sudo systemctl daemon-load
+      sudo systemctl restart vncserver@:5.service
 
 For Method 3:
 
@@ -674,7 +663,7 @@ Figure 7 shows two VNC sessions (5901 and 5905) accepting connections from
 any host as specified by the `0.0.0.0`'s.  This is before the
 :command:`-localhost` option was used.
 
-.. figure:: figures/vnc/vnc-7.png
+.. figure:: ../../_figures/vnc/vnc-7.png
    :scale: 100 %
    :alt: VNC session accepting connection from any host
 
@@ -684,7 +673,7 @@ Figure 8 shows two VNC sessions (5901 and 5905) only accepting connections from
 localhost as specified by `127.0.0.1`'s. This is after the
 :command:`-localhost` option was used.
 
-.. figure:: figures/vnc/vnc-8.png
+.. figure:: ../../_figures/vnc/vnc-8.png
    :scale: 100 %
    :alt: VNC session only accepting connection from localhost
 
@@ -695,7 +684,7 @@ Set up an SSH tunnel from your client system to your |CL| host
 
 **On Linux distros and macOS:**
 
-#. Open terminal emulator and enter:
+#. Open terminal window and enter:
 
    .. code-block:: bash
 
@@ -725,7 +714,7 @@ Set up an SSH tunnel from your client system to your |CL| host
 #. Launch Putty.
 #. Specify the |CL| VNC host to connect to.
 
-   #. Under the :guilabel:`Category` section, select :guilabel:`Session`.
+   a. Under the :guilabel:`Category` section, select :guilabel:`Session`.
       See Figure 1.
    #. Enter the IP address of your |CL| host in the
       :guilabel:`Host Name (or IP address)` field.
@@ -733,7 +722,7 @@ Set up an SSH tunnel from your client system to your |CL| host
 
 #. Configure the SSH tunnel.  See Figure 9 for an example.
 
-   #. Under the :guilabel:`Category` section, go to
+   a. Under the :guilabel:`Category` section, go to
       :guilabel:`Connection` > :guilabel:`SSH` > :guilabel:`Tunnels`.
 
    #. In the :guilabel:`Source port` field, enter an available client
@@ -745,7 +734,7 @@ Set up an SSH tunnel from your client system to your |CL| host
 
    #. Click the :guilabel:`Add` button.
 
-      .. figure:: figures/vnc/vnc-9.png
+      .. figure:: ../../_figures/vnc/vnc-9.png
          :scale: 100 %
          :alt: Putty - configure SSH tunnel
 
@@ -762,7 +751,7 @@ your VNC session.
 
 **On Linux distros:**
 
-#. Open terminal emulator and enter:
+#. Open terminal window and enter:
 
    .. code-block:: bash
 
@@ -774,7 +763,7 @@ your VNC session.
 #. Enter `localhost` and the fully-qualified VNC port number.  See Figure 10
    for an example.
 
-   .. figure:: figures/vnc/vnc-10.png
+   .. figure:: ../../_figures/vnc/vnc-10.png
       :scale: 100 %
       :alt: RealVNC viewer app connecting to localhost:1234
 

source/guides/network/wifi.rst

@@ -0,0 +1,109 @@
+.. _wi-fi:
+
+Configure Wi-Fi
+###############
+
+We recommend using `NetworkManager <https://developer.gnome.org/NetworkManager/stable/NetworkManager.html>`_ to manage network connections. If you
+choose to connect to Wi-Fi while using the
+:ref:`live installer <bare-metal-install-desktop>` image, your Wi-Fi settings
+will be added to your system during the installation process.
+
+NetworkManager provides three simple methods for configuring Wi-Fi.
+
+.. contents::
+   :local:
+   :depth: 1
+
+Desktop GUI (Graphical User Interface)
+**************************************
+
+1. Click anywhere on the icons at the right side of the top of the screen to
+   bring up a menu and click on :guilabel:`Wi-Fi Not Connected` then
+   choose :guilabel:`Select Network`.
+
+   .. figure:: /_figures/wifi/wifi-1.1.png
+
+2. Scroll through the list and select the network you'd like to connect to and
+   click :guilabel:`Connect`.
+
+   .. figure:: /_figures/wifi/wifi-2.png
+
+3. Enter the password and click :guilabel:`Connect`.
+
+   .. figure:: /_figures/wifi/wifi-3.png
+
+4. The Wi-Fi icon should now show the signal strength of the connection.
+
+   .. figure:: /_figures/wifi/wifi-4.png
+
+5. If you are installing using the live image, resume the
+   :ref:`installation process <install-on-target-end>` now. Your Wi-Fi
+   configuration will automatically be included in the install. 
+
+   .. figure:: /_figures/wifi/wifi-5.png
+
+CLI (Command Line Interface)
+****************************
+
+#. List the available Wi-Fi networks
+
+   .. code-block:: bash
+
+      nmcli device wifi list
+
+   .. code-block:: console
+
+      IN-USE  SSID                           MODE   CHAN  RATE        SIGNAL  BARS  SECURITY         
+              1st Network                    Infra  1     54 Mbit/s   65      ▂▄▆_  --               
+              2nd Network                    Infra  1     130 Mbit/s  52      ▂▄__  --               
+              3rd Network                    Infra  10    195 Mbit/s  29      ▂___  WPA2             
+
+#. Join the network.
+
+   .. code-block:: bash
+
+      nmcli device wifi connect $SSID password $password
+
+   .. code-block:: console
+
+      Device 'wlp1s0' successfully activated with 'f2501e67-27a3-4cf2-a8d9-cce3d029b788'.
+
+.. note::
+
+   To avoid having the Wi-Fi password stored in bash history, consider using the TUI.
+
+TUI (Text-based User Interface)
+*******************************
+
+#. Launch the NetworkManager Text User Interface
+
+   .. code-block:: bash
+
+      nmtui
+
+#. Select :guilabel:`Activate a connection` and hit :kbd:`return`.
+
+   .. figure:: /_figures/wifi/nmtui_1.png
+
+#. Use the arrow keys to select your network and then select
+   :guilabel:`Activate` and hit :kbd:`return`. 
+
+   .. figure:: /_figures/wifi/nmtui_2.png
+
+#. Enter your password and hit :kbd:`return` to select :guilabel:`OK`.
+
+   .. figure:: /_figures/wifi/nmtui_3.png
+
+#. Select :guilabel:`Back` and hit :kbd:`return`.
+
+   .. figure:: /_figures/wifi/nmtui_4.png
+
+#. Select :guilabel:`Quit` and hit :kbd:`return` to exit. 
+
+   .. figure:: /_figures/wifi/nmtui_5.png
+
+Other resources
+***************
+
+* NetworkManager CLI `documentation <https://developer.gnome.org/NetworkManager/stable/nmcli.html>`_.
+* Additional CLI `examples <https://developer.gnome.org/NetworkManager/stable/nmcli-examples.html>`_.

source/guides/stacks/dars.rst

@@ -3,8 +3,7 @@
 Data Analytics Reference Stack
 ##############################
 
-This guide explains how to use the :abbr:`DARS (Data Analytics Reference Stack)`,
-and to optionally build your own DARS container image.
+This guide explains how to use the :abbr:`DARS (Data Analytics Reference Stack)`, and to optionally build your own DARS container image.
 
 Any system that supports Docker\* containers can be used with DARS. The steps
 in this guide use |CL-ATTR| as the host system.
@@ -28,7 +27,7 @@ available on `Docker Hub`_:
 * A |CL|-derived  `DARS with Intel® MKL`_ stack optimized for `MKL`_ (Intel® Math Kernel Library)
 
 We recommend you view the latest component versions for each image in the
-:file:`README` found in the `Data Analytics Reference Stack`_ GitHub\*
+:file:`releasenote` found in the `Data Analytics Reference Stack`_ GitHub\*
 repository. Because |CL| is a rolling distribution, the package version numbers
 in the |CL|-based containers may not be the latest released by |CL|.
 
@@ -54,15 +53,22 @@ Launching the Image
       docker pull clearlinux/stacks-dars-mkl
 
 
-#. Once you have downloaded the image, you can run it with
+#. Once you have downloaded the image, you can run it with this command, which will launch the image and drop you into a bash shell inside the container.
 
    .. code-block:: bash
 
-      docker run -it --ulimit nofile=1000000:1000000 --name mkl <name of image>
+      docker run -it --ulimit nofile=1000000:1000000 --name mkl --network host --rm -i -t <name-of-image>
 
-   This will launch the image and drop you into a bash shell inside the container. The :command:`--ulimit nofile=` parameter is required in order to increase the allowed number of open files for the Apache Spark engine.
 
-   If you need to verify the name of the DARS image, you can use the :command:`docker image ls` command to see which images reside on your system.
+   Command Flags
+
+   :command:`--ulimit nofile=` is required in order to increase the allowed number of open files for the Apache Spark\* engine.
+
+   :command:`--name` can be any name of your choice.  This guide is using `mkl`
+
+   :command:`--network host` enables the host machine's IP address to be used to access the container.
+
+   If you need to verify the name of the DARS image for the <name-of-image> flag, you can use the :command:`docker image ls` command to see which images reside on your system.
 
    .. code-block:: bash
 
@@ -79,24 +85,30 @@ Launching the Image
 
 
 
+
+.. note::
+
+   All of the DARS components are compiled on Open JDK11\*. The container will have preinstalled JDK11 at :file:`/usr/lib/jvm/java-1.11.0-openjdk/` and it has been set as the default Java version. While the DARS containers also contain Open JDK8, it is not covered in this guide.
+
+
 Building DARS images
 ====================
 
-If you choose to build your own DARS container images, you can customize them as needed. Use the :file:`Dockerfile` included in the Github\* repository as your baseline. 
+If you choose to build your own DARS container images, you can customize them as needed. Use the :file:`Dockerfile` included in the Github\* repository as your baseline.
 
 To construct images with |CL|, start with a |CL| development platform that has the :command:`containers-basic-dev` bundle installed. Learn more about bundles and installing them by using :ref:`swupd-guide`.
 
-#. The `Data Analytics Reference Stack`_ is part of the |CL| Project GitHub\* repository. Clone the :file:`dockerfiles` repository.
+#. The `Data Analytics Reference Stack`_ is part of the Intel® stacks GitHub\* repository. Clone the :file:`stacks` repository.
 
    .. code-block:: bash
 
-      git clone https://github.com/clearlinux/dockerfiles.git
+      git clone https://github.com/intel/stacks.git
 
-#. Inside the :file:`stacks/dars/mkl` directory, use docker with the :file:`Dockerfile` to build the  MKL image.
+#. Inside the :file:`stacks/dars/clearlinux/mkl` directory, use docker with the :file:`Dockerfile` to build the  MKL image.
 
    .. code-block:: bash
 
-      cd ./dockerfiles/stacks/dlrs/mkl
+      cd ./stacks/dars/clearlinux/mkl
       docker build --no-cache -t clearlinux/stacks-dars-mkl .
 
 
@@ -108,6 +120,11 @@ To construct images with |CL|, start with a |CL| development platform that has t
 
 #. You can use any of the resulting images to launch fully functional containers. If you need to customize the containers, you can edit the provided :file:`Dockerfile`.
 
+.. note::
+
+   The environment variables for Apache Hadoop* and Apache Spark have been configured in the Dockerfile for the DARS container. For Apache Hadoop\* use :file:`/etc/hadoop` as `HADOOP_CONF_DIR` folder. For Apache Spark use :file:`/etc/spark` as `SPARK_CONF_DIR` folder.
+
+
 Using Apache Spark\* in DARS
 ****************************
 
@@ -172,9 +189,490 @@ DARS Usecase example
 The DARS container is used in conjunction with the Deep Learning Reference Stack container to implement a real world use case.  Refer to the `Github Issue Classification`_ Usecase found in the `stacks-usecase`_ repository for a walkthrough.  This usecase is implemented using the Scala environment, rather than PySpark.
 
 
+Using Apache Hadoop in DARS
+***************************
+
+Apache Hadoop is an open source framework allowing for distributed processing of large data sets across clusters of computers using simple programming models. This framework is designed to scale up from a few servers to thousands of machines, each offering local computation and storage.
+
+Single Node Hadoop Cluster Setup
+================================
+
+In this mode, all the daemons involved (e.g., the DataNode, NameNode, TaskTracker, JobTracker) run as Java processes on the same machine. This setup is useful for developing and testing Apache Hadoop applications.
+
+The components of an Apache Hadoop Cluster are described below:
+
+* NameNode manages HDFS storage. HDFS exposes a filesystem namespace and allows user data to be stored in files. Internally a file is split into one or more blocks and these blocks are stored in a set of DataNodes.
+* DataNode is also known as Slave node. It is responsible for storing and managing the data in that node and responds to the NameNode for all filesystem operations.
+* JobTracker is a master which creates and runs the job through tasktrackers. It also tracks resource availability and task lifecycle management.
+* TaskTracker manages the processing resources on each worker node and send status updates to the JobTracker periodically.
 
 
-.. _Data Analytics Reference Stack: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dars
+Configuration
+=============
+
+#. To setup a single node cluster, run a DARS container with the following flags:
+
+   .. code-block:: bash
+
+      docker run --ulimit nofile=1000000:1000000 -ti --rm --network host clearlinux/stacks-dars-mkl cp -r -n /usr/share/defaults/hadoop/* /etc/hadoop
+
+#. In the running container, set configuration in the :file:`/etc/hadoop/mapred-site.xml` file
+
+   .. code-block:: xml
+
+      <configuration>
+          <property>
+              <name>mapreduce.framework.name</name>
+              <value>yarn</value>
+          </property>
+
+          <property>
+              <name>yarn.app.mapreduce.am.env</name>
+              <value>HADOOP_MAPRED_HOME=${HADOOP_HOME}</value>
+          </property>
+
+          <property>
+              <name>mapreduce.map.env</name>
+              <value>HADOOP_MAPRED_HOME=${HADOOP_HOME}</value>
+          </property>
+
+          <property>
+              <name>mapreduce.reduce.env</name>
+              <value>HADOOP_MAPRED_HOME=${HADOOP_HOME}</value>
+          </property>
+       </configuration>
+
+#. Set up the :file:`/etc/hadoop/yarn-site.xml` as follows
+
+   .. code-block:: xml
+
+      <configuration>
+          <property>
+              <name>yarn.nodemanager.aux-services</name>
+              <value>mapreduce_shuffle</value>
+          </property>
+
+          <property>
+              <name>yarn.nodemanager.auxservices.mapreduce.shuffle.class</name>
+              <value>org.apache.hadoop.mapred.ShuffleHandler</value>
+          </property>
+      </configuration>
+
+Start the Apache Hadoop daemons
+===============================
+
+#. Format the NameNode server using this command:
+
+   .. code-block:: bash
+
+      hdfs namenode -format
+
+#. Start the Apache Hadoop services
+
+   HDFS Namenode service :
+
+   .. code-block:: bash
+
+      hdfs --daemon start namenode
+
+
+   HDFS Datanode service :
+
+   .. code-block:: bash
+
+      hdfs --daemon start datanode
+
+
+   Yarn ResourceManager :
+
+   .. code-block:: bash
+
+      yarn --daemon start resourcemanager
+
+
+   Yarn NodeManager :
+
+   .. code-block:: bash
+
+      yarn --daemon start nodemanager
+
+
+   jobhistory service :
+
+   .. code-block:: bash
+
+      mapred --daemon start historyserver
+
+#. Verify the nodes are alive with this command:
+
+
+   .. code-block:: bash
+
+      yarn node -list 2
+
+   Your output will look similar to:
+
+   .. code-block:: console
+
+      Total Nodes:1
+         Node-Id             Node-State Node-Http-Address       Number-of-Running-Containers
+      <hostname>:43489            RUNNING <hostname>:8042                      0
+
+
+Example application
+===================
+
+Apache Hadoop comes packages with a set of example  applications. In this example we will show how to use the cluster to calculate Pi. The JAR file containing the compiled class can be found on your running DARS container at :file:`/usr/share/hadoop/mapreduce/hadoop-mapreduce-examples-3.2.0.jar`
+
+
+.. code-block:: bash
+
+   hadoop jar /usr/share/hadoop/mapreduce/hadoop-mapreduce-examples-$(hadoop version | grep Hadoop | cut -d ' ' -f2).jar pi 16 100
+
+
+Deploy DARS on Kubernetes\*
+***************************
+
+Many containerized workloads are deployed in clusters managed by orchestration software like Kubernetes.
+
+Prerequisites
+=============
+
+* A running Kubernetes cluster at version >= 1.6 with access configured to it using kubectl.
+* You must have appropriate permissions to list, create, edit and delete pods in your cluster.
+* The service account credentials used by the driver pods must be allowed to create pods, services and configmaps.
+* You must have Kubernetes DNS configured in your cluster.
+
+.. note::
+
+  To ensure that Kubernetes is correctly installed and configured for |CL|, follow the instructions in :ref:`kubernetes`.
+
+
+#. For this example we will create the following Dockerfile
+
+   .. code-block:: bash
+
+        cat > $(pwd)/Dockerfile << 'EOF'
+        ARG DERIVED_IMAGE
+        FROM ${DERIVED_IMAGE}
+
+        RUN mkdir -p /etc/passwd /etc/pam.d /opt/spark/conf /opt/spark/work-dir
+
+        RUN set -ex && \
+            rm /bin/sh && \
+            ln -sv /bin/bash /bin/sh && \
+            touch /etc/pam.d/su \
+            echo "auth required pam_wheel.so use_uid" >> /etc/pam.d/su && \
+            chgrp root /etc/passwd && chmod ug+rw /etc/passwd
+
+        RUN ln -s /usr/share/apache-spark/jars/ /opt/spark/ && \
+            ln -s /usr/share/apache-spark/bin/ /opt/spark/ && \
+            ln -s /usr/share/apache-spark/sbin/ /opt/spark/ && \
+            ln -s /usr/share/apache-spark/examples/ /opt/spark/ && \
+            ln -s /usr/share/apache-spark/kubernetes/tests/ /opt/spark/ && \
+            ln -s /usr/share/apache-spark/data/ /opt/spark/ && \
+            ln -s /etc/spark/* /opt/spark/conf/
+
+        COPY entrypoint.sh /opt/
+        ENV JAVA_HOME=/usr/lib/jvm/java-1.11.0-openjdk
+        ENV PATH="${JAVA_HOME}/bin:${PATH}"
+        ENV SPARK_HOME /opt/spark
+        WORKDIR /opt/spark/work-dir
+        ENTRYPOINT [ "/opt/entrypoint.sh" ]
+        EOF
+
+
+#. Create the :file:`entrypoint.sh` file. The Dockerfile requires an entrypoint script, to allow spark-submit to interact with the container.
+
+   .. code-block:: bash
+
+        cat > $(pwd)/entrypoint.sh << 'EOF'
+        #!/bin/bash
+        #
+        # Licensed to the Apache Software Foundation (ASF) under one or more
+        # contributor license agreements.  See the NOTICE file distributed with
+        # this work for additional information regarding copyright ownership.
+        # The ASF licenses this file to You under the Apache License, Version 2.0
+        # (the "License"); you may not use this file except in compliance with
+        # the License.  You may obtain a copy of the License at
+        #
+        #    http://www.apache.org/licenses/LICENSE-2.0
+        #
+        # Unless required by applicable law or agreed to in writing, software
+        # distributed under the License is distributed on an "AS IS" BASIS,
+        # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        # See the License for the specific language governing permissions and
+        # limitations under the License.
+        #
+
+        # echo commands to the terminal output
+        set -ex
+
+        # Check whether there is a passwd entry for the container UID
+        myuid=$(id -u)
+        mygid=$(id -g)
+        # turn off -e for getent because it will return error code in anonymous uid case
+        set +e
+        uidentry=$(getent passwd $myuid)
+        set -e
+
+        # If there is no passwd entry for the container UID, attempt to create one
+        if [ -z "$uidentry" ] ; then
+            if [ -w /etc/passwd ] ; then
+                echo "$myuid:x:$myuid:$mygid:anonymous uid:$SPARK_HOME:/bin/false" >> /etc/passwd
+            else
+                echo "Container ENTRYPOINT failed to add passwd entry for anonymous UID"
+            fi
+        fi
+
+        SPARK_K8S_CMD="$1"
+        case "$SPARK_K8S_CMD" in
+            driver | driver-py | driver-r | executor)
+              shift 1
+              ;;
+            "")
+              ;;
+            *)
+              echo "Non-spark-on-k8s command provided, proceeding in pass-through mode..."
+              exec /sbin/tini -s -- "$@"
+              ;;
+        esac
+
+        SPARK_CLASSPATH="$SPARK_CLASSPATH:${SPARK_HOME}/jars/*"
+        env | grep SPARK_JAVA_OPT_ | sort -t_ -k4 -n | sed 's/[^=]*=\(.*\)/\1/g' > /tmp/java_opts.txt
+        readarray -t SPARK_EXECUTOR_JAVA_OPTS < /tmp/java_opts.txt
+
+        if [ -n "$SPARK_EXTRA_CLASSPATH" ]; then
+          SPARK_CLASSPATH="$SPARK_CLASSPATH:$SPARK_EXTRA_CLASSPATH"
+        fi
+
+        if [ -n "$PYSPARK_FILES" ]; then
+            PYTHONPATH="$PYTHONPATH:$PYSPARK_FILES"
+        fi
+
+        PYSPARK_ARGS=""
+        if [ -n "$PYSPARK_APP_ARGS" ]; then
+            PYSPARK_ARGS="$PYSPARK_APP_ARGS"
+        fi
+
+        R_ARGS=""
+        if [ -n "$R_APP_ARGS" ]; then
+            R_ARGS="$R_APP_ARGS"
+        fi
+
+        if [ "$PYSPARK_MAJOR_PYTHON_VERSION" == "2" ]; then
+            pyv="$(python -V 2>&1)"
+            export PYTHON_VERSION="${pyv:7}"
+            export PYSPARK_PYTHON="python"
+            export PYSPARK_DRIVER_PYTHON="python"
+        elif [ "$PYSPARK_MAJOR_PYTHON_VERSION" == "3" ]; then
+            pyv3="$(python3 -V 2>&1)"
+            export PYTHON_VERSION="${pyv3:7}"
+            export PYSPARK_PYTHON="python3"
+            export PYSPARK_DRIVER_PYTHON="python3"
+        fi
+
+        case "$SPARK_K8S_CMD" in
+          driver)
+            CMD=(
+              "$SPARK_HOME/bin/spark-submit"
+              --conf "spark.driver.bindAddress=$SPARK_DRIVER_BIND_ADDRESS"
+              --deploy-mode client
+              "$@"
+            )
+            ;;
+          driver-py)
+            CMD=(
+              "$SPARK_HOME/bin/spark-submit"
+              --conf "spark.driver.bindAddress=$SPARK_DRIVER_BIND_ADDRESS"
+              --deploy-mode client
+              "$@" $PYSPARK_PRIMARY $PYSPARK_ARGS
+            )
+            ;;
+            driver-r)
+            CMD=(
+              "$SPARK_HOME/bin/spark-submit"
+              --conf "spark.driver.bindAddress=$SPARK_DRIVER_BIND_ADDRESS"
+              --deploy-mode client
+              "$@" $R_PRIMARY $R_ARGS
+            )
+            ;;
+          executor)
+            CMD=(
+              ${JAVA_HOME}/bin/java
+              "${SPARK_EXECUTOR_JAVA_OPTS[@]}"
+              -Xms$SPARK_EXECUTOR_MEMORY
+              -Xmx$SPARK_EXECUTOR_MEMORY
+              -cp "$SPARK_CLASSPATH"
+              org.apache.spark.executor.CoarseGrainedExecutorBackend
+              --driver-url $SPARK_DRIVER_URL
+              --executor-id $SPARK_EXECUTOR_ID
+              --cores $SPARK_EXECUTOR_CORES
+              --app-id $SPARK_APPLICATION_ID
+              --hostname $SPARK_EXECUTOR_POD_IP
+            )
+            ;;
+
+          *)
+            echo "Unknown command: $SPARK_K8S_CMD" 1>&2
+            exit 1
+        esac
+
+        # Execute the container CMD
+        exec "${CMD[@]}"
+        EOF
+
+
+#. Make :file:`entrypoint.sh` executable
+
+   .. code-block:: bash
+
+      sudo chmod +x $(pwd)/entrypoint.sh
+
+#. Build the Docker image, for this example we will use dars_k8s_spark for the name of the image.
+
+   .. code-block:: bash
+
+      docker build . --build-arg DERIVED_IMAGE=clearlinux/stacks-dars-mkl -t dars_k8s_spark
+
+
+#. Verify your built image. Execute the following command looking for the given name dars_k8s_spark
+
+   .. code-block:: bash
+
+     docker images | grep "dars_k8s_spark"
+
+   You should see something like:
+
+   .. code-block:: console
+
+     dars_k8s_spark                               latest              1fa3278a3421        1 minutes ago       6.56GB
+
+#. Use a variable to store the image's given name:
+
+   .. code-block:: bash
+
+     DARS_K8S_IMAGE=dars_k8s_spark
+
+
+Configure RBAC
+==============
+
+Create the Spark service account and cluster role binding to allow Spark on Kubernetes to create Executors as required. For this example use the default namespace.
+
+.. code-block:: bash
+
+   kubectl create serviceaccount spark-serviceaccount --namespace default
+   kubectl create clusterrolebinding spark-rolebinding --clusterrole=edit --serviceaccount=default:spark-serviceaccount --namespace=default
+
+
+Prepare to Submit the Spark Job
+===============================
+
+#. Determine the Kubernetes master address:
+
+   .. code-block:: bash
+
+      kubectl cluster-info
+
+   You should see something like:
+
+   .. code-block:: console
+
+      Kubernetes master is running at https://192.168.39.127:8443
+
+#. Use a variable to store the master address:
+
+   .. code-block:: bash
+
+      MASTER_ADDRESS='https://192.168.39.127:8443'
+
+#. Submit the Spark Job on Minikube using the MASTER_ADDRESS and DARS_K8S variables. The driver pod will be called spark-pi-driver.
+
+   .. code-block:: bash
+
+      spark-submit \
+      --master k8s://${MASTER_ADDRESS} \
+      --deploy-mode cluster \
+      --name spark-pi \
+      --class org.apache.spark.examples.SparkPi \
+      --conf spark.executor.instances=2 \
+      --conf spark.kubernetes.container.image=${DARS_K8S_IMAGE} \
+      --conf spark.kubernetes.driver.pod.name=spark-pi-driver \
+      --conf spark.kubernetes.namespace=default \
+      --conf spark.kubernetes.authenticate.driver.serviceAccountName=spark-serviceaccount \
+      local:///usr/share/apache-spark/examples/jars/spark-examples_2.12-2.4.0.jar
+
+
+#. Check the Job. Read the logs and look for the Pi result:
+
+   .. code-block:: bash
+
+      kubectl logs spark-pi-driver | grep "Pi is roughly"
+
+   You should see something like:
+
+   .. code-block:: console
+
+      Pi is roughly 3.1418957094785473
+
+More information about spark-submit configuration is available in the  `running-on-kubernetes`_ documentation.
+
+
+Troubleshooting
+***************
+
+Dropped or refused connection
+=============================
+
+If Pyspark / Spark-shell warns of a dropped connection exception or Connection refused, check if the `HADOOP_CONF_DIR` environment variable is set. These APIs assume they will use Hadoop Distributed File System.
+You can unset `HADOOP_CONF_DIR` and use Spark RDDs, or start Hadoop services and then create your directories and files as required using hdfs.
+
+It is also possible to change the file system to local without unsetting `HADOOP_CONF_DIR` using one of these commands.
+
+.. code-block:: bash
+
+   pyspark --conf "spark.hadoop.fs.defaultFS=file:///"
+
+.. code-block:: bash
+
+   spark-shell --conf "spark.hadoop.fs.defaultFS=file:///"
+
+Using Spark with proxy settings
+===============================
+
+There are two ways to work with proxies:
+
+#. Add the following line to  :file:`$SPARK_CONF_DIR/spark-defaults.conf` for both `spark.executor.extraJavaOptions` and `spark.driver.extraJavaOptions` variables:
+
+.. code-block:: console
+
+   -Dhttp.proxyHost=<URL> -Dhttp.proxyPort=<PORT> -Dhttps.proxyHost=<URL> -Dhttps.proxyPort=<PORT>
+
+
+
+#. Give the proxies URL and Port as a configuration parameter
+
+.. code-block:: bash
+
+   pyspark --conf "spark.hadoop.fs.defaultFS=file:///" --conf "spark.driver.extraJavaOptions=-Dhttp.proxyHost=example.proxy -Dhttp.proxyPort=111 -Dhttps.proxyHost=example.proxy -Dhttps.proxyPort=112"
+
+.. code-block:: bash
+
+   spark-shell --conf "spark.hadoop.fs.defaultFS=file:///" --conf "spark.driver.extraJavaOptions=-Dhttp.proxyHost=example.proxy -Dhttp.proxyPort=111 -Dhttps.proxyHost=example.proxy -Dhttps.proxyPort=112"
+
+
+Known issues
+============
+
+#. There is an exception message `Unrecognized Hadoop major version number: 3.2.0 at org.apache.hadoop.hive.shims.ShimLoader.getMajorVersion.`
+
+This exception can be disregarded because DARS does not use hadoop.hive.shims. Hive binaries installed from Apache on |CL| with JDK11 does not work at the time of this writing.
+
+#. There is an exception message `Exception in thread "Thread-3" java.lang.ExceptionInInitializerError at org.apache.hadoop.hive.conf.HiveConf` This is related to the same issue with |CL| and JDK11 noted above, and does not affect DARS for the same reason.
+
+
+.. _Data Analytics Reference Stack: https://github.com/intel/stacks/tree/master/dars/clearlinux
 
 .. _Docker Hub: https://hub.docker.com/
 
@@ -199,3 +697,5 @@ The DARS container is used in conjunction with the Deep Learning Reference Stack
 .. _stacks-usecase: https://github.com/intel/stacks-usecase
 
 .. _Github Issue Classification: https://github.com/intel/stacks-usecase/tree/master/github-issue-classification
+
+.. _running-on-kubernetes: https://spark.apache.org/docs/latest/running-on-kubernetes.html#configuration

source/guides/stacks/dbrs.rst

@@ -55,7 +55,7 @@ Hardware configuration used in stacks development
 * BIOS with Reference Code
   * BIOS ID: SE5C620.86B.0D.01.0438.032620191658
   * BMC Firmware: 1.94.6b42b91d
-  * Apache Pass Firmware: 1.2.0.5310
+  * Intel® Optane™ DC Persistent MemoryFirmware: 1.2.0.5310
 * 2x Intel Xeon Platinum 8268 Processor
 * Intel SSD DC S5600 Series 960GB 2.5in SATA Drive
 * 64 GB RAM - Distributed in 4x 16 GB DDR4 DIMM's
@@ -82,7 +82,7 @@ Hardware configuration used in stacks development
      - Slot 0
 
    * -
-     - 256 AEP
+     - 256 GB DCPMM
      -
      - 16 GB DRAM
      -
@@ -141,33 +141,43 @@ Configuration Steps
    Run the following steps with root privileges (sudo) as shown in the examples
 
 
-#. To configure Optane DIMMs for App direct mode run this command and then reboot the system
+#. To configure Optane DIMMs for App direct mode run this command 
 
    .. code-block:: bash
 
       sudo ipmctl create -goal PersistentMemoryType=AppDirect
 
-
-#. Next, list the pmem devices in the system
+#. Verify the Optane Configuration by showing the defined region, then reboot the system for your changes to take effect
 
    .. code-block:: bash
 
-      sudo ndctl list –N
+      sudo ipmctl show -region
 
 
-#. Create namespaces based on the regions and set mode as fsdax  -- use the names of the regions listed in previous step as the –-region parameter
+#. Next, list the defined namespaces for the pmem devices in the system. If they are not defined, create them as shown in the following step. 
+
+
+   .. code-block:: bash
+
+      sudo ndctl list -N
+
+
+#. Create namespaces based on the regions and set mode as fsdax  -- use the names of the regions listed in previous step as the –-region parameter (default is region0 and region1; one for each CPU socket)
 
    .. code-block:: bash
 
       sudo ndctl create-namespace --region=region0 --mode=fsdax
+      sudo ndctl create-namespace --region=region1 --mode=fsdax
 
 
 #. Create the filesystem and mount it. We are using /mnt/dax{#} as a convention in this guide to mount our devices
 
    .. code-block:: bash
 
-      sudo mkfs.ext4 /dev/pmem{n}
+      sudo mkfs.ext4 /dev/pmem0
       sudo mount -o dax /dev/pmem0 /mnt/dax0
+      sudo mkfs.ext4 /dev/pmem1
+      sudo mount -o dax /dev/pmem1 /mnt/dax1
 
 
 Running DBRS with Apache Cassandra*
@@ -507,7 +517,7 @@ In order to configure the Apache Cassandra PMEM cluster some variables and value
 * image.repository:  The address of the container registry where the cassandra-pmem image should be pulled
 * image.tag:  The tag of the image to be pulled during deployment
 * image.name:  The name of the image to be pulled during deployment
-* pmem.containerPmemAllocation:  The size of the persistent volume claim to be used as heap, it uses the storage class `pmem-csi-sc-ext4` from pmem-csi  The size of the fsdax pool to be created inside the persistent volume claim, in practice it shuld be `1G` less than pmem.containerPmemAllocation
+* pmem.containerPmemAllocation:  The size of the persistent volume claim to be used as heap, it uses the storage class `pmem-csi-sc-ext4` from pmem-csi  The size of the fsdax pool to be created inside the persistent volume claim, in practice it should be `1G` less than pmem.containerPmemAllocation
 * pmem.fsdaxPoolSizeInGB: The size of the fsdax pool to be created inside the persistent volume claim, in practice it should be 1G less than pmem.containerPmemAllocation
 * enablePersistence: If set to `true`, K8s persistent volumes are deployed to store data and logs
 * persistentVolumes.logsVolumeSize:  The size of the persistent volume used for storing logs on each node, the default is `4G`
@@ -518,7 +528,7 @@ In order to configure the Apache Cassandra PMEM cluster some variables and value
 * exposeJmxPort:  When set to `true` it exposes the JMX port as part of the Kubernetes headless service. It should be used together with `enableAdditionalFilesConfigMap` in order to provide authentication files needed for JMX when the remote connections are allowed. When set to `false` only local access through 127.0.0.1 is granted and no additional authentication is needed.
 * enableClientToolsPod:  If set to `true`, an additional pod independent from the cluster is deployed, this pod contains various Cassandra client tools and mounts test profiles located under `<helm-chart-dir>/files/testProfiles` to `/testProfiles` inside the pod. This pod is useful to test and launch benchmarks
 * enableAdditionalFilesConfigMap:  When set to true, it takes the files located in `<helm-chart-dir>/files/additionalFiles` and mount them in `/etc/cassandra` inside the pods, some additional files for cassandra can be stored here, such as JMX auth files
-* jvmOpts.enabled:  If set to `true` the environment variable `JVM_OPTS` is overriden with the value provided on jvmOpts.value
+* jvmOpts.enabled:  If set to `true` the environment variable `JVM_OPTS` is overridden with the value provided on jvmOpts.value
 * jvmOpts.value: Sets the value of the environment variable `JVM_OPTS`, in this way some java runtime configurations can be provided such as RAM heap usage
 * resources.enabled:  if set to `true`, the resource constraints are set on each pod using the values under resources.requests and resources.limits
 * resources.requests.memory: Initial resource allocation for each pod in the cluster

source/guides/stacks/dlrs.rst

@@ -41,15 +41,13 @@ The Deep Learning Reference Stack is available in the following versions:
    * Intel® AVX-512 images require an Intel® Xeon® Scalable Platform
    * VNNI requires a 2nd generation Intel® Xeon® Scalable Platform
 
-Stack features
-==============
+Releases
+********
 
 * `DLRS V4.0`_ release announcement, including benchmark results.
-* `DLRS V3.0`_ release announcement.
-* Deep Learning Reference Stack v2.0 including current
-  `PyTorch benchmark`_.
-* Deep Learning Reference Stack v1.0 including current
-  `TensorFlow benchmark`_ results.
+* `DLRS V3.0`_ release announcement, including benchmark results.
+* `DLRS V2.0`_ including PyTorch benchmark results.
+* `DLRS V1.0`_ including TensorFlow benchmark results.
 * `DLRS Release notes`_  on Github\* for the latest release of Deep Learning
   Reference Stack.
 
@@ -59,12 +57,27 @@ Stack features
    software within the work has its own license.  Please see the `DLRS Terms of Use`_
    for more details about licensing and usage of the Deep Learning Reference Stack.
 
+Version compatibility
+=====================
+
+We validated the steps in this guide against the following software package versions:
+
+* |CL| 26240 (Minimum supported version)
+* Docker 18.06.1
+* Kubernetes 1.11.3
+* Go 1.11.12
+
+.. note::
+
+   The Deep Learning Reference Stack was developed to provide the best user experience when executed on a |CL| host.  However, as the stack runs in a container environment, you should be able to complete the following sections of this guide on other Linux* distributions, provided they comply with the Docker*, Kubernetes* and Go* package versions listed above. Look for your distribution documentation on how to update packages and manage Docker services.
+
+
 Prerequisites
 =============
 
 * :ref:`Install <bare-metal-install-desktop>` |CL| on your host system
-* :command:`containers-basic` bundle
-* :command:`cloud-native-basic` bundle
+* Add the :command:`containers-basic` bundle
+* Add the :command:`cloud-native-basic` bundle
 
 In |CL|, :command:`containers-basic` includes Docker\*, which is required for
 TensorFlow and PyTorch benchmarking. Use the :command:`swupd` utility to
@@ -92,21 +105,42 @@ bundle. To start Docker, enter:
 To ensure that Kubernetes is correctly installed and configured, follow the
 instructions in :ref:`kubernetes`.
 
-Version compatibility
-=====================
 
-We validated these steps against the following software package versions:
 
-* |CL| 26240 (Minimum supported version)
-* Docker 18.06.1
-* Kubernetes 1.11.3
-* Go 1.11.12
+Kubectl
+=======
 
-.. note::
+You can use kubectl to run commands against your Kubernetes cluster.  Refer to
+the `kubectl overview`_ for details on syntax and operations. Once you have a
+working cluster on Kubernetes, use the following YAML script to start a pod with
+a simple shell script, and keep the pod open.
+
+#. Copy this example.yaml script to your system:
+
+   .. code-block:: yaml
+
+      apiVersion: v1
+      kind: Pod
+      metadata:
+        name: example-pod
+        labels:
+          app: ex-pod
+      spec:
+        containers:
+        - name: ex-pod-container
+          image: clearlinux/stacks-dlrs-mkl:latest
+          command: ['/bin/bash', '-c', '--']
+          args: [ "while true; do sleep 30; done" ]
+
+#. Execute the script with kubectl:
+
+   .. code-block:: bash
+
+      kubectl apply –f <path-to-yaml-file>/example.yaml
+
+
+This script opens a single pod and is helpful to verify your setup is complete and correct. More robust solutions would create a deployment or inject a python script or larger shell script into the container.
 
-   The Deep Learning Reference Stack was developed to provide the best user
-   experience when executed on a |CL| host.  However, as the stack runs in a
-   container environment, you should be able to complete the following sections of this guide on other Linux* distributions, provided they comply with the Docker*, Kubernetes* and Go* package versions listed above. Look for your distribution documentation on how to update packages and manage Docker services.
 
 TensorFlow single and multi-node benchmarks
 *******************************************
@@ -228,7 +262,7 @@ Pre-requisites:
 
       # Env variables needed for your deployment
       export KFAPP="<your choice of application directory name>"
-      export CONFIG="https://raw.githubusercontent.com/kubeflow/kubeflow/v0.6.1/bootstrap/config/kfctl_k8s_istio.yaml"
+      export CONFIG="https://raw.githubusercontent.com/kubeflow/manifests/master/kfdef/kfctl_k8s_istio.yaml"
 
       kfctl init ${KFAPP} --config=${CONFIG} -V
       cd ${KFAPP}
@@ -353,7 +387,7 @@ Pre-requisites
 
 .. note::
 
-   Instead of using Arrikto's configuration manifest as shown  in the preceeding example, you should use the manifest provided by `Istio`_, for this example, as Seldon deployments depend on it.
+   Instead of using Arrikto's configuration manifest as shown  in the preceding example, you should use the manifest provided by `Istio`_, for this example, as Seldon deployments depend on it.
 
 #. Install deployment tools
 
@@ -497,7 +531,7 @@ In this example, you will:
 
 #. Run the Model Optimizer
 
-   Running the model optimizer is as simple as calling the appropriate script, however there are many configuration options that are explainedin the documentation
+   Running the model optimizer is as simple as calling the appropriate script, however there are many configuration options that are explained in the documentation
 
    .. code-block:: bash
 
@@ -815,13 +849,13 @@ Related topics
 
 .. _Logging Architecture: https://kubernetes.io/docs/concepts/cluster-administration/logging/
 
-.. _TensorFlow benchmark: https://clearlinux.org/stacks/deep-learning-reference-stack
+.. _DLRS V1.0: https://clearlinux.org/stacks/deep-learning-reference-stack
 
-.. _PyTorch benchmark: https://clearlinux.org/stacks/deep-learning-reference-stack-pytorch
+.. _DLRS V2.0: https://clearlinux.org/stacks/deep-learning-reference-stack-pytorch
 
 .. _Jupyter Notebook: https://jupyter.org/
 
-.. _Overview of kubectl: https://kubernetes.io/docs/reference/kubectl/overview/
+.. _kubectl overview: https://kubernetes.io/docs/reference/kubectl/overview/
 
 .. _launcher.py: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow
 
@@ -831,7 +865,7 @@ Related topics
 
 .. _Seldon Core: https://docs.seldon.io/projects/seldon-core/en/latest/
 
-.. _Istio: https://raw.githubusercontent.com/kubeflow/kubeflow/master/bootstrap/config/kfctl_k8s_istio.yaml
+.. _Istio: https://github.com/kubeflow/manifests/blob/master/kfdef/kfctl_k8s_istio.yaml
 
 .. _Dockerfile_openvino_base: https://github.com/clearlinux/dockerfiles/blob/master/stacks/dlrs/kubeflow/dlrs-seldon/docker/Dockerfile_openvino_base
 

source/reference/image-types.rst

@@ -21,7 +21,7 @@ The naming convention of a |CL| image filename is:
   file format.
 
 * The *[compression type]* field specifies the compression type. Two types of
-  compressions are used: GNU\* zip (*.gz*) and XZ (*.xz*).
+  compression methods are used: GNU\* zip (*.gz*) and XZ (*.xz*).
 
 .. _incl-image-filename-end:
 
@@ -80,8 +80,7 @@ Table 2 lists the currently available images that are platform specific.
      - Image suitable for use with PXE server.
 
    * - vmware.vmdk
-     - Virtual Machine Disk for VMware\* platforms inclduing Player, Workstation, and ESXi.
+     - Virtual Machine Disk for VMware\* platforms including Player, Workstation, and ESXi.
 
 .. _images: https://clearlinux.org/downloads
 .. _`optimized kernel`: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels
-

source/reference/system-requirements.rst

@@ -4,7 +4,8 @@ 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 GB RAM, and 2 GB of disk space.
+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:`about <about>` can
 be used to create a highly customized installation that can even run on a
@@ -44,7 +45,6 @@ these features:
   - Supplemental Streaming SIMD Extension 3 (Intel® SSSE3)
   - Intel® Streaming SIMD Extensions 4.1 (Intel® SSE 4.1)
   - Intel® Streaming SIMD Extensions 4.2 (Intel® SSE 4.2)
-  - Intel® Advanced Encryption Standard New Instructions (Intel® AES-NI)
   - Carry-less Multiplication (PCLMUL)
 
 The following processor families have been verified to run |CL|:

source/tutorials/docker.rst

@@ -15,7 +15,7 @@ This tutorial covers:
 
 .. note::
 
-   This tutorial focuses on the installaton of the Docker ecosystem.
+   This tutorial focuses on the installation of the Docker ecosystem.
    If you want to use |CL| as a Docker container image, refer to the
    official |CL| container image
    `published on Docker* Hub <https://hub.docker.com/_/clearlinux/>`_
@@ -146,7 +146,7 @@ typically located at :file:`/etc/docker/daemon.json`. |CL| features a
 Pulling and running an image from Docker Hub
 ********************************************
 
-`Docker Hub`_ is a publically available container image repository which
+`Docker Hub`_ is a publicly available container image repository which
 comes pre-configured with Docker. In the example below we will pull and run
 an the official Docker image for nginx\*, an open source reverse proxy server.
 
@@ -239,4 +239,4 @@ Related topics
 
 .. _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/
+.. _Docker Device Mapper storage driver: https://docs.docker.com/storage/storagedriver/device-mapper-driver/

source/tutorials/multi-boot/dual-boot-linux.rst

@@ -0,0 +1,282 @@
+.. _dual-boot-linux:
+
+Dual-boot |CL-ATTR| with Another GRUB-based Linux\* Distro
+##########################################################
+
+In this tutorial, we show how to install another GRUB-based Linux\* distro 
+alongside |CL|.  To do so, we resize the existing Linux root partition to 
+make enough room to install |CL|. Then we configure the |CL| bootloader, 
+:command:`systemd-boot`, which enables you to dual-boot |CL| and an existing
+Linux distro.  Although we use Ubuntu\* 19.04 Desktop as the example here, 
+these instructions also work for other distros such as Mint Linux, Kubuntu\*, Fedora\*, CentOS\*, among others.
+
+.. contents::
+   :local:
+   :depth: 1
+
+Prerequisites
+*************
+
+* Ubuntu 19.04 Desktop is already installed. 
+* There is no unallocated space available, but there is free space 
+  on the Ubuntu root partition.
+* Follow the Preliminary steps that follow below. 
+
+.. include:: ../../get-started/bare-metal-install-desktop.rst
+   :start-after: preliminary-steps-install-desktop:
+   :end-before: install-on-target-start:
+
+Install |CL| with Advanced Installation
+***************************************
+
+#. Shut down the Ubuntu OS before proceeding.
+
+#. Boot up the |CL| live desktop image, and click the penguin 
+   icon, at left, to launch the installer.
+
+#. Complete the :guilabel:`Required Options` until you reach 
+   :guilabel:`Select Installation Media`. See Figure 1.
+
+   .. figure:: ../../_figures/multi-boot/dual-boot-linux-01.png
+      :scale: 100%
+      :alt: Required options
+
+      Figure 1: Required options  
+
+#. Click :guilabel:`Select Installation Media`.  
+
+#. Select the “Advanced Installation” option. See Figure 2.  
+
+   .. figure:: ../../_figures/multi-boot/dual-boot-linux-02.png
+      :scale: 100%
+      :alt: Advanced Installation
+
+      Figure 2: Advanced Installation 
+
+#. Click :guilabel:`Partition Media` to start the GParted tool. 
+
+#. Shrink the Ubuntu root partition to free up some space for |CL|.
+
+   a. Select the Ubuntu root partition (in this example: /dev/sda2). 
+      Right-click it and select “Resize/Move”.  See Figure 3.
+
+      .. figure:: ../../_figures/multi-boot/dual-boot-linux-03.png
+         :scale: 100%
+         :alt: Ubuntu root partition
+
+         Figure 3: Ubuntu root partition
+
+   #. In the :guilabel:`New size (MiB)` field, reduce the size of the root
+      partition, leaving at least 22GB free. This allows enough space to 
+      create a swap partition (250MB) and root partition (approx. 21GB) for 
+      |CL|.  
+
+      .. note:: 
+
+         The resulting free space appears in the “Free space following 
+         (MiB)”. Click the “Resize/Move” button.  See Figure 4.
+
+      .. figure:: ../../_figures/multi-boot/dual-boot-linux-04.png
+         :scale: 100%
+         :alt: Resize Ubuntu root
+
+         Figure 4: Resize Ubuntu root
+
+   #. Click the green checkmark button to proceed. See Figure 5.  
+
+      .. figure:: ../../_figures/multi-boot/dual-boot-linux-05.png
+         :scale: 100%
+         :alt: New unallocated space
+
+         Figure 5: New unallocated space
+
+#. Share the existing EFI system partition by designating as such.
+
+   a. Right-click the :guilabel:`EFI System Partition` (e.g., /dev/sda1)
+      and select :guilabel:`Name Partition`.  
+
+   #. Set the name to “CLR_BOOT”.  See Figure 6 and Figure 7.  
+
+      .. figure:: ../../_figures/multi-boot/dual-boot-linux-06.png
+         :scale: 100%
+         :alt: Name CLR_BOOT partition
+
+         Figure 6: Name CLR_BOOT partition
+
+      .. figure:: ../../_figures/multi-boot/dual-boot-linux-07.png
+         :scale: 100%
+         :alt: Resulting CLR_BOOT main screen
+
+         Figure 7: Resulting CLR_BOOT main screen
+
+#. Create a swap partition for |CL|.
+
+   a. Right-click the “unallocated” partition and select :guilabel:`New` 
+      to add a new partition.
+
+   #. Enter “250” in the :guilabel:`New Size (MiB)` field to create a 
+      250MB swap space. 
+
+   #. Enter “CLR_SWAP” in the :guilabel:`Partition name` field and select
+      “linux-swap” as the “File system” type.  
+
+   #. Click the “Add” button.  See Figure 8.
+
+      .. figure:: ../../_figures/multi-boot/dual-boot-linux-08.png
+         :scale: 100%
+         :alt: Create CLR_SWAP partition
+
+         Figure 8: Create CLR_SWAP partition
+
+#. Create |CL| root partition.
+
+   a. Right-click “unallocated” partition again and select :guilabel:`New` 
+      to add a new partition.
+
+   #. Create a partition that is at least 21GB, enter “CLR_ROOT” in the 
+      :guilabel:`Partition name` field, and select a :guilabel:`File system` 
+      type of your choice.    
+
+   #. Click the “Add” button.  See Figure 9. 
+
+      .. figure:: ../../_figures/multi-boot/dual-boot-linux-09.png
+         :scale: 100%
+         :alt: Create CLR_ROOT partition
+
+         Figure 9: Create CLR_ROOT partition
+
+#. Click the green checkmark button to create the newly-defined partitions. 
+   See Figure 10.  
+
+   .. figure:: ../../_figures/multi-boot/dual-boot-linux-10.png
+      :scale: 100%
+      :alt: Partitions to be created
+
+      Figure 10: Partitions to be created
+
+#. Close the GParted window, and the |CL| installer will reappear with 
+   the newly-defined partitions to use.  See Figure 11.
+
+   .. figure:: ../../_figures/multi-boot/dual-boot-linux-11.png
+      :scale: 100%
+      :alt: |CL| installer partitions defined
+
+      Figure 11: |CL| installer partitions defined
+
+#. Complete the remaining steps of :guilabel:`Required Options` to 
+   to install |CL|. Complete any :guilabel:`Advanced Options` as desired.
+    
+Ways to boot |CL|
+*****************
+
+Although we installed |CL| last, Ubuntu is still the default boot OS.  There are several ways to boot |CL|:
+
+#. Use your BIOS “Boot Menu” to select and boot |CL|.  
+   This is temporary and will not make |CL| the default boot OS.  
+
+#. Make systemd-boot, the boot loader that |CL| uses, the default
+   boot loader to boot |CL| and chain-boot GRUB; therefore, boot 
+   Ubuntu. Follow the next section to implement this.  
+
+Make systemd-boot Default Bootloader and chain-boot GRUB
+********************************************************
+
+#. Boot up the |CL| installer image.
+#. Open a terminal window. 
+#. Identify the EFI system partition, Ubuntu root partition, and |CL| root
+   partition. 
+
+   .. code-block:: bash
+
+      sudo fdisk -l
+
+   Example output:
+
+   .. code-block:: console
+
+      clrlinux@clr-live~ $ sudo fdisk -l 
+      ... 
+
+      Disk /dev/sda: 335.4 GiB, 360080695296 bytes, 703282608 sectors
+      Disk model: INTEL SSDSCKKF36
+      Units: sectors of 1 * 512 = 512 bytes
+      Sector size (logical/physical): 512 bytes / 512 bytes
+      I/O size (minimum/optimal): 512 bytes / 1048576 bytes
+      Disklabel type: gpt
+      Disk identifier: D5CB69E9-2C27-4A16-9552-3CD6BFA5DA77
+
+      Device         Start       End   Sectors   Size Type
+      /dev/sda1       2048   1050623   1048576   512M EFI System
+      /dev/sda2    1050624 498481151 497430528 237.2G Linux filesystem
+      /dev/sda3  498481152 498993151    512000   250M Linux swap
+      /dev/sda4  498993152 703281151 204288000  97.4G Linux root (x86-64)
+      ...
+
+   The above example output contains these partitions:
+
+   * /dev/sda1 is the EFI system partition originally created by Ubuntu 
+     and shared with |CL|
+   * /dev/sda2 is the Ubuntu root partition
+   * /dev/sda3 is the swap partition for |CL|
+   * /dev/sda4 is the |CL| root partition
+
+   The remaining steps will work with these partitions.
+
+#. Mount these partitions
+
+   .. code-block:: bash
+      
+      sudo mkdir /mnt/clearlinux
+      sudo mount /dev/sda4 /mnt/clearlinux/
+      sudo mount /dev/sda1 /mnt/clearlinux/boot
+
+#. Make systemd-boot the default bootloader
+
+   .. code-block:: bash	
+
+      sudo bootctl install --esp-path=/mnt/clearlinux/boot
+
+#. Add a timeout to systemd-boot so that it will present the menu of
+   bootable OSes and give you time to select the one you want to boot. 
+
+   .. code-block:: bash	
+
+      sudo clr-boot-manager set-timeout 20 --path=/mnt/clearlinux
+      sudo clr-boot-manager update --path=/mnt/clearlinux
+
+#. Add a system-boot boot entry for GRUB.
+   
+   .. code-block:: bash	
+
+      sudo tee -a /mnt/clearlinux/boot/loader/entries/grub.conf << EOF
+      title GRUB menu
+      efi /EFI/ubuntu/grubx64.efi
+      EOF
+
+#. Umount all partitions. 
+
+   .. code-block:: bash	
+     
+      sudo umount /mnt/clearlinux/boot /mnt/clearlinux
+
+#. Reboot.
+
+   .. code-block:: bash
+   
+      sudo reboot
+
+#. Remove the |CL| installer USB thumb drive.
+
+#. You should be presented with the :command:`systemd-boot` menu.
+   See Figure 12. 
+
+   .. figure:: ../../_figures/multi-boot/dual-boot-linux-12.png
+      :scale: 100%
+      :alt: systemd-boot menu showing GRUB
+
+      Figure 12: systemd-boot menu showing GRUB
+
+.. _download the live desktop image: https://clearlinux.org/downloads
+
+.. _Downloads: https://clearlinux.org/downloads
+

source/tutorials/nvidia-cuda.rst

@@ -184,7 +184,7 @@ installed.
 
    .. code-block:: bash
 
-      /usr/local/cuda/bin/nvcc --version
+      /opt/cuda/bin/nvcc --version
       
       
 The CUDA Toolkit is now installed and can be used to compile and run CUDA

source/tutorials/nvidia.rst

@@ -34,9 +34,29 @@ Prerequisites
 * A |CL| system with a desktop installed
 * An NVIDIA device installed
 
-Install DKMS
+.. note:: NVIDIA Optimus
+   
+   Some systems come with a hybrid graphics configuration for a balanced power
+   and performance profile. This configuration is commonly found on
+   laptops. `NVIDIA Optimus* technology
+   <https://www.geforce.com/hardware/technology/optimus>`_, is designed to
+   allow switching seamlessly between a NVIDIA device and another graphics
+   devices sharing the same display.
+   
+   Getting NVIDIA Optimus* on Linux working well with both graphics devices
+   adds an additional level of complexity with platform specific steps and may
+   require additional software. Installation for systems with NVIDIA Optimus*
+   with both graphics devices operating is not covered by the scope of this
+   documentation. As a simple workaround, some systems can disable one of the
+   graphics devices or NVIDIA Optimus* in the system firmware.
+
+
+Installation
 ************
 
+Install DKMS
+============
+
 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|.
@@ -51,11 +71,8 @@ Install the appropriate DKMS bundle using the instructions below:
    :start-after: kernel-modules-dkms-install-begin:
    :end-before: kernel-modules-dkms-install-end:
 
-Download and install the NVIDIA drivers
-***************************************
-
-Download the NVIDIA drivers for Linux
-=====================================
+Download the NVIDIA drivers
+===========================
 
 #. Identify the NVIDIA GPU model that is installed.
 
@@ -65,22 +82,19 @@ Download the NVIDIA drivers for Linux
 
 #. Go to the `NVIDIA Driver Downloads website`_ . Search for and download the
    appropriate driver based on the NVIDIA GPU model you have with *Linux
-   64-bit* selected as the Operating System .
-
-#. Open a terminal and navigate to where the
-   :file:`NVIDIA-Linux-x86_64-<VERSION>.run` file was saved. In this
-   example, it was saved in the Downloads folder.
+   64-bit* selected as the Operating System.
 
    .. code-block:: bash
 
-      cd ~/Downloads/
+      wget https://download.nvidia.com/XFree86/Linux-x86_64/<VERSION>/NVIDIA-Linux-x86_64-<VERSION>.run   
 
-#. Make the :file:`NVIDIA-Linux-x86_64-<VERSION>.run` file executable.
+   If you already know the appropriate driver version for your device, you can
+   also obtain a download link directly from one of the links below:
 
-   .. code-block:: bash
-
-      chmod +x :file:`NVIDIA-Linux-x86_64-<VERSION>.run`
+   - https://www.nvidia.com/en-us/drivers/unix/
+   - https://download.nvidia.com/XFree86/Linux-x86_64/
 
+      
 Disable the nouveau driver
 ==========================
 
@@ -146,12 +160,19 @@ Install the NVIDIA drivers
    installation progress. Switch to a secondary virtual terminal by pushing
    :command:`CTRL + ALT + F2` or remotely login over SSH.
 
-#. Navigate to the directory where the NVIDIA installer was downloaded.
+#. Navigate to the directory where the NVIDIA installer was downloaded. In
+   this example, it was saved in the :file:`Downloads` folder.
 
    .. code-block:: bash
 
       cd ~/Downloads/
 
+#. Make the :file:`NVIDIA-Linux-x86_64-<VERSION>.run` file executable.
+
+   .. code-block:: bash
+
+      chmod +x NVIDIA-Linux-x86_64-<VERSION>.run
+
 #. Run the installer with the advanced options below.
 
    .. code-block:: bash
@@ -192,17 +213,25 @@ Install the NVIDIA drivers
 
       sudo swupd repair --quick --bundles=lib-opengl
 
-.. note::
+   .. warning:: 
 
-   The NVIDIA software places some files under the :file:`/usr` subdirectory
-   that are not managed by |CL| and conflict with the |CL| stateless design.
+      Although a limited version of :command:`swupd repair` is run above,
+      other uses of the :command:`swupd repair` command should be avoided
+      with the proprietary NVIDIA drivers installed.
 
-   Although a limited version of :command:`swupd repair` is run above,
-   other uses of the :command:`swupd repair` command should be avoided
-   with the proprietary NVIDIA drivers installed.
+      The NVIDIA software places some files under the :file:`/usr` subdirectory
+      that are not managed by |CL| and conflict with the |CL| stateless design.
 
-Updating the NVIDIA drivers
-***************************
+#. Optional: Create a link for the nvidia-settings desktop entry to
+   :file:`~/.local/share` so that it appears in the launcher for easy access. 
+
+   .. code-block:: bash
+
+      ln -sv /opt/nvidia/share/applications/nvidia-settings.desktop $HOME/.local/share
+
+
+Updating
+********
 
 The proprietary NVIDIA drivers are installed manually outside of
 :ref:`swupd <swupd-guide>` and must be updated manually when needed.
@@ -211,7 +240,7 @@ Updating the NVIDIA drivers follows the same steps as initial installation,
 however the desktop environment must first be stopped so that the drivers are
 not in use.
 
-#. Follow the steps in the `Download the NVIDIA Drivers for Linux`_ section
+#. Follow the steps in the `Download the NVIDIA drivers`_ section
    to get the latest NVIDIA drivers.
 
 #. Temporarily set the default boot target to the *multi-user*, which is
@@ -243,8 +272,8 @@ not in use.
 
       flatpak update
 
-Uninstalling the NVIDIA drivers
-*******************************
+Uninstallation
+**************
 
 The NVIDIA drivers and associated software can be uninstalled and nouveau
 driver restored with the instructions in this section.
@@ -261,12 +290,25 @@ driver restored with the instructions in this section.
 
       sudo rm /etc/X11/xorg.conf.d/nvidia-files-opt.conf
 
-#. Run the :command:`sudo /opt/nvidia/bin/nvidia-uninstall`
+#. Remove the nvidia-settings desktop entry file if it was linked to
+   :file:`~/.local/share`.
+
+   .. code:: bash
+
+      unlink -v $HOME/.local/share/nvidia-settings.desktop
+
+
+#. Run the :command:`nvidia-uninstall` command.
+
+   .. code:: bash
+
+      sudo /opt/nvidia/bin/nvidia-uninstall
 
 #. Follow the prompts on the screen and reboot the system.
 
-Debugging installation of NVIDIA drivers
-****************************************
+
+Troubleshooting
+***************
 
 * The NVIDIA driver places installer and uninstaller logs under
   :file:`/var/log/nvidia-install` and :file:`/var/log/nvidia-uninstall`.
@@ -278,8 +320,56 @@ Debugging installation of NVIDIA drivers
   installation files into a directory named
   :file:`NVIDIA-Linux-x86_64-<VERSION>`.
 
+
+Brightness control
+==================
+
+If you can't control the screen brightness with the NVIDIA driver installed,
+try one of the solutions below:
+
+- Add a kernel parameter *acpi_osi=* which disables the ACPI Operating System
+  Identification function. Some system firmware may manipulate brightness
+  control keys based on the reported operating system. Disabling the
+  identification mechanism can cause the system firmware to expose brightness
+  controls that are recognizable in Linux.
+
+  .. code:: bash
+
+     sudo mkdir -p /etc/kernel/cmdline.d 
+     echo "acpi_osi=" | sudo tee /etc/kernel/cmdline.d/acpi-backlight.conf   
+     sudo clr-boot-manager update  
+
+
+
+- Add a kernel parameter for the nvidia driver:
+  *NVreg_EnableBacklightHandler=1*. This handler overrides the ACPI-based one
+  provided by the video.ko kernel module. This option is available with NVIDIA
+  driver version 387.22 and above. 
+  
+  .. code:: bash
+
+     sudo mkdir -p /etc/kernel/cmdline.d 
+     echo "nvidia.NVreg_EnableBacklightHandler=1" | sudo tee /etc/kernel/cmdline.d/nvidia-backlight.conf   
+     sudo clr-boot-manager update
+     
+
+- Add the *EnableBrightnessControl=1* options to the *Device*
+  section of your xorg config. Below is an example:
+
+  .. code:: bash
+
+     sudo mkdir -p /etc/X11/xorg.conf.d/
+
+     sudo tee /etc/X11/xorg.conf.d/nvidia-brightness.conf > /dev/null <<'EOF'
+     Section "Device"
+         Identifier     "Device0"
+         Driver         "nvidia"
+         Option         "RegistryDwords" "EnableBrightnessControl=1"
+     EndSection   
+     EOF
+
 Additional resources
-********************
+====================
 
 * `Why aren't the NVIDIA Linux drivers open source? <https://nvidia.custhelp.com/app/answers/detail/a_id/1849/kw/Linux>`_
 
@@ -290,3 +380,5 @@ Additional resources
 .. _`nouveau project`:  https://nouveau.freedesktop.org/wiki/
 
 .. _`NVIDIA Driver Downloads website`: https://www.nvidia.com/download/index.aspx
+
+

source/tutorials/php.rst

@@ -0,0 +1,253 @@
+.. _php:
+
+PHP and PHP-FPM
+###############
+
+This tutorial describes how to configure and use :abbr:`PHP (PHP: Hypertext Preprocessor)`
+and :abbr:`PHP-FPM (PHP FastCGI Process Manager)` on |CL-ATTR|.
+
+.. contents::
+    :local:
+    :depth: 1
+
+Description
+***********
+
+The `PHP language`_ is an Open Source general-purpose scripting language that is popular
+with web-developers who leverage its ability to create dynamically generated
+web pages. `PHP-FPM`_ is a PHP FastCGI implementation that controls process
+management, workers, and logging for PHP. The two applications work together,
+but each one has its own configuration.
+
+This tutorial specifically addresses PHP and PHP-FPM, however, it provides a
+general guide for working with applications in the |CL| :ref:`stateless`
+environment.
+
+
+Background
+**********
+
+By default, PHP looks for configuration settings in the :file:`php.ini` file,
+which resides in the :file:`usr/share/defaults/php/` path. Because |CL| is a
+:ref:`stateless` operating system, you must create an optional configuration
+file to override the default values. Every time :command:`swupd` updates the
+system, it overwrites changes to the :file:`/usr/share/defaults` file
+structure. To save your configuration options through updates, you must create
+a PHP configuration file in a location that will not be overwritten. The
+recommended location is within the :file:`/etc` file structure, which is why this
+tutorial creates a :file:`/etc/php.d` directory.
+
+The PHP-FPM configuration file is separate from the :file:`php.ini` file used
+by PHP, however it has a similar default path restriction. |CL| installs the
+default :file:`php-fpm.conf` file in :file:`/usr/share/defaults/php`. This
+file with its default values is overwritten during each software update.
+However, PHP-FPM requires that the configuration file exist in that location,
+and, by design, does not read configuration options from a different path.
+This tutorial describes a solution to changing PHP-FPM configuration options
+in |CL|, by manually  overriding the php-fpm.service unit in systemd to pass
+an explicit location to a custom :file:`php-fpm.conf` file.
+
+
+Prerequisites
+*************
+
+* :ref:`Install <bare-metal-install-desktop>` |CL| on your host system.
+* Use :command:`swupd` to install the :file:`php-basic` bundle:
+
+  .. code-block:: bash
+
+     sudo swupd bundle-add php-basic
+
+.. note::
+
+   PHP does not require a web server for operation. If you need a web
+   server, refer to :ref:`web-server-install` for instructions on setting
+   up a :abbr:`LAMP (Linux, Apache\*, MySQL, PHP)` server, or use
+   :command:`swupd` to install :file:`nginx` or similar.
+
+
+Configure PHP
+*************
+
+.. important::
+
+   This section does **not** describe configuration for the PHP-FPM service, which is
+   described later in this guide.
+
+This section creates a :file:`/etc/php.d` directory for all PHP configuration
+files to work around the default path restriction.
+
+#.  Create a :file:`php.ini` file:
+
+    .. code-block:: bash
+
+       sudo mkdir -p /etc/php.d
+       sudo touch /etc/php.d/my-php.ini
+
+    This file can be edited with any of your specific configuration
+    requirements, and will not be overwritten when :command:`swupd` performs
+    an update. The `PHP configuration file`_ documentation contains details
+    about what you can set in this file.
+
+#.  Verify the location of the PHP configuration files:
+
+    .. code-block:: bash
+
+       php --ini
+
+    You should see output like this:
+
+    .. code-block:: console
+
+       Configuration File (php.ini) Path: /usr/share/defaults/php/
+       Loaded Configuration File:         /usr/share/defaults/php/php.ini
+       Scan for additional .ini files in: /etc/php.d
+       Additional .ini files parsed:
+
+
+    This output indicates that PHP will read the :file:`php.ini` file from
+    :file:`/usr/share/defaults/php` and will then load any further
+    configuration from :file:`.ini` files in :file:`/etc/php.d/`. The
+    :file:`my-php.ini` file in :file:`/etc/php.d` contains your configuration
+    details, and allows the defaults to be read from
+    :file:`/usr/share/defaults/php/`. Note that the :file:`my-php.ini` file
+    has not been parsed, because the file has no content at this
+    point and is disregarded.
+
+Install PHP extensions
+**********************
+
+PHP extensions are compiled libraries designed to enable specific functions in
+your PHP code. |CL| provides PHP extensions in the :file:`php-extras` bundle.
+
+#.  Install the bundle with swupd:
+
+    .. code-block:: bash
+
+       sudo swupd bundle-add php-extras
+
+#.  Find the list of extensions included in the `php-extras`_ bundle on the
+    |CL| `Store`_.
+
+
+Enable PHP extensions
+*********************
+
+To enable an installed extension, you must add it to the :file:`php.ini` file
+for the composer.
+
+#.  Create the :file:`my-php.ini` file using the directive to load the
+    php-imagick extension:
+
+    .. code-block:: bash
+
+       sudo echo "extension=imagick.so" >> /etc/php.d/my-php.ini
+
+#.  Restart the php-fpm service for PHP to pick up the modification to the
+    :file:`/etc/php.d/my-php.ini` file:
+
+    .. code-block:: bash
+
+       sudo systemctl restart php-fpm
+
+#.  Verify that the imagick extension has been loaded by searching through the
+    runtime list of loaded PHP Modules:
+
+    .. code-block:: bash
+
+       php -m | grep imagick
+
+
+.. note::
+
+   To enable an extension, you must install it, add it to the
+   :file:`my-php.ini` file, and restart the :file:`php-fpm` service. However,
+   some extensions may have configuration options, which will be documented by
+   the extension maintainer. Add the options you need to the
+   :file:`/etc/php.d/my-php.ini` file as described in the extension's
+   documentation. Be sure to restart :file:`php-fpm` after changing the file.
+
+Configure PHP-FPM
+*****************
+
+The PHP-FPM configuration file is separate from the :file:`php.ini` file used
+by PHP, however, it has a similar default path restriction. Follow the steps
+below to configure PHP-FPM.
+
+
+#.  Copy the :file:`/usr/share/defaults/php/php-fpm.conf` file to the
+    :file:`/etc/php.d` file:
+
+    .. code-block:: bash
+
+       sudo cp /usr/share/defaults/php/php-fpm.conf /etc/php.d/php-fpm.conf
+
+#.  Make changes to the :file:`php-fpm.conf` file as needed. The
+    `FPM documentation`_ has details on the configuration options available
+    to PHP-FPM.
+
+#.  Edit the systemd service unit file:
+
+    .. code-block:: bash
+
+       sudo systemctl edit --full php-fpm.service
+
+    This opens the :file:`php-fpm.service` file for systemd in your editor.
+
+#.  Change the :command:`ExecStart` configuration to add the
+    :command:`--fpm-config` option to point to the custom location:
+
+    .. code-block:: console
+
+       [Unit]
+       Description=The PHP FastCGI Process Manager
+       After=syslog.target network.target
+
+       [Service]
+       Type=notify
+       PIDFile=/run/php-fpm.pid
+       ExecStart=/usr/sbin/php-fpm --nodaemonize --fpm-config /etc/php.d/php-fpm.conf
+       ExecReload=/bin/kill -USR2 $MAINPID
+       PrivateTmp=true
+
+       [Install]
+       WantedBy=multi-user.target
+
+#.  Restart the service:
+
+    .. code-block:: bash
+
+       sudo systemctl restart php-fpm.service
+
+#.  Verify that the new path has been picked up:
+
+    .. code-block:: bash
+
+       sudo systemctl status php-fpm.service
+
+    You should see the new path in the output:
+
+    .. code-block:: console
+
+       ● php-fpm.service - The PHP FastCGI Process Manager
+       Loaded: loaded (/etc/systemd/system/php-fpm.service; enabled; vendor preset: disabled)
+       Active: active (running) since Thu 2019-10-17 13:19:34 PDT; 8min ago
+       Main PID: 14452 (php-fpm)
+       Status: "Processes active: 0, idle: 0, Requests: 0, slow: 0, Traffic: 0req/sec"
+        Tasks: 1
+       Memory: 11.1M
+       CGroup: /system.slice/php-fpm.service
+               └─14452 php-fpm: master process (/etc/php.d/php-fpm.conf)
+
+
+.. _PHP language: https://www.php.net/
+
+.. _PHP-FPM: https://php-fpm.org/
+
+.. _php-extras: https://clearlinux.org/software/bundle/php-extras
+
+.. _Store: https://clearlinux.org/software/
+
+.. _PHP configuration file: https://www.php.net/manual/en/configuration.file.php
+
+.. _FPM documentation: https://www.php.net/manual/en/install.fpm.configuration.php

source/tutorials/wordpress/web-server-install.rst

@@ -25,10 +25,10 @@ Apache is an open source HTTP web server application that can run on several
 operating systems, including |CL|. Go to the `Apache HTTP Server Project`_
 for more information.
 
-Install the web-server-basic bundle
-===================================
+Install the httpd bundle
+========================
 
-The **web-server-basic** bundle contains the packages needed to install the
+The **httpd** bundle contains the packages needed to install the
 Apache software bundle on |CL|.
 
 .. note::
@@ -44,7 +44,7 @@ Apache software bundle on |CL|.
 
    .. code-block:: bash
 
-      sudo swupd bundle-add web-server-basic
+      sudo swupd bundle-add httpd
 
 
 #. To start the Apache service, enter the following commands: