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

This reverts commit 186f1e02b8.

.buildinfo

@@ -1,4 +0,0 @@
-# Sphinx build info version 1
-# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: cc99ba4fd98ddc62c1fab24f336360f5
-tags: 645f666f9bcd5a90fca523b33c5a78b7

.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

@@ -0,0 +1,9 @@
+#Exluding from the tree the html build files
+source/_build
+# ignore vi temporary files
+*.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

Makefile

@@ -0,0 +1,16 @@
+# Makefile for Sphinx documentation
+#
+
+all:
+	make -C source html
+
+html:
+	make -C source html
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+
+clean:
+	make -C source clean
+

README.rst

@@ -0,0 +1,74 @@
+Documentation build instructions
+################################
+
+.. todo add comment re not using standards here.
+
+`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
+************
+
+Make sure you have Python and Sphinx installed. We use Python 3 and
+Sphinx 1.7.5
+
+The Sphinx documentation provides `instructions for installing Sphinx`_ on various
+platforms.
+
+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 the build
+*************
+
+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.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
+documentation.
+
+When testing changes in the documentation, make sure to remove the previous
+build before building again by running **make clean**:
+
+.. code-block:: console
+
+   $ 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/
+.. _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
+

_sources/FAQ/faq.rst.txt

@@ -1,189 +0,0 @@
-.. _faq:
-
-FAQ
-###
-
-Below is a list of commonly asked questions with answers sourced from the
-|CL-ATTR| team and `Clear Linux community forums`_.
-
-.. contents:: :local:
-    :depth: 2
-
-
-General
-*******
-
-Why did you make another distro?
-================================
-
-The |CL| team felt that performance was left on the table with Linux software.
-|CL| takes a holistic approach to improving performance across the stack. We
-also wanted to take more modern approaches with OS updates and tooling.
-
-|
-
-Can other distros copy |CL| improvements?
-=========================================
-
-Yes, we absolutely love open source reuse and upstreaming improvements.
-
-|
-
-How often do you update?
-========================
-
-The |CL| team puts out multiple releases a week, often releasing 2 or more
-times a day. This rolling release approach allows |CL| to remain agile to
-upstream changes and security patches.
-
-|
-
-Is telemetry required?
-======================
-
-The telemetry solution provided by |CL| is entirely optional and customizable.
-It is disabled by default. If you do choose to enable telemetry, the data
-helps the |CL| team proactively identify and resolve bugs. See the
-:ref:`telemetry <telemetry-about>` page for more information.
-
-|
-
-What is the default firewall?
-=============================
-
-|CL| packages :command:`iptables` as a bundle, however, there are no default
-firewall rules. All network traffic is allowed by default.
-
-|
-
-Where are the files that I usually see under /etc like fstab?
-=============================================================
-
-|CL| has a stateless design that maintains a separation between system files
-and user files. Default values are stored under :file:`/usr/share/defaults/`.
-Files under :file:`/etc/` are not created unless you create one.
-
-A blog post explaining how this is accomplished with :file:`/etc/fstab/`
-specifically is available here:
-https://clearlinux.org/news-blogs/where-etcfstab-clear-linux
-
-|
-
-Software packages
-*****************
-
-How is software installed and updated?
-======================================
-
-|CL| provides software in the form of :ref:`bundles <bundles-about>` and
-updates software with :ref:`swupd <swupd-about>`.
-
-:ref:`FlatPak\* <flatpak>` is an application virtualization solution that allows
-more software to be available to |CL| users by augmenting the software |CL|
-packages natively with software available through FlatPak.
-
-Our goal is to have software packaged natively and made available through
-bundles whenever possible.
-
-|
-
-Does |CL| use RPMs like other distros?
-======================================
-
-|CL| provides software in the form of :ref:`bundles <bundles-about>`. The RPM
-format is used as an intermediary step for packaging and determining software
-dependencies at OS build time.
-
-Individual RPMs can sometimes be manually installed on a |CL| system with the
-right tools, but that is not the intended use case.
-
-|
-
-Can I install a software package from another OS on |CL|?
-=========================================================
-
-Software that is packaged in other formats for other Linux distributions is
-not guaranteed to work on |CL| and may be impacted by |CL| updates.
-
-If the software you're seeking is open source, please submit a request to add
-it to |CL|. Submit requests on GitHub\* here:
-https://github.com/clearlinux/distribution/issues
-
-|
-
-Software availability
-*********************
-
-What software is available on |CL|?
-===================================
-
-Available software can be found in the `Software Store`_, through the GNOME\*
-Software application on the desktop, or by using :ref:`swupd search <bundle-commands>`.
-
-|
-
-Is Google\* Chrome\* available?
-===============================
-
-The Google Chrome web browser is not distributed as a bundle in |CL| due to
-copyright and licensing complexities.
-
-A discussion on manually installing and maintaining Google Chrome can be found
-on GitHub: https://github.com/clearlinux/distribution/issues/422
-
-|
-
-Is FFmpeg available?
-====================
-
-`FFmpeg`_ is a multimedia software suite, which is commonly used for
-various media encoding/decoding, streaming, and playback.
-
-|CL| does not distribute FFmpeg due to well-known licensing and legal
-complexities (See https://www.ffmpeg.org/legal.html and
-http://blog.pkh.me/p/13-the-ffmpeg-libav-situation.html).
-
-Read more in the |CL| repository, including discussion of an alternative
-hardware-based solution:
-https://github.com/clearlinux/distribution/issues/429.
-
-While |CL| cannot distribute FFmpeg, a manual solution to build and install
-FFmpeg under :file:`/usr/local` has been shared on the community forums:
-https://community.clearlinux.org/t/how-to-h264-etc-support-for-firefox-including-ffmpeg-install.
-
-|
-
-Is ZFS\* available?
-===================
-
-ZFS is not available with |CL| because of copyright and licensing
-complexities. BTRFS is an alternative filesystem that is available in |CL|
-natively.
-
-A user on GitHub notes that the ZFS kernel module can be compiled, built, and
-installed manually: https://github.com/clearlinux/distribution/issues/631
-
-|
-
-Can you add a driver that I need?
-=================================
-
-If a kernel module is available as part of the Linux kernel source tree but
-not enabled in the |CL| kernels, in many cases the |CL| team will enable it
-upon request. Submit requests on GitHub here:
-https://github.com/clearlinux/distribution/issues
-
-The |CL| team does not typically add out-of-tree kernel modules as a matter of
-practice because of the maintenance overhead. If the driver was unable to be
-merged upstream, there is a good chance we may be unable to merge it for
-similar reasons.
-
-Kernel modules can be individually built and installed on |CL|. See the
-:ref:`kernel modules <kernel-modules>` page for more information.
-
-|
-
-
-.. _`Clear Linux community forums`: https://community.clearlinux.org
-.. _`Software Store`: https://clearlinux.org/software
-.. _`FFmpeg`: https://ffmpeg.org/

_sources/about.rst.txt

@@ -1,24 +0,0 @@
-.. _about:
-
-About
-#####
-
-Clear Linux is a little different from other distros. Here are some important
-tools and concepts for managing your install.
-
-Training
-********
-
-Additional training materials are available in the `how-to-clear`_ GitHub\*
-project to help you get started with |CL| tools.
-
-The training helps you create a customized OS that is based on |CL| and provides
-complete details on the methods and tools used to create updates and how to
-deploy updates to targets.
-
-To complete the training, you will need a clean |CL| installation and a network connection. The project includes all files needed to complete the exercises.
-
-* `how-to-clear`_ training on GitHub
-
-
-.. _how-to-clear: https://github.com/clearlinux/how-to-clear

_sources/concepts/swupd-about.rst.txt

@@ -1,97 +0,0 @@
-.. _swupd-about:
-
-swupd: software updater
-#######################
-
-: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
-==========
-
-Using package managers to keep track of software version compatibility or compare multiple systems on many Linux distributions can be cumbersome.
-
-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.
-
-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
-========
-
-|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.
-
-Learn how to update your system using :ref:`swupd <swupd-guide>`.
-
-Update efficiency
------------------
-
-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.
-
-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.
-
-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.
-
-Update integrity
-----------------
-
-This is the basis of the :command:`swupd diagnose` subcommand, which allows a |CL| system to check for any discrepancies to system files. As necessary,
-:command:`swupd repair` provides a useful way for software developers to remediate these discrepancies and return to a known filesystem state.
-
-Bundles
-=======
-
-|CL-ATTR| approaches software management differently than many other
-Linux-based operating systems.
-
-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
-

_sources/concepts/telemetry-about.rst.txt

@@ -1,82 +0,0 @@
-.. _telemetry-about:
-
-Telemetrics
-###########
-
-One of the key features of |CL-ATTR| is telemetry, which is used to
-monitor system health. Telemetry enables developers to observe and proactively
-address issues before end users are impacted.
-
-*Telemetrics* is a combination word made from:
-
-*	*Telemetry* which is sensing and reporting data.
-*	*Analytics* which is using visualization and statistical inferencing to make
-	sense of the reported data.
-
-|CL| telemetry reports system-level debug/crash information using specialized probes. The
-probes monitor system tasks such as :abbr:`swupd (software updater)`, kernel
-oops, machine error checks, and BIOS error report table for unhandled hardware
-failures. Telemetry enables real-time issue reporting to allow system
-developers to quickly focus on an issue and monitor corrective actions.
-
-|CL| telemetry is fully customizable and can be used during software development
-for debugging purposes. You can use **libtelemetry** in your code to create custom
-telemetry records. You can also use **telem-record-gen** in script files or call
-it from another program.
-
-.. note::
-
-   The |CL| telemetry client is disabled by default until you decide to enable it.  Telemetry is an **opt-in** solution and can be easily enabled or disabled.
-
-Architecture
-************
-
-|CL| telemetry has two fundamental components, which are shown in figure 1:
-
-*	Client:  generates and delivers records to the backend server via the network.
-*	Backend: captures records sent from the client and displays the cumulative
-	content through a specialized interface.
-
-	.. note::
-
-		If you want to capture your own records for analysis, you must set up
-		your own backend server.
-
-.. figure:: ../guides/telemetrics/figures/telemetry-e2e.png
-   :scale: 75%
-   :alt: Clear Linux Telemetry Architecture.
-
-   Figure 1: Clear Linux Telemetry Architecture.
-
-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.
-
-*	**probes**, that collect specific types of data from the operating system.
-*	**libtelemetry**, that telemetrics probes use to create telemetrics records and
-	send them to the telemprobd daemon for further processing.
-
-
-The telemetry backend provides the server-side component of a complete telemetrics solution and
-consists of:
-
-*	Nginx web server.
-*	Two Flask apps:
-
-	*	Collector, an ingestion web app for records received from telemetrics-client probes.
-	*	TelemetryUI, a web app that exposes several views to visualize the telemetry data
-		and also provides a REST API to perform queries.
-
-*	PostgreSQL as the underlying database server.
-
-The default telemetry backend server reports back to the |CL| development team
-and is not viewable outside the Intel firewall. If you want to collect your
-own records, then you must set up your own telemetry backend server.
-
-Next steps
-**********
-
-To put this concept into practice, refer to :ref:`telem-guide`.
-

_sources/get-started/get-started.rst.txt

@@ -1,49 +0,0 @@
-.. _get-started:
-
-Get started
-###########
-
-The Get Started section guides you through the requirements and installation of
-|CL-ATTR|. Follow these step-by-step intructions to get started with |CL|, fast.
-
-Pre-install
-***********
-
-There are a couple of things to take care of before you install.
-
-* :ref:`system-requirements`
-* :ref:`compatibility-check`
-* :ref:`bootable-usb`
-
-When installing |CL-ATTR| in a VM, consider which kernel to use. 
-
-* :ref:`Compatible VM kernels <vm-kernels>`
-
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-
-   compatibility-check
-   bootable-usb/bootable-usb
-
-Install
-*******
-
-.. toctree::
-   :maxdepth: 1
-
-   bare-metal-install-desktop/bare-metal-install-desktop
-   bare-metal-install-server/bare-metal-install-server
-   install-configfile
-
-.. _virtual-machine-install:
-
-Install in a virtual machine
-****************************
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   virtual-machine-install/*
-   ../../guides/maintenance/increase-virtual-disk-size.rst

_sources/get-started/install-configfile.rst.txt

@@ -1,192 +0,0 @@
-.. _install-configfile:
-
-Install using clr-installer and a configuration file
-####################################################
-
-This page explains how to install |CL-ATTR| using the clr-installer tool
-with a configuration file. The configuration file (:file:`clr-installer.yaml`)
-can be reused to duplicate the same installation configuration on additional
-machines.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Prerequisites
-*************
-
-Ensure that your target system supports the installation:
-
-* :ref:`system-requirements`
-* :ref:`compatibility-check`
-
-Process
-*******
-
-This guide describes two methods for using a configuration file with the
-clr-installer tool. You can use either method to achieve the same goal. Choose
-the method that works best for your setup.
-
-If you are installing |CL| for the first time, we recommend Example 1.
-
-To clone an existing |CL| setup on another system, we recommend Example 2.
-
-Example 1
-=========
-
-This method uses a configuration file template to perform a new installation.
-
-Perform the following steps:
-
-#. Go to `Downloads`_ and download the latest Clear Linux OS Server image.
-
-   For example:
-   https://download.clearlinux.org/releases/30010/clear/clear-30010-live-server.iso.xz
-
-#. Follow the instructions to :ref:`bootable-usb` based on your OS.
-
-#. Boot up the USB thumb drive.
-#. Select :guilabel:`Clear Linux OS` from the menu.
-#. In the console window, log in as root and set a password.
-#. Verify you have a network connection to the Internet and configure proxy
-   settings if you're working behind a firewall.
-#. Download a :file:`live-server.yaml` template.
-
-   For example:
-
-   .. code-block:: bash
-
-      curl -O https://download.clearlinux.org/releases/30010/clear/config/image/live-server.yaml
-
-#. Edit the template and change the settings as needed.
-
-   Commonly-changed settings include:
-
-.. _install-configfile-yaml-begin:
-
-   #. Under *block-devices*, set “file: "/dev/sda"” or enter your preferred device.
-   #. Under *targetMedia*, set the third partition size to “0” to use the entire disk space.
-   #. Under *bundles*, add additional bundles as needed.
-   #. Delete the *post-install* section unless you have post-installation scripts.
-   #. Under *Version*, set a version number. To use the latest version, set to “0”.
-
-   Commonly-changed settings are shown in lines 15, 34, 37, and 51 below.
-   See `Installer YAML Syntax`_ for more details.
-
-   .. code-block:: bash
-      :linenos:
-      :emphasize-lines: 14,15,34,37,51
-
-		#clear-linux-config
-
-		# c-basic-offset: 2; tab-width: 2; indent-tabs-mode: nil
-		# vi: set shiftwidth=2 tabstop=2 expandtab:
-		# :indentSize=2:tabSize=2:noTabs=true:
-
-		# File:         developer-live-server.yaml
-		# Use Case:     Live Image which boots into login prompt
-		#               Optionally allows for installing Clear Linux OS
-		#               using the TUI clr-installer by running clr-installer
-
-		# switch between aliases if you want to install to an actual block device
-		# i.e /dev/sda
-		block-devices: [
-		   {name: "bdevice", file: "/dev/sda"}
-		]
-
-		targetMedia:
-		- name: ${bdevice}
-		  type: disk
-		  children:
-		  - name: ${bdevice}1
-		    fstype: vfat
-		    mountpoint: /boot
-		    size: "150M"
-		    type: part
-		  - name: ${bdevice}2
-		    fstype: swap
-		    size: "32M"
-		    type: part
-		  - name: ${bdevice}3
-		    fstype: ext4
-		    mountpoint: /
-		    size: "0"
-		    type: part
-
-		bundles: [os-core, os-core-update, NetworkManager, clr-installer, vim]
-
-		autoUpdate: false
-		postArchive: false
-		postReboot: false
-		telemetry: false
-		iso: true
-		keepImage: true
-		autoUpdate: false
-
-		keyboard: us
-		language: en_US.UTF-8
-		kernel: kernel-native
-
-		version: 30010
-
-.. _install-configfile-yaml-end:
-
-Start the installation with the command:
-
-.. code-block:: bash
-
-   clr-installer --config live-server.yaml
-
-Example 2
-=========
-
-This method uses a saved configuration file from a previous installation,
-which you can use to easily duplicate the installation on additional machines.
-
-Perform the following steps:
-
-#. Open a console window on a system where |CL| was installed to retrieve a
-   copy of the configuration file.
-
-#. In the console window, log in as root and enter your password.
-
-#. Change directory to :file:`/root` and copy the :file:`clr-installer.yaml`
-   file to a USB thumb drive.
-
-   .. code-block:: bash
-
-   	  cd /root
-   	  cp clr-installer.yaml <USB-thumb-drive>
-
-Start the installation on the target with the following steps:
-
-#. Go to `Downloads`_ and download the latest Clear Linux OS Server image.
-
-   For example:
-   https://download.clearlinux.org/releases/30010/clear/clear-30010-live-server.iso.xz
-
-#. Follow the instructions to :ref:`bootable-usb` based on your OS.
-
-#. Boot up the USB thumb drive.
-#. Select :guilabel:`Clear Linux OS` from the menu.
-#. In the console window, log in as root and set a password.
-#. Verify you have a network connection to the Internet and configure proxy
-   settings if you're working behind a firewall.
-#. Plug in and mount the USB thumb drive containing the retrieved
-   :file:`clr-installer.yaml` configuration file.
-#. Start the installation with the command:
-
-   .. code-block:: bash
-
-      clr-installer --config clr-installer.yaml
-
-References
-**********
-
-* `Clear Linux Installer`_
-* `Installer YAML Syntax`_
-
-.. _Downloads: https://clearlinux.org/downloads
-.. _Clear Linux Installer: https://github.com/clearlinux/clr-installer
-
-.. _Installer YAML Syntax: https://github.com/clearlinux/clr-installer/blob/master/scripts/InstallerYAMLSyntax.md

_sources/get-started/virtual-machine-install/gce.rst.txt

@@ -1,266 +0,0 @@
-.. _gce:
-
-Launch |CL-ATTR| Compute Engine on Google Cloud Platform\*
-##########################################################
-
-This page explains the steps to create a virtual machine instance of
-|CL-ATTR| on `Google Cloud Platform`_ (:abbr:`GCP (Google Cloud Platform)`).
-
-.. contents::
-   :local:
-   :depth: 1
-
-Prerequisites
-*************
-
-* Set up a Google account and a GCP billing account.
-
-* Generate and install a user SSH key in the Linux PCs that will connect to
-  the VMs in GCP.
-
-Setup |CL| VM on GCP
-********************
-
-#. Sign in to your Google\* account on the
-   `Google Cloud Console <https://console.cloud.google.com/>`_:
-
-   .. figure:: figures/gce/00-sign-in.png
-      :scale: 50 %
-      :alt: Sign in to Google services
-
-      Figure 1: Google sign in screen
-
-#. Google Cloud Platform uses **Projects** to manage resources.
-   Select or create a new project for hosting the |CL| VM.
-
-   .. note::
-
-      Refer to the
-      `Quickstart Using a Linux VM <https://cloud.google.com/compute/docs/quickstart-linux>`_
-      guide to learn about the process of creating VM instances on GCP.
-
-#. Navigate to the latest |CL|
-   `release folder <https://download.clearlinux.org/releases/current/clear/>`_
-   to view the currently released :abbr:`GCE (Google Compute Engine\*)`
-   image, and download the :file:`clear-<release number>-gce.tar.gz`
-   image archive.
-
-   You don't need to uncompress the image archive, the intact file will
-   be uploaded to the Google Cloud Storage later.
-
-#. Create a *Storage Bucket* for hosting the |CL| image source archive
-   downloaded in the previous step:
-
-   * Click the :guilabel:`Navigation menu` icon on the upper left screen menu.
-
-   * Select the :menuselection:`Storage` item from the side bar on the left. You
-     will be sent to the Storage Browser tool or the Cloud Storage overview page.
-
-   .. figure:: figures/gce/01-cloud-storage.png
-      :scale: 50 %
-      :alt: Browse Google Cloud Storage
-
-      Figure 2: Browse Google Cloud Storage
-
-   .. note::
-      You may need to create a billing account and link to this project
-      before you create a bucket.
-
-   .. figure:: figures/gce/02-storage-browser.png
-      :scale: 50 %
-      :alt: Cloud Storage Browser tool
-
-      Figure 3: Cloud Storage Browser tool
-
-   * Click the :guilabel:`CREATE BUCKET` button to enter the bucket creation tool.
-     The bucket name must be unique because buckets in the Cloud Storage share
-     a single global namespace.
-
-     Leave the remaining options set to the defaults, and click the
-     :guilabel:`Create` button at the bottom to create a *Bucket*.
-
-     .. figure:: figures/gce/03-create-bucket.png
-        :scale: 50 %
-        :alt: Set a unique bucket name
-
-        Figure 4: Set bucket name
-
-#. Once the bucket is created, click the :guilabel:`Upload files` button
-   on the Bucket details page to upload the |CL| GCE image archive
-   to the named bucket:
-
-   .. figure:: figures/gce/04-bucket-created.png
-      :scale: 50 %
-      :alt: Cloud Storage bucket is available for storing objects
-
-      Figure 5: Cloud Storage bucket
-
-   .. figure:: figures/gce/10-image-upload.png
-      :scale: 50 %
-      :alt: Uploading the image source archive file
-
-      Figure 6: Uploading the image source archive file
-
-   .. figure:: figures/gce/11-bucket-uploaded.png
-      :scale: 50 %
-      :alt: Image archive imported complete
-
-      Figure 7: Importing complete
-
-#. Browse the Compute Engine Image library page:
-
-   * Click the :guilabel:`Navigation menu` icon on the upper left screen menu.
-
-   * Select the :menuselection:`Compute Engine --> Images` from the side bar on
-     the left.
-
-     .. figure:: figures/gce/20-gce-image.png
-        :scale: 50 %
-        :alt: Go to Google Compute Engine Image library
-
-        Figure 8: Image library
-
-#. On the Compute Engine Image library page, click the :guilabel:`[+] CREATE IMAGE`
-   menu item to create a custom image:
-
-   .. figure:: figures/gce/20-image-library.png
-      :scale: 50 %
-      :alt: Create a Google Compute Engine image
-
-      Figure 9: Create image
-
-#. In the VM image creation page, change the image source type to
-   *Cloud Storage file*.
-
-#. Under :guilabel:`Source`, select :guilabel:`Browse`.
-
-#. Locate the :file:`clear-<release number>-gce.tar.gz` file,
-   and click :guilabel:`Select`.
-
-   .. figure:: figures/gce/21-create-image.png
-      :scale: 50 %
-      :alt: Create the image using the imported image archive object
-
-      Figure 10: Create image using imported object
-
-   Accept all default options, and click the :guilabel:`Create` button
-   at the bottom to import the Clear Linux GCE image to the image library.
-
-   .. figure:: figures/gce/22-image-list.png
-      :scale: 50 %
-      :alt: Clear Linux Compute Engine image is created
-
-      Figure 11: Image is created
-
-#. After the |CL| image is imported, you can launch a VM instance running
-   |CL|:
-
-   * Click the :guilabel:`Navigation menu` icon on the upper left screen menu.
-
-   * Select :menuselection:`Compute Engine --> VM Instances` from the side bar on
-     the left.
-
-   .. figure:: figures/gce/30-vm-instances.png
-      :scale: 50 %
-      :alt: Go to VM instances catalog
-
-      Figure 12: VM instances catalog
-
-#. If no VM instance was created in this project, you will be prompted to
-   create one.
-
-#. Alternatively, click the :guilabel:`CREATE INSTANCE` button on the VM
-   instances page to create a VM instance.
-
-   .. figure:: figures/gce/30-vm-none.png
-      :scale: 50 %
-      :alt: Prompt for VM creation
-
-      Figure 13: VM creation
-
-   .. figure:: figures/gce/30-vm-catalog.png
-      :scale: 50 %
-      :alt: List of VM instances
-
-      Figure 14: VM instances list
-
-   * Under :guilabel:`Region`, choose a region based on the
-     `Best practices for Compute Engine regions selection`_.
-
-   * Under :guilabel:`Boot disk`, click the :guilabel:`Change` button.
-
-     .. figure:: figures/gce/30-create-vm.png
-        :scale: 50 %
-        :alt: Use custom image while creating Clear Linux VM instance
-
-        Figure 15: Use custom image
-
-   * Select the :menuselection:`Custom images` tab for using Clear Linux OS GCE image.
-
-     .. figure:: figures/gce/31-select-boot-disk.png
-        :scale: 50 %
-        :alt: Select Clear Linux boot disk to create a VM instance
-
-        Figure 16: Select Clear Linux boot disk to create a VM instance
-
-   * Scroll down to the bottom of the VM instance creation page,
-     expand the :guilabel:`Management, security, disks, networking, sole tenancy`
-     group.
-
-     .. figure:: figures/gce/40-clear-vm-security.png
-        :scale: 50 %
-        :alt: Clear Linux requires setting up SSH keys
-
-        Figure 17: Set up SSH keys
-
-     .. note::
-        |CL| does not allow SSH login with a root account by default.
-        As a result, you must configure the VM instance with your
-        SSH public key, so that you are able to access it remotely.
-
-        Refer to :ref:`security` for more details.
-
-   * Click the :menuselection:`Security` tab, copy and paste your SSH public key:
-
-     .. figure:: figures/gce/40-ssh-key.png
-        :scale: 50 %
-        :alt: Set SSH key for remote login
-
-        Figure 18: Set SSH key for remote login
-
-     .. warning::
-
-        The username is assigned from characters preceding ``@`` in the email
-        address, included in the SSH key. The dot symbol "." is not allowed,
-        because it is an invalid character while creating user accounts in
-        |CL|.
-
-   * Click the :guilabel:`Create` button to create the |CL| VM.
-
-#. The Clear Linux VM instance is created and assigned a public IP address:
-
-   .. figure:: figures/gce/41-vm-created.png
-      :scale: 50 %
-      :alt: Clear Linux VM instance is created and started
-
-      Figure 19: Clear Linux VM instance is created and started
-
-#. You can now SSH login to the VM using the IP address obtained in the
-   previous step, and the username associated with the SSH public key:
-
-   .. figure:: figures/gce/42-ssh-vm.png
-      :scale: 50 %
-      :alt: SSH login to the Clear Linux VM
-
-      Figure 20: SSH login to Clear Linux VM
-
-Related topics
-**************
-
-* :ref:`azure`
-* :ref:`aws-web`
-
-
-.. _Google Cloud Platform: https://cloud.google.com/
-
-.. _Best practices for Compute Engine regions selection: https://cloud.google.com/solutions/best-practices-compute-engine-region-selection

_sources/get-started/virtual-machine-install/hyper-v.rst.txt

@@ -1,68 +0,0 @@
-.. _hyper-v:
-
-Use Hyper-V\*
-#############
-
-This page explains how to run |CL-ATTR| inside a
-`Windows Server Virtualization`_\* or **Hyper-V** environment.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Prerequisites
-*************
-
-* Enable `Intel® Virtualization Technology`_ (Intel® VT)
-
-* Enable `Intel® Virtualization Technology for Directed I/O`_ (Intel® VT-d) in
-  your BIOS/UEFI firmware configuration.
-
-Enable Hyper-V
-**************
-
-Please refer to `Install Hyper-V on Windows 10`_ to enable and configure
-*Hyper-V* on your machine.
-
-Create a virtual network
-************************
-
-Once *Hyper-V* has been enabled on your Windows system you will need to
-create a virtual network in the **Hyper-V Manager**.  Refer to the
-`Create a virtual network`_ documentation to create and configure
-a virtual network.
-
-Create a virtual machine
-************************
-
-#. Download and decompress the latest hyperv disk image
-   :file:`clear-XXXXX-hyperv.img.gz`, where XXXXX is the latest
-   available version of |CL| from our `Downloads`_ page.
-
-#. Create a virtual machine using the **Hyper-V Manager**:
-
-   a. Choose **Generation 2** when prompted to *specify VM generation*.
-   b. Choose **Use an existing virtual hard disk** and browse to find the
-      :file:`clear-XXXX-hyperv.vhdx` file.
-   c. When finished, open VM settings, select Firmware Section and in Secure
-      Boot config, **uncheck** Enable Secure Boot.
-
-   .. note:: Currently, |CL| does not boot with `secure boot`
-      enabled.
-
-#. Connect to your new VM and start it. You should see a prompt:
-
-   .. code-block:: console
-
-      > User: root
-
-#. Set a root user password.
-
-Your virtual machine running |CL| is ready!
-
-.. _Windows Server Virtualization: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/about/
-.. _Install Hyper-V on Windows 10: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v
-.. _Create a virtual network: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/connect-to-network
-.. _Downloads: https://cdn.download.clearlinux.org/image/
-.. _Intel® Virtualization Technology: http://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html
-.. _Intel® Virtualization Technology for Directed I/O: https://software.intel.com/en-us/articles/intel-virtualization-technology-for-directed-io-vt-d-enhancing-intel-platforms-for-efficient-virtualization-of-io-devices

_sources/get-started/virtual-machine-install/kvm.rst.txt

