Revert "Added Autoproxy guide"

Added Autoproxy guide

.github/ISSUE_TEMPLATE/identify--guides--type-by-role----for-guides-only-.md

@@ -1,20 +0,0 @@
----
-name: Identify 'Guides' Type by Role -- For Guides only.
-about: For new content in 'Guides', select 1 of 3 categories to which it belongs.
-
----
-
-New pages will appear here: https://clearlinux.org/documentation/clear-linux/guides
-
-1. Enter an 'x' in the category for the new "guide": 
-* [ ] Basics
-* [ ] Developer
-* [ ] Administrator
-
-Complete the field below, following the colon, that matches option selected above:
-
-I am a Clear Linux Beginner (Basics). I want to learn how to:  
-
-I am a Clear Linux Developer. I want to learn how to:  
-
-I am a Clear Linux Administrator. I want to learn how to:

.github/ISSUE_TEMPLATE/modify-document.md

@@ -0,0 +1,19 @@
+---
+name: Modify document
+about: Modify a document for the Clear Linux* Project
+
+---
+
+**Describe the error/improvement to an existing document or image**
+Provide a clear and concise description of the error or proposed improvement.
+
+**Screenshots**
+If applicable, add screenshots to help explain the error or unexpected behavior.
+
+**Environment (please complete the following):**
+ - Clear Linux OS version: [`cat /usr/lib/os-release`]
+ - Third-party tool/software: [version]
+ - Command [ [e.g. `sudo -i`]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/new-document.md

@@ -0,0 +1,17 @@
+---
+name: New document
+about: Request a new document for the Clear Linux* project
+
+---
+
+**Do you think Clear Linux documentation needs a new document? Please describe.**
+Please provide a clear and concise description of the title and content. Identify the target audience: Developer; System Administrator; or Basic User.
+
+**Should the new document be a guide, a reference, or a tutorial?**
+Recommend a type of document, based on the structure here: https://clearlinux.org/documentation/clear-linux
+
+**Describe or provide examples of similar documents, if possible, from other web sites**
+Please provide an example of similar documents if possible.
+
+**Additional context**
+Add any other context or screenshots for the document request here.

source/clear-containers/architecture-overview.rst

@@ -1,409 +0,0 @@
-.. _architecture-overview:
-
-Architecture Overview
-#####################
-
-Intel Clear Containers are architected around the Linux
-:abbr:`Kernel Virtual Machine (KVM)` virtualization infrastructure to
-make best use of Intel Architecture VT features. Operational speed
-gets improved and overhead gets reduced by optimizing existing code,
-removing redundant components, and implementing new techniques for
-containers with :abbr:`KVM (Kernel Virtual Machine)`.
-
-The latest release of Intel® Clear Containers is release 3.0. You can find
-detailed technical information on our `architecture overview`_ on GitHub.
-
-Version 1.0 of Clear Containers was designed as a lightweight container
-system based around `kvmtool`_'s ``lkvm``,
-:abbr:`KVM (Kernel Virtual Machine)` and Intel VT-x features; the
-initial version was aimed primarily at Docker\* integration.  Version
-2.0 replaces ``lkvm`` with a lightweight version of
-:abbr:`QEMU (Quick EMUlator)` `(link) <http:www.qemu.org>`_.
-
-Version 2.0 also expands the feature set to include key technologies, such
-as `SR-IOV`_, and the :abbr:`Open Container Initiative (OCI)` runtime API.
-
-V2.0
-====
-
-Intel Clear Containers V2.0 adopts an optimized version of the established
-`QEMU`_ host virtualization engine, in order to support extra features not
-found in Clear Containers V1.0. Clear Containers. V2.0 is also compatible with
-the :abbr:`OCI (Open Container Initiative)` runtime-specification standard,
-introducing a host-side abstraction tool to ease host-side integration and to
-isolate integration instances from future changes to the underlying Clear
-Containers architecture.
-
-.. figure:: ./figures/clear-containers-v2.png
-   :align: center
-   :alt: Clear Containers V2.0
-
-Host kernel optimizations
--------------------------
-
-V2.0 host kernel optimizations are currently the same as
-the V1.0 optimizations.
-
-Host user space
----------------
-
-Host user space is based around an optimized version of `QEMU`_ called
-``qemu-lite``, with an :abbr:`OCI (Open Container Initiative)`
-runtime-compliant wrapper called ``cor``.
-
-Our version of ``qemu-lite`` has the following modifications:
-
-* :abbr:`DAX (Direct Access)` support, **enabling fast and space efficient**
-  file access through zero-copy mapping and multi-container sharing of raw
-  client filesystem images from the host filesystem.
-* **Reduced "slimline" PC model** to reduce startup costs in both `QEMU`_
-  and the client kernel.
-* **Removed need for BIOS**, saving boot time.
-* **No bootloader requirement**, to speed up boot.
-* **Reduced memory footprint** by disabling memory-hungry features that
-  are not required by the client system.
-* **Direct kernel boot**, allowing fast booting by loading the kernel as
-  an uncompressed ELF binary. Although the kernel image is slightly larger
-  than a compressed one, it is faster to read and boot the larger
-  file than it is to uncompress and boot the slightly smaller file.
-* **Added an** :abbr:`OCI (Open Container Initiative)` **runtime-compliant
-  wrapper**, AKA ``cor``, for easier integration with
-  :abbr:`OCI (Open Container Initiative)`-compliant host orchestration systems.
-
-Client mini-OS
---------------
-
-The Client mini-OS is based on the same Clear Linux OS-based system as
-used in Intel Clear Containers V1.0; however, it may be built from more
-recent versions and with more current components, such as the kernel version.
-
-Client customer images
-----------------------
-
-Client customer images are supported in the same manner as they are
-in V1.0.
-
-
-Legacy V1.0
-===========
-
-V1.0 (also known as **Intel® Clear Containers for Docker Engine**) is based
-around `kvmtool`_, with example host integrations for Docker and `rkt`_.
-
-.. figure:: ./figures/clear-containers-v1.png
-   :align: center
-   :alt: Intel Clear Containers V1.0
-
-
-Host kernel optimizations
--------------------------
-
-Intel Clear Containers operate better when a number of host kernel features and
-optimizations are applied:
-
-* Enabling :abbr:`Kernel Samepage Merging (KSM)` in the host kernel
-  is recommended for efficient page sharing of VM pages. Kernel documentation
-  can be found in Documentation/vm/ksm.txt  Config symbol: ``CONFIG_KSM``
-* Using a kernel version >= v4.0 (or backporting appropriate
-  patches if your kernel version is less than v4.0), to get the best
-  :abbr:`KVM (Kernel Virtual Machine)` VM startup times
-
-  .. note::
-
-     Intel :abbr:`Extended Page Table (EPT)` acceleration will be
-     automatically detected and used by your host kernel if supported
-     by your hardware. You can check whether this feature is present by
-     looking for the ``ept`` string in the :file:`/proc/cpuinfo` of your
-     system. See `mmu.txt`_ for more details.
-
-
-Host user space
----------------
-
-Intel Clear Containers V1.0 host user space is based around `kvmtool`_ as a
-fast and lightweight hypervisor. Optimizations to `kvmtool`_ include:
-
-* **File access**, enabling efficient *shmem* / *pci-bar* / :abbr:`Direct
-  Access (DAX)` file access to client.
-* **Less verbosity**.
-* **Minimal UART scanning** to improve speed.
-* **TSC timer functionality changes** passing the client apic timer
-  calibration step speeds up container creation time.
-* Adding ability to **skip unused features**, (such as creation of a
-  custom rootfs).
-* **Removing need for BIOS** saves boot time.
-* **No bootloader required** speeds up initial booting of a machine.
-* **Direct kernel boot** -- The hypervisor can boot the kernel directly as
-  an uncompressed ELF binary. Although the kernel image is slightly larger
-  than a compressed one, it is faster to read and boot the larger
-  file than it is to uncompress and boot the slightly smaller file.
-
-
-Client mini-OS
---------------
-
-Intel Clear Containers V1.0 uses an optimized client user space (mini-OS) as
-its primary launch vehicle to execute workload commands. The mini-OS is built
-with a Clear Linux distribution that has an optimized configuration for time
-and space efficiency. The mini-OS includes:
-
-* Minimized ``systemd`` configuration
-* Optimized ``libc``
-* Custom AutoFDO settings
-* Optimized multi-lib runtime support
-* Optimized kernel config (speed and size)
-
-The mini-OS configuration can be modified and rebuilt by customers for their
-own use cases, which may preclude the need to load further client images.
-
-
-Client customer images
-----------------------
-
-Intel Clear Containers V1.0 mini-OS workloads can be used to bootstrap further
-customer images. These customer images would generally be mapped into the
-client via the host filesystem using :abbr:`9p (Plan 9 9p remote filesystem
-protocol)`, :abbr:`DAX (Direct Access)` or other filesystem and virtual
-device interfaces. These customer images could, for example:
-
-* Mount a new subtree containing a payload and execute it.
-* Mount a new subsystem and chroot to it for contained execution.
-
-The mini-OS image has been optimized for size and speed. It may be replaced
-or superseded -- in whole or in part -- by customer-created images.  Keep
-in mind, of course, that any benefits the mini-OS provides may be lost
-unless equivalent optimizations exist in the customer-created image, or have
-been migrated into the image they create.
-
-
-Architectural component details
-===============================
-
-Host kernel components
-----------------------
-
-:abbr:`Kernel SamePage Merging (KSM)`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Linux Kernel Documentation: Documentation/vm/ksm.txt
-
-:abbr:`KSM (Kernel Samepage Merging)` allows the kernel to locate
-and merge (share) identical memory pages within the system, even
-when they are not sourced from the same binary. When sourced from
-the same binary, the kernel will naturally share through the
-:abbr:`copy-on-write (COW)` method.
-
-:abbr:`KSM (Kernel Samepage Merging)` also allows the kernel to
-localize and to coalesce pages from within virtual machine memory
-spaces that would not normally be shared, thus saving memory space.
-
-To enable :abbr:`KSM (Kernel Samepage Merging)`, check that your host kernel
-config includes ``CONFIG_KSM``, and that your host system is running the
-``ksmd`` daemon.
-
-:abbr:`EPT (Extended Page Tables)`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Linux Kernel Documentation: Documentation/virtual/kvm/mmu.txt
-
-:abbr:`EPT (Extended Page Tables)` is an acceleration technology for virtual
-machine memory mappings. It reduces the number of Virtual Machine Manager
-entry/exits from the host system, thus improving system performance. If your
-hardware system supports :abbr:`EPT (Extended Page Tables)`, you'll see the
-``ept`` feature listed in the ``/proc/cpuinfo`` information from your system.
-The kernel, :abbr:`KVM (Kernel Virtual Machine)` and `QEMU`_ will
-automatically use and benefit from :abbr:`EPT (Extended Page Tables)`
-when supported by your system hardware.
-
-You can also check on the `Intel ARK website`_ to see if your Intel CPU
-supports **Intel VT-x with Extended Page Tables**; check under the
-*Advanced Technologies* table on the specific page for your CPU.
-
-:abbr:`KVM (Kernel Virtual Machine)` startup optimizations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Host kernel startup was optimized before the Linux kernel v4.0
-release by removing some unnecessary ``synchronize_rcu()`` calls. You
-should ensure your kernel is at least v4.0, or that you have backported
-any appropriate patches to your host kernel:  the ``synchronize_rcu() opt``,
-at the very least.
-
-.. We should add a Persistent data (how do we do that on R/O or COW'd
-  filesystems for instance?
-  [do we have a standard pattern to do for these docs?]
-  Persistence
-  ~~~~~~~~~~~
-
-
-Host tooling
-------------
-
-Kvmtool
-~~~~~~~
-
-Kvmtool is used in Intel Clear Containers V1.0 for virtual machine
-configuration and management. It was chosen because it is lighter
-and faster than the alternatives, and it's also easy to modify.
-
-Modifications to `kvmtool`_ include:
-
-* Implementation of **copy-free** :abbr:`DAX (Direct Access)` **file-system
-  access**.
-* **Less verbosity**.
-* **Minimal UART scanning** to improve speed.
-* **TSC timer functionality changes** passing the client apic timer
-  calibration step speeds up container creation time.
-* Adding ability to **skip unused features**, (such as creation of a
-  custom rootfs).
-* **Removing need for BIOS** saves boot time.
-* **No bootloader required** speeds up initial booting of a machine.
-* **Direct kernel boot** -- The hypervisor can boot the kernel directly as
-  an uncompressed ELF binary. Although the kernel image is slightly larger
-  than a compressed one, it ends up being faster to read and boot the larger
-  file than it is to uncompress and boot the slightly smaller file.
-
-
-.. _qemu-lite:
-
-qemu-lite
-~~~~~~~~~
-
-``qemu-lite`` is a modified version of `QEMU`_ used for the virtual
-machine configuration and management in Intel Clear Containers 2.0.
-
-The modifications made beyond generic `QEMU`_ are described in the
-following sections:
-
-:abbr:`DAX (Direct Access)` enablement
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-:abbr:`DAX (Direct Access)` enablement under ``qemu-lite`` utilizes
-existing `QEMU`_ ``nvdimm memdev`` functionality.
-
-PC-lite
-^^^^^^^
-
-A new `QEMU`_ PC model, called ‘pc-lite’, has been added that removes
-all unused or unnecessary PC style elements from the machine emulation
-that are not required for the client VM. This improves both speed of
-execution and memory footprint.
-
-Cor
-^^^
-
-Cor (the Clear :abbr:`OCI (Open Container Initiative)` runtime manager)
-implements the :abbr:`OCI (Open Container Initiative)` runtime specification
-atop of the V2.0 infrastructure (such as ``qemu-lite``). By
-utilizing Cor, your :abbr:`OCI (Open Container Initiative)`-compliant system
-can be implemented with Clear Containers whilst also insulating
-the user against any future underlying changes in Clear Containers,
-thus allowing easier future integration of upgrades. Cor currently
-supports :abbr:`OCI (Open Container Initiative)` runtime version 0.6.0.
-
-Client components
-~~~~~~~~~~~~~~~~~
-
-The client-side components consist of the mini-OS kernel and root
-filesystem, and optionally further customer specific items, such as
-a further fuller distribution or system to load. The intention is
-that customers may either extend and expand the mini-OS as required,
-or they can use the mini-OS to further load a complete self-contained
-image of their choice.
-
-Client mini-OS
-^^^^^^^^^^^^^^
-
-The mini-OS is an optimized version of Clear Linux OS for Intel Architecture
-which has been designed for the fastest and smallest container boot. The
-mini-OS consists of a Linux kernel image and root filesystem image.
-
-* **Kernel** -- The mini-OS's kernel is a Clear Linux kernel containing
-  the minimum feature set required to boot the client container. The kernel
-  has optimized for space and speed. This kernel can be modified and
-  re-built as desired, for specific requirements.
-
-* **DAX** -- The :abbr:`Direct Access (DAX)` filesystem.
-  (Linux Kernel Documentation: ``Documentation/filesystems/dax.txt``).
-  Mapping host-side files into the memory map of the client allows the use of
-  :abbr:`DAX (Direct Access)` to directly mount those files, bypassing the
-  client side page cache and the virtual device mechanisms between host and
-  client. This allows efficient zero-copy mapping and replaces costly virtual
-  device manipulations with efficient page fault handling, thus being faster
-  and more space-efficient than other filesystem mount methods. :abbr:`DAX
-  (Direct Access)` is enabled in Intel Clear Containers V1.0 using a shmem
-  PCI-BAR mechanism configured by `kvmtool`_.
-
-  .. figure:: ./figures/dax-v1.png
-    :align: center
-
-  :abbr:`DAX (Direct Access)` is enabled in Intel Clear Containers
-  V2.0 using an   NVDIMM `QEMU`_ memdev mechanism:
-
-   .. figure:: ./figures/dax-v2.png
-      :align: center
-
-  :abbr:`DAX (Direct Access)` can only be used to mount single flat files
-  from the host side (such as uncompressed filesystems), and not trees of
-  files in the host filesystem. More than one :abbr:`DAX (Direct Access)`
-  mount can be utilized though. :abbr:`DAX (Direct Access)` is limited only
-  by the virtual address space available, so it can easily accommodate large
-  file mappings.
-
-  :abbr:`DAX (Direct Access)` support was introduced in v4.0 of the kernel.
-  Also see the `qemu-lite`_ section.
-
-* **Rootfs image** -- The mini-OS rootfs image is a Clear Linux
-  rootfs. It can execute the client workload and be modified and
-  extended using the bundle method to enable further features as
-  necessary. It can also be used to further execute another client
-  container image, such as a different Linux distribution.
-
-
-Customer Client images and workloads
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Customers may use their own client images by instructing
-the mini-OS to execute them using the mini-OS workload. Please
-refer to the :ref:`Intel Clear Containers integration
-guide<cc-getting-started>` for further detail.
-
-.. removed this section since it is in the GSG
-
-FAQ
-===
-
-**Q.** "Can I run Clear Containers on any host Linux?"
-
-**A.** Yes, any up-to-date or recent Linux host should be able to run Clear
-   Containers, as long as the host system kernel contains the necessary
-   features and is configured with the necessary support enabled.
-
-..   [to do: finish this section]
-
-**Q.** "Do I need to use all of Clear Containers, or can I cherry pick parts?"
-
-**A.** You can cherry pick the parts of Clear Containers you need. Some parts
-   will make your life generally easier (such as the `QEMU`_ wrapper tool
-   ``cor``) and will help insulate you from future development changes, so you
-   should consider which parts you need for which features. The client
-   side obviously can be quite flexible in its configuration depending
-   on the deployment environment.
-
-**Q.** "Can I use Clear Containers technology to run other VMs, not just
-   container style ones?"
-
-**A.** Yes, the underlying mechanisms and accelerations used for Clear
-   Containers can be applied to any Virtual Machine setup, not just
-   those that are based around a container style workflow.
-
-
-.. _SR-IOV: http://www.intel.com/content/www/us/en/pci-express/pci-sig-sr-iov-primer-sr-iov-technology-paper.html
-.. _QEMU: http://www.qemu.org
-.. _mmu.txt:
-   https://www.kernel.org/doc/Documentation/virtual/kvm/mmu.txt
-
-.. _Intel ARK website: http://ark.intel.com
-.. _kvmtool: https://git.kernel.org/cgit/linux/kernel/git/will/kvmtool.git/
-.. _rkt: https://coreos.com/rkt/
-.. _architecture overview:
-   https://github.com/clearcontainers/runtime/blob/master/docs/architecture/architecture.md

source/clear-containers/clear-containers.rst

@@ -1,29 +0,0 @@
-.. _clear-containers.rst:
-
-Intel® Clear Containers
-#######################
-
-Intel® Clear Containers is a collection of tools, configurations,
-and techniques anchored on an implementation that leverages Intel®
-Architecture to optimize container launching and execution workflow.
-These optimizations improve speed, size, and efficiency while offering
-a number of benefits that can be derived only from hardware-backed
-virtual machines (hardware-enforced isolation and security, for
-example) on Intel® VT technology.
-
-These methods are applied across all levels of the host/virtual machine
-hierarchy: from the host-side userland software stack down through the host
-Linux\* kernel, and into the client-side kernel and userland.
-
-Although it is available as a standalone offering, the Clear Containers
-technology works best when it is able to leverage optimizations designed
-into the Clear Linux Project.
-
-Customers can integrate all or parts of Intel Clear Containers into a
-container infrastructure.
-
-.. toctree::
-    :maxdepth: 2
-
-    getting-started
-    architecture-overview

source/clear-containers/getting-started.rst

@@ -1,38 +0,0 @@
-.. _cc-getting-started:
-
-Clear Containers getting started guide
-######################################
-
-The Intel® Clear Containers enable executing existing Docker applications in
-the secure and fast Intel Clear Containers environment under Docker\*
-v17.05.0-ce and beyond via an :abbr:`Open Container Initiative (OCI)`
-compatible `runtime`.
-
-Visit our `architecture overview`_ for detailed architectural
-information.
-
-Installation instructions
-=========================
-
-The primary host platform is Clear Linux\* Project for Intel® Architecture.
-For instructions on installing Docker and Clear Containers under Clear Linux,
-please refer to instructions from the runtime source tree:
-
-	•	https://github.com/clearcontainers/runtime/wiki/Installation
-
-If you have any feedback, questions, or would like to participate and
-contribute, then  please consult the contact details (mailing list, IRC etc.)
-in the document at:
-
-- https://github.com/clearcontainers/runtime/CONTRIBUTING.md
-
-Source Code
-===========
-
-The source code for the Clear Containers 2.0 runtime and corresponding
-qemu-lite are publicly hosted on github:
-
-- https://github.com/clearcontainers/runtime/
-
-.. _architecture overview:
-   https://github.com/clearcontainers/runtime/blob/master/docs/architecture/architecture.md

source/clear-linux/clear-linux.rst

@@ -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::

source/clear-linux/concepts/autospec-about.rst

@@ -1,112 +1,107 @@
-.. _autospec-about: 
+.. _autospec-about:
 
 Autospec
 ########
 
-.. _incl-autospec-overview:
-
-Overview
-********
-
-Whereas a standard RPM build process using ``rpmbuild`` requires a tarball 
-and ``spec`` file to start, ``autospec`` only requires a tarball and package
-name. ``autospec`` analyzes the source code and :file:`Makefile` information 
-in order to generate a ``spec`` file for you. Although not required, you can 
-influence ``autospec`` by providing control files. 
-
-.. code-block:: console 
-
-   buildreq_add
-   buildreq__ban
-   pkgconfig_add
-   pkgconfig_ban
-   requires_add
-   requires_ban
-   options.conf
-   build_pattern
-
-These files should be located in same directory as the resulting ``spec`` 
-file. 
-
-.. note:: 
-
-   For a comprehensive list of control files, view the `autospec readme`_.  
-
-.. _incl-autospec-overview-end:
-
-Control files are explained in Table 1.
-
-.. list-table:: **Table 1. Control Files**
-   :widths: 20 80
-   :header-rows: 1
-   
-   * - Filename
-     - Description
-   * - buildreq_add
-     - Each line in the file provides the name of a package to add as a
-       build dependency to the ``spec``.
-   * - buildreq_ban
-     - Each line in the file is a build dependency that under no
-       circumstance should be automatically added to the build dependencies. 
-       This is useful to block automatic configuration routines adding 
-       undesired functionality, or to omit any automatically discovered 
-       dependencies during tarball scanning.
-   * - pkgconfig_add
-     - Each line in the file is assumed to be a pkgconfig() build
-       dependency. Add the pkg-config names here, as ``autospec`` will 
-       automatically transform the names into their ``pkgconfig($name)`` 
-       style when generating the ``spec``.
-   * - pkgconfig_ban
-     - Each line in this file is a pkgconfig() build dependency that should
-       not be added automatically to the build, much the same as 
-       `` buildreq_ban``. As with ``pkgconfig_add``, these names are 
-       automatically transformed by ``autospec`` into their correct 
-       ``pkgconfig($name))`` style.   
-   * - requires_add
-     - Each line in the file provides the name of a package to add as a
-       runtime dependency to the ``spec``.    
-   * - requires_ban
-     - Each line in the file is a runtime dependency that under no
-       circumstance should be automatically added to the runtime 
-       dependencies. This is useful to block automatic configuration 
-       routines adding undesired functionality, or to omit any automatically 
-       discovered dependencies during tarball scanning.
-   * - build_pattern
-     - In certain situations, the automatically detected build pattern may
-       not work for the given package. This one line file allows you to 
-       override the build pattern that ``autospec`` will use.
-   * - options.conf 
-     - Further control of the build can be achieved through the use of the
-       ``options.conf`` file. If this file does not exist it is created by
-       autospec with default values. If certain deprecated configuration 
-       files exists autospec will use the value indicated by those files and
-       remove them. 
+``autospec`` is a tool to assist in the automated creation and maintenance of
+RPM packaging in |CL-ATTR|. Where a standard RPM build process using ``rpmbuild``
+requires a tarball and .spec file to start, ``autospec`` requires only a tarball
+and package name to start.
 
 How autospec works
 ******************
 
-Autospec attempts to infer the requirements of the ``spec`` file. If 
-autospec infers correctly, the control files (Table 1) will automatically 
-correct the build requirements. The control files are used to influence
-the ``spec`` file generation. 
+``autospec`` attempts to infer the requirements of the .spec file by analyzing
+the source code and :file:`Makefile` information. It will continuously run
+updated builds based on new information discovered from build failures until it
+has a complete and valid .spec file. Although not required, you can influence
+the behavior of ``autospec`` by providing :ref:`control files <control-files>`.
 
-#. The :command:`make autospec` command generates a ``spec`` file from the 
-   control files.  
+The basic process is described in the following steps:
 
-#. ``autospec`` creates a ``build root`` with ``mock`` config. 
-   
-#. ``autospec`` attempts to build an RPM from the generated ``spec`` file.
-   
-#. ``autospec`` detects any missed declarations in the ``spec`` file. 
+#. The :command:`make autospec` command generates a .spec based on
+   analysis of code and control files, if present.
 
-.. note:: 
+#. ``autospec`` creates a ``build root`` with ``mock`` config.
 
-   * If there are missed declarations, ``autospec`` creates another ``mock``
-     ``chroot`` and starts building again at Step 1. 
-   * If a build error occurs, ``autospec`` stops for user inspection. 
-   * If no build errors occur, RPM packages are successfully built.       
+#. ``autospec`` attempts to build an RPM from the generated .spec.
 
-``autospec`` continues to rebuild the package, based on new information 
-discovered from build failures until it has a valid ``spec`` file. 
+#. ``autospec`` detects any missed declarations in the .spec.
+
+#. If build errors occur, ``autospec`` will scan the build log to try and detect
+   the root cause.
+
+#. If ``autospec`` detects the root cause and knows how to continue, it will restart the build
+   automatically at step 1 with updated build instructions.
+
+#. Otherwise, ``autospec`` will stop the build for user inspection and editing of control files
+   to resolve the errors. The user resumes the process at step 1 after errors are resolved.
+
+Following these steps, ``autospec`` continues to rebuild the package, based on
+new information discovered from build failures, until it has a valid .spec. If
+no build errors occur, RPM packages are successfully built.
+
+.. _control-files:
+
+Control files
+*************
+
+It is possible to influence the behavior of ``autospec`` by providing control
+files. These files may be used to alter the default behavior of the configure
+routine, to blacklist build dependencies, etc. Control files must be located
+in the same directory as the resulting .spec.
+
+Table 1 shows control files used to control dependencies, for example.
+
+.. list-table:: **Table 1. Control files to control dependencies**
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Filename
+     - Description
+   * - buildreq_add
+     - Each line in the file provides the name of a package to add as a
+       build dependency to the .spec.
+   * - buildreq_ban
+     - Each line in the file is a build dependency that under no
+       circumstance should be automatically added to the build dependencies.
+       This is useful to block automatic configuration routines adding
+       undesired functionality, or to omit any automatically discovered
+       dependencies during tarball scanning.
+   * - pkgconfig_add
+     - Each line in the file is assumed to be a pkgconfig() build
+       dependency. Add the pkg-config names here, as ``autospec`` will
+       automatically transform the names into their ``pkgconfig($name)``
+       style when generating the .spec.
+   * - pkgconfig_ban
+     - Each line in this file is a pkgconfig() build dependency that should
+       not be added automatically to the build, much the same as
+       `` buildreq_ban``. As with ``pkgconfig_add``, these names are
+       automatically transformed by ``autospec`` into their correct
+       ``pkgconfig($name))`` style.
+   * - requires_add
+     - Each line in the file provides the name of a package to add as a
+       runtime dependency to the .spec.
+   * - requires_ban
+     - Each line in the file is a runtime dependency that under no
+       circumstance should be automatically added to the runtime
+       dependencies. This is useful to block automatic configuration
+       routines adding undesired functionality, or to omit any automatically
+       discovered dependencies during tarball scanning.
+
+Further control of the build can be achieved through the use of the
+``options.conf`` file. If this file does not exist, it is created by
+``autospec`` with default values. If certain deprecated configuration
+files exists ``autospec`` will use the value indicated by those files and
+remove them.
+
+For a comprehensive list of control files, view the `autospec readme`_.
+
+Related topics
+**************
+
+* :ref:`autospec`
+* :ref:`mixer`
+* :ref:`mixin`
 
 .. _autospec readme: https://github.com/clearlinux/autospec

