Merge pull request #6 from clearlinux/master

Update from upstream
2026-09-03 20:31:31 +00:00 · 2018-12-05 11:26:56 -08:00
parent f3e8dc8307 41fc8d41a0
commit 57eb03e316
116 changed files with 6807 additions and 1138 deletions
@@ -3,33 +3,33 @@
 |CL-PRJ|
 #############################################

-Welcome to the |CLOSIA| documentation pages, the source for |CL| documentation. 
+Welcome to the |CL-ATTR| documentation pages, the source for |CL| documentation.
 Our documentation is divided into the following sections:

 * :ref:`get-started`

-  If you are new to |CL|, get started fast with tutorials for installing |CL| on 
-  bare metal, in a virtual environment, or as a live image on a USB stick. 
+  If you are new to |CL|, get started fast with tutorials for installing |CL| on
+  bare metal, in a virtual environment, or as a live image on a USB stick.

-* :ref:`concepts` 
-  
-  Wondering what makes |CL| different? Learn about |CL| features and what 
+* :ref:`concepts`
+
+  Wondering what makes |CL| different? Learn about |CL| features and what
  differentiates |CL| from other Linux distros.

-* :ref:`guides` 
+* :ref:`guides`

-  Guides show how to complete common tasks that help you leverage |CL| native 
-  features effectively. From basic system configuration to advanced management 
+  Guides show how to complete common tasks that help you leverage |CL| native
+  features effectively. From basic system configuration to advanced management
  of a cloud installation, there is a guide for you.

-* :ref:`tutorials` 
+* :ref:`tutorials`

-  |CL| tutorials provide step-by-step instructions on how |CL| features can 
-  be used and extended, frequently with third-party tools. 
+  |CL| tutorials provide step-by-step instructions on how |CL| features can
+  be used and extended, frequently with third-party tools.

-* :ref:`reference` 
-  
-  Find the detailed information you need to enable your configuration or task 
+* :ref:`reference`
+
+  Find the detailed information you need to enable your configuration or task
  in our |CL| reference section.

 .. toctree::
@@ -1,14 +1,82 @@
 .. _mixer-about:

 Mixer
-#######
+#####

-Mixing refers to composing a custom, versioned image of |CLOSIA| for a specific use case. While upstream |CL| provides options to install bundles for various capabilities, some developers and OSVs may wish to either augment the operating system with functionality from their own packages or modify the structure of current bundles. Mixing offers a method to add capabilities while retaining the ability to stay up to date with an upstream version of |CL|.
+|CL-ATTR| is a powerful, modular, and customizable OS. Upstream |CL| offers
+many images to support different environments and use-cases.  There are
+hundreds of bundles that will meet most, if not all, of your OS and software
+needs.

-Mixing is a multi-step process that starts with installing the mixer bundle using swupd. You will also need a working knowledge of :abbr:`RPMs (RPM Package Manager files)` and how |CL| bundles work. For a detailed guide on how to create a |CL| mix, visit :ref:`mixer`.
+However, if you need additional customization or content, |CL| provides the
+mixer tool. Depending on your needs, the mixer tool allows you to:

-Related Concepts
-================
+1. :ref:`create-mix` to create a distinct derivative of the |CL| that
+   contains your custom software.
+2. :ref:`create-mixin` to add custom bundles but also keep updating the OS
+   from upstream.

-* :ref:`swupd-about`
+.. _create-mix:
+
+Create a mix
+============
+
+When creating a mix, you can
+
+* Use any existing upstream bundles with no modification.
+* Redefine what goes into existing bundles.
+* Create completely new, custom bundles with your own custom packages.
+
+With mixer you are not required to incorporate every upstream release into
+your mix. You decide which upstream versions to update your derivative to, as
+illustrated in Figure 1.
+
+.. figure:: figures/mixer-about-1.png
+   :scale: 75%
+   :alt: Creating a custom mix.
+
+   Figure 1: With a custom mix, you add your custom bundle and decide which
+   upstream versions to update your mix to, on your own release cycle.
+
+Creating your own mix forks away from the |CL| upstream and requires that you
+act as your own OSV. There is a greater level of responsibility, requiring
+more infrastructure and processes to adopt. However, with this approach, you
+have a higher degree of control and customization of your custom |CL|.
+
+
+.. _create-mixin:
+
+Create a mixin
+==============
+
+The second option is to use the :command:`mixin` tool, a light wrapper for
+mixer, to create custom bundles and sideload them into your upstream version
+of |CL|. A mixin is useful when you need to add custom or 3rd
+party content but want to keep on the upstream update cycle, as shown in
+Figure 2. You can also create new bundles using upstream packages.
+
+.. figure:: figures/mixer-about-2.png
+   :scale: 75%
+   :alt: Creating a custom mix.
+
+   Figure 2: With a mixin you can add custom bundles, but stay on upstream.
+
+Mixin is primarily intended for end users. It is easier to adopt as it does
+not require breaking from upstream or acting as an OSV. With mixin
+
+* You are responsible for maintaining and testing your custom bundle(s).
+* You retain access to all upstream bundles and updates.
+* You can easily revert your system back to the upstream version.
+
+Related topics
+==============
+
+|CL| provides flexibility in how you customize your OS. Learn more about
+mixer and related topics to decide which customization approach is best for
+you.
+
+* :ref:`mixer`
+* :ref:`mixin`
 * :ref:`bundles-about`
+* :ref:`swupd-about`
+* :ref:`deploy-at-scale`
@@ -97,7 +97,7 @@ standards. Below are some examples:
  have been removed such as the `finger` and `tcpwrappers`.

 * `SFTP` has been disabled by default due to security 
-  considerations. See the `openssh-server reference page`_ for more details. 
+  considerations. 


 Verified trust
@@ -182,7 +182,6 @@ good security hygiene. Below are some examples:

 .. _`documentation about Software Updates`: https://clearlinux.org/documentation/clear-linux/concepts/swupd-about
 .. _`cve-check-tool`: https://github.com/clearlinux/cve-check-tool
-.. _`openssh-server reference page`: https://clearlinux.org/documentation/clear-linux/reference/bundles/openssh-server
 .. _`blog post about swupd security`: https://clearlinux.org/blogs/security-software-update-clear-linux-os-intel-architecture
 .. _`rolling release model`: https://en.wikipedia.org/wiki/Rolling_release
 .. _`clrtrust`: https://github.com/clearlinux/clrtrust
@@ -3,35 +3,35 @@
 Software update
 ###############

-|CLOSIA| does software updates differently than traditional Linux-based 
-operating systems. Where traditional distributions rely on packages for 
-software deployment, |CL| uses the concept of a "bundle" for 
-deployment. Traditional Linux packages provide a particular utility or 
-library; |CL| bundles provide all necessary packages to enable a 
+|CL-ATTR| does software updates differently than traditional Linux-based
+operating systems. Where traditional distributions rely on packages for
+software deployment, |CL| uses the concept of a "bundle" for
+deployment. Traditional Linux packages provide a particular utility or
+library; |CL| bundles provide all necessary packages to enable a
 specific function.

-With |CL|, updating equates to an entirely new OS version with a 
-specific set of bundles, as compared to a package-based distribution in 
-which packages may be updated individually. |CL| updates are 
+With |CL|, updating equates to an entirely new OS version with a
+specific set of bundles, as compared to a package-based distribution in
+which packages may be updated individually. |CL| updates are
 efficient, updating only changed files instead of entire packages.

-System administrators can customize or add bundles to the OS, while still 
-taking advantage of a controlled update stream. This enables system 
+System administrators can customize or add bundles to the OS, while still
+taking advantage of a controlled update stream. This enables system
 administrators to focus on the pieces that make their deployment unique.


 Bundles
 =======

-While we use packages to manage compiling source code into installable 
-binaries, we do not deploy software through packages. Instead, we use bundles 
-to deploy software, where each bundle encapsulates a particular functionality 
-- functionality that is enabled by composing all the required upstream 
-open-source projects and packages into one logical unit: a bundle. This 
+While we use packages to manage compiling source code into installable
+binaries, we do not deploy software through packages. Instead, we use bundles
+to deploy software, where each bundle encapsulates a particular functionality
+-- functionality that is enabled by composing all the required upstream
+open-source projects and packages into one logical unit: a bundle. This
 simplifies installing features on |CL|.

-For additional resources regarding available bundles, useful bundle commands, 
-and compatible |CL| kernels, visit our :ref:`bundles-about` 
+For additional resources regarding available bundles, useful bundle commands,
+and compatible |CL| kernels, visit our :ref:`bundles-about`
 page.


@@ -65,8 +65,8 @@ describe the versions of all the software on the OS. Each build is
 composed of a specific set of bundles made from a particular version of
 packages. This matters on a daily basis to system administrators, who
 need to determine which of their systems do not have the latest security
-fixes, or which combinations of software have been tested. Every release 
-of the same number is guaranteed to contain the same versions of software, 
+fixes, or which combinations of software have been tested. Every release
+of the same number is guaranteed to contain the same versions of software,
 so there's no ambiguity between two systems running the same version of |CL|.


@@ -76,20 +76,20 @@ Updating
 Another notable difference between package-based distributions and |CL|
 is how updates are managed. On a package-based OS, system administrators update
 each individual package or piece of software to a newer (or older!) version. With
-|CL|, an update translates to an entirely new OS version, containing one 
-or many updates.  It is not possible to update a piece of the system while 
+|CL|, an update translates to an entirely new OS version, containing one
+or many updates.  It is not possible to update a piece of the system while
 remaining on the same version of |CL|.

 How is this useful? Although it seems, at first, like a huge restriction
 or limitation, this method has many non-obvious benefits. Imagine a
 cloud environment composed of numerous machines.  Here, a homogeneous set of
 software makes sense -- from the system administrator's level down to the
-user level. Homogeneous systems allow users to focus on their contributions 
-and/or code, rather than configuring environments or worrying about 
-synchronizing versions and updates.  At the system admin level, it ensures 
+user level. Homogeneous systems allow users to focus on their contributions
+and/or code, rather than configuring environments or worrying about
+synchronizing versions and updates.  At the system admin level, it ensures
 security is tighter and makes it far easier to monitor and update patches.

-|CL| promotes regular updating of the OS and will automatically check 
+|CL| promotes regular updating of the OS and will automatically check
 for updates and apply them by default.

 To learn how to run an update of your system, visit our :ref:`swupd-guide` page.
@@ -98,9 +98,9 @@ To learn how to run an update of your system, visit our :ref:`swupd-guide` page.
 Update speed
 ============

-Software updates with |CL| are also efficient. Bundles simply describe 
-a set of files, and the update technology updates *only* files that actually 
-changed by using binary-delta technology for efficiency [1]_. Operating systems 
+Software updates with |CL| are also efficient. Bundles simply describe
+a set of files, and the update technology updates *only* files that actually
+changed by using binary-delta technology for efficiency [1]_. Operating systems
 that use packages as the unit of deployment require full package updates (thus
 hogging resources), even when one small file in that package has changed.

@@ -128,5 +128,5 @@ a controlled update stream.
 To learn more about mixing, visit our :ref:`mixer-about` page.


-.. [1] The software update technology for |CLOSIA| was first presented at the 
+.. [1] The software update technology for |CL-ATTR| was first presented at the
   Linux Plumbers conference in 2012.