@@ -1,253 +0,0 @@
-.. _kvm:
-
-Run |CL-ATTR| as a KVM guest OS
-###############################
-
-This page explains how to run |CL-ATTR| in a virtualized environment using
-:abbr:`KVM (Kernel-based Virtual Machine)`.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Install QEMU-KVM
-****************
-
-#. Enable the `Intel® Virtualization Technology`_ (Intel® VT) and the
-   `Intel® Virtualization Technology for Directed I/O`_ (Intel® VT-d) in the
-   host machine’s BIOS.
-
-#. Log in and open a terminal emulator.
-
-#. Install `QEMU*-KVM` on the host machine. Below are some example distros.
-
-   * On |CL|:
-
-     .. code-block:: bash
-
-        sudo swupd bundle-add kvm-host
-
-   * On Ubuntu\* 18.04 LTS Desktop:
-
-     .. code-block:: bash
-
-        sudo apt-get install qemu-kvm
-
-   * On Mint\* 19.1 “Cinnamon” Desktop:
-
-     .. code-block:: bash
-
-        sudo apt-get install qemu-kvm
-
-   * On Fedora\* 30 Workstation:
-
-     .. code-block:: bash
-
-        sudo dnf install qemu-kvm
-
-Download and launch the virtual machine
-***************************************
-
-#. Download the latest pre-built |CL| KVM image file from
-   the `image <https://cdn.download.clearlinux.org/image/>`_ directory. Look for
-   ``clear-<version>-kvm.img.xz``.  You can also use this command:
-
-   .. code-block:: bash
-
-      curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep '[0-9]'-kvm'\.')
-
-#. Uncompress the downloaded image:
-
-   .. code-block:: bash
-
-      unxz -v clear-<version>-kvm.img.xz
-
-#. Download the 3 OVMF files (`OVMF.fd`, `OVMF_CODE.fd`, `OVMF_VARS.fd`) that
-   provides UEFI  support for virtual machines.
-
-   .. code-block:: bash
-
-      curl -O https://cdn.download.clearlinux.org/image/OVMF.fd
-      curl -O https://cdn.download.clearlinux.org/image/OVMF_CODE.fd
-      curl -O https://cdn.download.clearlinux.org/image/OVMF_VARS.fd
-
-   .. note::
-
-      The default OVMF files from |CL| may not work for some distro version(s).
-      You may get an `ASSERT` in the `debug.log` file when starting the VM.
-      If that is the case, use the distro-specific-OVMF files instead.
-      For example, the |CL| OVMF files work for Ubuntu 18.04 LTS, but not for Ubuntu 19.04 LTS.
-      Installing and using the OVMF files for Ubuntu 19.04 LTS resolved the `ASSERT` issue.
-
-#. Download the `start_qemu.sh`_ script from the
-   `image <https://cdn.download.clearlinux.org/image/>`_ directory.  This script
-   will launch the |CL| VM and provide console interaction within the same
-   terminal emulator window.
-
-   .. code-block:: bash
-
-      curl -O https://cdn.download.clearlinux.org/image/start_qemu.sh
-
-#. Make the script executable:
-
-   .. code-block:: bash
-
-      chmod +x start_qemu.sh
-
-#. Start the |CL| KVM virtual machine:
-
-   .. code-block:: bash
-
-      sudo ./start_qemu.sh clear-<version>-kvm.img
-
-#. Log in as ``root`` user and set a new password.
-
-SSH access into the virtual machine
-***********************************
-
-To interact with the |CL| VM through SSH instead of the console it was
-launched from, follow these steps.
-
-#. Configure SSH in the |CL| VM to allow root login:
-
-   .. code-block:: bash
-
-      cat > /etc/ssh/sshd_config << EOF
-        PermitRootLogin yes
-        EOF
-
-#. Enable and start SSH server in the |CL| VM:
-
-   .. code-block:: bash
-
-      systemctl enable sshd
-      systemctl start sshd
-
-#. Determine the IP address of the host on which you will launch the VM.
-   Substitute <ip-addr-of-kvm-host> in the next step with this information.
-
-   .. code-block:: bash
-
-      ip a
-
-#. SSH into the |CL| VM using the default port of  `10022`:
-
-   .. code-block:: bash
-
-      ssh -p 10022 root@<ip-addr-of-kvm-host>
-
-Optional: Add the GNOME Display Manager (GDM)
-*********************************************
-
-To add :abbr:`GDM (GNOME Display Manager)` to the |CL| VM, follow these steps:
-
-#. Shutdown the active |CL| VM.
-
-   .. code-block:: bash
-
-      poweroff
-
-#. Install the Spice viewer on the local host or remote system. Below are some
-   example distros.
-
-   * On Clear Linux:
-
-     .. code-block:: bash
-
-        sudo swupd bundle-add virt-viewer
-
-   * On Ubuntu\* 18.04 LTS Desktop:
-
-     .. code-block:: bash
-
-        sudo apt-get install virt-viewer
-
-   * On Mint\* 19.1 “Cinnamon” Desktop:
-
-     .. code-block:: bash
-
-        sudo apt-get install virt-viewer
-
-   * On Fedora\* 30 Workstation:
-
-     .. code-block:: bash
-
-        sudo dnf install virt-viewer
-
-#. Modify the :file:`start_qemu.sh` script to increase memory (`-m`), add
-   graphics driver (`-vga`), and add Spice (`-spice`, `-usb`, and
-   `-device`) support.
-
-   .. code-block:: console
-
-      qemu-system-x86_64 \
-          -enable-kvm \
-          ${UEFI_BIOS} \
-          -smp sockets=1,cpus=4,cores=2 -cpu host \
-          -m 4096 \
-          -vga qxl \
-          -nographic \
-          -spice port=5924,disable-ticketing \
-          -usb \
-          -device usb-tablet,bus=usb-bus.0 \
-          -drive file="$IMAGE",if=virtio,aio=threads,format=raw \
-          -netdev user,id=mynet0,hostfwd=tcp::${VMN}0022-:22,hostfwd=tcp::${VMN}2375-:2375 \
-          -device virtio-net-pci,netdev=mynet0 \
-          -debugcon file:debug.log -global isa-debugcon.iobase=0x402 $@
-
-#. Due to changes in the :file:`start_qemu.sh` script from the previous step,
-   using the same OVMF files will result in the VM not booting properly and
-   you end up in the the UEFI shell.  The easiest way to avoid this is to delete
-   the OVMF files and restore the originals before relaunching the VM.
-
-#. Increase the size of the VM by 10GB to accommodate the GDM installation:
-
-   .. code-block:: bash
-
-      qemu-img resize -f raw clear-<version>-kvm.img +10G
-
-#. Relaunch the |CL| VM:
-
-   .. code-block:: bash
-
-      sudo ./start_qemu.sh clear-<version>-kvm.img
-
-#. Determine the IP address of the host on which you will launch the VM.
-   Substitute <ip-addr-of-kvm-host> in the next step with this information.
-
-   .. code-block:: bash
-
-      ip a
-
-#. From the local host or remote system, open a new terminal emulator window
-   and connect into the |CL| VM using the Spice viewer:
-
-   .. code-block:: bash
-
-      remote-viewer spice://<ip-address-of-kvm-host>:5924
-
-#. Log in as `root` user into the |CL| VM.
-
-#. Follow these steps from :ref:`increase-virtual-disk-size` to resize the partition of the virtual disk of the VM.
-
-#. Add GDM to the |CL| VM:
-
-   .. code-block:: bash
-
-      swupd bundle-add desktop-autostart
-
-#. Reboot the |CL| VM to start GDM:
-
-   .. code-block:: bash
-
-      reboot
-
-#. Go through the GDM out-of-box experience (OOBE).
-
-#. The default aspect ratio of the GDM GUI for the |CL| VM is 4:3. To change
-   it, use GDM's `Devices > Displays` setting tool (located at the top-right corner).
-
-
-.. _Intel® Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html
-.. _Intel® Virtualization Technology for Directed I/O: https://software.intel.com/en-us/articles/intel-virtualization-technology-for-directed-io-vt-d-enhancing-intel-platforms-for-efficient-virtualization-of-io-devices
-.. _start_qemu.sh: https://cdn.download.clearlinux.org/image/start_qemu.sh

_sources/get-started/virtual-machine-install/virtualbox-cl-installer.rst.txt

@@ -1,404 +0,0 @@
-.. _virtualbox-cl-installer:
-
-Install a |CL-ATTR| VM in VirtualBox\*
-######################################
-
-This page explains how to create a virtual machine on the `VirtualBox`_
-hypervisor with |CL-ATTR| as the guest operating system. These instructions
-support the |CL| live-server installer to create the |CL| virtual machine (VM).
-
-.. contents::
-   :local:
-   :depth: 1
-
-Prerequisites
-*************
-
-#. Enable virtualization, such as `Intel® Virtualization Technology`_
-   (Intel® VT), on the host system from EFI/BIOS.
-
-#. Download and install |VB| **version 6.0 or greater** from
-   `VirtualBox`_ using the  `VirtualBox Installation Instructions`_ for your
-   platform.
-
-Download and extract the |CL| installer ISO
-*******************************************
-
-#. Download the :file:`clear-<VERSION>-live-server.iso.xz` of
-   |CL| on the `Downloads`_ page.
-
-#. Validate the integrity of the downloaded image by checking the file hash
-   and signatures. Refer to :ref:`validate-signatures` for detailed steps.
-
-#. Decompress the downloaded image.
-
-   - On Windows you can use `7zip`_ to extract the file by right-clicking the
-     file to *Extract Here* (in the same directory)
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-01.png
-      :scale: 100%
-      :alt: 7zip extract here command
-
-      Figure 1: 7zip extract here command
-
-   - On Linux :
-
-     .. code-block:: bash
-
-        xz -d clear-<VERSION>-live-server.iso.xz
-
-#. Delete the originally downloaded compressed file.
-
-Create a new |VB| virtual machine
-*********************************
-
-A new :abbr:`VM (Virtual Machine)` needs to be created in |VBM| where |CL|
-will be installed. General instructions for creating a virtual machine and
-details about using different settings are available in the VirtualBox manual section `Creating Your First Virtual Machine`_.
-
-#. Launch the |VBM| from your host system.
-
-#. Click the :guilabel:`New` button to create a new VM.
-
-#. Choose :guilabel:`Expert mode`.
-
-#. On the :guilabel:`Create Virtual Machine` screen, enter the following settings:
-
-   - **Name**: Choose name (e.g. ClearLinuxOS-VM).
-   - **Type**: Linux
-   - **Version**: **Linux 2.6 / 3.x / 4.x (64-bit)**
-   - **Hard disk**: `Create a virtual hard disk now`
-   - **Memory size default**: 2048 MB (Adjust appropriately.)
-
-     .. note::
-        Later, if you want to change the amount of RAM allocated, power down your VM. Return to :file:`Settings > System` and change
-        :guilabel:`Base Memory` to the desired size.
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-02.png
-      :scale: 100%
-      :alt: Create Virtual Machine
-
-      Figure 2: Create Virtual Machine
-
-#. Click :guilabel:`Create`.
-
-#. On the :guilabel:`Create Virtual Hard Disk` screen, select:
-
-   - **File location**
-   - **File size**: **32.00 GB**. Adjust size to your needs.
-   - **Hard disk file type**: `VDI (VirtualBox Disk Image)`
-   - **Storage on physical hard disk**:`Dynamically allocated`
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-03.png
-      :scale: 100%
-      :alt: Create Virtual Hard Disk
-
-      Figure 3: Create Virtual Hard Disk
-
-#. Click :guilabel:`Create`.
-
-   A new virtual machine will be created and appear in the |VBM|.
-
-#. Click :guilabel:`Settings` to configure the |CL| VM.
-
-#. In the left-hand menu, navigate to the :menuselection:`System` menu.
-
-#. On the :guilabel:`Motherboard` tab, select the :guilabel:`Chipset` menu, and
-   then select :menuselection:`ICH9`. See Figure 4.
-
-   .. note::
-
-      You can select which chipset will be presented to the virtual machine.
-      Consult the `VM VirtualBox User Manual`_ for more details.
-
-#. In :guilabel:`Enabled Features`, check these boxes:
-
-   - **Enable I/O APIC**
-   - **Enable EFI (special OSes only)**
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-04.png
-      :scale: 100%
-      :alt: Settings > System
-
-      Figure 4: Settings > System
-
-   .. note::
-
-      By default, only 1 virtual CPU is allocated to the new VM. Consider
-      increasing the number of virtual processors allocated to the virtual
-      machine under Settings > System > Processor for increased
-      performance.
-
-#. Click :guilabel:`OK`.
-
-Install |CL| on the |VB| VM
-***************************
-
-|CL| is ready to be installed.
-
-Mount the installation ISO
-==========================
-
-The |CL| installer ISO needs to be mounted as a virtual CD-ROM on the VM
-before powering the VM on.
-
-#. From the *ClearLinux-OS* :guilabel:`Settings` menu at left, select
-   :guilabel:`Storage`.
-
-#. From :guilabel:`Storage Devices`, middle column, click the blue
-   disk labeled :guilabel:`Empty`.
-
-#. From the :guilabel:`Attributes` menu, click the blue CD disk next to
-   the :guilabel:`Optical Drive` drop down menu and click
-   :guilabel:`Choose Virtual Optical Disk File...`
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-05.png
-      :scale: 100%
-      :alt: Choose Virtual Optical Disk Drive
-
-      Figure 5: Choose Virtual Optical Disk Drive
-
-#. Where there appears :guilabel:`Please choose a virtual optical disk file`,
-   select the ISO file and click *Open*.
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-06.png
-      :scale: 100%
-      :alt: Mounting an ISO
-
-      Figure 6: Mounting an ISO
-
-#. Click :guilabel:`OK` to exit and return to the main |VBM|.
-
-Install |CL| with live-server installer
-=======================================
-
-#. In the |VBM|, select virtual machine you created and click :guilabel:`Start`.
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-07.png
-      :scale: 100%
-      :alt: Start the installer
-
-      Figure 7: Start the installer
-
-   .. note::
-
-      To release the mouse cursor from the VM console window, press the right
-      :kbd:`Ctrl` key on the keyboard.
-
-#. When :guilabel:`Clear Linux Installer` in boot manager appears,
-   select :kbd:`Enter`. Do not install the bundle `desktop-autostart`.
-
-#. Follow the steps in :ref:`bare-metal-install-server` to
-   install |CL| onto the VM virtual disk. Note:
-
-   #. In :guilabel:`Configure Installation Media`, navigate top
-      VBOX HARDDISK, and then select :guilabel:`Confirm`.
-
-   #. In :menuselection:`Advanced options --> Manage User`, create an
-      administrative user.
-
-   #. Do not install the bundle `desktop-autostart`.
-
-#. When |CL| installation is complete, click :guilabel:`Exit`.
-
-#. At the prompt, enter:
-
-   .. code-block:: bash
-
-      shutdown now
-
-Unmount the ISO
-===============
-
-The |CL| installer ISO needs to be unmounted to allow the VM to boot from the
-virtual hard disk.
-
-#. Return to the |VBM|.
-
-#. Click :guilabel:`Settings` to configure the |CL| VM.
-
-#. From the VM :guilabel:`Settings` window, navigate to the :guilabel:`Storage`
-   pane in the left menu.
-
-#. From the middle :guilabel:`Storage Devices` column, click the blue CD disk
-   labeled :guilabel:`clear-<VERSION>-live-server.iso` under the
-   :guilabel:`Controller: IDE`.
-
-#. From the :guilabel:`Attributes` column at right, in :guilabel:`Optical Drive`,
-   select the blue CD icon beside and click
-   :guilabel:`Remove Disk from Virtual Drive`.
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-08.png
-      :scale: 100%
-      :alt: Remove Disk from Virtual Drive
-
-      Figure 8: Remove Disk from Virtual Drive
-
-#. Click :guilabel:`OK` to exit the :guilabel:`VM Settings` menu and return to
-   the main |VBM|.
-
-Install |VB| Linux Guest Additions
-==================================
-
-|CL| provides Linux Guest Additions drivers for full compatibility using an
-install script in the **kernel-lts** (Long Term Support) bundle by |CL|.
-
-#. From the |VBM| select the |CL| VM, and select :guilabel:`Start`.
-
-#. In the VM Console, log in as the administrative user previously created.
-
-   .. note::
-      A message may appear: "A kernel update is available: you may wish
-      to reboot the system."
-
-      To update the kernel, enter:
-
-      .. code-block:: bash
-
-          sudo reboot
-
-      At initial login, enter the administrative user's password and continue.
-
-#. Validate the installed kernel is **kernel-lts** by checking the output
-   of the :command:`uname -r` command. It should end in **.lts** or **.lts2018**.
-
-   .. code-block:: bash
-
-      uname -r
-      <VERSION>.lts
-
-   If the running kernel is not **lts**: install the LTS kernel manually,
-   update the bootloader, and check again:
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add kernel-lts
-      clr-boot-manager set-kernel $(basename $(realpath /usr/lib/kernel/default-lts))
-      clr-boot-manager update
-      reboot
-
-#. Remove any kernel bundles that do not end in *-lts* or *kernel-install*
-   to simplify and avoid conflicts:
-
-   .. code-block:: bash
-
-      sudo swupd bundle-list | grep kernel
-      sudo swupd bundle-remove <NON-LTS-KERNEL>
-
-#. In the VM Console top menu, click :guilabel:`Devices`, and select
-   :guilabel:`Insert Guest Additions CD image...` to mount the |VB| driver
-   installation to the |CL| VM.
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-09.png
-      :scale: 100%
-      :alt: Insert Guest Additions CD image
-
-      Figure 9: Insert Guest Additions CD image
-
-#. If a dialogue appears, "VBx_GAs_6.0.8... Would you like to run it?",
-   select :guilabel:`Cancel`.
-
-   Instead, we provide a script to patch and install |VB| drivers on |CL|.
-
-#. Open a Terminal and enter the script:
-
-   .. code-block:: bash
-
-      sudo install-vbox-lga
-
-   .. note::
-
-      Successful installation shows: "Guest Additions installation complete".
-      If drivers are already installed, don't re-install them.
-
-#. Shut down the system. Select :menuselection:`Machine --> ACPI Shutdown`.
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-10.png
-      :scale: 100%
-      :alt: Powering off a VirtualBox VM
-
-      Figure 10: Powering off a VirtualBox VM
-
-#. Select :guilabel:`Settings`, :guilabel:`Display`.
-
-#. In :guilabel:`Graphics Controller`, select :guilabel:`VBoxSVGA`
-   to adjust screen size dynamically.
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-11.png
-      :scale: 100%
-      :alt: Remove Disk from Virtual Drive
-
-      Figure 11: VirtualBox hardware acceleration error
-
-#. In the |VBM|, select :guilabel:`Start`.
-
-#. In the VM console, login and verify the |VB| drivers are loaded:
-
-   .. code-block:: bash
-
-      lsmod | grep ^vbox
-
-   You should see drivers loaded with names beginning with **vbox**:
-   (e.g., vboxvideo, vboxguest).
-
-#. Add `desktop-autostart` for a full desktop experience.
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add desktop-autostart
-
-#. Reboot the VM and log in with the administrative user.
-
-   .. code-block:: bash
-
-      sudo reboot
-
-The |CL| VM running on |VB| is ready to develop and explore.
-
-Troubleshooting
-***************
-
-#. **Problem:** On a Microsoft\* Windows\* OS, |VB| encounters an error when
-   trying to start a VM indicating *VT-X/AMD-v hardware acceleration is not
-   available on your system.*
-
-   .. figure:: figures/vbox/virtualbox-cl-installer-12.png
-      :scale: 100%
-      :alt: Remove Disk from Virtual Drive
-
-      Figure 12: VirtualBox hardware acceleration error
-
-   **Solution:** First, double check the `Prerequisites`_ section to make
-   sure *Hardware accelerated virtualization* extensions have been enabled
-   in the host system's EFI/BIOS.
-
-   *Hardware accelerated virtualization*, may get disabled for |VB| when
-   another hypervisor, such as *Hyper-V* is enabled.
-
-   To disable *Hyper-V* execute this command in an
-   **Administrator: Command Prompt or Powershell**, and reboot the system:
-
-   .. code-block:: bash
-
-      bcdedit /set {current} hypervisorlaunchtype off
-
-   To enable Hyper-V again, execute this command in an
-   **Administrator: Command Prompt or Powershell**, and reboot the system:
-
-   .. code-block:: bash
-
-      bcdedit /set {current} hypervisorlaunchtype Auto
-
-.. _VirtualBox Installation Instructions: https://www.virtualbox.org/manual/ch02.html
-
-.. _VirtualBox: https://www.virtualbox.org
-
-.. _Downloads: https://clearlinux.org/downloads
-
-.. _`Creating Your First Virtual Machine`: https://www.virtualbox.org/manual/UserManual.html#gui-createvm
-
-.. _7zip: http://www.7-zip.org/
-
-.. _Intel® Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html
-
-.. _VM VirtualBox User Manual: https://docs.oracle.com/cd/E97728_01/E97727/html/settings-system.html

_sources/get-started/virtual-machine-install/vmw-player.rst.txt