source/clear-linux/concepts/concepts.rst

@@ -3,9 +3,8 @@
 Concepts
 ########
 
-The concepts section provides content for a deeper understanding of the
-features of |CLOSIA|. These concepts attempt to provide all the technical
-details relevant to the |CL| features.
+|CL-ATTR| does things differently than other Linux distributions. Use the concepts section to learn in detail about the features that make |CL|
+different.
 
 .. toctree::
    :maxdepth: 2

source/clear-linux/concepts/security.rst

@@ -1,6 +1,6 @@
 .. _security:
 
-|CL-ATTR| OS Security 
+OS Security 
 *************************
 
 |CL-ATTR| aims to make systemic and layered security-conscious decisions
@@ -9,7 +9,7 @@ within the project's codebase and operating culture.
 
 
 .. contents:: :local:
-   :depth: 2
+   :depth: 1
 
 
 

source/clear-linux/get-started/bare-metal-install/bare-metal-install.rst

@@ -1,29 +1,32 @@
 .. _bare-metal-install:
 
-Install Clear Linux OS on bare metal (automatic)
-################################################
+Install |CL-ATTR| on bare metal (automatic)
+###########################################
 
-These instructions guide you through the installation of |CLOSIA|
+These instructions guide you through the installation of |CL-ATTR|
 on bare metal using a bootable USB drive.
 
-Before you begin, run our :ref:`compatibility-check`.
+Before you begin, check that your system meets the requirements to install |CL|: 
+
+* :ref:`system-requirements` 
+* :ref:`compatibility-check`
 
 
-Download the latest Clear Linux installer image
-***********************************************
+Download the latest |CL| installer image
+****************************************
 
 Get the latest |CL| installer image from the `image`_ directory.
 Look for the :file:`clear-[version number]-installer.img.xz` file. You can also use this command:
 
 .. code-block:: bash
    
-   curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-installer.img.xz
+   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 uncompress the file.
+Once you have downloaded the image, verify and decompress the file.
 
-.. include:: ../../guides/maintenance/download-verify-uncompress-linux.rst
-   :Start-after: verify-linux:
-   :end-before: To uncompress a GZ
+.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst
+   :Start-after: incl-decompress-image:
+   :end-before: incl-decompress-image-end:
 
 .. include:: ../bootable-usb/bootable-usb-linux.rst
    :Start-after: copy-usb-linux:
@@ -31,8 +34,8 @@ Once you have downloaded the image, verify and uncompress the file.
 
 .. _install-on-target:
 
-Install Clear Linux on your target system
-*****************************************
+Install |CL| on your target system
+**********************************
 
 We formatted the previously created USB drive as a UEFI boot device. Our
 target system has a hard drive installed containing a single primary
@@ -54,25 +57,24 @@ Follow these steps to install |CL| on the target system:
 
 #. Reboot the target system.
 
-#. The |CL| Installer menu will start as shown in Figure 1.
+#. The |CL| boot menu will start as shown in figure 1.
    Select :guilabel:`Clear Linux OS for Intel Architecture` and press the
    :kbd:`Enter` key or wait five seconds to automatically select it.
 
    .. figure:: figures/bare-metal-install-1.png
       :scale: 50 %
-      :alt: Clear Linux boot menu
+      :alt: Boot menu
 
-      Figure 1: :guilabel:`Clear Linux boot menu`
+      Figure 1: :guilabel:`Boot menu`
 