@@ -0,0 +1,808 @@
+.. _bare-metal-install-beta:
+
+Install |CL-ATTR| from the live desktop beta image
+##################################################
+
+The live desktop beta image allows you to boot |CL-ATTR| into a GNOME
+desktop without modifying the host system. Using the live image, you can
+explore the possibilities of developing with |CL|. You can also launch the
+new installer and install |CL| on your target system.
+
+.. contents:: :local:
+   :depth: 1
+
+System requirements
+*******************
+
+Assure that your target system supports the installation:
+
+* :ref:`system-requirements`
+* :ref:`compatibility-check`
+
+Preliminary steps
+*****************
+
+#. `Navigate to the image directory`_.
+
+#. Download the file :file:`clear-<release number>-live-desktop-beta.img.xz`
+
+   .. note::
+
+      ``<release-number>`` is the latest |CL| auto-numbered release.
+
+#. Follow your OS instructions to create a bootable USB drive.
+
+   * :ref:`bootable-usb-linux-all`
+   * :ref:`bootable-usb-mac-all`
+   * :ref:`bootable-usb-windows-all`
+
+.. _install-from-live-image:
+
+Install from live image
+***********************
+
+After you've downloaded and burned the live desktop image on a
+USB drive, follow these steps.
+
+#. Insert the USB drive into an available USB slot.
+
+#. Power on the system.
+
+#. Open the system BIOS setup menu by pressing the F2 key.
+
+   .. note::
+
+    Your BIOS setup menu entry point may vary.
+
+#. In the setup menu, enable the UEFI boot and set the USB drive as the
+   first option in the device boot order.
+
+#. Save these settings and exit.
+
+#. Reboot the target system.
+
+Launch the installer
+====================
+
+#. After the |CL| live desktop image boots, select the :guilabel:`Activities`   menu in the upper left.
+
+#. Select the icon, :guilabel:`Install Clear Linux OS`, shown in Figure 1.
+
+   .. figure:: figures/bare-metal-install-beta-1.png
+     :scale: 50 %
+     :alt: Install Clear Linux OS icon
+
+     Figure 1: Install Clear Linux OS icon
+
+#. Upon selecting the icon, the installer is launched, as shown in Figure 2.
+
+   .. figure:: figures/bare-metal-install-beta-2.png
+     :scale: 50 %
+     :alt: Clear Linux OS Installer
+
+     Figure 2: Clear Linux OS Installer
+
+.. _minimum-installation-requirements:
+
+Minimum installation requirements
+*********************************
+
+To fulfill minimum installation requirements, complete the
+:guilabel:`Required options`. :guilabel:`Advanced options` are optional. Additional user help is described below.
+
+.. note::
+
+   * The :kbd:`Install` button is only highlighted **after** you complete the
+     :ref:`required-options-installation`, and after you enter all required
+     values in submenus of :ref:`required-options-installation` and
+     :ref:`advanced-options-installation`.
+
+   * You must choose whether or not to participate in :ref:`telemetrics`
+     before you can finish installation.
+
+   * You may wish to :ref:`test-network-settings` before you
+     :ref:`configure-network-interfaces`. Assure that a ``Success`` message is received before installation.
+
+Main Menu
+*********
+
+In the |CL| Installer Main Menu, two tabs appear:
+:guilabel:`[R] Required options` and :guilabel:`[A] Advanced options`.
+Navigate between tabs using the arrow keys or these shortcut keys:
+
+* :kbd:`Shift+A` for :guilabel:`[A] Advanced options`
+* :kbd:`Shift+R` for :guilabel:`[R] Required options`
+
+To meet the minimum requirements, enter your choices in the
+:guilabel:`Required options`. After confirmation, your selections appear
+below menu options in the Main Menu, beside the :guilabel:`>>` chevron.
+
+Navigation
+**********
+
+* Select :kbd:`Tab` or :kbd:`Up/Down` arrows to highlight your choice.
+
+* Select :kbd:`Enter` or :kbd:`Spacebar` to confirm your choice.
+
+* Select :kbd:`Cancel` or :kbd:`Esc` to cancel your choice.
+
+  The |CL| Installer Main Menu appears as shown in Figure 3.
+
+  .. figure:: figures/bare-metal-install-beta-3.png
+     :scale: 100 %
+     :alt: Clear Linux OS Installer Main Menu
+
+     Figure 3: :guilabel:`Clear Linux OS Installer Main Menu`
+
+.. _required-options-installation:
+
+Required options
+****************
+
+Choose Timezone
+===============
+
+#. From the Main Menu, select :guilabel:`Choose Timezone`.
+
+#. Select :kbd:`Enter` to continue.
+
+#. In :guilabel:`Select System Timezone`, navigate to
+   the desired timezone.
+
+#. Use :kbd:`Tab` to navigate to :guilabel:`Confirm`.
+
+#. Select :kbd:`Enter` to :kbd:`Confirm`.
+
+   .. note::
+
+      Select :guilabel:`Cancel` to restore the previously defined value and
+      return to the Main Menu.
+
+   .. figure:: figures/bare-metal-install-beta-4.png
+      :scale: 100 %
+      :alt: Select System Timezone
+
+      Figure 4: :guilabel:`Select System Timezone`
+
+Choose Language
+===============
+
+#. From the Main Menu, select :guilabel:`Choose Language`.
+
+#. Select :kbd:`Enter`.
+
+#. In :guilabel:`Select System Language`, navigate to your desired language.
+
+#. Select :kbd:`Tab` to highlight :kbd:`Confirm`.
+
+#. Select :kbd:`Enter` to :kbd:`Confirm`.
+
+   .. note::
+
+      Select :guilabel:`Cancel` to restore the previously defined value and return to the Main Menu.
+
+   .. figure:: figures/bare-metal-install-beta-5.png
+      :scale: 100 %
+      :alt: Select System Language
+
+      Figure 5: :guilabel:`Select System Language`
+
+
+Configure the Keyboard
+======================
+
+#. From the Main Menu, select :guilabel:`Configure the Keyboard`.
+
+#. Select :kbd:`Enter`.
+
+#. In :guilabel:`Select Keyboard`, navigate to the desired option.
+
+#. In :guilabel:`Test keyboard`, type text to assure that the keys map to
+   your keyboard.
+
+#. Select :kbd:`Tab` to highlight :guilabel:`Confirm`.
+
+#. Select :kbd:`Enter` to :kbd:`Confirm`.
+
+   .. note::
+
+      Select :guilabel:`Cancel` to restore the previously defined value and return to the Main Menu.
+
+   .. figure:: figures/bare-metal-install-beta-6.png
+      :scale: 100 %
+      :alt: Select Keyboard menu
+
+      Figure 6: :guilabel:`Select Keyboard menu`
+
+Configure Media
+===============
+
+#. From the Main Menu, select :guilabel:`Configure Media`.
+
+   .. note::
+
+      Available media appear by default.
+
+#. Navigate to the desired media until highlighted.
+
+   .. figure:: figures/bare-metal-install-beta-7.png
+      :scale: 100 %
+      :alt: Configure Media menu
+
+      Figure 7: :guilabel:`Configure Media menu`
+
+      .. note::
+
+         Use additional options as necessary during partitioning:
+
+         * Select :guilabel:`Revert` to cancel changes and revert to the
+           original configuration.
+         * Select :guilabel:`Rescan` to show media connected to the host
+           machine.
+
+#. Select :kbd:`Enter` or :kbd:`Spacebar` to select it.
+
+   Two options for partitioning appear.
+
+#. Select :guilabel:`Auto Partition` to accept the default configuration, or
+   :guilabel:`Add Partition` to add partitions manually. See instructions
+   below.
+
+#. Select :kbd:`Enter` to :kbd:`Confirm`.
+
+#. Choose one partitioning option and continue below:
+
+   * :ref:`auto-partition`
+   * :ref:`add-partition`
+
+.. _auto-partition:
+
+Auto Partition
+==============
+
+Auto partition will configure the media to meet the minimum requirements.
+
+#. Select :guilabel:`Auto Partition` as shown in Figure 8.
+
+#. Select :kbd:`Enter` or :kbd:`Spacebar` to highlight
+   :guilabel:`Auto partition`.
+
+#. Select :kbd:`Enter` to :kbd:`Confirm`.
+
+   This action returns you to the Main Menu.
+
+   .. figure:: figures/bare-metal-install-beta-8.png
+      :scale: 100 %
+      :alt: Auto Partition
+
+      Figure 8: :guilabel:`Auto Partition`
+
+#. You may skip to the :ref:`telemetry-tui` section below.
+
+.. _add-partition:
+
+Add Partition
+=============
+
+Minimum requirements
+====================
+
+To add partitions manually, assign partitions per the minimum
+requirements shown in Table 1:
+
+.. list-table:: **Table 1. Disk Partition Setup**
+   :widths: 33, 33, 33
+   :header-rows: 1
+
+   * - FileSystem
+     - Mount Point
+     - Minimum size
+   * - ``VFAT``
+     - /boot
+     - 150M
+   * - ``swap``
+     -
+     - 256MB
+   * - ``root``
+     - /
+     - *Size depends upon use case/desired bundles.*
+
+#. In the Configure Media menu, select :guilabel:`Add Partition`.
+
+   .. note:: To change an existing partition, navigate to the partition,
+      and select :guilabel:`Enter`.
+
+boot partition
+--------------
+
+#. In the :guilabel:`File System` menu, select :kbd:`Up/Down` arrows to
+   select the file system type.  See Figure 9.
+
+#. In :guilabel:`Mount Point`, enter the ``/boot`` partition.
+
+#. In :guilabel:`Size`, enter an appropriate size (e.g., 150M) per Table 1.
+
+#. Navigate to :guilabel:`Confirm` until highlighted.
+
+#. Select :guilabel:`Enter` to confirm.
+
+   .. figure:: figures/bare-metal-install-beta-9.png
+      :scale: 100 %
+      :alt: boot partition
+
+      Figure 9: :guilabel:`boot partition`
+
+swap partition
+--------------
+
+#. In the :guilabel:`File System` menu, select :kbd:`Up/Down` arrows to
+   select the file system type. See Figure 10.
+
+#. In :guilabel:`Mount Point`, the field remains blank.
+
+   .. note::
+
+      The Mount Point field is disabled.
+
+#. In :guilabel:`Size`, enter an appropriate size (e.g., 256MB) per Table 1.
+
+#. Navigate to :guilabel:`Add`.
+
+#. Select :guilabel:`Enter` to continue.
+
+   .. figure:: figures/bare-metal-install-beta-10.png
+      :scale: 100 %
+      :alt: swap partition
+
+      Figure 10: :guilabel:`swap partition`
+
+root partition
+--------------
+
+#. In the :guilabel:`File System` menu, select :kbd:`Up/Down` arrows to
+   select the file system type. See Figure 11.
+
+#. In :guilabel:`Mount Point`, enter ``/root``.
+
+#. In :guilabel:`Size`, enter an appropriate size per Table 1.
+
+   .. note::
+
+      The remaining available space shows by default.
+
+#. Navigate to :guilabel:`Add` until highlighted.
+
+#. Select :guilabel:`Enter` to continue.
+
+   You are returned to the :guilabel:`Configure media` menu.
+
+#. Select :guilabel:`Confirm` to complete the media selection.
+
+   .. figure:: figures/bare-metal-install-beta-11.png
+      :scale: 100 %
+      :alt: root partition
+
+      Figure 11: :guilabel:`root partition`
+
+   You are returned to the :guilabel:`Configure media` menu. Your partitions should appear similar to those shown in Figure 12.
+
+   .. figure:: figures/bare-metal-install-beta-12.png
+      :scale: 100 %
+      :alt: Partitions
+
+   Figure 12: :guilabel:`Partitions`
+
+#. Navigate to :guilabel:`Confirm` until highlighted.
+
+#. Select :guilabel:`Enter` to complete adding partitions.
+
+.. _telemetry-tui:
+
+Telemetry
+=========
+
+To fulfill the :guilabel:`Required options`, choose whether or not to
+participate in `telemetry`_.  :ref:`telemetrics` is a |CL| feature that
+reports failures and crashes to the |CL| development team for improvements.
+For more detailed information, visit our :ref:`telemetry-about` page.
+
+#. In the Main Menu, navigate to :guilabel:`Telemetry` and select
+   :kbd:`Enter`.
+
+#. Select :kbd:`Tab` to highlight your choice.
+
+#. Select :kbd:`Enter` to confirm.
+
+   .. figure:: figures/bare-metal-install-beta-13.png
+      :scale: 100 %
+      :alt: Enable Telemetry
+
+      Figure 13: :guilabel:`Enable Telemetry`
+
+Skip to finish installation
+===========================
+
+After selecting values for all :guilabel:`Required options`, you may skip
+directly to :ref:`finish-cl-installation`
+
+In the Main Menu, select the :guilabel:`Advanced options` if you wish to
+configure network interfaces or proxy settings, add bundles, add/manage
+users, and more. Continue to the next section.
+
+.. _advanced-options-installation:
+
+Advanced Options
+****************
+
+.. _configure-network-interfaces:
+
+Configure Network Interfaces
+============================
+
+By default, |CL| is configured to automatically detect the host network
+interface using DHCP. However, if you want to use a static IP address or if
+you do not have a DHCP server on your network, follow these instructions to
+manually configure the network interface. Otherwise, default network
+interface settings are automatically applied.
+
+.. note::
+
+   If DHCP is available, no user selection may be required.
+
+#. Navigate to :guilabel:`Configure Network Interfaces` and
+   select :kbd:`Enter`.
+
+#. Navigate to the network :guilabel:`interface` you wish to change.
+
+#. When the desired :guilabel:`interface` is highlighted, select
+   :guilabel:`Enter` to edit.
+
+   .. note:: Multiple network interfaces may appear.
+
+   .. figure:: figures/bare-metal-install-beta-14.png
+      :scale: 100 %
+      :alt: Configure Network Interfaces
+
+      Figure 14: :guilabel:`Configure Network Interfaces`
+
+#. Notice :guilabel:`Automatic / dhcp` is selected by default (at bottom).
+
+   Optional: Navigate to the checkbox :guilabel:`Automatic / dhcp` and select
+   :kbd:`Spacebar` to deselect.
+
+   .. figure:: figures/bare-metal-install-beta-15.png
+      :scale: 100 %
+      :alt: Network interface configuration
+
+      Figure 15: :guilabel:`Network interface configuration`
+
+#. Navigate to the appropriate fields and assign the desired
+   network configuration.
+
+#. To save settings, navigate to :guilabel:`Confirm` and select
+   :kbd:`Enter`.
+
+   .. note::
+
+      To revert to previous settings, navigate to the :guilabel:`Cancel`
+      and select :kbd:`Enter`.
+
+#. Upon confirming network configuration, the :guilabel:`Testing Networking`
+   dialogue appears. Assure the result shows success. If a failure occurs,
+   your changes will not be saved.
+
+#. Upon confirmation, you are returned to :guilabel:`Network interface`
+   settings.
+
+#. Navigate to and select :guilabel:`Main Menu`.
+
+Optional: :ref:`Skip to finish installation <finish-cl-installation>`.
+
+Proxy
+=====
+
+|CL| automatically attempts to detect proxy settings, as described in
+`Autoproxy`_. If you need to manually assign proxy settings, follow this
+instruction.
+
+#. From the Advanced options menu, navigate to :guilabel:`Proxy`, and
+   select :kbd:`Enter`.
+
+#. Navigate to the field :guilabel:`HTTPS Proxy`.
+
+   .. figure:: figures/bare-metal-install-beta-16.png
+      :scale: 100 %
+      :alt: Configure the network proxy
+
+      Figure 16: :guilabel:`Configure the network proxy`
+
+#. Enter the desired proxy address and port using conventional syntax,
+   such as: \http://address:port.
+
+#. Navigate to :guilabel:`Confirm` and select :kbd:`Enter`.
+
+#. To revert to previous settings, navigate to :guilabel:`Cancel`
+   and select :guilabel:`Cancel`.
+
+Optional: :ref:`Skip to finish installation <finish-cl-installation>`.
+
+.. _test-network-settings:
+
+Test Network Settings
+=====================
+
+To manually assure network connectivity before installing |CL|,
+select :guilabel:`Test Network Settings` and select :guilabel:`Enter`.
+
+A progress bar appears as shown in Figure 17.
+
+.. figure:: figures/bare-metal-install-beta-17.png
+   :scale: 100 %
+   :alt: Testing Networking dialogue
+
+   Figure 17: :guilabel:`Testing Networking dialogue`
+
+.. note::
+
+   Any changes made to network settings are automatically tested
+   during configuration.
+
+Optional: :ref:`Skip to finish installation <finish-cl-installation>`.
+
+Bundle Selection
+================
+
+#. On the Advanced menu, select :guilabel:`Bundle Selection`
+
+#. Navigate to the desired bundle using :kbd:`Tab` or :kbd:`Up/Down` arrows.
+
+#. Select :kbd:`Spacebar` to select the checkbox for each desired bundle.
+
+   .. figure:: figures/bare-metal-install-beta-18.png
+      :scale: 100 %
+      :alt: Bundle Selection
+
+      Figure 18: :guilabel:`Bundle Selection`
+
+..TODO:Add new screenshot that shows more bundles.
+
+#. Select :kbd:`Confirm` or :kbd:`Cancel`.
+
+   You are returned to the :guilabel:`Advanced options` menu.
+
+Optional: :ref:`Skip to finish installation <finish-cl-installation>`.
+
+User Manager
+============
+
+Add New User
+------------
+
+#. In Advanced Options, select :guilabel:`User Manager`.
+
+#. Select :guilabel:`Add New User` as shown in Figure 19.
+
+   .. figure:: figures/bare-metal-install-beta-19.png
+      :scale: 100 %
+      :alt: Add New User, User Name
+
+      Figure 19: :guilabel:`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-beta-20.png
+      :scale: 100 %
+      :alt: User Name
+
+      Figure 20: :guilabel:`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:`Retype`, 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.
+
+   .. figure:: figures/bare-metal-install-beta-21.png
+      :scale: 100 %
+      :alt: Administrative rights
+
+      Figure 21: :guilabel:`Administrative rights`
+
+#. Select :kbd:`Confirm`.
+
+   .. note::
+
+      If desired, select :guilabel:`Reset` to reset the form.
+
+#. In :guilabel:`User Manager`, navigate to :guilabel:`Confirm`.
+
+#. With :guilabel:`Confirm` highlighted, select :kbd:`Enter`.
+
+Modify / Delete User
+--------------------
+
+#. In User Manager, select :guilabel:`Tab` to highlight the user, as shown
+   in Figure 22.
+
+#. Select :kbd:`Enter` to modify the user.
+
+   .. figure:: figures/bare-metal-install-beta-22.png
+      :scale: 100 %
+      :alt: Modify User
+
+      Figure 22: :guilabel:`Modify User`
+
+#. Modify user details as desired.
+
+   Optional: To delete the user, navigate to the :guilabel:`Delete`
+   button and select :kbd:`Enter`
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+   .. note::
+
+      Optional: Select :guilabel:`Reset` to rest the form.
+
+#. Select :guilabel:`Confirm` to save the changes you made.
+
+You are returned to the User Manager menu.
+
+Optional: :ref:`Skip to finish installation <finish-cl-installation>`.
+
+Kernel Command Line
+===================
+
+For advanced users, |CL| provides the ability to add or remove kernel
+arguments. If you want to append a new argument, enter the argument here.
+This argument will be used every time you install or update a
+new kernel.
+
+#. In Advanced Options, select :guilabel:`Tab` to highlight
+   :guilabel:`Kernel Command Line`.
+
+#. Select :kbd:`Enter`.
+
+#. To add or remove arguments, choose one of the following options.
+
+   .. figure:: figures/bare-metal-install-beta-23.png
+      :scale: 100 %
+      :alt: kernel command line
+
+      Figure 23: :guilabel:`kernel command line`
+
+#. To add arguments, enter the argument in :guilabel:`Add Extra Arguments`.
+
+#. To remove an existing argument, enter the argument in
+   :guilabel:`Remove Arguments`.
+
+#. Select :kbd:`Confirm`.
+
+Optional: :ref:`Skip to finish installation <finish-cl-installation>`.
+
+Kernel Selection
+================
+
+#. Select a kernel option. By default, the latest kernel release is
+   selected.
+
+   .. note::
+
+      To choose a different kernel, such as Long Term Support (LTS), shown in Figure 24, navigate to it using :guilabel:`Tab`.
+
+   .. figure:: figures/bare-metal-install-beta-24.png
+      :scale: 100 %
+      :alt: Kernel selection
+
+      Figure 24: :guilabel:`Kernel selection`
+
+#. Select :kbd:`Spacebar` to select the desired option.
+
+#. Select :kbd:`Confirm`.
+
+Optional: :ref:`Skip to finish installation <finish-cl-installation>`.
+
+Swupd Mirror
+============
+
+If you have your own custom mirror of |CL|, you can add its URL.
+
+#. In Advanced Options, select :guilabel:`Swupd Mirror`.
+
+#. To add a local swupd mirror, enter a valid URL in :guilabel:`Mirror URL:`
+
+#. Select :kbd:`Confirm`.
+
+   .. figure:: figures/bare-metal-install-beta-25.png
+      :scale: 100 %
+      :alt: Swupd Mirror
+
+      Figure 25: :guilabel:`Swupd Mirror`
+
+Optional: :ref:`Skip to finish installation <finish-cl-installation>`.
+
+Assign Hostname
+===============
+
+#. In Advanced Options, select :guilabel:`Assign Hostname`.
+
+#. In :guilabel:`Hostname`, enter the hostname only (excluding the domain).
+
+   .. note::
+
+      Hostname does not allow empty spaces. Hostname must start with an
+      alphanumeric character but may also contain hyphens. Maximum length of
+      63 characters.
+
+   .. figure:: figures/bare-metal-install-beta-26.png
+      :scale: 100 %
+      :alt: Assign Hostname
+
+      Figure 26: :guilabel:`Assign Hostname`
+
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+#. Select :kbd:`Confirm`.
+
+Optional: :ref:`Skip to finish installation <finish-cl-installation>`.
+
+Automatic OS Updates
+====================
+
+In the rare case that you need to disable automatic software updates,
+follow the onscreen instructions.
+
+#. In Advanced Options, select :guilabel:`Automatic OS Updates`.
+
+#. Select the desired option.
+
+   .. figure:: figures/bare-metal-install-beta-27.png
+      :scale: 100 %
+      :alt: Automatic OS Updates
+
+      Figure 27: :guilabel:`Automatic OS Updates`
+
+You are returned to the :guilabel:`Main Menu`.
+
+.. _finish-cl-installation:
+
+Finish installation
+*******************
+
+#. When you are satisfied with your installation configuration, navigate to
+   :guilabel:`Install` and select :kbd:`Enter`.
+
+   .. note::
+
+      Whenever installation is finished, a ``reboot`` button appears.
+
+#. Select ``reboot``.
+
+#. When the system reboots, remove any installation media present.
+
+**Congratulations!**
+
+You have successfully installed |CL| on bare metal using the new installer.
+
+.. _Navigate to the image directory: https://download.clearlinux.org/image/
+.. _Autoproxy: https://clearlinux.org/features/autoproxy
+.. _telemetry: https://clearlinux.org/features/telemetry
@@ -6,9 +6,9 @@ Install |CL-ATTR| on bare metal (automatic)
 These instructions guide you through the installation of |CL-ATTR|
 on bare metal using a bootable USB drive.

-Before you begin, check that your system meets the requirements to install |CL|: 
+Before you begin, check that your system meets the requirements to install |CL|:

-* :ref:`system-requirements` 
+* :ref:`system-requirements`
 * :ref:`compatibility-check`


@@ -19,7 +19,7 @@ Get the latest |CL| installer image from the `image`_ directory.
 Look for the :file:`clear-[version number]-installer.img.xz` file. You can also use this command:

 .. code-block:: bash
-   
+
   curl -O https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep "installer")

 Once you have downloaded the image, verify and decompress the file.
@@ -58,7 +58,7 @@ Follow these steps to install |CL| on the target system:
 #. Reboot the target system.

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

   .. figure:: figures/bare-metal-install-1.png
@@ -225,7 +225,7 @@ process. Otherwise, you can follow the |CL| automatic installation steps.
   :guilabel:`< Automatic >` menu item shown in figure 7 and press the
   :kbd:`Enter` key.

-   The :guilabel:`Choose target device for installation` screen shown in figure 8 appears.  
+   The :guilabel:`Choose target device for installation` screen shown in figure 8 appears.

 #. Move the cursor to the desired target and press the :kbd:`Enter`
   key.