@@ -1,296 +0,0 @@
-.. _vmw-player:
-
-Install |CL-ATTR| as a VMware\* Workstation Player guest OS
-###########################################################
-
-This page explains how to create a new VM and install |CL| on it with the
-VMware Workstation Player hypervisor.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-`VMware Workstation Player`_ is a type 2 hypervisor. It runs on top of
-Windows\* or Linux\* operating systems. With VMware ESXi, you can
-create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)`
-on your local system.
-
-VMware offers a type 1 hypervisor called `VMware ESXi`_ designed for the
-cloud environment. For information on how to install |CL| as guest OS on
-it, see :ref:`vmware-esxi-install-cl`.
-
-.. note::
-
-   The screenshots on this document show the Windows version of the
-   VMware Workstation 15 Player. The menus and prompts are similar to those
-   in other versions and for the Linux OS save some minor wording differences.
-
-If you prefer to use a pre-configured |CL| VMware image instead,
-see our :ref:`vmw-player-preconf` guide.
-
-Install the VMware Workstation Player hypervisor
-************************************************
-
-#. Enable :abbr:`Intel® VT (Intel® Virtualization Technology)` and
-   :abbr:`Intel® VT-d (Intel® Virtualization Technology for Directed I/O)` in
-   your system's BIOS.
-
-#. `VMware Workstation Player`_ is available for Windows and Linux.
-   Download your preferred version.
-
-   .. note::
-
-      By default, selecting download means you receive the latest version
-      of this application. Commands may differ based on the version.
-
-#. Install VMware Workstation Player following the instructions
-   appropriate for your system's OS:
-
-   * On supported Linux distros:
-
-     #. Enable a GUI desktop.
-     #. Start a terminal emulator.
-     #. Start the installer by issuing the command below and follow the
-        guided steps.
-
-        .. code-block:: console
-
-           sudo sh ./VMware-Player-[version number].x86_64.bundle
-
-   * On Windows:
-
-     #. Start the installer.
-     #. Follow the setup wizard.
-
-For additional help, see the `VMware Workstation Player Documentation`_.
-
-Download the latest |CL| installer
-**********************************
-
-Get the latest installer with |CL| OS Desktop  from the `downloads`_ page.
-
-Visit :ref:`image-types` for additional information about all available |CL| images.
-
-We also provide instructions for downloading and verifying a Clear Linux ISO.
-For more information, refer to :ref:`download-verify-decompress`.
-
-Create and configure a new VM
-*****************************
-
-#. Start the `VMware Workstation Player` app.
-
-#. On the home screen, click :guilabel:`Create a New Virtual Machine`. See
-   Figure 1.
-
-   .. figure:: figures/vmw-player/vmw-player-01.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Create a new virtual machine
-
-      Figure 1: VMware Workstation Player - Create a new virtual
-      machine
-
-#. On the :guilabel:`Welcome to the New Virtual Machine Wizard` screen,
-   select the :guilabel:`Installer disc image file (iso)` option.
-   See Figure 2.
-
-   .. figure:: figures/vmw-player/vmw-player-02.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Select |CL| installer ISO
-
-      Figure 2: VMware Workstation Player - Select |CL| installer ISO
-
-#. Click the :guilabel:`Browse` button and select the decompressed |CL|
-   installer ISO.
-
-#. Click the :guilabel:`Next` button.
-
-#. On the :guilabel:`Select a Guest Operating System`, set the
-   :guilabel:`Guest operating system` setting to :guilabel:`Linux`. See
-   Figure 3.
-
-   .. figure:: figures/vmw-player/vmw-player-03.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Select guest operating system type
-
-      Figure 3: VMware Workstation Player - Select guest operating system
-      type
-
-#. Set the :guilabel:`Version` setting to
-   :guilabel:`Other Linux 4.x or later kernel 64-bit`.
-
-#. Click the :guilabel:`Next` button.
-
-#. On the :guilabel:`Name the Virtual Machine` screen, name the new VM. See
-   Figure 4.
-
-   .. figure:: figures/vmw-player/vmw-player-04.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Name virtual machine
-
-      Figure 4: VMware Workstation Player - Name virtual machine
-
-#. Click the :guilabel:`Next` button.
-
-#. On the :guilabel:`Specify Disk Capacity` screen, set the VM's maximum disk
-   size. See Figure 5.
-
-   .. figure:: figures/vmw-player/vmw-player-05.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Set disk capacity
-
-      Figure 5: VMware Workstation Player - Set disk capacity
-
-   .. note::
-
-      For optimal performance with the |CL| Desktop image, we recommend 32GB
-      of drive space. See :ref:`system-requirements` for more details.
-
-#. Click the :guilabel:`Next` button.
-
-#. On the :guilabel:`Ready to Create Virtual Machine` screen, click the
-   :guilabel:`Customize Hardware...` button. See Figure 6.
-
-   .. figure:: figures/vmw-player/vmw-player-06.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Customize hardware
-
-      Figure 6: VMware Workstation Player - Customize hardware
-
-#. Select :guilabel:`Memory` and set the size to 2GB. See Figure 7.
-
-   .. figure:: figures/vmw-player/vmw-player-07.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Set memory size
-
-      Figure 7: VMware Workstation Player - Set memory size
-
-   .. note::
-      The |CL| installer ISO needs a minimum of 2GB of RAM.
-      After completing installation, |CL| can run on as little as
-      128MB of RAM. Thus, you can reduce the memory size if needed.
-      See :ref:`system-requirements` for more details.
-
-#. Under the :guilabel:`Device` list, select :guilabel:`Processors`. See
-   Figure 8.
-
-   .. figure:: figures/vmw-player/vmw-player-08.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Set virtualization engine option
-
-      Figure 8: VMware Workstation Player - Set virtualization engine
-      option
-
-#. Under the :guilabel:`Virtualization engine` section,
-   check :guilabel:`Virtualize Intel VT-x/EPT or AMD-V/RVI`.
-
-#. Click the :guilabel:`Close` button.
-
-#. Click the :guilabel:`Finish` button.
-
-Install |CL| into the new VM
-****************************
-
-#. Select the newly-created VM and click the :guilabel:`Play virtual machine`
-   button. See Figure 9.
-
-   .. figure:: figures/vmw-player/vmw-player-09.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Power on virtual machine
-
-      Figure 9: VMware Workstation Player - Power on virtual machine
-
-#. Follow the :ref:`install-on-target-start` guide to complete the
-   installation of |CL|.
-
-#. After the installation completes, reboot the VM. This reboot restarts the
-   |CL| installer.
-
-Detach the |CL| installer ISO from the VM
-*****************************************
-
-#. To enable the mouse pointer so you access VMware Workstation Player's
-   menus, press :kbd:`<CTRL>` + :kbd:`<ALT>` on the keyboard.
-
-#. To disconnect the CD/DVD to stop it from booting the |CL| installer ISO
-   again, click the :guilabel:`Player` menu. See Figure 10.
-
-   .. figure:: figures/vmw-player/vmw-player-10.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Edit CD/DVD settings
-
-      Figure 10: VMware Workstation Player - Edit CD/DVD settings
-
-#. Go to :menuselection:`Removable Devices-->CD/DVD (IDE)-->Disconnect`.
-
-#. Click the :guilabel:`OK` button.
-
-Enable UEFI boot support
-************************
-
-|CL| needs UEFI support to boot. To enable UEFI:
-
-#. Power off the VM. click the :guilabel:`Player` menu. See Figure 11.
-
-   .. figure:: figures/vmw-player/vmw-player-11.png
-      :scale: 100%
-      :alt: VMware Workstation Player - Power off virtual machine
-
-      Figure 11: VMware Workstation Player - Power off virtual machine
-
-#. Go to :guilabel:`Power` and select :guilabel:`Shut Down Guest`.
-
-#. Add the following line to the end of your VM's :file:`.vmx` file:
-
-   .. code-block:: console
-
-      firmware = "efi"
-
-   .. note::
-
-      Depending on the OS, you can typically find the VMware VM files under:
-
-      * On Linux distros: :file:`/home/username/vmware`
-      * On Windows: :file:`C:\\Users\\username\\Documents\\Virtual Machines`
-
-
-#. After configuring the settings above, power on your |CL| virtual machine.
-   On the :guilabel:`VMware Workstation Player` home screen, select your
-   VM. See Figure 9.
-
-#. Click :guilabel:`Play virtual machine`.
-
-#. Install Open VM Tools. You may want to install the `open-vm-tools` in
-   your virtual machine. The Open Virtual Machine Tools (open-vm-tools) are
-   the open source implementation of VMware Tools for Linux guest operating
-   systems. In |CL| you can use the following to install the bundle in your VM
-
-   .. code-block:: console
-
-      sudo swupd bundle-add os-cloudguest-vmware
-      sudo systemctl enable --now open-vm-tools
-
-More information is available on the `VMWare Tools Product Documentation`_ site.
-
-Related topics
-**************
-
-For other guides on using the VMWare Player and ESXi, see:
-
-* :ref:`vmw-player-preconf`
-* :ref:`vmware-esxi-install-cl`
-* :ref:`vmware-esxi-preconfigured-cl-image`
-
-.. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html
-
-.. _VMware Workstation Player:
-   https://www.vmware.com/products/workstation-player.html
-
-.. _VMware Workstation Player Documentation:
-   https://docs.vmware.com/en/VMware-Workstation-Player/index.html
-
-.. _downloads: https://clearlinux.org/downloads
-
-.. _VMWare Tools Product Documentation: https://docs.vmware.com/en/VMware-Tools/10.1.0/com.vmware.vsphere.vmwaretools.doc/GUID-8B6EA5B7-453B-48AA-92E5-DB7F061341D1.html

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

@@ -1,288 +0,0 @@
-.. _vmware-esxi-preconfigured-cl-image:
-
-Run preconfigured |CL-ATTR| image as a VMware\* ESXi guest OS
-#############################################################
-
-This page explains how to deploy a preconfigured |CL| VMware
-:abbr:`VM (Virtual Machine)` image on a VMware ESXi 6.5 host.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-`VMware ESXi`_ is a type 1 bare-metal hypervisor which runs directly on top
-of server hardware.  With VMware ESXi, you can create, configure, manage,
-and run |CL-ATTR| virtual machines at scale.
-
-We provide a preconfigured |CL| VMware image that can be run on a VMware ESXi
-6.5 host.
-
-If manuall installation is preferred, refer to :ref:`vmware-esxi-install-cl`.
-
-.. note::
-
-   VMware also offers a type 2 hypervisor designed for the desktop environment,
-   called `VMware Workstation Player`_. Refer to :ref:`vmw-player-preconf` or
-   :ref:`vmw-player` for more information.
-
-Download the latest |CL| VMware image
-*************************************
-
-Get the latest |CL| VMware prebuilt image from the `image`_ repository.
-Look for :file:`clear-[version number]-vmware.vmdk.xz`. You can also use
-this command:
-
-.. code-block:: bash
-
-   curl -O https://cdn.download.clearlinux.org/image/$(curl https://cdn.download.clearlinux.org/image/latest-images | grep vmware)
-
-Visit :ref:`image-types` for additional information about all available |CL| images.
-
-We also provide instructions for downloading and verifying a Clear Linux ISO.
-For more information, refer to :ref:`download-verify-decompress`.
-
-Upload the |CL| image to the VMware server
-******************************************
-
-Once the |CL| VMware prebuilt image has been downloaded and 
-decompressed on your local system, it must be uploaded to a datastore 
-on the VMware ESXi server.
-
-The steps in this section can also be referenced from the VMware documentation
-`Using Datastore File Browser in the VMware Host Client`_.
-
-#. Connect to the VMware ESXi server and login to an account with sufficient
-   permission to create and manage VMs.
-
-#. Under the :guilabel:`Navigator` window on the left side, 
-   select :guilabel:`Storage`.
-   See Figure 1
-
-#. Under the :guilabel:`Datastores` tab, click 
-   the :guilabel:`Datastore browser` button.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-1.png
-      :scale: 100 %
-      :alt: VMware ESXi - Navigator > Storage
-
-      Figure 1: VMware ESXi - Navigator > Storage
-
-#. Click the :guilabel:`Create directory` button and name the directory
-   `Clear Linux VM`. See Figure 2.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-2.png
-      :scale: 100 %
-      :alt: VMware ESXi - Datastore > Create directory
-
-      Figure 2: VMware ESXi - Datastore > Create directory
-
-#. Select the newly-created directory and click the :guilabel:`Upload`
-   button. See Figure 3.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-3.png
-      :scale: 100 %
-      :alt: VMware ESXi - Datastore > Upload VMware image
-
-      Figure 3: VMware ESXi - Datastore > Upload VMware image
-
-#. Select the decompressed |CL| VMware image file
-   :file:`clear-[version number]-vmware.vmdk` and upload it.
-
-Convert the |CL| image to an ESXi-supported format
-**************************************************
-
-Once the |CL| VMware prebuilt image has been uploaded to the VMware ESXi
-datastore, it must be converted to a format for usable with VMware's ESXi 
-hypervisor. 
-
-The steps in this section can also be referenced from the VMware documentation on `Cloning and converting virtual machine disks with vmkfstools`_
-
-#. SSH into the `vSphere Management Assistant`_  appliance that is managing
-   the ESXi host or connect to the vSphere hosting using the `vSphere CLI`_.
-
-   .. note::
-
-      If there is no :abbr:`vMA (vSphere Management Assistant)` appliance or :abbr:`vCLI (vSphere CLI)` configured and available, 
-      you can temporarily enable SSH directly on the ESXi host by following the
-      steps described in `Enable the Secure Shell (SSH) in the VMware Host Client`_ .
-
-      As a security best practice, remember to disable SSH access after following the steps in this section. 
-
-
-#. Locate the uploaded image, which is typically found in
-   :file:`/vmfs/volumes/datastore1`.
-
-#. Use the :command:`vmkfstools` command to perform the conversion, as
-   shown below:
-
-   .. code-block:: console
-
-      vmkfstools -i clear-[version number]-vmware.vmdk -d zeroedthick clear-[version number]-esxi.vmdk
-
-   Two files should result from this:
-
-   * :file:`clear-[version number]-esxi-flat.vmdk`
-   * :file:`clear-[version number]-esxi.vmdk`
-
-   The :file:`clear-[version number]-esxi.vmdk` file will be used in the
-   next section when you create a new VM.
-
-Create and configure a new VM
-*****************************
-
-In this section, you will create a new VM, configure its basic parameters
-such as number of CPUs, memory size, and then attach the converted |CL| 
-VMware image. Also, in order to boot |CL|, you must enable UEFI support. 
-
-#. Under the :guilabel:`Navigator` window, select 
-   :guilabel:`Virtual Machines`. See Figure 4.
-
-#. In the right window, click the :guilabel:`Create / Register VM` button.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-4.png
-      :scale: 100 %
-      :alt: VMware ESXi - Navigator > Virtual Machines
-
-      Figure 4: VMware ESXi - Navigator > Virtual Machines
-
-#. On the :guilabel:`Select creation type` step:
-
-   #. Select the :guilabel:`Create a new virtual machine` option. See
-      Figure 5.
-
-   #. Click the :guilabel:`Next` button.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-5.png
-      :scale: 100 %
-      :alt: VMware ESXi - Create a new virtual machine
-
-      Figure 5: VMware ESXi - Create a new virtual machine
-
-#. On the :guilabel:`Select a name and guest OS` step:
-
-#. Give the new VM a name in the :guilabel:`Name` field. See Figure 6.
-
-#. Set the :guilabel:`Compatability` option to
-   :guilabel:`ESXi 6.5 virtual machine`.
-#. Set the :guilabel:`Guest OS family` option to :guilabel:`Linux`.
-#. Set the :guilabel:`Guest OS version` option to 
-   :guilabel:`Other 3.x or later Linux (64-bit)`.
-#. Click the :guilabel:`Next` button.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-6.png
-      :scale: 100 %
-      :alt: VMware ESXi - Give a name and select guest OS type
-
-      Figure 6: VMware ESXi - Give a name and select guest OS type
-
-#. On the :guilabel:`Select storage` step:
-
-   #. Accept the default option.
-   #. Click the :guilabel:`Next` button.
-
-#. On the :guilabel:`Customize settings` step:
-
-   #. Click the :guilabel:`Virtual Hardware` button. See Figure 7.
-   #. Expand the :guilabel:`CPU` setting and enable 
-      :guilabel:`Hardware virtualization` by checking 
-      :guilabel:`Expose hardware assisted virtualization to the guest OS`.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-7.png
-      :scale: 100 %
-      :alt: VMware ESXi - Enable hardware virtualization
-
-      Figure 7: VMware ESXi - Enable hardware virtualization
-
-   #. Remove the default :guilabel:`Hard drive 1` setting by clicking
-      the `X` icon on the right side. See Figure 8.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-8.png
-      :scale: 100 %
-      :alt: VMware ESXi - Remove hard drive
-
-      Figure 8: VMware ESXi - Remove hard drive
-
-   #. Since a preconfigured image will be used, 
-      the :guilabel:`CD/DVD Drive 1` setting will not be needed.  Disable it 
-      by unchecking the :guilabel:`Connect` checkbox. See Figure 9.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-9.png
-      :scale: 100 %
-      :alt: VMware ESXi - Disconnect the CD/DVD drive
-
-      Figure 9: VMware ESXi - Disconnect the CD/DVD drive
-
-   #. Attach the :file:`clear-[version number]-esxi.vmdk` file that was
-      converted from the preconfigured |CL| VMware image.
-
-      #. Click the :guilabel:`Add hard disk` button and select the
-         :guilabel:`Existing hard drive` option. See Figure 10.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-10.png
-      :scale: 100 %
-      :alt: VMware ESXi - Add an existing hard drive
-
-      Figure 10: VMware ESXi - Add an existing hard drive
-
-      #. Select the converted :file:`clear-[version number]-esxi.vmdk`
-         file. Do not use the original unconverted 
-         :file:`clear-[version number]-vmware.vmdk` file. See Figure 11.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-11.png
-      :scale: 100 %
-      :alt: VMware ESXi - Select the converted `vmdk` file
-
-      Figure 11: VMware ESXi - Select the converted 
-      :file:`clear-[version number]-esxi.vmdk` file
-
-#. |CL| needs UEFI support in order to boot.  Enable UEFI boot support.
-
-   #. Click the :guilabel:`VM Options` button. See Figure 12.
-   #. Expand the :guilabel:`Boot Options` setting.
-   #. For the :guilabel:`Firmware` setting, click the drop-down list to
-      the right of it and select the :guilabel:`EFI` option.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-12.png
-      :scale: 100 %
-      :alt: VMware ESXi - Set boot firmware to EFI
-
-      Figure 12: VMware ESXi - Set boot firmware to EFI
-
-#. Click the :guilabel:`Save` button.
-#. Click the :guilabel:`Next` button.
-#. Click the :guilabel:`Finish` button.
-
-Power on the VM and boot |CL|
-*****************************
-
-After configuring the settings above, power on the VM.
-
-#. Under the :guilabel:`Navigator` window, select 
-   :guilabel:`Virtual Machines`. See Figure 13.
-#. In the right window, select the newly-created VM.
-#. Click the :guilabel:`Power on` button.
-#. Click on the icon representing the VM to bring it into view and maximize
-   its window.
-
-   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-13.png
-      :scale: 100 %
-      :alt: VMware ESXi - Navigator > Virtual Machines > Power on VM
-
-      Figure 13: VMware ESXi - Navigator > Virtual Machines > Power on VM
-
-Related topics
-**************
-
-* :ref:`vmware-esxi-install-cl`
-
-.. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html
-.. _Using Datastore File Browser in the VMware Host Client: https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.vsphere.html.hostclient.doc/GUID-7533A767-8396-4844-A3F2-206047D254EA.html
-.. _vSphere Management Assistant: https://www.vmware.com/support/developer/vima/
-.. _vSphere CLI: https://www.vmware.com/support/developer/vcli/
-.. _Cloning and converting virtual machine disks with vmkfstools: https://kb.vmware.com/kb/1028042
-.. _Enable the Secure Shell (SSH) in the VMware Host Client: https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.vsphere.html.hostclient.doc/GUID-B649CB74-832F-467B-B6A4-8BA67AD5C1F0.html
-.. _VMware Workstation Player: https://www.vmware.com/products/workstation-player.html
-.. _image: https://cdn.download.clearlinux.org/image

_sources/guides/clear/autoproxy.rst.txt

@@ -1,153 +0,0 @@
-.. _autoproxy:
-
-Autoproxy
-#########
-
-Autoproxy is provided to enable |CL-ATTR| to work smoothly behind a
-corporate proxy.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Description
-***********
-
-Autoproxy tries to detect a Proxy Auto-Config (PAC) script and use it to
-automatically resolve the proxy needed for a given connection. With
-Autoproxy, you can use |CL| inside any proxy environment without having to
-manually configure the proxies.
-
-Corporate and private networks can be very complex, needing to restrict and
-control network connections for security reasons. The typical side effects
-are limited or blocked connectivity, and require manual configuration of
-proxies to perform the most mundane tasks, such as cloning a repo or checking
-for updates. With |CL|, all of the work is done behind the scenes to
-effortlessly use your network and have connections “just work”.
-
-This feature removes severe complications with network connectivity due to
-proxy issues. You can automate tasks, such as unit testing, without worrying
-about the proxy not being set, and you can remove unset proxies from the
-equation when dealing with network unavailability across systems.
-
-How it works
-************
-
-We designed Autoproxy around tools provided by most Linux\*
-distributions with a few minor additions and modifications. We leveraged the
-DHCP and network information obtained from systemd and created a
-PAC-discovery daemon. The daemon uses the information to resolve a URL for a
-PAC file. The daemon then passes the URL into PACrunner\*. PACrunner
-downloads the PAC file and uses the newly implemented Duktape\* engine to
-parse it.
-
-.. figure:: figures/autoproxy_0.png
-   :width: 400px
-
-   Figure 1: Autoproxy Flow
-
-From that point on, any cURL\* or network requests query PACrunner for the
-correct proxy to use. We modified the cURL library to communicate with
-PACrunner over DBus. However, cURL will ignore PACrunner and run normally if
-no PAC file is loaded or if you manually set any proxies. Thus, your
-environment settings are respected and no time is wasted trying to resolve a
-proxy. All these steps happen in the background with no user interaction.
-
-Troubleshooting
-===============
-
-Autoproxy allows |CL| to operate seamlessly behind a proxy
-because :ref:`swupd <swupd-guide>` and other |CL| tools are implemented on
-top of libcurl. Tools that do not use libcurl, like git, must
-be configured independently. 
-
-If you are familiar with PAC files and WPAD, you can use
-:command:`pacdiscovery` and :command:`FindProxyForURL` to
-troubleshoot problems with autproxy.
-
-.. note::
-
-   Learn more about WPAD, PAC files, and PAC functions at `findproxyforurl`_.
-
-.. _findproxyforurl: http://findproxyforurl.com/
-
-Run :command:`pacdiscovery` with no arguments to indicate
-
-1. if there is a problem resolving the :command:`WPAD` host name resolution: 
-
-   .. code-block:: bash
-
-      pacdiscovery
-
-   .. code-block:: console
-
-      failed getaddrinfo: No address associated with hostname
-      Unable to find wpad host
-
-2. or if the :command:`pacrunner` service is disabled (masked).
-
-   .. code-block:: bash
-
-      pacdiscovery
-
-   .. code-block:: console
-
-      PAC url: http://autoproxy.your.domain.com/wpad.dat
-      Failed to create proxy config: Unit pacrunner.service is masked.
-
-Unmask the :command:`pacrunner` service by running:
-
-.. code-block:: bash
-
-   systemctl unmask pacrunner.service
-
-:command:`FindProxyForURL` with :command:`busctl` can also indicate if the
-:command:`pacrunner.service` is masked.
-
-.. code-block:: bash
-
-   busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client 
-
-.. code-block:: console
-   
-   FindProxyForURL ss "http://www.google.com" "google.com"
-   Unit pacrunner.service is masked.
-   dig wpad, dig wpad.<domain>
-
-:command:`FindProxyForURL` returns the URL and port of the proxy server when
-an external URL and host are provided as arguments.
-
-.. code-block:: bash
-
-   busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client 
-
-.. code-block:: console
-
-   FindProxyForURL ss "http://www.google.com" "google.com"
-   s "PROXY proxy.your.domain.com:<port>"
-
-If a proxy server is not avialable, or if :command:`pacrunner` is running
-without a PAC file, :command:`FindProxyForURL` will return "DIRECT". 
-
-.. code-block:: bash
-
-   busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client 
-
-.. code-block:: console 
-
-   FindProxyForURL ss "http://www.google.com" "google.com"
-   s "DIRECT"
-
-Once :command:`pacdiscovery` is able to look up :command:`WPAD`, restart the
-:command:`pacrunner` service:
-
-.. code-block:: bash
-
-   systemctl stop pacrunner
-   systemctl restart pacdiscovery
-
-.. note::
-
-   A "domain" or "search" entry in :file:`/etc/resolv.conf` is required
-   for short name lookups to resolve. The :file:`resolv.conf` man page has
-   additional details.

_sources/guides/clear/compatible-kernels.rst.txt

@@ -1,83 +0,0 @@
-.. _compatible-kernels:
-
-Kernels
-#######
-
-The |CL-ATTR| provides the following Linux kernels with a respective bundle.
-This document describes the specific use cases these `bundles`_ serve
-and provides links to their source code.
-
-Bare metal only
-***************
-
-Kernel native
-    The *kernel-native* bundle focuses on the bare metal platforms. It is
-    optimized for fast booting and performs best on the Intel® architectures
-    described on the :ref:`supported hardware list<system-requirements>`. The
-    optimization patches are found in our `Linux`_ GitHub\* repo.
-
-.. _vm-kernels:
-
-Also compatible with VMs
-************************
-
-Kernel LTS
-    The *kernel-lts* bundle focuses on the bare metal platforms but uses the
-    latest :abbr:`LTS (Long Term Support)` Linux kernel. It is optimized for
-    fast booting and performs best on the Intel® architectures described on the
-    :ref:`supported hardware list<system-requirements>`. Additionally, this
-    kernel includes the VirtualBox\* kernel modules, see our
-    :ref:`instructions on using Virtualbox<virtualbox-cl-installer>` for more
-    information. The optimization patches are found in our `Linux-LTS`_ GitHub
-    repo.
-
-VM only
-*******
-
-Kernel KVM
-    The *kernel-kvm* bundle focuses on the Linux
-    :abbr:`KVM (Kernel-based Virtual Machine)`. It is optimized for fast
-    booting and performs best on Virtual Machines running on the Intel®
-    architectures described on the
-    :ref:`supported hardware list<system-requirements>`. Use this kernel when
-    running |CL| as the guest OS on top of *qemu/kvm*. Use this kernel with
-    **cloud orchestrators** using *qemu/kvm* internally as their **hypervisor**
-    . This kernel can be used as a standalone |CL| VM, see our
-    :ref:`instructions on using KVM<kvm>` for more information. The
-    optimization patches are found in our `Linux-KVM`_ GitHub repo.
-
-Kernel Hyper-V\*
-    The *kernel-hyperv* bundle focuses on running Linux on Microsoft\*
-    Hyper-V. It is optimized for fast booting and performs best on Virtual
-    Machines running on the Intel® architectures described on the
-    :ref:`supported hardware list<system-requirements>`.
-    Use this kernel when running |CL| as the guest OS of **Cloud Instances** in
-    projects such as Microsoft `Azure`_\*. This kernel can be used in a
-    standalone |CL| VM, see our :ref:`instructions on using Hyper-V<hyper-v>`
-    for more information. The optimization patches are found in our
-    `Linux-HyperV`_ GitHub repo.
-
-Kernel Hyper-V LTS
-    The *kernel-hyperv-lts* bundle focuses on running Linux on Microsoft
-    Hyper-V but uses the latest :abbr:`LTS (Long Term Support)` Linux kernel.
-    It is optimized for fast booting and performs best on Virtual
-    Machines running on the Intel® architectures described on the
-    :ref:`supported hardware list<system-requirements>`.
-    Use this kernel when running |CL| as the guest OS of **Cloud Instances** in
-    projects such as Microsoft `Azure`_. This kernel can be used in a
-    standalone |CL| VM, see our :ref:`instructions on using Hyper-V<hyper-v>`
-    for more information. The optimization patches are found in our
-    `Linux-HyperV-LTS`_ GitHub repo.
-
-
-.. _Linux: https://github.com/clearlinux-pkgs/linux
-.. _Linux-LTS: https://github.com/clearlinux-pkgs/linux-lts
-.. _Linux-KVM: https://github.com/clearlinux-pkgs/linux-kvm
-.. _Linux-HyperV: https://github.com/clearlinux-pkgs/linux-hyperv
-.. _Linux-HyperV-LTS: https://github.com/clearlinux-pkgs/linux-hyperv-lts
-.. _Linux-Container: https://github.com/clearlinux-pkgs/linux-container
-.. _bundles: https://github.com/clearlinux/clr-bundles
-.. _CIAO: https://github.com/01org/ciao
-.. _Azure:
-   https://azuremarketplace.microsoft.com/en-us/marketplace/apps/clear-linux-project.clear-linux-os
-

_sources/guides/clear/debug.rst.txt

@@ -1,91 +0,0 @@
-.. _debug:
-
-Debug system
-############
-
-|CL-ATTR| introduces a novel approach to system software debugging using
-*clr-debug-info*. On the client side, the |CL| debug system obtains any
-necessary debug information on-the-fly over a network during a debugging
-session. On the server side, the system curates and compresses debug
-information into small pieces for efficient downloading.
-
-For developers, this avoids the interruption during debugging that usually
-happens when debug information is missing. This can be especially useful on
-systems where storage is limited. 
-
-
-.. contents:: :local:
-    :depth: 2
-
-
-Background
-----------
-
-Software that is compiled and packaged for general usage in an operating
-system typically only contains components that are used to execute the
-program, such as binaries and libraries. Extra developer data, such as the
-actual source code and symbol information, are separated and excluded for
-efficiency. 
-
-The debug information helps relate binary code to human readable source code
-lines and variables. Most of the time, this auxiliary information 
-is not needed;
-however without it, debugging a program results in limited visibility. 
-
-
-Usage
------
-
-The clr-debug-info system is integrated into |CL| and seamlessly engages once
-installed.
-
-#. Install the *dev-utils* bundle.
-
-   .. code:: bash
-
-      sudo swupd bundle-add dev-utils 
-
-   .. note::
-
-      The *telemetrics* and *performance-tools* bundles also include
-      clr-debug-info.
-
-
-#. Start a debugging session against a program using a debugger, such as GDB. 
-   For example, to debug *gnome-control-center* execute the following
-   command:
-
-   .. code:: bash
-
-      gdb /usr/bin/gnome-control-center
-
-As you step through the program and debug information is needed, the
-clr_debug_daemon obtains it in the background.
-
-
-Implementation
---------------
-
-The implementation of the |CL| debug system is open source and available on
-GitHub at: https://github.com/clearlinux/clr-debug-info/
-
-.. figure:: figures/debug-diagram.png
-   :width: 400px
-   :alt: Debug system communication flow
-
-   Figure 1: The communication flow of the |CL| debug system
-
-The |CL| debug system implements a :abbr:`FUSE (filesystem in userspace)`
-filesystem mounted at :file:`/usr/lib/debug` and :file:`/usr/src/debug`. The
-FUSE filesystem starts automatically. You can verify its status by executing
-:command:`systemctl status clr_debug_fuse.service`.
-
-The *clr_debug_daemon* is responsible for fetching the appropriate package
-debug content from the server and making it available for any debugging
-programs that need it. It is socket activated whenever a request to the local
-FUSE filesystem occurs. You can verify its status with :command:`systemctl
-status clr_debug_daemon.service`.
-
-
-|CL| hosts debuginfo content packaged for consumption by |CL| debug clients at
-https://download.clearlinux.org/debuginfo/

_sources/guides/clear/mixer.rst.txt

@@ -1,859 +0,0 @@
-.. _mixer:
-
-mixer
-#####
-
-**mixer** is the tool used by the |CL-ATTR| team to generate official update
-content and releases. The update content generated by mixer is then consumed
-by swupd on a downstream client. The same mixer tool is available as part of
-|CL| to create your own customized update content and releases.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Description
-***********
-
-mixer uses the following sources as inputs to generate update content:
-
-* Upstream |CL| bundles with their corresponding RPM packages
-* Locally-defined bundles with their corresponding local RPM packages
-* Locally-defined bundles with upstream RPM packages
-
-Using the mixer tool, you select which set of content from these sources
-will be part of your update. You can select content from each of these sources to make a unique combination of functionality for your custom update content, known as a **mix**.
-
-The update content that mixer generates consists of various pieces of OS
-content, update metadata, as well as a complete image. The OS content
-includes all files in an update, as well as zero- and delta-packs for improved update performance. The update metadata, stored as manifests, describes all of the bundle information for the update. Update content produced by mixer is then published to a web server and consumed by clients via swupd. Refer to :ref:`swupd <swupd-guide>` for additional information regarding updates and update content.
-
-How it works
-************
-
-Learn the mixer tool set up and workflow.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Prerequisites
-=============
-
-* :command:`mixer` bundle
-
-  Add the mixer tool with the :command:`mixer` bundle. Refer to
-  :ref:`swupd-guide` for more information on installing bundles.
-
-* Docker\* container
-
-  mixer by default runs all build commands in a Docker container to ensure
-  the correct tool versions are used. This also allows custom mixes to
-  automatically perform downstream format bumps when the upstream releases a
-  format bump. See `Format version`_ for additional information regarding
-  format bumps.
-
-  Refer to `Configure and enable Docker`_ for instruction.
-
-* Docker proxy (optional)
-
-  If you use a proxy server, you must set your proxy environment variables and
-  create a proxy configuration file for the Docker daemon and container.
-
-  Consult your IT department for the correct values if you are behind a
-  corporate proxy.
-
-  Refer to `Configure Docker proxy info`_ for instruction.
-
-* Location to host the update content and images
-
-  In order for swupd to make use of your mix, the update content for your mix
-  must be hosted on a web server. Your mix will be configured with an update
-  location URL, which swupd will use to pull down updates.
-
-  Refer to `Set up a nginx web server for mixer`_ for an simple example of
-  setting up an update location.
-
-Mix setup
-==========
-
-Follow these steps to create and initialize the mixer workspace. Complete
-the setup before you create a mix.
-
-#. Create workspace.
-
-   The mixer tool uses a simple workspace to contain all input and output in a
-   basic directory structure. The workspace is simply an empty folder from
-   which you execute the mixer commands. Each mix uses its own separate
-   workspace.
-
-#. Initialize the workspace and mix.
-
-   Before you create a mix, you must explicitly initialize the mixer workspace.
-   During initialization, the mixer workspace is configured and the base for
-   your mix is defined. By default, your mix is based on the latest
-   upstream version and starts with the minimum set of bundles. Your first custom
-   mix version number starts at 10. Alternatively, you can select other
-   versions or bundle sets from which to start.
-
-   Initialization creates the directory structure within the workspace and adds
-   the :file:`builder.conf` file, which is used to configure the mixer tool.
-
-   View the `mixer.init man page`_ for more information on mixer
-   initialization.
-
-   View the list of suitable `releases`_ from which to mix.
-
-#. Edit builder.conf.
-
-   :file:`builder.conf` tells the mixer tool how to configure the mix. For
-   example, it allows you to configure where mixer output is located and where
-   swupd update content will be located.
-
-   At minimum, set the URL of your update server so your custom OS knows where
-   to get update content.
-
-   Refer to the `builder.conf`_ section for more information.
-
-Create a mix
-============
-
-A mix is created with the following steps:
-
-#. Add custom RPMs and set up local repo (optional).
-
-   If you are adding custom RPMs to your mix, you must add the RPMs to
-   your mix workspace and set up a corresponding local repository.
-
-   Go to the :ref:`autospec<autospec>` guide to learn to build RPMs from
-   scratch. If the RPMs are not built on |CL|, make sure your
-   configuration and toolchain builds them correctly for |CL|. Otherwise there
-   is no guarantee they will be compatible.
-
-   Refer to the :ref:`autospec` guide for more information on using autospec to
-   build RPMs.
-
-#. Update and build bundles.
-
-   Add, edit, or remove bundles that will be part of your content and build
-   them. mixer automatically updates the :file:`mixbundles` file when you
-   update the bundles in your mix.
-
-   View the `mixer.bundle man page`_ for more information on configuring bundles
-   in a mix.
-
-   View the `mixer.build man page`_ for more information on building bundles.
-
-   View the `Bundles`_ section for more information on how mixer manages
-   bundles.
-
-#. Create the update content.
-
-   mixer creates update content with this step. Zero-packs are created
-   automatically, and delta-packs can be optionally created at the same time
-   (for all builds after version 0).
-
-   A zero-pack is the full set of content needed to go from mix version 0
-   (nothing) to the mix version for which you just built content.
-
-   A delta-pack provides the content *delta* between a `PAST_VERSION` to a
-   `MIX_VERSION` that allows the transition from one mix version to another.
-
-   View :ref:`swupd-guide`  for more information on update content.
-
-#. Create image.
-
-   mixer creates a bootable image from your updated content using
-   the :ref:`ister` tool. In this step you can specify which bundles you want
-   *preinstalled* in the image. Users can later install other bundles available
-   in your mix.
-
-#. Make update available.
-
-   Deploy update content and images to your update server.
-
-   View the `Example 3: Deploy updates to target`_ for a simple deployment
-   scenario.
-
-Maintain or modify mix
-======================
-
-Update or modify your content to a new version by following the steps to
-create a mix. Increment the mix version number for the next mix.
-
-Examples
-********
-
-The following examples are designed to work together and in order. The examples
-use:
-
-* A stock installation of |CL|.
-* A web server that comes with |CL| to host the content updates.
-* A simple VM that updates against the locally produced content created in
-  Example 2.
-
-Complete all `Prerequisites`_ before using these examples.
-
-Example 1: Mix set up
-======================
-
-This example shows the basic steps for the first-time setup of 
-mixer for a new mix.
-
-#. Create an empty directory to use as a workspace for mixer:
-
-   .. code-block:: bash
-
-      mkdir ~/mixer
-
-#. In your mixer workspace, generate an initial mix based on the latest upstream
-   |CL| version, with minimum bundles. In the initialization output, be aware 
-   that your initial mix version is set to 10 and that the minimum bundles have 
-   been added.
-
-   .. code-block:: bash
-
-      cd ~/mixer
-      mixer init
-
-#. Edit :file:`builder.conf` to set the value of CONTENTURL and VERSIONURL to
-   the IP address of  the nginx\* server you set up in the prerequisite
-   `Set up a nginx web server for mixer`_. For example:
-
-   .. code-block:: console
-
-      CONTENTURL="http://192.168.25.52"
-      VERSIONURL="http://192.168.25.52"
-
-Example 2: Create a simple mix
-==============================
-
-This example shows how to create a simple custom mix using upstream content.
-We'll create an image for a QEMU virtual machine that we can use later to test
-our mix.
-
-We can use the default bundles that were added during initialization, but these
-include the :command:`native-kernel` bundle that is intended to be used on a
-bare metal system instead of a VM. So we will modify the default bundle
-set to get a smaller kernel image, which will also be faster to load.
-
-#. Update bundles in mix:
-
-   .. code-block:: bash
-
-      mixer bundle remove kernel-native
-      mixer bundle add kernel-kvm
-
-#. In this case, we will add the `editors` bundle from upstream, but we will
-   remove the `joe` editor.
-
-   .. code-block:: bash
-
-      mixer bundle add editors
-      mixer bundle edit editors
-
-#. Use an editor and manually remove `joe` from the bundle definition.
-
-   .. code-block:: bash
-
-      $EDITOR ./local-bundles/editors
-
-#. List the bundles in the mix again to confirm removal.
-
-   .. code-block:: bash
-
-      mixer bundle list  --tree
-
-
-#. Build bundles:
-
-   .. code-block:: bash
-
-      mixer build bundles
-
-   Look in ~/mixer/update/image/<mix version>/full for the full chroot after the
-   :command:`build` command completes.
-
-#. Build update content. Browse to your \http://localhost site and you'll see
-   the web page is now up, but with no update content. Build the update content:
-
-   .. code-block:: bash
-
-      mixer build update
-
-   Refresh your \http://localhost site and now you can see the update
-   content for mix version 10.
-
-   Look in ~/mixer/update/www/<mix version> to see the update content in your
-   workspace.
-
-#. Configure image. Edit the ister configuration file for your image to include
-   all of the bundles you want preinstalled in the image. If this is the first
-   time creating an image, first get a copy of the
-   :file:`release-image-config.json` template file:
-
-   .. code-block:: bash
-
-      curl -O https://raw.githubusercontent.com/bryteise/ister/master/release-image-config.json
-
-   For this example, edit :file:`release-image-config.json` so that the root
-   partition size is "5G" and replace the "kernel-native" bundle with
-   "kernel-kvm".
-
-   .. code-block:: console
-
-      {
-        "DestinationType" : "virtual",
-        "PartitionLayout" : [ { "disk" : "release.img", "partition" : 1, "size" : "32M", "type" : "EFI" },
-                              { "disk" : "release.img", "partition" : 2, "size" : "16M", "type" : "swap" },
-                              { "disk" : "release.img", "partition" : 3, "size" : "5G", "type" : "linux" } ],
-        "FilesystemTypes" : [ { "disk" : "release.img", "partition" : 1, "type" : "vfat" },
-                              { "disk" : "release.img", "partition" : 2, "type" : "swap" },
-                              { "disk" : "release.img", "partition" : 3, "type" : "ext4" } ],
-        "PartitionMountPoints" : [ { "disk" : "release.img", "partition" : 1, "mount" : "/boot" },
-                                   { "disk" : "release.img", "partition" : 3, "mount" : "/" } ],
-        "Version": "latest",
-        "Bundles": ["kernel-kvm", "os-core", "os-core-update"]
-      }
-
-#. Build the image.
-
-   .. code-block:: bash
-
-      sudo mixer build image
-
-   The output from this step will be :file:`release.img`, which is a live image.
-
-#. Make the next mix. Create a new version of your mix, for the live image to
-   update to. Increment your mix version by 10:
-
-   .. code-block:: bash
-
-      mixer versions update
-
-   Repeat steps 1-3 to add the upstream :command:`curl` bundle to the mix:
-
-   .. code-block:: bash
-
-      mixer bundle add curl
-      mixer build bundles
-      mixer build update
-
-   Build optional delta-packs, which helps reduce client update time:
-
-   .. code-block:: bash
-
-      mixer build delta-packs --from 10 --to 20
-
-   Refresh your \http://localhost site to see the update content for
-   mix version 20.
-
-   Look in ~/mixer/update/www/<mix version> to see the update content in your
-   workspace.
-
-Example 3: Deploy updates to target
-===================================
-
-The image created in Example 2 is directly bootable in QEMU. In this example,
-we'll boot the image from Example 2 to verify it, and update the image from
-mix version 10 (from which the image was built), to mix version 20.
-
-#. Set up the QEMU environment.
-
-   Install the :command:`kvm-host` bundle to your |CL|:
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add kvm-host
-
-   Get the virtual EFI firmware, download the image launch script, and make it
-   executable:
-
-   .. code-block:: bash
-
-      curl -O https://download.clearlinux.org/image/OVMF.fd
-      curl -O https://download.clearlinux.org/image/start_qemu.sh
-      chmod +x start_qemu.sh
-
-#. Start your VM image (created in Example 2):
-
-   .. code-block:: bash
-
-      sudo ./start_qemu.sh release.img
-
-#. Log in as root and set a password
-
-#. Try out your mix.
-
-   Take a look at the default bundles installed in your mix:
-
-   .. code-block:: bash
-
-      swupd info
-      swupd bundle-list
-      swupd bundle-list -a
-
-#. Now we will add the `editors` bundle that we modified.
-
-   .. code-block:: bash
-
-      swupd bundle add editors
-
-#. Try to start the `joe` editor.  It should not appear because we removed it
-   from the original `editors` bundle.
-
-#. Next we will update from version 10 to 20 to capture the newly
-   available bundles. Use :command:`swupd` to update your mix:
-
-   .. code-block:: bash
-
-      swupd check-update
-      swupd update
-      swupd bundle-list -a
-
-#. Now your mix should be at version 20 and curl is now available. Try using
-   curl. This will fail because curl is not yet installed:
-
-   .. code-block:: console
-
-      curl: command not found
-      To install curl use: swupd bundle-add curl
-
-   Add the new bundle from your update server to your VM. Retry curl. It works!
-
-   .. code-block:: bash
-
-      swupd bundle-add curl
-      curl -O https://download.clearlinux.org/image/start_qemu.sh
-
-   Shutdown your VM:
-
-   .. code-block:: bash
-
-      poweroff
-
-
-.. Example: Create a mix with custom RPM
-.. -------------------------------------
-.. TODO future example to show copy into local-rpms...
-
-References
-**********
-
-Reference the `mixer man page`_ for details regarding mixer commands and options.
-
-.. contents::
-   :local:
-   :depth: 1
-
-.. rst-class:: content-collapse
-
-builder.conf
-============
-
-mixer initialization creates a :file:`builder.conf` that stores the basic
-configuration for the mixer tool. The items of primary interest are CONTENTURL
-and VERSIONURL, which will be used by systems updating against your custom
-content.
-
-.. code-block:: console
-
-   #builder.conf
-
-   #VERSION 1.0
-
-   [Builder]
-     CERT = "/home/clr/mix/Swupd_Root.pem"
-     SERVER_STATE_DIR = "/home/clr/mix/update"
-     VERSIONS_PATH = "/home/clr/mix"
-     YUM_CONF = "/home/clr/mix/.yum-mix.conf"
-
-   [Swupd]
-     BUNDLE = "os-core-update"
-     CONTENTURL = "<URL where the content will be hosted>"
-     VERSIONURL = "<URL where the version of the mix will be hosted>"
-
-   [Server]
-     DEBUG_INFO_BANNED = "true"
-     DEBUG_INFO_LIB = "/usr/lib/debug"
-     DEBUG_INFO_SRC = "/usr/src/debug"
-
-   [Mixer]
-     LOCAL_BUNDLE_DIR = "/home/clr/mix/local-bundles"
-     LOCAL_REPO_DIR = ""
-     LOCAL_RPM_DIR = ""
-     DOCKER_IMAGE_PATH = "clearlinux/mixer"
-
-Additional explanation of variables in :file:`builder.conf` is provided in Table
-1.
-
-+-------------------------------+----------------------------------------------------------+
-| **Variable**                  | **Explanation**                                          |
-+-------------------------------+----------------------------------------------------------+
-| `CERT`                        | Sets the path where mixer stores the certificate file    |
-|                               | used to sign content for verification. mixer             |
-|                               | automatically generates the certificate if you do not    |
-|                               | provide the path to an existing one, and signs the       |
-|                               | :file:`Manifest.MoM` file to provide security for the    |
-|                               | updated content you create.                              |
-|                               |                                                          |
-|                               | chroot-builder uses the certificate file to sign         |
-|                               | the root :file:`Manifest.MoM` file to provide            |
-|                               | security for content verification.                       |
-|                               |                                                          |
-|                               | swupd uses this certificate to verify the                |
-|                               | :file:`Manifest.MoM` file's signature.                   |
-|                               |                                                          |
-|                               | For now, we strongly recommend that you do not modify    |
-|                               | this variable, as swupd expects a certificate with a     |
-|                               | very specific configuration to sign and verify           |
-|                               | properly.                                                |
-+-------------------------------+----------------------------------------------------------+
-| `CONTENTURL` and `VERSIONURL` | Set these variables to the IP address of the web server  |
-|                               | hosting the update content.                              |
-|                               |                                                          |
-|                               | VERSIONURL is the IP address where the swupd client      |
-|                               | looks to determine if a new version is available.        |
-|                               |                                                          |
-|                               | CONTENTURL is the location from which swupd pulls        |
-|                               | content updates.                                         |
-|                               |                                                          |
-|                               | If the web server is on the same machine as the          |
-|                               | SERVER_STATE_DIR directory, you can create a symlink to  |
-|                               | the directory in your web server's document root to      |
-|                               | easily host the content.                                 |
-|                               |                                                          |
-|                               | These URLs are embedded in the images created by mixer.  |
-+-------------------------------+----------------------------------------------------------+
-| `DOCKER_IMAGE_PATH`           | Sets the base name of the docker image that mixer pulls  |
-|                               | down to run builds in the proper container.              |
-+-------------------------------+----------------------------------------------------------+
-| `LOCAL_BUNDLE_DIR`            | Sets the path where mixer stores the local bundle        |
-|                               | definition files. The bundle definition files include    |
-|                               | any new, original bundles you create, along with any     |
-|                               | edited versions of upstream bundles.                     |
-+-------------------------------+----------------------------------------------------------+
-| `SERVER_STATE_DIR`            | Sets the path to which mixer outputs content. By         |
-|                               | default, mixer automatically sets the path.              |
-+-------------------------------+----------------------------------------------------------+
-| `VERSIONS_PATH`               | Sets the path for the mix version and upstream version's |
-|                               | two state files: :file:`mixversion` and                  |
-|                               | :file:`upstreamversion`. mixer creates both files for    |
-|                               | you when you set up the workspace.                       |
-+-------------------------------+----------------------------------------------------------+
-| `YUM_CONF`                    | Sets the path where mixer automatically generates the    |
-|                               | :file:`.yum-mix.conf` file.                              |
-|                               |                                                          |
-|                               | The yum configuration file points the chroot-builder to  |
-|                               | where the RPMs are stored.                               |
-+-------------------------------+----------------------------------------------------------+
-| **Table 1**: *Variables in builder.conf*                                                 |
-+-------------------------------+----------------------------------------------------------+
-
-Format version
---------------
-
-Compatible versions of an OS are tracked with an OS *compatibility epoch*.
-Versions of an OS within an epoch are fully compatible and can update to any
-other version within that epoch. The compatibility epoch is set as the
-`Format` variable in the :file:`mixer.state` file. Variables in the
-:file:`mixer.state` are used by mixer between executions and should not be
-manually changed.
-
-A format bump is like modifying the foundation of a house to create a new
-level. If `Format` increments to a new epoch (a "format bump"), the OS has
-changed in such a way that updating from build A in format X to build B in
-format Y will not work.
-
-A format bump is required when:
-
-* The software updater, :command:`swupd`, or the software is no longer
-  compatible with the previous update scheme
-
-* A package is removed from the update stream and the update must ensure the
-  files associated with that package are removed from the system
-
-Using a format increment, we make sure pre- and co-requisite changes flow out
-with proper ordering. The updated client will only update to the latest
-release in its respective format version, unless overridden by command line
-flags. In this way, we can guarantee that all clients update to the final
-version in their given format.
-
-The given format *must* contain all the changes needed to understand the content built in the next format. Only after reaching the final release in the old format can a client continue to update to releases in the new format.
-
-The format version is incremented only when a compatibility breakage is
-introduced. Normal updates, such as updating a software package, do not require a format increment.
-
-.. rst-class:: content-collapse
-
-Bundles
-=======
-
-mixer stores information about the bundles included in a mix in a flat file
-called :file:`mixbundles`, which is located in the path set by the VERSIONS_PATH variable in :file:`builder.conf`. :file:`mixbundles` is automatically created when the mix is initiated. mixer will refresh the file each time you change the bundles in the mix.
-
-Bundles can include other bundles. Nested bundles can themselves include
-other bundles. If you see an unexpected bundle in your mix, it is likely a
-nested bundle in one of the bundles you explicitly added.
-
-A bundle will fill into one of two categories: upstream or local. Upstream
-bundles are those provided by |CL|. Local bundles are either modified upstream bundles or new local bundles.
-
-Upstream bundles
-----------------
-
-mixer automatically downloads and caches upstream bundle definition files.
-These definition files are stored in the upstream-bundles directory in the
-workspace. Do not modify the files in this directory. This directory is
-simply a mirror for mixer to use. mixer will automatically delete the
-contents of this directory before repopulating it on-the-fly if a new
-version must be downloaded.
-
-The mixer tool automatically caches the bundles for the |CL| version
-configured in the :file:`upstreamversion` file. mixer also cleans up old
-versions once they are no longer needed.
-
-Local bundles
--------------
-
-Local bundles are bundles that you create, or are edited versions of upstream
-bundles. Local bundle definition files are stored in the local-bundles
-directory in the workspace. The LOCAL_BUNDLE_DIR variable sets the path of this directory in the :file:`builder.conf` file.
-
-*mixer always checks for local bundles first and the upstream bundles
-second.* So bundles in the local-bundles directory will always take
-precedence over any upstream bundles that have the same name. This
-precedence enables you to copy upstream bundles locally, and edit into a
-local variation.
-
-Bundle configuration
---------------------
-
-mixer provides commands to configure the bundles for a mix, such as to add a
-bundle to a mix, to create a new bundle for a mix, or to remove a bundle from a
-mix. View the `mixer.bundle man page`_ for a full list of commands and more
-information on configuring bundles in a mix.
-
-Editing an existing local bundle is as simple as opening the bundle definition
-file in your favorite editor, making the desired edits, and saving your changes.
-
-.. note::
-
-   Removing bundles from a mix: By default, removing a bundle will only
-   remove the bundle from the mix. The local bundle definition file will
-   still remain. To completely remove a bundle, including its local bundle definition file, use the :command:`--local` flag.
-
-   If you remove the bundle definition file for a local, edited version of an
-   upstream bundle in a mix, the mix reverts to reference the original upstream version of the bundle.
-
-.. rst-class:: content-collapse
-
-Configure and enable Docker
-===========================
-
-Use these steps to enable Docker for the mixer tool. Make sure to
-`Configure Docker proxy info`_ first if needed.
-
-#. Start the Docker daemon:
-
-   .. code-block:: bash
-
-      sudo systemctl start docker
-      sudo chmod 777 /var/run/docker.sock
-      sudo docker info
-
-#. Add user to the docker group
-
-   .. code-block:: bash
-
-      sudo usermod -G docker -a <username>
-
-Pull Docker container manually (optional)
------------------------------------------
-
-By default, mixer automatically pulls a Docker container for mixing if one
-does not already exist. If you need to troubleshoot the mixer container, it
-may be useful to manually pull a mixer Docker container.
-
-Versions of the mixer Docker container are available under the tags for the
-`clearlinux/mixer repo <https://hub.docker.com/r/clearlinux/mixer/tags/>`_
-on Docker Hub. Each version of the mixer Docker container is named after the
-associated |CL| upstream format version. Refer to `Format version`_ for
-additional information on upstream format versions.
-
-Use the following steps to manually pull a mixer Docker container:
-
-#. Find the version of the container you need by viewing the tags for the
-   `clearlinux/mixer repo <https://hub.docker.com/r/clearlinux/mixer/tags/>`_
-   on Docker Hub.
-
-#. Pull the latest container version:
-
-   .. code-block:: bash
-
-      docker pull clearlinux/mixer:<upstream-format-version>
-
-#. View local docker images:
-
-   .. code-block:: bash
-
-      docker images
-
-.. rst-class:: content-collapse
-
-Configure Docker proxy info
-===========================
-
-If needed, use these steps to configure the Docker proxy information.
-
-#. Create the Docker daemon proxy config directory:
-
-   .. code-block:: bash
-
-      sudo mkdir -p /etc/systemd/system/docker.service.d
-
-#. Create :file:`/etc/systemd/system/docker.service.d/http-proxy.conf` and
-   add the following using your own proxy values:
-
-   .. code-block:: console
-
-      [Service]
-      Environment="HTTP_PROXY=<HTTP proxy URL>:<port number>"
-      Environment="HTTPS_PROXY=<HTTPS proxy URL>:<port number>"
-
-#. Reload the Docker daemon:
-
-   .. code-block:: bash
-
-      sudo systemctl daemon-reload
-
-Configure the Docker container proxies, to pass proxy settings to
-containers:
-
-#. Create a directory for your container config:
-
-   .. code-block:: bash
-
-      mkdir ~/.docker
-
-#. Create the config file :file:`~/.docker/config.json` and add the following
-   entries, using your own proxy values:
-
-   .. code-block:: console
-
-      {
-        "proxies":
-        {
-          "default":
-          {
-            "httpProxy": "<proxy-url>:<port>",
-            "httpsProxy": "<proxy-url>:<port>"
-          }
-        }
-      }
-
-#. Set ownership and permission on the docker config directory:
-
-   .. code-block:: bash
-
-      sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
-      sudo chmod g+rwx "$HOME/.docker" -R
-
-Configure proxies to allow mixer to access upstream content from behind
-a firewall.
-
-#. Open your :file:`$HOME/.bashrc` file and add proxy and port values for the
-   following:
-
-   .. code-block:: console
-
-      export http_proxy="<proxy-url>:<port>"
-      export https_proxy="<proxy-url>:<port>"
-      export HTTP_PROXY="<proxy-url>:<port>"
-      export HTTPS_PROXY="<proxy-url>:<port>"
-      export no_proxy="<...>"
-
-#. Log out and log back in for the proxies to take effect.
-
-.. rst-class:: content-collapse
-
-Set up a nginx web server for mixer
-===================================
-
-A web server is needed to host your update content. In this example, we use
-the nginx web server, which comes with |CL|.
-
-Set up a nginx web server for mixer with the following steps:
-
-#. Install the :command:`nginx` bundle:
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add nginx
-
-#. Make the directory where mixer updates will reside:
-
-   .. code-block:: bash
-
-      sudo mkdir -p /var/www
-
-#. Create a symbolic link between your workspace updates and the updates on
-   the local nginx web server. In this example, `$HOME/mixer` is the
-   workspace for the mix.
-
-   .. code-block:: bash
-
-      sudo ln -sf $HOME/mixer/update/www /var/www/mixer
-
-#. Set up ``nginx`` configuration:
-
-   .. code-block:: bash
-
-      sudo mkdir -p  /etc/nginx/conf.d
-
-#. Copy the default example configuration file:
-
-   .. code-block:: bash
-
-      sudo cp -f /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf
-
-#. Configure the mixer update server. Create and add the following server
-   configuration content to :file:`/etc/nginx/conf.d/mixer.conf` (sudo required):
-
-   .. code-block:: console
-
-      server {
-           server_name localhost;
-           location / {
-                     root /var/www/mixer;
-                     autoindex on;
-           }
-      }
-
-#. Restart the daemon, enable nginx on boot, and start the service.
-
-   .. code-block:: bash
-
-      sudo systemctl daemon-reload
-
-      sudo systemctl enable nginx
-
-      sudo systemctl start nginx
-
-#. Verify the web server is running at \http://localhost. At this point
-   you should no longer see a "404 Not Found" message.
-
-Related topics
-**************
-
-* :ref:`About mixer <mixer-about>`
-* :ref:`autospec-about`
-* :ref:`bundles-about`
-* :ref:`swupd-about`
-
-.. _Docker Hub: https://hub.docker.com/r/clearlinux/mixer/tags/
-.. _mixer man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.1.rst
-.. _mixer.init man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.init.1.rst
-.. _mixer.bundle man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.bundle.1.rst
-.. _mixer.build man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.build.1.rst
-.. _releases: https://github.com/clearlinux/clr-bundles/releases