-#. This will take you into the :guilabel:`Clear Linux OS for Intel
-   Architecture Installer` menu as shown in figure 2 and explains how to
+#. This will take you into the |CL| installer menu as shown in figure 2 and explains how to
    navigate through the |CL| installer setup menus.
 
    .. figure:: figures/bare-metal-install-2.png
       :scale: 50 %
-      :alt: Clear Linux OS for Intel Architecture Installer
+      :alt: Installer menu
 
-      Figure 2: :guilabel:`Clear Linux OS for Intel Architecture Installer`
+      Figure 2: :guilabel:`Installer menu`
 
    Press the :kbd:`Enter` key.
 
@@ -97,7 +99,7 @@ The :guilabel:`Network Requirements` menu, the first step of the |CL|
 installer setup process, will attempt to connect to the |CL| update server
 where the installer image is located. Once the connection to the |CL| update
 server is established, you will see a screen similar to the one shown in
-figure 4:
+figure 4.
 
 .. figure:: figures/bare-metal-install-4.png
    :scale: 50 %
@@ -134,11 +136,11 @@ Once the connection to the |CL| udpate server is established, use the
 :kbd:`Tab` key to advance to the :guilabel:`< Next >` button and press
 :kbd:`Enter` to advance to the next |CL| installer setup menu.
 
-Choose Clear Linux installer action
-===================================
+Choose |CL| installer action
+============================
 
 The :guilabel:`Choose Action` menu is where you can choose to install, repair,
-open a shell, or exit the |CL| installer.  This menu is shown in figure 5:
+open a shell, or exit the |CL| installer.  This menu is shown in figure 5.
 
 .. figure:: figures/bare-metal-install-5.png
    :scale: 50 %
@@ -181,8 +183,8 @@ open a shell, or exit the |CL| installer.  This menu is shown in figure 5:
    information is collected. Please visit our website to
    `learn more about telemetry.`_
 
-Choose Clear Linux installation type
-************************************
+Choose |CL| installation type
+*****************************
 
 Figure 7 shows the next step of the |CL| installer:
 :guilabel:`Choose installation Type`. Chose whether to install |CL|
@@ -216,8 +218,8 @@ If you want to perform any of these additional tasks, select the
 :ref:`bare-metal-manual-install` to complete the |CL| manual installation
 process. Otherwise, you can follow the |CL| automatic installation steps.
 
-Clear Linux automatic installation
-**********************************
+|CL| automatic installation
+***************************
 
 #. To install the minimum components for your |CL| implementation, select the
    :guilabel:`< Automatic >` menu item shown in figure 7 and press the
@@ -279,7 +281,7 @@ Set up your root account
 ========================
 
 Once the |CL| installation is complete and the system boots, a full screen
-console requests your login: as shown in figure 12:
+console requests your login as shown in figure 12:
 
 .. figure:: figures/bare-metal-install-12.png
    :scale: 50 %
@@ -300,18 +302,15 @@ You have now set your root password and are logged in with root privileges.
 You have successfully installed |CL| on a bare metal system using the
 automatic installation method and set the password for the ``root`` user.
 
-The automatic installation of |CL| is designed to install with minimal
-software overhead. Therefore, some housekeeping and package installations
-could be needed before you can take full advantage of the |CL| operating
-system. These instructions are captured in the :ref:`enable-user-space`.
+Next steps
+**********
 
-* Create a new user
-* Update the OS to its most current version using `swupd`.
-* Install the most common applications for system administrators and
-  developers using bundles.
-* Setup a new user.
-* Setup `sudo` privileges for that new user.
-* Install a GUI using those `sudo` privileges.
+The automatic installation of |CL| is designed to install with minimal
+software overhead. Some housekeeping and package installations could be 
+needed before you can take full advantage of the |CL| operating system. 
+
+See the :ref:`enable-user-space` guide for additional information and
+instructions.
 
 
 .. _`information about stateless`:
@@ -323,4 +322,4 @@ system. These instructions are captured in the :ref:`enable-user-space`.
 .. _`NUC6i5SYH product page`:
    http://www.intel.com/content/www/us/en/nuc/nuc-kit-nuc6i5syh.html
 
-.. _image: https://download.clearlinux.org/image
+.. _image: https://download.clearlinux.org/image

source/clear-linux/get-started/bare-metal-manual-install/bare-metal-manual-install.rst

@@ -89,7 +89,7 @@ to install |CL| onto.
 
       Figure 4: :guilabel:`Device installation warning`
 
-.. _Additional_manual_installer_settings:
+.. _incl-additional-manual-installer-settings:
 
 Additional manual installer settings
 ====================================
@@ -183,6 +183,8 @@ For a complete description of the content of these additional bundles, go to
 the :ref:`software bundle list <bundles>` and select the name for a
 specific bundle to show the contents within the bundle.
 
+.. _incl-additional-manual-installer-settings-end:
+
 Target system network configuration
 ===================================
 

source/clear-linux/get-started/bootable-usb/bootable-usb-linux.rst

@@ -1,9 +1,9 @@
 .. _bootable-usb-linux:
 
-Create a bootable USB drive on Linux
-####################################
+Create a bootable USB drive on Linux\*
+######################################
 
-Follow these instructions to create a bootable |CLOSIA| USB drive.
+Follow these instructions to create a bootable |CL-ATTR| USB drive.
 Use an **8GB** or larger USB drive. Download either a live image, 
 ``clear-<version>-live.img.xz`` or an installer image, 
 ``clear-<version>-installer.img.xz``, from our `image`_ download page. 
@@ -17,13 +17,13 @@ Instructions are also available for other operating systems:
    :start-after: incl-image-filename: 
    :end-before: incl-image-filename-end:
 
-.. include:: ../../guides/maintenance/download-verify-uncompress-linux.rst
+.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst
    :Start-after: verify-linux:
 
 .. _copy-usb-linux:
 
-Burn the Clear Linux image onto a USB drive
-*******************************************
+Burn the |CL| image onto a USB drive
+************************************
 
 .. caution::
 
@@ -35,7 +35,7 @@ Burn the Clear Linux image onto a USB drive
 
       sudo -s
 
-#. Go to the directory with the uncompressed image.
+#. 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

source/clear-linux/get-started/bootable-usb/bootable-usb-mac.rst

@@ -3,7 +3,7 @@
 Create a bootable USB drive on macOS
 ####################################
 
-Follow these instructions to create a bootable |CLOSIA| USB drive.
+Follow these instructions to create a bootable |CL-ATTR| USB drive.
 Use an **8GB** or larger USB drive. Download either a live image, 
 ``clear-<version>-live.img.xz`` or an installer image, 
 ``clear-<version>-installer.img.xz``, from our `image`_ download page. 
@@ -17,25 +17,25 @@ Instructions are also available for other operating systems:
    :start-after: incl-image-filename: 
    :end-before: incl-image-filename-end:
 
-.. include:: ../../guides/maintenance/download-verify-uncompress-mac.rst
+.. include:: ../../guides/maintenance/download-verify-decompress-mac.rst
    :start-after: verify-mac:
 
 
-Burn the Clear Linux image onto a USB drive
-*******************************************
+Burn the |CL| image onto a USB drive
+************************************
 
 .. caution::
 
    |CAUTION-BACKUP-USB|
 
 #. Launch the Terminal app.
-#. Go to the directory with the uncompressed image.
+#. 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
+      diskutil list
 
    .. figure:: figures/bootable-usb-mac-1.png
       :scale: 100 %
@@ -48,14 +48,14 @@ Burn the Clear Linux image onto a USB drive
 
    .. code-block:: console
 
-      $ diskutil umountDisk /dev/disk2
+      diskutil umountDisk /dev/disk2
 
 #. Burn the image onto the drive using the :command:`dd` command.  The 
    command-line example below burns an uncompressed image onto `/dev/disk2`:
 
    .. code-block:: console
 
-      $ sudo dd if=./clear-[version number]-[image type] of=/dev/rdisk2 bs=4m
+      sudo dd if=./clear-[version number]-[image type] of=/dev/rdisk2 bs=4m
 
 
    Adding an ‘r’ in front of the disk identifier should help speed up the 
@@ -67,7 +67,7 @@ Burn the Clear Linux image onto a USB drive
 
    .. code-block:: console
 
-      $ diskutil eject /dev/disk2
+      diskutil eject /dev/disk2
 
 Next steps
 **********

source/clear-linux/get-started/bootable-usb/bootable-usb-windows.rst

@@ -1,9 +1,9 @@
 .. _bootable-usb-windows:
 
-Create a bootable USB drive on Windows
-######################################
+Create a bootable USB drive on Windows\*
+########################################
 
-Follow these instructions to create a bootable |CLOSIA| USB drive.
+Follow these instructions to create a bootable |CL-ATTR| USB drive.
 Use an **8GB** or larger USB drive. Download either a live image, 
 ``clear-<version>-live.img.xz`` or an installer image, 
 ``clear-<version>-installer.img.xz``, from our `image`_ download page.
@@ -17,11 +17,11 @@ Instructions are also available for other operating systems:
    :start-after: incl-image-filename: 
    :end-before: incl-image-filename-end:
 
-.. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst
+.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst
    :Start-after: verify-windows:
 
-Burn the Clear Linux image onto a USB drive
-*******************************************
+Burn the |CL| image onto a USB drive
+************************************
 
 .. caution::
 

source/clear-linux/get-started/bootable-usb/bootable-usb.rst

@@ -1,23 +1,23 @@
 .. _bootable-usb:
 
-Create a bootable Clear Linux USB drive
-#######################################
+Create a bootable |CL-ATTR| USB drive
+#####################################
 
-Instructions to create a |CLOSIA| USB drive vary depending on your operating
+Instructions to create a |CL-ATTR| USB drive vary depending on your operating
 system.
 
 .. _download-usb-image:
 
-Download the latest Clear Linux image
-*************************************
+Download the latest |CL| image
+******************************
 
 There are 2 types of |CL| images suitable for burning onto and running
 off a USB drive:
 
-   * Live image: :file:`clear-[version number]-live.img.xz`
-   * Installer image: :file:`clear-[version number]-installer.img.xz`
+* Live image: :file:`clear-[version number]-live.img.xz`
+* Installer image: :file:`clear-[version number]-installer.img.xz`
 
-Go to the Clear Linux `image`_ repository and download the desired type.
+Go to the |CL| `image`_ repository and download the desired type.
 
 With the appropriate image downloaded, choose the step-by-step instructions
 applicable to your system:

source/clear-linux/get-started/cgdisk-manual-install/cgdisk-manual-install.rst

@@ -1,11 +1,11 @@
 .. _cgdisk-manual-install:
 
-Create partitions for Clear Linux\* using CGDISK
-################################################
+Create partitions for |CL-ATTR| using CGDISK
+############################################
 
-As part of the |CL| manual installation processThese instructions guide you through the initial setup of your hard drive
-partitions using the :command:`cgdisk` utility . If you do not wish to continue creating your own
-partitions, :ref:`return to the bare metal manual installation
+These instructions guide you through the initial setup of your hard drive
+partitions using the :command:`cgdisk` utility . If you do not wish to continue 
+creating your own partitions, :ref:`return to the bare metal manual installation
 <bare-metal-manual-install>`.
 
 Prerequisites
@@ -67,7 +67,7 @@ installation.
 
       Figure 4: :guilabel:`cgdisk`
 
-Linux Partition setup
+Linux partition setup
 *********************
 
 In order to properly set up the |CL| partitioning scheme, we create three
@@ -173,7 +173,7 @@ about it, review `Rod Smith's Partitioning advice about alignment`_.
       Figure 9: :guilabel:`cgdisk - swap partition defined`
 
 Create the Linux filesystem partition
-*************************************
+=====================================
 
 Lastly, we must create the the Linux filesystem partition to use it as the
 root mount point for you |CL| installation.
@@ -265,21 +265,40 @@ partitions and select to format them.
 
       Figure 14: :guilabel:`Set mount point of sda3`
 
-   Upon completion, the :guilabel:`Set mount points` appear as shown
-   in figure 15:
+#. Optional: Select :guilabel:`Encrypt Root Partition`, if
+   desired, as shown in figure 15. 
 
+   .. note:: 
+      `Set mount points` now show as completed. 
+   
    .. figure:: figures/cgdisk-manual-install-15.png
       :scale: 50 %
-      :alt: Set mount point completed
+      :alt: Encrypt root partition
 
-      Figure 15: :guilabel:`Set mount points completed`
+      Figure 15: :guilabel:`Encrypt root partition`
+
+#. Type a confirmation passphrase as directed.    
+
+   .. note: 
+
+      It is recommended to record the passphrase for safekeeping. 
+               
+   .. figure:: figures/cgdisk-manual-install-16.png
+      :scale: 50 %
+      :alt: Type confirmation passphrase
+
+      Figure 16: :guilabel: `Type confirmation passphrase`
 
 #. Select the :guilabel:`< Next >` button and press :kbd:`Enter`. 
    
    You have completed the process of manually partitioning your target
-   system. Now, :ref:`return to the bare metal manual installation 
-   <bare-metal-manual-install>` to complete installation of Clear Linux.
-   Continue at the section *Additional manual installer settings*.
+   system. 
+
+#. Now, :ref:`return to the bare metal manual installation 
+   <bare-metal-manual-install>` to complete installation of |CL|.
+   
+   Continue at the section :ref:`Additional manual installer settings
+   <incl-additional-manual-installer-settings>`.
 
 .. _`GPT fdisk tutorial`:
    http://www.rodsbooks.com/gdisk/

source/clear-linux/get-started/compatibility-check.rst

@@ -1,11 +1,11 @@
 .. _compatibility-check:
 
-Check processor and EFI firmware compatibility with Clear Linux\*
-#################################################################
+Check processor and EFI firmware compatibility
+##############################################
 
-On a system that is currently running a Linux operating system, follow the
+On a system that is currently running a Linux\* operating system, follow the
 instructions below to determine if your system's processor and EFI firmware is
-capable of running |CLOSIA|. Otherwise,
+capable of running |CL-ATTR|. Otherwise,
 :ref:`run Clear Linux as a Live image <live-image>` and then perform the steps
 below.
 
@@ -19,13 +19,13 @@ below.
 
    .. code-block:: console
 
-      $ curl -O https://download.clearlinux.org/current/clear-linux-check-config.sh
+      curl -O https://download.clearlinux.org/current/clear-linux-check-config.sh
 
 #. Make the script executable.
 
    .. code-block:: console
 
-      $ chmod +x clear-linux-check-config.sh
+      chmod +x clear-linux-check-config.sh
 
 #. Run the script.
 
@@ -34,13 +34,13 @@ below.
 
       .. code-block:: console
 
-         $ ./clear-linux-check-config.sh host
+         ./clear-linux-check-config.sh host
 
    #. Check to see if the host is capable of running |CL| in a container.
 
       .. code-block:: console
 
-         $ ./clear-linux-check-config.sh container
+         ./clear-linux-check-config.sh container
 
    The script will print a list of test results similar to the output below.
    All items should return a `SUCCESS` status. This example indicates the
@@ -48,7 +48,7 @@ below.
 
    .. code-block:: console
 
-      Checking if host is capable of running Clear Liunx* OS for Intel® Architecture
+      Checking if host is capable of running Clear Linux* OS
 
       SUCCESS: 64-bit CPU (lm)
       SUCCESS: Supplemental Streaming SIMD Extensions 3 (ssse3)

source/clear-linux/get-started/get-started.rst

@@ -3,21 +3,33 @@
 Get started
 ###########
 
-This section contains information about the installation of |CLOSIA|.
+The Get Started section will get you up and running fast with |CL-ATTR|. Use 
+these step-by-step instructions to guide you through the installation of |CL| 
+from bare metal to a live image.
+ 
+Pre-install
+***********
+
+* :ref:`system-requirements` 
+* :ref:`compatibility-check`
+* :ref:`bootable-usb` 
+
+Install |CL| 
+************
+
+* :ref:`bare-metal-install` 
+* :ref:`bare-metal-manual-install`
+* :ref:`virtual-machine-install`
+* :ref:`live-image`
 
-The :ref:`get-started` section provides step-by-step instructions to download
-and run |CL| on :ref:`bare metal <bare-metal-install>`, under
-a :ref:`virtual machine <virtual-machine-install>`, or by way of a
-:ref:`live image <live-image>`. Additionally, it provides useful pre-install
-information and instructions on how to complete pre-install tasks.
 
 .. toctree::
    :maxdepth: 2
+   :hidden:
 
-   ../reference/system-requirements
    bare-metal-install/bare-metal-install
-   bare-metal-install/bare-metal-manual-install
-   bare-metal-install/cgdisk-manual-install
+   bare-metal-manual-install/bare-metal-manual-install
+   cgdisk-manual-install/cgdisk-manual-install
    virtual-machine-install/virtual-machine-install
    live-image
    compatibility-check

source/clear-linux/get-started/live-image.rst

@@ -1,12 +1,12 @@
 .. _live-image:
 
-Install Clear Linux as a live image
-###################################
+Install |CL-ATTR| as a live image
+#################################
 
-A live image contains the complete |CLOSIA| operating system and resides
+A live image contains the complete |CL-ATTR| operating system and resides
 on a bootable media such as a USB drive or in a virtual machine
-(see :ref:`virtual-machine-install`). This is a
-great way to use |CL| without modifying your computer's hard disk.
+(see :ref:`virtual-machine-install`). This is a great way to use |CL| 
+without modifying your computer's hard disk.
 
 To create a bootable USB drive with a live image, follow
 :ref:`our step-by-step instructions<bootable-usb>` and use the latest |CL|
@@ -15,8 +15,8 @@ live image from the `image`_ directory. Look for the
 
 .. _boot-live-image:
 
-Boot the Clear Linux live image
-*******************************
+Boot the |CL| live image
+************************
 
 #. Configure the BIOS/UEFI firmware settings of the target system:
 

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

@@ -3,7 +3,7 @@
 Use Hyper-V\*
 #############
 
-This section explains how to run |CLOSIA| inside a
+This section explains how to run |CL-ATTR| inside a
 `Windows Server Virtualization`_\* or **Hyper-V** environment.
 
 Please ensure you have enabled `Intel® Virtualization Technology