@@ -255,7 +255,7 @@ process. Otherwise, you can follow the |CL| automatic installation steps.
   through the automated installation process.

   Once all steps have completed, you will see the :guilabel:`Successful
-   installation` status message and the :guilabel:`< Ok >` button is highlighted as shown in figure 10. 
+   installation` status message and the :guilabel:`< Ok >` button is highlighted as shown in figure 10.

 #. Press the :kbd:`Enter` key to continue.

@@ -266,10 +266,10 @@ process. Otherwise, you can follow the |CL| automatic installation steps.
      Figure 10: :guilabel:`Installation complete`

   Figure 11 shows the final installer screen, showing that the
-   installation completed successfully and the system will reboot. 
+   installation completed successfully and the system will reboot.

-#. Press the :kbd:`Enter` key and remove the USB media while the system 
-   restarts. 
+#. Press the :kbd:`Enter` key and remove the USB media while the system
+   restarts.

   .. figure:: figures/bare-metal-install-11.png
      :scale: 50 %
@@ -306,8 +306,8 @@ Next steps
 **********

 The automatic installation of |CL| is designed to install with minimal
-software overhead. Some housekeeping and package installations could be 
-needed before you can take full advantage of the |CL| operating system. 
+software overhead. Some housekeeping and package installations could be
+needed before you can take full advantage of the |CL| operating system.

 See the :ref:`enable-user-space` guide for additional information and
 instructions.
@@ -0,0 +1,203 @@
+.. _bootable-usb-beta-all:
+
+Create a bootable USB on your OS
+################################
+
+Follow these instructions to create a bootable |CL-ATTR| USB drive based on 
+your OS.
+
+* :ref:`bootable-usb-linux-all`
+* :ref:`bootable-usb-mac-all`
+* :ref:`bootable-usb-windows-all`
+
+Return to :ref:`install-from-live-image`
+
+Requirements: 
+*************
+
+* Use a **16GB** or larger USB drive. 
+
+.. _bootable-usb-linux-all:
+
+Create a bootable USB drive on Linux
+************************************
+
+.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst
+   :Start-after: verify-linux:
+
+
+Burn the |CL| image onto a USB drive
+====================================
+
+.. caution::
+
+   |CAUTION-BACKUP-USB|
+
+#. Open a terminal emulator and get root privilege.
+
+   .. code-block:: bash
+
+      sudo -s
+
+#. Go to the directory with the decompressed image.
+#. Plug in the USB drive.
+#. Identify the USB drive using the :command:`lsblk` command. This shows all
+   drives attached to the system, including the primary hard disk. In the
+   example output below, there are 4 drives 
+   (`/dev/sda`, `/dev/sdb`, `/dev/sdc`, and `/dev/sdd`) attached, where 
+   `/dev/sda` is primary drive in this case. The remaining are 3 USB drives.
+   The output also shows the mounted partitions (under the `MOUNTPOINT`
+   column) for each drive.
+
+   .. code-block:: bash
+
+      lsblk
+
+   Example output:
+
+   .. code-block:: console
+
+      NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
+      sdd      8:48   1    15G  0 disk
+      ├─sdd2   8:50   1     5G  0 part /run/media/user1/960c184f-3bb7-42b7-bcaf-0c1282
+      ├─sdd3   8:51   1     8G  0 part /run/media/user1/704f3382-b26d-4f34-af1b-cb9aab
+      └─sdd1   8:49   1     2G  0 part
+      sdb      8:16   1  14.8G  0 disk
+      └─sdb1   8:17   1  14.8G  0 part /run/media/user1/PATRIOT_USB
+      sdc      8:32   1   7.3G  0 disk
+      └─sdc1   8:33   1   7.3G  0 part /run/media/user1/LINUX MINT
+      sda      8:0    0 335.4G  0 disk
+      ├─sda4   8:4    0    28G  0 part
+      ├─sda2   8:2    0   3.7G  0 part [SWAP]
+      ├─sda7   8:7    0     6G  0 part /home
+      ├─sda5   8:5    0     1G  0 part /boot
+      ├─sda3   8:3    0   954M  0 part /boot/efi
+      ├─sda1   8:1    0    28G  0 part
+      ├─sda8   8:8    0    30G  0 part /
+      └─sda6   8:6    0   7.9G  0 part [SWAP]
+
+#. Before an image can be burned onto a USB drive, it should be un-mounted.
+   Some Linux* distros may automatically mount a USB drive when it is plugged
+   in. To unmount, use the :command:`umount` command followed by the device
+   identifier/partition. For example: From the above :command:`lsblk` output,
+   `/dev/sdd` has 2 mounted partitions.  To unmount them, enter:
+
+   .. code-block:: bash
+
+      umount /dev/sdd2
+      umount /dev/sdd3
+
+#. Burn the image onto the USB drive. The command-line example below burns an
+   uncompressed image onto `/dev/sdd`:
+
+   .. code-block:: bash
+
+      dd if=./clear-[version number]-[image type] of=/dev/sdd bs=4M status=progress
+
+.. _bootable-usb-mac-all:
+
+Create a bootable USB drive on macOS*
+*************************************
+
+.. include:: ../../guides/maintenance/download-verify-decompress-mac.rst
+   :start-after: verify-mac:
+
+
+Burn the |CL| image onto a USB drive
+====================================
+
+.. caution::
+
+   |CAUTION-BACKUP-USB|
+
+#. Launch the Terminal app.
+#. Go to the directory with the decompressed image.
+#. Plug in a USB drive and get its identifier by entering the command
+   :command:`diskutil list`.  See Figure 1.
+
+   .. code-block:: console
+
+      diskutil list
+
+   .. figure:: figures/bootable-usb-mac-1.png
+      :scale: 100 %
+      :alt: Get USB drive identifier
+
+      Figure 1: macOS* - Get USB drive identifier
+
+#. Unmount the USB drive identified in the previous step.  The command-line
+   example below umounts `/dev/disk2`:
+
+   .. code-block:: console
+
+      diskutil umountDisk /dev/disk2
+
+#. Burn the image onto the drive using the :command:`dd` command.  The 
+   command-line example below burns an uncompressed image onto `/dev/disk2`:
+
+   .. code-block:: console
+
+      sudo dd if=./clear-[version number]-[image type] of=/dev/rdisk2 bs=4m
+
+
+   Adding an ‘r’ in front of the disk identifier should help speed up the 
+   imaging process.
+   
+   You can press :kbd:`<CTL>-T` to check imaging progress.
+
+#. Eject the USB drive.
+
+   .. code-block:: console
+
+      diskutil eject /dev/disk2
+
+.. _bootable-usb-windows-all:
+
+Create a bootable USB drive on Windows\*
+****************************************
+
+.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst
+   :Start-after: verify-windows:
+
+Burn the |CL| image onto a USB drive
+====================================
+
+.. caution::
+
+   |CAUTION-BACKUP-USB|
+
+#. Download the `Rufus`_ utility to burn the image onto a USB drive.
+
+#. Plug in the USB drive and open Rufus.
+
+#. Click the :guilabel:`SELECT` button. See Figure 1.
+
+   .. figure:: figures/bootable-usb-windows-1.png
+      :scale: 80 %
+      :alt: Rufus utility - Click the SELECT button
+
+      Figure 1: Rufus utility - Click the SELECT button
+
+#. Find and select the previously extracted |CL| image file. 
+   Then, click the  :guilabel:`Open` button. See Figure 2.
+
+   .. figure:: figures/bootable-usb-windows-2.png
+      :scale:  80 %
+      :alt: Rufus utility - Show and select |CL| image file
+
+      Figure 2: Rufus utility - Show and select |CL| image file
+    
+#. Click the :guilabel:`START` button. See Figure 3.
+
+   .. figure:: figures/bootable-usb-windows-3.png
+      :scale: 80 %
+      :alt: Rufus utility - Click the START button
+         
+      Figure 3: Rufus utility - Click START button
+
+Return to install from live image
+*********************************
+
+Return to :ref:`install-from-live-image`
+
+.. _Rufus: https://rufus.ie/
@@ -14,14 +14,16 @@ Pre-install
 * :ref:`compatibility-check`
 * :ref:`bootable-usb` 

+
+
 Install |CL| 
 ************

 * :ref:`bare-metal-install` 
 * :ref:`bare-metal-manual-install`
 * :ref:`virtual-machine-install`
-* :ref:`live-image`
-
+* :ref:`live-image` 
+* :ref:`bare-metal-install-beta`

 .. toctree::
   :maxdepth: 2
@@ -33,4 +35,7 @@ Install |CL|
   virtual-machine-install/virtual-machine-install
   live-image
   compatibility-check
-   bootable-usb/bootable-usb
+   bootable-usb/bootable-usb
+
+   bare-metal-install-beta/bare-metal-install-beta
+   bootable-usb/bootable-usb-beta-all
@@ -1,21 +1,21 @@
-.. _deploy-at-scale.rst:
+.. _deploy-at-scale:

-Deploying |CL| at Scale
-#######################
+Deploy at Scale
+###############

-Once you are comfortable with `Clear Linux concepts`_, your next step
-as a system administrator is to understand how to deploy Clear Linux*
-at scale in your environment.  
+Once you are comfortable with |CL-ATTR| :ref:`concepts <concepts>`, your next step
+as a system administrator is to understand how to deploy |CL|
+at scale in your environment.

 In this document the term *endpoint* refers to a system targeted for
 |CL| installation, whether that is a datacenter system or unit deployed in
-field.  
+field.

 .. note::

    This is not a replacement or blueprint for designing your own IT
-    operating environment. 
-    
+    operating environment.
+
    Your |CL| deployment should complement the existing environment and
    available tools. It is assumed foundational core IT dependencies of your
    environment, such as your network, are healthy and scaled to suit the
@@ -27,27 +27,27 @@ field.
 Pick a |CL| usage and update strategy
 =====================================

-Different business scenarios call for different deployment methodologies. 
-|CLOSIA| offers the flexibility to continue consuming the upstream |CL|
+Different business scenarios call for different deployment methodologies.
+|CL| offers the flexibility to continue consuming the upstream |CL|
 distribution or the option to fork away from the |CL| distribution and
-act as your own :abbr:`OSV (Operating System Vendor)`. 
+act as your own :abbr:`OSV (Operating System Vendor)`.

 Below are overviews of both approaches and some considerations.

 Option #1: Use the |CL| as the upstream origin (mixin)
 ------------------------------------------------------

-This approach is *easier to adopt* by relying on the |CL| upstream for 
-packaging updates for you to deploy. 
+This approach is *easier to adopt* by relying on the |CL| upstream for
+packaging updates for you to deploy.

 Custom software or packages that are not available in a preformed bundle
-can be added using the `mixin process`_ to form a custom bundle. 
-If custom bundles are needed, you will be responsible for maintaining 
-the custom bundle(s) and testing between |CL| releases in your environment, 
-while the rest of the operating system and preformed bundles come from the 
+can be added using the `mixin process`_ to form a custom bundle.
+If custom bundles are needed, you will be responsible for maintaining
+the custom bundle(s) and testing between |CL| releases in your environment,
+while the rest of the operating system and preformed bundles come from the
 |CL| upstream.
-    
-#. Ensure |CL| systems are able to be inventoried, managed, and orchestrated 
+
+#. Ensure |CL| systems are able to be inventoried, managed, and orchestrated
   to coordinate software updates.

 #. With autoupdate enabled, |CL| is updated daily, however you may wish to
@@ -56,70 +56,70 @@ while the rest of the operating system and preformed bundles come from the
   yourself which is realistic with the operational expectations of your
   environment.

-#. Use a web caching proxy for |CL| updates for devices connected to 
-   a local area network (LAN), like a datacenter, to increase the speed 
-   and resiliency of updates from the |CL| update servers. 
-   
-   Your caching proxy server is just like any other web application. 
+#. Use a web caching proxy for |CL| updates for devices connected to
+   a local area network (LAN), like a datacenter, to increase the speed
+   and resiliency of updates from the |CL| update servers.
+
+   Your caching proxy server is just like any other web application.
   |WEB-SERVER-SCALE|

 Option #2: Create your own Linux distribution (mix)
 ---------------------------------------------------

-This approach forks away from the |CL| upstream and has you act as your own 
-:abbr:`OSV (Operating System Vendor)` by leveraging the `mixer process`_ to 
-create customized images based on |CL|. This is a level of responsibility 
-that requires having more infrastructure and processes to adopt. In return, 
+This approach forks away from the |CL| upstream and has you act as your own
+:abbr:`OSV (Operating System Vendor)` by leveraging the `mixer process`_ to
+create customized images based on |CL|. This is a level of responsibility
+that requires having more infrastructure and processes to adopt. In return,
 this approach *offers you a high degree of control and customization*.

-* Development systems which are generating bundles and updates should be 
-  sufficiently performant for the task and separate from the swupd update 
+* Development systems which are generating bundles and updates should be
+  sufficiently performant for the task and separate from the swupd update
  webservers which are serving update content to production machines.

-* swupd update webservers which are serving update content to 
+* swupd update webservers which are serving update content to
  production machines (see `mixer process`_ for more information) should be
-  appropriately scaled. 
+  appropriately scaled.

-  Your swupd update server is just like any other web application. 
-  |WEB-SERVER-SCALE| 
+  Your swupd update server is just like any other web application.
+  |WEB-SERVER-SCALE|

 Adopt an agile methodology
 --------------------------
 The cloud, and other scaled deployments, are all about flexibility and speed.
-It only makes sense that any |CL| deployment strategy should follow suit. 
+It only makes sense that any |CL| deployment strategy should follow suit.

-Manually rebuilding your own bundles or mix for every release is not 
-sustainable at a large scale. A |CL| deployment pipeline should be agile 
-enough to validate and produce new versions with speed. Whether or not those 
-updates actually make their way to your production can be separate 
-business decision. However this *ability to frequently roll new versions* of 
-software to your endpoints is an important prerequisite. 
+Manually rebuilding your own bundles or mix for every release is not
+sustainable at a large scale. A |CL| deployment pipeline should be agile
+enough to validate and produce new versions with speed. Whether or not those
+updates actually make their way to your production can be separate
+business decision. However this *ability to frequently roll new versions* of
+software to your endpoints is an important prerequisite.

-You own the validation and lifecycle of the OS and should treat it like any 
+You own the validation and lifecycle of the OS and should treat it like any
 other software development lifecycle. Below are some pointers:

 * Thoroughly understand the custom software packages that you will need to
  integrate with |CL| and maintain along with their dependencies.

-* Setup a path to production for building |CL| based images. At minimum this 
+* Setup a path to production for building |CL| based images. At minimum this
  should include:

-    * A development clr-on-clr environment to test building packages and 
-      bundles for |CL| systems. 
+    * A development clr-on-clr environment to test building packages and
+      bundles for |CL| systems.

-    * A pre-production environment to deploy |CL| versions to before 
-      production 
+    * A pre-production environment to deploy |CL| versions to before
+      production

 * Employ a continuous integration and continuous deployment (CI/CD)
  philosophy in order to:

-    - Automatically pull custom packages as they are updated from their 
-      upstream projects or vendors. 
+    - Automatically pull custom packages as they are updated from their
+      upstream projects or vendors.

-    - Generate |CL| bundles and potentially bootable images with your 
-      customizations, if any. 
+    - Generate |CL| bundles and potentially bootable images with your
+      customizations, if any.

-    - Measure against metrics and indicators which are relevant to your 
+    - Measure against metrics and indicators which are relevant to your
      business (e.g. performance, power, etc) from release to release.

    - Integrate with your organization's governance processes, such as change
@@ -128,92 +128,93 @@ other software development lifecycle. Below are some pointers:
 Versioning Infrastructure
 -------------------------

-|CL| version numbers are very important as they apply to the whole 
+|CL| version numbers are very important as they apply to the whole
 infrastructure stack from OS components to libraries and
-applications. 
+applications.

-Good record keeping is important, so you should keep a detailed registry 
+Good record keeping is important, so you should keep a detailed registry
 and history of previously deployed versions and their contents.

 With a glance at the |CL| version numbers deployed, you should be
-able to tell if your Clear systems are patched against a 
+able to tell if your Clear systems are patched against a
 particular security vulnerability or incorporate a critical new feature.
- 
+
 Pick an image distribution strategy
 ===================================

-Once you have decided on a usage and update strategy, you should understand 
-*how* |CL| will be deployed to your endpoints. In a large scale 
-deployment, interactive installers should be avoided in favor of automated 
+Once you have decided on a usage and update strategy, you should understand
+*how* |CL| will be deployed to your endpoints. In a large scale
+deployment, interactive installers should be avoided in favor of automated
 installations or prebuilt images.

-There are many well-known ways to install an operating system at scale. Each 
-have their own benefits, and one may lend itself easier in your environment 
+There are many well-known ways to install an operating system at scale. Each
+have their own benefits, and one may lend itself easier in your environment
 depending on the resources available to you.

-See the `reference of Clear Linux image types`_
- 
+See the available :ref:`image-types`.
+
 Below are some common ways to install |CL| to systems at scale:

 Baremetal
 ---------

-Preboot Execution Environments (PXE) or other 
+Preboot Execution Environments (PXE) or other
 out-of-band booting options are one way to distribute |CL|
 to physical baremetal systems on a LAN.

-This option works well if your customizations are fairly small in size 
-and infrastructure can be stateless. 
+This option works well if your customizations are fairly small in size
+and infrastructure can be stateless.

-The |CL| `downloads page`_ offers a Live Image that can be deployed as 
+The |CL| `downloads page`_ offers a live image that can be deployed as
 a PXE boot server if one doesn't already exist in your environment. Also see
-`documentation on installing Clear Linux on bare metal systems`_
+documentation on how to :ref:`bare-metal-install`.

-Cloud Instances or Virtual Machines 
+Cloud Instances or Virtual Machines
 -----------------------------------
-Image templates in the form of cloneable disks are an effective way to 
-distribute |CL| for virtual machine environments, whether on-premises or 
-hosted by a Cloud Solution Provider (CSP). 

-When used in concert with cloud VM migration features, 
-this can be a good option for allowing your applications a degree of high 
-availability and workload mobility; VMs can be restarted on a cluster of 
-hypervisor host or moved between datacenters transparently. 
+Image templates in the form of cloneable disks are an effective way to
+distribute |CL| for virtual machine environments, whether on-premises or
+hosted by a Cloud Solution Provider (CSP).

-The |CL| `downloads page`_ offers example prebuilt VM images and is 
-readily available on popular CSPs. Also see 
-`documentation on installing Clear Linux in VMs`_.
+When used in concert with cloud VM migration features,
+this can be a good option for allowing your applications a degree of high
+availability and workload mobility; VMs can be restarted on a cluster of
+hypervisor host or moved between datacenters transparently.
+
+The |CL| `downloads page`_ offers example prebuilt VM images and is
+readily available on popular CSPs. Also see
+documentation on how to :ref:`virtual-machine-install`.

 Containers
 ----------

-Containerization platforms allow images to be pulled from a 
-repository and deployed repeatedly as isolated containers.  
+Containerization platforms allow images to be pulled from a
+repository and deployed repeatedly as isolated containers.

-Containers with a |CL| image can be a good option to blueprint and ship 
-your application, including all its dependencies, as an artifact while 
-allowing you or your customers to dynamically orchestrate and scale 
+Containers with a |CL| image can be a good option to blueprint and ship
+your application, including all its dependencies, as an artifact while
+allowing you or your customers to dynamically orchestrate and scale
 applications.

-|CL| is capable of running a Docker host, has a container image which can 
+|CL| is capable of running a Docker host, has a container image which can
 be pulled from DockerHub, or can be built as a customized container.
 For more information visit the `containers page`_.

 Considerations with stateless systems
 =====================================
-An important |CL| concept is statelessness and partitioning of system data 
-from user data. This concept can change the way you think about an at scale 
+An important |CL| concept is statelessness and partitioning of system data
+from user data. This concept can change the way you think about an at scale
 deployment.

 Backup strategy
 ---------------

-A |CL| system and its infrastructure should be considered a commodity and 
+A |CL| system and its infrastructure should be considered a commodity and
 be easily reproducible. Avoid focusing on backing up the operating system
-itself or default values. 
+itself or default values.

-Instead, focus on backing up what's important and unique - the application 
-and data.  In other words, only focus on backing up critical areas like 
+Instead, focus on backing up what's important and unique - the application
+and data.  In other words, only focus on backing up critical areas like
 `/home`,  `/etc`,  and `/var`.

 Meaningful Logging & Telemetry
@@ -222,16 +223,16 @@ Meaningful Logging & Telemetry
 Offload logging and telemetry from endpoints to external servers, so it is
 persistent and can be accessed on another server when an issue occurs.

-* Remote syslogging in |CL| is available through the 
-  `systemd journal-remote service`_  
+* Remote syslogging in |CL| is available through the
+  `systemd journal-remote service`_

-* |CL| offers a `native telemetry solution`_ which can be a powerful tool 
-  for a large deployment to quickly crowdsource issues of interest. Take 
+* |CL| offers a `native telemetry solution`_ which can be a powerful tool
+  for a large deployment to quickly crowdsource issues of interest. Take
  advantage of this feature with careful consideration of the target audience
  and the kind of data that would be valuable, and expose events
-  appropriately.  
+  appropriately.

-  Your telemetry server is just like any other web application. 
+  Your telemetry server is just like any other web application.
  |WEB-SERVER-SCALE|

 Orchestration and Configuration Management
@@ -240,47 +241,43 @@ Orchestration and Configuration Management
 In cloud environments, where systems can be ephemeral, being able to
 configure and maintain generic instances is valuable.

-|CL| offers an efficient cloud-init style solution, `micro-config-drive`_, 
+|CL| offers an efficient cloud-init style solution, `micro-config-drive`_,
 through the *os-cloudguest* bundles which allow you to configure many Day 1
-tasks such as setting hostname, creating users, or placing 
-SSH keys in an automated way at boot. For more information on 
-automating configuration during deployment of |CL| endpoints see 
+tasks such as setting hostname, creating users, or placing
+SSH keys in an automated way at boot. For more information on
+automating configuration during deployment of |CL| endpoints see
 the `documentation on bulk provisioning`_ .
- 
-A configuration management tool is useful for maintaining consistent system 
-and application-level configuration. Ansible\* is offered through the 
+
+A configuration management tool is useful for maintaining consistent system
+and application-level configuration. Ansible\* is offered through the
 *sysadmin-hostmgmt* bundle as a configuration management and automation
-tool. 
+tool.

 Cloud-native applications
 -------------------------

-An Infrastructure OS can design for good behavior, but it is ultimately up 
-to applications to make agile design choices. Applications deployed 
-on |CL| should aim to be host-aware but not depend on any specific host to 
+An Infrastructure OS can design for good behavior, but it is ultimately up
+to applications to make agile design choices. Applications deployed
+on |CL| should aim to be host-aware but not depend on any specific host to
 run. References should be relative and dynamic when possible.

-The application architecture should incorporate an appropriate tolerance for 
-infrastructure outages. Don't just keep stateless design as a noted feature. 
-Continuously test its use; Automate its use by redeploying |CL| and 
-application on new hosts. This naturally minimizes configuration drift, 
+The application architecture should incorporate an appropriate tolerance for
+infrastructure outages. Don't just keep stateless design as a noted feature.
+Continuously test its use; Automate its use by redeploying |CL| and
+application on new hosts. This naturally minimizes configuration drift,
 challenges your monitoring systems, and business continuity plans.

-.. _`Clear Linux concepts`: https://clearlinux.org/documentation/clear-linux/concepts
 .. _`mixin process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixin
 .. _`mixer process`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/mixer
-.. _`reference of Clear Linux image types`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/image-types
-.. _`documentation on installing Clear Linux on bare metal systems`: https://clearlinux.org/documentation/clear-linux/get-started/bare-metal-install
 .. _`downloads page`: https://download.clearlinux.org/image/
-.. _`documentation on installing Clear Linux in VMs`: https://clearlinux.org/documentation/clear-linux/get-started/virtual-machine-install
 .. _`containers page`: https://clearlinux.org/containers
 .. _`systemd journal-remote service`: https://www.freedesktop.org/software/systemd/man/systemd-journal-remote.service.html
 .. _`native telemetry solution`: https://clearlinux.org/features/telemetry
 .. _`micro-config-drive`: https://github.com/clearlinux/micro-config-drive
 .. _`documentation on bulk provisioning`: https://clearlinux.org/documentation/clear-linux/guides/maintenance/bulk-provision

-.. |WEB-SERVER-SCALE| replace:: 
-   There are many well-known ways to achieve a scalable and resilient web 
+.. |WEB-SERVER-SCALE| replace::
+   There are many well-known ways to achieve a scalable and resilient web
   server for this purpose, however implementation details are not in the
   scope of this document. In general, they should be close to your
   endpoints, highly available, and easy to scale with a load balancer when
@@ -3,11 +3,11 @@
 Guides
 ######

-Our Guides: 
+Our Guides:

-*  Provide a critical, fundamental understanding of |CL| features
+*  Provide a critical, fundamental understanding of |CL-ATTR| features
 *  Show you how to leverage the full feature set of |CL|
-*  Enhance your productivity when using |CL| 
+*  Enhance your productivity when using |CL|


 The following guides provide step-by-step instructions for tasks that come
@@ -19,3 +19,4 @@ after completing the |CL| :ref:`installation <get-started>`.
   maintenance/maintenance
   network/network
   deploy-at-scale
+   telemetrics/telemetrics
@@ -0,0 +1,71 @@
+.. _assign-static-ip:
+
+Assign a static IP address to a network interface
+#################################################
+
+Introduction
+************
+
+By default, your |CL-ATTR| system automatically gets an IP address from your
+network via DHCP. If you do not have a DHCP server on your network or simply
+want to use a static IP address, follow the steps in this guide.
+
+Process
+*******
+
+#.	Create this directory structure:
+
+	.. code-block:: bash
+
+		sudo mkdir -p /etc/systemd/network
+
+#.	Identify the interface to be assigned the static IP address:
+
+	.. code-block:: bash
+
+		ip addr
+
+	The system returns the following:
+
+	.. code-block:: console
+
+		1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
+		    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+		    inet 127.0.0.1/8 scope host lo
+		       valid_lft forever preferred_lft forever
+		    inet6 ::1/128 scope host
+		       valid_lft forever preferred_lft forever
+
+		2: wlp1s0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc mq state DOWN group default qlen 1000
+		    link/ether 4a:98:8d:e5:43:15 brd ff:ff:ff:ff:ff:ff
+
+		3: eno1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq state UP group default qlen 1000
+		    link/ether f4:4d:30:68:96:20 brd ff:ff:ff:ff:ff:ff
+		    inet 10.0.1.2/24 brd 10.54.74.255 scope global dynamic eno1
+		       valid_lft 6766sec preferred_lft 6766sec
+		    inet6 fe80::f64d:30ff:fe68:9620/64 scope link
+		       valid_lft forever preferred_lft forever
+
+	In this example, we will use the `eno1` interface.
+
+#.	Create the :file:`70-static.network` file and add the following:
+
+	.. code-block:: bash
+
+		sudo $EDITOR /etc/systemd/network/70-static.network
+
+		[Match]
+		Name=[interface name]
+		[Network]
+		Address=[IP address]/24
+		DHCP=yes # to get DNS info, etc.
+
+	Replace [interface name] and [IP address] with your specific settings.
+
+#.	Restart the networkd service:
+
+	.. code-block:: bash
+
+		sudo systemctl restart systemd-networkd
+
+**Congratulations!** You have successfully assigned a static IP address.
@@ -0,0 +1,18 @@
+.. _autoproxy:
+
+Autoproxy
+#########
+
+.. rst-class:: content-collapse
+
+About
+=====
+
+.. include:: autoproxy_about.txt
+
+.. rst-class:: content-collapse
+
+Guide
+=====
+
+.. include:: autoproxy_guide.txt
@@ -0,0 +1,43 @@
+The |CL-ATTR| is the first Linux distribution to support autoproxy. The OS
+can discover a Proxy Auto-Config (PAC) script and use it to automatically
+resolve the proxy needed for a given connection. With Autoproxy, you can use
+|CL| inside any proxy environment without having to manually
+configure the proxies.
+
+Corporate and private networks can be very complex, needing to restrict and
+control network connections for security reasons. The typical side effects
+are limited or blocked connectivity and requiring manual configuration of
+proxies to perform the most mundane tasks such as cloning a repo or checking
+for updates. With Clear Linux, all of the work is done behind the scenes to
+effortlessly use your network and have connections “just work”.
+
+This feature removes massive complications in network connectivity due to
+proxy issues. You can automate tasks like unit testing without worrying
+about the proxy not being set and you can remove unset proxies from the
+equation when dealing with network unavailability across systems.
+
+How Autoproxy works
+-------------------
+
+We designed autoproxy around general tools provided by nearly any Linux
+distribution with a few minor additions and modifications. We leveraged the
+DHCP and network information provided from systemd and created a
+PAC-discovery daemon. The daemon uses the information to resolve a URL for a
+PAC file. The daemon then passes the URL into PACrunner*. PACrunner
+downloads the PAC file and uses the newly implemented Duktape* engine to
+parse it.
+
+.. figure:: figures/autoproxy_0.png
+   :width: 400px
+
+   Figure 1: Autoproxy Flow
+
+From that point on, any cURL* or network requests query PACrunner for the
+correct proxy to use. We modified the cURL library to communicate with
+PACrunner over DBus. However, cURL will ignore PACrunner and run normally if
+no PAC file is loaded or if you set any proxies manually. Thus, your
+environment settings are respected and no time is wasted trying to resolve a
+proxy.
+
+More importantly: all these steps happen in the background, very quickly, and
+with no user interaction.
@@ -0,0 +1,77 @@
+Autoproxy allows |CL| to operate seamlessly behind a proxy
+because, :ref:`swupd-guide` and other |CL| tools are implemented on
+top of libcurl. Tools that do not use libcurl, like git, must
+be configured independently. 
+
+If you encounter problems with autoproxy functioning, use
+:command:`pacdiscovery` and :command:`FindProxyForURL` to
+help troubleshoot assuming a familiarity with PAC files and WPAD. 
+
+.. note::
+
+   Learn more about WPAD, PAC files, and PAC functions at `findproxyforurl`_.
+
+.. _findproxyforurl: http://findproxyforurl.com/
+
+Running :command:`pacdiscovery` with no arguments will immediately indicate
+
+1. if there is a problem resolving the :command:`WPAD` host name resolution: 
+
+   .. code:: console
+
+      $ pacdiscovery
+      failed getaddrinfo: No address associated with hostname
+      Unable to find wpad host
+
+2. or if the :command:`pacrunner` service is disabled (masked).
+
+   .. code:: console
+
+      $ pacdiscovery
+      PAC url: http://autoproxy.your.domain.com/wpad.dat
+      Failed to create proxy config: Unit pacrunner.service is masked.
+
+Unmask the :command:`pacrunner` service by running:
+
+.. code:: console
+
+   $ systemctl unmask pacrunner.service
+
+:command:`FindProxyForURL` with :command:`busctl` can also indicate if the
+:command:`pacrunner.service` is masked.
+
+.. code:: console
+
+   $ busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com"
+   Unit pacrunner.service is masked.
+   dig wpad, dig wpad.<domain>
+
+:command:`FindProxyForURL` returns the URL and port of the proxy server when
+an external URL and host are provided as arguments.
+
+.. code:: console
+
+   $ busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com"
+   s "PROXY proxy.your.domain.com:<port>"
+
+If a proxy server is not avialable, or if :command:`pacrunner` is running
+without a PAC file, :command:`FindProxyForURL` will return "DIRECT". 
+
+.. code:: console
+
+   $ busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com"
+   s "DIRECT"
+
+Once :command:`pacdiscovery` is able to look up :command:`WPAD`, restart the
+:command:`pacrunner` service:
+
+.. code:: console
+
+   $ systemctl stop pacrunner
+   $ systemctl restart pacdiscovery
+
+.. note::
+
+   A "domain" or "search" entry in :file:`/etc/resolv.conf` is required for short
+   name lookups to resolve. The :file:`resolv.conf` man page has additional
+   details.
@@ -96,8 +96,7 @@ we build a new helloclear RPM.

   .. note::