_sources/guides/clear/security.rst.txt

@@ -1,156 +0,0 @@
-.. _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
-within the project's codebase and operating culture.
-
-.. contents:: :local:
-   :depth: 1
-
-Security in updates
-*******************
-
-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.
-
-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|.
-
-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
-a software update, if desired.
-
-In |CL| updates are delivered automatically, efficiently, and effectively. For
-more information about software updates in |CL|, refer to the :ref:`swupd-guide`
-guide.
-
-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
-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 CVEs daily, and security
-patches are deployed as soon as they are available.
-
-These combined practices minimize the amount of time |CL| systems are exposed to unnecessary security risk.
-
-Security in software
-*********************
-
-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:
-
-* `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
-  have been removed such as the `finger` and `tcpwrappers`.
-
-* `SFTP` has been disabled by default due to security considerations.
-
-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:
-
-* All update operations from swupd are transparently encrypted and checked
-  against the |CL| maintainers' public key for authenticity.
-  More information about swupd security can be found in the
-  `Security for software update in Clear Linux* OS`_ blog post.
-
-* 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.
-
-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:
-
-* 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
-  `Kernel address space layout randomization (KASLR)`_  are kernel features
-  which defend against certain memory based attacks.
-  More information about PIE executables can be found in the
-  `Recent GNU* C library improvements`_ blog post.
-
-Security in system design
-*************************
-
-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:
-
-* Full disk encryption using :abbr:`LUKS (Linux Unified Key Setup)` is available
-  during installation. Refer to `cryptsetup`_ for additional information about
-  LUKS.
-
-* |CL| uses the PAM cracklib module to harden user login and password
-  security resulting in:
-
-  - 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,
-    cannot be set in |CL|.
-
-  - 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.
-
-.. _`Security for software update in Clear Linux* OS`: https://clearlinux.org/blogs/security-software-update-clear-linux-os-intel-architecture
-.. _`Recent GNU* C library improvements`: https://clearlinux.org/blogs/recent-gnu-c-library-improvements
-.. _`rolling release`: https://en.wikipedia.org/wiki/Rolling_release
-.. _`clrtrust`: https://github.com/clearlinux/clrtrust
-.. _`Address space layout randomization (ASLR)`: https://en.wikipedia.org/wiki/Address_space_layout_randomization
-.. _`Kernel address space layout randomization (KASLR)`: https://lwn.net/Articles/569635/
-.. _`cryptsetup`: https://gitlab.com/cryptsetup/cryptsetup/
-.. _`Tallow`: https://github.com/clearlinux/tallow
-
-.. |NVD| raw:: html
-
-    <a href="https://nvd.nist.gov/" target="_blank">https://nvd.nist.gov/</a>
-
-.. |MITRE| raw:: html
-
-    <a href="https://cve.mitre.org/" target="_blank">https://cve.mitre.org/</a>

_sources/guides/clear/stateless.rst.txt

@@ -1,139 +0,0 @@
-.. _stateless:
-
-Stateless
-#########
-
-In most operating systems, user data, system data, and configuration files
-can become intermingled.
-
-.. figure:: figures/stateless-1.png
-   :scale: 45%
-   :align: center
-   :alt: Stateless: User and system files mixed
-
-   Figure 1: Without stateless, user and system files become mixed on the filesystem over time.
-
-|CL-ATTR| has a stateless design philosophy with the goal to provide an
-:abbr:`OS (operating system)` that functions without excessive user
-configuration or customization. Stateless in this context does *not* mean
-ephemeral or non-persistent.
-
-.. contents:: :local:
-   :depth: 1
-
-File-level separation
-*********************
-
-To accomplish a stateless design the Linux Filesystem Hierarchy is separated
-between user-owned areas and |CL|-owned areas.
-
-.. figure:: figures/stateless-2.png
-   :scale: 45%
-   :align: center
-   :alt: Stateless: User and system files separation
-
-   Figure 2: With stateless, user and system files are separated on the filesystem.
-
-System areas
-============
-File under the :file:`/usr` directory are managed by |CL| as system files.
-Files written under the :file:`/usr` directory by users can get removed
-through system updates with :ref:`swupd <swupd-about>`. This operating
-assumption allows |CL| to verify and maintain integrity of system files.
-
-User areas
-==========
-Files under the :file:`/etc/`, :file:`/home`, and :file:`/var` directories are
-owned and managed by the user. A freshly installed |CL| system will only have
-a minimal set of files in the :file:`/etc/` directory and software installed
-by |CL| does not write to :file:`/etc`. This operating assumption allows |CL|
-users to clearly identify the configuration that makes their system unique.
-
-
-Software configuration
-**********************
-
-With stateless separation, default software configurations are read in order
-from predefined source code, |CL| provided defaults, and user-provided
-configuration.
-
-Default configurations
-======================
-
-Software in |CL| provides default configuration values so that it is
-immediately functional, whenever it is appropriate to do so.
-
-|CL| distributed software packages may be directly modified to include default
-configuration values or default configuration files may be provided by |CL|
-under :file:`/usr/share/defaults`. These files can be referenced as templates
-for customization.
-
-For example, the default configuration that Apache uses when installed can be
-found at :file:`/usr/share/defaults/httpd/httpd.conf` directory.
-
-
-Overriding configurations
-=========================
-
-If a configuration needs to be changed, the appropriate file should be
-modified by the user under :file:`/etc/`. If the configuration file does not
-already exist, it can be created in the appropriate location.
-
-User defined configuration files should contain the minimal set of desired
-changes and rely on default configuration for the rest.
-
-For example, a customized Apache configuration can be used instead by:
-
-#. Create the destination directory for the configuration:
-
-   .. code-block:: bash
-
-      sudo mkdir /etc/httpd
-
-#. Copy the default configuration as a reference template:
-
-   .. code-block:: bash
-
-      sudo cp /usr/share/defaults/httpd/httpd.conf /etc/httpd/
-
-#. Make any desired modifications to the configurations:
-
-   .. code-block:: bash
-
-      sudoedit /etc/httpd/httpd.conf
-
-#. Reload the service or reboot the system to pickup any changes:
-
-   .. code-block:: bash
-
-      systemctl daemon-reload httpd && systemctl restart httpd
-
-This pattern can be used to modify the configurations of other programs too.
-The `stateless man page`_ has application-specific examples.
-
-System reset
-************
-
-Once advantage of the stateless design is that the system defaults can be
-easily restored by simply deleting everything under :file:`/etc/` and
-:file:`/var`.
-
-Running the commands below effectively performs a system reset as if it was
-just installed:
-
-.. code-block:: bash
-
-   sudo rm -rf /etc
-   sudo rm -rf /var
-
-In other Linux distributions, this can be a catastrophic action that renders
-a system unable to boot.
-
-Additional information
-**********************
-
-* `stateless man page`_
-
-.. _`stateless man page`: https://github.com/clearlinux/clr-man-pages/blob/master/stateless.7.rst
-
-

_sources/guides/clear/swupd-guide.rst.txt

@@ -1,351 +0,0 @@
-.. _swupd-guide:
-
-swupd
-#####
-
-:command:`swupd` links a |CL-ATTR| installation with upstream updates and
-software.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Description
-***********
-
-:command:`swupd` has two main functions:
-
-#. Manage software and replace APT or YUM, by installing bundles
-   rather than packages.
-#. Check for system updates and install them.
-
-:command:`swupd` manages overlapping dependencies behind the scenes, ensuring
-that all software is compatible across the system. It can be used to verify
-the OS, clean cached files, and fix issues.
-
-:ref:`Bundles <bundles>` contain everything needed to deliver a software
-capability. They are the smallest granularity component that is
-managed by |CL|. A bundle comes with all of its dependencies rather than
-downloading a cascade of package dependencies when installing a piece of
-software.
-
-Versioning
-==========
-
-Using package managers to monitor software version compatibility or
-compare multiple systems on many Linux distributions can be cumbersome.
-
-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.
-
-A number that represents the **current** release of the OS describes 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. On a daily basis,
-this matters 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|.
-
-Updating
-========
-
-|CL| enforces regular updating of the OS by default and automatically
-checks for updates against a version server. The content server provides the
-file and metadata content for all versions and can be the same as the
-version server. The content url server provides metadata in the form of
-*manifests*, which list and describe file contents, symlinks,
-and directories. Additionally, the actual content is provided to clients
-in the form of archive files.
-
-Software updates with |CL| are also efficient. Unlike package-based
-distributions, :command:`swupd` only updates files that have changed, rather
-than entire packages. For example, it is quite common for an OS security
-patch to be as small as 15 KB. Using binary deltas, |CL| is able to
-apply only what is needed.
-
-For details on how to generate update content for |CL|, see the
-:ref:`mixer <mixer>` tool.
-
-How it works
-************
-
-Prerequisites
-=============
-
-* The device is on a well-connected network.
-* The device is able to connect to an update server. The default server is:
-  http://update.clearlinux.org
-
-Updates
-=======
-
-|CL| updates are automatic by default, but can be set to occur only on
-demand. :command:`swupd` makes sure that regular updates are simple and
-secure. It can also check the validity of currently installed files and
-software, and can correct any problems.
-
-Manifests
----------
-
-The |CL| software update content consists of data and metadata. The data is
-the files that end up in the OS. The metadata contains relevant information to
-properly provision the data to the OS file system, as well as update the
-system and add or remove additional content to the OS.
-
-The manifests are mostly long lists of hashes that describe content.
-Each bundle gets its own manifest file. There is a master manifest
-file that describes all manifests to tie it all together.
-
-Fullfiles, packs, and delta packs
----------------------------------
-
-To speed up updates and optimize content delivery, update data provisioned to
-a system is obtained by one of the following methods:
-
-* *Fullfiles* are always generated for every file in every release. This
-  allows any |CL| to obtain the exact copy of the content
-  for each version directly. This is used if the OS verification
-  needs to replace a single file, for instance.
-
-* *Packs* are available for some releases. They combine many files to speed
-  up the creation of installation media and large updates.
-
-* *Delta packs* are an optimized version of packs that only contain updates
-  (binary diffs). They cannot be used without having the original file content.
-
-Bundle search
-=============
-
-:command:`swupd` searches download manifest data for
-bundles that match the term. Enter only one term, or hyphenated term, per
-search. Use the command :command:`man swupd` to learn more.
-
-Only the base bundle is returned. Bundles can contain other bundles via
-includes. For more details, see `Bundle Definition Files`_ and its
-subdirectory bundles.
-
-Bundles that are already installed are marked **(installed)** in search
-results.
-
-Optionally, you can review our `bundles`_ on GitHub\*.
-
-Examples
-********
-
-Example 1: Disable and enable automatic updates
-===============================================
-
-|CL| updates are automatic by default, but can be set to occur only
-on demand.
-
-#. Verify your current auto-update setting.
-
-   .. code-block:: bash
-
-      sudo swupd autoupdate
-
-   Output:
-
-   .. code-block:: console
-
-      Enabled
-
-#. Disable automatic updates.
-
-   .. code-block:: bash
-
-      sudo swupd autoupdate --disable
-
-   Output:
-
-   .. code-block:: console
-
-      Warning: disabling automatic updates may take you out of compliance with your IT policy
-
-      Running systemctl to disable updates
-      Created symlink /etc/systemd/system/swupd-update.service → /dev/null.
-      Created symlink /etc/systemd/system/swupd-update.timer → /dev/null.
-
-#. Check manually for updates.
-
-   .. code-block:: bash
-
-      sudo swupd check-update
-
-#. Install an update after identifying one that you need.
-
-   .. code-block:: bash
-
-      sudo swupd update --version <version number>
-
-#. Re-enable automatic installs.
-
-   .. code-block:: bash
-
-      sudo swupd autoupdate --enable
-
-.. _swupd-guide-example-install-bundle:
-
-Example 2: Find and install Kata Containers\*
-=============================================
-
-Kata Containers is a popular container implementation. Unlike other
-container implementations, each Kata Container has its own
-kernel instance and runs on its own :abbr:`VM (Virtual Machine)` for
-improved security.
-
-|CL| makes it very easy to install, since you only need to add
-one bundle to use `Kata Containers`_: `containers-virt`_, despite a
-number of dependencies.  Also, check out our tutorial: :ref:`kata`.
-
-#. Find the correct bundle.
-
-   To return all possible matches for the search string, enter
-   :command:`swupd search`, followed by 'kata':
-
-   .. code-block:: bash
-
-      sudo swupd search kata
-
-   The output should be similar to:
-
-   .. code-block:: console
-
-      Bundle with the best search result:
-
-      containers-virt - Run container applications from Dockerhub in
-      lightweight virtual machines
-
-      This bundle can be installed with:
-
-           swupd bundle-add  containers-virt
-
-      Alternative bundle options are
-
-           cloud-native-basic - Contains ClearLinux native software for Cloud
-
-   .. note::
-
-      If your search does not produce results with a specific term, shorten
-      the search term. For example, use *kube* instead of *kubernetes*.
-
-#. Add the bundle.
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add containers-virt
-
-   .. note::
-
-      To add multiple bundles, add a space followed by the bundle name.
-
-   The output of a successful installation should be similar to:
-
-   .. code-block:: console
-
-      Downloading packs...
-
-      Extracting containers-virt pack for version 24430
-          ...50%
-      Extracting kernel-container pack for version 24430
-          ...100%
-      Starting download of remaining update content. This may take a while...
-          ...100%
-      Finishing download of update content...
-      Installing bundle(s) files...
-          ...100%
-      Calling post-update helper scripts.
-      Successfully installed 1 bundle
-
-Example 3: Verify and correct system file mismatch
-==================================================
-
-:command:`swupd` can determine whether system directories and files have
-been added to, overwritten, removed, or modified (e.g., permissions).
-
-.. code-block:: bash
-
-   sudo swupd diagnose
-
-All directories that are watched by :command:`swupd` are verified according
-to the manifest data. Hash mismatches are flagged as follows:
-
-.. code-block:: console
-
-   Verifying version 23300
-   Verifying files
-      ...0%
-   Hash mismatch for file: /usr/bin/chardetect
-   ...
-   ...
-   Hash mismatch for file: /usr/lib/python3.6/site-packages/urllib3/util/wait.py
-      ...100%
-   Inspected 237180 files
-      423 files did not match
-   Verify successful
-
-In this case, Python\* packages that were installed on top of the default
-install were flagged as mismatched. :command:`swupd` can be directed to
-ignore or fix issues based on command line options.
-
-:command:`swupd` can correct any issues it detects. Additional directives
-can be added including a white list of directories to be ignored.
-
-The following command repairs issues, removes unknown items, and
-ignores files or directories matching :file:`/usr/lib/python`:
-
-.. code-block:: bash
-
-   sudo swupd repair --picky --picky-whitelist=/usr/lib/python
-
-Quick reference
-***************
-
-swupd info
-   Returns the currently installed version and update servers.
-
-swupd update <version number>
-   Updates to a specific version or updates to latest version if no
-   arguments are used.
-
-swupd bundle-list [--all]
-   Lists installed bundles.
-
-swupd bundle-add [-b] <search term>
-   Finds a bundle that contains your search term.
-
-swupd bundle-add <bundle name>
-   Adds a bundle.
-
-swupd bundle-remove <bundle name>
-   Removes a bundle.
-
-swupd --help
-   Lists additional :command:`swupd` commands.
-
-man swupd
-   Opens the :command:`swupd` man page.
-
-Refer to `swupd source documentation`_ on GitHub for more details.
-
-Related topics
-**************
-
-* :ref:`autospec`
-* :ref:`mixer`
-* :ref:`bundles`
-
-.. _swupd source documentation: https://github.com/clearlinux/swupd-client/blob/master/docs/swupd.1.rst
-
-.. _Kata Containers: https://clearlinux.org/downloads/containers
-
-.. _containers-virt: https://github.com/clearlinux/clr-bundles/blob/master/bundles/containers-virt
-
-.. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles
-
-.. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles

_sources/guides/guides.rst.txt

@@ -1,58 +0,0 @@
-.. _guides:
-
-Guides
-######
-
-The following guides provide step-by-step instructions on using |CL|.
-
-.. note::
-
-   As of 22 May 2019 :file:`mixin` is no longer supported.
-
-Clear Linux
-===========
-
-.. toctree:: 
-   :maxdepth: 1
-   :glob:
-
-   clear/*
-   telemetrics/*
-
-Maintenance
-===========
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   maintenance/*
-   deploy-at-scale
-
-Network
-=======
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   network/*
-
-Kernel
-=======
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   kernel/*
-
-Stacks
-=======
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   stacks/*
-   stacks/dlrs/*

_sources/guides/kernel/kernel-modules-dkms.rst.txt

@@ -1,312 +0,0 @@
-.. _kernel-modules-dkms:
-
-Add kernel modules with DKMS
-############################
-
-This guide describes how to add kernel modules with
-:abbr:`DKMS (Dynamic Kernel Module System)`.
-
-.. contents:: :local:
-   :depth: 1
-   :backlinks: top
-
-Overview
-********
-
-Certain kernel modules are enabled by default in |CL-ATTR|. To use additional
-kernel modules that are not part of the Linux source tree, you may need to
-build out-of-tree kernel modules. Use this guide to add kernel modules with
-:abbr:`DKMS (Dynamic Kernel Module System)` or refer to :ref:`kernel-modules`.
-
-Description
-***********
-
-Kernel modules are additional pieces of software capable of being inserted
-into the Linux kernel to add functionality, such as a hardware driver.
-Kernel modules may already be part of the Linux source tree (in-tree) or may
-come from an external source, such as directly from a vendor (out-of-tree).
-
-:abbr:`DKMS (Dynamic Kernel Module System)` is a framework that facilitates
-the building and installation of kernel modules. DKMS allows |CL| to provide
-hooks that automatically rebuild modules against new kernel versions.
-
-.. include:: kernel-modules.rst
-   :start-after: kernel-modules-availability-begin:
-   :end-before: kernel-modules-availability-end:
-
-Install DKMS
-************
-
-.. _kernel-modules-dkms-install-begin:
-
-The :command:`kernel-native-dkms` bundle provides the :command:`dkms` program and
-Linux kernel headers, which are required for compiling kernel modules.
-
-The :command:`kernel-native-dkms` bundle also:
-
-* Adds a `systemd` update trigger
-  (:file:`/usr/lib/systemd/system/dkms-new-kernel.service`) to automatically
-  run DKMS to rebuild modules after a kernel upgrade occurs with :ref:`swupd
-  update <swupd-guide>`.
-
-* Disables kernel module signature verification by appending a kernel
-  command-line parameter (:command:`module.sig_unenforce`) from the
-  :file:`/usr/share/kernel/cmdline.d/clr-ignore-mod-sig.conf` file.
-
-* Adds a notification to the Message of the Day (MOTD) indicating kernel
-  module signature verification is disabled.
-
-.. warning::
-
-   We recommend that you always review the :command:`swupd update` output
-   to make sure kernel modules were successfully rebuilt against the new
-   kernel. This is especially important for systems where a successful boot
-   relies on a kernel module.
-
-Install the :command:`kernel-native-dkms` or :command:`kernel-lts-dkms`
-bundle:
-
-#. Determine which kernel variant is running on |CL|. Only the *native*
-   and *lts* kernels are enabled to build and load out-of-tree kernel modules
-   with DKMS.
-
-   .. code-block:: bash
-
-      $ uname -r
-      5.XX.YY-ZZZZ.native
-
-   Ensure *.native* or *.lts* is in the kernel name.
-
-#. Install the DKMS bundle corresponding to the installed kernel. Use
-   :command:`kernel-native-dkms` for the native kernel or
-   :command:`kernel-lts-dkms` for the lts kernel.
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add kernel-native-dkms
-
-   or
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add kernel-lts-dkms
-
-
-#. Update the |CL| bootloader and reboot.
-
-   .. code-block:: bash
-
-      sudo clr-boot-manager update
-      reboot
-
-.. _kernel-modules-dkms-install-end:
-
-Build, install, and load an out-of-tree module
-**********************************************
-
-Follow the steps in this section if you are an individual user or testing,
-and you need an out-of-tree kernel module that is not available through
-|CL|. For a more scalable and customizable approach, we recommend using
-:ref:`mixer` to provide a custom kernel and updates.
-
-Prerequisites
-=============
-
-Before you begin, you must:
-
-* Disable Secure Boot in UEFI/BIOS. The loading of new out-of-tree modules
-  modifies the signatures that Secure Boot relies on for trust.
-
-* Obtain a kernel module package in the form of source code or
-  pre-compiled binaries.
-
-Obtain kernel module source
-===========================
-
-A required :file:`dkms.conf` file inside of the kernel module's source code
-directory informs DKMS how the kernel module should be compiled.
-
-Kernel modules may come packaged as:
-
-- Source code without a :file:`dkms.conf` file
-- Source code with a premade :file:`dkms.conf` file
-- Source code with a premade :file:`dkms.conf` file and precompiled module
-  binaries
-- Precompiled module binaries only (without source code)
-
-Of the package types listed above, only precompiled kernel module binaries
-will not work, because |CL| requires kernel modules to be built against the
-same kernel source tree before they can be loaded. If you are only able to
-obtain source code without a :file:`dkms.conf` file, you must manually create
-a :file:`dkms.conf` file, described later in this document.
-
-#. Download the kernel module's source code.
-
-   * Review the available download options. Some kernel modules provide
-     separate archives that are specifically enabled for DKMS support.
-
-   * Review the README documentation, because it often provides required
-     information to build the module with DKMS support.
-
-   .. code-block:: bash
-
-      curl -O http://<URL-TO-KERNEL-MODULE-SOURCE>.tar.gz
-      tar -xvf <KERNEL-MODULE-SOURCE>.tar.gz
-      cd <KERNEL-MODULE-SOURCE>/
-      cat README
-
-Build kernel module with an existing dkms.conf
-==============================================
-
-If the kernel module maintainer packaged the source archive with the
-:command:`dkms mktarball` command, the entire archive can be passed to the
-:command:`dkms ldtarball` which completes many steps for you.
-
-The archive contains the required :file:`dkms.conf` file, and may contain
-a :file:`dkms_source_tree` directory and a :file:`dkms_binaries_only`
-directory.
-
-#. Run the :command:`dkms ldtarball` command against the kernel
-   module archive.
-
-   .. code-block:: bash
-
-      dkms ldtarball <KERNEL-MODULE-SOURCE_WITH_DKMS>.tar.gz
-
-
-   :command:`dkms ldtarball` places the kernel module source under
-   :file:`/usr/src/<MODULE-NAME>-<MODULE-VERSION>/`, builds it if necessary,
-   and adds the module into the DKMS tree.
-
-
-#. Verify the kernel module is detected by checking the output of the
-   :command:`dkms status` command.
-
-   .. code-block:: bash
-
-      dkms status
-
-
-#. Install the kernel module.
-
-   .. code-block:: bash
-
-      dkms install -m <MODULE-NAME> -v <MODULE-VERSION>
-
-Build kernel module without an existing dkms.conf
-=================================================
-
-If the kernel module source does not contain a :file:`dkms.conf` file or the
-:command:`dkms ldtarball` command encounters errors, you must manually
-create the file.
-
-Review the kernel module README documentation for guidance on what needs to be
-in the :file:`dkms.conf` file, including special variables that may be
-required to build successfully.
-
-Here are some additional resources that can be used for reference:
-
-* DKMS manual page (:command:`man dkms`) shows detailed syntax in the
-  DKMS.CONF section.
-
-* Ubuntu community wiki entry for the `Kernel DKMS Package`_ shows an example
-  where a single package contains multiple modules.
-
-* Sample `dkms.conf`_ file in the GitHub\* repository for the DKMS project.
-
-.. note::
-
-   :command:`AUTOINSTALL=yes` must be set in the dkms.conf for the module to
-   be automatically recompiled with |CL| updates.
-
-The instructions below show a generic example:
-
-#. Create or modify the :file:`dkms.conf` file inside of the extracted source
-   code directory.
-
-   .. code-block:: bash
-
-      $EDITOR dkms.conf
-
-      MAKE="make -C src/ KERNELDIR=/lib/modules/${kernelver}/build"
-      CLEAN="make -C src/ clean"
-      BUILT_MODULE_NAME=custom_module
-      BUILT_MODULE_LOCATION=src/
-      PACKAGE_NAME=custom_module
-      PACKAGE_VERSION=1.0
-      DEST_MODULE_LOCATION=/kernel/drivers/other
-      AUTOINSTALL=yes
-
-   This example identifies a kernel module named *custom_module* with version
-   *1.0*.
-
-#. Copy the kernel module source code into the :file:`/usr/src/` directory.
-
-   .. code-block:: bash
-
-      sudo mkdir /usr/src/<PACKAGE_NAME>-<PACKAGE_VERSION>
-      sudo cp -Rv . /usr/src/<PACKAGE_NAME>-<PACKAGE_VERSION>
-
-   .. note::
-
-      *<PACKAGE_NAME>* and *<PACKAGE_VERSION>* must match the entries in the
-      :file:`dkms.conf` file.
-
-#. Add the kernel module to the DKMS tree so that it is tracked by DKMS.
-
-   .. code-block:: bash
-
-      sudo dkms add -m <MODULE-NAME>
-
-#. Build the kernel module using DKMS. If the build encounters errors,
-   you may need to edit the :file:`dkms.conf` file.
-
-   .. code-block:: bash
-
-      sudo dkms build -m <MODULE-NAME> -v <MODULE-VERSION>
-
-#. Install the kernel module using DKMS.
-
-   .. code-block:: bash
-
-      sudo dkms install -m <MODULE-NAME> -v <MODULE-VERSION>
-
-Load kernel module
-==================
-
-By default, DKMS installs modules "in-tree" under :file:`/lib/modules` so the
-:command:`modprobe` command can be used to load them.
-
-#. Load the installed module with the :command:`modprobe` command.
-
-    .. code-block:: bash
-
-       sudo modprobe <MODULE-NAME>
-
-#. Validate the kernel module is loaded.
-
-   .. code-block:: bash
-
-      lsmod | grep <MODULE-NAME>
-
-Examples
-********
-
-.. include:: kernel-modules.rst
-   :start-after: kernel-modules-autoload-begin:
-   :end-before: kernel-modules-autoload-end:
-
-Related topics
-**************
-
-* `Dynamic Kernel Module System (DKMS)`_
-
-* `Dell Linux Engineering Dynamic Kernel Module Support: From Theory to Practice <https://www.kernel.org/doc/ols/2004/ols2004v1-pages-187-202.pdf>`_
-
-* `Linux Journal: Exploring Dynamic Kernel Module Support <https://www.linuxjournal.com/article/6896>`_
-
-.. _Dynamic Kernel Module System (DKMS): https://github.com/dell/dkms
-
-.. _Kernel DKMS Package: https://help.ubuntu.com/community/Kernel/DkmsDriverPackage#Configure_DKMS
-
-.. _dkms.conf: https://github.com/dell/dkms/blob/master/sample.conf