@@ -13,13 +13,13 @@ Please ensure you have enabled `Intel® Virtualization Technology
 (Intel® VT-d) in your BIOS/UEFI firmware configuration.
 
 Enable Hyper-V
-==============
+**************
 
 Please refer to the `Microsoft documentation`_ to enable and configure
 *Hyper-V* on your machine.
 
 Create a virtual network
-========================
+************************
 
 Once *Hyper-V* has been enabled on your Windows system you will need to 
 create a virtual network in the **Hyper-V Manager**.  Refer to the
@@ -27,11 +27,11 @@ create a virtual network in the **Hyper-V Manager**.  Refer to the
 a virtual network.
 
 Create a virtual machine
-========================
+************************
 
-#. Download and uncompress the latest hyperv disk image
+#. Download and decompress the latest hyperv disk image
    :file:`clear-XXXXX-hyperv.img.gz`, where XXXXX is the latest 
-   available version of |CLOSIA| from our `downloads`_ section.
+   available version of |CL| from our `downloads`_ section.
 
 #. Create a virtual machine using the **Hyper-V Manager**:
 
@@ -41,7 +41,7 @@ Create a virtual machine
    c. When finished, open VM settings, select Firmware Section and in Secure
       Boot config, **uncheck** Enable Secure Boot.
 
-   .. note:: Currently, Clear Linux does not boot with `secure boot`
+   .. note:: Currently, |CL| does not boot with `secure boot`
       enabled.
 
 #. Connect to your new VM and start it. You should see a prompt:
@@ -52,7 +52,7 @@ Create a virtual machine
 
 #. Set a root user password.
 
-Your virtual machine running |CLOSIA| is ready!
+Your virtual machine running |CL| is ready!
 
 .. _Windows Server Virtualization: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/
 .. _Microsoft documentation: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v

source/clear-linux/get-started/virtual-machine-install/kvm.rst

@@ -1,13 +1,13 @@
 .. _kvm:
 
-Run Clear Linux as a KVM guest OS
-#################################
+Run |CL-ATTR| as a KVM guest OS
+###############################
 
-This section explains how to run |CLOSIA| in a virtualized environment using
+This section explains how to run |CL-ATTR| in a virtualized environment using
 :abbr:`KVM (Kernel-based Virtual Machine)`.
 
 Install QEMU-KVM
-================
+****************
 
 #. Enable the `Intel® Virtualization Technology`_ (Intel® VT) and the
    `Intel®Virtualization Technology for Directed I/O`_ (Intel® VT-d) in the
@@ -16,38 +16,38 @@ Install QEMU-KVM
 #. Log in, open a terminal emulator, and get root privilege on the host
    machine:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-    $ sudo -s
+      sudo -s
 
 #. Install `QEMU*-KVM` on the host machine. Below are some example distros.
 
    * On |CL|:
 
-     .. code-block:: console
+     .. code-block:: bash
 
-        # swupd bundle-add desktop-autostart kvm-host
+        swupd bundle-add desktop-autostart kvm-host
 
    * On Ubuntu\* 16.04 LTS Desktop:
 
-     .. code-block:: console
+     .. code-block:: bash
 
-        # apt-get install qemu-kvm
+        apt-get install qemu-kvm
 
    * On Mint\* 18.1 “Serena” Desktop:
 
-     .. code-block:: console
+     .. code-block:: bash
 
-        # apt-get install qemu-kvm
+        apt-get install qemu-kvm
 
    * On Fedora\* 25 Workstation:
 
-     .. code-block:: console
+     .. code-block:: bash
 
-        # dnf install qemu-kvm
+        dnf install qemu-kvm
 
 Download and launch the virtual machine
-=======================================
+***************************************
 
 #. Download the latest pre-built |CL| KVM image file from
    the `image <https://download.clearlinux.org/image/>`_ directory. Look for
@@ -55,13 +55,13 @@ Download and launch the virtual machine
 
    .. code-block:: bash
 
-      curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-kvm.img.xz
+      curl -O https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep '[0-9]'-kvm)
 
 #. Uncompress the downloaded image:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # unxz clear-<version>-kvm.img.xz
+      unxz clear-<version>-kvm.img.xz
 
 #. Download the `OVMF file`_ file that provides UEFI support for
    virtual machines from the `image <https://download.clearlinux.org/image/>`_
@@ -74,74 +74,75 @@ Download and launch the virtual machine
 
 #. Make the script executable:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # chmod +x start_qemu.sh
+      chmod +x start_qemu.sh
 
 #. Start the |CL| KVM virtual machine:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # ./start_qemu.sh clear-<version>-kvm.img
+      ./start_qemu.sh clear-<version>-kvm.img
 
 #. Log in as ``root`` user and set a new password.
 
 SSH access into the virtual machine
-===================================
+***********************************
+
 To interact with the |CL| VM through SSH instead of the console it was
 launched from, follow these steps.
 
 #. Enable SSH in the |CL| VM:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # cat > /etc/ssh/sshd_config << EOF
+      cat > /etc/ssh/sshd_config << EOF
         PermitRootLogin yes
         EOF
 
 #. From the host, SSH into the |CL| VM.  The port number ``10022`` is defined
    in the ``start_qemu.sh`` script.  
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # ssh -p 10022 root@localhost
+      ssh -p 10022 root@localhost
 
 Add the GNOME Display Manager (GDM)
-===================================
+***********************************
 
 To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps:
 
 #. Shutdown the active |CL| VM.
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # shutdown now
+      shutdown now
           
 #. Install a VNC viewer on the host machine.  Below are some example distros.
 
    * On Clear Linux:
 
-     .. code-block:: console
+     .. code-block:: bash
 
-        # swupd bundle-add desktop-apps-extras 
+        swupd bundle-add desktop-apps-extras 
 
    * On Ubuntu\* 16.04 LTS Desktop:
 
-     .. code-block:: console
+     .. code-block:: bash
 
-        # apt-get install vncviewer
+        apt-get install vncviewer
 
    * On Mint\* 18.1 “Serena” Desktop:
 
-     .. code-block:: console
+     .. code-block:: bash
 
-        # apt-get install vncviewer
+        apt-get install vncviewer
 
    * On Fedora\* 25 Workstation:
 
-     .. code-block:: console
+     .. code-block:: bash
 
-        # dnf install tigervnc
+        dnf install tigervnc
 
 #. Modify the :file:`start_qemu.sh` script to increase memory (``-m``), add
    graphics driver (``-vga``), and add VNC (``-vnc``, ``-usb``, and
@@ -169,48 +170,48 @@ To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps:
 
    #. Relaunch the |CL| VM.  The UEFI shell will appear.
 
-      .. code-block:: console
+      .. code-block:: bash
 
-         # ./start_qemu.sh clear-<version>-kvm.img
+         ./start_qemu.sh clear-<version>-kvm.img
 
    #. At the UEFI shell, delete the :file:`NvVars` file:
 
-      .. code-block:: console
+      .. code-block:: bash
 
          Shell> del FS0:\NvVars
 
    #. Exit out of the UEFI shell:
 
-      .. code-block:: console
+      .. code-block:: bash
 
          Shell> reset -s
 
    #. Relaunch the |CL| VM:
 
-      .. code-block:: console
+      .. code-block:: bash
 
-         # ./start_qemu.sh clear-<version>-kvm.img
+         ./start_qemu.sh clear-<version>-kvm.img
 
 #. From the host machine, open a new terminal emulator window and VNC into the
    |CL| VM:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # vncviewer 0.0.0.0
+      vncviewer 0.0.0.0
 
 #. Log in as ``root`` user into the |CL| VM.
 
 #. Add GDM to the |CL| VM:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # swupd bundle-add desktop-autostart
+      swupd bundle-add desktop-autostart
 
 #. Reboot the |CL| VM to enable GDM:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      # reboot
+      reboot
       
 #. Go through GDM's out-of-box experience (OOBE).
 

source/clear-linux/get-started/virtual-machine-install/virtual-machine-install.rst

@@ -1,26 +1,26 @@
 .. _virtual-machine-install:
 
-Install Clear Linux in a virtual machine
-########################################
+Install |CL-ATTR| in a virtual machine
+######################################
 
-There are some considerations to make when installing |CL| in a VM.
+There are some considerations to make when installing |CL-ATTR| in a VM.
 First, you need to decide which kernel to use. This document
 will walk you through the available kernel options to help this decision. At
 the end of this document, you will be able to select the set of installation
 steps most suitable to you and install |CL| under a VM.
 
 Compatible kernels
-==================
+******************
 
-The |CLOSIA| provides the following Linux kernels with a respective
+The |CL| provides the following Linux kernels with a respective
 :ref:`bundle <bundles-about>` for VMs. Specific use cases these bundles serve
 are provided along with links to their source code.
 
 .. include:: ../../reference/compatible-kernels.rst
    :Start-after: vm-kernels:
 
-Next steps:
-===========
+Next steps
+**********
 
 Now that you have read about the |CL| compatible kernels, choose the
 appropriate set of step-by-step instructions to proceed.

source/clear-linux/get-started/virtual-machine-install/virtualbox.rst

@@ -6,14 +6,14 @@ Run pre-configured |CL-ATTR| as a VirtualBox\* guest OS
 This instruction explains how to deploy a pre-configured |CL-ATTR| image as a guest on the `VirtualBox hypervisor`_ .
 
 Download VirtualBox
-===================
+*******************
 
 VirtualBox\* is a type 2 hypervisor from Oracle. Download and use **version 5.0 or greater** from the `official VirtualBox website`_.
 
 .. _create_vm_vbox:
 
 Prerequisites
-=============
+*************
 
 The instruction assumes that you have: 
 
@@ -29,7 +29,7 @@ The instruction assumes that you have:
 If you have not completed the above steps, do so before continuing. 
 
 Create a virtual machine in VirtualBox
-======================================
+**************************************
 
 #. Log in to your host and open a terminal emulator.
 
@@ -38,7 +38,7 @@ Create a virtual machine in VirtualBox
 
    .. code-block:: bash
 
-      curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-live.img.xz
+      curl -O https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep live)
 
 #. Decompress the downloaded image. Uncompressed image size is ~ **5GB**.
 
@@ -103,7 +103,7 @@ Create a virtual machine in VirtualBox
 
 
 Run your new VM
-===============
+***************
 
 |CL| supports VirtualBox kernel modules used
 by the Linux kernel 4.14 :abbr:`LTS (Long Term Support)` 
@@ -147,7 +147,7 @@ To install the VirtualBox kernel modules, here are the steps:
      clr-boot-manager update
 
 Install Guest Additions
------------------------
+=======================
 
 The kernel modules are shipped with the ``kernel-lts`` bundle. Insert Guest 
 Additions CD image using *Devices* menu you'll need to install the *user* 
@@ -170,7 +170,7 @@ follow these steps:
 
 
 Troubleshooting
----------------
+===============
 
 On Windows OS, *VirtualBox* cannot do a **Hardware Virtualization** when
 *Hyper-V* is enabled.
@@ -193,4 +193,4 @@ To enable Hyper-V again, you should execute::
 .. _VirtualBox hypervisor: https://www.virtualbox.org/
 .. _latest: https://download.clearlinux.org/image/
 .. _7zip: http://www.7-zip.org/
-.. _Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html
+.. _Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html

source/clear-linux/get-started/virtual-machine-install/vmw-player-preconf.rst

@@ -1,11 +1,11 @@
 .. _vmw-player-preconf:
 
-Run pre-configured Clear Linux image as a VMware\* Workstation Player guest OS
-##############################################################################
+Run pre-configured |CL-ATTR| image as a VMware\* Workstation Player guest OS
+############################################################################
 
 `VMware Workstation 14 Player`_ is a type 2 hypervisor. It runs on top of
 another operating system such as Windows\* or Linux\*. With VMware ESXi, you
-can create, configure, manage, and run |CLOSIA| :abbr:`VMs (Virtual Machines)`
+can create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)`
 on your local system.
 
 This section shows how to deploy a pre-configured |CL| VMware image on
@@ -13,18 +13,12 @@ VMware Workstation 14 Player.
 
 In this tutorial, we perform the following steps:
 
-#. Install the VMware Workstation Player hypervisor
-#. Download the latest |CL| pre-configured image
-#. VMware image Verify the integrity of the |CL| image
-#. Uncompress the |CL| image
-#. Create and configure a new VM
-#. Attach the pre-configured VMware |CL| image
-#. Enable EFI boot support
-#. Power on the VM
+.. contents:: :local:
+   :depth: 1
 
 .. note::
 
-   The screenshots on this document show the Windows\* version of the
+   The screenshots on this document show the Windows version of the
    VMware Workstation 14 Player. The menus and prompts are similar to those
    in the Linux version save some minor wording differences.
 
@@ -61,14 +55,8 @@ Install the VMware Workstation Player hypervisor
 
 For additional help, see the `VMware Workstation Player guide`_.
 
-Clear Linux image types
-***********************
-
-.. include:: ../../reference/image-types.rst
-   :Start-after: image-types-content:
-
-Download the latest Clear Linux VMware image
-********************************************
+Download the latest |CL| VMware image
+*************************************
 
 Get the latest |CL| VMware image from the `image`_ repository.
 Look for :file:`clear-[version number]-vmware.vmdk.xz`. You can also use
@@ -76,15 +64,17 @@ this command:
 
 .. code-block:: bash
 
-   curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-vmware.vmdk.xz
+   curl -O https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep vmware)
 
-.. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst
+Visit :ref:`image-types` for additional information about all available |CL| images.
+
+.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst
    :Start-after: verify-windows:
 
 We also provide instructions for other operating systems:
 
-* :ref:`download-verify-uncompress-linux`
-* :ref:`download-verify-uncompress-mac`
+* :ref:`download-verify-decompress-linux`
+* :ref:`download-verify-decompress-mac`
 
 Create and configure a new VM
 *****************************
@@ -189,10 +179,10 @@ Create and configure a new VM
 
 #. Click the :guilabel:`Finish` button.
 
-Attach the pre-configured Clear Linux VMware image
-**************************************************
+Attach the pre-configured |CL| VMware image
+*******************************************
 
-#. Move the downloaded and uncompressed pre-configured |CL| VMware image file
+#. Move the downloaded and decompressed pre-configured |CL| VMware image file
    :file:`clear-[version number]-basic.vmdk` to the directory where your
    newly-created VM resides.
 
@@ -304,6 +294,9 @@ After configuring the settings above, power on your |CL| virtual machine.
 
 #. Click :guilabel:`Play virtual machine`.
 
+Related topics
+**************
+
 For other guides on using the VMWare Player and ESXi, see:
 
 * :ref:`vmw-player`

source/clear-linux/get-started/virtual-machine-install/vmw-player.rst

@@ -1,11 +1,11 @@
 .. _vmw-player:
 
-Install Clear Linux as a VMware\* Workstation Player guest OS
-#############################################################
+Install |CL-ATTR| as a VMware\* Workstation Player guest OS
+###########################################################
 
 `VMware Workstation 14 Player`_ is a type 2 hypervisor. It runs on top of
-another operating system such as Windows or Linux. With VMware ESXi, you can
-create, configure, manage, and run |CLOSIA| :abbr:`VMs (Virtual Machines)` on
+another operating system such as Windows\* or Linux\*. With VMware ESXi, you can
+create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)` on
 your local system.
 
 This section shows how to create a new VM and install |CL| into it with the