-      For a local tarball, use for the *URL*:
-      file://<absolute-path-to-tarball>
+      For a local tarball, use this type of *URL*: \file://<absolute-path-to-tarball>

 #. If build failures or dependency issues occur, continue below.
   Otherwise, skip directly to `Next steps`_.
@@ -3,42 +3,39 @@
 Developer Workstation
 #####################

-Overview
-********
+*Developer Workstation* helps you find the :ref:`bundles-about` you need to
+start your |CL-ATTR| development project.

-*Developer Workstation* helps you find the :ref:`bundles-about` you need to 
-start your |CL| development project. 
-
-Before continuing, we recommend that you learn how to use 
+Before continuing, we recommend that you learn how to use
 :ref:`swupd <swupd-guide>`. Visit our :ref:`swupd-about` page to understand
 how |CL| simplifies software versioning compared to other Linux\*
-distributions. 
+distributions.

 Workstation Setup
-=================
+*****************

-This guide helps you understand the minimum bundles required to get started. 
-After installing them, you can add more bundles relevant to your use case. 
-To run any process required for Clear Linux development, you can add the 
+This guide helps you understand the minimum bundles required to get started.
+After installing them, you can add more bundles relevant to your use case.
+To run any process required for |CL| development, you can add the
 large bundle :ref:`*os-clr-on-clr* <enable-user-space>`. However, given how
 many packages this bundle contains, you may want instead to deploy a leaner
-OS with only those bundles relevant to your project. Developer Workstation 
-responds to this need. 
+OS with only those bundles relevant to your project. Developer Workstation
+responds to this need.

-Use Table 1, *Clear Linux Developer Profiles*, to identify the *minimum 
-required bundles* to get started developing based on your role or project. 
-While your role may not neatly fit in one of these categories, consider using Table 1 as a starting point. 
+Use Table 1, *Developer Profiles*, to identify the *minimum
+required bundles* to get started developing based on your role or project.
+While your role may not neatly fit in one of these categories, consider using Table 1 as a starting point.

-.. list-table:: **Table 1. Clear Linux Developer Profiles**
+.. list-table:: **Table 1. Developer Profiles**
   :widths: 20, 20, 20, 20
   :header-rows: 1

-   * - Clear Linux Bundle
-     - *Internet of Things (IoT)* 
+   * - |CL| Bundle
+     - *Internet of Things (IoT)*
     - *System Administrator*
     - *Client/Cloud/Web Developer*
-     
-   * - `editors` 
+
+   * - `editors`
     - ✓
     - ✓
     - ✓
@@ -52,60 +49,60 @@ While your role may not neatly fit in one of these categories, consider using Ta
     - ✓
     - ✓
     - ✓
-   
+
   * - `webserver-basic`
-     - 
+     -
     - ✓
-     - ✓   
-   
+     - ✓
+
   * - `application-server`
-     - 
+     -
     - ✓
     - ✓
-   
+
   * - `database-basic`
-     - 
+     -
     - ✓
     - ✓
-   
+
   * - `desktop-autostart`
     - ✓
     - ✓
     - ✓

   * - `dev-utils`
-     - 
-     - 
+     -
+     -
     - ✓

 `swupd` search
-==============
+**************

 We recommend trying out :ref:`swupd search <swupd-search>`, to learn the
-commands to search for and add bundles relevant to your project. 
+commands to search for and add bundles relevant to your project.

-:ref:`swupd-search` shows you how to: 
+:ref:`swupd-search` shows you how to:

-* Use `swupd` to search for bundles 
+* Use `swupd` to search for bundles
 * Use `swupd` to add bundles

 Core Concepts
-=============
+*************

-We recommend that you understand these core concepts in |CL| *before* 
-developing your project. 
+We recommend that you understand these core concepts in |CL| *before*
+developing your project.

 * :ref:`Bundles <bundles-about>`
 * :ref:`Software update <swupd-about>`
 * :ref:`Mixer <mixer-about>`
-* :ref:`Autospec <autospec-about>` 
+* :ref:`Autospec <autospec-about>`

 Other resources for developers
 -----------------------------------

-* `Developer Tooling Framework for Clear Linux`_
-* `Clear Linux Bundles`_
+* `Developer Tooling Framework`_ for |CL|
+* `Bundle definition files`_

-.. _Clear Linux Bundles: https://github.com/clearlinux/clr-bundles
+.. _Bundle definition files: https://github.com/clearlinux/clr-bundles

-.. _Developer Tooling Framework for Clear Linux: https://github.com/clearlinux/common
+.. _Developer Tooling Framework: https://github.com/clearlinux/common
@@ -4,7 +4,7 @@ Create and enable a new user space
 ##################################

 This section provides steps to complete the following basic setup tasks for
-a newly installed |CLOSIA| system:
+a newly installed |CL-ATTR| system:

 * Create a new user.
 * Update the OS to its most current version using `swupd`.
@@ -51,7 +51,7 @@ Install the `sysadmin-basic` bundle:

 We provide the full list of bundles and packages installed with the
 `sysadmin-basic`_ bundle. Additionally, we have listed
-`all Clear Linux bundles`_, active or deprecated. Click any bundle on the
+`all bundles`_ for |CL|, active or deprecated. Click any bundle on the
 list to view the manifest of the bundle.

 Set up a new user and add the new user to the `wheel` group
@@ -88,7 +88,7 @@ Install a GUI to test `sudo` privileges
 .. note::

   If you are following this sequence after just setting up the
-   pre-configured VMware\* virtual machine from the repo, you must 
+   pre-configured VMware\* virtual machine from the repo, you must
   :ref:`increase virtual disk size<increase-virtual-disk-size>` or the
   following step will fail.

@@ -136,7 +136,7 @@ system.
 .. _`sysadmin-basic`:
   https://github.com/clearlinux/clr-bundles/blob/master/bundles/sysadmin-basic

-.. _`all Clear Linux bundles`:
+.. _`all bundles`:
   https://github.com/clearlinux/clr-bundles/tree/master/bundles

 .. _`wheel group`:
@@ -3,15 +3,15 @@
 Modify hostname on |CL-ATTR|
 ############################

-This guide describes how to modify and view the hostname of your 
+This guide describes how to modify and view the hostname of your
 |CL-ATTR| system.

-By default, |CL| installations have a machine generated name, which is a 
-long string of letters and numbers. The generated name is fine for computers 
-but is not human-friendly. Administrators and users will often want to rename 
-their machines with a name that is easier to remember, type, and search 
-for. Renaming a machine also makes it easier to identify, by including 
-meaningful data in the name.  The following examples show human-friendly machine 
+By default, |CL| installations have a machine generated name, which is a
+long string of letters and numbers. The generated name is fine for computers
+but is not human-friendly. Administrators and users will often want to rename
+their machines with a name that is easier to remember, type, and search
+for. Renaming a machine also makes it easier to identify, by including
+meaningful data in the name.  The following examples show human-friendly machine
 names:

 * *regression-test*
@@ -21,12 +21,12 @@ names:
 Set your hostname
 *****************

-|CL| uses the :command:`hostnamectl` command to display and modify the machine 
-name. :command:`hostnamectl` is part of the **os-core** bundle, which provides 
-a basic Linux\* user space and utilities. 
+|CL| uses the :command:`hostnamectl` command to display and modify the machine
+name. :command:`hostnamectl` is part of the **os-core** bundle, which provides
+a basic Linux\* user space and utilities.

-This example sets the hostname to *telemetry-test-2-h15*, to identify a 
-|CL| telemetry test machine on the second floor at grid location H15. 
+This example sets the hostname to *telemetry-test-2-h15*, to identify a
+|CL| telemetry test machine on the second floor at grid location H15.
 Make sure to reboot after setting a new hostname.

 .. code-block:: bash
@@ -36,14 +36,14 @@ Make sure to reboot after setting a new hostname.

 .. note::

-   There are three types of hostname: *static*, *transient*, and *pretty*. 
-   The most common is the static hostname. Static hostnames must be between 
-   two and 63 characters long, must start and end with a letter or number, 
-   and may contain letters (case-insensitive), numbers, dashes, or dots.  
+   There are three types of hostname: *static*, *transient*, and *pretty*.
+   The most common is the static hostname. Static hostnames must be between
+   two and 63 characters long, must start and end with a letter or number,
+   and may contain letters (case-insensitive), numbers, dashes, or dots.

-   If the static hostname exists, it is used to generate the transient hostname, 
-   which is maintained by the kernel. The transient hostname can be changed 
-   by DHCP or mDNS at runtime. 
+   If the static hostname exists, it is used to generate the transient hostname,
+   which is maintained by the kernel. The transient hostname can be changed
+   by DHCP or mDNS at runtime.

   The pretty hostname is a free-form UTF8 name used for presentation to the user.

@@ -70,5 +70,5 @@ You should see output similar to:
   Kernel            : Linux 4.18.8-632.native
   Architecture      : x86-64

- 
+
 **Congratulations!** You successfully modified the hostname of your |CL| system.
@@ -1,18 +1,18 @@
 .. _increase-virtual-disk-size:

-Increase virtual disk size of a Clear Linux\* image 
-###################################################
+Increase virtual disk size of a |CL-ATTR| image
+###############################################

-|CLOSIA| prebuilt images come in different sizes, ranging from 300 MB to 20
+|CL-ATTR| prebuilt images come in different sizes, ranging from 300 MB to 20
 GB. This guide describes how to increase the size of your prebuilt |CL| image
 if you need more capacity.

 .. contents:: This guide will cover:

-Determine the partition order and sizes of the prebuilt image 
+Determine the partition order and sizes of the prebuilt image
 *************************************************************

-There are two methods to find the order and sizes of partitions virtual disk 
+There are two methods to find the order and sizes of partitions virtual disk
 of your prebuilt |CL| image.

 In both examples, the prebuilt Hyper-V image has a disk size of 8.5 GB with /
@@ -28,7 +28,7 @@ execute the :command:`lsblk` command as shown below:

   sudo lsblk

-An example output of the :command:`lsblk` command: 
+An example output of the :command:`lsblk` command:

 .. code-block:: console

@@ -36,16 +36,16 @@ An example output of the :command:`lsblk` command:
   sda      8:0   0    8.5G  0 disk
   ├─sda1   8:1   0    512M  0 part
   ├─sda2   8:2   0     32M  0 part [SWAP]
-   └─sda3   8:3   0      8G  0 part /         
+   └─sda3   8:3   0      8G  0 part /

 An example of this can also be seen in Figure 1.

-Checking :file:`config.json` used to build the image  
+Checking :file:`config.json` used to build the image
 ----------------------------------------------------

-The second method to determine partition to check the :file:`config.json` 
+The second method to determine partition to check the :file:`config.json`
 file used to create prebuilt image, located in the `releases`_ repository.
-For example, to find the size of the Hyper-V\* image version number 20450, 
+For example, to find the size of the Hyper-V\* image version number 20450,
 follow these steps:

 #. Go to the `releases`_ repository.
@@ -74,17 +74,17 @@ follow these steps:

 Increase virtual disk size
 **************************
-Once you have determined the disk and partition to be increased, you are 
+Once you have determined the disk and partition to be increased, you are
 ready to perform the actual increase of the disk, partition, and filesystem.

 Power off VM and increase virtual disk size:
 --------------------------------------------

-To increase the virtual disk size for a prebuilt image, perform the steps 
+To increase the virtual disk size for a prebuilt image, perform the steps
 below:

 #. Shut down your VM if it is running.
-#. Use the process defined by your hypervisor 
+#. Use the process defined by your hypervisor
   or cloud provider to increase
   the virtual disk size of your |CL| VM.
 #. Power up the VM.
@@ -95,7 +95,7 @@ Resize the partition of the virtual disk:

 #. Log in to an account with root privileges.
 #. Open a terminal emulator.
-#. Add the |CL| `storage-utils` bundle to install the 
+#. Add the |CL| `storage-utils` bundle to install the
   :command:`parted` and :command:`resize2fs` tools.

   .. code-block:: bash
@@ -121,7 +121,7 @@ Resize the partition of the virtual disk:

         Fix/Ignore?

-   #. Enter :command:`resizepart [partition number]` where 
+   #. Enter :command:`resizepart [partition number]` where
      *[partition number]* is the partition number of the partition to modify.
   #. Enter :command:`yes` when prompted.
   #. Enter the new `End` size.
@@ -142,18 +142,18 @@ Resize the partition of the virtual disk:

      .. figure:: figures/increase-virtual-disk-size-1.png
         :scale: 100 %
-         :alt: Increase root partition size 
+         :alt: Increase root partition size

         Figure 1: Increase root partition size.

-Resize the filesytem 
+Resize the filesytem
 --------------------

 #. Enter :command:`sudo resize2fs -p /dev/[modified partition name]` where
   *[modified partition name]* is the partition that was changed in `parted`.

 #. Run the :command:`df -h` to verify that the filesystem size has
-   increased. 
+   increased.

   Figure 2 depicts the described steps to resize the partition of the virtual disk from 8.5GB to 20GB.

@@ -164,6 +164,6 @@ Resize the filesytem
      Figure 2: Increase root filesystem size after partition has been expanded.

 Congratulations! You have resized the disk, partition, and filesystem. At
-this point, the increase in disk capacity is usable. 
+this point, the increase in disk capacity is usable.

 .. _releases: https://download.clearlinux.org/releases/
@@ -0,0 +1,176 @@
+.. _kernel-modules:
+
+Add kernel modules 
+##################
+
+Kernel modules are additional pieces of software capable of being inserted 
+into the Linux kernel to add functionality, such as a hardware driver. 
+Kernel modules may already be part of the Linux source tree (in-tree) or may 
+come from an external source, such as directly from a vendor (out-of-tree).  
+
+In cases where drivers beyond those enabled by default in |CL-ATTR| are
+needed it may be necessary to:
+
+.. contents:: :local:
+   :depth: 1
+   :backlinks: top
+
+Check if the module is available through |CL|
+=============================================
+
+Using an existing module is significantly easier to maintain and retains 
+signature verification of the |CL| kernel. For more information on |CL| 
+security practices, see the :ref:`security` page.
+
+|CL| comes with many upstream kernel modules available for use.  If 
+you require a kernel module, be sure to check whether it is already available in |CL| first. 
+
+You can search for kernel module file names, which end with the :file:`.ko` 
+file extension, using the :command:`swupd search` command. For example: 
+:command:`sudo swupd search ${module_name}.ko`.
+See :ref:`swupd-search` for more information. 
+
+Request the module be added to |CL|
+===================================
+
+If the kernel module you need is already open source 
+(e.g. in the Linux upstream) and likely to be useful to others, 
+consider submitting a request to add or enable in the |CL| kernel.
+
+Make enhancement requests to the |CL| distribution `on GitHub`_ .
+
+Build and load an out-of-tree module
+====================================
+
+In some cases you may need an out-of-tree kernel module that is not 
+available through |CL|.
+
+You can build and load out-of-tree kernel modules, however you must:
+
+* disable secure boot
+* disable kernel module integrity checking
+* build the module against new versions of the Linux kernel
+
+.. note::
+
+   Any time the kernel is upgraded on your Clear Linux system, you will 
+   need to rebuild your out-of-tree modules.
+
+This approach works well for individual development or testing. 
+For a more scalable and customizable approach, consider using the 
+`mixer tool`_ to provide a custom kernel and updates.
+
+Build kernel module
+-------------------
+
+#. From a |CL| system, ensure you are running the *native* kernel. 
+   Currently only the native kernel is enabled to build and load
+   out-of-tree modules.
+
+   .. code-block:: bash
+
+      $ uname -r
+      4.XX.YY-ZZZZ.native
+      # Ensure *.native* is in the kernel name
+
+#. Install the `linux-dev` bundle to obtain the kernel headers, which are
+   required for compiling kernel modules.
+
+   .. code-block:: bash
+
+      sudo swupd bundle-add linux-dev
+
+#. Follow instructions from the kernel module source code to compile the 
+   kernel module.
+
+
+Load kernel module
+------------------
+
+#. Disable Secure Boot in your system's UEFI settings, if you have enabled
+   it. The loading of new out-of-tree modules modifies the signatures Secure
+   Boot relies on for trust. 
+
+
+#. Disable signature checking for the kernel by modifying the kernel boot 
+   parameters and reboot the system. 
+
+   All kernel modules from |CL| have been signed to enforce kernel security. 
+   However, out-of-tree modules break this chain of trust so this mechanism 
+   needs to be disabled.
+  
+   .. code-block:: bash
+
+      sudo mkdir -p /etc/kernel/cmdline.d
+      echo "module.sig_unenforce" | sudo tee /etc/kernel/cmdline.d/allow-unsigned-modules.conf
+
+#. Update the boot manager and reboot the system to implement the changed 
+   kernel parameters.
+
+   .. code-block:: bash
+
+        sudo clr-boot-manager update
+        sudo reboot
+
+   .. note::
+
+      :command:`clr-boot-manager update` does not return any
+      console output if successful.
+
+   
+#. After rebooting, out-of-tree modules can be manually loaded with 
+   :command:`insmod`. 
+
+   .. code-block:: bash
+
+      sudo insmod ${path_to_module}
+
+
+Optional: Use `modprobe` to specify module options and aliases
+--------------------------------------------------------------
+
+Use :command:`modprobe` to load a module and set options.  
+
+Because :command:`modprobe` can add or remove more than one module, due to 
+modules having dependencies, a method of specifying what options are 
+to be used with individual modules is useful. This can be done with 
+configuration files under the :file:`/etc/modprobe.d` directory. 
+
+.. code-block:: bash
+
+   sudo mkdir /etc/modprobe.d
+
+All files underneath the :file:`/etc/modprobe.d` directory 
+that end with the :file:`.conf` extension specify module options to use when
+loading. This can also be used to create convenient aliases for modules or 
+they can override the normal loading behavior altogether for those with 
+special requirements. 
+
+You can find more info on module loading in the modprobe.d manual page:
+
+.. code-block:: bash
+
+   man modprobe.d
+
+Optional: Configure kernel modules to load at boot
+--------------------------------------------------
+
+Use the :file:`/etc/modules-load.d` configuration directory to 
+specify kernel modules to load automatically at boot.
+
+.. code-block:: bash
+
+   sudo mkdir /etc/modules-load.d
+
+All files underneath the :file:`/etc/modules-load.d` directory 
+that end with the :file:`.conf` extension contain a list of module names 
+of aliases (one per line) to load at boot.
+
+You can find more info on module loading in the modules-load.d manual page:
+
+.. code-block:: bash
+
+   man modules-load.d
+
+.. _`on GitHub`: https://github.com/clearlinux/distribution 
+.. _`mixer tool`: https://clearlinux.org/features/mixer-tool
@@ -10,15 +10,16 @@ completed.
 .. toctree::
   :maxdepth: 2

+   autoproxy
   developer-workstation
   swupd-search
   enable-user-space
   swupd-guide
   bulk-provision
+   kernel-modules
   mixer
   mixin
   validate-signatures
-   telemetry-enable
   time
   hostname
   increase-virtual-disk-size
@@ -26,3 +27,4 @@ completed.
   download-verify-decompress-mac
   download-verify-decompress-windows
   autospec
+   assign-static-ip
@@ -3,7 +3,7 @@
 Create and add custom bundles to your upstream Clear Linux system
 #################################################################

-|CLOSIA| offers many curated bundles that you can install on your system to
+|CL-ATTR| offers many curated bundles that you can install on your system to
 create your desired capabilities. If the available upstream bundles do not
 meet your needs, you can create and add your own custom bundles to your
 system using one of two methods. Note: Upstream refers to the official
@@ -5,7 +5,7 @@ Use swupd

 *swupd* manages the software update capability of |CL-ATTR|. It can check for
 valid system updates and, if found, download and install them. It can also
-perform verification of the system software. 
+perform verification of the system software.

 |CL| uses :ref:`bundles <bundles-about>` as the base abstraction for
 installing functionality on top of the core operating system. Use the `swupd`
@@ -18,7 +18,7 @@ This guide assumes:
 * The device is able to connect to the release infrastructure
  http://update.clearlinux.org

-.. contents:: 
+.. contents::
   :local:
   :depth: 2

@@ -54,7 +54,7 @@ Current OS version and update server info:
 Enable or disable automatic updates
 ===================================

-|CL| updates are automatic by default but can be set to occur only 
+|CL| updates are automatic by default but can be set to occur only
 on demand. To verify your current auto-update setting:

 .. code-block:: bash
