Revert "Merge of latest changes into RTD theme to enable multi-language support (#604)"

This reverts commit 186f1e02b8.

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

.gitignore

@@ -4,3 +4,6 @@ source/_build
 *.swp
 *~
 .*~
+
+# ignore VS code settings
+.vscode/

.gitlab-ci.yml

@@ -0,0 +1,19 @@
+image: alpine
+
+pages:
+  script:
+  - apk --no-cache add python3
+  - python3 -m ensurepip
+  - pip3 install sphinx==1.7.5 docutils==0.14 sphinx_rtd_theme breathe==4.9.1 sphinxcontrib-plantuml
+  - apk --no-cache add make
+  - apk --no-cache add doxygen
+  - apk --no-cache add graphviz
+  - apk --no-cache add ttf-dejavu 
+  - apk --no-cache add openjdk8-jre
+  - make html
+  - mv source/_build/html/ public/
+  artifacts:
+    paths:
+    - public
+  only:
+  - rtd-theme

README.rst

@@ -1,83 +1,74 @@
-Documentation Build Instructions
+Documentation build instructions
 ################################
 
-The `website documentation`_ for Clear Linux\* OS for Intel Architecture
-should be written in :abbr:`ReStructuredText (ReST)` AKA ``.rst``, which
-makes it easy to build parsable, command-line readable, indexed, and
-search-friendly documentation and APIs with `Sphinx`_.
+.. todo add comment re not using standards here.
 
-.. _requirements:
+`Clear Linux\* OS documentation`_ is written using `reStructuredText`_ and
+built using `Sphinx`_. Follow the instructions in this README to build the
+documentation locally for development and testing.
+
+Please make yourself familiar with our `contribution guidelines`_ before
+submitting a contribution.
 
 Requirements
-============
+************
 
-To build documentation with Sphinx, ensure your system has these
-prerequisites:
+Make sure you have Python and Sphinx installed. We use Python 3 and
+Sphinx 1.7.5
 
-* `GNU make`_
-* `Python`_
-* `PIP`_
-* `Sphinx`_
+The Sphinx documentation provides `instructions for installing Sphinx`_ on various
+platforms.
 
-The instructions for installing these varies according to OS. On a basic out-
-of-the-box Ubuntu-like OS (which usually has Python installed by default),
-check your python version you might need something like:
-
-.. code-block:: console
-
-   $ sudo apt-get install python-pip
-   $ sudo pip install -U sphinx sphinx-autobuild
-
-
-
-.. code-block:: console
-
-   $ python -c 'print __import__("sphinx").__version__'
-     1.3.1
-
-Cloning the documentation repository
-====================================
-
-We have confirmed Sphinx installed.  The next step is to clone Gitlab
-repository to our local machine.
+Clone the documentation repository
+**********************************
 
+Once Sphinx is installed, clone the documentation repository to your
+local machine.
 
 .. code-block:: console
 
    $ git clone https://github.com/clearlinux/clear-linux-documentation
 
-Run make
-========
+Run the build
+*************
 
-Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the
-:file:`source/` directory where your ``.rst`` files are, before
-running :command:`make html`, or the doc format of your choice.
+We build our documentation using Sphinx. In the source directory of your
+local clear-linux-documentation repository, build the documentation by running
+**make html**:
 
 .. code-block:: console
 
    $ make html
    >
    sphinx-build -b html -d _build/doctrees   . _build/html
-   Running Sphinx v1.3.1
+   Running Sphinx v1.7.5
    making output directory...
    .
    .
    .
    build succeeded, 0 warnings.
 
+   The HTML pages are in _build/html.
+
    Build finished. The HTML pages are in _build/html.
 
-Open one of the .html pages in a web browser to view the rendered
+Open one of the HTML pages in a web browser to view the rendered
 documentation.
 
-For tips on how to contribute documentation formatted in the .rst style
-needed to integrate beautifully on the clearlinux.org website, please see
- `Theming Sphinx`_.
+When testing changes in the documentation, make sure to remove the previous
+build before building again by running **make clean**:
 
+.. code-block:: console
 