@@ -15,17 +15,8 @@ size, number of partitions, installed bundles, etc.
 
 In this tutorial, we perform the following steps:
 
-#. Install the VMware Workstation Player hypervisor
-#. Download the latest |CL| installer ISO
-#. Verify the integrity of the |CL| image
-#. Uncompress the |CL| image
-#. Create and configure a new VM
-#. Attach the |CL| installer ISO to the VM
-#. Install |CL| into the new VM
-#. Detach the |CL| installer ISO from the VM
-#. Power off the VM
-#. Enable EFI boot support
-#. Power on the VM
+.. contents:: :local:
+   :depth: 1
 
 If you prefer to use a pre-configured |CL| VMware image instead,
 see our :ref:`vmw-player-preconf` guide.
@@ -36,7 +27,7 @@ it, see :ref:`vmware-esxi-install-cl`.
 
 .. note::
 
-   The screenshots on this document show the Windows\* version of the
+   The screenshots on this document show the Windows version of the
    VMware Workstation 14 Player. The menus and prompts are similar to those
    in the Linux version save some minor wording differences.
 
@@ -55,42 +46,37 @@ Install the VMware Workstation Player hypervisor
 
    * On supported Linux distros:
 
-      #. Enable a GUI desktop.
-      #. Start a terminal emulator.
-      #. Start the installer by issuing the command below and follow the
-          guided steps.
+     #. Enable a GUI desktop.
+     #. Start a terminal emulator.
+     #. Start the installer by issuing the command below and follow the
+        guided steps.
 
-          .. code-block:: console
+        .. code-block:: console
 
-            $ sudo sh ./VMware-Player-[version number].x86_64.bundle
+           sudo sh ./VMware-Player-[version number].x86_64.bundle
 
    * On Windows:
 
-      #. Start the installer.
-      #. Follow the setup wizard.
+     #. Start the installer.
+     #. Follow the setup wizard.
 
 For additional help, see the `VMware Workstation Player guide`_.
 
-Clear Linux image types
-***********************
-
-.. include:: ../../reference/image-types.rst
-   :Start-after: image-types-content:
-
-
-Download the latest Clear Linux installer ISO
-*********************************************
+Download the latest |CL| installer ISO
+**************************************
 
 Get the latest |CL| installer ISO image from the `image`_ repository.
 Look for :file:`clear-[version number]-installer.iso.xz`.
 
-.. include:: ../../guides/maintenance/download-verify-uncompress-windows.rst
+Visit :ref:`image-types` for additional information about all available |CL| images.
+
+.. include:: ../../guides/maintenance/download-verify-decompress-windows.rst
    :Start-after: verify-windows:
 
 We also provide instructions for other operating systems:
 
-* :ref:`download-verify-uncompress-linux`
-* :ref:`download-verify-uncompress-mac`
+* :ref:`download-verify-decompress-linux`
+* :ref:`download-verify-decompress-mac`
 
 Create and configure a new VM
 *****************************
@@ -117,7 +103,7 @@ Create and configure a new VM
 
       Figure 2: VMware Workstation 14 Player - Select |CL| installer ISO
 
-#. Click the :guilabel:`Browse` button and select the uncompressed |CL|
+#. Click the :guilabel:`Browse` button and select the decompressed |CL|
    installer ISO.
 
 #. Click the :guilabel:`Next` button.
@@ -204,8 +190,8 @@ Create and configure a new VM
 
 #. Click the :guilabel:`Finish` button.
 
-Install Clear Linux into the new VM
-***********************************
+Install |CL| into the new VM
+****************************
 
 #. Select the newly-created VM and click the :guilabel:`Play virtual machine`
    button. See Figure 9.
@@ -267,7 +253,7 @@ Enable UEFI boot support
 |CL| needs UEFI support to boot. To enable UEFI, add the
 following line to the end of your VM's :file:`.vmx` file:
 
-.. code-block:: bash
+.. code-block:: console
 
    firmware = "efi"
 
@@ -294,6 +280,9 @@ After configuring the settings above, power on your |CL| virtual machine.
 
 #. Click :guilabel:`Play virtual machine`.
 
+Related topics
+**************
+
 For other guides on using the VMWare Player and ESXi, see:
 
 * :ref:`vmw-player-preconf`

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

@@ -1,18 +1,15 @@
 .. _vmware-esxi-install-cl:
 
-Install Clear Linux as a VMware\* ESXi guest OS
-###############################################
+Install |CL-ATTR| as a VMware\* ESXi guest OS
+#############################################
 
 `VMware ESXi`_ is a type 1 bare-metal hypervisor which runs directly on top
 of server hardware. With VMware ESXi, you can create, configure, manage, and
-run |CLOSIA| virtual machines in the cloud.  
+run |CL-ATTR| virtual machines in the cloud.  
 
 This section shows you how to create a new :abbr:`VM (Virtual Machine)` and 
 manually install |CL| into it with VMware ESXi 6.5. 
 
-If you would prefer to use a preconfigured |CL| VMware disk image 
-instead, see :ref:`vmware-esxi-preconfigured-cl-image`. 
-
 Manually installing |CL| into a new VM provides you some additional 
 configuration flexibility during installation. For example: alternate
 disk sizes, number of partitions, pre-installed bundles, etc. 
@@ -35,23 +32,23 @@ Install steps:
    :depth: 1
 
 
-Download the latest Clear Linux installer ISO
-*********************************************
+Download the latest |CL| installer ISO
+**************************************
 
 Get the latest |CL| installer ISO image from the `image`_ repository.
 Look for :file:`clear-[version number]-installer.iso.xz`.
 
-.. include:: ../../guides/maintenance/download-verify-uncompress-linux.rst
-   :Start-after: verify-linux:
-   :end-before: To uncompress a GZ
+.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst
+   :Start-after: incl-decompress-image:
+   :end-before: incl-decompress-image-end:
 
 For alternative instructions on other operating systems, see: 
 
-* :ref:`download-verify-uncompress-mac`
-* :ref:`download-verify-uncompress-windows`
+* :ref:`download-verify-decompress-mac`
+* :ref:`download-verify-decompress-windows`
 
-Upload the Clear Linux installer ISO to the VMware server
-*********************************************************
+Upload the |CL| installer ISO to the VMware server
+**************************************************
 
 #.  Connect to the VMware server and log into an account with sufficient 
     permission to create and manage VMs.  
@@ -84,7 +81,7 @@ Upload the Clear Linux installer ISO to the VMware server
 
       Figure 3: VMware ESXi - Datastore > Upload ISO 
    
-#.  Select the uncompressed |CL| installer ISO file :file:`clear-[version number]-installer.iso` 
+#.  Select the decompressed |CL| installer ISO file :file:`clear-[version number]-installer.iso` 
     and upload it.
 
 Create and configure a new VM
@@ -188,8 +185,8 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I
 #.  Click the :guilabel:`Next` button.
 #.  Click the :guilabel:`Finish` button.
 
-Install Clear Linux into the new VM
-***********************************
+Install |CL| into the new VM
+****************************
 
 #.  Power on the VM.
     
@@ -211,8 +208,8 @@ Install Clear Linux into the new VM
 #.  After the installation is complete, follow the |CL| instruction to reboot it.  
     This will restart the installer again. 
 
-Reconfigure the VM's settings to boot the newly-installed Clear Linux
-*********************************************************************
+Reconfigure the VM's settings to boot the newly-installed |CL|
+**************************************************************
 
 After |CL| has been installed using the installer ISO, it must be detached so
 it will not run again.  Also, in order to boot the newly-installed |CL|, you must
@@ -268,8 +265,8 @@ enable UEFI support.
 
 #.  Click the :guilabel:`Save` button.
 
-Power on the VM and boot Clear Linux
-************************************
+Power on the VM and boot |CL|
+*****************************
 
 After configuring the settings above, power on the VM.  
 
@@ -286,8 +283,8 @@ After configuring the settings above, power on the VM.
 
       Figure 16: VMware ESXi - Navigator > Virtual Machines > Power on VM
 
-See Also:
-=========
+Related topics
+**************
 
 * :ref:`vmware-esxi-preconfigured-cl-image`
 

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

@@ -1,11 +1,11 @@
 .. _vmware-esxi-preconfigured-cl-image:
 
-Run preconfigured Clear Linux\* image as a VMware\* ESXi guest OS
-#################################################################
+Run preconfigured |CL-ATTR| image as a VMware\* ESXi guest OS
+#############################################################
 
 `VMware ESXi`_ is a type 1 bare-metal hypervisor which runs directly on top
 of server hardware.  With VMware ESXi, you can create, configure, manage,
-and run |CLOSIA| virtual machines at scale.
+and run |CL-ATTR| virtual machines at scale.
 
 This section shows you how to deploy a preconfigured |CL| VMware 
 :abbr:`VM (Virtual Machine)` image on a VMware ESXi 6.5 host.
@@ -21,15 +21,14 @@ VMware ESXi :abbr:`VM (Virtual Machine)` instead, see
 
    See :ref:`vmw-player-preconf` or see :ref:`vmw-player`.
 
-   Visit :ref:`image-types` to learn more about all available images.
 
 Install steps: 
 
 .. contents:: :local:
     :depth: 1
 
-Download the latest Clear Linux VMware image
-********************************************
+Download the latest |CL| VMware image
+*************************************
 
 Get the latest |CL| VMware prebuilt image from the `image`_ repository.
 Look for :file:`clear-[version number]-vmware.vmdk.xz`. You can also use
@@ -37,22 +36,24 @@ this command:
 
 .. code-block:: bash
 
-   curl -O https://download.clearlinux.org/image/clear-$(curl https://download.clearlinux.org/latest)-vmware.vmdk.xz
+   curl -O https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep vmware)
 
-.. include:: ../../guides/maintenance/download-verify-uncompress-linux.rst
-   :Start-after: verify-linux:
-   :end-before: To uncompress a GZ
+Visit :ref:`image-types` for additional information about all available |CL| images.
+
+.. include:: ../../guides/maintenance/download-verify-decompress-linux.rst
+   :Start-after: incl-decompress-image:
+   :end-before: incl-decompress-image-end:
 
 For alternative instructions on other operating systems, see:
 
-* :ref:`download-verify-uncompress-mac`
-* :ref:`download-verify-uncompress-windows`
+* :ref:`download-verify-decompress-mac`
+* :ref:`download-verify-decompress-windows`
 
-Upload the Clear Linux image to the VMware server
-*************************************************
+Upload the |CL| image to the VMware server
+******************************************
 
 Once the |CL| VMware prebuilt image has been downloaded and 
-uncompressed on your local system, it must be uploaded to a datastore 
+decompressed on your local system, it must be uploaded to a datastore 
 on the VMware ESXi server.
 
 The steps in this section can also be referenced from the `VMware documentation on Using the Datastore File Browser`_ 