_sources/guides/maintenance/assign-static-ip.rst.txt

@@ -1,184 +0,0 @@
-.. _assign-static-ip:
-
-Assign a static IP address
-##########################
-
-
-This guide explains how to assign a static IP address. This may be helpful in
-scenarios such as a network with no DHCP server.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Identify which program is managing the interface
-************************************************
-
-New installations of |CL-ATTR| use NetworkManager as the default network interface
-manager for all network connections.
-
-.. note:: 
-
-   * The cloud |CL| images continue to use `systemd-networkd` to manage
-     network connections.
-
-   * In earlier |CL| versions, `systemd-network` was used to manage Ethernet
-     interfaces and NetworkManager was used for wireless interfaces.
-
-
-Before defining a configuration for assigning a static IP address, verify which
-program is managing the network interface.
-
-#. Check the output of :command:`nmcli device` to see if NetworkManager is
-   managing the device.
-
-   .. code-block:: bash
-
-      nmcli device status
-
-   If the STATE column for the device shows *connected* or *disconnected*, the
-   network configuration is being managed by NetworkManager, then use the
-   instructions for :ref:`using NetworkManager <nm-static-ip>`.
-
-   If the STATE column for the device shows *unmanaged*, then check if the
-   device is being managed by systemd-networkd.
-
-
-#. Check the output of :command:`networkctl list` to see if
-   `systemd-networkd` is managing the device.
-
-   .. code-block:: bash
-
-      networkctl list 
-
-   If the SETUP column for the device shows *configured*, the network
-   configuration is being managed by `systemd-networkd`, then use the
-   instructions for :ref:`using systemd-networkd <networkd-static-ip>`.
-
-
-.. _nm-static-ip:
-
-Using NetworkManager
-********************
-
-Network connections managed by NetworkManager are stored as files with the
-:file:`.nmconnection` file extension in the
-:file:`/etc/NetworkManager/system-connections/` directory.
-
-A few tools exists to aid to manipulate network connections managed by
-NetworkManager:
-
-* nmcli - a command-line tool 
-
-* nmtui - a text user interface that provides a pseudo graphical menu in the
-  terminal
-
-* nm-connection-editor - a graphical user interface
-
-The method below uses the command line tool nmcli to modify network
-connection. 
-
-
-#. Identify the existing connection name:
-
-   .. code:: bash
-
-      nmcli connection show
-
-   Sample output:
-
-   .. code:: bash
-
-      NAME                UUID                                  TYPE            DEVICE 
-      Wired connection 1  00000000-0000-0000-0000-000000000000  802-3-etherneten01
-
-   If a connection does not exist, create it with the
-   :command:`nmcli connection add` command.
-
-
-#. Modify the connection to use a static IP address. Replace the variables in
-   brackets with the appropriate values. Replace *[CONNECTION_NAME]* with the
-   NAME from the command above.
-
-   .. code::
-
-      sudo nmcli connection modify "[CONNECTION_NAME]" \
-      ipv4.method "manual" \
-      ipv4.addresses "[IP_ADDRESS]/[CIDR_NETMASK]" \
-      ipv4.gateway "[GATEWAY_IP_ADDRESS]" \
-      ipv4.dns "[PRIMARY_DNS_IP],[SECONDARY_DNS_IP]"
-
-
-   See the `nmcli developer page <https://developer.gnome.org/NetworkManager/stable/nmcli.html>`_ for more
-   configuration options. For advanced configurations, the
-   :file:`/etc/NetworkManager/system-connections/*.nmconnection`. can be edited
-   directly.
-
-
-#. Restart the NetworkManager server to reload the DNS servers:
-
-   .. code-block:: bash
-
-      sudo systemctl restart NetworkManager
-
-
-#. Verify your static IP address details have been set:
-
-   .. code-block:: bash
-
-      nmcli
-
-
-
-.. _networkd-static-ip:
-
-Using systemd-networkd
-**********************
-
-Network connections managed by systemd-networkd are stored as files with the
-:file:`.network` file extension the :file:`/etc/systemd/network/` directory.
-
-Files to manipulate network connections managed by systemd-networkd must be
-created manually. 
-
-#. Create the :file:`/etc/systemd/network` directory if it does not already exist:
-
-   .. code-block:: bash
-
-      sudo mkdir -p /etc/systemd/network
-
-#. Create a :file:`.network` file and add the following content. Replace the
-   variables in brackets with the appropriate values. Replace *[INTERFACE_NAME]*
-   with LINK from the output of the :command:`networkctl list` command that was
-   run previously.
-
-   .. code-block:: bash
-
-      sudo $EDITOR /etc/systemd/network/70-static.network
-
-      [Match]
-      Name=[INTERFACE_NAME]
-
-      [Network]
-      Address=[IP_ADDRESS]/[CIDR_NETMASK]
-      Gateway=[GATEWAY_IP_ADDRESS]
-      DNS=[PRIMARY_DNS_IP]
-      DNS=[SECONDARY_DNS_IP]
-
-   See the `systemd-network man page
-   <https://www.freedesktop.org/software/systemd/man/systemd.network.html>`_
-   for more configuration options.
-
-#. Restart the `systemd-networkd` service:
-
-   .. code-block:: bash
-
-      sudo systemctl restart systemd-networkd
-
-
-#. Verify your static IP address details have been set:
-
-   .. code-block:: bash
-
-      networkctl status
-

_sources/guides/maintenance/cpu-performance.rst.txt

@@ -1,208 +0,0 @@
-.. _cpu-performance:
-
-CPU Power and Performance
-#########################
-
-This guide explains the CPU power and performance mechanisms in |CL-ATTR|.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-Modern x86 :abbr:`CPUs (central processing units)` employ a number of features
-and technologies to balance performance, energy, and thermal efficiencies.
-
-By default, |CL| prioritizes maximum CPU performance with the philosophy that
-the faster the program finishes execution, the faster the CPU can return to a
-low energy idle state. It is important to understand and evaluate all of these
-technologies when troubleshooting or considering changing the defaults.
-
-.. contents::
-   :local:
-   :depth: 1
-
-CPU power saving mechanisms
-***************************
-
-C-states and P-states are both CPU power saving mechanisms that are entered
-under different operating conditions. The tradeoff is a slightly longer time
-to exit these states when the CPU is needed once again.
-
-.. _c-states-section:
-
-C-states (idle states)
-======================
-
-C-states are hardware sleep states that are entered when it is determined that
-the CPU is idle and not executing instructions.
-
-C-states aim to reduce power utilization by increasingly reducing clock
-frequency, voltages, and features in each state.
-
-Although C-states can typically be limited or disabled in a system's UEFI or
-BIOS configuration, these settings are overridden when the `intel_idle driver`_
-is in use.
-
-To view the current cpuidle driver run this command in a terminal:
-
-.. code:: bash
-
-   cat /sys/devices/system/cpu/cpuidle/current_driver
-
-For troubleshooting, C-states can be limited with a kernel command line boot
-parameter by adding :command:`processor.max_cstate=N intel_idle.max_cstate=N`
-or completely disabled with :command:`idle=poll`.
-
-.. note::
-
-   * :command:`processor.max_cstate=0` is changed to :command:`processor.max_cstate=1`
-     by the kernel to be a valid value.
-
-   * :command:`intel_idle.max_cstate=0` disables the Intel Idle driver, not set
-     it to C-state 0.
-
-.. _p-states-section:
-
-P-states (performance states)
-=============================
-
-P-states, also known as *Intel SpeedStep® technology* on Intel processors or
-*Cool'n'Quiet* on AMD processors, are states entered while the CPU is active and
-executing instructions.
-
-P-states aim to reduce power utilization by adjusting CPU clock frequency and
-voltages based on CPU demand.
-
-P-states can typically be limited or disabled in a system's firmware (UEFI/BIOS).
-
-Turbo boost
------------
-
-`Intel® Turbo Boost Technology`_, found on some modern Intel CPUs, allows core(s) on
-a processor to temporarily operate at a higher than rated CPU clock frequency
-to accommodate demanding workloads if the CPU is under defined power and
-thermal thresholds.
-
-Turbo boost is an extension of P-states. As such, changing or limiting
-C-states or P-states impact the ability of a process to enter Turbo boost.
-
-Turbo boost can be disabled in a system's UEFI or BIOS. Turbo boost can also
-be disabled within |CL| with the command:
-
-.. code:: bash
-
-   echo 1 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo
-
-Linux CPU clock frequency scaling
-*********************************
-
-The CPUFreq subsystem in Linux allows the OS to control :ref:`C-states
-<c-states-section>` and :ref:`P-states <P-states-section>`
-via CPU drivers and governors that provide algorithms that define how and when
-to enter these states.
-
-Scaling driver
-==============
-
-Linux uses the `Intel P-state driver`_, :command:`intel_pstate`, for modern Intel
-processors from the Sandy Bridge generation or newer. Other processors may
-default to the :command:`acpi-cpufreq*` driver which reads values from the systems
-UEFI or BIOS.
-
-To view the current CPU frequency scaling driver run this command in a terminal:
-
-.. code:: bash
-
-   cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_driver
-
-Scaling governor
-================
-
-|CL| sets the CPU governor to *performance* which calls for the CPU to operate
-at maximum clock frequency. In other words, P-state P0. While this may sound
-wasteful at first, it is important to remember that power utilization does not
-increase significantly simply because of a locked clock frequency without a
-workload.
-
-To view the current CPU frequency scaling governor run this command in a terminal:
-
-.. code:: bash
-
-   cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
-
-To change the CPU frequency scaling governor:
-
-#. Disable |CL| enforcement of certain power and performance settings:
-
-   .. code:: bash
-
-      sudo systemctl mask clr-power.timer
-
-#. Change the governor. In the example below, the governor is set to
-   *performance*:
-
-   .. code:: bash
-
-      echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
-
-The list of all governors can be found in the Linux kernel documentation on
-`CPUFreq Governors`_.
-
-.. note::
-
-   The intel_pstate driver only supports *performance* and *powersave* governors.
-
-Thermal management
-******************
-
-`thermald`_ is a Linux thermal management daemon used to prevent the
-overheating of platforms. When temperature thresholds are exceeded, thermald
-forces a C-state by inserting CPU sleep cycles and adjusts available cooling
-methods. This can be especially desirable for laptops.
-
-By default, thermald is disabled in |CL| and starts automatically if battery
-power is detected. thermald can be manually enabled using the systemd service
-by running the command:
-
-.. code:: bash
-
-   sudo systemctl enable thermald
-   sudo systemctl start thermald
-
-For more information, see the thermald man page:
-
-.. code:: bash
-
-   man thermald
-
-`ThermalMonitor`_ is a GUI application that can visually graph and log
-temperatures from thermald. To use ThermalMonitor, add the
-:command:`desktop-apps-extras` bundle and add your user account to the power
-group:
-
-.. code:: bash
-
-   sudo swupd bundle-add desktop-apps-extras
-   sudo usermod -a -G power <USER>
-   ThermalMonitor
-
-.. note::
-
-   After adding a new group, you must log out and log back in for the new group
-   to take effect.
-
-
-.. _`Intel P-state driver`: https://www.kernel.org/doc/Documentation/cpu-freq/intel-pstate.txt
-
-.. _`CPUFreq Governors`: https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt
-
-.. _thermald: https://01.org/linux-thermal-daemon
-
-.. _`intel_idle driver`: https://github.com/torvalds/linux/blob/master/drivers/idle/intel_idle.c
-
-.. _`ThermalMonitor`: https://github.com/intel/thermal_daemon/tree/master/tools/thermal_monitor
-
-.. _`Intel® Turbo Boost Technology`: https://www.intel.com/content/www/us/en/architecture-and-technology/turbo-boost/turbo-boost-technology.html

_sources/guides/maintenance/download-verify-decompress.rst.txt

@@ -1,176 +0,0 @@
-.. _download-verify-decompress:
-
-Download, verify, and decompress a |CL-ATTR| image
-##################################################
-
-This guide describes the available types of |CL| images, where to
-download them, how to verify their integrity, and how to decompress them.
-Follow the steps for your OS.
-
-.. contents::
-   :local:
-   :depth: 1
-
-
-.. include:: ../../reference/image-types.rst
-   :start-after: image-types-content:
-   :end-before: incl-image-filename-end:
-
-.. _download-verify-decompress-linux:
-
-Linux OS steps
-**************
-
-.. _verify-linux:
-
-Verify the integrity of the |CL| image
-======================================
-
-Before you use a downloaded |CL| image, verify its integrity. This action
-eliminates the small chance of a corrupted image due to download issues. To
-support verification, each released |CL| image has a corresponding SHA512
-checksum file designated with the suffix `-SHA512SUMS`.
-
-#.  Download the corresponding SHA512 checksum file of your |CL| `image`_.
-#.  Open a Terminal.
-#.  Go to the directory with the downloaded image and checksum files.
-#.  Verify the integrity of the image and compare it to its original checksum
-    with the command:
-
-    .. code-block:: bash
-
-        sha512sum -c ./clear-[version number]-[image type].[compression type]-SHA512SUMS
-
-If the checksum of the downloaded image is different than the original
-checksum, a warning is displayed with a message indicating the computed
-checksum does **not** match. Otherwise, the name of the image is printed on
-the screen followed by `OK`.
-
-For a more in-depth discussion of image verification including checking the
-certificate see :ref:`image-content-validation`.
-
-.. incl-decompress-image:
-
-Decompress the |CL| image
-=========================
-
-Released |CL| images are compressed with either GNU zip (*.gz*) or XZ
-(*.xz*). The compression type depends on the target platform or
-environment. To decompress the image, follow these steps:
-
-#.  Open a Terminal.
-#.  Go to the directory with the downloaded image.
-
-    To decompress an XZ image, enter:
-
-    .. code-block:: bash
-
-        unxz clear-[version number]-[image type].xz
-
-    To decompress a GZ image, enter:
-
-    .. code-block:: bash
-
-        gunzip clear-[version number]-[image type].gz
-
-.. incl-decompress-image-end:
-
-.. _download-verify-decompress-mac:
-
-macOS\* steps
-*************
-
-.. _verify-mac:
-
-Verify the integrity of the |CL| image
-======================================
-
-Before you use a downloaded |CL| image, verify its integrity. This action
-eliminates the small chance of a corrupted image due to download issues. To
-support verification, each released |CL| image has a corresponding SHA512
-checksum file designated with the suffix `-SHA512SUMS`.
-
-#. Download the corresponding SHA512 checksum file of your |CL| `image`_.
-#. Open a Terminal.
-#. Go to the directory with the downloaded image and checksum files.
-#. Verify the integrity of the image and compare it to its original checksum
-   with the command:
-
-   .. code-block:: bash
-
-      shasum -a512 clear-[version number]-[image type].[compression type] | diff clear-[version number]-[image type].[compression type]-SHA512SUMS -
-
-If the checksum of the downloaded image is different than the original
-checksum, the differences will be displayed. Otherwise, an empty output indicates
-a match and your downloaded image is good.
-
-Decompress the |CL| image
-=========================
-
-We compress all released |CL| images by default with either GNU zip
-(`.gz`) or xz (`.xz`). The compression type we use depends on the target
-platform or environment. To decompress the image, follow these steps:
-
-#. Open a Terminal.
-#. Go to the directory with the downloaded image.
-#. Use the :command:`gunzip` command to decompress either compression type. For example:
-
-   .. code-block:: bash
-
-      gunzip clear-[version number]-[image type].xz
-      gunzip clear-[version number]-[image type].gz
-
-.. _download-verify-decompress-windows:
-
-Windows\* OS steps
-******************
-
-.. _verify-windows:
-
-Verify the integrity of the |CL| image
-======================================
-
-Before you use a downloaded |CL| image, verify its integrity. This action
-eliminates the small chance of a corrupted image due to download issues. To
-support verification, each released |CL| image has a corresponding SHA512
-checksum file designated with the suffix `-SHA512SUMS`.
-
-#.  Download the corresponding SHA512 checksum file of your |CL| `image`_.
-#.  Start Command Prompt.
-#.  Go to the directory with the downloaded image and checksum files.
-#.  Get the SHA512 checksum of the image with the command:
-
-    .. code-block:: bash
-
-        CertUtil -hashfile ./clear-[version number]-[image type].[compression type] sha512
-
-#.  Manually compare the output with the original checksum value shown in
-    the downloaded checksum file and make sure they match.
-
-Decompress the |CL| image
-=========================
-
-Released |CL| images are compressed with either GNU zip (*.gz*) or XZ
-(*.xz*). The compression type depends on the target platform or
-environment. To decompress the image, follow these steps:
-
-#. Download and install `7-Zip`_.
-#. Go to the directory with the downloaded image and right-click it.
-#. From the pop-up menu, select :guilabel:`7-Zip` and select
-   :guilabel:`Extract Here` as shown in Figure 1.
-
-   .. figure:: figures/download-verify-decompress-windows-fig-1.png
-      :scale: 80 %
-      :alt: 7-Zip extract file
-
-      Figure 1: Windows 7-Zip extract file.
-
-.. _7-Zip: http://www.7-zip.org/
-
-Image types
-***********
-
-.. include:: ../../reference/image-types.rst
-   :start-after: incl-image-filename-end:
-
-.. _image: https://clearlinux.org/downloads

_sources/guides/maintenance/enable-user-space.rst.txt

@@ -1,103 +0,0 @@
-.. _enable-user-space:
-
-Create and enable a new user space
-##################################
-
-This guide provides steps to complete the following basic setup tasks for
-a newly installed |CL-ATTR| system:
-
-.. contents::
-   :local:
-   :depth: 1
-
-Create a new user
-*****************
-
-To create a new user and set a password for that user, enter the following
-commands as a root user:
-
-.. code-block:: bash
-
-   useradd <userid>
-   passwd <userid>
-
-Replace the <userid> with the name of the user account you want to create
-including the password for that user. The :command:`passwd` command prompts
-you to enter a new password. Retype the new password for the new user
-account just created.
-
-Add the new user to the *wheel* group
-*************************************
-
-Before logging off as root and logging into your new user account,
-enable the :command:`sudo` command for your new <userid>.
-
-To be able to execute all applications with root privileges, add the
-<userid> to the `wheel group`_.
-
-#. Add <userid> to the wheel group:
-
-   .. code-block:: bash
-
-      usermod -G wheel -a <userid>
-
-#. Log out of root and into the new <userid>.
-
-   To log off as root, enter :command:`exit`.
-
-#. Enter the new <userid> and the password created earlier.
-
-   You will now be in the home directory of <userid>.
-
-Install and update the OS software to its current version
-*********************************************************
-
-The |CL| software utility :ref:`swupd <swupd-guide>` allows you to perform
-system updates while reaping the benefits of upstream development.
-
-To update your newly installed OS, run:
-
-.. code-block:: bash
-
-   sudo swupd update
-
-Add a bundle
-************
-
-Software applications are installed as bundles using the command
-:command:`swupd bundle-add`. Experienced Linux users might compare swupd
-to running :command:`apt-get` or :command:`yum install` for package
-management. However |CL| manages packages at the level of bundles, which
-are integrated stacks of packages.
-
-For example, the :command:`sysadmin-basic` bundle installs the majority of
-applications useful to a system administrator. To install it, enter:
-
-.. code-block:: bash
-
-   swupd bundle-add sysadmin-basic
-
-View a full list of bundles and packages installed with the `sysadmin-basic`_
-bundle. You can also view all `bundles`_ for |CL|, active or deprecated.
-
-Expand your knowledge of :command:`swupd` and check out our developer resources:
-
-* :ref:`swupd-guide`
-* :ref:`developer-workstation`
-
-Next steps
-**********
-
-Check out our guides and tutorials.
-
-* :ref:`guides`
-* :ref:`tutorials`
-
-.. _`sysadmin-basic`:
-   https://github.com/clearlinux/clr-bundles/blob/master/bundles/sysadmin-basic
-
-.. _`bundles`:
-   https://github.com/clearlinux/clr-bundles/tree/master/bundles
-
-.. _`wheel group`:
-   https://en.wikipedia.org/wiki/Wheel_(Unix_term)

_sources/guides/maintenance/fix-broken-install.rst.txt

@@ -1,91 +0,0 @@
-.. _fix-broken-install:
-
-Fix a broken installation
-#########################
-
-This guide explains how to fix a broken installation of |CL-ATTR| using a live
-desktop image on a USB.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-This guide assumes you have installed |CL| on a target system, but the OS
-does not boot or function properly.
-
-The process described in this guide can only verify and fix files that
-:ref:`swupd<swupd-guide>` owns in :file:`/usr`. Files outside of this path, such
-as :file:`/home/`, :file:`/etc`, :file:`/var`, etc., cannot be repaired by this
-process.
-
-Prerequisites
-*************
-
-* Download and install the live desktop image on a USB. See
-  :ref:`bare-metal-install-desktop` for install instructions.
-
-Boot a live desktop image to fix target system
-**********************************************
-
-#. Boot the |CL| live desktop image.
-
-.. include:: ../../get-started/bare-metal-install-desktop/bare-metal-install-desktop.rst
-   :start-after: install-on-target-start:
-   :end-before: install-on-target-end:
-
-Mount root partition, verify, and fix
-*************************************
-
-#. Open a Terminal window.
-
-#. Ensure the system is connected to the network.
-
-#. Mount the system’s root partition.
-
-   #. To find the root partition, run:
-
-      .. code-block:: bash
-
-         lsblk
-
-      We'll use :file:`/dev/sda3/` as the root partition example.
-
-   #. Next, mount the partition to the :file:`/mnt` folder.
-
-      .. code-block:: bash
-
-         sudo mount /dev/sda3 /mnt
-
-#. Verify that you mounted the correct root partition by checking for some
-   files commonly found on |CL| systems.
-
-   .. code-block:: bash
-
-      cat /mnt/usr/lib/os-release
-      ls /mnt/usr/share/clear/bundles
-
-#. Next, run swupd to fix any issues on the target system.
-
-   .. code-block:: bash
-
-      sudo swupd repair --picky --path=/mnt
-
-   :ref:`Learn more about how swupd works <swupd-guide>`.
-
-#. After the process is complete, unmount the root partition:
-
-   .. code-block:: bash
-
-      sudo umount /mnt
-
-#. Reboot the system, remove the live desktop USB drive,
-   and boot into the repaired system.
-
-   .. code-block:: bash
-
-      sudo reboot
-
-**Congratulations!** You successfully restored |CL|.

_sources/guides/maintenance/hostname.rst.txt

@@ -1,81 +0,0 @@
-.. _hostname:
-
-Modify hostname
-###############
-
-This guide describes how to modify and view the hostname of your |CL-ATTR|
-system.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-By default, |CL| installations have a machine generated name, which is a
-long string of letters and numbers. The generated name is fine for computers
-but is not human-friendly. Administrators and users will often want to rename
-their machines with a name that is easier to remember, type, and search
-for. Renaming a machine also makes it easier to identify, by including
-meaningful data in the name.  The following examples show human-friendly machine
-names:
-
-* *regression-test*
-* *sally-test-box1*
-* *az-bldg2-lab*
-
-Set your hostname
-*****************
-
-|CL| uses the :command:`hostnamectl` command to display and modify the machine
-name. :command:`hostnamectl` is part of the :command:`os-core` bundle, which
-provides a basic Linux\* user space and utilities.
-
-This example sets the hostname to *telemetry-test-2-h15*, to identify a
-|CL| telemetry test machine on the second floor at grid location H15.
-Make sure to reboot after setting a new hostname.
-
-.. code-block:: bash
-
-   sudo hostnamectl set-hostname telemetry-test-2-h15
-   sudo reboot
-
-.. note::
-
-   There are three types of hostname: *static*, *transient*, and *pretty*.
-   The most common is the static hostname. Static hostnames must be between
-   two and 63 characters long, must start and end with a letter or number,
-   and may contain letters (case-insensitive), numbers, dashes, or dots.
-
-   If the static hostname exists, it is used to generate the transient hostname,
-   which is maintained by the kernel. The transient hostname can be changed
-   by DHCP or mDNS at runtime.
-
-   The pretty hostname is a free-form UTF8 name used for presentation to the user.
-
-View your hostname
-******************
-
-View your current hostname using the following command:
-
-.. code-block:: bash
-
-   hostnamectl
-
-You should see output similar to:
-
-.. code-block:: console
-
-   Static hostname   : telemetry-test-2-h15
-   Pretty hostname   : telemetry-test-2-h15
-   Icon name         : computer-desktop
-   Chassis           : desktop
-   Machine ID        : 4d0d60207a904ebbab96680a51ac1339
-   Boot ID           : 98d3514e5a984e8cbbdf46a2f0d6b397
-   Operating System  : Clear Linux OS
-   Kernel            : Linux 4.18.8-632.native
-   Architecture      : x86-64
-
-
-**Congratulations!** You successfully modified the hostname of your |CL| system.