-.. _website documentation:  https://clearlinux.org/documentation
+   $ make clean
+   >
+   rm -rf _build/*
+
+This will completely remove the previous build output.
+
+.. _Clear Linux\* OS documentation:  https://clearlinux.org/documentation
 .. _Sphinx: http://sphinx-doc.org/
-.. _GNU make: https://www.gnu.org/software/make/
-.. _Python: https://www.python.org/
-.. _PIP: https://pypi.python.org/pypi/pip/
-.. _Theming Sphinx: https://github.com/otcshare/tcs-hub/blob/master/theming-sphinx.rst
+.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _contribution guidelines: https://clearlinux.org/documentation/clear-linux/reference/collaboration
+.. _instructions for installing Sphinx: https://www.sphinx-doc.org/en/master/usage/installation.html
+

source/Makefile

@@ -6,6 +6,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
+SCRIPTDIR     = scripts/_python
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -56,6 +57,9 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+py:
+	$(MAKE) -C $(SCRIPTDIR) py
+
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
@@ -73,6 +77,7 @@ pickle:
 
 json:
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	$(MAKE) -C $(SCRIPTDIR) py
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
@@ -166,10 +171,8 @@ changes:
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
+	-$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	python3 scripts/_python/linkcheck/parse-link-check.py $(BUILDDIR)/linkcheck
 
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest

source/_themes/clearlinux/header.html

@@ -16,7 +16,7 @@
             <div class="region region-header">
               <div id="block-system-main-menu" class="block block-system block-menu">
                 <ul class="menu">
-                  <li class="first leaf"><a href="https://download.clearlinux.org" title="Downloads" target="_blank">Downloads</a></li>
+                  <li class="first leaf"><a href="https://cdn.download.clearlinux.org" title="Downloads" target="_blank">Downloads</a></li>
                   <li class="collapsed"><a href="/features" title="Features">Features</a></li>
                   <li class="collapsed"><a href="/documentation" title="Documentation" class="active">Documentation</a></li>
                 </ul>

source/_themes/otc_tcs_sphinx_theme/.gitignore

@@ -0,0 +1 @@
+__pycache__

source/_themes/otc_tcs_sphinx_theme/layout.html

@@ -0,0 +1,48 @@
+{% extends "sphinx_rtd_theme/layout.html" %}
+
+{% block extrahead %}
+
+<link rel="stylesheet" href="{{ pathto('_static/tcs_theme.css', 1) }}" type="text/css" />
+
+{% endblock %}
+
+{% block content %}
+
+<header id="header">
+  <div class="padding-md--left-right">
+
+    <div class="header__site_info">
+           <object class="header__site_img_object" type="image/svg+xml" data="https://stg.clearlinux.org/modules/custom/clearlinux_org/themes/clearlinux_theme/clear-technologies.svg"></object>
+           <div class="header__site_info_name">
+             <a href ="https://stg.clearlinux.org"> Clear Linux* Project</a>
+           </div>
+    </div>
+    <nav class="header__menu">
+        <ul class="header__menu_list">
+                         <li class="header__menu_list_item green  ">
+                <a tabindex='1' href="https://stg.clearlinux.org/about">About</a>
+              </li>
+                         <li class="header__menu_list_item purple  ">
+                <a tabindex='1' href="https://stg.clearlinux.org/developer">Developer</a>
+              </li>
+                         <li class="header__menu_list_item blue  ">
+                <a tabindex='1' href="https://stg.clearlinux.org/software">Software</a>
+              </li>
+        </ul>
+    </nav>
+
+  </div>
+
+
+
+</header>
+
+{{ super() }}
+
+{% endblock %}
+
+{% block footer %}
+
+<script type="text/javascript" src="{{ pathto('_static/tcs_theme.js', 1) }}"></script>
+
+{% endblock %}

source/_themes/otc_tcs_sphinx_theme/readme.rst

@@ -0,0 +1,28 @@
+OTC-TCS Sphinx Theme
+####################
+
+Built on top of the popular Read the Docs Sphinx theme, this theme
+has a few small formatting/color improvements and implements collapsible
+sections. It is in active development in order to support OTC and other
+Intel organizations to publish high quality, consistent documentation
+for open source projects.
+
+To see an example of documentation produced using this theme visit the
+`OTC-TCS Documentation`_ site. 
+
+How to use it
+*************
+
+#. Download or clone the repository
+#. Create a ``_themes`` directory in main directory of your sphinx
+   documentation
+#. Install sphinx_rtd_theme using pip: ``pip3 install sphinx_rtd_theme``
+#. copy ``otc_tcs_sphinx_theme`` directory into the new ``_themes`` directory
+#. Add the following to your ``conf.py``: 
+
+   .. code-block:: python
+
+       html_theme = 'otc_tcs_sphinx_theme'
+       html_theme_path = ['_themes']
+
+.. _OTC-TCS Documentation: https://github.intel.com/pages/otc-tcs/

source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.css

@@ -0,0 +1,252 @@
+/* -- Extra CSS styles for content (RTD theme) ----------------------- */
+
+/* make the page width fill the window */
+.wy-nav-content {
+   max-width: none;
+}
+
+
+.wy-nav-side {
+   background: #8e6db6;
+}
+/* (temporarily) add an under development tagline to the bread crumb
+.wy-breadcrumbs::after {
+   content: " (Content under development)";
+   background-color: #FFFACD;
+   color: red;
+   font-weight: bold;
+}
+*/
+
+/* code block highlight color in rtd changed to lime green, no no no */
+
+.rst-content tt.literal, .rst-content code.literal, .highlight {
+   background: #f0f0f0;
+}
+.rst-content tt.literal, .rst-content code.literal {
+    color: #000000;
+}
+
+/* Make the version number more visible */
+.wy-side-nav-search>div.version {
+    color: rgba(255,255,255,1);
+}
+
+/* squish the space between a paragraph before a list */
+div > p + ul, div > p + ol {
+   margin-top: -20px;
+}
+
+/* add some space before the figure caption */
+p.caption  {
+    border-top: 1px solid;
+    margin-top: 1em;
+}
+
+/* add a colon after the figure/table number (before the caption) */
+span.caption-number::after {
+   content: ": ";
+}
+
+p.extrafooter {
+   text-align: right;
+   margin-top: -36px;
+}
+
+table.align-center {
+   display: table !important;
+}
+
+
+.code-block-caption {
+    color: #000;
+    font: italic 85%/1 arial,sans-serif;
+    padding: 1em 0;
+    text-align: center;
+}
+
+/*  make .. hlist:: tables fill the page */
+table.hlist {
+    width: 95% !important;
+}
+
+/*  override rtd theme white-space no-wrap in table heading and content  */
+th,td {
+    white-space: normal !important;
+}
+
+/* tweak for doxygen-generated API headings (for RTD theme) */
+.rst-content dl.group>dt, .rst-content dl.group>dd>p {
+   display:none !important;
+}
+.rst-content dl.group {
+  margin: 0 0 12px 0px;
+}
+.rst-content dl.group>dd {
+  margin-left: 0  !important;
+}
+.rst-content p.breathe-sectiondef-title {
+  text-decoration: underline;  /* for API sub-headings */
+  font-size: 1.25rem;
+  font-weight: bold;
+  margin-bottom: 12px;
+}
+
+.rst-content div.breathe-sectiondef {
+  padding-left: 0 !important;
+}
+
+.clps1 {
+  font-size: 175%;
+}
+
+.clps2 {
+  font-size: 150%;
+}
+
+.clps3 {
+  font-size: 125%;
+}
+
+.clps4 {
+  font-size: 115%;
+}
+
+.clps5 {
+  font-size: 110%;
+}
+
+.clps6 {
+  font-size: 100%;
+}
+
+.collapsible {
+  margin-left: -10px;
+  background-color: #f1f1f1;
+  cursor: pointer;
+  padding: 18px 18px 18px 10px;
+  width: 100%;
+  border: none;
+  text-align: left;
+  outline: none;
+  font-weight: 700;
+  font-family: "Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif;
+}
+
+.collapsible:hover {
+  background-color: #d8d8d8;
+}
+
+.collapsible:after {
+  content: '\002B';
+  font-weight: bold;
+  float: right;
+  margin-left: 5px;
+}
+
+.active:after {
+  content: "\2212";
+}
+
+.content-collapse {
+  overflow: hidden;
+  transition: max-height 0.2s ease-out;
+}
+
+#header {
+    width: 100%;
+    display: block;
+    font-family: "IntelClear-Regular", Helvetica, Arial, sans-serif;
+    font-size: 16px;
+   }
+
+.padding-md--left-right {
+    padding-left: 2.6%;
+    padding-right: 2.6%;
+    display: flex;
+    justify-content: space-between;
+}
+
+.header__site_info {
+  display: inline-block;
+}
+
+.header__site_img_object {
+    height: 50px;
+}
+
+.header__site_info_name {
+    vertical-align: middle;
+    display: inline-block;
+    height: 50px
+}
+
+#header__site_info_name a:link {
+  color: black;
+}
+
+#header__site_info_name a:visited {
+  color: black;
+}
+
+.header__menu {
+    text-align: right;
+    display: inline-block;
+}
+
+.header__menu_list li {
+    display: inline;
+    margin-left: 20px;
+}
+
+.header__menu_list li a {
+  color: black;
+}
+
+.header__menu_list_item {
+    display: inline;
+    position: relative;
+    margin-bottom: 0;
+    margin-left: 0;
+    min-width: 1px;
+    max-width: 100%;
+    padding: 0;
+    text-align: left;
+    /*top: 35px;*/
+}
+
+.header__menu_list_item.green > a::before {
+    color: #009B93;
+}
+
+.header__menu_list_item.purple > a::before {
+    color: #6E4C9F;
+}
+
+.header__menu_list_item.blue > a::before {
+    color: #358CCB;
+}
+
+.header__menu_list_item > a::before {
+    content: '•';
+    font-size: 35px;
+    margin-right: 10px;
+    position: relative;
+    top: 5px;
+    left: 5px;
+}
+
+.header__banner {
+   width: 120%;
+   margin-left: -3.236em;
+   background-image: url(https://stg.clearlinux.org/sites/default/files/bg_developer_0.png);
+}
+
+.header__banner_title {
+   display: block;
+   color: white;
+   font-size: 36px;
+   font-family: "IntelClear-Bold", Helvetica, Arial, sans-serif;
+   margin-left: 0.67em;
+   line-height: 100px;
+}

source/_themes/otc_tcs_sphinx_theme/static/tcs_theme.js

@@ -0,0 +1,50 @@
+var i;
+var contents = document.getElementsByClassName("content-collapse section");
+
+for (i = 0; i < contents.length; i++) {
+
+  //Make sure the "content-collapse section" class is occurring in <div>
+  if (contents[i].tagName.toLowerCase() == 'div') {
+    var element = contents[i].children[0];
+    var element_type = element.tagName.toLowerCase();
+    var span_id;
+    var spanElement;
+
+    //if the next element is a span grab the id and skip to the header
+    if (element_type == 'span') {
+      span_id = element.id;
+      element.id = "";
+      element = contents[i].children[1];
+      element_type = element.tagName.toLowerCase();
+    }
+
+    var btn = document.createElement("BUTTON");
+    //If it is a header capture which level and pass on to button
+    if (element_type.length == 2 && element_type[0] == 'h') {
+      var newClass = 'clps' + element_type[1];
+      //collapses the section by default only if javascript is working
+      contents[i].style.maxHeight = 0;
+      //Build the button and define behavior
+      btn.className += " " + newClass;
+      btn.innerHTML = element.innerHTML;
+      btn.className += " collapsible";
+      btn.id = span_id;
+      btn.addEventListener("click", function() {
+        this.classList.toggle("active");
+        var content = this.nextElementSibling;
+        if (content.style.maxHeight != "0px"){
+          content.style.maxHeight = 0;
+        } else {
+          content.style.maxHeight = content.scrollHeight + "px";
+        } 
+      });
+
+      //Add the button to the page and remove the header
+      contents[i].parentNode.insertBefore(btn, contents[i]);
+      contents[i].removeChild(element);
+    }else{
+      //reset span id if it isn't followed by Hx element
+      spanElement.id = span_id;
+    }
+  }
+}

source/_themes/otc_tcs_sphinx_theme/theme.conf

@@ -0,0 +1,2 @@
+[theme]
+inherit = sphinx_rtd_theme

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,38 @@
 |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.
+
+.. raw:: html
+
+   <iframe width="560" height="315" src="https://www.youtube.com/embed/JFg-_5xihkE" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
 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,106 @@
-.. _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`
 
 .. _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/mixer-about.rst

@@ -1,14 +1,54 @@
 .. _mixer-about:
 
 Mixer
-#######
+#####
 
-Mixing refers to composing a custom, versioned image of |CLOSIA| for a specific use case. While upstream |CL| provides options to install bundles for various capabilities, some developers and OSVs may wish to either augment the operating system with functionality from their own packages or modify the structure of current bundles. Mixing offers a method to add capabilities while retaining the ability to stay up to date with an upstream version of |CL|.
+|CL-ATTR| is a powerful, modular, and customizable OS. Upstream |CL| offers
+many images to support different environments and use-cases.  There are
+hundreds of bundles that will meet most, if not all, of your OS and software
+needs.
 
-Mixing is a multi-step process that starts with installing the mixer bundle using swupd. You will also need a working knowledge of :abbr:`RPMs (RPM Package Manager files)` and how |CL| bundles work. For a detailed guide on how to create a |CL| mix, visit :ref:`mixer`.
+However, if you need additional customization or content, |CL| provides the
+mixer tool. Depending on your needs, the mixer tool allows you to:
 
-Related Concepts
-================
+* :ref:`create-mix` to create a distinct derivative of the |CL| that
+   contains your custom software.
 
-* :ref:`swupd-about`
+.. _create-mix:
+
+Create a mix
+============
+
+When creating a mix, you can
+
+* Use any existing upstream bundles with no modification.
+* Redefine what goes into existing bundles.
+* Create completely new, custom bundles with your own custom packages.
+
+With mixer you are not required to incorporate every upstream release into
+your mix. You decide which upstream versions to update your derivative to, as
+illustrated in Figure 1.
+
+.. figure:: figures/mixer-about-1.png
+   :scale: 75%
+   :alt: Creating a custom mix.
+
+   Figure 1: With a custom mix, you add your custom bundle and decide which
+   upstream versions to update your mix to, on your own release cycle.
+
+Creating your own mix forks away from the |CL| upstream and requires that you
+act as your own OSV. There is a greater level of responsibility, requiring
+more infrastructure and processes to adopt. However, with this approach, you
+have a higher degree of control and customization of your custom |CL|.
+
+Related topics
+==============
+
+|CL| provides flexibility in how you customize your OS. Learn more about
+mixer and related topics to decide which customization approach is best for
+you.
+
+* :ref:`mixer`
 * :ref:`bundles-about`
+* :ref:`swupd-about`
+* :ref:`deploy-at-scale`

source/clear-linux/concepts/security.rst

@@ -1,36 +1,36 @@
 .. _security:
 
-|CL-ATTR| OS Security 
+OS Security
 *************************
 
 |CL-ATTR| aims to make systemic and layered security-conscious decisions
-that are both performant and practical. This security philosophy is rooted 
+that are both performant and practical. This security philosophy is rooted
 within the project's codebase and operating culture.
 
 
 .. contents:: :local:
-   :depth: 2
+   :depth: 1
 
 
 
 Security in Updates
 ===================
 
-The |CL| team believes in the benefits of 
-software security through open sourcing, incremental updates, and 
+The |CL| team believes in the benefits of
+software security through open sourcing, incremental updates, and
 rapidly resolving known security advisories.
- 
 
 
-The latest Linux codebase
--------------------------
 
-|CL| uses the newest version of the Linux kernel which allows the operating 
-system to leverage the latest features from the upstream Linux kernel, 
-including security fixes. 
+The latest Linux* codebase
+--------------------------
+
+|CL| uses the newest version of the Linux kernel which allows the operating
+system to leverage the latest features from the upstream Linux kernel,
+including security fixes.
+
 
 
- 
 
 Automated Effective Updating
 ----------------------------
@@ -38,43 +38,43 @@ Automated Effective Updating
 |CL| is incrementally updated multiple times per day.
 
 This `rolling release model`_ allows |CL| to consume the latest security
-fixes of software packages as soon as they become available. 
-There is no waiting for major or minor releases on |CL|. 
+fixes of software packages as soon as they become available.
+There is no waiting for major or minor releases on |CL|.
 
-An update is not effective if it is just simply downloaded onto a system. 
+An update is not effective if it is just simply downloaded onto a system.
 It needs to be obtained *AND* ensured that the new patched copy is being
-used; not an older copy loaded into memory. |CL| will let you know when a 
-service needs to be rebooted or do it for your automatically after 
+used; not an older copy loaded into memory. |CL| will let you know when a
+service needs to be rebooted or do it for your automatically after
 a software update, if desired.
 
 
-In |CL| updates are delivered automatically, efficiently, 
-and effectively. For more information see 
+In |CL| updates are delivered automatically, efficiently,
+and effectively. For more information see
 `documentation about Software Updates`_ in |CL|.
 
- 
+
 
 
 
 Automated CVE Scanning and Remediation
 --------------------------------------
 
-The sheer number of software packages and security vulnerabilities is growing 
-exponentially. Repositories of Common Vulnerabilities and Exposures (CVEs) 
-and their fixes, if known, are published by :abbr:`NIST` in a 
+The sheer number of software packages and security vulnerabilities is growing
+exponentially. Repositories of Common Vulnerabilities and Exposures (CVEs)
+and their fixes, if known, are published by :abbr:`NIST` in a
 National Vulnerability Database \ |NVD|\  and at \ |MITRE|\  .
 
 
 |CL| employs a proactive and measured approach to addressing known
 and fixable :abbr:`CVEs (Common Vulnerabilities and Exposures)`.
-Packages are automatically scanned against 
-:abbr:`CVEs (Common Vulnerabilities and Exposures)` daily, and security 
-patches are deployed as soon as they are available. 
+Packages are automatically scanned against
+:abbr:`CVEs (Common Vulnerabilities and Exposures)` daily, and security
+patches are deployed as soon as they are available.
 
-These combined practices minimize the amount of 
+These combined practices minimize the amount of
 time |CL| systems are exposed to unnecessary security risk.
 
- 
+
 
 
 
@@ -86,18 +86,18 @@ Minimized attack surface
 -------------------------
 
 |CL| removes legacy, unneeded, or redundant standards and
-components as much as possible to enable the use of best known security 
-standards. Below are some examples: 
+components as much as possible to enable the use of best known security
+standards. Below are some examples:
 
-* `RC4`, `SSLv3`, `3DES`, and `SHA-1` ciphers which have had known 
-  vulnerabilities, have been explicitly disabled within many |CL| packages to 
-  avoid their accidental usage. 
+* `RC4`, `SSLv3`, `3DES`, and `SHA-1` ciphers which have had known
+  vulnerabilities, have been explicitly disabled within many |CL| packages to
+  avoid their accidental usage.
 
-* Services and subsystems which expose sensitive system information 
+* Services and subsystems which expose sensitive system information
   have been removed such as the `finger` and `tcpwrappers`.
 
-* `SFTP` has been disabled by default due to security 
-  considerations. See the `openssh-server reference page`_ for more details. 
+* `SFTP` has been disabled by default due to security
+  considerations.
 
 
 Verified trust
@@ -105,65 +105,62 @@ Verified trust
 
 |CL| encourages the use of secure practices such as encryption
 and digital signature verification throughout the system and discourages blind
-trust. Below are some examples: 
+trust. Below are some examples:
 
-* All update operations from swupd are transparently encrypted and checked 
-  against the |CL| maintainers' public key for authenticity. 
-  More information can be found in this blog post: 
-  `blog post about swupd security`_ 
+* All update operations from swupd are transparently encrypted and checked
+  against the |CL| maintainers' public key for authenticity.
+  More information can be found in this blog post:
+  `blog post about swupd security`_
 
-* Before being built, packages available from |CL| verify checksums and 
+* Before being built, packages available from |CL| verify checksums and
   signatures provided by third party project codebases and maintainers.
 
-* |CL| features a unified certificate store, `clrtrust`_ which comes 
-  ready to work with well-known Certificate Authorities out of the box. 
-  `clrtrust`_ also offers an easy to use command line interface for managing 
-  system-wide chains of trust, instead of ignoring foreign certificates. 
+* |CL| features a unified certificate store, `clrtrust`_ which comes
+  ready to work with well-known Certificate Authorities out of the box.
+  `clrtrust`_ also offers an easy to use command line interface for managing
+  system-wide chains of trust, instead of ignoring foreign certificates.
+
 
 
- 
 
 
 
 Compiled with secure options
 ----------------------------
 
-While |CL| packages are optimized for performance on 
-Intel® architecture, security conscious kernel and compiler options are 
-sensibly taken advantage of. Below are some examples: 
+While |CL| packages are optimized for performance on
+Intel® architecture, security conscious kernel and compiler options are
+sensibly taken advantage of. Below are some examples:
 
- 
-* Kernels shipped with |CL| are signed and disallow the usage of 
+
+* Kernels shipped with |CL| are signed and disallow the usage of
   custom kernel modules to maintain verifiable system integrity.
 
-* `Address space layout randomization (ASLR)`_ and 
+* `Address space layout randomization (ASLR)`_ and
   `Kernel address space layout randomization (KASLR)`_  are kernel features
-  which defend against certain memory based attacks. 
+  which defend against certain memory based attacks.
   More information can be found in a `blog post about PIE executables`_ .
 
-* `dm-verity`_ is a kernel mechanism readily available in |CL| 
-  which verifies integrity of the devices being written to, like hard disks,
-  to help ensure they have not been tampered with.  
 
 
 
-  
+
 
 Security in System Design
 =========================
 
-Simple, yet effective, techniques are used throughout the 
+Simple, yet effective, techniques are used throughout the
 |CL| system design to defend against common attack vectors and enable
-good security hygiene. Below are some examples: 
+good security hygiene. Below are some examples:
 
 
-* Full disk encryption using `Linux Unified Key Setup`_ (LUKS)  is available 
+* Full disk encryption using `Linux Unified Key Setup`_ (LUKS)  is available
   during installation.
 
 * |CL| uses the PAM cracklib module to harden user login and password
-  security resulting in: 
+  security resulting in:
 
-  - No default username or root password set out of the box with 
+  - No default username or root password set out of the box with
     |CL|, you will be asked to set your own password immediately.
 
   - Simple password schemes, which are known to be easily compromised,
@@ -172,9 +169,9 @@ good security hygiene. Below are some examples:
   - A password blacklist, to avoid system passwords being set to
     passwords which have been compromised in the past.
 
-* `Tallow`_, a lightweight service which monitors and blocks suspicious SSH 
-  login patterns, is installed with the :command:`openssh-server` bundle. 
-        
+* `Tallow`_, a lightweight service which monitors and blocks suspicious SSH
+  login patterns, is installed with the :command:`openssh-server` bundle.
+
 
 
 
@@ -182,7 +179,6 @@ good security hygiene. Below are some examples:
 
 .. _`documentation about Software Updates`: https://clearlinux.org/documentation/clear-linux/concepts/swupd-about
 .. _`cve-check-tool`: https://github.com/clearlinux/cve-check-tool
-.. _`openssh-server reference page`: https://clearlinux.org/documentation/clear-linux/reference/bundles/openssh-server
 .. _`blog post about swupd security`: https://clearlinux.org/blogs/security-software-update-clear-linux-os-intel-architecture
 .. _`rolling release model`: https://en.wikipedia.org/wiki/Rolling_release
 .. _`clrtrust`: https://github.com/clearlinux/clrtrust
@@ -191,7 +187,7 @@ good security hygiene. Below are some examples:
 .. _`dm-verity`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/device-mapper/verity.txt
 .. _`SELinux`: https://github.com/SELinuxProject
 .. _`Linux Unified Key Setup`: https://gitlab.com/cryptsetup/cryptsetup/
-.. _`blog post about PIE executables`: https://clearlinux.org/blogs/recent-gnu-c-library-improvements 
+.. _`blog post about PIE executables`: https://clearlinux.org/blogs/recent-gnu-c-library-improvements
 .. _`Tallow`: https://github.com/clearlinux/tallow
 
 .. |NVD| raw:: html
@@ -201,4 +197,3 @@ good security hygiene. Below are some examples:
 .. |MITRE| raw:: html
 
     <a href="https://cve.mitre.org/" target="_blank">https://cve.mitre.org/</a>
-

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

@@ -1,132 +1,101 @@
 .. _swupd-about:
 
-Software update
-###############
+swupd: software updater
+#######################
 
-|CLOSIA| does software updates differently than traditional Linux-based 
-operating systems. Where traditional distributions rely on packages for 
-software deployment, |CL| uses the concept of a "bundle" for 
-deployment. Traditional Linux packages provide a particular utility or 
-library; |CL| bundles provide all necessary packages to enable a 
-specific function.
-
-With |CL|, updating equates to an entirely new OS version with a 
-specific set of bundles, as compared to a package-based distribution in 
-which packages may be updated individually. |CL| updates are 
-efficient, updating only changed files instead of entire packages.
-
-System administrators can customize or add bundles to the OS, while still 
-taking advantage of a controlled update stream. This enables system 
-administrators to focus on the pieces that make their deployment unique.
-
-
-Bundles
-=======
-
-While we use packages to manage compiling source code into installable 
-binaries, we do not deploy software through packages. Instead, we use bundles 
-to deploy software, where each bundle encapsulates a particular functionality 
--- functionality that is enabled by composing all the required upstream 
-open-source projects and packages into one logical unit: a bundle. This 
-simplifies installing features on |CL|.
-
-For additional resources regarding available bundles, useful bundle commands, 
-and compatible |CL| kernels, visit our :ref:`bundles-about` 
-page.
+:command:`swupd` is an operating system software manager and update program
+that operates at a file-level to enable verifiable integrity and update
+efficiency.
 
+Visit the `swupd man page`_ for more details.
 
 Versioning
 ==========
 
-In a traditional distribution, the process of describing current software
-versioning usually involves:
+Using package managers to keep track of software version compatibility or compare multiple systems on many Linux distributions can be cumbersome.
 
--  Listing and keeping track of the current OS release (generally
-   uninformative about any singular packages or functionality).
+With |CL| :command:`swupd`, versioning happens at the individual
+file-level. This means |CL| generates an entirely new OS version with any set
+of software changes to the system (including software downgrades or removals). This rolling release versioning model is similar to
+:command:`git` internal version tracking, where any of the individual file
+commits are tracked and move the pointer forward when changed.
 
--  Keeping track of packages and repositories being used, and updating them
-   individually.
-
--  Listing and tracking every package available and installed on the
-   system, none of which are directly tied to the current OS release.
-
-This can be done effectively, but given the nearly endless combinations of
-packages and versions of packages a server may have, it quickly becomes
-non-trivial to define what "version" the system is and what software it
-is running without explicitly going through each system and inspecting
-every package.
-
-With |CL|, we need only track:
-
--  One single number
-
-A number representing the **current** release of the OS is sufficient to
-describe the versions of all the software on the OS. Each build is
-composed of a specific set of bundles made from a particular version of
-packages. This matters on a daily basis to system administrators, who
-need to determine which of their systems do not have the latest security
-fixes, or which combinations of software have been tested. Every release 
-of the same number is guaranteed to contain the same versions of software, 
-so there's no ambiguity between two systems running the same version of |CL|.
+While administrators can pick and choose which `bundles`_ a system has
+installed, a single |CL| version number strictly represents one combination
+of all software versions that can be installed onto a system of that |CL|
+version. This method of whole OS versioning offers unique advantages.
+Namely, system administrators can quickly compare multiple |CL| systems that share the same version for important software and security fixes.
 
 
 Updating
 ========
 
-Another notable difference between package-based distributions and |CL|
-is how updates are managed. On a package-based OS, system administrators update
-each individual package or piece of software to a newer (or older!) version. With
-|CL|, an update translates to an entirely new OS version, containing one 
-or many updates.  It is not possible to update a piece of the system while 
-remaining on the same version of |CL|.
+|CL| promotes regular and automated updating of software to ensure
+integration of new enhancements and security fixes. Refer to :ref:`security`
+documentation for more information.
 
-How is this useful? Although it seems, at first, like a huge restriction
-or limitation, this method has many non-obvious benefits. Imagine a
-cloud environment composed of numerous machines.  Here, a homogeneous set of
-software makes sense -- from the system administrator's level down to the
-user level. Homogeneous systems allow users to focus on their contributions 
-and/or code, rather than configuring environments or worrying about 
-synchronizing versions and updates.  At the system admin level, it ensures 
-security is tighter and makes it far easier to monitor and update patches.
+Learn how to update your system using :ref:`swupd <swupd-guide>`.
 
-|CL| promotes regular updating of the OS and will automatically check 
-for updates and apply them by default.
+Update efficiency
+-----------------
 
-To learn how to run an update of your system, visit our :ref:`swupd-guide` page.
+Because :command:`swupd` operates at the individual file-level instead of a
+package-level, |CL| updates are small and fast.
 
+On many Linux\* distributions, updates to a particular software package
+require the whole software package to be downloaded and replaced
+--even for one line of code.
 
-Update speed
-============
+In |CL|, updates are generated using the :ref:`mixer <mixer-about>` tool. Mixer calculates the difference between two |CL| versions and makes available
+*binary deltas*, which contain only the changed portion of files. This
+*binary delta technology* [1]_ means :command:`swupd` on |CL| systems only
+needs to download and apply a small fraction of a package in order to
+receive an update.
 
-Software updates with |CL| are also efficient. Bundles simply describe 
-a set of files, and the update technology updates *only* files that actually 
-changed by using binary-delta technology for efficiency [1]_. Operating systems 
-that use packages as the unit of deployment require full package updates (thus
-hogging resources), even when one small file in that package has changed.
+The :ref:`mixer <mixer-about>` tool additionally computes updates files in
+multiple compression formats, allowing :command:`swupd` to utilize the most
+efficiently compressed format for a |CL| system to minimize the cost
+to update.
 
-It is quite common for a full OS update fixing a security hole to be
-only 15 kilobytes in total update size. If only several kilobytes need
-to be changed, it does not make sense to re-download and reinstall an
-entire package or suite of programs just to incorporate a minuscule (yet
-important) update. Through binary deltas, the OS is able to update only
-those bits that changed, yielding very small update content (deltas)
-that can be applied exceedingly fast.  As a result, major security patches
-and core update take merely seconds.
+Update integrity
+----------------
 
+:command:`swupd` operates against a published manifest of files for a
+particular |CL| version that contains the unique hash of each file. This is
+the basis of the :command:`swupd verify` subcommand, which allows a |CL|
+system to check for and remediate any discrepancies to system files. As
+necessary, :command:`swupd verify` provides a useful way for software
+developers to return to a known filesystem state.
 
-Customize the OS
-================
+Bundles
+=======
 
-While we realize our definition of bundles makes sense to us, data center
-operators may have special needs and ideas. Therefore, we provide a
-:ref:`mixer tool <mixer>`. This tool allows users to customize and add bundles
-or even add their own software, while keeping the operating
-system and its updates as the basis. Using this tool, system administrators
-can focus on the customization their deployments require while staying on
-a controlled update stream.
+|CL-ATTR| approaches software management differently than many other
+Linux-based operating systems.
 
-To learn more about mixing, visit our :ref:`mixer-about` page.
+Instead of deploying granular software packages, |CL| uses the concept of
+bundles with pre-associated software. Each bundle encapsulates a particular
+use-case, which is enabled by composing all the required upstream open-source
+projects and packages into one logical unit.
 
+This bundle-based approach offers some unique advantages:
+
+* Bundles provide a particular functionality, or stack, which
+  include all associated runtime dependencies.
+
+* Software package dependencies are resolved on the server, so file-level
+  conflicts do not occur on the target system after an update.
+
+* All combinations of bundles are able to co-exist on a |CL| system.
+
+For more information on bundles, visit:
+
+* :ref:`bundles`
+* :ref:`bundles-about`
+* :ref:`bundle-commands`
+* :ref:`compatible-kernels`
+
+.. [1] The software update technology for |CL-ATTR| was first presented at the Linux Plumbers conference in 2012.
+
+.. _swupd man page: https://github.com/clearlinux/swupd-client/blob/master/docs/swupd.1.rst
 
-.. [1] The software update technology for |CLOSIA| was first presented at the 
-   Linux Plumbers conference in 2012.

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

@@ -38,7 +38,7 @@ Architecture
 		If you want to capture your own records for analysis, you must set up
 		your own backend server.
 
-.. figure:: figures/telemetry-about-1.png
+.. figure:: ../guides/telemetrics/figures/telemetry-e2e.png
    :scale: 75%
    :alt: Clear Linux Telemetry Architecture.
 
@@ -48,7 +48,7 @@ The telemetry client provides the front end of a complete telemetrics solution
 and includes the following components:
 
 *	**telemprobd**, a daemon that prepares the telemetry records and spools them on disk prior to delivery
-*       **telempostd**, a daemon that sends the records to the telemetry backend server or leaves them on disk until deleting after the record expires. 
+*       **telempostd**, a daemon that sends the records to the telemetry backend server or leaves them on disk until deleting after the record expires.
 
 *	**probes**, that collect specific types of data from the operating system.
 *	**libtelemetry**, that telemetrics probes use to create telemetrics records and
@@ -76,8 +76,7 @@ Next steps
 
 To put this concept into practice, see the following resources:
 
-*	:ref:`telemetry-enable`
-*	:ref:`telemetry-backend`
+*	:ref:`telem-guide`
 *	`Telemetry feature description`_
 
 .. _`Telemetry feature description`:

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

@@ -0,0 +1,496 @@
+.. _bare-metal-install-desktop:
+
+Install |CL-ATTR| from the live desktop
+#######################################
+
+The live desktop allows you to boot |CL-ATTR| in a GNOME desktop without
+modifying the host system, offering the chance to explore developing
+on |CL|. Better yet, launch the |CL| installer to install on your target
+system.
+
+.. contents:: :local:
+   :depth: 1
+
+System requirements
+*******************
+
+Assure that your target system supports the installation:
+
+* :ref:`system-requirements`
+* :ref:`compatibility-check`
+
+Preliminary steps
+*****************
+
+#. `Visit our Downloads page`_.
+
+#. Download the file :file:`clear-<release number>-live-desktop.iso`
+
+   .. note::
+
+      <release-number> is the latest |CL| auto-numbered release.
+
+#. Follow your OS instructions to create a bootable USB drive.
+
+   * :ref:`bootable-usb`
+
+.. _install-on-target-start:
+
+Install from live image
+***********************
+
+After you download and burn the live desktop image on a USB drive, follow
+these steps.
+
+#. Insert the USB drive into an available USB slot.
+
+#. Power on the system.
+
+#. Open the system BIOS setup menu by pressing the :kbd:`F2` key.
+   Your BIOS setup menu entry point may vary.
+
+#. In the setup menu, enable the UEFI boot and set the USB drive as the
+   first option in the device boot order.
+
+#. Save these settings, e.g. :kbd:`F10`, and exit.
+
+#. Reboot the target system.
+
+#. Select :guilabel:`Clear Linux OS` in the boot menu, shown in Figure 1.
+
+   .. figure:: figures/bare-metal-install-desktop-01.png
+      :scale: 100%
+      :alt: Clear Linux OS in boot menu
+
+      Figure 1: Clear Linux OS in boot menu
+
+.. _install-on-target-end:
+
+Confirm network connection
+==========================
+
+Confirm there is a network connection before launching the installer.
+Choose a method: `Wired Connection`, or `WiFi Connected`.
+This guide shows an example of a **Wired Connection**.
+
+#. In the upper right of the top menu bar, select the square icon to view
+   Network settings, shown in Figure 2.
+
+#. Select :guilabel:`Wired Connected` and then :guilabel:`Wired Settings`.
+
+   .. figure:: figures/bare-metal-install-desktop-02.png
+      :scale: 100%
+      :alt: Software icon, Network settings
+
+      Figure 2: Software icon, Network settings
+
+#. View the :guilabel:`Wired` menu to assure that you're target system and
+   installer are connected to a network.
+
+#. Optional: Configure Proxy settings.
+
+   #. To view :guilabel:`Network Proxy`, select its :guilabel:`Gear` icon.
+
+   #. Select from `Automatic`, `Manual` or `Disabled` as desired.
+
+   #. Close the dialogue box.
+
+#. Select the :guilabel:`Gear` icon to view Network settings.
+
+#. If desired, select :guilabel:`Connect automatically`.
+   Select other options as desired.
+
+#. Select :guilabel:`Apply` button to confirm change to settings.
+
+Software
+--------
+
+Optional: Explore |CL| bundles and other software available. Double-click the :guilabel:`Software` icon from the Activities menu, shown in Figure 2.
+
+.. note::
+
+   `Sofware` application is *only intended for exploring* available bundles,
+   applications, and images. Do not attempt to install them.
+
+   Assure there is a network connection before launching `Software`.
+
+Launch the |CL| installer
+=========================
+
+#. After the live desktop image boots, find the |CL| icon in
+   the :guilabel:`Activities` menu at left, shown in Figure 3.
+
+#. Click the icon, :guilabel:`Install Clear Linux OS`.
+
+   .. figure:: figures/bare-metal-install-desktop-02.png
+      :scale: 100%
+      :alt: Install Clear Linux OS icon
+
+      Figure 3: Install Clear Linux OS icon
+
+#. The installer is launched, as shown in Figure 4.
+
+   .. figure:: figures/bare-metal-install-desktop-04.png
+      :scale: 100%
+      :alt: |CL| Desktop Installer
+
+      Figure 4: |CL| OS Desktop Installer
+
+#. In :guilabel:`Select Language`, select a language from the options, or
+   type your preferred language in the search bar.
+
+#. Select :guilabel:`Next`.
+
+
+.. _incl-bare-metal-beta-start:
+
+Minimum installation requirements
+*********************************
+
+To fulfill minimum installation requirements, complete the
+`Required options`_. We also recommend completing `Advanced options`_.
+
+.. note::
+
+   * The :kbd:`Install` button is only highlighted **after** you complete
+     `Required options`_.
+
+   * Checkmarks indicate a selection has been made.
+
+   * An Internet connection is required. You may want to launch a browser
+     prior to installation to verify your Internet connection.
+
+|CL| Desktop Installer
+**********************
+
+The |CL| Desktop Installer Main Menu appears as shown in Figure 5. To meet
+the minimum requirements, enter values in all submenus for the
+:guilabel:`Required options`. After you complete them, your selections appear
+below submenus and a checkmark appears at right.
+
+.. figure:: figures/bare-metal-install-desktop-05.png
+   :scale: 100%
+   :alt: Clear Linux OS Desktop Installer - Main Menu
+
+   Figure 5: Clear Linux OS Desktop Installer - Main Menu
+
+Navigation
+**********
+
+* Use the :kbd:`mouse` to navigate or select options.
+
+* Use :kbd:`Tab` key to navigate between :guilabel:`Required options`
+  and :guilabel:`Advanced options`
+
+* Use :kbd:`Up` or :kbd:`Down` arrow keys to navigate submenu list.
+
+* Select :kbd:`Confirm`, or :kbd:`Cancel` in submenus.
+
+Required options
+****************
+
+Select Time Zone
+================
+
+#. From the Main Menu, select :guilabel:`Select Time Zone`. `UTC` is selected
+   by default.
+
+#. In :guilabel:`Select Time Zone`, navigate to the desired time zone.
+   Or start typing the region and then city.
+   (.e.g., :file:`America/Los_Angeles`).
+
+#. Select :guilabel:`Confirm`.
+
+   .. figure:: figures/bare-metal-install-desktop-06.png
+      :scale: 100%
+      :alt: Select System Timezone
+
+      Figure 6: Select System Time Zone
+
+Select Keyboard
+===============
+
+#. From the Main Menu, select :guilabel:`Select Keyboard`.
+
+#. Navigate to your desired keyboard layout. We select "us" for the
+   United States.
+
+#. Select :guilabel:`Confirm`.
+
+   .. figure:: figures/bare-metal-install-desktop-07.png
+      :scale: 100%
+      :alt: Select Keyboard menu
+
+      Figure 7: Select Keyboard menu
+
+Select Installation Media
+=========================
+
+#. From the Main Menu, select :guilabel:`Select Installation Media`.
+
+#. Choose an installation method: `Safe Installation`_ or
+   `Destructive Installation`_.
+
+   .. figure:: figures/bare-metal-install-desktop-08.png
+      :scale: 100%
+      :alt: Select Installation Media
+
+      Figure 8: Select Installation Media
+
+Safe Installation
+-----------------
+Use this method to safely install |CL| on media with available space, or
+alongside existing partitions, and accept the `Default partition schema`_.
+If enough free space exists, safe installation is allowed.
+
+Destructive Installation
+------------------------
+
+Use this method to destroy the contents of the target device, install |CL| on it, and accept the `Default partition schema`_.
+
+Disk encryption
+===============
+
+For greater security, disk encryption is supported using LUKS. Encryption is
+optional.
+
+#. To encrypt the root partition, select :guilabel:`Enable Encryption`,
+   as shown in Figure 9.
+
+   .. figure:: figures/bare-metal-install-desktop-09.png
+      :scale: 100%
+      :alt: Enable Encryption
+
+      Figure 9: Enable Encryption
+
+#. When :guilabel:`Encryption Passphrase` appears, enter a passphrase.
+
+   .. figure:: figures/bare-metal-install-desktop-10.png
+      :scale: 100%
+      :alt: Encryption Passphrase
+
+      Figure 10: Encryption Passphrase
+
+   .. note::
+
+      Minimum length is 8 characters. Maximum length is 94 characters.
+
+#. Enter the same passphrase in the second field.
+
+#. Select :guilabel:`Confirm` in the dialogue box.
+
+   .. note::
+
+      :guilabel:`Confirm` is only highlighted if passphrases match.
+
+#. Select :guilabel:`Confirm` in submenu.
+
+Manage User
+===========
+
+#. In Required Options, select :guilabel:`Manage User`.
+
+#. In :guilabel:`User Name`, enter a user name.
+
+   .. figure:: figures/bare-metal-install-desktop-11.png
+      :scale: 100%
+      :alt: Manage User
+
+      Figure 11: Manage User
+
+#. In :guilabel:`Login`, create a login name. It must start with a letter
+   and can use numbers, hyphens, and underscores. Maximum length is 31
+   characters.
+
+#. In :guilabel:`Password`, enter a password. Minimum length is
+   8 characters. Maximum length is 255 characters.
+
+#. In :guilabel:`Confirm`, enter the same password.
+
+   .. note::
+
+      :guilabel:`Administrator` rights are selected by default.
+      For security purposes, the default user must be assigned as an
+      Administrator.
+
+#. Select :kbd:`Confirm`.
+
+   .. note::
+
+      Select :guilabel:`Cancel` to return to the Main Menu.
+
+Modify User
+-----------
+
+#. In Manager User, select :guilabel:`Manage User`.
+
+#. Modify user details as desired.
+
+#. Select :guilabel:`Confirm` to save the changes you made.
+
+   .. note::
+
+      Optional: Select :guilabel:`Cancel` to return to the Main Menu to
+      revert changes.
+
+Optional: Skip to `Finish installation`_.
+
+Telemetry
+=========
+
+Choose whether to participate in `telemetry`. :ref:`telem-guide` is a |CL|
+feature that reports failures and crashes to the |CL| development
+team for improvements. For more information, see :ref:`telemetry-about`.
+
+#. From :guilabel:`Required Options`, select :guilabel:`Telemetry`.
+
+#. Select :kbd:`Confirm`.
+
+#. If you don't wish to participate, deselect :kbd:`Enable Telemetry`.
+
+#. Select :kbd:`Confirm`.
+
+   .. figure:: figures/bare-metal-install-desktop-12.png
+      :scale: 100%
+      :alt: Enable Telemetry
+
+      Figure 12: Enable Telemetry
+
+Advanced options
+****************
+
+After you complete the `Required options`_, we recommend completing
+:guilabel:`Advanced options`--though they're not required. Doing so
+customizes your development environment, so you're ready to go immediately
+after reboot.
+
+* `Bundle Selection`_
+
+* `Assign Hostname`_
+
+As for bundles, you can always add more later with :ref:`swupd-guide`.
+
+Bundle Selection
+================
+
+#. On the Advanced menu, select :guilabel:`Bundle Selection`
+
+#. Select your desired bundles.
+
+   .. figure:: figures/bare-metal-install-desktop-13.png
+      :scale: 100%
+      :alt: Bundle Selection
+
+      Figure 13: Bundle Selection
+
+#. Select :kbd:`Confirm`.
+
+#. View the bundles that you selected.
+
+   .. figure:: figures/bare-metal-install-desktop-14.png
+      :scale: 100%
+      :alt: Bundle Selections - Advanced Options
+
+      Figure 14: Bundle Selections - Advanced Options
+
+Optional: Skip to `Finish installation`_.
+
+Assign Hostname
+===============
+
+#. In Advanced Options, select :guilabel:`Assign Hostname`.
+
+#. In :guilabel:`Hostname`, enter the hostname only (excluding the domain).
+
+   .. figure:: figures/bare-metal-install-desktop-15.png
+      :scale: 100%
+      :alt: Assign Hostname
+
+      Figure 15: Assign Hostname
+
+   .. note::
+
+      Hostname does not allow empty spaces. Hostname must start with an
+      alphanumeric character but may also contain hyphens. Maximum length of
+      63 characters.
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+#. Select :kbd:`Confirm`.
+
+Optional: Skip to `Finish installation`_.
+
+Finish installation
+*******************
+
+#. When you are satisfied with your installation configuration, select
+   :guilabel:`Install`.
+
+   .. figure:: figures/bare-metal-install-desktop-16.png
+      :scale: 100%
+      :alt: Assign Hostname
+
+      Figure 16: Finish installation
+
+   .. note:
+
+      All checkmarks must be visible in :guilabel:`Required Options` for you to select :guilabel:`Install`.
+
+#. If you do not enter a selection for all :guilabel:`Required Options`,
+   the :guilabel:`Install` button remains greyed out, as shown
+   in Figure 17. Return to `Required Options`_ and make selections.
+
+
+   .. figure:: figures/bare-metal-install-desktop-17.png
+      :scale: 100%
+      :alt: Required Options - Incomplete
+
+      Figure 17: Required Options - Incomplete
+
+#. After installation is complete, select :guilabel:`Exit`.
+
+#. Shut down the target system.
+
+#. Remove the USB or any installation media.
+
+#. Power on your system.
+
+   .. note::
+
+      Allow time for the graphical login to appear. A login prompt shows the administrative user that you created.
+
+#. Log in as the adminstrative user.
+
+Congratulations. You successfully installed |CL|.
+
+Default partition schema
+========================
+
+Table 1 shows the defult partition schema with the exception of root,
+which varies.
+
+.. list-table:: **Table 1. Disk Partition Setup**
+   :widths: 33, 33, 33
+   :header-rows: 1
+
+   * - FileSystem
+     - Mount Point
+     - Minimum size
+   * - ``VFAT``
+     - /boot
+     - 150M
+   * - ``swap``
+     -
+     - 256MB
+   * - ``root``
+     - /
+     - *Size depends upon use case/desired bundles.*
+
+Next steps
+**********
+
+:ref:`guides`
+
+.. _Visit our downloads page: https://clearlinux.org/downloads
+.. _Autoproxy: https://clearlinux.org/features/autoproxy
+

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

@@ -0,0 +1,855 @@
+.. _bare-metal-install-server:
+
+Install |CL-ATTR| on bare metal with live server
+################################################
+
+These instructions guide you through installing |CL-ATTR| on bare metal from a bootable USB drive using a live server image.
+
+.. contents::
+   :local:
+   :depth: 1
+
+System requirements
+*******************
+
+Assure that your target system supports the installation:
+
+* :ref:`system-requirements`
+* :ref:`compatibility-check`
+
+Download the latest |CL| live server image
+******************************************
+
+Get the latest |CL| installer image from the `downloads page`_. Look for the
+:file:`clear-[version number]-live-server.iso` file.
+
+#. Follow your OS instructions to create a bootable USB drive.
+
+   * :ref:`bootable-usb`
+
+#. After downloading the image, verify and decompress the file per your OS.
+
+Install |CL| on your target system
+**********************************
+
+Ensure that your system is configured to boot UEFI. The installation method
+described below requires a wired Internet connection with DHCP.
+
+.. note::
+
+   Alternatively, you can install |CL| over a wireless connection by first
+   using `nmtui`. Follow the `nmtui` instructions shown in Figure 2.
+
+Follow these steps to install |CL| on the target system:
+
+#. Insert the USB drive into an available USB slot.
+
+#. Power on the system.
+
+#. Open the system BIOS setup menu by pressing the :kbd:`F2` key.
+   Your BIOS setup menu entry point may vary.
+
+#. In the setup menu, enable the UEFI boot and set the USB drive as the first
+   option in the device boot order.
+
+#. Save these settings and exit.
+
+#. Reboot the target system.
+
+#. This action launches the |CL| installer boot menu, shown in figure 1.
+
+   .. figure:: figures/bare-metal-install-server-01.png
+      :scale: 100%
+      :alt: Clear Linux OS Installer boot menu
+
+      Figure 1: Clear Linux OS Installer boot menu
+
+#. With :guilabel:`Clear Linux OS` highlighted, select :kbd:`Enter`.
+
+Launch the |CL| Installer
+*************************
+
+#. At the :guilabel:`login` prompt, enter :command:`root`.
+
+#. Follow the onscreen instructions, shown in Figure 2, and
+   enter a temporary password.
+
+   .. figure:: figures/bare-metal-install-server-02.png
+      :scale: 100%
+      :alt: root login
+
+      Figure 2: root login
+
+#. At the :guilabel:`root` prompt, enter :command:`clr-installer` and
+   press :kbd:`Enter`.
+
+   .. figure:: figures/bare-metal-install-server-03.png
+      :scale: 100%
+      :alt: clr-installer command
+
+      Figure 3: clr-installer command
+
+Minimum installation requirements
+*********************************
+
+To fulfill minimum installation requirements, complete the
+`Required options`_. While not required, we encourage you to apply the
+`Recommended options`_. `Advanced options`_ are optional.
+
+.. note::
+
+   * The :kbd:`Install` button is **only highlighted after** you complete
+     `Required options`_.
+
+Main Menu
+*********
+The |CL| Installer Main Menu appears as shown in Figure 4.
+
+.. figure:: figures/bare-metal-install-server-04.png
+   :scale: 100%
+   :alt: Clear Linux OS Installer
+
+   Figure 4: Clear Linux OS Installer
+
+The |CL| Installer Main Menu has two tabs: :guilabel:`[R] Required options`
+and :guilabel:`[A] Advanced options`. Navigate between tabs using the arrow
+these shortcut keys:
+
+* :kbd:`Shift+A` for :guilabel:`[A] Advanced options`
+* :kbd:`Shift+R` for :guilabel:`[R] Required options`
+
+To meet the minimum requirements, enter your choices in the
+:guilabel:`Required options`. After confirmation, your selections appear
+beside the :guilabel:`>>` chevron, below the menu options.
+
+Navigation
+**********
+
+* Select :kbd:`Tab` or :kbd:`Up/Down` arrows to highlight your choice.
+
+* Select :kbd:`Enter` or :kbd:`Spacebar` to confirm your choice.
+
+* Select :kbd:`Cancel` or :kbd:`Esc` to cancel your choice.
+
+Required options
+****************
+
+Choose Timezone
+===============
+
+#. From the Main Menu, navigate to :guilabel:`Choose Timezone`.
+   `UTC` is the default.
+
+#. Select :kbd:`Enter`.
+
+#. In :guilabel:`Select System Timezone`, use :kbd:`Up/Down` arrows
+   navigate to the desired timezone.
+
+.. todo: User need only select Enter; can only select Confirm with mouse.
+
+#. Press :kbd:`Enter` to confirm.
+
+   .. figure:: figures/bare-metal-install-server-05.png
+      :scale: 100%
+      :alt: Select System Timezone
+
+      Figure 5: Select System Timezone
+
+Choose Language
+===============
+
+#. From the Main Menu, navigate to :guilabel:`Choose Language`.
+
+#. Select :kbd:`Enter`.
+
+#. In :guilabel:`Select System Language`, navigate to your desired language.
+
+#. Press :kbd:`Enter` to confirm.
+
+   .. figure:: figures/bare-metal-install-server-06.png
+      :scale: 100%
+      :alt: Select System Language
+
+      Figure 6: Select System Language
+
+Configure the Keyboard
+======================
+
+#. From the Main Menu, select :guilabel:`Configure the Keyboard`.
+
+#. Select :kbd:`Enter`.
+
+#. In :guilabel:`Select Keyboard`, navigate to the desired option.
+
+#. Select :kbd:`Enter` to :kbd:`Confirm`.
+
+#. Optional: In :guilabel:`Test keyboard`, type text to assure
+   that the keys map to your keyboard.
+
+   .. figure:: figures/bare-metal-install-server-07.png
+      :scale: 100%
+      :alt: Select Keyboard menu
+
+      Figure 7: Select Keyboard menu
+
+Configure Installation Media
+============================
+
+#. From the Main Menu, select :guilabel:`Configure Installation Media`.
+
+#. Choose an installation method:
+   * `Safe Installation`_
+   * `Destructive Installation`_
+   * `Advanced Configuration`_
+
+
+   .. figure:: figures/bare-metal-install-server-08.png
+      :scale: 100%
+      :alt: Select Installation Media
+
+      Figure 8: Select Installation Media
+
+#. Select :guilabel:`Rescan Media` to show available installation targets.
+
+.. todo: Revise below section to match the dev-gui-00
+
+Safe Installation
+-----------------
+
+Use this method to safely install |CL| on media with available space, or
+alongside existing partitions, and accept the `Default partition schema`_.
+If enough free space exists, safe installation is allowed. See also
+`Troubleshooting`_ below.
+
+Destructive Installation
+------------------------
+
+Use this method to destroy the contents of the target device, install |CL|
+on it, and accept the `Default partition schema`_.
+
+.. note::
+
+   From the :guilabel:`Select Installation Media` menu, select
+   :guilabel:`Enable Encryption` to encrypt the root filesystem for either
+   option above. See also `Disk encryption`_ for more information.
+
+Advanced Configuration
+----------------------
+
+Use this method to manually configure partitions. These must meet
+`Default partition schema`_. You may also choose `Disk encryption`_ during
+configuration of each partition.
+
+.. note::
+
+   `Advanced Configuration` is available in the installer versions 1.2.0 and
+   above.
+
+#. From :guilabel:`Select Installation Media`, shown in Figure 8 above,
+   select :guilabel:`Advanced Configuration`.
+
+#. In :guilabel:`Advanced Configuration`, navigate to :file:`/dev/sda`
+   and then press :kbd:`Enter`.
+
+   .. figure:: figures/bare-metal-install-server-09.png
+      :scale: 100%
+      :alt: Advanced configuration menu
+
+      Figure 9: Advanced configuration menu
+
+#. Choose a partition method:
+
+   * :guilabel:`Auto Partition` Select this option to accept the
+     `Default partition schema`_.
+
+     #. Navigate to and press :guilabel:`Confirm`.
+
+     #. Continue with installation configuration. Jump to `Telemetry`_.
+
+   * `Manual Partition`_ Continue below.
+
+Manual Partition
+----------------
+
+We provide a simple example below.
+
+#. Navigate to the unallocated media (e.g.,`/dev/sda`) until highlighted, as
+   shown in Figure 9.
+
+#. Press :guilabel:`Enter` to edit the partition.
+
+#. The :guilabel:`Partition Setup` menu appears, shown in Figure 10.
+
+   .. note::
+
+      After adding the first partition, select :guilabel:`Free Space` to add another partition.
+
+root partition
+--------------
+
+#. We configure the `root` partition as shown in Figure 10.
+   Configuration of the `root` partition varies.
+
+   .. figure:: figures/bare-metal-install-server-10.png
+      :scale: 100%
+      :alt: root partition
+
+      Figure 10: root partition
+
+#. Navigate to :guilabel:`Add` and press :guilabel:`Enter`.
+
+boot partition
+--------------
+
+#. We configure the `boot` partition as shown in Figure 11.
+
+   .. figure:: figures/bare-metal-install-server-11.png
+      :scale: 100%
+      :alt: boot partition
+
+      Figure 11: boot partition
+
+#. Navigate to :guilabel:`Add` and press :guilabel:`Enter`.
+
+swap partition
+--------------
+
+#. In the :guilabel:`File System` pulldown menu, select `swap`, and
+   enter a label. We enter the minimum required size (e.g., 256M).
+
+   .. figure:: figures/bare-metal-install-server-12.png
+      :scale: 100%
+      :alt: swap partition
+
+      Figure 12: swap partition
+
+#. Navigate to :guilabel:`Add` and press :guilabel:`Enter`.
+
+#. Next, navigate to :guilabel:`Confirm` and press :guilabel:`Enter`,
+   shown in Figure 13.
+
+   Manual partitioning is complete.
+
+   .. figure:: figures/bare-metal-install-server-13.png
+      :scale: 100%
+      :alt: Final configuration of disk partitions
+
+      Figure 13: Final configuration of disk partitions
+
+#. You may skip to the `Telemetry`_ section below.
+
+Disk encryption
+===============
+
+For greater security, disk encryption is supported using LUKS for the
+any partition except `/boot` on |CL|. To encrypt the root partition, see the
+example below. Encryption is optional.
+
+Encryption Passphrase
+---------------------
+
+|CL| uses a single passphrase for encrypted partitions. Additional keys may
+be configured post-installation using the ``cryptsetup`` tool.
+
+#. Optional: Select :guilabel:`[X] Encrypt` to encrypt the root partition,
+   as shown in Figure 14.
+
+   .. figure:: figures/bare-metal-install-server-14.png
+      :scale: 100%
+      :alt: Encrypt partition
+
+      Figure 14: Encrypt partition
+
+#. The :guilabel:`Encryption Passphrase` dialogue appears.
+
+   .. note::
+
+      Minimum length is 8 characters. Maximum length is 94 characters.
+
+   .. figure:: figures/bare-metal-install-server-15.png
+      :scale: 100%
+      :alt: Encryption Passphrase
+
+      Figure 15: Encryption Passphrase
+
+#. Enter the same passphrase in the first and second field.
+
+#. Navigate to :guilabel:`Confirm` and press :kbd:`Enter`.
+
+   .. note::
+
+      :guilabel:`Confirm` is only highlighted if passphrases match.
+
+Telemetry
+=========
+
+:ref:`telem-guide` is a |CL| feature that reports failures and crashes to
+the |CL| development team for improvements. For more detailed information,
+visit our :ref:`telemetry-about` page.
+
+Select your desired option on whether to participate in `telemetry`.
+
+#. In the Main Menu, navigate to :guilabel:`Telemetry` and select
+   :kbd:`Enter`.
+
+#. Select :kbd:`Tab` to highlight your choice.
+
+#. Select :kbd:`Enter` to confirm.
+
+   .. figure:: figures/bare-metal-install-server-16.png
+      :scale: 100%
+      :alt: Enable Telemetry
+
+      Figure 16: Enable Telemetry
+
+Recommended options
+*******************
+
+After you complete the `Required options`_, we highly recommend completing
+these selected `Advanced options`_ at minimum:
+
+* `Manage User`_ Assign a new user with administrative rights
+* `Assign Hostname`_ Simplify your development environment
+
+Skip to finish installation
+===========================
+
+After selecting values for all :guilabel:`Required options`, you may skip
+to `Finish installation`_.
+
+Otherwise, continue below. In the Main Menu, select
+:guilabel:`Advanced options` for additional configuration.
+
+Advanced options
+****************
+
+Configure Network Interfaces
+============================
+
+By default, |CL| is configured to automatically detect the host network
+interface using DHCP. However, if you want to use a static IP address or if
+you do not have a DHCP server on your network, follow these instructions to
+manually configure the network interface. Otherwise, default network
+interface settings are automatically applied.
+
+.. note::
+
+   If DHCP is available, no user selection may be required.
+
+#. Navigate to :guilabel:`Configure Network Interfaces` and
+   select :kbd:`Enter`.
+
+#. Navigate to the network :guilabel:`interface` you wish to change.
+
+#. When the desired :guilabel:`interface` is highlighted, select
+   :guilabel:`Enter` to edit.
+
+   .. note:: Multiple network interfaces may appear.
+
+   .. figure:: figures/bare-metal-install-server-17.png
+      :scale: 100%
+      :alt: Configure Network Interfaces
+
+      Figure 17: Configure Network Interfaces
+
+#. Notice :guilabel:`Automatic / dhcp` is selected by default (at bottom).
+
+   Optional: Navigate to the checkbox :guilabel:`Automatic / dhcp` and select
+   :kbd:`Spacebar` to deselect.
+
+   .. figure:: figures/bare-metal-install-server-18.png
+      :scale: 100%
+      :alt: Network interface configuration
+
+      Figure 18: Network interface configuration
+
+#. Navigate to the appropriate fields and assign the desired
+   network configuration.
+
+#. To save settings, navigate to :guilabel:`Confirm` and select
+   :kbd:`Enter`.
+
+   .. note::
+
+      To revert to previous settings, navigate to the :guilabel:`Cancel`
+      and select :kbd:`Enter`.
+
+#. Upon confirming network configuration, the :guilabel:`Testing Networking`
+   dialogue appears. Assure the result shows success. If a failure occurs,
+   your changes will not be saved.
+
+#. Upon confirmation, you are returned to :guilabel:`Network interface`
+   settings.
+
+#. Navigate to and select :guilabel:`Main Menu`.
+
+Optional: Skip to `Finish installation`_.
+
+Proxy
+=====
+
+|CL| automatically attempts to detect proxy settings, as described in
+`Autoproxy`_. If you need to manually assign proxy settings, follow this
+instruction.
+
+#. From the Advanced options menu, navigate to :guilabel:`Proxy`, and
+   select :kbd:`Enter`.
+
+#. Navigate to the field :guilabel:`HTTPS Proxy`.
+
+   .. figure:: figures/bare-metal-install-server-19.png
+      :scale: 100%
+      :alt: Configure the network proxy
+
+      Figure 19: Configure the network proxy
+
+#. Enter the desired proxy address and port using conventional syntax,
+   such as: \http://address:port.
+
+#. Navigate to :guilabel:`Confirm` and select :kbd:`Enter`.
+
+#. To revert to previous settings, navigate to :guilabel:`Cancel`
+   and select :guilabel:`Cancel`.
+
+Optional: Skip to `Finish installation`_.
+
+Test Network Settings
+=====================
+
+To manually assure network connectivity before installing |CL|,
+select :guilabel:`Test Network Settings` and select :guilabel:`Enter`.
+
+A progress bar appears as shown in Figure 20.
+
+.. figure:: figures/bare-metal-install-server-20.png
+   :scale: 100%
+   :alt: Testing Networking dialogue
+
+   Figure 20: Testing Networking dialogue
+
+.. note::
+
+   Any changes made to network settings are automatically tested
+   during configuration.
+
+Optional: Skip to `Finish installation`_.
+
+Bundle Selection
+================
+
+#. On the Advanced menu, select :guilabel:`Bundle Selection`
+
+#. Navigate to the desired bundle using :kbd:`Tab` or :kbd:`Up/Down` arrows.
+
+#. Select :kbd:`Spacebar` to select the checkbox for each desired bundle.
+
+   .. figure:: figures/bare-metal-install-server-21.png
+      :scale: 100%
+      :alt: Bundle Selection
+
+      Figure 21: Bundle Selection
+
+#. Optional: To start developing with |CL|, we recommend
+   adding :file:`os-clr-on-clr`.
+
+#. Navigate to and select :kbd:`Confirm`.
+
+   You are returned to the :guilabel:`Advanced options` menu.
+
+Optional: Skip to `Finish installation`_.
+
+Manage User
+===========
+
+Add New User
+------------
+
+#. In Advanced Options, select :guilabel:`Manage User`.
+
+#. Select :guilabel:`Add New User` as shown in Figure 22.
+
+   .. figure:: figures/bare-metal-install-server-22.png
+      :scale: 100%
+      :alt: Add New User, User Name
+
+      Figure 22: Add New User
+
+#. Optional: Enter a :guilabel:`User Name`.
+
+   .. note:
+
+      The User Name must be alphanumeric and can include spaces, commas, or hyphens. Maximum length is 64 characters.
+
+   .. figure:: figures/bare-metal-install-server-23.png
+      :scale: 100%
+      :alt: User Name
+
+      Figure 23: User Name
+
+#. Enter a :guilabel:`Login`.
+
+   .. note::
+
+      The User Login must be alphanumeric and can include hyphens and underscores. Maximum length is 31 characters.
+
+#. Enter a :guilabel:`Password`.
+
+   .. note:
+
+      Minimum length is 8 characters. Maximum length is 255 characters.
+
+#. In :guilabel:`Confirm`, enter the same password.
+
+#. Optional: Navigate to the :guilabel:`Administrative` checkbox and select
+   :kbd:`Spacebar` to assign administrative rights to the user.
+
+   .. note::
+
+      Selecting this option enables sudo privileges for the user.
+
+#. Select :kbd:`Confirm`.
+
+   .. note::
+
+      If desired, select :guilabel:`Reset` to reset the form.
+
+#. In :guilabel:`Manage User`, navigate to :guilabel:`Confirm`.
+
+#. With :guilabel:`Confirm` highlighted, select :kbd:`Enter`.
+
+Modify / Delete User
+--------------------
+
+#. In :guilabel:`Manage User`, navigate to the user you wish
+   to modify until highlighted, as shown in Figure 24.
+
+#. Select :kbd:`Enter` to modify the user.
+
+   .. figure:: figures/bare-metal-install-server-24.png
+      :scale: 100%
+      :alt: Modify User
+
+      Figure 24: Modify User
+
+#. Modify user details as desired.
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+   .. note::
+
+      Optional: Select :guilabel:`Reset` to rest the form.
+
+#. Select :guilabel:`Confirm` to save the changes you made.
+
+#. Optional: In :guilabel:`Modify User`, to delete the user, navigate to
+   the :guilabel:`Delete` button and select :kbd:`Enter`.
+
+   .. figure:: figures/bare-metal-install-server-25.png
+      :scale: 100%
+      :alt: Delete User
+
+      Figure 25: Delete User
+
+You are returned to :guilabel:`Manage User`.
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+#. Select :guilabel:`Enter` to complete :guilabel:`Manage User` options.
+
+Optional: Skip to `Finish installation`_.
+
+Kernel Command Line
+===================
+
+For advanced users, |CL| provides the ability to add or remove kernel
+arguments. If you want to append a new argument, enter the argument here.
+This argument will be used every time you install or update a
+new kernel.
+
+#. In Advanced Options, select :guilabel:`Tab` to highlight
+   :guilabel:`Kernel Command Line`.
+
+#. Select :kbd:`Enter`.
+
+   .. figure:: figures/bare-metal-install-server-26.png
+      :scale: 100%
+      :alt: kernel command line
+
+      Figure 26: kernel command line
+
+#. Choose from the following options.
+
+   * To add arguments, enter the argument in :guilabel:`Add Extra Arguments`.
+
+   * To remove an argument, enter the argument in
+     :guilabel:`Remove Arguments`.
+
+#. Select :kbd:`Confirm`.
+
+Optional: Skip to `Finish installation`_.
+
+Kernel Selection
+================
+
+#. Select a kernel option. By default, the latest kernel release is
+   selected. Native kernel is shown in Figure 27.
+
+#. To select a different kernel, navigate to it using :guilabel:`Tab`.
+
+   .. figure:: figures/bare-metal-install-server-27.png
+      :scale: 100%
+      :alt: Kernel selection
+
+      Figure 27: Kernel selection
+
+#. Select :kbd:`Spacebar` to select the desired option.
+
+#. Navigate to :kbd:`Confirm` and select :kbd:`Enter`.
+
+Optional: Skip to `Finish installation`_.
+
+Swupd Mirror
+============
+
+If you have your own custom mirror of |CL|, you can add its URL.
+
+#. In Advanced Options, select :guilabel:`Swupd Mirror`.
+
+#. To add a local swupd mirror, enter a valid URL in :guilabel:`Mirror URL:`
+
+#. Select :kbd:`Confirm`.
+
+   .. figure:: figures/bare-metal-install-server-28.png
+      :scale: 100%
+      :alt: Swupd Mirror
+
+      Figure 28: Swupd Mirror
+
+Optional: Skip to `Finish installation`_.
+
+Assign Hostname
+===============
+
+#. In Advanced Options, select :guilabel:`Assign Hostname`.
+
+#. In :guilabel:`Hostname`, enter the hostname only (excluding the domain).
+
+   .. note::
+
+      Hostname does not allow empty spaces. Hostname must start with an
+      alphanumeric character but may also contain hyphens. Maximum length of
+      63 characters.
+
+   .. figure:: figures/bare-metal-install-server-29.png
+      :scale: 100%
+      :alt: Assign Hostname
+
+      Figure 29: Assign Hostname
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+#. Select :kbd:`Confirm`.
+
+Optional: Skip to `Finish installation`_.
+
+Automatic OS Updates
+====================
+
+Automatical OS updates are enabled by default. In the rare case that you
+need to disable automatic software updates, follow the onscreen instructions,
+shown in Figure 30.
+
+#. In Advanced Options, select :guilabel:`Automatic OS Updates`.
+
+#. Select the desired option.
+
+   .. figure:: figures/bare-metal-install-server-30.png
+      :scale: 100%
+      :alt: Automatic OS Updates
+
+      Figure 30: Automatic OS Updates
+
+You are returned to the :guilabel:`Main Menu`.
+
+Save Configuration Settings
+===========================
+
+#. In Advanced Options, select :guilabel:`Save Configuration Settings`.
+
+#. A dialogue box shows the installation configuration was saved to
+   :file:`clr-installer.yaml`
+
+   .. figure:: figures/bare-metal-install-server-31.png
+      :scale: 100%
+      :alt: Automatic OS Updates
+
+      Figure 31: Automatic OS Updates
+
+#. Use the :file:`clr-installer.yaml` file to install |CL|, with the same
+   configuration, on multiple targets.
+
+Finish installation
+*******************
+
+#. When you are satisfied with your installation configuration, navigate to
+   :guilabel:`Install` and select :kbd:`Enter`.
+
+   .. figure:: figures/bare-metal-install-server-32.png
+      :scale: 100%
+      :alt: Select Install
+
+      Figure 32: Select Install
+
+#. Select :guilabel:`reboot`.
+
+   .. note::
+
+      If you do not assign an administrative user, upon rebooting,
+      enter `root` and set the root password immediately.
+
+#. When the system reboots, remove any installation media present.
+
+Default partition schema
+========================
+
+To add partitions manually, see `Advanced configuration`_ below, and create
+partitions per requirements in Table 1.
+
+.. list-table:: **Table 1. Disk Partition Setup**
+   :widths: 33, 33, 33
+   :header-rows: 1
+
+   * - FileSystem
+     - Mount Point
+     - Minimum size
+   * - ``VFAT``
+     - /boot
+     - 150M
+   * - ``swap``
+     -
+     - 256MB
+   * - ``root``
+     - /
+     - *Size depends upon use case/desired bundles.*
+
+Troubleshooting
+***************
+
+For Configure Installation Media
+================================
+
+If a warning message appears that no media or space is available after
+entering :guilabel:`Configure Installation Media`:
+
+- Verify that target media has enough free space.
+
+- Confirm the USB is properly connected to and mounted on target media.
+
+- Review the size of existing partitions on the target media:
+
+  - Linux\* OS: :command:`lsblk -a`
+  - Windows\* OS:  :command:`diskpart`, then :command:`list disk`
+  - macOS\* platform: :command:`diskutil list`
+
+.. _Autoproxy: https://clearlinux.org/features/autoproxy
+.. _downloads page: https://clearlinux.org/downloads

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

@@ -1,326 +0,0 @@
-.. _bare-metal-install:
-
-Install Clear Linux OS on bare metal (automatic)
-################################################
-
-These instructions guide you through the installation of |CLOSIA|
-on bare metal using a bootable USB drive.
-
-Before you begin, run our :ref:`compatibility-check`.
-
-
-Download the latest Clear Linux 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
-
-Once you have downloaded the image, verify and uncompress the file.
-
-.. include:: ../../guides/maintenance/download-verify-uncompress-linux.rst
-   :Start-after: verify-linux:
-   :end-before: To uncompress a GZ
-
-.. include:: ../bootable-usb/bootable-usb-linux.rst
-   :Start-after: copy-usb-linux:
-   :end-before: usb-next
-
-.. _install-on-target:
-
-Install Clear Linux 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
-partition. The target system needs a wired Internet connection with DHCP.
-
-Follow these steps to install |CL| on the target system:
-
-#. Insert the USB drive into an available USB slot.
-
-#. Power on the system.
-
-#. Open the system BIOS setup menu by pressing the :kbd:`F2` key.
-   Your BIOS setup menu entry point may vary.
-
-#. In the setup menu, enable the UEFI boot and set the USB drive as the first
-   option in the device boot order.
-
-#. Save these settings and exit.
-
-#. Reboot the target system.
-
-#. The |CL| Installer 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
-
-      Figure 1: :guilabel:`Clear Linux 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
-   navigate through the |CL| installer setup menus.
-
-   .. figure:: figures/bare-metal-install-2.png
-      :scale: 50 %
-      :alt: Clear Linux OS for Intel Architecture Installer
-
-      Figure 2: :guilabel:`Clear Linux OS for Intel Architecture Installer`
-
-   Press the :kbd:`Enter` key.
-
-#. The :guilabel:`Keyboard selection` menu shown in figure 3 allows you to set
-   up the keyboard layout that you will be using to navigate within the |CL|
-   installer setup menus.
-
-   .. figure:: figures/bare-metal-install-3.png
-      :scale: 50 %
-      :alt: Keyboard Selection
-
-      Figure 3: :guilabel:`Keyboard Selection`
-
-   For this guide we will select :menuselection:`Keyboard Selection -->
-   < * us >` for the keyboard mapping, which should already be highlighted.
-   Press the :kbd:`Enter` key to continue to the next menu.
-
-Network requirements
-====================
-
-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:: figures/bare-metal-install-4.png
-   :scale: 50 %
-   :alt: Network Requirements
-
-   Figure 4: :guilabel:`Network Requirements`
-
-If you need to configure any :guilabel:`Proxy Settings` to gain access to the
-update server, enter the appropriate address and port of your proxy server in
-the :guilabel:`HTTPS proxy:` field.  Select the :guilabel:`< Set proxy
-configuration >` button and press :kbd:`Enter`. You will then see the
-connection to the update server established.
-
-Optionally, set up a :guilabel:`static IP configuration` to your |CL|
-installer image.  Enter the required information in the :guilabel:`Interface`,
-:guilabel:`IP address`, :guilabel:`Subnet mask`, :guilabel:`Gateway` and
-:guilabel:`DNS` fields and then select the :guilabel:`< Set static IP
-configuration >` button and press the :kbd:`Enter` key.
-
-The information displayed in the lower right quadrant of the screen shows the
-current IP configuration for the |CL| update server where the installer image
-is located.
-
-.. note::
-
-   If you are having difficulty establishing a connection to the update server
-   and you see the message :guilabel:`none detected, install will fail`, you
-   can press the :kbd:`Tab` key to highlight the :guilabel:`< Refresh >`
-   button and press :kbd:`Enter` to attempt to reconnect to the |CL| update
-   server. If this fails to establish a connection after multiple attempts,
-   reboot your system and return to this step.
-
-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
-===================================
-
-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:
-
-.. figure:: figures/bare-metal-install-5.png
-   :scale: 50 %
-   :alt: Choose Action
-
-   Figure 5: :guilabel:`Choose Action`
-
-#. Select the :menuselection:`Choose action --> Install` menu item to continue
-   the installation process.
-
-   The :menuselection:`Choose action --> Repair` menu option will run the
-   :command:`swupd --fix` command to correct any issues found with the system
-   software that has already been installed on your system and correct any
-   issues found by overwriting the incorrect file content, adding missing
-   files, fixing permissions and any additional changes required to return the
-   file to it's original content and permissions.
-
-   The :menuselection:`Choose action --> Shell` menu item opens a terminal
-   session on your system as the root user and you will be able to manage your
-   system from this console.  When you are finished, type :command:`exit` to
-   return to the :guilabel:`Choose Action` menu.
-
-   The :menuselection:`Choose action --> Exit` menu option terminates the |CL|
-   installation process and the system will shut down.
-
-#. You will be prompted to join the :guilabel:`Stability Enhancement Program`
-   as shown in figure 6. Press the :kbd:`Spacebar` or :kbd:`Enter` key until
-   the cursor appears in the :guilabel:`[ ] Yes.` button. Press tab to highlight :guilabel:`< Next >`, and select Enter to advance.
-
-   .. figure:: figures/bare-metal-install-6.png
-      :scale: 50 %
-      :alt: Stability Enhancement Program
-
-      Figure 6: :guilabel:`Stability Enhancement Program`
-
-   If you choose not to enable this functionality during this step, you can
-   install the ``telemetrics`` software bundle at a later time. As stated in
-   the menu, this feature only collects anonymous information about your
-   system to help improve system stability and no personally identifiable
-   information is collected. Please visit our website to
-   `learn more about telemetry.`_
-
-Choose Clear Linux installation type
-************************************
-
-Figure 7 shows the next step of the |CL| installer:
-:guilabel:`Choose installation Type`. Chose whether to install |CL|
-**automatically** or **manually**.  To end the installer process and shut down
-the system, select the :guilabel:`< Exit >` button.
-
-.. figure:: figures/bare-metal-install-7.png
-   :scale: 50 %
-   :alt: Choose installation type
-
-   Figure 7: :guilabel:`Choose installation Type`
-
-If you select :guilabel:`< Automatic >` as the installation type, the |CL|
-Installer will add the minimum amount of functionality required for a fully
-functional |CL| system. You will not be able to modify the disk layout, add
-a user or any other tasks that the manual installation process will allow.
-
-With the :guilabel:`< Manual(Advanced) >` option, you can do the following
-additional tasks during |CL| Installer setup:
-
-* Modify the disk layout using the cgdisk utility.
-* Add additional command-line parameters to the kernel.
-* Create a hostname for your system.
-* Create an administrative user.
-* Add additional software bundles to enhance the functionality of your initial
-  |CL| installation.
-* Optionally, set up a static IP address for your system.
-
-If you want to perform any of these additional tasks, select the
-:guilabel:`< Manual(Advanced) >` menu item and follow the steps in our
-: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
-**********************************
-
-#. To install the minimum components for your |CL| implementation, select the
-   :guilabel:`< Automatic >` menu item shown in figure 7 and press the
-   :kbd:`Enter` key.
-
-   The :guilabel:`Choose target device for installation` screen shown in figure 8 appears.  
-
-#. Move the cursor to the desired target and press the :kbd:`Enter`
-   key.
-
-   .. figure:: figures/bare-metal-install-8.png
-      :scale: 50 %
-      :alt: Choose target device for installation
-
-   Figure 8: :guilabel:`Choose target device for installation`
-
-   In this example, we selected the single primary partition from our hard drive.
-
-   With all the |CL| installer setup information gathered for the automatic
-   installation option, the |CL| Installer prompts you to begin the actual
-   installation as shown in figure 9.
-
-   .. figure:: figures/bare-metal-install-9.png
-      :scale: 50 %
-      :alt: Begin installation
-
-   Figure 9: :guilabel:`Begin installation`
-
-#. When you are satisfied with the information you have entered, select the
-   :guilabel:`< Yes >` button and press :kbd:`Enter` to begin installing |CL|.
-
-   |CL| Installation begins and each step shows its status as it progresses
-   through the automated installation process.
-
-   Once all steps have completed, you will see the :guilabel:`Successful
-   installation` status message and the :guilabel:`< Ok >` button is highlighted as shown in figure 10. 
-
-#. Press the :kbd:`Enter` key to continue.
-
-   .. figure:: figures/bare-metal-install-10.png
-      :scale: 50 %
-      :alt: Installation complete
-
-      Figure 10: :guilabel:`Installation complete`
-
-   Figure 11 shows the final installer screen, showing that the
-   installation completed successfully and the system will reboot. 
-
-#. Press the :kbd:`Enter` key and remove the USB media while the system 
-   restarts. 
-
-   .. figure:: figures/bare-metal-install-11.png
-      :scale: 50 %
-      :alt: Successful installation
-
-      Figure 11: :guilabel:`Successful Installation`
-
-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:
-
-.. figure:: figures/bare-metal-install-12.png
-   :scale: 50 %
-   :alt: Login screen
-
-   Figure 12: :guilabel:`Login screen`
-
-#. At the initial login prompt, enter: ``root``
-
-#. Once prompted, enter a new password.
-
-#. Re-enter the password to verify it.
-
-You have now set your root password and are logged in with root privileges.
-
-**Congratulations!**
-
-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`.
-
-* 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.
-
-
-.. _`information about stateless`:
-   https://clearlinux.org/features/stateless
-
-.. _`learn more about telemetry.`:
-   https://clearlinux.org/features/telemetry
-
-.. _`NUC6i5SYH product page`:
-   http://www.intel.com/content/www/us/en/nuc/nuc-kit-nuc6i5syh.html
-
-.. _image: https://download.clearlinux.org/image

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

@@ -1,286 +0,0 @@
-.. _bare-metal-manual-install:
-
-Install |CL-ATTR| on bare metal (manual)
-#############################################
-
-This section contains the steps for a |CL-ATTR| manual installation. It
-picks up where the :ref:`bare-metal-install` left off.
-
-To perform additional tasks during the |CL| Installer setup, select the 
-:guilabel:`< Manual(Advanced) >` menu option (figure 1).  
-
-* :ref:`Modify the disk layout using the cgdisk utility<cgdisk-manual-install>`
-* Add additional command-line parameters to the kernel
-* Create a hostname for your system
-* Create an administrative user
-* Add additional software bundles to enhance the functionality of your
-  initial |CL| installation
-* Optionally set up a static IP address for your system
-
-Begin the manual installation process
-*************************************
-
-#. Move the cursor to the :guilabel:`< Manual(Advanced) >` menu item
-   and press the :kbd:`Enter` key.
-
-   .. figure:: figures/bare-metal-manual-install-1.png
-      :scale: 50 %
-      :alt: Choose installation Type
-
-   Figure 1: :guilabel:`Choose installation Type`
-
-#. The screen :guilabel:`Choose partitioning method` will
-   appear (figure 2).
-
-   .. figure:: figures/bare-metal-manual-install-2.png
-      :scale: 50 %
-      :alt: Choose partitioning method
-
-      Figure 2: :guilabel:`Choose partitioning method`
-
-   If your hard drive has already been partitioned for a Linux system, you 
-   can select the :guilabel:`< Use default partition and mount scheme on 
-   target device >` menu item and press :kbd:`Enter` to move to the next
-   step of the installer setup process.
-
-   .. _cgdisk-manual-setup:
-
-   Otherwise, to set up your hard drive partitions manually before moving to
-   the next step, select the :guilabel:`< Manually configure mounts and
-   partitions >` menu item and follow the instructions for :ref:`using CGDISK
-   to set up your Clear Linux hard drive<cgdisk-manual-install>`.
-
-.. _choose-target-device:
-
-Choose target device for installation
-=====================================
-
-The :guilabel:`Choose target device for installation` menu, shown in figure 
-3, displays the current device and partition information. In
-this example, ``/dev/sda`` is the only drive on the system with three
-partitions defined and assigned. The menu cursor highlights the partition
-to install |CL| onto.
-
-#. Select the :guilabel:`< Partition /dev/sda >` button and press the
-   :kbd:`Enter` key.
-
-   .. note::
-
-      To return to the previous menu, press the :kbd:`Tab` key
-      to highlight the :guilabel:`< Previous >` button and press :kbd:`Enter`
-      to return to the previous menu.
-
-   .. figure:: figures/bare-metal-manual-install-3.png
-      :scale: 50 %
-      :alt: Choose target device for installation
-
-      Figure 3: :guilabel:`Choose target device for installation`
-
-#. Next, you will be presented with a warning screen (figure 4) with
-   :guilabel:`< No >` highlighted by default. If this is the device onto
-   which you wish to install |CL|, press :kbd:`Tab` to highlight
-   the :guilabel:`< Yes >` button. 
-
-#. Press :kbd:`Enter` to proceed.
-
-   .. figure:: figures/bare-metal-manual-install-4.png
-      :scale: 50 %
-      :alt: Device installation warning
-
-      Figure 4: :guilabel:`Device installation warning`
-
-.. _Additional_manual_installer_settings:
-
-Additional manual installer settings
-====================================
-
-The next steps of the manual installer setup process allows you to:
-
-* Set up any additional command-line parameters to the kernel.
-* Create a hostname for your system.
-* Set up an administrative user.
-* Install additional software bundles.
-* Optionally create a static IP address for your system.
-
-#. The :guilabel:`Append to kernel cmdline` menu shown in figure 5 allows you
-   to add more options to the kernel command-line to further customize
-   your installation.  Normally this is not required; however, if there are
-   specific options that need to be set in the Linux kernel, you can enter
-   them here. For a complete list of command-line parameters for the Linux
-   kernel you can visit the official documentation of the `latest kernel's
-   command-line parameters`_.
-
-   Add any additional command-line parameters in the :guilabel:`Append to
-   cmdline:` field and then press the :kbd:`Tab` key to move to the
-   :guilabel:`< Next >` button and press :kbd:`Enter`.
-
-   .. figure:: figures/bare-metal-manual-install-5.png
-      :scale: 50 %
-      :alt: Append to kernel cmdline
-
-      Figure 5: :guilabel:`Append to kernel cmdline`
-
-#. The :guilabel:`Configuring Hostname` menu shown in figure 6 suggests
-   a hostname string prefaced with "clr". You can make your hostname anything
-   meaningful and unique. Once complete, press the :kbd:`Tab` key to move to
-   the :guilabel:`< Next >` button and press :kbd:`Enter`.
-
-   .. figure:: figures/bare-metal-manual-install-6.png
-      :scale: 50 %
-      :alt: Configure Hostname
-
-   Figure 6: :guilabel:`Configure Hostname`
-
-   To learn more about hostname naming conventions and restrictions, you can
-   check this `wiki page about hostnames`_.
-
-#. The :guilabel:`User configuration` menu shown in figure 7 allows you to
-   create a userid with administrative privileges. If you do not want to 
-   create a user at this time, select 
-   :guilabel:`< No user creation (login as root) >` to skip this step and
-   proceed to the :guilabel:`Bundle selector` menu.
-
-   .. figure:: figures/bare-metal-manual-install-7.png
-      :scale: 50 %
-      :alt: User configuration
-
-   Figure 7: :guilabel:`User configuration`
-
-   #. To create a userid, select the :guilabel:`< Create an administrative 
-      user >` field and press :kbd:`Enter` to go to the the next screen.
-   #. You will be presented with the second :guilabel:`User configuration` 
-      menu shown in figure 8. You are only required to fill in the
-      :guilabel:`Username`, :guilabel:`Password`, and :guilabel:`Confirm 
-      password` fields.
-   #. To give a user administrative privileges, press :kbd:`Tab` until
-      cursor appears in the field :guilabel:`Add user to the sudoers?` and
-      select. This adds the user to the ``wheel`` group and allows entry of 
-      the :command:`sudo` command.
-
-      After entering all data, press :kbd:`Tab` until :guilabel:`< Next >`
-      is highlighted. Then press :kbd:`Enter`.
-
-      .. figure:: figures/bare-metal-manual-install-8.png
-         :scale: 50 %
-         :alt: User configuration - create user
-
-      Figure 8: :guilabel:`User configuration - create user`
-
-#. In the menu :guilabel:`Bundle selector` (figure 9), you can add
-   software bundles to your initial |CL| installation. Press the :kbd:`Tab`
-   key to highlight additional bundles, and then press :kbd:`Spacebar` or 
-   :kbd:`Enter` to select each bundle. This menu will also list the
-   additional :guilabel:`--- required ---` software bundles that will be
-   installed during the |CL| installation.
-
-   .. figure:: figures/bare-metal-manual-install-9.png
-      :scale: 50 %
-      :alt: Bundle selector
-
-      Figure 9: :guilabel:`Bundle selector`
-
-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.
-
-Target system network configuration
-===================================
-
-Before the actual |CL| installation begins, we must set up the
-:guilabel:`Network configuration` shown in figure 10. Select
-:guilabel:`< Use DHCP >` to have an IP address automatically assigned when
-the system boots up.
-
-.. figure:: figures/bare-metal-manual-install-10.png
-   :scale: 50 %
-   :alt: Network configuration
-
-   Figure 10: :guilabel:`Network configuration`
-
-You can optionally set up a static IP address for your system.  Select the
-:guilabel:`< Use static IP configuration >` menu item and fill in the
-required fields.
-
-Begin installation
-******************
-
-The |CL| installer is now ready to use the information you provided on the
-previous sections to begin the actual installation. Figure 11 shows the
-installer's prompt to begin the installation.
-
-.. figure:: figures/bare-metal-manual-install-11.png
-   :scale: 50 %
-   :alt: Begin installation
-
-   Figure 11: :guilabel:`Begin installation`
-
-When you are satisfied with the information entered, select the
-:guilabel:`< Yes >` button and press :kbd:`Enter` to begin installing |CL|.
-
-The |CL| Installation begins and each step shows its status as it progresses
-through the manual installation process as shown in figure 12.
-
-.. figure:: figures/bare-metal-manual-install-12.png
-   :scale: 50 %
-   :alt: Installation status
-
-   Figure 12: :guilabel:`Installation status`
-
-Once all steps have completed, you will see the ``Successful installation``
-status message and the :guilabel:`< Ok >` button is highlighted as shown in
-figure 13. Press the :kbd:`Enter` key to continue.
-
-.. figure:: figures/bare-metal-manual-install-13.png
-   :scale: 50 %
-   :alt: Installation complete
-
-   Figure 13: :guilabel:`Installation complete`
-
-Congratulations! The installation completed successfully and the system will
-reboot. Figure 14 shows the installer's final prompt. Press the :kbd:`Enter`
-key and remove the USB media while the system restarts.
-
-.. figure:: figures/bare-metal-manual-install-14.png
-   :scale: 50 %
-   :alt: Successful Installation
-
-   Figure 14: :guilabel:`Successful Installation`
-
-Once the system boots, the Gnome Desktop sign-in screen shown in figure 15
-appears:
-
-.. figure:: figures/bare-metal-manual-install-15.png
-   :scale: 50 %
-   :alt: Gnome sign-in screen
-
-   Figure 15: :guilabel:`Gnome sign-in screen`
-
-Click on the :guilabel:`username` you created, enter the password, and you
-will be logged into the system. The Gnome 3 desktop appears as shown in
-figure 16:
-
-.. figure:: figures/bare-metal-manual-install-16.png
-   :scale: 50 %
-   :alt: Gnome Desktop Manager
-
-   Figure 16: :guilabel:`Gnome Desktop Manager`
-
-**Congratulations!**
-
-You have successfully installed |CL| on a bare metal system using the
-manual installation method.
-
-Visit our :ref:`tutorials <tutorials>` section for examples on using your
-|CL| system.
-
-.. _`information about stateless`:
-   https://clearLinux.org/features/stateless
-
-.. _`wiki page about Hostnames`:
-   https://en.wikipedia.org/wiki/Hostname
-
-.. _`learn more about telemetry.`:
-   https://clearLinux.org/features/telemetry
-
-.. _`latest kernel's command-line parameters`:
-   https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html

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

@@ -1,294 +0,0 @@
-.. _cgdisk-manual-install:
-
-Create partitions for Clear Linux\* 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
-<bare-metal-manual-install>`.
-
-Prerequisites
-*************
-
-This guide assumes that you have followed the :ref:`bare-metal-install`
-guide and intend to :ref:`install Clear Linux manually
-<bare-metal-manual-install>` by choosing the :guilabel:`< Manual(Advanced) >`
-menu item on the :guilabel:`Choose Installation Type` |CL| Installer setup
-menu as shown in figure 1:
-
-.. figure:: figures/cgdisk-manual-install-1.png
-   :scale: 50 %
-   :alt: Choose installation Type
-
-   Figure 1: :guilabel:`Choose installation Type`
-
-Partition using CGDISK
-**********************
-
-We use the :command:`cgdisk` application to create a
-:abbr:`GPT (GUID Partition Table)` since |CL| only supports the
-:abbr:`UEFI (Unified Extensible Firmware Interface)` specification. For a
-complete description of the :command:`cgdisk` utility and how to use it,
-visit Rod Smith's website for a `GPT fdisk tutorial`_.
-
-In this guide, we intend to use an unpartitioned hard drive for the |CL|
-installation.
-
-#. To manually partition your hard drive, select 
-   :guilabel:`< Manually configure mounts and partitions >` in the menu
-   :guilabel:`Choose partitioning method`, shown in figure 2. 
-   
-   .. figure:: figures/cgdisk-manual-install-2.png
-      :scale: 50 %
-      :alt: Choose partitioning method
-
-      Figure 2: :guilabel:`Choose partitioning method`
-
-   Next, the current device available to partition is shown. In this
-   example, shown in figure 3, :file:`/dev/sda` is available but
-   does not have any partitions defined.
-
-#. Select the :guilabel:`< Partition /dev/sda >` menu item and press
-   :kbd:`Enter` to begin the process of modifying this disk.
-
-   .. figure:: figures/cgdisk-manual-install-3.png
-      :scale: 50 %
-      :alt: Choose a drive to partition using cgdisk tool
-
-      Figure 3: :guilabel:`Choose a drive to partition using cgdisk tool`
-
-   The :command:`cgdisk` application starts and displays the settings for
-   :file:`/dev/sda` as shown in figure 4.
-
-   .. figure:: figures/cgdisk-manual-install-4.png
-      :scale: 50 %
-      :alt: cgdisk
-
-      Figure 4: :guilabel:`cgdisk`
-
-Linux Partition setup
-*********************
-
-In order to properly set up the |CL| partitioning scheme, we create three
-partitions using the :command:`cgdisk` utility in the following order:
-
-#. EFI boot partition
-#. Linux swap partition
-#. Linux root partition
-
-For a complete understanding of these partitions, you can review the
-`Linux partitioning scheme`_ information.
-
-Create the EFI boot partition
-=============================
-
-#. With the free space highlighted in the :command:`cgdisk` utility,
-   you can either select the :guilabel:`[ New ]` button and press :kbd:`Enter`
-   or press the :kbd:`N` key to define a new partition.
-
-   The utility prompts you to enter the first sector. Press the :kbd:`Enter`
-   key to accept the default value shown.
-
-   .. note::
-      In this example, the first sector starts at 2048. For more information
-      about alignment using the cgdisk tool, see
-      `Rod Smith's Partitioning Advice about alignment`_.
-
-#. The program then prompts you for the size of the partition. To create a
-   512MB partition, enter 512M and press :kbd:`Enter` as shown in figure 5:
-
-   .. figure:: figures/cgdisk-manual-install-5.png
-      :scale: 50 %
-      :alt: cgdisk - New
-
-      Figure 5: :guilabel:`cgdisk - New partition`
-
-#. To define the type of partition, the :command:`cgdisk` utility has
-   pre-defined partition types. Press the :kbd:`L` key to show the hex codes
-   you can use. Use these codes to set the correct
-   :abbr:`GUID (Globally unique identifier)` for *GPT partition types* as
-   shown in figure 6:
-
-   .. figure:: figures/cgdisk-manual-install-6.png
-      :scale: 50 %
-      :alt: cgdisk - hex codes for partition types
-
-      Figure 6: :guilabel:`cgdisk - hex codes for partition types`
-
-   We need to use the following three codes for our partitions:
-
-   * ef00 - EFI System
-   * 8200 - Linux swap
-   * 8300 - Linux filesystem
-
-#. To create the EFI boot partition, enter ``ef00`` as the hexcode for this
-   partition and press :kbd:`Enter`.
-
-#. To name the partition, enter ``boot`` and press :kbd:`Enter` to finish
-   setting up the EFI boot partition. The utility shows the first partition as
-   an ``EFI System`` 512MiB partition named ``boot`` as shown in figure 7:
-
-   .. figure:: figures/cgdisk-manual-install-7.png
-      :scale: 50 %
-      :alt: cgdisk - boot partition defined
-
-      Figure 7: :guilabel:`cgdisk - boot partition defined`
-
-Create the Linux swap partition
-===============================
-
-Next, we must create the Linux swap partition. In figure 7, notice the two
-areas defined as free space. We created the first 1007.0 KiB free space area
-when we started the EFI boot partition at sector 2048. For more information
-about it, review `Rod Smith's Partitioning advice about alignment`_.
-
-#. Move your cursor to highlight the larger free space of 334.8 GiB at the
-   bottom of the partition list before you begin to create the Linux swap
-   partition as shown in figure 8:
-
-   .. figure:: figures/cgdisk-manual-install-8.png
-      :scale: 50 %
-      :alt: cgdisk - free space selection
-
-      Figure 8: :guilabel:`cgdisk - free space selection`
-
-#. To create the Linux swap partition, with the largest free space
-   highlighted, select the :guilabel:`[ New ]` button or press the :kbd:`N`
-   key and enter the following values for the Linux swap partition:
-
-   .. code-block:: console
-
-      First sector:  press :kbd:`Enter` to select the default value
-      Size in sectors:  4G
-      Hex code or GUID:  8200
-      Enter new partition name:  swap
-
-   Your :command:`cgdisk` partition list should now look like figure 9.
-
-   .. figure:: figures/cgdisk-manual-install-9.png
-      :scale: 50 %
-      :alt: cgdisk - swap partition defined
-
-      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.
-
-#. Highlight the largest free space entry at the bottom of the list and select
-   the :guilabel:`[ New ]` button or press the :kbd:`N` key and enter the
-   following values to create the Linux filesystem partition:
-
-   .. code-block:: console
-
-      First sector:  press :kbd:`Enter` to select the default value
-      Size in sectors:  press :kbd:`Enter` to select the default value, which
-                        is the remainder of available space on the disk
-      Hex code or GUID:  8300
-      Enter new partition name:  root
-
-   With all the partitions now defined, you should see a list similar to what
-   is shown in figure 10:
-
-   .. figure:: figures/cgdisk-manual-install-10.png
-      :scale: 50 %
-      :alt: cgdisk - defined partitions
-
-      Figure 10: :guilabel:`cgdisk - defined partitions`
-
-#. If you are satisfied that the partition scheme is correct, you need to
-   write this GPT to the hard drive. Select the :guilabel:`[ Write ]` button
-   or press the :kbd:`W` key and the :command:`cgdisk` program prompts with:
-
-   .. code-block:: console
-
-      Are you sure you want to write the partition table to disk? (yes or no)
-
-#. Enter ``yes`` and press :kbd:`Enter` to write this data to the hard drive
-   and then select the :guilabel:`[ Quit ]` button or press :kbd:`Q` to exit
-   the :command:`cgdisk` utility.
-
-#. You see the partitions that were created as shown in figure 11. Move your
-   cursor to the :guilabel:`< Next >` button and press :kbd:`Enter`.
-
-   .. figure:: figures/cgdisk-manual-install-11.png
-      :scale: 50 %
-      :alt: defined partitions
-
-      Figure 11: :guilabel:`defined partitions`
-
-Set the mount points
-********************
-
-The :guilabel:`Set mount points` menu sets the mount points that the |CL|
-installer uses for your |CL| installation, shown in figure 12.
-
-.. figure:: figures/cgdisk-manual-install-12.png
-   :scale: 50 %
-   :alt: Set mount points
-
-   Figure 12: :guilabel:`Set mount points`
-
-In this menu you need to set the mount points for the boot and root
-partitions and select to format them.
-
-#. Highlight the EFI System partition type menu entry and press the
-   :kbd:`Enter` key to edit this item. The :guilabel:`Set mount point of
-   sda1` menu is shown.
-
-   #. For :guilabel:`Enter mount point:` type `/boot` and press
-      :kbd:`Enter`.
-   #. Press Tab to enter the :guilabel:`[ ] Format` field. 
-   #. Press Enter/Spacebar to select :guilabel:`[ ] Format`, which allows
-      formatting of the partition. 
-      
-   Figure 13 shows the information entered.  Select :guilabel:`< Next >`
-   and press :kbd:`Enter`.
-
-   .. figure:: figures/cgdisk-manual-install-13.png
-      :scale: 50 %
-      :alt: Set mount point of sda1
-
-      Figure 13: :guilabel:`Set mount point of sda1`
-
-#. Do the same for the Linux filesystem partition by highlighting the
-   :guilabel:`Linux filesystem` menu entry and entering the information shown
-   in figure 14 to set the :guilabel:`Enter mount point:` to :file:`/` and
-   enable formatting:
-
-   .. figure:: figures/cgdisk-manual-install-14.png
-      :scale: 50 %
-      :alt: Set mount point of sda3
-
-      Figure 14: :guilabel:`Set mount point of sda3`
-
-   Upon completion, the :guilabel:`Set mount points` appear as shown
-   in figure 15:
-
-   .. figure:: figures/cgdisk-manual-install-15.png
-      :scale: 50 %
-      :alt: Set mount point completed
-
-      Figure 15: :guilabel:`Set mount points completed`
-
-#. 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*.
-
-.. _`GPT fdisk tutorial`:
-   http://www.rodsbooks.com/gdisk/
-
-.. _`Rod Smith's Partitioning Advice about alignment`:
-   http://www.rodsbooks.com/gdisk/advice.html#alignment
-
-.. _`information about swupd`:
-   https://clearlinux.org/features/software-update
-
-.. _`Linux partitioning scheme`:
-   https://wiki.archlinux.org/index.php/partitioning#Partition_scheme