@@ -105,7 +105,7 @@ to, overwritten, removed, or modified (e.g., permissions).

   sudo swupd verify

-All directories that are watched by `swupd` are verified according to 
+All directories that are watched by `swupd` are verified according to
 the manifest data and hash mismatches are flagged as follows:

 .. code-block:: console
@@ -113,7 +113,7 @@ the manifest data and hash mismatches are flagged as follows:
   Verifying version 23300
   Verifying files
      ...0%
-   Hash mismatch for file: /usr/bin/chardetect   
+   Hash mismatch for file: /usr/bin/chardetect
   ...
   ...
   Hash mismatch for file: /usr/lib/python3.6/site-packages/urllib3/util/wait.py
@@ -124,7 +124,7 @@ the manifest data and hash mismatches are flagged as follows:

 In this case, python packages that were installed on top of the default
 install were flagged as mismatched. `swupd` can be directed to ignore
-or fix issues based on :ref:`command line options <man_swupd>`. 
+or fix issues based on :ref:`command line options <man_swupd>`.

 Fixing hash mismatches
 ======================
@@ -138,7 +138,7 @@ ignore files or directories matching `/usr/lib/python`:

 .. code-block:: bash

-   sudo swupd verify --fix --picky --picky-whitelist=/usr/lib/python 
+   sudo swupd verify --fix --picky --picky-whitelist=/usr/lib/python

 Bundles
 *******
@@ -150,7 +150,7 @@ You can list all of the bundles currently installed on the system

 .. code-block:: bash

-   sudo swupd bundle-list --all 
+   sudo swupd bundle-list --all

 Finding a bundle containing a binary
 ====================================
@@ -160,7 +160,7 @@ binary. Note that it may be present in multiple bundles:

 .. code-block:: bash

-   swupd search -b <binary you want> 
+   swupd search -b <binary you want>

 Adding a bundle
 ===============
@@ -1,54 +1,54 @@
-.. _swupd-search: 
+.. _swupd-search:

 Use swupd search to find bundles
 ################################

 This document explains how to use `swupd search` to find and add
-bundles in |CL-ATTR|. 
+bundles in |CL-ATTR|.

 Assumptions
 ***********

-This guide assumes you: 
+This guide assumes you:

-* Possess a basic knowledge of :ref:`swupd <swupd-guide>` 
-* Understand :ref:`how swupd differs <swupd-about>` from  
-  other Linux\* distributions 
+* Possess a basic knowledge of :ref:`swupd <swupd-guide>`
+* Understand :ref:`how swupd differs <swupd-about>` from
+  other Linux\* distributions
 * May :ref:`mixer` to produce a custom distribution/image

-How do I search for a bundle? 
+How do I search for a bundle?
 *****************************

-Use `swupd search` to locate the bundle where the application binary exists. 
+Use `swupd search` to locate the bundle where the application binary exists.

 Example: Kata\* Containers
 ==========================

-Containers have revolutionized the way we manage cloud infrastructure. 
-Traditional containers often share the same OS kernel, which raises 
-security concerns. Instead, with Kata Containers, each container has its own 
-kernel instance and runs on its own :abbr:`Virtual Machine (VM)`. Whether you're running 3 or 300 nodes on your cluster, Kata Containers provide a 
-lightweight, fast, and secure option for app/container management.  
+Containers have revolutionized the way we manage cloud infrastructure.
+Traditional containers often share the same OS kernel, which raises
+security concerns. Instead, with Kata Containers, each container has its own
+kernel instance and runs on its own :abbr:`Virtual Machine (VM)`. Whether you're running 3 or 300 nodes on your cluster, Kata Containers provide a
+lightweight, fast, and secure option for app/container management.

-In |CL|, you only need to add `one bundle`_ to use `Kata Containers`_: 
+In |CL|, you only need to add `one bundle`_ to use `Kata Containers`_:
 `containers-virt`. Also, check out our tutorial: :ref:`kata`.

-We need to find *kata* containers in a bundle. How do we search for it? 
+We need to find *kata* containers in a bundle. How do we search for it?

-#. Enter :command:`swupd search`, followed by 'kata' as the search term: 
+#. Enter :command:`swupd search`, followed by 'kata' as the search term:

   .. code-block:: bash

      sudo swupd search kata

-   .. note:: 
+   .. note::

      `swupd search` downloads |CL| manifest data and searches for
-      matching paths. Enter only one term, or hyphenated term, per 
+      matching paths. Enter only one term, or hyphenated term, per
      search. Use the command :command:`man swupd` to learn more.

 #. Alternatively, if you want to search binaries only, add the `-b`
-   flag: 
+   flag:

   .. code-block:: bash

@@ -56,15 +56,15 @@ We need to find *kata* containers in a bundle. How do we search for it?

   .. note::

-      `-b` flag, or `--binary`, means: Restrict search to program binary paths. Omit this flag if you want a larger scope of search results.  
+      `-b` flag, or `--binary`, means: Restrict search to program binary paths. Omit this flag if you want a larger scope of search results.

-      Only the base bundle is returned. In |CL|, *bundles* can contain 
-      other *bundles* via `includes`. For more details, see `Bundle Definition Files`_ and its subdirectory *bundles*. 
+      Only the base bundle is returned. In |CL|, *bundles* can contain
+      other *bundles* via `includes`. For more details, see `Bundle Definition Files`_ and its subdirectory *bundles*.

      If your search does not produce results on a specific term when using
-      the `-b` flag, abbreviate the search term. For example, if you search 
-      for *kubernetes* and it does not show results, instead abbreviate the 
-      term to *kube* to show results. 
+      the `-b` flag, abbreviate the search term. For example, if you search
+      for *kubernetes* and it does not show results, instead abbreviate the
+      term to *kube* to show results.

 #. Optionally, you can review our `bundles`_ or individual `packages`_

@@ -82,7 +82,7 @@ We need to find *kata* containers in a bundle. How do we search for it?

   .. note::

-      If the bundle is already installed, *[installed]* appears in search results. If this doesn't apppear, the bundle needs to be installed. 
+      If the bundle is already installed, *[installed]* appears in search results. If this doesn't apppear, the bundle needs to be installed.

 #. Add the bundle `containers-virt`:

@@ -94,11 +94,11 @@ We need to find *kata* containers in a bundle. How do we search for it?

      To add multiple bundles simply add a space followed by the bundle name.

-#. When prompted, enter your password. 
+#. When prompted, enter your password.

 #. Upon successful installation, your console should show similar data:
-  
-   .. code-block:: console 
+
+   .. code-block:: console

      Downloading packs...

@@ -123,11 +123,11 @@ Learn how to:

 * :ref:`kata_migration`

-* :ref:`swupd-guide` 
+* :ref:`swupd-guide`

 * :ref:`Show all available bundles <swupd-guide>`

-* :ref:`Remove bundles<swupd-guide>` 
+* :ref:`Remove bundles<swupd-guide>`

 .. _Kata Containers: https://clearlinux.org/blogs/clear-linux-os-announces-support-kata-containers

@@ -135,6 +135,6 @@ Learn how to:

 .. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles

- .. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles 
+ .. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles

- .. _packages: https://github.com/clearlinux/clr-bundles/blob/master/packages 
+ .. _packages: https://github.com/clearlinux/clr-bundles/blob/master/packages
@@ -3,7 +3,7 @@
 Set the time
 ############

-|CLOSIA| uses the `systemd-timesyncd.service` daemon to synchronize time.
+|CL-ATTR| uses the `systemd-timesyncd.service` daemon to synchronize time.

 This guide describes how to reset the time in your |CL| system when
 the default :abbr:`NTP (Network Time Protocol)` servers cannot be reached.
@@ -3,7 +3,7 @@
 Validate signatures
 ###################

-|CLOSIA| offers a way to validate the content of an image or an update. All
+|CL-ATTR| offers a way to validate the content of an image or an update. All
 validation of content works by creating and signing a hash. A valid signature
 creates a chain of trust. A broken chain of trust, seen as an invalid
 signature, means the content is not valid.
@@ -21,7 +21,7 @@ For the outlined steps, the installer image of the latest release of |CL| is
 used for illustrative purposes. You may use any image of |CL| you choose.

 #. Download the image, the signature of the SHA512 sum of the image, and the
-   Clear Linux certificate used for signing the SHA512 sum.
+   |CL| certificate used for signing the SHA512 sum.

   .. code-block:: console

@@ -29,16 +29,16 @@ used for illustrative purposes. You may use any image of |CL| you choose.
      curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz
      # Signature of SHA512 sum of image
      curl -O https://download.clearlinux.org/current/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig
-      # Clear Linux certificate
+      # Certificate
      curl -O https://download.clearlinux.org/releases/$(curl https://download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem

-#. Generate the SHA256 sum of the Clear Linux certificate.
+#. Generate the SHA256 sum of the |CL| certificate.

   .. code-block:: console

      sha256sum ClearLinuxRoot.pem

-#. Ensure the generated SHA256 sum of the Clear Linux certificate matches the
+#. Ensure the generated SHA256 sum of the |CL| certificate matches the
   following SHA256 sum to verify the integrity of the certificate.

   .. code-block:: console
@@ -52,12 +52,19 @@ used for illustrative purposes. You may use any image of |CL| you choose.
      sha512sum clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz > sha512sum.out

 #. Ensure the signature of the SHA512 sum of the image was created using the
-   Clear Linux certificate. This validates the image is trusted and it has not
+   |CL| certificate. This validates the image is trusted and it has not
   been modified.

   .. code-block:: console

-      openssl smime -verify -in clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem
+      openssl smime -verify -purpose any -in clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem
+
+   .. note::
+
+      The `-purpose any` option is required when using OpenSSL 1.1.  If using
+      an earlier version of OpenSSL, omit this option to perform signature
+      validation.  The `openssl version` command may be used to determine the
+      version of OpenSSL in use.

 #. The output should contain ``Verification successful``. If the output
   contains ``bad_signature`` anywhere, then the image is not trustworthy.
@@ -101,7 +108,14 @@ these steps manually when performing a ``swupd update``.

   .. code-block:: console

-      openssl smime -verify -in Manifest.MoM.sig -inform der -content Manifest.MoM -CAfile Swupd_Root.pem
+      openssl smime -verify -purpose any -in Manifest.MoM.sig -inform der -content Manifest.MoM -CAfile Swupd_Root.pem
+
+   .. note::
+
+      The `-purpose any` option is required when using OpenSSL 1.1.  If using
+      an earlier version of OpenSSL, omit this option to perform signature
+      validation.  The `openssl version` command may be used to determine the
+      version of OpenSSL in use.

   .. note::

@@ -3,8 +3,8 @@
 Build a custom |CL-ATTR| based Docker container image
 #######################################################

-The official base |CL-ATTR| container image is published on Docker\* Hub and 
-is updated on a regular basis. This guide contains the steps to build a 
+The official base |CL-ATTR| container image is published on Docker\* Hub and
+is updated on a regular basis. This guide contains the steps to build a
 custom container image.

 Prerequisites
@@ -111,7 +111,7 @@ Build the base container image
    ..  note::

        * :file:`os-core` provides the minimal Linux namespace.
-        * :file:`os-core-update` provides the basic suite for running the |CLOSIA|
+        * :file:`os-core-update` provides the basic suite for running the |CL|
          updater.

 #. Optionally, you can include additional bundles with the base image.
@@ -25,7 +25,7 @@ drivers, sample applications, and tools for fast packet processing.
 Prerequisites
 *************

-*  Two platforms using |CLOSIA| release `13330`_ or higher.
+*  Two platforms using |CL-ATTR| release `13330`_ or higher.
 *  Both images must include the :file:`kernel-native bundle`.
 *  Install the :file:`network-basic-dev` bundle with the command:

@@ -130,7 +130,7 @@ NICs to DPDK modules to run DPDK applications.
 Set hugepages (Platforms A and B)
 *********************************

-|CLOSIA| supports `hugepages` for the large memory pool allocation used for
+|CL| supports `hugepages` for the large memory pool allocation used for
 packet buffers.

 #. Set the number of hugepages.
@@ -264,7 +264,7 @@ machines control the NICs on the host.

      sudo curl -O https://download.clearlinux.org/image/start_qemu.sh

-#. Download a bare-metal image of |CLOSIA| and rename it as :file:`clear.img`.
+#. Download a bare-metal image of |CL| and rename it as :file:`clear.img`.

 #. Look for an Ethernet\* device entry that contains vendor and device ID:

@@ -283,7 +283,7 @@ machines control the NICs on the host.
   host.


-#. Unbind the NICs from the host to do pass-through with virtual machines. |CLOSIA|
+#. Unbind the NICs from the host to do pass-through with virtual machines. |CL|
   supports this action. The commands take the format:

   .. code-block:: bash
@@ -1,9 +1,9 @@
 .. _ipxe-install:

-Install Clear Linux over the network with iPXE
-################################################
+Install |CL-ATTR| over the network with iPXE
+############################################

-This guide describes how to install Clear Linux\* using :abbr:`PXE (Pre-boot
+This guide describes how to install |CL-ATTR| using :abbr:`PXE (Pre-boot
 Execution Environment)`.

 PXE is an industry standard that describes client-server interaction with
@@ -6,7 +6,7 @@ Combine multiple interfaces with network bonding
 Network bonding combines multiple network interfaces into a single logical
 interface to provide redundancy and bandwidth aggregation.

-|CLOSIA| includes Linux bonding_ and team_ drivers. This guide describes how
+|CL-ATTR| includes Linux bonding_ and team_ drivers. This guide describes how
 to configure systemd to use the `bonding` driver.

 The example demonstrates how to:
@@ -4,7 +4,7 @@ Network guide
 #############

 This guide provides step-by-step instructions for common tasks associated with
-the configuration, administration, and use of networks in the |CLOSIA|.
+the configuration, administration, and use of networks in the |CL-ATTR|.

 .. toctree::
   :maxdepth: 1
@@ -1,10 +1,10 @@
 .. _vnc:

-Remote-desktop to a Clear Linux host using VNC
+Remote-desktop to a |CL-ATTR| host using VNC
 ##############################################

 :abbr:`VNC (Virtual Network Computing)` is a client-server GUI-based tool
-that allows you to connect via remote-desktop to your |CLOSIA| host.    
+that allows you to connect via remote-desktop to your |CL-ATTR| host.

 This guide shows you how to:

@@ -15,13 +15,13 @@ This guide shows you how to:
 * Terminate a VNC connection to your |CL| host.
 * Encrypt VNC traffic through an SSH tunnel.

-Install the VNC server and misc. components on your Clear Linux host
-********************************************************************
+Install the VNC server and misc. components on your host
+********************************************************

 To configure VNC to work on your |CL| host, install these bundles:

-* `desktop-autostart`: Installs :abbr:`GDM (Gnome Desktop Manager)`, sets 
-  it to start automatically on boot, and installs TigerVNC Viewer.  
+* `desktop-autostart`: Installs :abbr:`GDM (Gnome Desktop Manager)`, sets
+  it to start automatically on boot, and installs TigerVNC Viewer.
 * `vnc-server`: Installs the TigerVNC server.

 Follow these steps:
@@ -35,16 +35,16 @@ Follow these steps:
 #. Install the |CL| bundles.

   .. code-block:: console
-      
+
      # swupd bundle-add desktop-autostart vnc-server

 #. Reboot your |CL| host.

-Configure a VNC-server-start method on your Clear Linux host
-************************************************************
+Configure a VNC-server-start method on your host
+************************************************

-There are three methods you can use to configure and start the VNC server on 
-your host: 
+There are three methods you can use to configure and start the VNC server on
+your |CL| host:

 .. list-table:: Table 1: VNC-server-start Configuration Methods
   :widths: 10,20,20,20
@@ -55,14 +55,14 @@ your host:
     - `Method 2`: Automatically start a VNC session via a systemd service script
     - `Method 3`: Create multi-user logins with authentication through GDM
   * - Description
-     - This is the traditional method where you SSH into the |CL| host, manually 
-       start a VNC session to get a display ID, and connect to it by 
+     - This is the traditional method where you SSH into the |CL| host, manually
+       start a VNC session to get a display ID, and connect to it by
       supplying the display ID.
-     - The system administrator sets up a systemd service script for you with 
-       a pre-assigned display ID.  You make a VNC connection and supply 
+     - 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.
-       When you make a VNC connection to the |CL| host, you see  
+       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
@@ -82,10 +82,10 @@ your host:
     - No.  Use |CL| account username and password through GDM


-Although all three methods can coexist on the same |CL| host, we recommend 
-you pick a method that suits your needs. 
+Although all three methods can coexist on the same |CL| host, we recommend
+you pick a method that suits your needs.

-For simplicity, the rest of this guide refers to these methods as 
+For simplicity, the rest of this guide refers to these methods as
 `Method 1`, `Method 2`, and `Method 3`.

 Method 1: Manually start a VNC session
@@ -94,18 +94,18 @@ 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 emulator.
 #. 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.

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

-      $ vncserver 
+      $ vncserver

   Example output:

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

      $ vncserver

@@ -123,15 +123,15 @@ You (and each user) must perform these steps to initialize your VNC settings.
      Starting applications specified in /home/vnc-user-a/.vnc/xstartup
      Log file is /home/vnc-user-a/.vnc/clr-linux:2.log

-   Upon completion, you can find the default configuration files and the 
-   password file hidden in the `.vnc` directory in your home directory.    
+   Upon completion, you can find the default configuration files and the
+   password file hidden in the `.vnc` directory in your home directory.

-   Also, a VNC session starts and shows a unique display ID, which is the 
-   number following the hostname and the colon `:`.  In the above example, the display ID is 2.  In a later step, you will supply the display ID to 
-   your VNC viewer app for connection.  
+   Also, a VNC session starts and shows a unique display ID, which is the
+   number following the hostname and the colon `:`.  In the above example, the display ID is 2.  In a later step, you will supply the display ID to
+   your VNC viewer app for connection.

-#. Kill the active VNC session for the time being with the 
-   :command:`vncserver -kill :[display ID]` command.  Substitute [display ID] 
+#. Kill the active VNC session for the time being with the
+   :command:`vncserver -kill :[display ID]` command.  Substitute [display ID]
   with your active VNC session display ID.  For example:

   .. code-block:: console
@@ -140,22 +140,22 @@ You (and each user) must perform these steps to initialize your VNC settings.

   .. note::

-      If you do not recall the active session display ID, use the 
-      :command:`vncserver -list` command to find it.  
+      If you do not recall the active session display ID, use the
+      :command:`vncserver -list` command to find it.

 #. Optional configurations:

-   * To customize settings such as screen size, security type, etc., 
-     modify the :file:`$HOME/.vnc/config` file.  
-   * To customize the applications to run at startup, modify the 
-     :file:`$HOME/.vnc/xstartup` file.  
+   * To customize settings such as screen size, security type, etc.,
+     modify the :file:`$HOME/.vnc/config` file.
+   * To customize the applications to run at startup, modify the
+     :file:`$HOME/.vnc/xstartup` file.

 Method 2: Automatically start a VNC session via a systemd service script
 ========================================================================

 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.  
+set up a systemd service file for all intended VNC users with their own
+preassigned unique display ID.

 #. Log in and get root privileges.

@@ -163,7 +163,7 @@ preassigned unique display ID.

      $ sudo -s

-#. Make sure the user accounts already exist.  Use the following command to 
+#. Make sure the user accounts already exist.  Use the following command to
   list all users.


@@ -180,8 +180,8 @@ preassigned unique display ID.
 #. Create a systemd service script file :file:`vncserver@:[X].service`,
   where [X] is the display ID, for each user in :file:`/etc/systemd/system`
   Each user must be assigned a unique display ID.  Be sure the correct
-   username is entered in the `User` field. The example below shows user 
-   `vnc-user-b` who is assigned the display ID `5`.  
+   username is entered in the `User` field. The example below shows user
+   `vnc-user-b` who is assigned the display ID `5`.

   .. code-block:: console

@@ -203,12 +203,12 @@ preassigned unique display ID.
      [Install]
      WantedBy=multi-user.target

-      EOF 
+      EOF

-#. Have each user log into their account and set a VNC password with 
+#. Have each user log into their account and set a VNC password with
   the :command:`vncpasswd` command before proceeding to the next step.

-#. Start the VNC service script and set it to start automatically on 
+#. Start the VNC service script and set it to start automatically on
   boot for each user.  Replace the [X] with the display ID.

   .. code-block:: console
@@ -217,29 +217,29 @@ preassigned unique display ID.
      # systemctl start vncserver@:[X].service
      # systemctl enable vncserver@:[X].service

-#. After starting the services, verify they are running.  
+#. After starting the services, verify they are running.

   .. code-block:: console

      # systemctl | grep vnc

-   The example below shows 2 VNC sessions that were successfully started for 
+   The example below shows 2 VNC sessions that were successfully started for
   users `vnc-user-b` with display ID 5 and `vnc-user-c` with display ID 6.

   .. code-block:: console

      # 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"                           
-      system-vncserver.slice  loaded active active system-vncserver.slice    
+      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"
+      system-vncserver.slice  loaded active active system-vncserver.slice

-Method 3: Multi-user logins with authentication through GDM 
+Method 3: Multi-user logins with authentication through GDM
 ===========================================================

-For this method, VNC is configured as a systemd service that listens on port 
-5900 and GDM is configured to accept access requests from VNC. When you 
-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.   
+For this method, VNC is configured as a systemd service that listens on port
+5900 and GDM is configured to accept access requests from VNC. When you
+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.

@@ -253,7 +253,7 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc

      # 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` and add the following:

   .. code-block:: console

@@ -307,7 +307,7 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc

      EOF

-#. Start the VNC socket script and set it to start automatically on boot.  
+#. Start the VNC socket script and set it to start automatically on boot.

   .. code-block:: console

@@ -315,20 +315,20 @@ make a VNC connection to your |CL| host, you are presented with the GDM login sc
      # systemctl start xvnc.socket
      # systemctl enable xvnc.socket

-#. After starting the socket, verify it is running.  
+#. After starting the socket, verify it is running.

   .. code-block:: console

      # systemctl | grep vnc