@@ -91,11 +92,11 @@ The steps in this section can also be referenced from the `VMware documentation
 
       Figure 3: VMware ESXi - Datastore > Upload VMware image
 
-#. Select the uncompressed |CL| VMware image file
+#. Select the decompressed |CL| VMware image file
    :file:`clear-[version number]-vmware.vmdk` and upload it.
 
-Convert the Clear Linux image to an ESXi-supported format
-*********************************************************
+Convert the |CL| image to an ESXi-supported format
+**************************************************
 
 Once the |CL| VMware prebuilt image has been uploaded to the VMware ESXi
 datastore, it must be converted to a format for usable with VMware's ESXi 
@@ -258,8 +259,8 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support.
 #. Click the :guilabel:`Next` button.
 #. Click the :guilabel:`Finish` button.
 
-Power on the VM and boot Clear Linux
-************************************
+Power on the VM and boot |CL|
+*****************************
 
 After configuring the settings above, power on the VM.
 
@@ -276,8 +277,8 @@ After configuring the settings above, power on the VM.
 
       Figure 13: VMware ESXi - Navigator > Virtual Machines > Power on VM
 
-See Also:
-=========
+Related topics
+**************
 
 * :ref:`vmware-esxi-install-cl`
 

source/clear-linux/guides/guides.rst

@@ -19,3 +19,4 @@ after completing the |CL| :ref:`installation <get-started>`.
    maintenance/maintenance
    network/network
    deploy-at-scale
+   telemetrics/telemetrics

source/clear-linux/guides/maintenance/autospec.rst

@@ -3,45 +3,41 @@
 Build RPMs with autospec
 ########################
 
-This guide shows you how to create RPMs with :ref:`autospec <autospec-about>`
-, a tool that assists in automated creation and maintenance of RPM packaging 
-on |CLOSIA|.  Additionally, you learn how to use these RPMs to create bundles
-with :ref:`mixer <mixer>`. 
+This guide shows you how to create RPMs with :ref:`autospec <autospec-about>`,
+a tool that assists in automated creation and maintenance of RPM packaging
+on |CL-ATTR|.
+
+See our :ref:`autospec concept page <autospec-about>` for a detailed explaination
+of how ``autospec`` works on |CL|. For a general understanding of how RPMs work,
+we recommend visiting the `rpm website`_ or the `RPM Packaging Guide`_ .
 
 Prerequisites
 *************
-This guide assumes that you have:
 
-* Created :ref:`a custom mix <mixer>` of |CL| and deployed it to a
-  to a target device
+This guide requires that you:
 
-* |CL| running on a host machine or virtual environment
-  
-  .. note:: 
+* Have installed |CL| on a host machine or virtual environment. For detailed
+  instructions on installing |CL|, visit the :ref:`get-started` section.
 
-     To install |CL|, see: 
+* :ref:`install-tooling`
 
-     * :ref:`bare-metal-install`
-     * :ref:`virtual-machine-install`
-   
-Install Clear Linux tooling framework
-=====================================
+.. _install-tooling:
 
-Our GitHub\* repository provides you with the resources you need
-to create and maintain packages.
+Install the |CL| tooling framework
+==================================
+
+#. Install the `os-clr-on-clr` developer bundle on your host system.
 
-#. On your host system, install this developer bundle. 
-   
    .. code-block:: bash
 
       sudo swupd bundle-add os-clr-on-clr
 
-#. Run this command to download the :file:`user-setup.sh` script.
+#. Download the :file:`user-setup.sh` script.
 
    .. code-block:: bash
 
       curl -O https://raw.githubusercontent.com/clearlinux/common/master/user-setup.sh
-   
+
 #. Make :file:`user-setup.sh` executable.
 
    .. code-block:: bash
@@ -49,7 +45,7 @@ to create and maintain packages.
       chmod +x user-setup.sh
 
 #. Run the script as an unprivileged user.
-  
+
    .. code-block:: bash
 
       ./user-setup.sh
@@ -59,41 +55,31 @@ to create and maintain packages.
 
    The `user-setup script`_ creates a folder called :file:`clearlinux`, which
    contains the :file:`Makefile`, :file:`packages`, and :file:`projects`
-   subfolders.  
+   subfolders.
 
-   The :file:`projects` folder contains the main tools, `autospec` 
-   and `common`, used for making packages in |CL|. 
+   The :file:`projects` folder contains the main tools, `autospec`
+   and `common`, used for making packages in |CL|.
 
 Create a RPM with autospec
 **************************
 
-.. include:: ../../concepts/autospec-about.rst
-   :start-after: incl-autospec-overview:
-   :end-before: incl-autospec-overview-end:
- 
-For a detailed explanation of how ``autospec`` works on |CL|, visit our 
-:ref:`autospec-about` about page.  For a general understanding of how RPMs 
-work, we recommend visiting the `rpm website`_ or the 
-`RPM Packaging Guide`_ . 
-
-Building RPMs 
-=============
-
 Choose one of the following options to build RPMs and manage source
-code: 
+code:
 
-* :ref:`build-a-new-rpm` and spec file using ``make autospecnew``. 
+* :ref:`build-a-new-rpm` and spec file using ``make autospecnew``.
 
-* :ref:`build-source-code-with-existing-spec-file` (without changing the
-  spec file) using ``make build``.  
+* :ref:`build-source-code-with-existing-spec-file` using ``make build``, without changing the
+  spec file.
 
-* :ref:`generate-a-new-spec-file` based on changes in the control files with
-  ``make autospec``. 
+* :ref:`generate-a-new-spec-file` using ``make autospec``, based on changes in the control files.
 
 .. _build-a-new-rpm:
 
-Build a new RPM
-===============
+Option 1: Build a new RPM
+=========================
+
+Use this method to build a new RPM with no spec file. In this example,
+we build a new helloclear RPM.
 
 #. Navigate to the autospec workspace.
 
@@ -101,21 +87,21 @@ Build a new RPM
 
       cd ~/clearlinux
 
-#. Enter the command: 
+#. Enter the command:
 
    .. code-block:: bash
 
-      make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz" 
+      make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz"
       NAME="helloclear"
 
-   .. note:: 
+   .. note::
 
-      For a local tarball, use for the *URL*: 
+      For a local tarball, use for the *URL*:
       file://<absolute-path-to-tarball>
-   
+
 #. If build failures or dependency issues occur, continue below.
-   Otherwise, skip directly to `copy-rpm-packages-to-mixer`_.    
-   
+   Otherwise, skip directly to `Next steps`_.
+
    #. Navigate to the specific package.
 
       .. code-block:: bash
@@ -123,52 +109,60 @@ Build a new RPM
          cd ~/clearlinux/packages/[package-name]
 
    #. Respond to the build process output by editing control files to resolve
-      issues, which may include dependencies or exclusions. 
+      issues, which may include dependencies or exclusions.
       See `autospec readme`_
 
-   #. Run this command: 
+   #. Run this command:
 
       .. code-block:: bash
 
          make autospec
-  
-   Repeat the last two steps above until all errors are resolved and you 
-   complete a successful build. 
 
-   Skip to `copy-rpm-packages-to-mixer`_ to add the new RPM to your mix.
+   Repeat the last two steps above until all errors are resolved and you
+   complete a successful build.
+
+**Congratulations!**
+
+You've successfully created a RPM.
+
+Skip to `Next steps`_.
 
 .. _build-source-code-with-existing-spec-file:
 
-Build source code with an existing spec file 
-============================================
+Option 2: Build source code with an existing spec file
+======================================================
 
-If you only want to build the RPM using the spec file, use this method. This 
-method assumes that a spec file already exists. In this example, we run a 
-``make build`` on the ``dmidecode`` package. 
+Use this method if you only want to build the RPM using the spec file. This
+method assumes that a spec file already exists. In this example, we run a
+``make build`` on the ``dmidecode`` package.
 
-#. Navigate to the ``dmidecode`` package in clearlinux:  
+#. Navigate to the ``dmidecode`` package in clearlinux:
 
    .. code-block:: bash
 
-      cd ~/clearlinux/packages/dmidecode/   
+      cd ~/clearlinux/packages/dmidecode/
 
-#. To download the tarball and build, run the command: 
+#. To download the tarball and build, run the command:
 
-   .. code-block:: bash 
+   .. code-block:: bash
 
       make build
 
-   Skip to `copy-rpm-packages-to-mixer`_ to add the new RPM to your mix.
+**Congratulations!**
+
+You've successfully created a RPM.
+
+Skip to `Next steps`_.
 
 .. _generate-a-new-spec-file:
 
-Generate a new spec file with a pre-defined package
-===================================================
+Option 3: Generate a new spec file with a pre-defined package
+=============================================================
 
-In this method, you will modify an existing |CL| package called ``dmidecode``
-to create a custom RPM. You will make a simple change to this package, 
-change the revision to a new number that is higher than the |CL| OS version, 
-and rebuild the package.
+Use this method to modify an existing package. In this example, you will
+modify an existing |CL| package called ``dmidecode`` to create a custom
+RPM. You will make a simple change to this package, change the revision to
+a new number that is higher than the |CL| OS version, and rebuild the package.
 
 #. Navigate to clearlinux:
 
@@ -182,7 +176,7 @@ and rebuild the package.
 
       make clone_dmidecode
 
-#. Navigate into the *dmidecode* directory:    
+#. Navigate into the *dmidecode* directory:
 
    .. code-block:: bash
 
@@ -199,15 +193,15 @@ and rebuild the package.
       /usr/share/man/man8/ownership.8
       /usr/share/man/man8/vpddecode.8
 
-   .. note:: 
+   .. note::
 
       These files aren't needed by dmidecode, so we can remove them without
       any issues.
 
-#. Save the file and exit. 
+#. Save the file and exit.
 
-#. At :file:`~/clearlinux/packages/dmidecode`, build the modified 
-   ``dmidecode`` package: 
+#. At :file:`~/clearlinux/packages/dmidecode`, build the modified
+   ``dmidecode`` package:
 
    .. code-block:: bash
 
@@ -216,98 +210,32 @@ and rebuild the package.
    When the process completes, you will see new RPM packages in the
    :file:`results/` folder.
 
-#. To view the new RPM packages, enter: 
+#. To view the new RPM packages, enter:
 
    .. code-block:: bash
 
-      ls /clearlinux/packages/dmidecode/results/      
+      ls /clearlinux/packages/dmidecode/results/
 
-Add a custom RPM to a mix and deploy to target
-**********************************************
-
-We need a RPM repository to store our custom RPMs. This repository also 
-includes some metadata that allows programs such as ``yum`` and ``dnf`` to 
-follow and include any specified dependencies. This architecture enables us
-to test custom RPMs before we integrate them in a mix. 
-
-.. note:: 
-
-   Assure that you followed the :ref:`mixer` instruction and created
-   a location for **local RPM packages** using the *--local-rpms* flag
-   with the command: :command:`mixer init --local-rpms`. If you skipped 
-   this step, return and complete it in :ref:`mixer` before proceeding.  
-
-.. _copy-rpm-packages-to-mixer:
-
-Copy RPM packages to mixer and build bundle
-============================================
-
-Transfer the newly generated RPM packages to the ``mixer`` folder so
-that it can include them as needed. 
-
-.. note:: 
-
-   This guide assumes that you have a web server that hosts ``swupd`` update 
-   content. 
-
-#. Change directory into the mix workspace: 
-
-   .. code-block:: bash
-
-      cd ~/mix
-
-#. Copy the contents from the results folder in the RPM packages to the 
-   :file:`local-rpms` folder in the :file:`mix` folder: 
-
-   .. code-block:: bash
-
-      cp ~/clearlinux/packages/dmidecode/results/*x86_64*rpm ~/mix/local-rpms/
-
-#. Remove the debuginfo: 
-   
-   .. code-block:: bash
-
-      rm ~/mix/local-rpms/*debuginfo*x86_64*
-
-#. Generate the yum repo: 
-
-   .. code-block:: bash
-
-      sudo mixer add-rpms
-
-#. Create a local bundle definition file to include the newly generated RPM 
-   package in your mix. In our example, the ``[bundle-name]`` is 
-   either ``dmidecode`` or  ``helloclear``. 
-
-   .. code-block:: bash
-
-      mixer bundle edit [bundle-name]
-
-#. Then add the new bundle to the mix.
-       
-   .. code-block:: bash 
-  
-      mixer bundle add [bundle-name]
-
-#. Build the bundle and update content.
-
-   .. code-block:: bash
-
-      sudo mixer build all
-  
-#. Log into the target device.     
-  
-#. On the target device, update and install the new bundle.
-
-   .. code-block:: bash
-
-      sudo swupd update
-
-      sudo swupd bundle-add [bundle-name]
-            
 **Congratulations!**
 
-You successfully built a RPM and created a mix with it. 
+You've successfully created a RPM.
+
+Next steps
+**********
+
+Now you can create a custom bundle with your new RPM and use it with |CL|:
+
+* Use the :ref:`Mixer tool <mixer>` to add a new bundle to your derivative of |CL|.
+* Use the :ref:`Mixin tool <mixin>` to customize your upstream |CL| installation with a new bundle.
+
+Related topics
+**************
+
+* :ref:`Mixer tool <mixer>`
+* :ref:`Mixin tool <mixin>`
+* :ref:`autospec <autospec-about>`
+* :ref:`Bundles <bundles-about>`
+
 
 .. _rpm website: http://rpm.org
 

source/clear-linux/guides/maintenance/bulk-provision.rst

@@ -143,13 +143,13 @@ Configuration
       # MAC address,role
       default,ciao
 
-#. Verify the following URLs are accessible:
+#. Verify the following URLs are accessible on your local network:
 
-   * http://192.168.1.1:60000/icis/static/ister/ister.conf
-   * http://192.168.1.1:60000/icis/static/ister/ister.json
-   * http://192.168.1.1:60000/icis/get_config/<MAC address>
-   * http://192.168.1.1:60000/icis/get_role/<role>
-   * http://192.168.1.1:60000/ipxe/ipxe_boot_script.txt
+   * ``http://192.168.1.1:60000/icis/static/ister/ister.conf``
+   * ``http://192.168.1.1:60000/icis/static/ister/ister.json``
+   * ``http://192.168.1.1:60000/icis/get_config/<MAC address>``
+   * ``http://192.168.1.1:60000/icis/get_role/<role>``
+   * ``http://192.168.1.1:60000/ipxe/ipxe_boot_script.txt``
 
 #. Power on the PXE client and watch it boot and install |CL|.
 

source/clear-linux/guides/maintenance/download-verify-decompress-linux.rst

@@ -1,15 +1,15 @@
-.. _download-verify-uncompress-linux:
+.. _download-verify-decompress-linux:
 
-Download, verify, and uncompress a Clear Linux image on Linux
-#############################################################
+Download, verify, and decompress a |CL-ATTR| image on Linux
+###########################################################
 
-This guide describes the types of |CLOSIA| images available, where to download
-them, how to verify the integrity of an image, and how to uncompress it.
+This guide describes the types of |CL| images available, where to download
+them, how to verify the integrity of an image, and how to decompress it.
 
 Instructions for other operating systems are available:
 
-* :ref:`download-verify-uncompress-mac`
-* :ref:`download-verify-uncompress-windows`
+* :ref:`download-verify-decompress-mac`
+* :ref:`download-verify-decompress-windows`
 
 Image types
 ***********
@@ -19,8 +19,8 @@ Image types
 
 .. _verify-linux:
 
-Verify the integrity of the Clear Linux image
-*********************************************
+Verify the integrity of the |CL| image
+**************************************
 
 Before you use a downloaded |CL| image, verify its integrity. This action
 eliminates the small chance of a corrupted image due to download issues. To
@@ -45,24 +45,28 @@ the screen followed by `OK`.
 For a more in-depth discussion of image verification including checking the
 certificate see :ref:`image-content-validation`.
 
-Uncompress the Clear Linux image
-********************************
+.. incl-decompress-image:
+
+Decompress the |CL| image
+*************************
 
 Released |CL| images are compressed with either GNU zip (*.gz*) or XZ
 (*.xz*). The compression type depends on the target platform or
-environment. To uncompress the image, follow these steps:
+environment. To decompress the image, follow these steps:
 
 #.  Start a terminal emulator.
 #.  Go to the directory with the downloaded image.
 
-    To uncompress an XZ image, enter:
+    To decompress an XZ image, enter:
 
     .. code-block:: bash
 
         unxz clear-[version number]-[image type].xz
 
-    To uncompress a GZ image, enter:
+    To decompress a GZ image, enter:
 
     .. code-block:: bash
 
         gunzip clear-[version number]-[image type].gz
+
+.. incl-decompress-image-end:

source/clear-linux/guides/maintenance/download-verify-decompress-mac.rst

@@ -1,15 +1,15 @@
-.. _download-verify-uncompress-mac:
+.. _download-verify-decompress-mac:
 
-Download, verify, and uncompress a Clear Linux image on macOS\*
-###############################################################
+Download, verify, and decompress a |CL-ATTR| image on macOS\*
+#############################################################
 
-This guide describes the types of |CLOSIA| images available, where to download
-them, how to verify the integrity of an image, and how to uncompress it.
+This guide describes the types of |CL| images available, where to download
+them, how to verify the integrity of an image, and how to decompress it.
 
 Instructions for other operating systems are available:
 
-* :ref:`download-verify-uncompress-linux`
-* :ref:`download-verify-uncompress-windows`
+* :ref:`download-verify-decompress-linux`
+* :ref:`download-verify-decompress-windows`
 
 Image types
 ***********
@@ -19,8 +19,8 @@ Image types
 
 .. _verify-mac:
 
-Verify the integrity of the Clear Linux image
-*********************************************
+Verify the integrity of the |CL| image
+**************************************
 
 Before you use a downloaded |CL| image, verify its integrity. This action
 eliminates the small chance of a corrupted image due to download issues. To
@@ -41,16 +41,16 @@ If the checksum of the downloaded image is different than the original
 checksum, the differences will be displayed. Otherwise, an empty output indicates
 a match and your downloaded image is good.
 
-Uncompress the Clear Linux image
-********************************
+Decompress the |CL| image
+*************************
 
 We compress all released |CL| images by default with either GNU zip 
 (`.gz`) or xz (`.xz`). The compression type we use depends on the target 
-platform or environment. To uncompress the image, follow these steps:
+platform or environment. To decompress the image, follow these steps:
 
 #. Start the Terminal app.
 #. Go to the directory with the downloaded image.
-#. Use the :command:`gunzip` command to uncompress either compression type. For example:
+#. Use the :command:`gunzip` command to decompress either compression type. For example:
 
    .. code-block:: bash
 

source/clear-linux/guides/maintenance/download-verify-decompress-windows.rst

@@ -1,15 +1,15 @@
-.. _download-verify-uncompress-windows:
+.. _download-verify-decompress-windows:
 
-Download, verify, and uncompress a Clear Linux image on Windows\*
-#################################################################
+Download, verify, and decompress a |CL-ATTR| image on Windows\*
+###############################################################
 
-This guide describes the types of |CLOSIA| images available, where to download
-them, how to verify the integrity of an image, and how to uncompress it.
+This guide describes the types of |CL-ATTR| images available, where to download
+them, how to verify the integrity of an image, and how to decompress it.
 
 Instructions for other operating systems are available:
 
-* :ref:`download-verify-uncompress-linux`
-* :ref:`download-verify-uncompress-mac`
+* :ref:`download-verify-decompress-linux`
+* :ref:`download-verify-decompress-mac`
 
 Image types
 ***********
@@ -19,8 +19,8 @@ Image types
 
 .. _verify-windows:
 
-Verify the integrity of the Clear Linux image
-*********************************************
+Verify the integrity of the |CL| image
+**************************************
 
 Before you use a downloaded |CL| image, verify its integrity. This action
 eliminates the small chance of a corrupted image due to download issues. To
@@ -39,19 +39,19 @@ checksum file designated with the suffix `-SHA512SUMS`.
 #.  Manually compare the output with the original checksum value shown in
     the downloaded checksum file and make sure they match.
 
-Uncompress the Clear Linux image
+Decompress the |CL| image
 ********************************
 
 Released |CL| images are compressed with either GNU zip (*.gz*) or XZ
 (*.xz*). The compression type depends on the target platform or
-environment. To uncompress the image, follow these steps:
+environment. To decompress the image, follow these steps:
 
 #. Download and install `7-Zip`_.
 #. Go to the directory with the downloaded image and right-click it.
 #. From the pop-up menu, select :guilabel:`7-Zip` and select
    :guilabel:`Extract Here` as shown in Figure 1.
 
-   .. figure:: figures/download-verify-uncompress-windows-fig-1.png
+   .. figure:: figures/download-verify-decompress-windows-fig-1.png
       :scale: 80 %
       :alt: 7-Zip extract file
 

source/clear-linux/guides/maintenance/enable-user-space.rst

@@ -41,19 +41,16 @@ and to perform system updates called software update utility or
 :command:`swupd`. Software applications are installed as bundles using the
 sub-command :command:`bundle-add`.
 
-The `os-clr-on-clr` bundle installs the vast majority of
-applications useful to a system administrator or a developer. The bundle
-contains other bundles such as `sysadmin-basic`, `editors`, `c-basic`,
-`dev-utils-dev`, and other useful packages.
-
-Install the `os-clr-on-clr` bundle:
+The `sysadmin-basic` bundle installs the vast majority of
+applications useful to a system administrator.
+Install the `sysadmin-basic` bundle:
 
 .. code-block:: bash
 
-   swupd bundle-add os-clr-on-clr
+   swupd bundle-add sysadmin-basic
 
 We provide the full list of bundles and packages installed with the
-`os-clr-on-clr`_ bundle. Additionally, we have listed
+`sysadmin-basic`_ bundle. Additionally, we have listed
 `all Clear Linux bundles`_, active or deprecated. Click any bundle on the
 list to view the manifest of the bundle.
 
@@ -81,8 +78,8 @@ To be able to execute all applications with root privileges, add the
 #. Enter the new `<userid>` and the password created earlier.
 
    You will now be in the home directory of `<userid>`. The bundle
-   `os-clr-on-clr`_ contains the majority of applications that a developer or
-   system administrator would want, but it does not include a graphical user
+   `sysadmin-basic`_ contains the majority of applications that a system
+   administrator would want, but it does not include a graphical user
    interface. The `desktop` bundle includes the GNOME\* Display Manager and
    additional supporting applications.
 
@@ -136,8 +133,8 @@ With your system now running |CL|, many opportunities exist.
 Visit the :ref:`tutorials <tutorials>` page for examples on using your |CL|
 system.
 
-.. _`os-clr-on-clr`:
-   https://github.com/clearlinux/clr-bundles/blob/master/bundles/os-clr-on-clr
+.. _`sysadmin-basic`:
+   https://github.com/clearlinux/clr-bundles/blob/master/bundles/sysadmin-basic
 
 .. _`all Clear Linux bundles`:
    https://github.com/clearlinux/clr-bundles/tree/master/bundles

source/clear-linux/guides/maintenance/hostname.rst

@@ -0,0 +1,74 @@
+.. _hostname:
+
+Modify hostname on |CL-ATTR|
+############################
+
+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 
+names:
+
+* *regression-test*
+* *sally-test-box1*
+* *az-bldg2-lab*
+
+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. 
+
+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
+
+   sudo hostnamectl set-hostname telemetry-test-2-h15
+   sudo reboot
+
+.. 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.  
+
+   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.
+
+View your hostname
+******************
+
+View your current hostname using the following command:
+
+.. code-block:: bash
+
+   hostnamectl
+
+You should see output similar to:
+
+.. code-block:: console
+
+   Static hostname   : telemetry-test-2-h15
+   Pretty hostname   : telemetry-test-2-h15
+   Icon name         : computer-desktop
+   Chassis           : desktop
+   Machine ID        : 4d0d60207a904ebbab96680a51ac1339
+   Boot ID           : 98d3514e5a984e8cbbdf46a2f0d6b397
+   Operating System  : Clear Linux OS
+   Kernel            : Linux 4.18.8-632.native
+   Architecture      : x86-64
+
+ 
+**Congratulations!** You successfully modified the hostname of your |CL| system.

source/clear-linux/guides/maintenance/maintenance.rst

@@ -3,8 +3,9 @@
 Maintenance guide
 #################
 
-This guide provides step-by-step instructions for common tasks associated with
-maintaining |CLOSIA| after :ref:`installation <get-started>` is completed.
+These guides provide step-by-step instructions for common tasks associated
+with maintaining |CL-ATTR| after :ref:`installation <get-started>` is
+completed.
 
 .. toctree::
    :maxdepth: 2
@@ -17,10 +18,10 @@ maintaining |CLOSIA| after :ref:`installation <get-started>` is completed.
    mixer
    mixin
    validate-signatures
-   telemetry-enable
    time
+   hostname
    increase-virtual-disk-size
-   download-verify-uncompress-linux
-   download-verify-uncompress-mac
-   download-verify-uncompress-windows
+   download-verify-decompress-linux
+   download-verify-decompress-mac
+   download-verify-decompress-windows
    autospec

source/clear-linux/guides/maintenance/mixer.rst

@@ -1,10 +1,10 @@
 .. _mixer:
 
-Use mixer tool
-##############
+Use the mixer tool
+##################
 
 *Mixing* refers to composing an operating system for specific use cases.
-While the default |CLOSIA| provides options to install bundles for various
+While the default |CL-ATTR| provides options to install bundles for various
 server capabilities, some developers may wish to either augment the
 operating system itself with functionality from their own packages or modify
 the structure of current bundles to cater to their particular needs.
@@ -22,24 +22,26 @@ add it with the :command:`swupd bundle-add` command as follows:
 
 Current mixing workflow
 ***********************
+Mixer by default runs *all* build commands in a container to ensure the
+correct version of the tooling is being used. This also allows custom mixes
+to automatically perform downstream format bumps when upstream releases
+a format bump. You can still run mixer natively by appending the *--native* flag to
+any of the commands. 
+
+.. note::
+  You cannot run mixer if you are already in a container, unless you pass 
+  *--native* to the command. Nested containerization is not supported, nor 
+  is building images using the container mode.
 
 There are two different workflows to create your own mix.
-First, if your mix only uses |CL| content, *skip step 5* below. 
+First, if your mix only uses |CL| content, *skip Create custom RPMs* below. 
 Second, if your mix includes your own 
-:abbr:`RPMs (RPM Package Manager files)`, follow all these steps. 
+:abbr:`RPMs (RPM Package Manager files)`, follow all steps below. 
 
-#. `Create ngninx web server to host mixer updates`_
-#. `Create a workspace`_
-#. `Generate the starting point for your mix`_
-#. `Edit builder.conf`_
-#. `Create custom RPMs`_
-    #. `Create or locate RPMs for the mix`_
-    #. `Import RPMs into workspace`_
-    #. `Create a local RPM repo`_
-#. `List, edit, create, add, remove, or validate bundles`_
-#. `Build the bundle chroots`_
-#. `Create an update`_
-#. `Create an image`_
+.. contents:: 
+   :local:
+   :depth: 1
+   :backlinks: top
 
 The following sections contain detailed information on every step of
 these workflows.
@@ -47,12 +49,12 @@ these workflows.
 .. _create-nginx-web-server:
 
 Create nginx web server to host mixer updates
-**********************************************
+=============================================
 
 Follow these steps to set up a HTTP service with ``nginx`` web 
-server, where you can host custom |CL| mixes.  
+server, where you can host custom |CL| mixes:  
 
-#. Install ``web-server-basic``: 
+#. Install ``web-server-basic``. 
    
    .. code-block:: bash
 
@@ -115,7 +117,7 @@ server, where you can host custom |CL| mixes.
 
       sudo systemctl start nginx 
 
-#. To verify the web server is running, enter in an Internet browser:
+#. To verify the web server is running, check it in an Internet browser:
 
    .. code-block:: bash
 
@@ -133,7 +135,7 @@ server, where you can host custom |CL| mixes.
       and a few worker processes.
 
 Connect the URL to mixer
-========================
+------------------------
 
 Add the URL of the `nginx` server to builder.conf. Your |CL| clients connect 
 to this URL to find the update content.    
@@ -158,7 +160,7 @@ to this URL to find the update content.
          VERSIONURL=http://192.168.25.52
 
 Create a workspace
-******************
+==================
 
 Use the following command to create an empty directory in your |CL| image to
 use as a **workspace** for mixing:
@@ -170,7 +172,7 @@ use as a **workspace** for mixing:
 This guide assumes your workspace location is :file:`/home/clr/mix`.
 
 Generate the starting point for your mix
-****************************************
+========================================
 
 In your workspace, initialize mixer with the following command:
 
@@ -191,7 +193,7 @@ For example:
 
 .. code-block:: bash
 
-   mixer init --clear-version 21060 --mix-version 100
+   mixer init --upstream-version 21060 --mix-version 10
 
 
 Additionally, to build a mix with your own custom RPMs, use the optional
@@ -228,10 +230,10 @@ up automatically with the optional *--git* flag, for example:
 
    .. code-block:: bash
 
-      mixer init --clear-version 21060 --mix-version 100 --local-rpms --all-upstream --git
+      mixer init --upstream-version 21060 --mix-version 10 --local-rpms --all-upstream --git
 
 Edit builder.conf
-*****************
+=================
 
 To configure the mixer tool, edit the :file:`builder.conf` as needed.
 
@@ -260,26 +262,29 @@ following example:
 
 .. code-block:: console
 
-   [Mixer]
-   LOCAL_BUNDLE_DIR=/home/clr/mix/local-bundles
+   #VERSION 1.0
 
    [Builder]
-   SERVER_STATE_DIR=/home/clr/mix/update
-   BUNDLE_DIR=/home/clr/mix/mix-bundles
-   YUM_CONF=/home/clr/mix/.yum-mix.conf
-   CERT=/home/clr/mix/Swupd_Root.pem
-   VERSIONS_PATH=/home/clr/mix
+     CERT = "/home/clr/mix/Swupd_Root.pem"
+     SERVER_STATE_DIR = "/home/clr/mix/update"
+     VERSIONS_PATH = "/home/clr/mix"
+     YUM_CONF = "/home/clr/mix/.yum-mix.conf"
 
-   [swupd]
-   BUNDLE=os-core-update
-   CONTENTURL=<URL where the content will be hosted>
-   VERSIONURL=<URL where the version of the mix will be hosted>
-   FORMAT=1
+   [Swupd]
+     BUNDLE = "os-core-update"
+     CONTENTURL = "<URL where the content will be hosted>"
+     VERSIONURL = "<URL where the version of the mix will be hosted>"
 
    [Server]
-   debuginfo_banned=true
-   debuginfo_lib=/usr/lib/debug/
-   debuginfo_src=/usr/src/debug/
+     DEBUG_INFO_BANNED = "true"
+     DEBUG_INFO_LIB = "/usr/lib/debug"
+     DEBUG_INFO_SRC = "/usr/src/debug"
+
+   [Mixer]
+     LOCAL_BUNDLE_DIR = "/home/clr/mix/local-bundles"
+     LOCAL_REPO_DIR = ""
+     LOCAL_RPM_DIR = ""
+     DOCKER_IMAGE_PATH = "clearlinux/mixer"
 
 The following variables require further explanation:
 
@@ -292,13 +297,6 @@ The following variables require further explanation:
   content. Mixer automatically creates the path for you, but the path can be
   set to any location. In this example, we use the workspace directory.
 
-* The `BUNDLE_DIR` variable sets the path where mixer temporarily stores the
-  bundle definition files while building chroots. Only the legacy
-  chroot-builder uses this path. By default, mixer does not generate this
-  directory until the directory is needed. In our example, the path is set to
-  :file:`/home/clr/mix/mix-bundles`. The new chroot-builder does not generate
-  the folder at all.
-
 * The `YUM_CONF` variable sets the path where mixer automatically generates
   the :file:`.yum-mix.conf` yum configuration file. The yum configuration 
   file points the chroot-builder to the path where the RPMs are stored.
@@ -333,24 +331,23 @@ The following variables require further explanation:
   from where to download the updated content. These links are equivalent
   to the |CL| `update page`_ but for the mix.
 
-* The `FORMAT` variable relates to format bumps. To learn more about the
-  `FORMAT` option, refer to :ref:`mixer-format` and the `format bumps wiki`_.
-  For now, leave the `FORMAT` value unchanged.
-
 * The `VERSIONS_PATH` variable sets the path for the mix version and upstream
   |CL| version's two state files: :file:`mixversion` and
   :file:`upstreamversion`. Mixer creates both files for you when you set up
   the workspace.
 
+* The `DOCKER_IMAGE_PATH` variable sets the base name of the docker image
+  mixer will pull down in order to run builds in the proper container.
+
 .. note:: If you are working only with |CL| bundles, then
    skip to `List, edit, create, add, remove, or validate bundles`_.
 
 
 Create custom RPMs
-******************
+==================
 
 Create or locate RPMs for the mix
-=================================
+---------------------------------
 
 If you create RPMs from scratch, you can use `autospec`, `mock`, `rpmbuild`,
 or similar tools to build them. If the RPMs are not built on |CL|, ensure
@@ -359,7 +356,7 @@ there is no guarantee they will be compatible. For more information on
 building the RPMs properly, refer to our `build RPMs instructions`_.
 
 Import RPMs into workspace
-==========================
+--------------------------
 
 #. Create a :file:`local-rpms` directory in your workspace, for example,
    :file:`/home/clr/mix/local-rpms`.
@@ -376,7 +373,7 @@ Mixer uses this directory to find the RPMs to build a local RPM repo for
 yum to use.
 
 Create a local RPM repo
-=======================
+-----------------------
 
 #. Create an empty directory in your workspace named :file:`local-yum`.
 #. Add the path to your :file:`builder.conf` file:
@@ -390,7 +387,7 @@ Create a local RPM repo
 
    .. code-block:: bash
 
-      sudo mixer add-rpms
+      mixer add-rpms
 
 After the tool exits, you should see the RPMs and a repository data
 directory in :file:`/home/clr/mix/local-yum`. If the RPMs are not all in this
@@ -398,7 +395,7 @@ directory in :file:`/home/clr/mix/local-yum`. If the RPMs are not all in this
 and not corrupt.
 
 List, edit, create, add, remove, or validate bundles
-****************************************************
+====================================================
 
 The bundles in the mix are specified in the mix bundle list. Mixer stores
 this list as a flat file called :file:`mixbundles` in the path set by the
@@ -408,7 +405,7 @@ initialization. Mixer reads and writes the bundle list file when you change
 the bundles of the mix.
 
 List the bundles in the mix
-===========================
+---------------------------
 
 To view the bundles already in the mix, enter the following command:
 
@@ -468,7 +465,7 @@ Both the local and upstream :command:`bundle list` commands accept the
 between the bundles in the mix.
 
 Edit the bundles in the mix
-===========================
+---------------------------
 
 **Mixer always checks local bundles first and the upstream bundles second.**
 
@@ -504,7 +501,7 @@ can edit multiple bundles with the following command:
    mixer bundle edit bundle1 bundle2 [bundle3 ...]
 
 Create bundles for the mix
-==========================
+--------------------------
 
 To create a totally **new bundle**, the bundle name you specify cannot exist
 upstream. If that is the case, create a :file:`new-bundle` with the following
@@ -531,7 +528,7 @@ as part of the bundle.
       mixer bundle edit new-bundle1 new-bundle2 [new-bundle3 ...]
 
 Add bundles to the mix
-======================
+----------------------
 
 Add `bundle1` to your mix with the following command:
 
@@ -554,7 +551,7 @@ To add multiple bundles at once, use the following command:
    mixer bundle add bundle1 bundle2 [bundle3 ...]
 
 Remove bundles from the mix
-===========================
+---------------------------
 
 Remove `bundle1` from your mix with the following command:
 
@@ -589,7 +586,7 @@ keep the bundle in the mix bundles list, mixer will not find a valid
 bundle definition file and will produce an error.
 
 Validate the bundles in the mix
-===============================
+-------------------------------
 
 Mixer performs basic validation on all bundles when used throughout the
 system.
@@ -621,7 +618,7 @@ Validate multiple bundles with the following command:
    mixer bundle validate bundle1 bundle2 [bundle3 ...]
 
 Managing bundles with Git
-=========================
+-------------------------
 
 If you initialized your workspace to be tracked as a git repository
 with the :command:`mixer init --git` command, it might be useful to apply a
@@ -637,63 +634,43 @@ when the command completes, for example:
    mixer bundle remove --git bundle1
 
 Build the bundle chroots
-************************
+========================
 
 To build all the ``chroots`` based on the defined bundles, use the following
 command in your workspace:
 
 .. code-block:: bash
 
-   sudo mixer build chroots
+   mixer build bundles 
 
 If the mix has many bundles, this step might take some time.
 
-By default, mixer uses the legacy chroot-builder. In this mode, mixer
-automatically gathers the bundle definition files for the bundles in the mix
-into a :file:`mix-bundles` directory. The directory's path is set in the
-`BUNDLE_DIR` variable in the :file:`builder.conf`. **Do not edit these
-files.** Mixer automatically deletes the contents of the :file:`mix-bundles`
-directory before repopulating the directory on-the-fly as mixer builds the
-chroots.
+Mixer automatically gathers the bundle definition files for the upstream
+bundles into a :file:`upstream-bundles` directory, and user bundles should
+be placed directly into :file:`local-bundles`. The local path is set in
+the `LOCAL_BUNDLE_DIR` variable in the :file:`builder.conf`. **Do not edit
+files in upstream-bundles.** Mixer automatically deletes the contents of
+the :file:`upstream-bundles` directory before repopulating the directory
+on-the-fly if a new version must be downloaded.
 
-We have added a new chroot-builder to the mixer tool itself. While this is
-currently an experimental feature, you should use the new chroot-builder. To
-use the new chroot-builder, use the following command with the
-*--new-chroots* flag:
-
-.. code-block:: bash
-
-   sudo mixer build chroots --new-chroots
-
-We will soon deprecate the legacy chroot-builder. When we do, mixer will use
-the new version automatically.
 
 Create an update
-****************
+================
 
 Create an update with the following command:
 
 .. code-block:: bash
 
-   sudo mixer build update
+   mixer build update
 
 When the build completes, you can find the mix update content under
 :file:`/home/clr/mix/update/www/VER`. In our example, the update content is
 found in :file:`/home/clr/mix/update/www/{<MIXVERSION>}`. `<MIXVERSION>`
 is the defined mix version, which is 10 by default.
 
-By default, mixer uses the legacy `swupd-server` to generate the update
-content. However, we have built a new implementation into the mixer tool
-itself. While this is currently an experimental feature, you should use the
-new `swupd-server`. To use the the new `swupd-server`, use the following
-command with the *--new-swupd* flag:
-
 .. code-block:: bash
 
-   sudo mixer build update --new-swupd
-
-We will soon deprecate the legacy `swupd-server`. When we do, mixer will use
-the new version automatically.
+   mixer build update 
 
 Mixer creates all the content needed to make a fully usable mix with this
 step. However, only *zero packs* are automatically generated. Zero packs are
@@ -705,19 +682,18 @@ mix version to another, with the following command:
 
 .. code-block:: bash
 
-   sudo mixer-pack-maker.sh --to <MIX_VERSION> --from <PAST_VERSION> -S /home/clr/mix/update
+   mixer build delta-packs --to <MIX_VERSION> --from <PAST_VERSION>
 
-The pack-maker generates all delta packs for the bundles changed from
-`PAST_VERSION` to `MIX_VERSION`. If your `STATE_DIR` is in a different
-location, specify the location with the *-S* flag. Mixer cannot
-create delta packs for the first build because the update is from version 0.
-Version 0 implicitly has no content. Thus, mixer can generate no deltas.
+This command generates all delta packs for the bundles changed from
+`PAST_VERSION` to `MIX_VERSION`. Mixer cannot create delta packs for the
+first build because the update is from version 0. Version 0 implicitly has
+no content, thus mixer can generate no deltas.
 
 For subsequent builds, you can run :file:`mixer-pack-maker.sh` to generate
 delta content between them, for example: 10 to 20.
 
 Create an image
-*****************
+===============
 
 Since mixer uses the `ister` tool to create a bootable image from your
 updated content, we must first configure the `ister` tool. To configure the
@@ -755,7 +731,7 @@ With the `ister` tool configured, build the image with the following command:
 
 .. code-block:: bash
 
-   sudo mixer build image --format 1
+   sudo mixer build image
 
 Mixer automatically looks for the :file:`release-image-config.json` file, but
 you can freely choose the filename. To use a different name, simply pass the
@@ -763,7 +739,7 @@ you can freely choose the filename. To use a different name, simply pass the
 
 .. code-block:: bash
 
-   sudo mixer build image --format 1 --template path/to/file.config
+   sudo mixer build image --template path/to/file.config
 
 By default, `ister` uses the format version of the build machine it runs on.
 Therefore, if the format you are building differs from the format of the |CL|
@@ -775,7 +751,7 @@ flag. Find the current format version of your OS with the following command:
    sudo cat /usr/share/defaults/swupd/format
 
 Update the next mix version information
-***************************************
+=======================================
 
 Increment the mix version number for the next mix with the following command:
 
@@ -789,14 +765,14 @@ amount, use the *--increment* flag, for example:
 
 .. code-block:: bash
 
-   mixer versions update --increment 100
+   mixer versions update --increment 10
 
 Alternatively, to set the mix version to a specific value, use the
 *--mix-version* flag, for example:
 
 .. code-block:: bash
 
-   mixer versions update --mix-version 200
+   mixer versions update --mix-version 20
 
 The :command:`mixer versions update` command does not allow you to set the
 mix version to a value less than its current value. The mix version is
@@ -842,25 +818,24 @@ modifications as needed, for example:
 
    .. code-block:: bash
 
-      sudo mixer build chroots
+      mixer build chroots
 
 #. Build and update with:
 
    .. code-block:: bash
 
-      sudo mixer build update
+      mixer build update
 
 #. Optionally, you can create delta packs with:
 
    .. code-block:: bash
 
-      sudo mixer-pack-maker.sh --to <NEWVERSION> --from <PREV_VERSION> -S /
-      home/clr/mix/update
+      mixer build delta-packs --to <NEWVERSION> --from <PREV_VERSION>
 
 .. _mixer-format:
 
 Format version
-**************
+==============
 
 The `Format` variable set in the :file:`builder.conf` file can be more
 precisely referred to as an OS *compatibility epoch*. Versions of the OS
@@ -881,9 +856,10 @@ reaching the final release in the old format can a client continue to update
 to releases in the new format.
 
 When creating a custom mix, the format version should start at "1" or some
-known number. The format version should increment only when a compatibility
-breakage is introduced. Normal updates, like updating a software package for
-example, do not require a format increment.
+known number such as the host system format. The format version should
+increment only when a compatibility breakage is introduced. Normal updates,
+like updating a software package for example, do not require a format
+increment.
 
 .. _update page: https://cdn.download.clearlinux.org/update/
 

source/clear-linux/guides/maintenance/telemetry-enable.rst

@@ -1,116 +0,0 @@
-.. _telemetry-enable:
-
-Enable and disable telemetry in Clear Linux
-###########################################
-
-|CL| 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
-daemon, **telemd**. 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:`telemd` daemon 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

source/clear-linux/guides/network/custom-clear-container.rst

@@ -370,9 +370,4 @@ Example output:
     ---> ec23189ef954
    Removing intermediate container 7694989e97de
    Successfully built ec23189ef954
-   Successfully tagged my-clearlinux-remove-pxe-server-bundle:latest
-
-For more details, refer to:
-
-* :ref:`cc-getting-started`
-* :ref:`architecture-overview`
+   Successfully tagged my-clearlinux-remove-pxe-server-bundle:latest

source/clear-linux/guides/telemetrics/telemctl.rst

@@ -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`