_sources/guides/maintenance/increase-virtual-disk-size.rst.txt

@@ -1,174 +0,0 @@
-.. _increase-virtual-disk-size:
-
-Increase virtual disk size of an image
-######################################
-
-This guide describes how to increase the disk size of your prebuilt |CL-ATTR|
-image if you need more capacity.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Determine the partition order and sizes of the prebuilt image
-*************************************************************
-
-|CL| prebuilt images come in different sizes, ranging from 300 MB to 20
-GB.
-
-There are two methods to find the order and sizes of partitions virtual disk
-of your prebuilt |CL| image.
-
-In both examples, the prebuilt Hyper-V image has a disk size of 8.5 GB with
-:file:`/dev/sda3` being the partition for the root filesystem (/)
-
-Checking :command:`lsblk` on the VM
-===================================
-
-The first method is to boot up your :abbr:`VM (Virtual Machine)` and
-execute the :command:`lsblk` command as shown below:
-
-.. code-block:: bash
-
-   sudo lsblk
-
-An example output of the :command:`lsblk` command:
-
-.. code-block:: console
-
-   NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
-   sda      8:0   0    8.5G  0 disk
-   ├─sda1   8:1   0    512M  0 part
-   ├─sda2   8:2   0     32M  0 part [SWAP]
-   └─sda3   8:3   0      8G  0 part /
-
-An example of this can also be seen in Figure 1.
-
-Checking :file:`config.json` used to build the image
-====================================================
-
-The second method to determine partition to check the :file:`config.json`
-file used to create prebuilt image, located in the `releases`_ repository.
-For example, to find the size of the Hyper-V\* image version number 20450,
-follow these steps:
-
-#. Go to the `releases`_ repository.
-#. Drill down into the `20450 > clear > config > image` directory.
-#. Open the :file:`hyperv-config.json` file.
-#. Locate the `PartitionLayout` key.
-
-   The example shows 512 MB for the EFI partition, 32 MB for the swap
-   partition, and 8 GB for the root partition.
-
-
-   .. code-block:: console
-
-      "PartitionLayout" : [ { "disk" : "hyperv.img",
-                              "partition" : 1,
-                              "size" : "512M",
-                              "type" : "EFI" },
-                              { "disk" : "hyperv.img",
-                              "partition" : 2,
-                              "size" : "32M",
-                              "type" : "swap" },
-                              { "disk" : "hyperv.img",
-                              "partition" : 3,
-                              "size" : "8G",
-                              "type" : "linux" } ],
-
-Increase virtual disk size
-**************************
-Once you have determined the disk and partition to be increased, you are
-ready to perform the actual increase of the disk, partition, and filesystem.
-
-Power off VM and increase virtual disk size
-===========================================
-
-To increase the virtual disk size for a prebuilt image, perform the steps
-below:
-
-#. Shut down your VM if it is running.
-#. Use the process defined by your hypervisor  or cloud provider to increase
-   the virtual disk size of your |CL| VM.
-#. Power up the VM.
-
-
-Resize the partition of the virtual disk
-========================================
-
-#. Log in to an account with root privileges.
-#. Open a terminal emulator.
-#. Add the :command:`storage-utils` bundle to install the
-   :command:`parted` and :command:`resize2fs` tools.
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add storage-utils
-
-#. Launch the `parted` tool.
-
-   .. code-block:: bash
-
-      sudo parted
-
-#. In the `parted` tool, perform these steps:
-
-   #. Press :command:`p` to print the partitions table.
-   #. If the warning message below is displayed, enter :command:`Fix`.
-
-      .. code-block:: console
-
-         Warning: Not all of the space available to :file:`/dev/sda` appears to be
-         used, you can fix the GPT to use all of the space (an extra ...
-         blocks) or continue with the current setting?
-
-         Fix/Ignore?
-
-   #. Enter :command:`resizepart [partition number]` where
-      *[partition number]* is the partition number of the partition to modify.
-   #. Enter :command:`yes` when prompted.
-   #. Enter the new End size.
-
-      .. note::
-
-         If you want a partition to take up the remaining disk space, then
-         enter the total size of the disk. When you print the partitions
-         table with the :command:`p` command, the total disk size is shown
-         after the :guilabel:`Disk` label.
-
-         An example of this can be seen in Figure 1.
-
-   #. Enter :command:`q` to exit `parted` when you are finished resizing the
-      image.
-
-      Figure 1 depicts the described steps  to resize the partition of the virtual disk from 8.5GB to 20GB.
-
-      .. figure:: figures/increase-virtual-disk-size-1.png
-         :scale: 100 %
-         :alt: Increase root partition size
-
-         Figure 1: Increase root partition size.
-
-Resize the filesystem
-=====================
-
-#. Enter :command:`sudo resize2fs -p /dev/[modified partition name]` where
-   *[modified partition name]* is the partition that was changed in the `parted`
-   tool.
-
-#. Run the :command:`df -h` to verify that the filesystem size has
-   increased.
-
-   Figure 2 depicts the described steps to resize the partition of the virtual
-   disk from 8.5GB to 20GB.
-
-   .. figure:: figures/increase-virtual-disk-size-2.png
-      :scale: 100 %
-      :alt: Increase root filesystem with resize2fs
-
-      Figure 2: Increase root filesystem size after partition has been expanded.
-
-**Congratulations!** You have resized the disk, partition, and filesystem. At
-this point, the increase in disk capacity is usable.
-
-.. _releases: https://cdn.download.clearlinux.org/releases/

_sources/guides/maintenance/query-upstream.rst.txt

@@ -1,226 +0,0 @@
-.. _query-upstream:
-
-Query package info from upstream repository
-###########################################
-
-This guide describes how to query package information from the |CL| upstream
-repositories. This guide is intended for developers and advanced users.
-
-.. contents::
-   :local:
-   :depth: 1
-   :backlinks: top
-
-Overview
-********
-
-In |CL-ATTR|, the :ref:`swupd<swupd-guide>` tool manages software
-dependencies and installs bundles instead of packages. Although a bundle is
-a collection of one or more packages, |CL| does not work with packages on
-the client side. However, on the upstream/factory side, |CL| does work with
-packages using a process called *mixing*.
-
-Currently, :command:`swupd` does not report which packages are installed,
-provide package version information, or return other package details. This
-guide describes a method for retrieving package information from the |CL|
-upstream repositories using :abbr:`DNF(Dandified Yum)` commands.
-
-Prerequisites
-*************
-
-This guide assumes you have installed |CL| on your host system.
-For detailed instructions on installing |CL| on a bare metal system, visit
-the :ref:`bare metal installation guide <bare-metal-install-desktop>`.
-
-Before you install any new packages, update |CL| with the following command:
-
-.. code-block:: bash
-
-   sudo swupd update
-
-Configure DNF
-*************
-
-#. Install the DNF bundle with the command:
-
-   .. code-block:: bash
-
-	  sudo swupd bundle-add dnf
-
-#. Create a :file:`dnf.conf` file with the commands:
-
-   .. code-block:: bash
-
-	  sudo mkdir -p /etc/dnf
-	  sudo curl -L https://github.com/clearlinux/common/raw/master/conf/dnf.conf --output /etc/dnf/dnf.conf
-
-
-#. Edit the :file:`/etc/dnf/dnf.conf` file and set the **baseurl** variable
-   for binary and source RPMs as shown in lines 3 and 9 in the following
-   example.
-
-   .. code-block:: bash
-	  :linenos:
-	  :emphasize-lines: 3,9
-
-	  [clear]
-	  name=Clear
-	  baseurl=https://cdn.download.clearlinux.org/releases/$releasever/clear/x86_64/os/
-	  enabled=1
-	  gpgcheck=0
-	  [clear-source]
-	  name=Clear sources
-	  failovermethod=priority
-	  baseurl=https://cdn.download.clearlinux.org/releases/$releasever/clear/source/SRPMS/
-	  enabled=1
-	  gpgcheck=0
-
-#. Initialize the RPM database with the command:
-
-   .. code-block:: bash
-
-	  sudo rpm --initdb
-
-
-DNF command usage examples
-**************************
-
-.. contents:: :local:
-   :depth: 1
-   :backlinks: top
-
-List all binary and source RPMs in the current release
-======================================================
-
-Command:
-
-.. code-block:: bash
-
-	dnf repoquery --releasever=current
-
-Sample output:
-
-.. code-block:: console
-
-   Clear                                    5.1	MB/s |  13 MB     00:02
-   Clear sources                            1.8	MB/s | 1.7 MB     00:00
-   AVB-AudioModules-0:4.1.0-1.src
-   AVB-AudioModules-0:4.1.0-1.x86_64
-   AVB-AudioModules-data-0:4.1.0-1.x86_64
-   AVB-AudioModules-dev-0:4.1.0-1.x86_64
-   AVB-AudioModules-lib-0:4.1.0-1.x86_64
-   AVB-AudioModules-license-0:4.1.0-1.x86_64
-   AVBStreamHandler-0:1.1.0-21.src
-   AVBStreamHandler-0:1.1.0-21.x86_64
-   AVBStreamHandler-abi-0:1.1.0-21.x86_64
-   AVBStreamHandler-bin-0:1.1.0-21.x86_64
-   AVBStreamHandler-data-0:1.1.0-21.x86_64
-   AVBStreamHandler-dev-0:1.1.0-21.x86_64
-   AVBStreamHandler-lib-0:1.1.0-21.x86_64
-   AVBStreamHandler-license-0:1.1.0-21.x86_64
-   ...
-   <trimmed>
-
-Show version information for a package in current release
-=========================================================
-
-This example queries version information for the zstd package.
-
-Command:
-
-.. code-block:: bash
-
-   dnf repoquery --releasever=current zstd
-
-Sample output:
-
-.. code-block:: console
-
-	Last metadata expiration check: 0:02:30 ago on Tue 16 Jul 2019 03:03:34 PM PDT.
-	zstd-0:1.4.0-46.src
-	zstd-0:1.4.0-46.x86_64
-
-
-Show version information for a package in a specific release
-============================================================
-
-This example queries version information for the zstd package in release
-21000.
-
-Command:
-
-.. code-block:: bash
-
-   dnf repoquery --releasever=21000 zstd
-
-Sample output:
-
-.. code-block:: console
-
-   Clear
-   2.7 MB/s | 3.9 MB     00:01
-   Clear sources
-   628 kB/s | 559 kB     00:00
-   zstd-0:1.3.3-20.src
-   zstd-0:1.3.3-20.x86_64
-
-Show only version and release information for a package in a specific release
-=============================================================================
-
-This example queries version and release information for the zstd package in
-release 15000.
-
-Command:
-
-.. code-block:: bash
-
-   dnf repoquery --releasever=15000 --qf="%{VERSION}\n%{RELEASE}" zstd
-
-Sample output:
-
-.. code-block:: console
-
-   Clear
-   3.4 MB/s | 3.9 MB     00:01
-   Clear sources
-   345 kB/s | 528 kB     00:01
-   1.1.4
-   5
-
-Show the binary package for a specified binary file
-===================================================
-
-This example returns the binary package that contains the
-:file:`/usr/bin/zip` binary file.
-
-Command:
-
-.. code-block:: bash
-
-   dnf repoquery --releasever=current --whatprovides /usr/bin/zip
-
-Sample output:
-
-.. code-block:: console
-
-   Last metadata expiration check: 0:04:47 ago on Tue 16 Jul 2019 03:03:34 PM PDT.
-   zip-bin-0:3.0-23.x86_64
-
-Show the source package for a specified binary file
-===================================================
-
-This example returns the source package that contains the
-:file:`/usr/bin/zip` binary file.
-
-Command:
-
-.. code-block:: bash
-
-   dnf repoquery --releasever=current --whatprovides /usr/bin/zip --srpm
-
-Sample output:
-
-.. code-block:: console
-
-   Last metadata expiration check: 0:05:50 ago on Tue 16 Jul 2019 03:03:34 PM PDT.
-   zip-0:3.0-23.src

_sources/guides/maintenance/resource-limits.rst.txt

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

_sources/guides/maintenance/restart.rst.txt

@@ -1,164 +0,0 @@
-.. _restart:
-
-Restart system services after an OS update
-##########################################
-
-This guide describes how to use the :command:`clr-service-restart` tool.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-|CL-ATTR| includes a :command:`clr-service-restart` tool that shows which
-system daemons require a restart.
-
-:command:`clr-service-restart` reads various files in the :file:`procfs`
-filesystem provided by the kernel and relies on :command:`systemd` to
-determine which services to restart.
-
-
-How it works
-************
-
-:command:`clr-service-restart` implements a whitelist to identify which
-daemons can be restarted. As a system administrator, you can customize the
-default |CL| OS whitelist using :command:`allow` or :command:`disallow` options
-for restarting system services. When a software update occurs,
-:command:`clr-service-restart` consults the whitelist to see if a service daemon
-is allowed to be restarted or not.
-
-
-Basic options
-*************
-
-:command:`clr-service-restart` has three basic options: :command:`allow`,
-:command:`disallow`, and :command:`default`.
-
-allow
-=====
-
-The :command:`allow` option identifies a daemon to restart after an OS software
-update. The :command:`clr-service-restart` daemon creates a symlink in
-:file:`/etc/clr-service-restart` as a record. The example below tells
-:command:`clr-service-restart` to restart the *tallow* daemon after an
-OS software update.
-
-.. code-block:: bash
-
-   sudo clr-service-restart allow tallow.service
-
-disallow
-========
-
-The :command:`disallow` option tells :command:`clr-service-restart` not to
-restart the specified daemon even if the OS defaults permit the daemon to be
-restarted. The :command:`clr-service-restart` daemon creates a symlink in
-:file:`/etc/clr-service-restart` that points to :file:`/dev/null` as a
-record. The example below tells :command:`clr-service-restart` not to
-restart the *rngd* daemon after an OS software update.
-
-.. code-block:: bash
-
-   sudo clr-service-restart disallow rngd
-
-default
-=======
-
-The :command:`default` option makes :command:`clr-service-restart` revert back
-to the OS defaults and delete any symlink  in :file:`/etc/clr-service-restart`.
-The example below  tells :command:`clr-service-restart` to restart *rngd*
-automatically again, because *rngd* is whitelisted for automatic service
-restarts by default in |CL|.
-
-.. code-block:: bash
-
-   sudo clr-service-restart default rngd
-
-Monitor options
-***************
-
-:command:`clr-service-restart` works in the background and is invoked with
-:command:`swupd` automatically. Review the journal output to verify that
-services are restarted after an OS software update.
-
-If you pass both options (:command:`-a` and :command:`-n`) described below,
-:command:`clr-service-restart` displays a complete list of system services
-that require a restart. Use both options to verify that all desired daemons
-are restarted.
-
-
--n option
-=========
-
-The :command:`-n` option makes :command:`clr-service-restart` perform no restarts.
-Instead it displays the services that could potentially be restarted. When used,
-:command:`clr-service-restart` outputs a list of messages showing:
-
-* Which service needs a restart.
-* What unit it is.
-* Why it needs a restart.
-* Which command is required to restart the unit.
-
--a option
-=========
-
-The :command:`-a` option makes :command:`clr-service-restart` consider all system
-services, not only the ones that are whitelisted. Because the default whitelist
-in |CL| is relatively short, you can use this option to restart all impacted
-services when you log in on the system.
-
-Example
-*******
-
-In the example below, :command:`clr-service-restart` is invoked with both the
-:command:`-a` and :command:`-n` options, which displays a complete list of system
-services that require a restart.
-
-Command:
-
-.. code-block:: bash
-
-     sudo clr-service-restart -a -n
-
-Sample output:
-
-.. code-block:: console
-
-     upower.service: needs a restart (a library dependency was updated)
-     /usr/bin/systemctl --no-ask-password try-restart upower.service
-     NetworkManager.service: needs a restart (a library dependency was
-     updated)
-     /usr/bin/systemctl --no-ask-password try-restart NetworkManager.service
-     ....
-
-Telemetry
-*********
-
-:command:`clr-service-restart` may cause problems such as a short service
-outage when a daemon is being restarted, or if a daemon fails to properly
-restart. To minimize issues, :command:`clr-service-restart` creates a
-telemetry record and sends it to the optional |CL| telemetry service if both
-conditions below are met:
-
-* If a unit fails to automatically restart after an OS update.
-* If that unit resides in the system location :file:`/usr/lib/systemd/system`.
-
-If you do not install the |CL| telemetrics bundle, the data is discarded. If
-you install the telemetrics bundle and you opt to send telemetry, then the
-system unit name is sent to the |CL| telemetry service. We evaluate the
-report and update the whitelist to remove services that are not safe to
-restart.
-
-
-Conclusion
-**********
-
-The |CL| team enjoys coming up with simple and efficient solutions to make
-your work easier. We made a GitHub\* project of :command:`clr-service-restart`
-and we invite you to look at the code, share your thoughts, and work with us
-on improving the project. You can find the project at:
-
-https://github.com/clearlinux/clr-service-restart

_sources/guides/maintenance/validate-signatures.rst.txt