-   The example below shows the xvnc.socket is running.  
+   The example below shows the xvnc.socket is running.

   .. code-block:: console

      # systemctl | grep vnc

      xvnc.socket 		loaded active listening	XVNC Server on port 5900
-      system-xvnc.slice 	loaded active active	system-xvnc.slice    
+      system-xvnc.slice 	loaded active active	system-xvnc.slice

 See the `vncserver` Man page for additional information.

@@ -336,15 +336,15 @@ Install a VNC viewer app and an SSH client on your client system
 ****************************************************************

 You need a VNC viewer app on your client system to connect to your |CL| host.
-An SSH client is only needed if you chose to use `Method 1` or you plan to 
-encrypt your VNC traffic, which is discussed later in this guide. 
+An SSH client is only needed if you chose to use `Method 1` or you plan to
+encrypt your VNC traffic, which is discussed later in this guide.

-Perform the steps below to add these apps to your client system.   
+Perform the steps below to add these apps to your client system.

 Install a VNC viewer app
 ========================

-On |CL|: 
+On |CL|:

 .. code-block:: console

@@ -354,9 +354,9 @@ On Ubuntu, Mint:

 .. code-block:: console

-   # apt-get install xtightvncviewer 
+   # apt-get install xtightvncviewer

-On Fedora: 
+On Fedora:

 .. code-block:: console

@@ -365,38 +365,38 @@ On Fedora:
 On Windows:

 * Install `RealVNC for Windows`_
-  
+
 On macOS:

-* Install `RealVNC for macOS`_ 
+* Install `RealVNC for macOS`_

 Install an SSH client
 =====================

-* On most Linux distros (Clear Linux, Ubuntu, Mint, Fedora, etc.) and macOS, 
+* On most Linux distros (|CL|, Ubuntu, Mint, Fedora, etc.) and macOS,
  SSH is built-in so you don't need to install it.
 * On Windows, you can install `Putty`_.

-Establish a VNC connection to your Clear Linux host
-***************************************************
+Establish a VNC connection to your host
+***************************************

-Depending on the VNC-server-configuration method chosen, use the appropriate VNC connection:  
+Depending on the VNC-server-configuration method chosen, use the appropriate VNC connection:

-If you chose `Method 1`, you must take a few extra steps by 
-using SSH to connect to your |CL| host and then manually launching VNC. 
+If you chose `Method 1`, you must take a few extra steps by
+using SSH to connect to your |CL| host and then manually launching VNC.

 If you chose `Method 2`, get your preassigned VNC display ID from your
-system administrator first and then proceed to the 
+system administrator first and then proceed to the
 :ref:`connect-to-vnc-session` section below.

-If you chose `Method 3`, proceed to the 
-:ref:`connect-to-vnc-session` below.  
+If you chose `Method 3`, proceed to the
+:ref:`connect-to-vnc-session` below.


-SSH into your Clear Linux host and launch VNC
-=============================================
+SSH into your host and launch VNC
+=================================

-#. SSH into your Clear Linux host
+#. SSH into your |CL| host

   #. On Linux distros and macOS:

@@ -409,8 +409,8 @@ SSH into your Clear Linux host and launch VNC
      #. Launch Putty.
      #. Under the :guilabel:`Category` section, select :guilabel:`Session`.
         See Figure 1.
-      #. Enter the IP address of your Clear Linux host in the 
-         :guilabel:`Host Name (or IP address)` field. 
+      #. Enter the IP address of your |CL| host in the
+         :guilabel:`Host Name (or IP address)` field.
      #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`.
      #. Click the :guilabel:`Open` button.

@@ -420,8 +420,8 @@ SSH into your Clear Linux host and launch VNC

            Figure 1: Putty - configure SSH session settings

-#. Log in with your |CL| username and password. Do not use your VNC 
-   password.  
+#. Log in with your |CL| username and password. Do not use your VNC
+   password.
 #. Start a VNC session.

   .. code-block:: console
@@ -440,35 +440,35 @@ SSH into your Clear Linux host and launch VNC
      Log file is /home/vnc-user-c/.vnc/clr-linux:3.log

 #. Take note of the generated display ID because you will input it into
-   the VNC viewer app to establish the connection.  The above example shows 
-   the display ID is 3.  
+   the VNC viewer app to establish the connection.  The above example shows
+   the display ID is 3.

   .. note::

-      VNC automatically picks a unique display ID unless you specify one.  
-      To specify a display ID, enter a unique number that is not already 
-      in use after the colon.  For example: 
+      VNC automatically picks a unique display ID unless you specify one.
+      To specify a display ID, enter a unique number that is not already
+      in use after the colon.  For example:

   .. code-block:: console

      $ vncserver :8

-#. You can now end the SSH connection by logging out.  This does 
-   not terminate your active VNC session.   
+#. You can now end the SSH connection by logging out.  This does
+   not terminate your active VNC session.

 .. _connect-to-vnc-session:

 Connect to your VNC session
 ===========================

-For `Method 1` and `Method 2`, you must connect to a specific active session 
-or display ID using one of two options: 
+For `Method 1` and `Method 2`, you must connect to a specific active session
+or display ID using one of two options:

 * Use a fully-qualified VNC port number, which consists of the default VNC
  server port (5900) plus the display ID
-* Use the display ID  
+* Use the display ID

-For example, if the display ID is 3, it can be specified as `5903` or just 
+For example, if the display ID is 3, it can be specified as `5903` or just
 as `3`. For `Method 3`, VNC does not expect a display ID.  Use `5900`. For simplicity, the instructions below use the fully-qualified VNC port
 number.

@@ -483,22 +483,22 @@ number.
 #. Enter your credentials.

   * For `Method 1` and `Method 2`, enter your VNC password.  No username is
-     required.  
+     required.
   * For `Method 3`, enter your |CL| account username and password through
     GDM.

     .. note::

        With `Method 3`, you cannot remotely log into your |CL| host through
-        VNC if you are logged in locally and vice versa.      
+        VNC if you are logged in locally and vice versa.

 **On Windows and macOS using `RealVNC` app:**

 #. Start the RealVNC viewer app. See Figure 2.
-#. Enter the IP address of the Clear Linux host and the fully-qualified 
+#. Enter the IP address of the |CL| host and the fully-qualified
   VNC port number.

-   The following screenshot shows connecting to |CL| host 
+   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
@@ -512,7 +512,7 @@ number.
 #. Enter your credentials.

   * For `Method 1` and `Method 2`, enter your VNC password.  No username is
-     required.  
+     required.
   * For `Method 3`, enter your |CL| account username and password through
     GDM.

@@ -520,8 +520,8 @@ number.

        With `Method 3`, you cannot remotely log into your |CL| host through
        VNC if you are logged in locally and vice versa.
-  
-`Optional: Configure RealVNC Image Quality` 
+
+`Optional: Configure RealVNC Image Quality`
 -------------------------------------------

 To increase the RealVNC viewer image quality, manually change the `ColorLevel` value. Follow these steps:
@@ -546,16 +546,16 @@ To increase the RealVNC viewer image quality, manually change the `ColorLevel` v

      Figure 4: RealVNC Viewer - change :guilabel:`ColorLevel`

-Terminate a VNC connection to your Clear Linux host
-***************************************************
+Terminate a VNC connection to your host
+***************************************

-For `Method 1` and `Method 2`, once started, a VNC session remains active 
+For `Method 1` and `Method 2`, once started, a VNC session remains active
 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 Clear Linux host.
+#. SSH into your |CL| host.
 #. Open a terminal emulator.
-#. Find the active VNC session display ID with the command 
+#. Find the active VNC session display ID with the command
   :command:`vncserver -list`.

   .. code-block:: console
@@ -581,7 +581,7 @@ truly terminate an active VNC session, follow these steps:
 Encrypt VNC traffic through an SSH tunnel
 *****************************************

-By default, VNC traffic is not encrypted.  Figure 6 shows an example warning 
+By default, VNC traffic is not encrypted.  Figure 6 shows an example warning
 from RealVNC Viewer.

 .. figure:: figures/vnc/vnc-6.png
@@ -592,13 +592,13 @@ from RealVNC Viewer.

 To add security, VNC traffic can be routed through an SSH tunnel. This is accomplished by following these steps:

-#. Configure the VNC server to only accept connection from localhost by 
+#. Configure the VNC server to only accept connection from localhost by
   adding the `-localhost` option.
-#. Set up an SSH tunnel between your client system and your |CL| host.  
-   Your client system will forward traffic from the localhost (the client) 
-   destined for a specified fully-qualified VNC port number (on the client) 
-   to your |CL| host with the same port number.  
-#. The VNC viewer app on your client system will now connect to localhost, 
+#. Set up an SSH tunnel between your client system and your |CL| host.
+   Your client system will forward traffic from the localhost (the client)
+   destined for a specified fully-qualified VNC port number (on the client)
+   to your |CL| host with the same port number.
+#. The VNC viewer app on your client system will now connect to localhost,
   instead of the IP address of your |CL| host.

 Configure VNC to only accept connection from localhost
@@ -622,11 +622,11 @@ For `Method 1`:
      localhost
      # alwaysshared

-#. If an active session exists, kill it, and then restart it. 
+#. If an active session exists, kill it, and then restart it.

 For `Method 2`:

-#. Edit the systemd service script :file:`vncserver@:[X].service` located in 
+#. Edit the systemd service script :file:`vncserver@:[X].service` located in
   :file:`/etc/systemd/system` and add `-localhost` to the `ExecStart`
   line. The example below uses vncserver@:5.service:

@@ -657,12 +657,12 @@ For `Method 2`:

 For `Method 3`:

-#. No change is needed to the :file:`xvnc@service` script.  
+#. No change is needed to the :file:`xvnc@service` script.

   After you have restarted your VNC session, you can verify that it only
   accepts connections from localhost by using the :command:`netstat`
-   command like this: 
-   
+   command like this:
+
   .. code-block:: console

      $ netstat -plant
@@ -673,7 +673,7 @@ For `Method 3`:
      command.

 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 `-localhost` option was used.  
+any host as specified by the `0.0.0.0`'s.  This is before the `-localhost` option was used.

 .. figure:: figures/vnc/vnc-7.png
   :scale: 100 %
@@ -681,8 +681,8 @@ any host as specified by the `0.0.0.0`'s.  This is before the `-localhost` optio

   Figure 7: VNC sessions (5901 and 5905) accepting connections from any host

-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 `-localhost` option was used.  
- 
+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 `-localhost` option was used.
+
 .. figure:: figures/vnc/vnc-8.png
   :scale: 100 %
   :alt: VNC session only accepting connection from localhost
@@ -698,23 +698,23 @@ Set up an SSH tunnel from your client system to your |CL| host

   .. code-block:: console

-      $ ssh -L [client port number]:localhost:[fully-qualified VNC port number] \ 
+      $ ssh -L [client port number]:localhost:[fully-qualified VNC port number] \
      -N -f -l [username] [clear-linux-host-ip-address]

 #. Enter your |CL| account password (not your VNC password).

-   .. note:: 
+   .. note::

      *	`-L` specifies that [client port number] on the localhost (on the
-        client side) is forwarded to [fully-qualified VNC port number] 
+        client side) is forwarded to [fully-qualified VNC port number]
        (on the server side).
-      * Replace `[client port number]` with an available client port number 
-        (for example: 1234). For simplicity, you can make the 
+      * Replace `[client port number]` with an available client port number
+        (for example: 1234). For simplicity, you can make the
        `[client port number]` the same as the `[fully-qualified VNC port number]`.
-      * Replace `[fully-qualified VNC port number]` with 5900 (default VNC 
-        port) plus the display ID.  For example, if the display ID is 2, 
-        the fully-qualified VNC port number is is 5902. 
-      *	`-N` tells SSH to only forward ports and not execute a remote 
+      * Replace `[fully-qualified VNC port number]` with 5900 (default VNC
+        port) plus the display ID.  For example, if the display ID is 2,
+        the fully-qualified VNC port number is is 5902.
+      *	`-N` tells SSH to only forward ports and not execute a remote
        command.
      *	`-f` tells SSH to go into the background before command execution.
      *	`-l` specifies the username to log in as.
@@ -722,28 +722,28 @@ Set up an SSH tunnel from your client system to your |CL| host
 **On Windows:**

 #. Launch Putty.
-#. Specify the |CL| VNC host to connect to. 
-	
-   #. Under the :guilabel:`Category` section, select :guilabel:`Session`. 
+#. Specify the |CL| VNC host to connect to.
+
+   #. Under the :guilabel:`Category` section, select :guilabel:`Session`.
      See Figure 1.
-   #. Enter the IP address of your Clear Linux host in the 
-      :guilabel:`Host Name (or IP address)` field. 
+   #. Enter the IP address of your |CL| host in the
+      :guilabel:`Host Name (or IP address)` field.
   #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`.

 #. Configure the SSH tunnel.  See Figure 9 for an example.

-   #. Under the :guilabel:`Category` section, go to 
+   #. Under the :guilabel:`Category` section, go to
      :guilabel:`Connection` > :guilabel:`SSH` > :guilabel:`Tunnels`.
-		
-   #. In the :guilabel:`Source port` field, enter an available client 
+
+   #. In the :guilabel:`Source port` field, enter an available client
      port number (for example: 1234). For simplicity, you can make the
      `Source port` the same as the fully-qualified VNC port number.
-    
-   #. In the :guilabel:`Destination` field, enter 
+
+   #. In the :guilabel:`Destination` field, enter
      `localhost:` plus the fully-qualified VNC port number.

   #. Click the :guilabel:`Add` button.
- 
+
      .. figure:: figures/vnc/vnc-9.png
         :scale: 100 %
         :alt: Putty - configure SSH tunnel
@@ -756,7 +756,7 @@ Set up an SSH tunnel from your client system to your |CL| host
 Connect to a VNC session through an SSH tunnel
 ==============================================

-After you have set up an SSH tunnel, follow these instructions to connect to 
+After you have set up an SSH tunnel, follow these instructions to connect to
 your VNC session.

 **On Linux distros:**
@@ -776,13 +776,13 @@ your VNC session.
   .. figure:: figures/vnc/vnc-10.png
      :scale: 100 %
      :alt: RealVNC viewer app connecting to localhost:1234
- 
+
      Figure 10: RealVNC viewer app connecting to `localhost:1234`

-      .. note:: 
+      .. note::

-         RealVNC will still warn that the connection is not encrypted even 
-         though its traffic is going through the SSH tunnel.  You can ignore 
+         RealVNC will still warn that the connection is not encrypted even
+         though its traffic is going through the SSH tunnel.  You can ignore
         this warning.

 .. _RealVNC for Windows: https://www.realvnc.com/en/connect/download/viewer/windows/