source/clear-linux/guides/telemetrics/telemetrics.rst

@@ -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

source/clear-linux/guides/telemetrics/telemetry-config.rst

@@ -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`

source/clear-linux/guides/telemetrics/telemetry-enable.rst

@@ -0,0 +1,114 @@
+.. _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

source/clear-linux/guides/telemetrics/telemetry-journal.rst

@@ -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`

source/clear-linux/guides/telemetrics/telemetry-z-api.rst

@@ -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/

source/clear-linux/reference/bundle-commands.rst

@@ -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:
 

source/clear-linux/reference/bundles/bundles.html

@@ -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>

source/clear-linux/reference/bundles/bundles.rst

@@ -3,18 +3,8 @@
 Available bundles
 #################
 
-This document provides a current list of `available bundles`_ as 
-of ``12 September 2018``.                                      
-
-See in depth descriptions of the following bundles:
-
-.. toctree::
-   :maxdepth: 1
-
-   containers-basic
-   openssh-server
-   os-core
-   kvm-host
+This document provides a current list of `available bundles`_ as
+of ``12 September 2018``.
 
 Bundle list
 ===========

source/clear-linux/reference/bundles/containers-basic.rst

@@ -1,41 +0,0 @@
-.. _containers-basic:
-
-containers-basic
-################
-
-The `containers-basic` bundle adds the necessary tools to enable running
-containers using Docker*. The bundle includes Intel® |CC| as an
-additional Docker runtime.
-
-|CC| enable a hardware backed :abbr:`VM (Virtual Machine)` based
-container runtime, compared with the normal software namespace containers
-provided by standard Docker `runc` runtime.
-
-Default runtime
-===============
-If your system has `VT-x` enabled, then, under |CL|, |CC|
-will be used as the default Docker runtime, otherwise, the standard Docker
-`runc` runtime will be used.
-
-To identify which runtimes are available and which is being used as
-the default on your installed system, run the following command.
-
-.. code-block:: console
-
-   sudo docker info | grep Runtime
-
-The |CC| runtime will be listed as `cor`.
-
-For more information on |CC| please see the
-`Clear Containers runtime GitHub`_.
-
-Working with a proxy
-====================
-
-If you are behind an HTTP proxy server, in a corporate
-setting for example, please follow the `Docker proxy instructions`_.
-
-.. _Clear Containers runtime GitHub: https://github.com/01org/cc-oci-runtime
-
-.. _Docker proxy instructions:
-   https://docs.docker.com/engine/admin/systemd/#http-proxy