@@ -1,139 +0,0 @@
-.. _validate-signatures:
-
-Validate signatures
-###################
-
-
-This guide describes how to validate the contents of a |CL-ATTR| image.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-Validating the contents of an image is a manual process and is the same process
-that :ref:`swupd-guide` performs internally.
-
-|CL| offers a way to validate the content of an image or an update. All
-validation of content works by creating and signing a hash. A valid signature
-creates a chain of trust. A broken chain of trust, seen as an invalid
-signature, means the content is not valid.
-
-
-.. _image-content-validation:
-
-Image content validation
-************************
-
-In the steps below, we used the installer image of the latest release
-of |CL|. You may use any image of |CL| you choose.
-
-#. Download the image, the signature of the SHA512 sum of the image, and the
-   |CL| certificate used for signing the SHA512 sum.
-
-   .. code-block:: console
-
-      # Image
-      curl -O https://cdn.download.clearlinux.org/current/clear-$(curl https://cdn.download.clearlinux.org/latest)-installer.img.xz
-      # Signature of SHA512 sum of image
-      curl -O https://cdn.download.clearlinux.org/current/clear-$(curl https://cdn.download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig
-      # Certificate
-      curl -O https://cdn.download.clearlinux.org/releases/$(curl https://cdn.download.clearlinux.org/latest)/clear/ClearLinuxRoot.pem
-
-#. Generate the SHA256 sum of the |CL| certificate.
-
-   .. code-block:: console
-
-      sha256sum ClearLinuxRoot.pem
-
-#. Ensure the generated SHA256 sum of the |CL| certificate matches the
-   following SHA256 sum to verify the integrity of the certificate.
-
-   .. code-block:: console
-
-      4b0ca67300727477913c331ff124928a98bcf2fb12c011a855f17cd73137a890  ClearLinuxRoot.pem
-
-#. Generate the SHA512 sum of the image and save it to a file.
-
-   .. code-block:: console
-
-      sha512sum clear-$(curl https://cdn.download.clearlinux.org/latest)-installer.img.xz > sha512sum.out
-
-#. Ensure the signature of the SHA512 sum of the image was created using the
-   |CL| certificate. This confirms that the image is trusted and has not
-   been modified.
-
-   .. code-block:: console
-
-      openssl smime -verify -purpose any -in clear-$(curl https://cdn.download.clearlinux.org/latest)-installer.img.xz-SHA512SUMS.sig -inform der -content sha512sum.out -CAfile ClearLinuxRoot.pem
-
-   .. note::
-
-      The :command:`-purpose any` option is required when using OpenSSL 1.1.
-      If you use an earlier version of OpenSSL, omit this option to perform
-      signature validation.  The :command:`openssl version` command may be used
-      to determine the version of OpenSSL in use.
-
-#. The output should contain "Verification successful". If the output
-   contains "bad_signature" anywhere, then the image is not trustworthy.
-
-Update content validation
-*************************
-
-**swupd** validates all update content automatically before applying the
-update content. The process swupd follows internally is illustrated here
-with manual steps using the latest |CL| release. There is no need to perform
-these steps manually when performing a :command:`swupd update`.
-
-#. Download the :abbr:`MoM (top-level manifest)`, the signature of the MoM,
-   and the Swupd certificate used for signing the signature of the MoM.
-
-   .. code-block:: console
-
-      # MoM
-      curl -O https://cdn.download.clearlinux.org/update/$(curl https://cdn.download.clearlinux.org/latest)/Manifest.MoM
-      # Signature of MoM
-      curl -O https://cdn.download.clearlinux.org/update/$(curl https://cdn.download.clearlinux.org/latest)/Manifest.MoM.sig
-      # Swupd certificate
-      curl -O https://cdn.download.clearlinux.org/releases/$(curl https://cdn.download.clearlinux.org/latest)/clear/Swupd_Root.pem
-
-#. Generate the SHA256 sum of the swupd certificate.
-
-   .. code-block:: console
-
-      sha256sum Swupd_Root.pem
-
-#. Confirm that the generated SHA256 sum of the swupd certificate matches the
-   SHA256 sum shown below to verify the integrity of the certificate.
-
-   .. code-block:: console
-
-      ff06fc76ec5148040acb4fcb2bc8105cc72f1963b55de0daf3a4ed664c6fe72c  Swupd_Root.pem
-
-#. Confirm that the signature of the MoM was created using the Swupd
-   certificate. This signature validates the update content is trustworthy and 
-   has not been modified.
-
-   .. code-block:: console
-
-      openssl smime -verify -purpose any -in Manifest.MoM.sig -inform der -content Manifest.MoM -CAfile Swupd_Root.pem
-
-   .. note::
-
-      The :command:`-purpose any` option is required when using OpenSSL 1.1.
-      If you use an earlier version of OpenSSL, omit this option to perform
-      signature validation.  The :command:`openssl version` command may be used
-      to determine the version of OpenSSL in use.
-
-   .. note::
-
-      The SHA512 sum of the MoM is not generated and then signed. Instead, the
-      MoM is signed directly because it is small in size compared to an image of
-      |CL|.
-
-#. The output should contain "Verification successful". If the output
-   contains "bad_signature" anywhere, then the MoM cannot be trusted.
-   Because the MoM contains a list of hashes for bundle manifests, if the MoM
-   cannot be trusted, then the bundle content cannot be trusted.

_sources/guides/network/ipxe-install.rst.txt

@@ -1,340 +0,0 @@
-.. _ipxe-install:
-
-Install over the network with iPXE
-##################################
-
-This guide describes how to install |CL-ATTR| using :abbr:`PXE (Pre-boot
-Execution Environment)` over the network.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-PXE is an industry standard that describes client-server interaction with
-network-boot software and uses the DHCP and TFTP protocols. This guide shows one
-method of using the PXE environment to install |CL|.
-
-The PXE extension called `iPXE`_ adds support for additional protocols such as
-HTTP, :abbr:`iSCSI (Internet Small Computer Systems Interface)`, :abbr:`AoE
-(ATA over Ethernet\*)`, and :abbr:`FCoE (Fiber Channel over Ethernet\*)`. iPXE
-enables network booting on computers with no built-in PXE support.
-
-To install |CL| through iPXE, you must create a PXE client. Figure 1 depicts
-the flow of information between a PXE server and a PXE client.
-
-.. figure:: ./figures/network-boot-flow.png
-   :alt: PXE information flow
-
-   Figure 1: PXE information flow.
-
-.. caution::
-
-   The |CL| image that boots through the PXE process automatically erases all
-   data and partitions on the PXE client system and creates 3 new partitions
-   to install onto.
-
-Prerequisites
-*************
-
-Before booting with iPXE, make the following preparations.
-
-Connect the PXE server and PXE clients to a switch on a private network, as
-shown in figure 2.
-
-.. figure:: ./figures/network-boot-setup.png
-   :alt: Network topology
-
-   Figure 2: Network topology.
-
-Your PXE client must have a boot order where the network boot option is
-prioritized before the disk boot option.
-
-Your PXE server must have:
-
-* Ethernet/LAN boot option.
-* At least two network adapters.
-* Connection to a public network.
-* Secure boot option disabled.
-
-.. note::
-
-   You must disable the secure boot option in the BIOS because the UEFI
-   binaries used to boot |CL| are not signed.
-
-
-Configuration
-*************
-
-To set up |CL| using iPXE automatically, use the :file:`configure-ipxe.sh`
-script included with :abbr:`ICIS (Ister Cloud Init Service)`. For additional
-instructions on the script, refer to the guide on the `ister-cloud-init-svc`_
-GitHub\* repository.
-
-To set up |CL| manually, perform the steps below.
-
-#. Define the variables used for iPXE boot configuration.
-
-   .. code-block:: console
-
-      ipxe_app_name=ipxe
-      ipxe_port=50000
-      web_root=/var/www
-      ipxe_root=$web_root/$ipxe_app_name
-      tftp_root=/srv/tftp
-      external_iface=eno1
-      internal_iface=eno2
-      pxe_subnet=192.168.1
-      pxe_internal_ip=$pxe_subnet.1
-      pxe_subnet_mask_ip=255.255.255.0
-      pxe_subnet_bitmask=16
-
-#. Log in and get root privilege.
-
-   .. code-block:: bash
-
-      sudo -s
-
-#. Add the :command:`pxe-server` bundle to your |CL| system. The bundle contains all
-   files needed to run a PXE server.
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add pxe-server
-
-#. Download the latest network-bootable release of |CL| and extract the
-   files.
-
-   .. code-block:: bash
-
-      sudo mkdir -p $ipxe_root
-      sudo curl -o /tmp/clear-pxe.tar.xz \
-        https://cdn.download.clearlinux.org/current/clear-$(curl \
-        https://cdn.download.clearlinux.org/latest)-pxe.tar.xz
-      sudo tar -xJf /tmp/clear-pxe.tar.xz -C $ipxe_root
-      sudo ln -sf $(ls $ipxe_root | grep 'org.clearlinux.*') $ipxe_root/linux
-
-   .. note::
-
-      Ensure that the initial ramdisk file is named :file:`initrd` and
-      the kernel file is named :file:`linux`, which is a symbolic link to the
-      actual kernel file.
-
-#. Create an iPXE boot script with the following contents. During an iPXE
-   boot, the iPXE boot script directs the PXE client to download the files to
-   boot and install |CL|. Use the names previously given to the initial
-   ramdisk and kernel files.
-
-   .. code-block:: console
-
-      sudo cat > $ipxe_root/ipxe_boot_script.ipxe << EOF
-      #!ipxe
-      kernel linux quiet init=/usr/lib/systemd/systemd-bootchart \
-      initcall_debug tsc=reliable no_timer_check noreplace-smp rw \
-      initrd=initrd
-      initrd initrd
-      boot
-      EOF
-
-#. The :command:`pxe-server` bundle contains a lightweight web-server known as
-   nginx. Create a configuration file for nginx to serve |CL| to PXE
-   clients with the following contents:
-
-   .. code-block:: console
-
-      sudo mkdir -p /etc/nginx/conf.d
-      sudo cat > /etc/nginx/conf.d/$ipxe_app_name.conf << EOF
-      server {
-        listen $ipxe_port;
-        server_name localhost;
-        location /$ipxe_app_name/ {
-          root $web_root;
-          autoindex on;
-        }
-      }
-      EOF
-
-      sudo cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf
-
-   .. note::
-
-      Create a separate nginx configuration file to serve network-bootable
-      images on a non-standard port number. This action saves existing nginx
-      configurations.
-
-#. Start nginx and enable the startup on boot option.
-
-   .. code-block:: bash
-
-      sudo systemctl start nginx
-      sudo systemctl enable nginx
-
-#. The :command:`pxe-server` bundle contains a lightweight DNS server which
-   conflicts with the DNS stub listener provided in `systemd-resolved`.
-   Disable the DNS stub listener and temporarily stop `systemd-resolved`.
-
-   .. code-block:: console
-
-      sudo mkdir -p /etc/systemd
-      sudo cat > /etc/systemd/resolved.conf << EOF
-      [Resolve]
-      DNSStubListener=no
-      EOF
-
-      sudo systemctl stop systemd-resolved
-
-#. Assign a static IP address to the network adapter for the private network
-   and restart `systemd-networkd` with the following commands:
-
-   .. code-block:: console
-
-      sudo mkdir -p /etc/systemd/network
-      sudo cat > /etc/systemd/network/70-internal-static.network << EOF
-      [Match]
-      Name=$internal_iface
-      [Network]
-      DHCP=no
-      Address=$pxe_internal_ip/$pxe_subnet_bitmask
-      EOF
-
-      sudo systemctl restart systemd-networkd
-
-#. Configure :abbr:`NAT (Network Address Translation)` to route traffic from
-   the private network to the public network. This action makes the PXE
-   server act as a router. To make these changes persistent during reboots, save the
-   changes to the firewall with the following commands:
-
-   .. code-block:: bash
-
-      sudo iptables -t nat -F POSTROUTING
-      sudo iptables -t nat -A POSTROUTING -o $external_iface -j MASQUERADE
-      sudo systemctl enable iptables-save.service
-      sudo systemctl restart iptables-save.service
-      sudo systemctl enable iptables-restore.service
-      sudo systemctl restart iptables-restore.service
-
-   .. note::
-
-      The firewall masks packets to make them appear as coming from the PXE
-      server and hides PXE clients from the public network.
-
-#. Configure the kernel to forward network packets to different
-   interfaces. Otherwise, NAT will not work.
-
-   .. code-block:: bash
-
-      sudo mkdir -p /etc/sysctl.d
-      sudo echo net.ipv4.ip_forward=1 > /etc/sysctl.d/80-nat-forwarding.conf
-      sudo echo 1 > /proc/sys/net/ipv4/ip_forward
-
-#. The :command:`pxe-server` bundle contains iPXE firmware images that allow computers
-   without an iPXE implementation to perform an iPXE boot. Create a TFTP
-   hosting directory and populate the directory with the iPXE firmware images
-   with the following commands:
-
-   .. code-block:: bash
-
-      sudo mkdir -p $tftp_root
-      sudo ln -sf /usr/share/ipxe/undionly.kpxe $tftp_root/undionly.kpxe
-
-#. The :command:`pxe-server` bundle contains a lightweight TFTP, DNS, and DHCP
-   server known as `dnsmasq`. Create a configuration file for `dnsmasq`
-   to listen on a dedicated IP address for those functions. PXE clients on
-   the private network will use this IP address.
-
-   .. code-block:: console
-
-      sudo cat > /etc/dnsmasq.conf << EOF
-      listen-address=$pxe_internal_ip
-      EOF
-
-#. Add the options to serve iPXE firmware images to PXE clients over TFTP to
-   the `dnsmasq` configuration file.
-
-   .. code-block:: console
-
-      sudo cat >> /etc/dnsmasq.conf << EOF
-      enable-tftp
-      tftp-root=$tftp_root
-      EOF
-
-#. Add the options to host a DHCP server for PXE clients to the :file:`dnsmasq`
-   configuration file.
-
-   .. code-block:: console
-
-      sudo cat >> /etc/dnsmasq.conf << EOF
-      dhcp-leasefile=/var/db/dnsmasq.leases
-
-      dhcp-authoritative
-      dhcp-option=option:router,$pxe_internal_ip
-      dhcp-option=option:dns-server,$pxe_internal_ip
-
-      dhcp-match=set:pxeclient,60,PXEClient*
-      dhcp-range=tag:pxeclient,$pxe_subnet.2,$pxe_subnet.253,$pxe_subnet_mask_ip,15m
-      dhcp-range=tag:!pxeclient,$pxe_subnet.2,$pxe_subnet.253,$pxe_subnet_mask_ip,6h
-
-      dhcp-match=set:ipxeboot,175
-      dhcp-boot=tag:ipxeboot,http://$pxe_internal_ip:$ipxe_port/$ipxe_app_name/ipxe_boot_script.ipxe
-      dhcp-boot=tag:!ipxeboot,undionly.kpxe,$pxe_internal_ip
-      EOF
-
-
-   The configuration provides the following important functions:
-
-   * Directs PXE clients without an iPXE implementation to the TFTP server
-     to acquire architecture-specific iPXE firmware images that allow them
-     to perform an iPXE boot.
-   * Activates only on the network adapter that has an IP address on the
-     defined subnet.
-   * Directs PXE clients to the DNS server.
-   * Directs PXE clients to the PXE server for routing via NAT.
-   * Divides the private network into two pools of IP addresses. One pool
-     is for network boot and one pool is used after boot. Each pool has
-     their own lease times.
-
-#. Create a file for `dnsmasq` to record the IP addresses it provides
-   to PXE clients.
-
-   .. code-block:: bash
-
-      sudo mkdir -p /var/db
-      sudo touch /var/db/dnsmasq.leases
-
-#. Start `dnsmasq` and enable startup on boot.
-
-   .. code-block:: bash
-
-      sudo systemctl enable dnsmasq
-      sudo systemctl restart dnsmasq
-
-#. Start `systemd-resolved`.
-
-   .. code-block:: bash
-
-      sudo systemctl start systemd-resolved
-
-   .. note::
-
-      `systemd-resolved` dynamically updates the list of DNS servers for the
-      private network if you use the `dnsmasq` DNS server. The setup creates a
-      pass-through DNS server that relies on the DNS servers listed in
-      :file:`/etc/resolv.conf`.
-
-#. Power on the PXE client and watch the client boot and install |CL|.
-
-   After booting, |CL| automatically partitions the hard drive,
-   installs itself, updates to the latest version, and reboots.
-
-
-**Congratulations!** You have successfully installed and configured a PXE
-server that enables PXE clients to boot and install |CL| over the network.
-
-
-.. _iPXE:
-   http://ipxe.org/
-
-.. _ister-cloud-init-svc:
-   https://github.com/clearlinux/ister-cloud-init-svc

_sources/guides/network/network-bonding.rst.txt

@@ -1,130 +0,0 @@
-.. _network-bonding:
-
-Combine multiple interfaces with network bonding
-################################################
-
-This guide describes how to configure systemd to use the :command:`bonding`
-driver.
-
-Network bonding combines multiple network interfaces into a single logical
-interface to provide redundancy and bandwidth aggregation.
-
-|CL-ATTR| includes the Linux `Bonding driver`_ and `Team driver`_ .
-
-The example demonstrates how to:
-
-*  Bond all four ports of a quad-port NIC in 802.3ad mode.
-
-*  Enable jumbo frames to optimize large data transfers on the local network.
-
-Your NICs and network switch must support 802.3ad mode and jumbo frames. The
-example explains how to configure your NICs for both features. Your switch may
-require additional configuration. See your switch documentation for details.
-
-.. note::
-
-   You must run all commands in this guide as root.
-
-#. Log in and get root privileges.
-
-   .. code-block:: console
-
-      sudo -s
-
-#. Create the :file:`/etc/systemd/network` directory.
-
-   .. code-block:: bash
-
-      mkdir -p /etc/systemd/network
-
-   The :file:`/etc/systemd/network` directory contains configuration files and
-   network settings for the virtual device and its underlying physical
-   interfaces.
-
-#. Configure systemd to create a virtual network device called `bond1`. Use a
-   text editor to create a file named :file:`30-bond1.netdev`.
-
-   .. code-block:: console
-
-      [NetDev]
-      Name=bond1
-      Kind=bond
-
-      [Bond]
-      Mode=802.3ad
-      TransmitHashPolicy=layer3+4
-      MIIMonitorSec=1s
-      LACPTransmitRate=fast
-
-   Refer to the `systemd.netdev`_ manpage for :file:`30-bond1.netdev` file
-   syntax. This example is based on Example 9 on the manpage. Modify the
-   example for your configuration.
-
-#. Configure the slave interfaces. Create a text file named
-   :file:`30-bond1-enp1s0.network`. Assign the slave interfaces to the virtual
-   `bond1` device and use the syntax shown in `systemd.network`_.
-
-   .. code-block:: console
-
-      [Match]
-      Name=enp1s0f*
-
-      [Network]
-      Bond=bond1
-
-      [Link]
-      MTUBytes=9000
-
-   The example bonds all four ports of a quad-port NIC as a slave of `bond1`.
-   The example uses a wildcard match because the NIC names are in the range
-   `enp1s0f0-enp1s0f3`. If your NIC names are not wildcard-compatible, create
-   a separate :file:`.network` file for each NIC.
-
-   For best results, do not assign addresses or DHCP support to the individual
-   NICs.
-
-   The `MTUBytes` setting enables jumbo frames of up to 9000 bytes. Your
-   switch may require additional configuration to support this setting.
-
-#. Configure the bonded interface in a file named :file:`30-bond1.network`.
-
-   .. code-block:: console
-
-      [Match]
-      Name=bond1
-
-      [Network]
-      BindCarrier=enp1s0f0 enp1s0f1 enp1s0f2 enp1s0f3
-      Address=192.168.1.201/24
-
-      [Link]
-      MTUBytes=9000
-
-   `bond1` is a virtual interface with no physical link status.
-
-   `BindCarrier` indicates that the `bond1` link status is determined by the
-   status of the listed slave devices.
-
-   `Address` contains an IP address that you assign to the logical interface.
-   DHCP bonded interfaces are complex and outside the scope of this example.
-
-   `MTUBytes` must be set to 9000 on all slave interfaces and on the bonded
-   interface for successful jumbo frames operation. If `MTUBytes` is not the
-   same on all interfaces, then the lowest value is used.
-
-#. Apply the new network configuration with the command:
-
-   .. code-block:: bash
-
-      systemctl restart systemd-networkd
-
-   The `MTUBytes` settings do not take effect until you reboot or manually
-   apply the settings with a utility such as ifconfig.
-
-.. _Bonding driver: https://www.kernel.org/doc/Documentation/networking/bonding.txt
-
-.. _Team driver: https://www.kernel.org/doc/Documentation/networking/team.txt
-
-.. _systemd.netdev: https://www.freedesktop.org/software/systemd/man/systemd.netdev.html
-
-.. _systemd.network: https://www.freedesktop.org/software/systemd/man/systemd.network.html

_sources/guides/network/vnc.rst.txt

@@ -1,791 +0,0 @@
-.. _vnc:
-
-Remote-desktop to a host using VNC
-##################################
-
-This guide describes how to use :abbr:`VNC (Virtual Network Computing)` to
-connect to a remote |CL-ATTR| host.
-
-VNC is a client-server GUI-based tool that allows you to connect via
-remote-desktop to your |CL| host.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Install the VNC server and misc. components on your host
-********************************************************
-
-To configure VNC to work on your |CL| host, install these bundles:
-
-* :command:`desktop-autostart`: Installs :abbr:`GDM (Gnome Desktop Manager)`, sets
-  it to start automatically on boot, and installs TigerVNC Viewer.
-* :command:`vnc-server`: Installs the TigerVNC server.
-
-Follow these steps:
-
-#. Log into your |CL| host and get root privileges.
-
-   .. code-block:: bash
-
-      sudo -s
-
-#. Install the |CL| bundles.
-
-   .. code-block:: bash
-
-      swupd bundle-add desktop-autostart vnc-server
-
-#. Reboot your |CL| host.
-
-Configure a VNC-server-start method on your host
-************************************************
-
-There are three methods you can use to configure and start the VNC server on
-your |CL| host:
-
-.. list-table:: Table 1: VNC-server-start Configuration Methods
-   :widths: 10,20,20,20
-   :header-rows: 1
-
-   * - Attribute
-     - Method 1: Manually start a VNC session
-     - Method 2: Automatically start a VNC session via a systemd service script
-     - Method 3: Create multi-user logins with authentication through GDM
-   * - Description
-     - This is the traditional method where you SSH into the |CL| host, manually
-       start a VNC session to get a display ID, and connect to it by
-       supplying the display ID.
-     - The system administrator sets up a systemd service script for you with
-       a pre-assigned display ID.  You make a VNC connection and supply
-       your pre-assigned display ID.
-     - The system adminstrator configures GDM to accept connection requests.
-       When you make a VNC connection to the |CL| host, you see
-       the GDM login screen and authenticate as if you are local.
-   * - Who configures VNC settings?
-     - You
-     - System adminstrator
-     - System adminstrator
-   * - Who starts VNC session?
-     - You
-     - Set to start automatically on boot by system administrator
-     - Set to start automatically on boot by system administrator
-   * - Who ends VNC sesssion?
-     - You
-     - You
-     - System administrator can disable VNC service altogether
-   * - Requires VNC password to authenticate?
-     - Yes
-     - Yes
-     - No.  Use |CL| account username and password through GDM
-
-
-Although all three methods can coexist on the same |CL| host, we recommend
-you pick a method that suits your needs.
-
-For simplicity, the rest of this guide refers to these methods as
-Method 1, Method 2, and Method 3.
-
-Method 1: Manually start a VNC session
-======================================
-
-You (and each user) must perform these steps to initialize your VNC settings.
-
-#. Log in.
-#. Open a terminal emulator.
-#. Start VNC with the :command:`vncserver` command.  Since this is your
-   first time starting VNC, it adds default configuration files and asks you
-   to set a VNC password.
-
-   .. code-block:: bash
-
-      vncserver
-
-   Example output:
-
-   .. code-block:: console
-
-      You will require a password to access your desktops.
-
-      Password:
-      Verify:
-      Would you like to enter a view-only password (y/n)? n
-      xauth:  file /home/vnc-user-a/.Xauthority does not exist
-
-      New 'clr-linux:2 (vnc-user-a)' desktop is clr-linux:2
-
-      Creating default startup script /home/vnc-user-a/.vnc/xstartup
-      Creating default config /home/vnc-user-a/.vnc/config
-      Starting applications specified in /home/vnc-user-a/.vnc/xstartup
-      Log file is /home/vnc-user-a/.vnc/clr-linux:2.log
-
-   Upon completion, you can find the default configuration files and the
-   password file hidden in the :file:`.vnc` directory in your home directory.
-
-   A VNC session starts and shows a unique display ID, which is the
-   number following the hostname and the colon ":".  In the above example, the
-   display ID is 2.  In a later step, you will supply the display ID to
-   your VNC viewer app for connection.
-
-#. Kill the active VNC session for the time being with the
-   :command:`vncserver -kill :[display ID]` command.  Substitute [display ID]
-   with your active VNC session display ID.  For example:
-
-   .. code-block:: bash
-
-      vncserver -kill :2
-
-   .. note::
-
-      If you do not recall the active session display ID, use the
-      :command:`vncserver -list` command to find it.
-
-#. Optional configurations:
-
-   * To customize settings such as screen size, security type, etc.,
-     modify the :file:`$HOME/.vnc/config` file.
-   * To customize the applications to run at startup, modify the
-     :file:`$HOME/.vnc/xstartup` file.
-
-Method 2: Automatically start a VNC session via a systemd service script
-========================================================================
-
-To configure VNC for this method, you must have root privileges.  You will
-set up a systemd service file for all intended VNC users with their own
-preassigned unique display ID.
-
-#. Log in and get root privileges.
-
-   .. code-block:: bash
-
-      sudo -s
-
-#. Make sure the user accounts already exist.  Use the following command to
-   list all users.
-
-
-   .. code-block:: bash
-
-      cut -d: -f1 /etc/passwd
-
-#. Create the path :file:`/etc/systemd/system`.
-
-   .. code-block:: bash
-
-      mkdir -p /etc/systemd/system
-
-#. Create a systemd service script file :file:`vncserver@:[X].service`,
-   where [X] is the display ID, for each user in :file:`/etc/systemd/system`
-   Each user must be assigned a unique display ID.  Be sure the correct
-   username is entered in the :guilabel:`User` field. The example below shows user
-   vnc-user-b who is assigned the display ID 5.
-
-   .. code-block:: console
-
-      # cat > /etc/systemd/system/vncserver@:5.service << EOF
-
-      [Unit]
-      Description=VNC Remote Desktop Service for "vnc-user-b" with display ID "5"
-      After=syslog.target network.target
-
-      [Service]
-      Type=simple
-      User=vnc-user-b
-      PAMName=login
-      PIDFile=/home/%u/.vnc/%H%i.pid
-      ExecStartPre=/bin/sh -c '/usr/bin/vncserver -kill %i > /dev/null 2>&1 || :'
-      ExecStart=/usr/bin/vncserver %i -geometry 2000x1200 -alwaysshared -fg
-      ExecStop=/usr/bin/vncserver -kill %i
-
-      [Install]
-      WantedBy=multi-user.target
-
-      EOF
-
-#. Have each user log into their account and set a VNC password with
-   the :command:`vncpasswd` command before proceeding to the next step.
-
-#. Start the VNC service script and set it to start automatically on
-   boot for each user.  Replace the [X] with the display ID.
-
-   .. code-block:: bash
-
-      systemctl daemon-reload
-      systemctl start vncserver@:[X].service
-      systemctl enable vncserver@:[X].service
-
-#. After starting the services, verify they are running.
-
-   .. code-block:: bash
-
-      systemctl | grep vnc
-
-   The example below shows 2 VNC sessions that were successfully started for
-   users vnc-user-b with display ID 5 and vnc-user-c with display ID 6.
-
-   .. code-block:: console
-
-      # systemctl | grep vnc
-
-      vncserver@:5.services   loaded active running  VNC Remote Desktop Service for "vnc-user-b" with display ID "5"
-      vncserver@:6.services   loaded active running  VNC Remote Desktop Service for "vnc-user-c" with display ID "6"
-      system-vncserver.slice  loaded active active system-vncserver.slice
-
-Method 3: Multi-user logins with authentication through GDM
-===========================================================
-
-For this method, VNC is configured as a systemd service that listens on port
-5900 and GDM is configured to accept access requests from VNC. When you
-make a VNC connection to your |CL| host, you are presented with the GDM login
-screen and you authenticate as if you are local.  You must have root privileges
-to perform this configuration.
-
-#. Log in and get root privileges.
-
-   .. code-block:: bash
-
-      sudo -s
-
-#. Create the path :file:`/etc/systemd/system`.
-
-   .. code-block:: bash
-
-      mkdir -p /etc/systemd/system
-
-#. Create a systemd socket file :file:`xvnc.socket` and add the following:
-
-   .. code-block:: console
-
-      # cat > /etc/systemd/system/xvnc.socket << EOF
-
-      [Unit]
-      Description=XVNC Server on port 5900
-
-      [Socket]
-      ListenStream=5900
-      Accept=yes
-
-      [Install]
-      WantedBy=sockets.target
-
-      EOF
-
-#. Create a systemd service file :file:`xvnc@.service` and add the following:
-
-   .. code-block:: console
-
-      # cat > /etc/systemd/system/xvnc@.service << EOF
-
-      [Unit]
-      Description=Daemon for each XVNC connection
-
-      [Service]
-      ExecStart=-/usr/bin/Xvnc -inetd -query localhost -geometry 2000x1200 -once -SecurityTypes=None
-      User=nobody
-      StandardInput=socket
-      StandardError=syslog
-
-      EOF
-
-#. Create the path :file:`/etc/gdm`.
-
-   .. code-block:: bash
-
-      mkdir -p /etc/gdm
-
-
-#. Create a GDM :file:`custom.conf` file and add the following:
-
-   .. code-block:: console
-
-      # cat > /etc/gdm/custom.conf << EOF
-
-      [xdmcp]
-      Enable=true
-      Port=177
-
-      EOF
-
-#. Start the VNC socket script and set it to start automatically on boot.
-
-   .. code-block:: bash
-
-      systemctl daemon-reload
-      systemctl start xvnc.socket
-      systemctl enable xvnc.socket
-
-#. After starting the socket, verify it is running.
-
-   .. code-block:: bash
-
-      systemctl | grep vnc
-
-   The example below shows the xvnc.socket is running.
-
-   .. code-block:: console
-
-      # systemctl | grep vnc
-
-      xvnc.socket 		loaded active listening	XVNC Server on port 5900
-      system-xvnc.slice 	loaded active active	system-xvnc.slice
-
-See the vncserver Man page for additional information.
-
-Install a VNC viewer app and an SSH client on your client system
-****************************************************************
-
-You need a VNC viewer app on your client system to connect to your |CL| host.
-An SSH client is only needed if you chose to use Method 1 or you plan to
-encrypt your VNC traffic, which is discussed later in this guide.
-
-Perform the steps below to add these apps to your client system.
-
-Install a VNC viewer app
-========================
-
-On |CL|:
-
-.. code-block:: bash
-
-   swupd bundle-add desktop-autostart
-
-On Ubuntu\*, Mint\*:
-
-.. code-block:: bash
-
-   apt-get install xtightvncviewer
-
-On Fedora\*:
-
-.. code-block:: bash
-
-   dnf install tigervnc
-
-On Windows\*:
-
-* Install `RealVNC for Windows`_
-
-On macOS\*:
-
-* Install `RealVNC for macOS`_
-
-Install an SSH client
-=====================
-
-* On most Linux distros (|CL|, Ubuntu, Mint, Fedora, etc.) and macOS,
-  SSH is built-in so you don't need to install it.
-* On Windows, you can install `Putty`_.
-
-Establish a VNC connection to your host
-***************************************
-
-Depending on the VNC-server-configuration method chosen, use the appropriate VNC
-connection:
-
-* If you chose Method 1, you must take a few extra steps by using SSH to connect
-  to your |CL| host and then manually launching VNC.
-
-* If you chose Method 2, get your preassigned VNC display ID from your system
-  administrator first and then proceed to the :ref:`connect-to-vnc-session`
-  section below.
-
-* If you chose Method 3, proceed to the :ref:`connect-to-vnc-session` below.
-
-
-SSH into your host and launch VNC
-=================================
-
-#. SSH into your |CL| host
-
-   #. On Linux distros and macOS:
-
-      .. code-block:: bash
-
-         ssh [username]@[clear-linux-host-ip-address]
-
-   #. On Windows:
-
-      #. Launch Putty.
-      #. Under the :guilabel:`Category` section, select :guilabel:`Session`.
-         See Figure 1.
-      #. Enter the IP address of your |CL| host in the
-         :guilabel:`Host Name (or IP address)` field.
-      #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`.
-      #. Click the :guilabel:`Open` button.
-
-         .. figure:: figures/vnc/vnc-1.png
-            :scale: 90 %
-            :alt: Putty - configure SSH session settings
-
-            Figure 1: Putty - configure SSH session settings
-
-#. Log in with your |CL| username and password. Do not use your VNC password.
-#. Start a VNC session.
-
-   .. code-block:: bash
-
-      vncserver
-
-   Example output:
-
-   .. code-block:: console
-
-      New 'clr-linux:3 (vnc-user-c)' desktop is clr-linux:3
-
-      Starting applications specified in /home/vnc-user-c/.vnc/xstartup
-      Log file is /home/vnc-user-c/.vnc/clr-linux:3.log
-
-#. Take note of the generated display ID because you will input it into
-   the VNC viewer app to establish the connection.  The above example shows
-   the display ID is 3.
-
-   .. note::
-
-      VNC automatically picks a unique display ID unless you specify one.
-      To specify a display ID, enter a unique number that is not already
-      in use after the colon.  For example:
-
-      .. code-block:: bash
-
-         vncserver :8
-
-#. You can now end the SSH connection by logging out.  This does
-   not terminate your active VNC session.
-
-.. _connect-to-vnc-session:
-
-Connect to your VNC session
-===========================
-
-For Method 1 and Method 2, you must connect to a specific active session
-or display ID using one of two options:
-
-* Use a fully-qualified VNC port number, which consists of the default VNC
-  server port (5900) plus the display ID
-* Use the display ID
-
-For example, if the display ID is 3, it can be specified as 5903 or just
-as 3. For Method 3, VNC does not expect a display ID.  Use 5900. For simplicity,
-the instructions below use the fully-qualified VNC port number.
-
-**On Linux distros:**
-
-#. Open a terminal emulator and enter:
-
-   .. code-block:: bash
-
-      vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port  number]
-
-#. Enter your credentials.
-
-   * For Method 1 and Method 2, enter your VNC password.  No username is
-     required.
-   * For Method 3, enter your |CL| account username and password through
-     GDM.
-
-     .. note::
-
-        With Method 3, you cannot remotely log into your |CL| host through
-        VNC if you are logged in locally and vice versa.
-
-**On Windows and macOS using RealVNC app:**
-
-#. Start the RealVNC viewer app. See Figure 2.
-#. Enter the IP address of the |CL| host and the fully-qualified
-   VNC port number.
-
-   The following screenshot shows connecting to |CL| host
-   192.168.25.54 with a fully-qualified VNC port number 5902.
-
-   .. figure:: figures/vnc/vnc-2.png
-      :scale: 90 %
-      :alt: RealVNC Viewer
-
-      Figure 2: RealVNC Viewer
-
-#. Press the :kbd:`Enter` key.
-
-#. Enter your credentials.
-
-   * For Method 1 and Method 2, enter your VNC password.  No username is
-     required.
-   * For Method 3, enter your |CL| account username and password through
-     GDM.
-
-     .. note::
-
-        With Method 3, you cannot remotely log into your |CL| host through
-        VNC if you are logged in locally and vice versa.
-
-Optional: Configure RealVNC Image Quality
------------------------------------------
-
-To increase the RealVNC viewer image quality, manually change the :guilabel:`ColorLevel`
-value. Follow these steps:
-
-#. Right-click a connection node and select :guilabel:`Properties...`.
-   See Figure 3.
-
-   .. figure:: figures/vnc/vnc-3.png
-      :scale: 90 %
-      :alt: RealVNC Viewer - change connection node properties
-
-      Figure 3: RealVNC Viewer - change connection node properties
-
-#. Select the :guilabel:`Expert` tab. See Figure 4.
-
-#. Select the :guilabel:`ColorLevel` setting and change it to your
-   preferred setting.
-
-   .. figure:: figures/vnc/vnc-4.png
-      :scale: 90 %
-      :alt: RealVNC Viewer - change ColorLevel
-
-      Figure 4: RealVNC Viewer - change :guilabel:`ColorLevel`
-
-Terminate a VNC connection to your host
-***************************************
-
-For Method 1 and Method 2, once started, a VNC session remains active
-on your |CL| host even if you close your VNC viewer app. If you want to
-truly terminate an active VNC session, follow these steps:
-
-#. SSH into your |CL| host.
-#. Open a terminal emulator.
-#. Find the active VNC session display ID with the command
-   :command:`vncserver -list`.
-
-   .. code-block:: bash
-
-      vncserver -list
-
-#. Terminate it with the :command:`vncserver -kill` command followed by a
-   colon and the display ID.
-
-   .. code-block:: bash
-
-      vncserver -kill :[display ID]
-
-#. For Method 3, only the system administrator can stop and disable the
-   VNC service by using these commands:
-
-   .. code-block:: bash
-
-      systemctl stop xvnc.socket
-      systemctl disable xnvc.socket
-
-
-Encrypt VNC traffic through an SSH tunnel
-*****************************************
-
-By default, VNC traffic is not encrypted.  Figure 6 shows an example warning
-from RealVNC Viewer.
-
-.. figure:: figures/vnc/vnc-6.png
-   :scale: 90 %
-   :alt: RealVNC Viewer - Connection not encrypted warning
-
-   Figure 6: RealVNC Viewer - Connection not encrypted warning
-
-To add security, VNC traffic can be routed through an SSH tunnel. This is
-accomplished by following these steps:
-
-#. Configure the VNC server to only accept connection from localhost by
-   adding the :command:`-localhost` option.
-#. Set up an SSH tunnel between your client system and your |CL| host.
-   Your client system will forward traffic from the localhost (the client)
-   destined for a specified fully-qualified VNC port number (on the client)
-   to your |CL| host with the same port number.
-#. The VNC viewer app on your client system will now connect to localhost,
-   instead of the IP address of your |CL| host.
-
-Configure VNC to only accept connection from localhost
-======================================================
-
-For Method 1:
-
-#. Edit the :file:`config` file located in :file:`$HOME/.vnc` and uncomment
-   the `# localhost` line.  It should look like this:
-
-   .. code-block:: console
-
-      ## Supported server options to pass to vncserver upon invocation can be listed
-      ## in this file. See the following manpages for more: vncserver(1)
-      Xvnc(1).
-      ## Several common ones are shown below. Uncomment and modify to your liking.
-      ##
-      # securitytypes=vncauth,tlsvnc
-      # desktop=sandbox
-      # geometry=2000x1200
-      localhost
-      # alwaysshared
-
-#. If an active session exists, kill it, and then restart it.
-
-For Method 2:
-
-#. Edit the systemd service script :file:`vncserver@:[X].service` located in
-   :file:`/etc/systemd/system` and add :command:`-localhost` to the `ExecStart`
-   line. The example below uses vncserver@:5.service:
-
-   .. code-block:: console
-
-      [Unit]
-      Description=VNC Remote Desktop Service for "vnc-user-b" with display ID "5"
-      After=syslog.target network.target
-
-      [Service]
-      Type=simple
-      User=vnc-user-b
-      PAMName=login
-      PIDFile=/home/%u/.vnc/%H%i.pid
-      ExecStartPre=/bin/sh -c '/usr/bin/vncserver -kill %i > /dev/null 2>&1 || :'
-      ExecStart=/usr/bin/vncserver %i -geometry 2000x1200 -localhost -alwaysshared -fg
-      ExecStop=/usr/bin/vncserver -kill %i
-
-      [Install]
-      WantedBy=multi-user.target
-
-#. Restart the service script:
-
-   .. code-block:: bash
-
-      systemctl daemon-load
-      systemctl restart vncserver@:5.service
-
-For Method 3:
-
-#. No change is needed to the :file:`xvnc@service` script.
-
-   After you have restarted your VNC session, you can verify that it only
-   accepts connections from localhost by using the :command:`netstat`
-   command like this:
-
-   .. code-block:: bash
-
-      netstat -plant
-
-   .. note::
-
-      Add the |CL| :command:`network-basic` bundle to get the :command:`netstat`
-      command.
-
-Figure 7 shows two VNC sessions (5901 and 5905) accepting connections from
-any host as specified by the `0.0.0.0`'s.  This is before the
-:command:`-localhost` option was used.
-
-.. figure:: figures/vnc/vnc-7.png
-   :scale: 100 %
-   :alt: VNC session accepting connection from any host
-
-   Figure 7: VNC sessions (5901 and 5905) accepting connections from any host
-
-Figure 8 shows two VNC sessions (5901 and 5905) only accepting connections from
-localhost as specified by `127.0.0.1`'s. This is after the
-:command:`-localhost` option was used.
-
-.. figure:: figures/vnc/vnc-8.png
-   :scale: 100 %
-   :alt: VNC session only accepting connection from localhost
-
-   Figure 8: VNC sessions (5901 and 5905) only accepting connections from localhost
-
-Set up an SSH tunnel from your client system to your |CL| host
-==============================================================
-
-**On Linux distros and macOS:**
-
-#. Open terminal emulator and enter:
-
-   .. code-block:: bash
-
-      ssh -L [client port number]:localhost:[fully-qualified VNC port number] \
-      -N -f -l [username] [clear-linux-host-ip-address]
-
-#. Enter your |CL| account password (not your VNC password).
-
-   .. note::
-
-      *	`-L` specifies that [client port number] on the localhost (on the
-        client side) is forwarded to [fully-qualified VNC port number]
-        (on the server side).
-      * Replace `[client port number]` with an available client port number
-        (for example: 1234). For simplicity, you can make the
-        `[client port number]` the same as the `[fully-qualified VNC port number]`.
-      * Replace `[fully-qualified VNC port number]` with 5900 (default VNC
-        port) plus the display ID.  For example, if the display ID is 2,
-        the fully-qualified VNC port number is is 5902.
-      *	`-N` tells SSH to only forward ports and not execute a remote
-        command.
-      *	`-f` tells SSH to go into the background before command execution.
-      *	`-l` specifies the username to log in as.
-
-**On Windows:**
-
-#. Launch Putty.
-#. Specify the |CL| VNC host to connect to.
-
-   #. Under the :guilabel:`Category` section, select :guilabel:`Session`.
-      See Figure 1.
-   #. Enter the IP address of your |CL| host in the
-      :guilabel:`Host Name (or IP address)` field.
-   #. Set the :guilabel:`Connection type` option to :guilabel:`SSH`.
-
-#. Configure the SSH tunnel.  See Figure 9 for an example.
-
-   #. Under the :guilabel:`Category` section, go to
-      :guilabel:`Connection` > :guilabel:`SSH` > :guilabel:`Tunnels`.
-
-   #. In the :guilabel:`Source port` field, enter an available client
-      port number (for example: 1234). For simplicity, you can make the
-      `Source port` the same as the fully-qualified VNC port number.
-
-   #. In the :guilabel:`Destination` field, enter
-      `localhost:` plus the fully-qualified VNC port number.
-
-   #. Click the :guilabel:`Add` button.
-
-      .. figure:: figures/vnc/vnc-9.png
-         :scale: 100 %
-         :alt: Putty - configure SSH tunnel
-
-         Figure 9: Putty - configure SSH tunnel
-
-#. Click the :guilabel:`Open` button.
-#. Enter your |CL| account password (not your VNC password).
-
-Connect to a VNC session through an SSH tunnel
-==============================================
-
-After you have set up an SSH tunnel, follow these instructions to connect to
-your VNC session.
-
-**On Linux distros:**
-
-#. Open terminal emulator and enter:
-
-   .. code-block:: bash
-
-      vncviewer localhost:[client port number]
-
-**On Windows and macOS using `RealVNC`:**
-
-#. Start the RealVNC viewer app.
-#. Enter `localhost` and the fully-qualified VNC port number.  See Figure 10
-   for an example.
-
-   .. figure:: figures/vnc/vnc-10.png
-      :scale: 100 %
-      :alt: RealVNC viewer app connecting to localhost:1234
-
-      Figure 10: RealVNC viewer app connecting to `localhost:1234`
-
-      .. note::
-
-         RealVNC will still warn that the connection is not encrypted even
-         though its traffic is going through the SSH tunnel.  You can ignore
-         this warning.
-
-.. _RealVNC for Windows: https://www.realvnc.com/en/connect/download/viewer/windows/
-.. _RealVNC for macOS: https://www.realvnc.com/en/connect/download/viewer/macos/
-.. _Putty: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

_sources/guides/stacks/dars.rst.txt

@@ -1,133 +0,0 @@
-.. _dars:
-
-Data Analytics Reference Stack
-##############################
-
-This guide explains how to use the :abbr:`DARS (Data Analytics Reference Stack)`,
-and to optionally build your own DARS container image.
-
-Any system that supports Docker\* containers can be used with DARS. This steps
-in this guide use |CL-ATTR| as the host system.
-
-.. contents::
-   :local:
-   :depth: 1
-
-The Data Analytics Reference Stack release
-******************************************
-
-The Data Analytics Reference Stack (DARS) provides developers and enterprises a straightforward, highly optimized software stack for storing and processing large
-amounts of data.  More detail is available on the
-`DARS architecture and performance benchmarks`_.
-
-The Data Analytics Reference Stack provides two pre-built Docker images,
-available on `Docker Hub`_:
-
-* A |CL|-derived `DARS with OpenBlas`_ stack optimized for `OpenBLAS`_
-* A |CL|-derived  `DARS with Intel® MKL`_ stack optimized for `MKL`_
-
-We recommend you view the latest component versions for each image in the
-:file:`README` found in the `Data Analytics Reference Stack`_ GitHub\*
-repository. Because |CL| is a rolling distribution, the package version numbers
-in the |CL|-based containers may not be the latest released by |CL|.
-
-.. note::
-
-   The Data Analytics Reference Stack is a collective work, and each piece
-   of software within the work has its own license.  Please see the
-   `DARS Terms of Use`_ for more details about licensing and usage of the Data
-   Analytics Reference Stack.
-
-Using the Docker images
-***********************
-
-#. To immediately start using the latest stable DARS images, pull an image
-   directly from `Docker Hub`_. This example uses the
-   `DARS with Intel® MKL`_ Docker image.
-
-#. Once you have downloaded the image, you can run it with
-
-   .. code-block:: bash
-
-      docker run -it --ulimit nofile=1000000:1000000 --name mkl <name of image>
-
-   This will launch the image and drop you into a bash shell inside the
-   container.  You will see output similar to the following:
-
-   .. code-block:: console
-
-      root@fd5155b89857 /root # spark-shell
-      spark-shell
-      Config directory: /usr/share/defaults/spark/
-      Welcome to
-        ____              __
-       / __/__  ___ _____/ /__
-       _\ \/ _ \/ _ `/ __/  '_/
-      /___/ .__/\_,_/_/ /_/\_\   version 2.4.0
-         /_/
-
-      Using Scala version 2.12.7 (OpenJDK 64-Bit Server VM, Java 1.8.0-internal)
-      Type in expressions to have them evaluated.
-      Type :help for more information.
-
-      scala>
-
-   The :command:`--ulimit nofile` parameter is currently required in order to
-   increase the number of open files opened at certain point by the spark
-   engine.
-
-Building DARS images
-********************
-
-If you choose to build your own DARS container images, you can customize
-them as needed. Use the provided Dockerfile as a baseline.
-
-To construct images with |CL|, start with a |CL| development platform that
-has the :command:`containers-basic-dev` bundle installed. Learn more about
-bundles and installing them by using :ref:`swupd-guide`.
-
-#. Clone the `Data Analytics Reference Stack`_ GitHub\* repository.
-
-   .. code-block:: bash
-
-      git clone https://github.com/clearlinux/dockerfiles/tree/master/stacks/dars -b master
-
-#. Inside the DARS directory, run :command:`make` to build OpenBLAS and MKL images.
-
-   .. code-block:: bash
-
-      make
-
-   Run :command:`make baseline` to build the baseline CentOS image. Depending on
-   the system, it may take a while to finish building.
-
-   .. code-block:: bash
-
-      make baseline
-
-#. Once completed, check the resulting images with :command:`Docker`
-
-   .. code-block:: bash
-
-      docker images | grep dars
-
-#. You can use any of the resulting images to launch fully functional containers.
-   If you need to customize the containers, you can edit the provided :file:`Dockerfile`.
-
-.. _Data Analytics Reference Stack: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dars
-
-.. _Docker Hub: https://hub.docker.com/
-
-.. _OpenBLAS: http://www.openblas.net/
-
-.. _MKL: https://software.intel.com/en-us/mkl
-
-.. _CentOS: https://www.centos.org/
-
-.. _DARS with OpenBLAS: https://hub.docker.com/r/clearlinux/stacks-dars-openblas/
-
-.. _DARS with Intel® MKL: https://hub.docker.com/r/clearlinux/stacks-dars-mkl/
-
-.. _DARS architecture and performance benchmarks: https://clearlinux.org/stacks/data-analytics-stack-v1
-
-.. _DARS Terms of Use: https://clearlinux.org/stacks/data-analytics/terms-of-use

_sources/guides/telemetrics/telem-guide.rst.txt

@@ -1,862 +0,0 @@
-.. _telem-guide:
-
-Telemetrics
-###########
-
-This guide describes the |CL-ATTR| telemetry solution.
-
-.. important::
-
-   Telemetry in |CL| is **opt-in**. The telemetry client is **not**  active
-   and sends **no** data until you explicitly enable it.
-
-.. note::
-
-   The telemetry functionality adheres to `Intel privacy policies`_ regarding
-   the collection and use of :abbr:`PII (Personally Identifiable Information)`
-   and is open source.
-
-   No intentionally identifiable information about the user or system owner is
-   collected.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-Telemetrics in |CL| is a client and server solution used to collect
-data from running |CL| systems to help quickly identify and fix bugs in the
-OS. Both client and server are customizable, and an API is available on the
-client side for instrumenting your code for debug and analysis.
-
-Telemetry, one of the key features of |CL|, enables developers to observe and
-proactively address issues in the OS before end users are impacted.
-
-Telemetrics is a combination word made from:
-
-* Telemetry, which is sensing and reporting data.
-* Analytics, which is using visualization and statistical inferencing to make
-  sense of the reported data.
-
-|CL| telemetry reports system-level debug/crash information using specialized
-probes. The probes monitor system tasks such as swupd, kernel oops, machine
-error checks, and the BIOS error report table for unhandled hardware
-failures. Telemetry enables real-time issue reporting to allow system
-developers to focus quickly on an issue and monitor corrective actions.
-
-|CL| telemetry is fully customizable and can be used during software
-development for debugging purposes. You can use the libtelemetry library in
-your code to create custom telemetry records. You can also use the
-telem-record-gen utility in script files for light-touch record creation
-where instrumenting code files doesn't make sense.
-
-The |CL| telemetrics solution is an **opt-in** choice on the client side.
-By default, the telemetry client is disabled until you choose to enable it.
-Enabling the client is covered in this guide.
-
-Architecture
-============
-
-|CL| telemetry has two fundamental components, which are shown in Figure 1:
-
-* Client: generates and delivers records to the backend server via the network.
-
-* Backend: receives records sent from the client and displays the cumulative
-  content through a specialized web interface.
-
-.. figure:: figures/telemetry-e2e.png
-   :alt: Figure 1, Telemetry Architecture
-
-   Figure 1: :guilabel:`|CL| Telemetry Architecture`
-
-The telemetry client provides the front end of the telemetrics solution and
-includes the following components:
-
-* telemprobd, which is a daemon that receives and prepares telemetry records
-  from probes and spools them to disk.
-* telempostd, which is a daemon that manages spooled telemetry records and
-  delivers these records according to configurable settings.
-* probes, which collect specific types of data from the operating system.
-* libtelemetry, which is the API that telemetrics probes use to create records.
-
-The telemetry backend provides the server-side component of the telemetrics
-solution and consists of:
-
-* Nginx web server.
-* Two Flask apps:
-
-  * Collector, which is an ingestion web app for records received from client
-    probes.
-  * TelemetryUI, which is a web app that exposes different views to visualize
-    the telemetry data.
-* PostgreSQL as the underlying database server.
-
-.. note::
-
-   The default telemetry backend server is hosted by the Intel |CL| development
-   team and is not viewable outside the Intel firewall. To collect your own
-   records, you must set up your own telemetry backend server.
-
-How to use
-**********
-
-From a workflow perspective, the |CL| telemetrics system is straightforward.
-On the client side, the main decisions after installation and enabling
-telemetry involve what to do with the record data generated by the probes.
-You can send the data to the default or a custom backend server, keep the data
-local to the system, or both. The backend server has a more complex setup, but
-once it's running, it is simple to use and configure.
-
-This section describes some of the possible scenarios for configuring
-the |CL| telemetrics system, and suggests which ones make sense according to
-your needs.
-
-Scenarios
-=========
-
-#. Enable telemetry:
-
-   Before probes can generate records, the telemetry client daemons must be
-   enabled. You can configure the client before enabling by creating a custom
-   :file:`telemetrics.conf` file that you place in the :file:`/etc/telemetrics`
-   directory. If you choose to use the default settings, records will be sent
-   to the telemetrics backend server managed by the |CL| development team at
-   Intel.
-
-#. Save record data locally:
-
-   You can configure the telemetry client to save records locally. This is
-   convenient when you want instant feedback during a development cycle, or to
-   track system issues if you believe there is a machine specific problem. The
-   client can be set not to send records at all, or to both keep the records
-   locally and send to the backend server.
-
-#. Set up a server to collect data:
-
-   Whether you are managing a network of |CL| systems or you don't want to
-   send records to the default telemetry server, you can set up a backend
-   server to collect your records. The backend server can be installed on any
-   Linux system and provides the same dashboard as the default server.
-
-
-#. Instrument your code with the libtelemetry API:
-
-   The :command:`telemetrics` bundle includes the libtelemetry C library, which
-   exposes an API used by the telemprobd and telempostd daemons. You can use
-   these in your applications as well. The API documentation is found in the
-   :file:`telemetry.h` file in `Telemetrics client`_ repository.
-
-
-Examples
-********
-
-.. contents::
-   :local:
-   :depth: 1
-
-Enable or disable telemetry
-===========================
-
-#. Enabling during installation:
-
-   During the initial installation of |CL|, you are requested to join the
-   stability enhancement program and allow |CL| to collect anonymous reports to
-   improve system stability. If you choose not to join this program, then the
-   telemetry software bundle is not added to your system. Choosing to join will
-   automatically enable telemetry on your system after installation is
-   complete.
-
-#. Enabling after install:
-
-   To start telemetry on your system, run the following command:
-
-   .. code-block:: bash
-
-      sudo telemctl start
-
-   This enables and starts the :command:`telemprobd` and :command:`telempostd`
-   daemons. Your system will begin to send telemetry data to the server defined
-   in the file :file:`/etc/telemetrics/telemetrics.conf`. If this file does not
-   exist, the :command:`telemprobd` and :command:`telempostd` daemons will use
-   the file :file:`/usr/share/defaults/telemetrics/telemetrics.conf`.
-
-#. Disabling after install:
-
-   To disable both of the telemetry daemons, run the following command:
-
-   .. code-block:: bash
-
-      sudo telemctl stop
-
-#. Opt in to telemetry:
-
-   To opt-in to the telemetry services, simply enter the opt-in command, which  
-   also starts the service:
-
-   .. code-block:: bash
-
-      sudo telemctl opt-in
-
-   This removes the :file:`/etc/telemetrics/opt-out` file, if it exists, and
-   starts the telemetry services.
-
-   .. note::
-
-      To opt-in but not immediately start telemetry services, you must
-      run the command :command:`sudo telemctl stop` after the :command:`opt-in`
-      command is entered. Once you are ready to start the service, enter the
-      command :command:`sudo telemctl start`.
-
-#. Opt out of telemetry:
-
-   To stop sending telemetrics data from your system, opt out of the telemetry
-   service:
-
-   .. code-block:: bash
-
-      sudo telemctl opt-out
-
-   This creates the file :file:`/etc/telemetrics/opt-out` and stops the
-   telemetry services.
-
-
-Saving data locally
-===================
-
-This example requires |CL| to be installed and telemetry to be enabled on the
-system.
-
-To change how records are managed, copy the default
-:file:`/usr/share/defaults/telemetrics/telemetrics.conf` file to
-:file:`/etc/telemetrics/telemetrics.conf` and edit it. The changes in the
-:file:`/etc/telemetrics/telemetrics.conf` file will override the defaults in
-the :file:`/usr/share/defaults/telemetrics/telemetrics.conf` file. You may need
-root permissions to create and edit files in :file:`/etc`. For each
-example, and for any time you make changes to the configuration file, you must
-restart the client daemons to pick up the changes:
-
-.. code-block:: bash
-
-  sudo telemctl restart
-
-
-The :command:`telemctl journal` command gives you access to features and
-options of the telemetry journal to assist with system analytics and debug.
-:command:`telemctl journal` has a number of options to help filter records.
-Use :command:`-h` or :command:`--help` to view usage options.
-
-
-#. Keep a local copy and send records to backend server:
-
-   To keep a local copy of the telemetry record and also send it on to the
-   backend server, we will need to change the
-   :guilabel:`record_retention_enabled` configuration key value to
-   :guilabel:`true`.
-
-#. Keep all records  -- don't send to backend server:
-
-   To keep records on the system without sending them to a backend server, set
-   the :guilabel:`record_server_delivery_enabled` key value to
-   :guilabel:`false`. Note that you will also need to ensure the
-   :guilabel:`record_retention_enabled` configuration key value is set to
-   :guilabel:`true` or the system will not keep local copies.
-
-#. Keep and send records to custom server:
-
-   This assumes you have set up a custom server according to the next example.
-
-   The server is identified by the :guilabel:`server` setting, and by default
-   records are sent to the |CL| server
-   :guilabel:`server=https://clr.telemetry.intel.com/v2/collector`. To change
-   this, you can use an IP address or fully qualified domain name.
-
-
-Set up a back-end server to collect telemetry records
-=====================================================
-
-For this example, start with a clean installation of |CL| on a new system
-using the :ref:`bare-metal-install-server` getting started guide and:
-
-#. Join the :guilabel:`Stability Enhancement Program` to install and
-   enable the telemetrics components.
-
-#. Select the manual installation method with the following settings:
-
-   * Set the hostname to :guilabel:`clr-telem-server`,
-   * Create an administrative user named :guilabel:`clear` and add this user
-     to sudoers
-
-#. Log in with your administrative user, from your :file:`$HOME` directory, 
-   run :command:`git` to clone the :guilabel:`telemetrics-backend` repository
-   into the :file:`$HOME/telemetrics-backend` directory:
-
-   .. code-block:: console
-
-      git clone https://github.com/clearlinux/telemetrics-backend
-
-   .. note::
-
-      You may need to set up the :envvar:`https_proxy` environment variable if
-      you have issues reaching github.com.
-
-#. Change your current working directory to :file:`telemetrics-backend/scripts`.
-#. Before you install the telemetrics backend with the :file:`deploy.sh` script
-   file in the next step, here is an explanation of the options to be specified:
-
-   * :command:`-a install` to perform an install
-   * :command:`-d clr` to install to a |CL| distro
-   * :command:`-H localhost` to set the domain to localhost
-
-   .. caution::
-      The :file:`deploy.sh` shell script has minimal error checking and makes
-      several changes to your system. Be sure that the options you define on
-      the cmdline are correct before proceeding.
-
-#. Run the shell script from the :file:`$HOME/telemetrics-backend/scripts`
-   directory:
-
-   .. code-block:: console
-
-      ./deploy.sh -H localhost -a install -d clr
-
-
-
-   The script starts and lists all the defined options and prompts you for
-   the :guilabel:`PostgreSQL` database password.
-
-   .. code-block:: console
-
-      Options:
-       host: localhost
-       distro: clr
-       action: install
-       repo: https://github.com/clearlinux/telemetrics-backend
-       source: master
-       type: git
-       DB password: (default: postgres):
-
-#. For the :guilabel:`DB password:`, press the :kbd:`Enter` key to accept the
-   default password `postgres`.
-
-   .. note::
-
-      The :file:`deploy.sh` script uses :command:`sudo` to run commands and you
-      may be prompted to enter your user password at any time while the script
-      is executing. If this occurs, enter your user password to execute the
-      :command:`sudo` command.
-
-
-#. After all the server components have been installed, you are prompted to
-   enter the :guilabel:`PostgreSQL` database password to change it as
-   illustrated below:
-
-   .. code-block:: console
-
-      Enter password for 'postgres' user:
-      New password:
-      Retype new password:
-      passwd: password updated successfully
-
-   Enter `postgres` for the current value of the password and then enter a new
-   password, retype it to verify the new password and the :guilabel:`PostgreSQL`
-   database password will be updated.
-
-#. After the installation is complete, you can use your web browser to view the
-   new server by opening the browser on the system and typing in localhost
-   in the address bar. You should see a web page similar to the one shown in
-   Figure 2 below.
-
-   .. figure:: figures/telemetry-backend-1.png
-      :alt: Telemetry UI
-
-      Figure 2: :guilabel:`Telemetry UI`
-
-Create records with telem-record-gen
-====================================
-
-The telemetrics bundle provides a record generator tool called
-`telem-record-gen`. This tool can be used to create records from shell
-scripts or the command line when writing a probe in C is not desirable.
-Records are sent to the backend server, and can also be echoed to stdout.
-
-There are three ways to supply the payload to the record.
-
-#. On the command line, use the :command:`-p <string>` option:
-
-   .. code-block:: bash
-
-      telem-record-gen -c a/b/c -n -o -p 'payload goes here'
-
-   .. code-block:: console
-
-      record_format_version: 4
-      classification: a/b/c
-      severity: 1
-      machine_id: FFFFFFFF
-      creation_timestamp: 1539023189
-      arch: x86_64
-      host_type: innotek GmbH|VirtualBox|1.2
-      build: 25180
-      kernel_version: 4.14.71-404.lts
-      payload_format_version: 1
-      system_name: clear-linux-os
-      board_name: VirtualBox|Oracle Corporation
-      cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz
-      bios_version: VirtualBox
-      event_id: 2236710e4fc11e4a646ce956c7802788
-
-      payload goes here
-
-#. Specify a file that contains the payload with the option
-   :command:`-P path/to/file`.
-
-   .. code-block:: bash
-
-      telem-record-gen -c a/b/c -n -o -P ./payload_file.txt
-
-   .. code-block:: console
-
-      record_format_version: 4
-      classification: a/b/c
-      severity: 1
-      machine_id: FFFFFFFF
-      creation_timestamp: 1539023621
-      arch: x86_64
-      host_type: innotek GmbH|VirtualBox|1.2
-      build: 25180
-      kernel_version: 4.14.71-404.lts
-      payload_format_version: 1
-      system_name: clear-linux-os
-      board_name: VirtualBox|Oracle Corporation
-      cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz
-      bios_version: VirtualBox
-      event_id: d73d6040afd7693cccdfece479df9795
-
-      payload read from file
-
-#. If the :command:`-p` or :command:`-P` options are absent, the tool reads
-   from stdin so you can use it in a :file:`heredoc` in scripts.
-
-   .. code-block:: bash
-
-      #telem-record-gen -c a/b/c -n -o << HEOF
-      payload read from stdin
-      HEOF
-
-   .. code-block:: console
-
-      record_format_version: 4
-      classification: a/b/c
-      severity: 1
-      machine_id: FFFFFFFF
-      creation_timestamp: 1539023621
-      arch: x86_64
-      host_type: innotek GmbH|VirtualBox|1.2
-      build: 25180
-      kernel_version: 4.14.71-404.lts
-      payload_format_version: 1
-      system_name: clear-linux-os
-      board_name: VirtualBox|Oracle Corporation
-      cpu_model: Intel(R) Core(TM) i7-4650U CPU @ 1.70GHz
-      bios_version: VirtualBox
-      event_id: 2f070e8e71679f2b1f28794e3a6c42ee
-
-      payload read from stdin
-
-Set a static machine id
-=======================
-
-The machine id reported by the telemetry client is rotated every three days
-for privacy reasons. If you wish to have a static machine id for testing
-purposes, you can opt in by creating a file named `opt-in-static-machine-id`
-in the directory  :file:`/etc/telemetrics/`.
-
-#. Create a directory `telemetrics`.
-
-   .. code-block:: bash
-
-      sudo mkdir -p /etc/telemetrics
-
-
-#. Create the file and replace the "unique machine ID" with your desired
-   static machine ID.
-
-   .. code-block:: bash
-
-      echo "unique machine ID" | sudo tee /etc/telemetrics/opt-in-static-machine-id
-
-.. note::
-
-   The machine ID is different than the system hostname.
-
-Instrument your code with the libtelemetry API
-==============================================
-
-Prerequisites
--------------
-
-Confirm that the telemetrics header file is located on the system at
-:file:`usr/include/telemetry.h`  The `latest version`_ of the file can also be
-found on github for reference, but installing the :command:`telemetry` bundle
-will install the header file that matches your |CL| version.
-
-#. Includes and variables:
-
-   You must include the following headers in your code to use the API:
-
-   .. code-block:: console
-
-      #define _GNU_SOURCE
-      #include <stdlib.h>
-      #include <stdio.h>
-      #include <string.h>
-      #include <telemetry.h>
-
-
-   Use the following code to create the variables needed to hold the data for
-   the record to be created:
-
-   .. code-block:: console
-
-      uint32_t severity = 1;
-      uint32_t payload_version = 1;
-      char classification[30] = "org.clearlinux/hello/world";
-      struct telem_ref *tm_handle = NULL;
-      char *payload;
-      int ret = 0;
-
-
-
-   Severity:
-    Type: uint32_t
-    Value:  Severity field value. Accepted values are in the range 1-4, with
-    1 being the lowest severity, and 4 being the highest severity. Values
-    provided outside of this range are clamped to 1 or 4. [low, med, high,
-    crit]
-
-   Payload_version:
-    Type: uint32_t
-    Value: Payload format version. The only supported value right now is 1,
-    which indicates that the payload is a freely-formatted (unstructured)
-    string. Values greater than 1 are reserved for future use.
-
-   Classification:
-     Type: char array
-     Value: It should have the form, DOMAIN/PROBENAME/REST: DOMAIN is the 
-     reverse domain to use as a namespace for the probe (e.g. org.clearlinux);
-     PROBENAME is the name of the probe; and REST is an arbitrary value that
-     the probe should use to classify the record. The maximum length for the
-     classification string is 122 bytes. Each sub-category may be no longer
-     than 40 bytes long. Two / delimiters are required.
-
-   Tm_handle:
-     Type: Telem_ref struct pointer
-     Value:  Struct pointer declared by the caller, The struct is initialized
-     if the function returns success.
-
-   Payload:
-     Type: char pointer
-     Value: The payload to set
-
-#. For this example, we'll set the payload to “hello” by using
-   :command:`asprintf()`:
-
-   .. code-block:: console
-
-         if (asprintf(&payload, "hello\n") < 0) {
-           exit(EXIT_FAILURE);
-            }
-
-   The functions :command:`asprintf()` and :command:`vasprintf()` are analogs of
-   :command:`sprintf(3)` and :command:`vsprintf(3)`, except that they allocate a
-   string large enough to hold the output including the terminating null byte
-   ('\0'), and return a pointer to it via the first argument. This pointer
-   should be passed to :command:`free(3)` to release the allocated storage when
-   it is no longer needed.
-
-#. Create the new telemetry record:
-
-   The  function  :command:`tm_create_record()` initializes a telemetry record and
-   sets the severity and classification of that record, as well as the payload
-   version number. The memory needed to store the telemetry record is allocated
-   and should be freed with :command:`tm_free_record()` when no longer needed.
-
-   .. code-block:: console
-
-      if ((ret = tm_create_record(&tm_handle, severity,    classification, payload_version)) < 0) {
-      printf("Failed to create record: %s\n", strerror(-ret));
-      ret = 1;
-      goto fail;
-      }
-
-#. Set the payload field of a telemetrics record:
-
-   The function :command:`tm_set_payload()` attaches the provided telemetry record
-   data to the telemetry record. The current maximum payload size is 8192b.
-
-   .. code-block:: console
-
-      if ((ret = tm_set_payload(tm_handle, payload)) < 0) {
-         printf("Failed to set record payload: %s\n", strerror(-ret));
-         ret = 1;
-         goto fail;
-      }
-      free(payload);
-
-   The :command:`free()` function frees the memory space pointed to by `ptr`, which
-   must have been returned by a previous call to :command:`malloc()`,
-   :command:`calloc()`, or :command:`realloc()`. Otherwise, or if
-   :command:`free(ptr)` has already been called before, undefined behavior
-   occurs. If `ptr` is NULL, no operation is performed.
-
-#. Send a record to the telemetrics daemon:
-
-   The function :command:`tm_send_record()` delivers the record to the local
-   :command:`telemprobd(1)` service. Since the telemetry record was allocated by
-   the program it should be freed with :command:`tm_free_record()` when it is no
-   longer needed.
-
-   .. code-block:: console
-
-      if ((ret = tm_send_record(tm_handle)) < 0) {
-         printf("Failed to send record to daemon: %s\n", strerror(-ret));
-         ret = 1;
-         goto fail;
-      } else {
-         printf("Successfully sent record to daemon.\n");
-         ret = 0;
-      }
-      fail:
-      tm_free_record(tm_handle);
-      tm_handle = NULL;
-
-      return ret;
-
-
-#. A full sample application with compiling flags:
-
-   Create a new file :file:`test.c` and add the following code:
-
-   .. code-block:: console
-
-        #define _GNU_SOURCE
-        #include <stdlib.h>
-        #include <stdio.h>
-        #include <string.h>
-        #include <telemetry.h>
-
-        int main(int argc, char **argv)
-        {
-              uint32_t severity = 1;
-              uint32_t payload_version = 1;
-              char classification[30] = "org.clearlinux/hello/world";
-              struct telem_ref *tm_handle = NULL;
-              char *payload;
-
-              int ret = 0;
-
-              if (asprintf(&payload, "hello\n") < 0) {
-                      exit(EXIT_FAILURE);
-              }
-
-              if ((ret = tm_create_record(&tm_handle, severity, classification, payload_version)) < 0) {
-                      printf("Failed to create record: %s\n", strerror(-ret));
-                      ret = 1;
-                      goto fail;
-              }
-
-              if ((ret = tm_set_payload(tm_handle, payload)) < 0) {
-                      printf("Failed to set record payload: %s\n", strerror(-ret));
-                      ret = 1;
-                      goto fail;
-              }
-
-              free(payload);
-
-              if ((ret = tm_send_record(tm_handle)) < 0) {
-                      printf("Failed to send record to daemon: %s\n", strerror(-ret));
-                      ret = 1;
-                      goto fail;
-              } else {
-                      printf("Successfully sent record to daemon.\n");
-                      ret = 0;
-              }
-        fail:
-              tm_free_record(tm_handle);
-              tm_handle = NULL;
-
-              return ret;
-         }
-
-
-
-   Compile with the gcc compiler, using this command:
-
-   .. code-block:: bash
-
-      gcc test.c -ltelemetry -o test_telem
-
-
-   Test to ensure the program is working:
-
-   .. code-block:: bash
-
-      ./test_telem
-      Successfully sent record to daemon.
-
-   .. note::
-
-      A full example of the `heartbeat probe`_ in C is documented in the
-      source code.
-
-Reference
-*********
-
-.. contents::
-   :local:
-   :depth: 1
-
-The telemetry API
-=================
-
-Installing the :command:`telemetrics` bundle includes the libtelemetry C library,
-which exposes an API used by the telemprobd and telempostd daemons. You can
-use these in your applications as well. The API documentation is found in the
-:file:`telemetry.h` file in `Telemetrics client`_ repository.
-
-Client configuration
-====================
-
-The telemetry client will look for the configuration file located at
-:file:`/etc/telemetrics/telemetrics.conf` and use it if it exists. If the
-file does not exist, the client will use the default configuration located
-at :file:`/usr/share/defaults telemetrics/telemetrics.conf`. To modify or
-customize the configuration, copy the file from
-:file:`/usr/share/defaults/telemetrics` to :file:`/etc/telemetrics` and edit it.
-
-Configuration options
----------------------
-
-The client uses the following configuration options from the config file:
-
-server
-   This specifies the web server to which telempostd sends the telemetry records.
-socket_path
-   This specifies the path of the unix domain socket on which the telemprobd
-   listens for connections from the probes.
-spool_dir
-   This configuration option is related to spooling. If the daemon is not able
-   to send the telemetry records to the backend server due to reasons such as
-   the network availability, then it stores the records in a spool directory.
-   This option specifies the path of the spool directory. This directory should
-   be owned by the same user as the daemon.
-record_expiry
-   This is the time, in minutes, after which the records in the spool directory
-   are deleted by the daemon.
-spool_process_time
-   This specifies the time interval, in seconds, that the daemon waits for
-   before checking the spool directory for records. The daemon picks up the
-   records in the order of modification date and tries to send the record to the
-   server. It sends a maximum of 10 records at a time. If it was able to send a
-   record successfully, it deletes the record from the spool. If the daemon
-   finds a record older than the "record_expiry" time, then it deletes that
-   record. The daemon looks at a maximum of 20 records in a single spool run loop.
-rate_limit_enabled
-   This determines whether rate-limiting is enabled or disabled. When enabled,
-   there is a threshold on both records sent within a window of time, and record
-   bytes sent within a window a time.
-record_burst_limit
-   This is the maximum amount of records allowed to be passed by the daemon
-   within the record_window_length of time. If set to -1, the rate-limiting for
-   record bursts is disabled.
-record_window_length
-   The time, in minutes (0-59), that establishes the window length for the
-   record_burst_limit. For example, if record_burst_window=1000 and
-   record_window_length=15, then no more than 1000 records can be passed within
-   any given fifteen-minute window.
-byte_burst_limit
-   This is the maximum amount of bytes that can be passed by the daemon within
-   the byte_window_length of time. If set to -1, the rate-limiting for byte
-   bursts is disabled.
-byte_window_length
-   This is the time, in minutes (0-59), that establishes the window length for
-   the byte_burst_limit.
-rate_limit_strategy
-   This is the strategy chosen once the rate-limiting threshold has been
-   reached. Currently the options are 'drop' or 'spool', with spool being the
-   default. If spool is chosen, records will be spooled and sent at a later time.
-record_retention_enabled
-   When this key is enabled (true) the daemon saves a copy of the payload on
-   disk from all valid records. To avoid the excessive use of disk space only
-   the latest 100 records are kept. The default value for this configuration key
-   is false.
-record_server_delivery_enabled
-   This key controls the delivery of records to server; when enabled (default
-   value), the record will be posted to the address in the configuration file.
-   If this configuration key is disabled (false), records will not be spooled or
-   posted to backend. This configuration key can be used in combination with
-   record_retention_enabled to keep copies of telemetry records locally only.
-
-  .. note::
-
-  	 Configuration options may change as the telemetry client evolves.
-  	 Please use the comments in the file itself as the most accurate
-  	 reference for configuration.
-
-
-Client run-time options
-=======================
-
-The |CL| telemetry client provides an admin tool called :guilabel:`telemctl`
-for managing the telemetry services and probes. The tool is located in
-:file:`/usr/bin`. Running it with no argument results in the following:
-
-.. code-block:: bash
-
-   sudo telemctl
-
-.. code-block:: console
-
-   /usr/bin/telemctl - Control actions for telemetry services
-     stop       Stops all running telemetry services
-     start      Starts all telemetry services
-     restart    Restarts all telemetry services
-     is-active  Checks if telemprobd and telempostd are active
-     opt-in     Opts in to telemetry, and starts telemetry services
-     opt-out    Opts out of telemetry, and stops telemetry services
-     journal    Prints telemetry journal contents. Use -h argument for more
-                options
-
-start/stop/restart
-------------------
-
-The commands to start, stop and restart the telemetry services manage all
-required services and probes on the system. There is no need to separately
-start/stop/restart the two client daemons telemprobd and telempostd.
-The :command:`restart` command option will call :command:`telemctl stop`
-followed by :command:`telemctl start` .
-
-is-active
----------
-
-The :command:`is-active` option reports whether the two client daemons are
-active. This is useful to verify that the :command:`opt-in` and
-:command:`opt-out` options have taken effect, or to ensure that telemetry is
-functioning on the system. Note that both daemons are verified.
-
-.. code-block:: bash
-
-   sudo telemctl is-active
-
-.. code-block:: console
-
-   telemprobd : active
-   telempostd : active
-
-
-.. _Telemetrics client: https://github.com/clearlinux/telemetrics-client/
-.. _latest version: https://github.com/clearlinux/telemetrics-client/tree/master/src
-.. _heartbeat probe: https://github.com/clearlinux/telemetrics-client/tree/master/src/probes/hello.c
-.. _Intel privacy policies: https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html

_sources/index.rst.txt

@@ -1,47 +0,0 @@
-.. _clear-linux:
-
-|CL-PRJ|
-#############################################
-
-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.
-
-:ref:`about`
-    Clear Linux is a little different from other distros. Here are some
-    important tools and concepts for managing your install.
-
-:ref:`guides`
-    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`
-    |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
-    in our |CL| reference section.
-
-:ref:`faq`
-    Refer to our FAQ section to read commonly asked questions and answers.
-
-.. toctree::
-    :maxdepth: 2
-    :hidden:
-
-    get-started/get-started
-    about
-    guides/guides
-    tutorials/tutorials
-    reference/reference
-    FAQ/faq