@@ -0,0 +1,65 @@
+.. _telemctl:
+
+telemctl options
+################
+
+The |CL-ATTR| telemetry client provides an admin tool called ``telemctl`` 
+that is used for managing the telemetry services and probes. The tool is 
+located in :file:`/usr/bin`. Running it with no argument results in the 
+following:
+
+.. code-block:: bash
+
+   sudo telemctl
+
+.. code-block:: console
+
+   /usr/bin/telemctl - Control actions for telemetry services
+     stop       Stops all running telemetry services
+     start      Starts all telemetry services
+     restart    Restarts all telemetry services
+     is-active  Checks if telemprobd and telempostd are active
+     opt-in     Opts in to telemetry, and starts telemetry services
+     opt-out    Opts out of telemetry, and stops telemetry services
+     journal    Prints telemetry journal contents. Use -h argument for more
+                options
+
+telemctl commands:
+******************
+
+start/stop/restart
+==================
+
+The commands to start, stop and restart the telemetry services manage all
+required services and probes on the system.  There is no need to separately
+start/stop/restart the two client daemons **telemprobd** and **telempostd**.
+The **restart** command option will call **telemctl stop** followed by 
+**telemctl start** .
+
+is-active
+=========
+
+The `is-active` option reports whether the two client daemons are active.
+This is useful to verify that the **opt-in** and **opt-out** options have
+taken effect, or to ensure that telemetry is functioning on the system.
+Note that both daemons are verified.
+
+.. code-block:: bash
+
+   sudo telemctl is-active
+
+.. code-block:: console
+
+   telemprobd : active
+   telempostd : active
+
+.. include:: ./telemetry-enable.rst
+   :start-after: incl-opt-in-out-telemetry:
+   :end-before: incl-opt-in-out-telemetry-end:
+
+Next steps
+==========
+
+Learn to read records:
+
+* :ref:`telemetry-journal`
@@ -0,0 +1,19 @@
+.. _telemetrics:
+
+Telemetry
+#########
+
+The |CL-ATTR| telemetrics solution collects data from running |CL| systems
+and helps to quickly identify and fix bugs in the OS. These guides will walk
+you through setup, configuration, and customization of the telemetry client. The data collected from the client system is analyzed and presented by the
+telemetry backend solution. For more details, learn how to
+:ref:`telemetry-backend`.
+
+.. toctree::
+   :maxdepth: 1
+
+   telemetry-enable
+   telemetry-config
+   telemctl
+   telemetry-journal
+   telemetry-z-api
@@ -0,0 +1,101 @@
+.. _telemetry-config:
+
+Telemetry client configuration
+##############################
+
+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 located
+at :file:`/usr/share/defaults/telemetrics/telemetrics.conf`. To modify or
+customize the configuration, copy the file from
+:file:`/usr/share/defaults/telemetrics` to
+:file:`/etc/telemetrics` and edit it.
+
+Configuration Options
+*********************
+The client uses the following configuration options from the config file:
+
+* **server**: This specifies the web server to which telempostd sends the
+  telemetry records.
+* **socket_path**: This specifies the path of the unix domain socket that
+  the telemprobd listens on for connections from the probes.
+* **spool_dir**: This configuration option is related to spooling. If the
+  daemon is not able to send the telemetry records to the backend server due
+  to reasons such as the network availability, then it stores the records in
+  a spool directory. This option specifies that path of the spool directory.
+  This directory should be owned by the same user as the daemon.
+
+  - mkdir -p /var/spool/telemetry
+  - chown -R telemetry:telemetry /var/spool/telemetry
+  - systemctl restart telemprobd.service
+
+* **record_expiry**: This is the time in minutes after which the records in
+  the spool directory are deleted by the daemon.
+* **spool_process_time**: This specifies the time interval in seconds that
+  the daemon waits for before checking the spool directory for records. The
+  daemon picks up the records in the order of modification date and tries to
+  send the record to the server. It sends a maximum of 10 records at a time.
+  If it was able to send a record successfully, it deletes the record from
+  the spool. If the daemon finds a record older than the "record_expiry"
+  time, then it deletes that record. The daemon looks at a maximum of 20
+  records in a single spool run loop.
+* **rate_limit_enabled**: This determines whether rate-limiting is enabled or
+  disabled. When enabled, there is a threshold on both records sent within a
+  window of time, and record bytes sent within a window a time.
+* **record_burst_limit**: This is the maximum amount of records allowed to be
+  passed by the daemon within the record_window_length of time. If set to
+  -1, the rate-limiting for record bursts is disabled.
+* **record_window_length**: The time in minutes (0-59) that
+  establishes the window length for the record_burst_limit. EX: if
+  record_burst_window=1000 and record_window_length=15, then no more than
+  1000 records can be passed within any given fifteen minute window.
+* **byte_burst_limit**: This is the maximum amount of bytes that can be
+  passed by the daemon within the byte_window_length of time. If set to -1, the rate-limiting for byte bursts is disabled.
+* **byte_window_length**: This is the time, in minutes (0-59), that
+  establishes the window length for the byte_burst_limit.
+* **rate_limit_strategy**: This is the strategy chosen once the rate-limiting
+  threshold has been reached. Currently the options are 'drop' or 'spool',
+  with spool being the default. If spool is chosen, records will be spooled
+  and sent at a later time.
+* **record_retention_enabled**: When this key is enabled (true) the daemon
+  saves a copy of the payload on disk from all valid records. To avoid the
+  excessive use of disk space only the latest 100 records are kept. The
+  default value for this configuration key is false.
+* **record_server_delivery_enabled**: This key controls the delivery of
+  records to server; when enabled (default value), the record will be posted
+  to the address in the configuration file. If this configuration key is
+  disabled (false), records will not be spooled or posted to backend. This
+  configuration key can be used in combination with record_retention_enabled
+  to keep copies of telemetry records locally only.
+
+  .. note::
+
+  	 Configuration options may change as the telemetry client evolves.
+  	 Please use the comments in the file itself as the most accurate
+  	 reference for configuration.
+
+Setting a static machine id
+===========================
+
+The machine id reported by the telemetry client is rotated every 3 days for
+privacy reasons. If you wish to have a static machine id for testing
+purposes, you can opt in by creating a static machine id file named
+"opt-in-static-machine-id" under the directory  :file:`/etc/telemetrics/`.
+Where "unique machine ID" is your desired static machine ID.
+
+.. code-block:: bash
+
+   sudo mkdir -p /etc/telemetrics
+
+.. code-block:: bash
+
+   sudo echo "unique machine ID" > /etc/telemetrics/opt-in-static-machine-id
+
+.. note::
+
+   The machine id mentioned here is not the same as the system hostname. Learn how to :ref:`hostname`: 
+
+Next steps
+==========
+
+* :ref:`telemctl`
@@ -1,116 +1,114 @@
-.. _telemetry-enable:
-
-Enable and disable telemetry in |CL-ATTR|
-#########################################
-
-|CL-ATTR| includes a telemetry solution as part of the OS that records events
-of interest and reports them back to the development team via the telemetrics
-client daemons, **telempobd** and **telempostmd**. This functionality is
-maintained in the **telemetrics** software bundle.
-
-.. note::
-   The telemetry functionality adheres to `Intel privacy policies`_
-   regarding the collection and use of :abbr:`PII (Personally Identifiable
-   Information)` and is open source. Specifically, no intentionally
-   identifiable information about the user or system owner is collected.
-
-End users may enable or disable the telemetry component of |CL| or even
-redirect where the records go if they wish to collect records for themselves.
-
-Install the telemetry software bundle
-*************************************
-
-During the initial installation of |CL|, you are requested to join the
-stability enhancement program and allow |CL| to collect anonymous reports
-to improve system stability. If you choose not to join this program, then the
-telemetry software bundle is not added to your system.
-
-To install the telemetry bundle, enter the following command as either the
-root user or with :command:`sudo` privileges:
-
-.. code-block:: bash
-
-	sudo swupd bundle-add telemetrics
-
-This adds the telemetrics-client to your system and you will automatically
-opt-in for the service.
-
-Enable telemetry
-*****************
-
-To start telemetry on your system, run the following command:
-
-.. code-block:: bash
-
-   sudo telemctl start
-
-This enables and starts the :command:`telemprobd` and :command:`telempostd` daemons and your system will
-begin to send telemetry data to the server defined in the file
-:file:`/etc/telemetrics/telemetrics.conf`. If this file does not exist, the
-:command:`telemprobd` and :command:`telempostd` daemons will use the file
-:file:`/usr/share/defaults/telemetrics/telemetrics.conf`.
-
-Disable telemetry
-*****************
-
-To disable both of the telemetry daemons, run the following command:
-
-.. code-block:: bash
-
-   sudo telemctl stop
-
-Opt-out of telemetry
-********************
-
-To stop sending telemetrics data from your system, opt out of the
-telemetry service:
-
-.. code-block:: bash
-
-   sudo telemctl opt-out
-
-This creates the file :file:`/etc/telemetrics/opt-out` and stops the
-telemetry services.
-
-Opt-in to telemetry
-*******************
-
-Conversely, to opt-in to the telemetry services, simply enter the opt-in
-command and start the service:
-
-.. code-block:: bash
-
-   sudo telemctl opt-in
-
-This removes the file :file:`/etc/telemetrics/opt-out` file, if it exists,
-and starts the telemetry services.
-
-.. note::
-	
-   To opt-in but not immediately start telemetry services, you will need to
-   run the command :command:`sudo telemctl stop` after the :command:`opt-in`
-   command is entered. Once you are ready to start the service, enter the
-   command :command:`sudo telemctl start`.
-
-Remove the telemetry software bundle
-************************************
-
-To completely remove telemetrics from your system, use the command
-:command:`swupd` to remove the telemetry software bundle:
-
-.. code-block:: bash
-
-   sudo swupd bundle-remove telemetrics
-
-Additional resources
-********************
-
-*	`Telemetry feature description`_
-*	:ref:`Telemetry architecture<telemetry-about>`
-*	:ref:`telemetry-backend`
-*	https://github.com/clearlinux/telemetrics-client
-
-.. _Intel privacy policies: https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html
-
-.. _`Telemetry feature description`:
-	https://clearlinux.org/features/telemetry
+.. _telemetry-enable:
+
+Enable telemetry
+################
+
+Telemetry enables developers to observe and proactively address issues on
+|CL-ATTR| before end users are impacted. The telemetry functionality
+is maintained in the ``telemetrics`` software bundle.
+
+.. note::
+
+   The telemetry functionality adheres to `Intel privacy policies`_
+   regarding the collection and use of :abbr:`PII (Personally Identifiable
+   Information)` and is open source. Specifically, no intentionally
+   identifiable information about the user or system owner is collected.
+
+End users may enable or disable the telemetry component of |CL| or even
+redirect where the records go if they wish to collect records for themselves.
+
+Install the telemetry software bundle
+*************************************
+
+During the initial installation of |CL|, you are requested to join the
+stability enhancement program and allow |CL| to collect anonymous reports
+to improve system stability. If you choose not to join this program, then the
+telemetry software bundle is not added to your system.
+
+To install the telemetry bundle, enter the following command as either the
+root user or with :command:`sudo` privileges:
+
+.. code-block:: bash
+
+	sudo swupd bundle-add telemetrics
+
+This adds the telemetrics-client to your system, and you will automatically
+opt-in for the service.
+
+Enable telemetry
+================
+
+To start telemetry on your system, run the following command:
+
+.. code-block:: bash
+
+   sudo telemctl start
+
+This enables and starts the :command:`telemprobd` and :command:`telempostd`
+daemons. Your system will begin to send telemetry data to the server defined
+in the file :file:`/etc/telemetrics/telemetrics.conf`. If this file does not
+exist, the :command:`telemprobd` and :command:`telempostd` daemons will use
+the file :file:`/usr/share/defaults/telemetrics/telemetrics.conf`.
+
+Disable telemetry
+=================
+
+To disable both of the telemetry daemons, run the following command:
+
+.. code-block:: bash
+
+   sudo telemctl stop
+
+.. _incl-opt-in-out-telemetry:
+
+Opt-in to telemetry
+===================
+
+To opt-in to the telemetry services, simply enter the opt-in
+command and start the service:
+
+.. code-block:: bash
+
+   sudo telemctl opt-in
+
+This removes the file :file:`/etc/telemetrics/opt-out` file, if it exists,
+and starts the telemetry services.
+
+.. note::
+
+   To opt-in but not immediately start telemetry services, you will need to
+   run the command :command:`sudo telemctl stop` after the :command:`opt-in`
+   command is entered. Once you are ready to start the service, enter the
+   command :command:`sudo telemctl start`.
+
+Opt-out of telemetry
+====================
+
+To stop sending telemetrics data from your system, opt out of the
+telemetry service:
+
+.. code-block:: bash
+
+   sudo telemctl opt-out
+
+This creates the file :file:`/etc/telemetrics/opt-out` and stops the
+telemetry services.
+
+.. _incl-opt-in-out-telemetry-end:
+
+Remove the telemetry software bundle
+====================================
+
+To completely remove telemetrics from your system, use the :command:`swupd`
+command to remove the telemetry software bundle:
+
+.. code-block:: bash
+
+   sudo swupd bundle-remove telemetrics
+
+Next steps
+==========
+
+* :ref:`telemetry-config`
+
+.. _Intel privacy policies: https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html
@@ -0,0 +1,108 @@
+.. _telemetry-journal:
+
+telemctl journal
+################
+
+The telemctl ``journal`` command gives you access to features and options of
+the telemetry journal to assist with system analytics and debug. The
+:command:`telemctl journal` has a number of options to help filter
+records. Use :command:`-h` or :command:`--help` to view usage options.
+
+.. code-block:: bash
+
+   sudo telemctl journal -h
+
+::
+
+   -r,  --record_id        Print record with specific record_id
+   -e,  --event_id         Print records with specific event_id
+   -c,  --classification   Print records with specific classification
+   -b,  --boot_id          Print records with specific boot_id
+   -i,  --include_record   Include record content
+   -V,  --verbose          Verbose output
+   -h,  --help             Display this help message
+
+Journal Output
+**************
+
+To see the listing of records in the journal, run the command:
+
+.. code-block:: bash
+
+   sudo telemctl journal -V
+
+This will produce output like the following:
+
+.. list-table:: **Table 1. Journal Output**
+   :widths:  10 30 20 20 20
+   :header-rows: 1
+
+   * - Classification
+     - Time stamp
+     - Record ID
+     - Event ID
+     - Boot ID
+
+   * - org.clearlinux/heartbeat/ping
+     - Fri 2018-09-21 00:00:57 UTC
+     - 269e8e4026e6aa440c4d2ed71e38efcd
+     - b3a51b5e62a008ed0b56d1740be67d48
+     - 853a75aa-da3b-4356-a085-079abab3ffe1
+
+   * - org.clearlinux/hello/world
+     - Fri 2018-09-21 17:53:21 UTC
+     - b06c8d31adf5ccc7d5d3f8959d8d3e72
+     - 57c64c79a9b911d68f4dab10a00267d7
+     - 853a75aa-da3b-4356-a085-079abab3ffe1
+
+   * - org.clearlinux/crash/clr
+     - Fri 2018-09-21 17:57:59 UTC
+     - b62cd4278672ae3331cf121bc7a8e1c6
+     - b6adb5751382c48eebb7ee007fe1790a
+     - 853a75aa-da3b-4356-a085-079abab3ffe1
+
+Each line gives information about a distinct record.  The :command:`-V` or
+:command:`--verbose` option adds the header to identify the Classification,
+Time Stamp, Record ID, Event ID and Boot ID for each record. The journal
+feature can filter records according to the Classification, Record ID, Event
+ID and Boot ID by using the :command:`-c`,:command:`-r`, :command:`-e` and
+:command:`-b` options accordingly.
+
+Payload Information
+********************
+
+From the previous output, you may want to get more information about the
+record with the "org.clearlinux/crash/clr" classification to help debug a
+crash.  You can use the :command:`-c` and :command:`-i` options to see the payload of the record, like this:
+
+.. code-block:: bash
+
+   sudo telemctl journal -c org.clearlinux/crash/clr -i
+
+.. code-block:: console
+
+   org.clearlinux/crash/clr       Tue 2018-09-25 18:43:50 UTC 07ae583edbd13829965d67e9ba97d70c 69c600470769c841649266178375d67e d32c13d1-fda0-49c6-8431-e6c5b29cbefa
+   Process: /usr/bin/bash
+   PID: 685
+   Signal: 11
+
+   Backtrace (TID 685):
+   #0 kill() - [libc.so.6]
+   #1 bash_tilde_expand() - [/usr/bin/bash]
+   #2 maybe_execute_file() - [/usr/bin/bash]
+   #3 main() - [/usr/bin/bash]
+   #4 __libc_start_main() - [libc.so.6]
+   #5 _start() - [/usr/bin/bash]
+
+If you have records of multiple crashes, you can use the :command:'-r'
+option to specify the record more precisely, rather than going by
+classification. You can also specify a classification of record and use the
+:command:'-i' option to see the payload of each record with that
+classification.
+
+Next steps
+==========
+
+Adding telemetry to your applications:
+
+* :ref:`telemetry-api`
@@ -0,0 +1,170 @@
+.. _telemetry-api:
+
+Telemetry API
+#############
+
+Installing the ``telemetrics`` bundle includes the libtelemetry C library,
+which exposes an API used by the telemprobd and telempostd daemons. You
+can use these in your applications as well. The API documentation is found
+in the :file:`telemetry.h` file in `Telemetrics client`_ repository.
+
+Creating records with telem-record-gen
+**************************************
+
+The telemetrics bundle also provides a record generator tool called
+``telem-record-gen``. This tool can be used to create records from shell
+scripts, etc., when writing a probe in C is not desirable. Records are sent
+to the backend server, and can also be echoed to stdout.
+
+telem-record-gen usage
+======================
+
+.. code-block:: bash
+
+   telem-record-gen [OPTIONS] - create and send a custom telemetry record
+
+.. code-block:: console
+
+   Help Options:
+   -h, --help            Show help options
+
+   Application Options:
+   -V, --version         Print the program version
+   -s, --severity        Severity level (1-4) - (default 1)
+   -c, --class           Classification level_1/level_2/level_3 (required)
+   -p, --payload         Record body (max size = 8k) (required)
+   -P, --payload-file    File to read payload from
+   -R, --record-version  Version number for format of payload (default 1)
+   -e, --event-id        Event id to use in the record
+   -o, --echo            Echo record to stdout
+   -n, --no-post         Do not post record just print
+
+The :command:`-c` and :command:`-p` options are required; defaults are
+supplied for most other options. The maximum payload size is 8k
+(8192 bytes). Excess is ignored, regardless of source (file/commandline/
+stdin). An empty payload is allowed, but even an empty payload must be
+specified in one of the three ways shown below.
+
+telem-record-gen examples
+=========================
+
+There are three ways to supply the payload to the record.
+
+#. On the command line, use the :command:`-p <string>` option:
+
+   .. code-block:: bash
+
+      telem-record-gen -c a/b/c -n -o -p 'payload goes here'
+
+   .. code-block:: console
+
+      record_format_version: 4
+      classification: a/b/c
+      severity: 1
+      machine_id: FFFFFFFF
+      creation_timestamp: 1539023189
+      arch: x86_64
+      host_type: innotek GmbH|VirtualBox|1.2
+      build: 25180
+      kernel_version: 4.14.71-404.lts
+      payload_format_version: 1
+      system_name: clear-linux-os
+      board_name: VirtualBox|Oracle Corporation
+      cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz
+      bios_version: VirtualBox
+      event_id: 2236710e4fc11e4a646ce956c7802788
+
+      payload goes here
+
+#. Specify a file that contains the payload with the option
+   :command:'-P path/to/file'.
+
+   .. code-block:: bash
+
+      telem-record-gen -c a/b/c -n -o -P ./payload_file.txt
+
+   .. code-block:: console
+
+      record_format_version: 4
+      classification: a/b/c
+      severity: 1
+      machine_id: FFFFFFFF
+      creation_timestamp: 1539023621
+      arch: x86_64
+      host_type: innotek GmbH|VirtualBox|1.2
+      build: 25180
+      kernel_version: 4.14.71-404.lts
+      payload_format_version: 1
+      system_name: clear-linux-os
+      board_name: VirtualBox|Oracle Corporation
+      cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz
+      bios_version: VirtualBox
+      event_id: d73d6040afd7693cccdfece479df9795
+
+      payload read from file
+
+#. If the :command:`-p` or :command:`-P` options are absent, the tool reads
+   from stdin so you can use it in a :file:`heredoc` in scripts.
+
+   .. code-block:: bash
+
+      telem-record-gen -c a/b/c -n -o << HEOF
+      payload read from stdin
+      HEOF
+
+   .. code-block:: console
+
+      record_format_version: 4
+      classification: a/b/c
+      severity: 1
+      machine_id: FFFFFFFF
+      creation_timestamp: 1539023621
+      arch: x86_64
+      host_type: innotek GmbH|VirtualBox|1.2
+      build: 25180
+      kernel_version: 4.14.71-404.lts
+      payload_format_version: 1
+      system_name: clear-linux-os
+      board_name: VirtualBox|Oracle Corporation
+      cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz
+      bios_version: VirtualBox
+      event_id: 2f070e8e71679f2b1f28794e3a6c42ee
+
+      payload read from stdin
+
+   .. note::
+
+      Although only the classification and payload are specified, the tool supplies values for the remaining values.
+
+Telemetry records and the REST API
+==================================
+
+If you have not configured the telemetry client to keep records locally, you
+can view them using the Web UI of the server, or you can query them from the
+server using the REST API provided by |CL| telemetrics. The API is
+available at :file:`<server>/api/records`, and when queried, returns a JSON
+response that contains a list of records. There are several parameters for
+filtering queries, similar to the filters available through the telemetryui Records view.
+
+* classification: The classification of the record
+* severity: The severity of the record. Restricted to integer value
+* machine_id: The id of the machine where this record was generated on
+* build: The build on which the record was generated. Restricted to 256
+  characters.
+* created_in_days: causes the query to return records created after the last
+  given days
+* created_in_sec: returns the records created after the last given seconds
+* limit: The maximum number of records to be returned.
+
+Next Steps
+==========
+
+* :ref:`telemetry-backend`
+* `Telemetrics client`_
+
+Related topics
+==============
+
+* :ref:`telemetry-about`
+
+.. _Telemetrics client: https://github.com/clearlinux/telemetrics-client/
@@ -22,7 +22,7 @@ To search for bundles and their contents, enter:

 .. code-block:: bash

-   sudo swupd search [bundle name]  
+   sudo swupd search [bundle name]

 To add a bundle, enter:

@@ -30,14 +30,14 @@ To add a bundle, enter:

   sudo swupd bundle-add [bundle name]

-Additional information 
+Additional information
 ======================

 For additional :command:`swupd` commands, enter:

 .. code-block:: bash

-   swupd --help 
+   swupd --help

 To reference the :command:`swupd` man page, enter:

@@ -1,53 +1,3 @@
-<head>
-   <title>Bundles in Clear Linux OS for Intel® Architecture</title>
-   <style type="text/css">
-   table {
-      margin: 2em;
-      border: 1px solid #e0e0e0;
-      border-collapse: collapse;
-      width: auto;
-   }
-
-   th {
-      align: center;
-      padding: 0.33em;
-      border: #ccc solid 1px;
-      background-color: #555;
-      color: #fff;
-      text-transform: uppercase;
-      font-size: 1.21em
-   }
-
-   tbody tr:nth-child(odd) {
-      background-color: #e0e0e0;
-   }
-
-   .bundlename {
-      font-family: monospace;
-      font-size: 1.13em;
-      font-weight: bolder;
-      padding-left: 0.42em;
-   }
-
-   .bundlestatus {
-      font-family: sans;
-      font-weight: lighter;
-   }
-
-   .bundledesc {
-      font-size: 0.93em;
-      line-height: 0.88em;
-      font-family: sans;
-   }
-
-   li,
-   ul {
-      margin-left: 0.53em;
-      padding-left: 0.23em;
-   }
-   </style>
-</head>
-
 <table>
   <thead>
    <tr>
@@ -3,13 +3,12 @@
 Available bundles
 #################

-This document provides a current list of `available bundles`_ as 
-of ``12 September 2018``.                                      
+This document provides a current list of `available bundles`_. To learn more about how |CL-ATTR| uses bundles for software deployment, visit :ref:`bundles-about`.  

 Bundle list
 ===========

 .. raw:: html
-   :file: bundles.html
+   :file: bundles.html.txt

 .. _available bundles: https://github.com/clearlinux/clr-bundles
@@ -3,7 +3,7 @@
 Collaboration guidelines
 ########################

-Thank you for your interest in collaborating with the |CLOSIA|. This guide
+Thank you for your interest in collaborating with the |CL-ATTR|. This guide
 details the best ways to collaborate with the |CL| team.
 Additionally, this guide provides the guidelines our documentation follows.
 Thus, you can help improve our documents with your use case tutorials,
@@ -3,7 +3,7 @@
 Code blocks
 ###########

-Collaborating to the |CLOSIA| is all about code. Therefore, your
+Contributing to the |CL-ATTR| is all about code. Therefore, your
 documentation must include as many code examples as possible. You can write
 code examples directly in the documentation or include them from a source
 file. Use these guidelines to insert code blocks to your documentation:
@@ -4,7 +4,7 @@
 Contents directive
 ##################

-For |CL| documentation that has three or more sections, use the `contents::`
+For |CL-ATTR| documentation that has three or more sections, use the `contents::`
 directive as shown in the example below. This directive automatically captures the headings (and 
 subheadings if used) as specified in the value given after `:depth:`. Adding this directive to 
 longer documents allows users to quickly navigate to the desired section.
@@ -24,8 +24,8 @@ longer documents allows users to quickly navigate to the desired section.

 EXAMPLE: 

-Clear Linux Guide Example  
-*************************
+Guide Example  
+*************

 Introduction
 ============
@@ -12,7 +12,7 @@ consistency of the documents.
 Internal cross-references
 *************************

-An internal cross-reference is a reference to a location within the |CLOSIA|
+An internal cross-reference is a reference to a location within the |CL-ATTR|
 documentation. Use explicit markup labels and the ``:ref:`` role to create
 cross references to headings, figures, and code examples as needed. Every
 file must have a label before the title, which is identical to the file's 
@@ -127,7 +127,7 @@ Use this template to add a hyperlink with a separated definition:
 The include directive 
 *********************

-Clear Linux documentation also uses the ``.. include::`` 
+|CL| documentation also uses the ``.. include::`` 
 directive to include a portion of another reST file. 

 Use the ``.. include::`` directive to show a select portion of a file.  
@@ -3,7 +3,7 @@
 Documentation contribution guidelines
 #####################################

-The |CLOSIA| documentation contribution guidelines provide detailed information
+The |CL-ATTR| documentation contribution guidelines provide detailed information
 about the scope and purpose of the documentation, the accepted writing style,
 and the markup used.

@@ -4,7 +4,7 @@ Grammar guide
 #############

 This guide provides valuable insight into the correct grammar for the
-|CLOSIA| documentation. It covers subjects such as capitalization, verbs,
+|CL-ATTR| documentation. It covers subjects such as capitalization, verbs,
 hyphenation, possessives, and contractions.

 Capitalization
@@ -6,7 +6,7 @@ Headings
 Descriptive and brief headings are crucial to the quality of the
 documentation. Sphinx uses the headings within the
 :abbr:`ReST (RestructuredText)` files to generate the navigation of the HTML
-output and the outlines of the PDF files. The |CLOSIA| publishes the
+output and the outlines of the PDF files. The |CL-ATTR| publishes the
 documentation as HTML making consistent heading levels extremely important.

 In addition to the title of the file, only three levels of headings are
@@ -8,7 +8,7 @@ sometimes is difficult to explain using words alone. Well-planned graphics
 reduce the amount of text required to explain information. Non-native English
 readers rely heavily on graphics because graphics enhance their understanding of the text.

-Follow these guidelines when creating graphics for the |CLOSIA|:
+Follow these guidelines when creating graphics for the |CL-ATTR|:

 * Save the image files in a :file:`figures` folder. The folder must be found
  at the same level as the file containing the text.
@@ -4,7 +4,7 @@ Inline Markup
 *************

 Sphinx supports a large number of inline markup elements called roles. The
-|CLOSIA| documentation encourages the use of as many roles as
+|CL-ATTR| documentation encourages the use of as many roles as
 possible. Thus, you can use any additional roles supported by Sphinx
 not listed here. Please refer to the `Sphinx reStructuredText Markup`_
 documentation for the full list of supported roles.
@@ -4,13 +4,13 @@ Language reference guide
 ########################

 This section describes acceptable usage of the English language in the
-|CLOSIA| documentation. It includes information about words use,
+|CL-ATTR| documentation. It includes information about words use,
 punctuation, and grammar. This guide does not replace a professional
 writer's review but is intended to help collaborators submit consistent
 contributions.

 To make translations easier and to make the content accessible to non-native
-speakers, |CLOSIA| uses Simple English. However, we have not implemented any
+speakers, |CL-ATTR| uses Simple English. However, we have not implemented any
 controlled language standards.

 .. toctree::
@@ -4,7 +4,7 @@ Punctuation guide
 #################

 This section contains all the information regarding the correct use of
-punctuation for the |CLOSIA| documentation.
+punctuation for the |CL-ATTR| documentation.

 Commas, Semicolons, and Colons
 ******************************