source/clear-linux/reference/bundles/kvm-host.rst

@@ -1,42 +0,0 @@
-.. _bdl-kvm-host:
-
-kvm-host
-########
-
-This bundle provides the software needed to run virtual machines.
-
-QEMU
-====
-
-|CL| provides :abbr:`QEMU (Quick Emulator)` to perform hardware virtualization.
-When possible, qemu would be used together with
-:abbr:`KVM (Kernel-based Virtual Machine)` in order to run virtual machines at
-near-native speed.
-
-For more information about how to use qemu, please refer to `qemu.org`_
-
-virsh
-=====
-
-|CL| provides the virsh program to manage `libvirt`_ guests and the hypervisor.
-libvirtd management daemon is not enabled nor started by default. To enable
-the hypervisor, perform the following commands as root.
-
-#. Enable the service to start every time the machine boots.
-   This step is optional
-
-   .. code-block:: console
-
-      # systemctl enable libvirtd.service
-
-#. Start the libvirtd management daemon service
-
-   .. code-block:: console
-
-      # systemctl start libvirtd.service
-
-Congratulations! The libvirtd management daemon is running and virsh is ready
-to be used.
-
-.. _qemu.org: http://www.qemu.org/
-.. _libvirt: http://libvirt.org/

source/clear-linux/reference/bundles/openssh-server.rst

@@ -1,57 +0,0 @@
-.. _bdl-openssh-server:
-
-openssh-server
-##############
-
-This bundle provides the OpenSSH\* package needed to enable a SSH service.
-Remote users require a SSH service to be able to use an encrypted login
-shell. The first time OpenSSH starts, it generates the server SSH keys needed
-for the service.
-
-SFTP
-====
-
-|CL| *disables* the :abbr:`SFTP (SSH File Transfer Protocol)` subsystem by
-default due to security considerations. To enable the SFTP subsystem, perform
-the following configuration of the :abbr:`SSHD (SSH Daemon)` service file:
-
-#. Create a systemd drop-in directory for the SSHD service:
-
-   .. code-block:: console
-
-      # mkdir -p /etc/systemd/system/sshd@.service.d
-
-#. Create the following file:
-   :file:`/etc/systemd/system/sshd@.service.d/sftp.conf`
-
-#. Add the OPTIONS environment variable
-
-   .. code-block:: console
-
-      [Service]
-      Environment="OPTIONS=-o Subsystem=\"sftp /usr/libexec/sftp-server\""
-
-#. Reload systemd configuration:
-
-   .. code-block:: console
-
-      # systemctl daemon-reload
-
-Congratulations! The SFTP subsystem is enabled.
-
-Root login
-==========
-
-To enable root login via ssh, perform the following steps:
-
-#. Create a *ssh* directory in :file:`/etc`, only if it does not exist)
-
-   .. code-block:: console
-
-      # mkdir /etc/ssh
-
-#. Set the configuration variable.
-
-   .. code-block:: console
-
-      # echo "PermitRootLogin yes" >> /etc/ssh/sshd_config

source/clear-linux/reference/bundles/os-core.rst

@@ -1,106 +0,0 @@
-.. _os-core:
-
-os-core
-#######
-
-This bundle contains the basic core components of the operating system.
-|CLOSIA| relies on `systemd` to provide the basic OS components. The
-`systemd` package contains solutions for:
-
-* Service management
-* Basic network management
-* Hostname management
-* Time synchronization management
-* Boot control management
-* Journal management
-
-Additionally, `os-core` includes the `util-linux` and `coreutils` packages to
-provide a set of basic Linux\* command line tools such as `ls`, `cp`, `rm`,
-etc.
-
-
-Static IP
-=========
-
-To configure a static IP, follow these steps:
-
-#. Create the file: :file:`/etc/systemd/network/50-static.network` If the
-   path does not exist, create it.
-
-#. Add, at the very least, the following lines to the
-   :file:`50-static.network` file:
-
-   .. code-block:: console
-
-      [Match]
-      Name=<device_name>
-
-      [Network]
-      Address=<Provide a static IPv4 or IPv6 address with its
-      prefix length. Separate them with the "/" character.>
-      Gateway=<The gateway's address>
-
-   The `<device_name>` is your network device name, for example: enp1s0 or
-   enp0s25.
-
-#. To add more options you can consult the `systemd network configuration`_
-   manual.
-
-#. Restart the *systemd-networkd* service with the following command:
-
-
-   .. code-block:: console
-
-      # systemctl restart systemd-networkd
-
-   Alternatively, restart |CL|.
-
-#. Check the new IP with the following command:
-
-   .. code-block:: console
-
-      # ip addr
-
-
-Setting time
-============
-
-Clear Linux uses the `systemd-timesyncd.service` service to synchronize the
-system's time. Default :abbr:`NTP (Network Time Protocol)` servers are
-configured, for example: `time1.google.com`, `time2.google.com`,
-`time3.google.com`, and `time4.google.com`. Manually setting the time via
-`timedatectl` or using RTC mode is not possible. If those servers cannot be
-reached and the system time is incorrect, follow these steps:
-
-#. Set the timezone, for example, Pacific time:
-
-   .. code-block:: console
-
-      timedatectl set-timezone America/Los_Angeles
-
-   To see a list of timezones, use the following command:
-
-   .. code-block:: console
-
-      timedatectl list-timezones
-
-#. Go to the :file:`/etc/systemd/` directory, if it does not exist, create
-   it.
-
-#. Create the :file:`/etc/systemd/timesyncd.conf` file and enter the
-   following lines:
-
-   .. code-block:: console
-
-      [Time]
-      NTP=<Preferred Server>
-      FallbackNTP=<backup server 1> <backup server 2>
-
-#. Restart the timesync daemon with the following command:
-
-   .. code-block:: console
-
-      # systemctl  restart systemd-timesyncd
-
-.. _systemd network configuration:
-   https://www.freedesktop.org/software/systemd/man/systemd.network.html

source/clear-linux/reference/collaboration/collaboration.rst

@@ -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,

source/clear-linux/reference/collaboration/documentation/code.rst

@@ -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:

source/clear-linux/reference/collaboration/documentation/contents.rst

@@ -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
 ============

source/clear-linux/reference/collaboration/documentation/cross.rst

@@ -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.  

source/clear-linux/reference/collaboration/documentation/documentation.rst

@@ -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.
 

source/clear-linux/reference/collaboration/documentation/grammar.rst

@@ -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