@@ -8,7 +8,7 @@ RestructuredText guide
 Overview
 ********

-The |CLOSIA| uses Sphinx and RestructuredText as authoring tools for its
+The |CL-ATTR| uses Sphinx and RestructuredText as authoring tools for its
 documentation. This section contains the preferred methods for using the
 :abbr:`ReST (RestructuredText)` markup on your documents. Please refer to the
 `Sphinx documentation`_ for the complete list of available markup and use
@@ -12,7 +12,7 @@ Simple English improves the clarity of procedural technical writing,
 makes translation easier, and improves comprehension for people whose
 first language is not English.

-|CLOSIA| does not use controlled language, which restricts the writer's
+|CL-ATTR| does not use controlled language, which restricts the writer's
 vocabulary to a list of approved words. However, we do strongly recommend
 using the language principles described below.

@@ -4,7 +4,7 @@ Consistent content structures guide
 ###################################

 This section guides you through the different content structures used in the
-|CLOSIA| documentation. This section serves as an example of the correct use
+|CL-ATTR| documentation. This section serves as an example of the correct use
 of markup. Refer to our :ref:`rest` to learn more about using
 restructuredText to author your content.

@@ -5,7 +5,7 @@ Tables

 Tables must only be used for information that is either too numerous or too
 related for a list to be appropriate. The smallest acceptable table is 2x2
-not counting the table header. The |CLOSIA| uses special ReStructuredText
+not counting the table header. The |CL-ATTR| uses special ReStructuredText
 markup to make including tables easier. If you plan on adding a table
 consider transforming it into a list before you embark on creating a table.
 Follow these general guidelines:
@@ -4,10 +4,10 @@ Compatible Hardware
 ###################

 This document describes hardware that has been tested and confirmed as
-compatible with |CLOSIA|. This list is not comprehensive and will continue to
+compatible with |CL-ATTR|. This list is not comprehensive and will continue to
 grow.

-.. list-table:: **Table 1. Clear Linux Compatible Hardware**
+.. list-table:: **Table 1. Compatible Hardware**
    :widths: 20, 20
    :header-rows: 1

@@ -1,9 +1,9 @@
 .. _compatible-kernels:

-Compatible Clear Linux\* kernels
-################################
+Compatible kernels
+##################

-The |CLOSIA| provides the following Linux kernels with a respective bundle.
+The |CL-ATTR| provides the following Linux kernels with a respective bundle.
 This document describes the specific use cases these `bundles`_ serve
 and provides links to their source code.

@@ -44,10 +44,10 @@ The *kernel-kvm* bundle focuses on the Linux
 :abbr:`KVM (Kernel-based Virtual Machine)`. It is optimized for fast booting
 and performs best on Virtual Machines running on the Intel® architectures
 described on the :ref:`supported hardware list<system-requirements>`.
-Use this kernel when running |CL| as the guest OS on top of *qemu/kvm*. Use 
-this kernel with **cloud orchestrators** using *qemu/kvm* internally as 
-their **hypervisor**. This kernel can be used as a standalone |CL| VM, see 
-our :ref:`instructions on using KVM<kvm>` for more information. The 
+Use this kernel when running |CL| as the guest OS on top of *qemu/kvm*. Use
+this kernel with **cloud orchestrators** using *qemu/kvm* internally as
+their **hypervisor**. This kernel can be used as a standalone |CL| VM, see
+our :ref:`instructions on using KVM<kvm>` for more information. The
 optimization patches are found in our `Linux-KVM`_ GitHub repo.

 Kernel Hyper-V\*
@@ -58,7 +58,7 @@ Hyper-V. It is optimized for fast booting and performs best on Virtual
 Machines running on the Intel® architectures described on the
 :ref:`supported hardware list<system-requirements>`.
 Use this kernel when running |CL| as the guest OS of **Cloud Instances** in
-projects such as Microsoft `Azure`_\*. This kernel can be used in a 
+projects such as Microsoft `Azure`_\*. This kernel can be used in a
 standalone |CL| VM, see our :ref:`instructions on using Hyper-V<hyper-v>` for
 more information. The optimization patches are found in our `Linux-HyperV`_
 GitHub repo.
@@ -6,7 +6,7 @@ How to Clear training overview
 The existing Linux\* ecosystem can be challenging to users because of long
 intervals between :abbr:`OS (operating system)` updates, which leads to large
 update downloads. Users can also be frustrated when managing complicated
-component dependencies. |CLOSIA| solves these problems by:
+component dependencies. |CL-ATTR| solves these problems by:

 *	Allowing you to update frequently, even multiple times per day
 *	Preventing you from combining incompatible components
@@ -31,7 +31,7 @@ overview of these |CL| mechanisms:
 *   Tools: `mixer-tools` software suite generates the update server content using |CL|
    official software update content, local bundle definitions, and local RPM files.

-The training helps you create a customized OS that is based on |CLOSIA|. The
+The training helps you create a customized OS that is based on |CL|. The
 training content is self-contained and hosted on GitHub. You need a clean
 |CL| installation and a functional network connection to complete the
 training. For convenience, the project includes the training files you need
@@ -35,14 +35,14 @@ Table 2 lists the currently available images that are platform specific.
   * - Image Type
     - Description

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

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

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

 .. list-table:: Table 2: Types of platform-specific |CL| images
   :widths: 15, 85
@@ -70,7 +70,7 @@ Table 2 lists the currently available images that are platform specific.
     - Virtual Hard Disk for use with Microsoft Hyper-V\* hypervisor. Includes `optimized kernel`_ for Hyper-V.

   * - kvm.img
-     - Image for booting in a simple VM with start_qemu.sh. Includes 
+     - Image for booting in a simple VM with start_qemu.sh. Includes
       `optimized kernel`_ for KVM.

   * - vmware.vmdk
@@ -3,11 +3,11 @@
 Reference
 #########

-This section provides additional information on the |CL| project and |CL|
+This section provides additional information on the |CL| project and
 features.

 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1

   compatible-hardware
   bundle-commands
@@ -3,7 +3,7 @@
 Recommended minimum system requirements
 #######################################

-|CL-ATTR| can run on very minimal hardware. For example, it can run on a 
+|CL-ATTR| can run on very minimal hardware. For example, it can run on a
 system with a single core CPU, 128MB of memory, and 600MB of disk space.

 Different use cases and applications will require different configurations.
@@ -12,7 +12,7 @@ minimum requirements include:

 *  Processors:

-   |CL-ATTR| can run on any Intel® 64bit processors which support UEFI\* 
+   |CL-ATTR| can run on any Intel® 64bit processors which support UEFI\*
   and SSE\* v4.1 streaming SIMD\* instructions.

   The following processor families have been verified to run |CL|:
@@ -1,6 +1,6 @@
 .. _aws-web:

-Create and launch Clear Linux from Amazon Web Services
+Create and launch |CL-ATTR| from Amazon Web Services
 ######################################################

 This tutorial walks you through creating and launching a |CL|
@@ -25,14 +25,14 @@ This tutorial assumes the following statements are true:
  directory.
 * You have already set up an AWS user account and logged into the AWS
  console.
-  
+
 .. note::
   This tutorial uses a |CL| AMI t2.micro instance that is eligible for the
   AWS free tier. To learn more about AWS and setting up an account, visit the
   AWS website at http://aws.amazon.com.

-Locate, select, and launch the Clear Linux OS Basic AMI
-*******************************************************
+Locate, select, and launch the |CL| Basic AMI
+*********************************************

 #. Start from your main AWS services console menu in your browser and select the
   :guilabel:`EC2` text as shown in figure 1:
@@ -57,18 +57,18 @@ Locate, select, and launch the Clear Linux OS Basic AMI
   This selection takes you to the
   :guilabel:`Step 1: Choose an Amazon Machine Image (AMI)` menu.

-#. To find the :guilabel:`|CL| OS Basic` AMI in the
+#. To find the :guilabel:`Clear Linux OS Basic` AMI in the
   :guilabel:`Step 1: Choose an Amazon Machine Image (AMI)` menu, do the
   following:
-   
+
   #. In the lefthand navigation window, select the
      :guilabel:`AWS Marketplace` menu item to bring up the search bar to
      :guilabel:`Search AWS Marketplace Products`.

-   #. In the search bar, type `clear linux os` and hit the :kbd:`Enter` key to
-      search for and locate the :guilabel:`|CL| OS Basic` AMI.
+   #. In the search bar, type "clear linux os" and hit the :kbd:`Enter` key to
+      search for and locate the :guilabel:`Clear Linux OS Basic` AMI.

-   #. Select the :guilabel:`|CL| OS Basic` AMI by clicking on the
+   #. Select the :guilabel:`Clear Linux OS Basic` AMI by clicking on the
      :guilabel:`Select` button as shown in figure 3:

      .. figure:: figures/aws-web-3.png
@@ -78,7 +78,7 @@ Locate, select, and launch the Clear Linux OS Basic AMI
         Figure 3: :guilabel:`Step 1: Choose AMI`

   #. A pop-up dialog box appears showing you more information about the
-      :guilabel:`|CL| OS Basic` AMI along with the pricing details for running
+      :guilabel:`Clear Linux OS Basic` AMI along with the pricing details for running
      |CL| on different platform configurations as shown in figure 4. Select
      the :guilabel:`Continue` button.

@@ -129,13 +129,13 @@ Locate, select, and launch the Clear Linux OS Basic AMI
         Figure 7: :guilabel:`Select an existing key pair or create a new pair`

      #. Select the :guilabel:`Create a new key pair` option.
-      
+
      #. For the :guilabel:`Key pair name` field, enter `AWSClearTestKey`.
-      
+
      #. Select the :guilabel:`Download Key Pair` button to download the
         :file:`AWSClearTestKey.pem` to your browser's defined
         :file:`Downloads` directory.
-         
+
      #. When the file finishes downloading, select the
         :guilabel:`Launch Instances` button to proceed to the
         :guilabel:`Launch Status` menu shown in figure 8.
@@ -171,8 +171,8 @@ other instances available, they are also listed but not selected.

 #. To connect to your running instance, click the :guilabel:`Connect` button
   located at the top of your dashboard. AWS brings up the pop-up dialog
-   box shown in figure 11 describing how to connect to your running instance. 
-   
+   box shown in figure 11 describing how to connect to your running instance.
+
 .. _fig-aws-web-11:

 .. figure:: figures/aws-web-11.png
@@ -223,10 +223,10 @@ other instances available, they are also listed but not selected.
   .. code-block:: console

      Warning: Permanently added 'ec2-34-209-39-184.us-west-2.compute.amazonaws.com,34.209.39.184' (ECDSA) to the list of known hosts.
-      clear@clr-96a8565d0ca54b0c80364a1e5e7b0f88 ~ $ 
+      clear@clr-96a8565d0ca54b0c80364a1e5e7b0f88 ~ $

-Update the Clear Linux OS instance
-**********************************
+Update the |CL| instance
+************************

 Run the :command:`sudo swupd update` command to update the operating
 system as shown in figure 12:
@@ -239,8 +239,8 @@ system as shown in figure 12:

 In this example we updated from version 18940 to 19100.

-Stop the Clear Linux OS instance
-********************************
+Stop the |CL| instance
+**********************

 When you are finished using your AWS |CL| instance you need to stop it using
 the :guilabel:`Instances` dashboard to stop accruing charges. Complete the
@@ -1,9 +1,9 @@
 .. _azure:

-Run Clear Linux using Microsoft Azure CLI 2.0
-#############################################
+Run |CL-ATTR| using Microsoft Azure CLI 2.0
+###########################################

-|CLOSIA| is available for you to use in the Microsoft* Azure* marketplace and
+|CL-ATTR| is available for you to use in the Microsoft* Azure* marketplace and
 is offered with three different images, also known as a
 :abbr:`SKU (Stock Keeping Unit)`.

@@ -89,8 +89,8 @@ sysadmin-basic software bundle using the :command:`swupd` command:
   instructions in the `MS Azure Install Azure CLI tutorial`_ for your
   specific operating system.

-Install MS Azure CLI 2.0 on Clear Linux
-***************************************
+Install MS Azure CLI 2.0 on |CL|
+********************************

 #. To install the MS Azure CLI 2.0 on |CL|, use the :command:`curl` command as
   follows:
@@ -335,8 +335,8 @@ of resources within MS Azure.
        "tags": null
      }

-Create and log into the Clear Linux virtual machine
-***************************************************
+Create and log into the |CL| virtual machine
+********************************************

 For this tutorial, we are using the |CL| Basic SKU for our VM.

@@ -467,8 +467,8 @@ For this tutorial, we are using the |CL| Basic SKU for our VM.
   When you are finished using your new |CL| VM, type :command:`exit` to close
   the :command:`SSH` terminal and logout.

-Stop and deallocate the Clear Linux VM and resources
-****************************************************
+Stop and deallocate the |CL| VM and resources
+*********************************************

 When you finish using your new |CL| instance, you must stop the VM and
 deallocate the resources in your resource group. If you only stop a VM, the OS
@@ -516,7 +516,7 @@ Next steps
 To see use cases you can fulfill with your |CL| instance, visit our
 :ref:`tutorials <tutorials>` section.

-For additional information visit the Clear Linux
+For additional information visit the |CL|
 `Azure Partner Mini Case Study`_ and the `Azure Partner Datasheet`_.

 To learn more about the MS Azure CLI 2.0 tool and options that are available,
@@ -1,12 +1,12 @@
 .. _docker:

-Run Docker\* on Clear Linux\*
-#############################
+Run Docker\* on |CL-ATTR|
+#########################

-|CLOSIA| supports multiple containerization platforms, including a Docker\* 
-solution. |CL| has many `unique features`_ including a minimal default 
-installation, which makes it compelling to use as a host for container 
-workloads, management, and orchestration. 
+|CL-ATTR| supports multiple containerization platforms, including a Docker\*
+solution. |CL| has many `unique features`_ including a minimal default
+installation, which makes it compelling to use as a host for container
+workloads, management, and orchestration.

 This tutorial covers:

@@ -14,18 +14,29 @@ This tutorial covers:
   :depth: 1

 .. note::
-   
-   This tutorial focuses on the installaton of the Docker ecosystem. 
+
+   This tutorial focuses on the installaton of the Docker ecosystem.
   If you want to use |CL| as a Docker container image, refer to the
-   official `Clear Linux image on Docker Hub`_ 
-   and `building a custom Clear Linux docker image`_ . 
+   official |CL| container image
+   `published on Docker* Hub <https://hub.docker.com/_/clearlinux/>`_
+   and our guide to :ref:`custom-clear-container`.

 Prerequisites
 *************

-* Basic understanding of Linux and Docker. 
+This tutorial assumes you have installed |CL| on your host system.
+For detailed instructions on installing |CL| on a bare metal system, follow
+the :ref:`bare metal installation instructions<bare-metal-install>`.

-* Successful completion: :ref:`bare-metal-install` 
+Before you install any new packages, update |CL| with the following command:
+
+.. code-block:: bash
+
+   sudo swupd update
+
+Additionally, you should have:
+
+* A basic understanding of Linux and Docker.

 * |CL| environment that has transparent network access to the Internet.
  If you are behind a HTTP proxy server, in a corporate setting for example,
@@ -35,10 +46,10 @@ Install the containers-basic bundle
 ***********************************

 Software in |CL| is offered in the form of `bundles`_ to provide a
-complete function. The *containers-basic* provides all the required software 
-packages to run Docker images as containers.  
+complete function. The *containers-basic* provides all the required software
+packages to run Docker images as containers.

-#. First, install the *containers-basic* bundle by running this 
+#. First, install the *containers-basic* bundle by running this
   :command:`swupd` command:

   .. code-block:: bash
@@ -51,49 +62,49 @@ packages to run Docker images as containers.

      sudo systemctl start docker

-   If you want Docker to start automatically on boot, enable the 
+   If you want Docker to start automatically on boot, enable the
   systemd service by running this command:

   .. code-block:: bash

      sudo systemctl enable docker

-#. Finally, verify :command:`docker` has been installed by running this  
+#. Finally, verify :command:`docker` has been installed by running this
   command and checking the version output for both *client* and *server*:

   .. code-block:: bash

-      sudo docker version 
+      sudo docker version

-Congratulations! At this point, you have a working installation of Docker 
+Congratulations! At this point, you have a working installation of Docker
 on |CL|. You are ready to start using container images on your system.

 Integration with Kata Containers (optional)
 ********************************************

 `Kata Containers`_, is an open source project aiming to increase security
-of containers by using a hardware-backed virtual machine container runtime 
-rather than software namespace containers that are provided by the standard 
+of containers by using a hardware-backed virtual machine container runtime
+rather than software namespace containers that are provided by the standard
 Docker *runc* runtime.

-Clear Linux provides easy integration of the *kata-runtime* with Docker.
+|CL| provides easy integration of the *kata-runtime* with Docker.
 More information on installing and using  the *kata-runtime* may be found at :ref:`kata`.


-.. note:: 
+.. note::

   The proceeding sections of this tutorial are standard to Docker setup
-   and configuration. If you are familiar with Docker basics, you do not 
-   need to continue reading. The following sections are provided here for 
+   and configuration. If you are familiar with Docker basics, you do not
+   need to continue reading. The following sections are provided here for
   sake of completeness.

 Additional Docker configuration
 *******************************

 Perform additional Docker daemon configuration via a configuration file
-typically located at :file:`/etc/docker/daemon.json`. |CL| features a 
+typically located at :file:`/etc/docker/daemon.json`. |CL| features a
 `stateless system`_  so the configuration file :file:`daemon.json` does *NOT*
-exist by default. 
+exist by default.

 #. Create the :file:`daemon.json` by running this command:

@@ -101,34 +112,35 @@ exist by default.

      sudo touch /etc/docker/daemon.json

-   .. note:: 
+   .. note::

-      Refer to the `Docker documentation on daemon configuration`_ for the 
+      Refer to the `Docker documentation on daemon configuration`_ for the
      full list of available configuration options and examples.

-      A minimal configuration would be.
-    .. code-block:: json
-      
-      {
-         "storage-driver": "devicemapper"
-      }
+      A minimal configuration would be:

-#. Once you've made any required changes, be sure to restart the 
+      .. code-block:: json
+
+         {
+            "storage-driver": "devicemapper"
+         }
+
+#. Once you've made any required changes, be sure to restart the
   Docker daemon through systemd manager by running this command:

   .. code-block:: bash

      sudo systemctl restart docker

-Pulling and Running an image from Docker Hub
+Pulling and running an image from Docker Hub
 ********************************************

 `Docker Hub`_ is a publically available container image repository which
-comes preconfigured with Docker. In the example below we will pull and run 
-an the official Docker image for nginx, an open source reverse proxy server. 
+comes preconfigured with Docker. In the example below we will pull and run
+an the official Docker image for nginx, an open source reverse proxy server.

-#. First, pull a container image from Docker Hub using the 
-   :command:`docker pull` command. Download the latest nginx Docker 
+#. First, pull a container image from Docker Hub using the
+   :command:`docker pull` command. Download the latest nginx Docker
   container image by running this command:

   .. code-block:: bash
@@ -143,37 +155,37 @@ an the official Docker image for nginx, an open source reverse proxy server.
      sudo docker run --name test-nginx -d -p 8080:80 nginx

   .. note::
-    
+
      Below is an explanation of switches used in the command above. For
-      detailed :command:`docker run` switches and syntax, refer to the 
+      detailed :command:`docker run` switches and syntax, refer to the
      `Docker Documentation`_ .

      * The *--name* switch lets you provide a friendly name to
        target the container for future operations

      * The *-d* switch launches the container in the background
-        
+
      * The *-p* switch allows the container's HTTP port (80) to be
-        accessible from the Clear Linux host on port 8080
+        accessible from the |CL| host on port 8080

 #. You can access the Welcome to Nginx! splash page running in the container
-   by browsing to http://127.0.0.1:8080 or by running this :command:`curl` 
-   command from your Clear Linux machine:
+   by browsing to \http://127.0.0.1:8080 or by running this :command:`curl`
+   command from your |CL| machine:

   .. code-block:: bash

      curl 127.0.0.1:8080

-#. Finally, stop and delete the nginx container by running the 
+#. Finally, stop and delete the nginx container by running the
   :command:`docker stop` and :command:`docker rm` commands.

   .. code-block:: bash

-      sudo docker stop test-nginx 
+      sudo docker stop test-nginx
      sudo docker rm test-nginx

-Congratulations! At this point, you have successfully pulled a nginx 
-container image from `Docker Hub`_ and have run an example container. 
+Congratulations! At this point, you have successfully pulled a nginx
+container image from `Docker Hub`_ and have run an example container.

 Creating a Docker swarm cluster
 *******************************
@@ -181,30 +193,27 @@ Creating a Docker swarm cluster
 Clusters of Docker hosts are referred to as *swarms*.

 The process in this tutorial can be repeated to install Docker on multiple
-Clear Linux hosts with the intent to form a Docker swarm cluster.
+|CL| hosts with the intent to form a Docker swarm cluster.

-The `Docker documentation on swarm key concepts`_ and 
-`Docker documentation on creating a swarm`_ can be referenced 
+The `Docker documentation on swarm key concepts`_ and
+`Docker documentation on creating a swarm`_ can be referenced
 for further instructions on setting up a swarm.

-Also see:
---------
+Related topics
+**************
+
 * `Docker Home`_
 * `Docker Documentation`_
 * `Docker Hub`_
-* `Kata Containers`_ 
+* `Kata Containers`_

 .. _unique features: https://clearlinux.org/features

-.. _Clear Linux image on Docker Hub: https://hub.docker.com/_/clearlinux/
-
-.. _building a custom Clear Linux docker image: https://clearlinux.org/documentation/clear-linux/guides/network/custom-clear-container
-
 .. _Docker proxy instructions: https://docs.docker.com/config/daemon/systemd/#httphttps-proxy

 .. _bundles: https://clearlinux.org/documentation/clear-linux/concepts/bundles-about#related-concepts

-.. _stateless system: https://clearlinux.org/features/stateless 
+.. _stateless system: https://clearlinux.org/features/stateless

 .. _Docker documentation on daemon configuration: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file

--- a/Show More
+++ b/Show More