Added fix for swupd bundle-add Error

Signed-off-by: Anthony Pray anthony.s.pray@intel.com
When using the docker image you may see error
"Failed to install x of x"
ruining  "swupd clean" will fix the problems.

.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,22 @@
+---
+name: Modify document
+about: Modify a document for the Clear Linux* Project
+title: ''
+labels: P2
+assignees: ''
+
+---
+
+**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,20 @@
+---
+name: New document
+about: Request a new document for the Clear Linux* project
+title: ''
+labels: P2
+assignees: ''
+
+---
+
+**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.

.github/workflows/check.yml

@@ -0,0 +1,23 @@
+name: Check
+
+on: [pull_request]
+
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install dependencies
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        sudo apt-get install -y python3-setuptools
+        pip3 install --user -r requirements.txt
+    - name: Build the docs
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        make py
+        make htmlall
+        

.github/workflows/greetings.yml

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

.github/workflows/main.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches:
+        - master
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install dependencies
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        sudo apt-get install -y python3-setuptools
+        pip3 install --user -r requirements.txt
+    - name: Build the docs
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        make py
+        make htmlall
+    - name: Pre-deploy
+      run: |
+        wget https://github.com/clearlinux/clear-linux-documentation-zh-CN/releases/latest/download/clearlinux-docs-zh-CN.tar.gz
+        mkdir source/_build/html/zh_CN
+        tar xvzf clearlinux-docs-zh-CN.tar.gz -C source/_build/html/zh_CN
+        mv source/_build/html $HOME/output
+    - name: Deploy the docs
+      run: |
+        cd $HOME/output
+        git init
+        git config --global user.name "${GITHUB_ACTOR}"
+        git config --global user.email "${GITHUB_ACTOR}@github.com"
+        git add .
+        git commit -m "latest html output"
+        git push -f https://${GITHUB_ACTOR}:${{secrets.ACCESS_TOKEN}}@github.com/clearlinux/clear-linux-documentation.git HEAD:developmentHTML

.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish
+
+on:
+  push:
+    branches:
+        - publish
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install dependencies
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        sudo apt-get install -y python3-setuptools
+        pip3 install --user -r requirements.txt
+    - name: Build the docs
+      run: |
+        export PATH="$HOME/.local/bin:$PATH"
+        make py
+        make htmlall
+    - name: Pre-deploy
+      run: |
+        wget https://github.com/clearlinux/clear-linux-documentation-zh-CN/releases/latest/download/clearlinux-docs-zh-CN.tar.gz
+        mkdir source/_build/html/zh_CN
+        tar xvzf clearlinux-docs-zh-CN.tar.gz -C source/_build/html/zh_CN
+        mv source/_build/html $HOME/output
+    - name: Deploy the docs
+      run: |
+        cd $HOME/output
+        git init
+        git config --global user.name "${GITHUB_ACTOR}"
+        git config --global user.email "${GITHUB_ACTOR}@github.com"
+        git add .
+        git commit -m "latest html output"
+        git push -f https://${GITHUB_ACTOR}:${{secrets.ACCESS_TOKEN}}@github.com/clearlinux/clear-linux-documentation.git HEAD:latestHTML
+    - name: Publish the docs
+      run: |
+        wget ${{secrets.PUBLISH_URL}}
+        cat clearlinux-latest

.gitignore

@@ -0,0 +1,19 @@
+#Exluding from the tree the html build files
+source/_build
+# ignore vi temporary files
+*.swp
+*~
+.*~
+
+# ignore VS code settings
+.vscode/
+
+# ignore .mo translation files
+*.mo
+
+# ignore artifacts generated by running make py
+cloned_repo
+bundles.html.txt
+
+# ignore the venv, used for running make py
+venv

.gitlab-ci.yml

@@ -0,0 +1,19 @@
+image: alpine
+
+pages:
+  script:
+  - apk --no-cache add python3
+  - python3 -m ensurepip
+  - pip3 install sphinx==1.8.0 docutils==0.14 sphinx_rtd_theme breathe==4.9.1 sphinxcontrib-plantuml sphinx-intl==2.0.0 sphinx-sitemap==1.0.2
+  - 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 htmlall
+  - mv source/_build/html/ public/
+  artifacts:
+    paths:
+    - public
+  only:
+  - rtd-theme

Makefile

@@ -0,0 +1,39 @@
+# Makefile for Sphinx documentation
+
+SHELL := /bin/bash
+
+PY_VERSION ?= 3.6
+
+all:
+	make -C source html
+
+htmlall:
+	make -C source htmlall
+
+htmlzh:
+	make -C source htmlzh
+
+htmlde:
+	make -C source htmlde
+
+html:
+	make -C source html
+
+linkcheck:
+	make -C source linkcheck
+
+py:
+	make -C source py
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+
+clean:
+	make -C source clean
+	rm -rf venv
+
+venv:
+	virtualenv venv;\
+	source venv/bin/activate; \
+	pip3 install -r requirements.txt;

README.rst

@@ -0,0 +1,184 @@
+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.
+
+Clone the documentation repository
+**********************************
+
+Clone the documentation repository to your local machine.
+
+.. code-block:: bash
+
+   git clone https://github.com/clearlinux/clear-linux-documentation
+
+Requirements
+************
+
+Make sure you have Python 3 installed to start.
+
+The Sphinx documentation provides `instructions for installing Sphinx`_
+on various platforms.
+
+Use pip3 to install additional Python dependencies listed in the
+requirements.txt file found in the repository:
+
+.. code-block:: bash
+
+   pip3 install -r requirements.txt
+
+Run the build
+*************
+
+We build our documentation using Sphinx. In the source directory of your
+local clear-linux-documentation repository, preview changes to the
+documentation by building the docs in the default language (English) by
+running ``make html``:
+
+.. code-block:: bash
+
+   make html
+
+.. code-block:: console
+
+   sphinx-build -b html -d _build/doctrees   . _build/html
+   Running Sphinx v1.8.0
+   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 found in ``source/_build/html`` in a web browser
+to view the rendered documentation.
+
+If you want to build the documentation exactly as seen on the website, use
+``make py`` followed by ``make htmlall``. This builds some
+external dependencies and all supported languages.
+
+Use virtualenv 
+**************
+
+To develop documentation in a ``virtualenv``, use the ``venv`` target.
+The Clear Linux OS documentation make target ``venv`` provides a 
+simple development environment that ensures that you have the 
+latest packages and that you manage Python versions separately. Use of the 
+``virtualenv`` requires **Python 3.6** or higher. For Windows examples below, use Powershell as an Administrator.
+
+The **virtual environment** uses the same version of Python that was used to **create the virtual environment**. 
+
+Verify ``pip`` is installed. A file path to pip should appear. 
+
+On Clear Linux OS and macOS\*:
+
+.. code-block:: bash
+
+   which pip
+   
+On Windows\* 10 OS: 
+
+.. code-block:: bash
+
+   pip --version
+
+If ``pip`` is not installed, install it. 
+
+On Clear Linux OS and macOS:
+
+.. code-block:: bash
+
+   python3 -m pip install --user --upgrade pip
+
+On Windows 10 OS: 
+
+.. code-block:: bash
+
+   py -m pip install --upgrade pip
+
+.. note::
+
+   This assumes Python was already added to your Windows path. 
+
+Install virtualenv 
+==================
+
+Install ``virtualenv``. 
+
+On Clear Linux OS and macOS\*:
+
+.. code-block:: bash
+
+   python3 -m pip install --user virtualenv
+
+On Windows 10 OS: 
+
+.. code-block:: bash
+
+   py -m pip install --user virtualenv
+
+Create the ``virtualenv`` and install the required packages: 
+
+.. code-block:: bash
+
+   make venv
+
+Activate the ``venv``. 
+
+.. code-block:: bash
+
+   source venv/bin/activate
+
+Follow `Run the build`_ section to start developing documentation.
+
+Remove the ``venv`` when finished developing.  
+
+.. code-block:: bash
+
+   deactivate
+
+Additional help
+***************
+
+Cleaning up
+===========
+
+When testing changes in the documentation, make sure to remove the previous
+build before building again by running ``make clean``:
+
+.. code-block:: bash
+
+   make clean
+
+This will completely remove the previous build output, including artifacts 
+from the `make venv` target when done outside an active venv.
+
+Convenience script
+==================
+
+This bash script (Linux only) includes both ``make clean`` and
+``make html``. It also starts a simple Python web server that
+displays a preview of the site at http://localhost:8000 on your local machine.
+
+.. code-block:: bash
+
+   ./checkwork.sh
+
+To stop the web server simply use ``ctrl-c``.
+
+.. _Clear Linux\* OS documentation:  https://docs.01.org/clearlinux/
+.. _Sphinx: http://sphinx-doc.org/
+.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _contribution guidelines: https://docs.01.org/clearlinux/latest/collaboration/collaboration.html
+.. _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/autospec-about.rst.txt

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

_sources/concepts/bundles-about.rst.txt

@@ -1,30 +0,0 @@
-.. _bundles-about:
-
-Bundles
-#######
-
-Linux-based operating systems contain the code of several hundred, if
-not thousands, of open source projects. To make this manageable,
-distributions use a concept called "packages" to configure and compile
-the source code of these projects into binaries.
-
-Many distributions then split the content of these compiled packages
-into so-called sub-packages, which are the granularity at which these
-distributions deploy their software. With those kinds of distributions,
-system administrators can then install and update sub-packages
-individually or as a set, using tools such as "yum" and "apt-get."
-
-The |CL-ATTR| takes a slightly different approach. While we also use the
-concept of packages to manage compiling source code into binaries, we do not
-use the package concept to deploy software. Instead, we provide software
-"bundles" that are installed and managed using :ref:`swupd<swupd-about>`.
-Each bundle contains as many or as few open source projects needed to provide a complete functionality.
-
-Next steps
-==========
-
-To put this concept into practice, see the following resources:
-
-* :ref:`bundles`
-* :ref:`bundle-commands`
-* :ref:`compatible-kernels`

_sources/concepts/mixer-about.rst.txt

@@ -1,54 +0,0 @@
-.. _mixer-about:
-
-Mixer
-#####
-
-|CL-ATTR| is a powerful, modular, and customizable OS. Upstream |CL| offers
-many images to support different environments and use-cases.  There are
-hundreds of bundles that will meet most, if not all, of your OS and software
-needs.
-
-However, if you need additional customization or content, |CL| provides the
-mixer tool. Depending on your needs, the mixer tool allows you to:
-
-* :ref:`create-mix` to create a distinct derivative of the |CL| that
-   contains your custom software.
-
-.. _create-mix:
-
-Create a mix
-============
-
-When creating a mix, you can
-
-* Use any existing upstream bundles with no modification.
-* Redefine what goes into existing bundles.
-* Create completely new, custom bundles with your own custom packages.
-
-With mixer you are not required to incorporate every upstream release into
-your mix. You decide which upstream versions to update your derivative to, as
-illustrated in Figure 1.
-
-.. figure:: figures/mixer-about-1.png
-   :scale: 75%
-   :alt: Creating a custom mix.
-
-   Figure 1: With a custom mix, you add your custom bundle and decide which
-   upstream versions to update your mix to, on your own release cycle.
-
-Creating your own mix forks away from the |CL| upstream and requires that you
-act as your own OSV. There is a greater level of responsibility, requiring
-more infrastructure and processes to adopt. However, with this approach, you
-have a higher degree of control and customization of your custom |CL|.
-
-Related topics
-==============
-
-|CL| provides flexibility in how you customize your OS. Learn more about
-mixer and related topics to decide which customization approach is best for
-you.
-
-* :ref:`mixer`
-* :ref:`bundles-about`
-* :ref:`swupd-about`
-* :ref:`deploy-at-scale`

_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/bootable-usb/bootable-usb.rst.txt

@@ -1,208 +0,0 @@
-.. _bootable-usb:
-
-Create a bootable USB drive
-###########################
-
-Follow the instructions applicable to your system to create a bootable |CL-ATTR|
-USB drive:
-
-* :ref:`bootable-usb-linux`
-* :ref:`bootable-usb-mac`
-* :ref:`bootable-usb-windows`
-
-Prerequisites
-*************
-
-* Use an **8GB** or larger USB drive.
-* Download the |CL| live boot image or interactive installer image from the
-  `Downloads`_ page.
-
-.. _bootable-usb-linux:
-
-Create a bootable USB drive on Linux\*
-**************************************
-
-Make sure you have have completed all `Prerequisites`_.
-
-Before burning the image onto your USB drive,
-:ref:`verify and decompress your image <verify-linux>`.
-
-Burn the |CL| image onto a USB drive
-====================================
-
-.. caution::
-
-   |CAUTION-BACKUP-USB|
-
-#. Open a terminal emulator and get root privilege.
-
-   .. code-block:: bash
-
-      sudo -s
-
-#. Go to the directory with the decompressed image.
-
-#. Plug in the USB drive.
-
-#. Identify the USB drive using the :command:`lsblk` command. This shows all
-   drives attached to the system, including the primary hard disk. In the
-   example output below, there are 4 drives
-   (`/dev/sda`, `/dev/sdb`, `/dev/sdc`, and `/dev/sdd`) attached, where
-   `/dev/sda` is primary drive. The remaining are three USB drives. The output
-   also shows the mounted partitions (under the `MOUNTPOINT` column) for each
-   drive.
-
-   .. code-block:: bash
-
-      lsblk
-
-   Example output:
-
-   .. code-block:: console
-
-      NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
-      sdd      8:48   1    15G  0 disk
-      ├─sdd2   8:50   1     5G  0 part /run/media/user1/960c184f-3bb7-42b7-bcaf-0c1282
-      ├─sdd3   8:51   1     8G  0 part /run/media/user1/704f3382-b26d-4f34-af1b-cb9aab
-      └─sdd1   8:49   1     2G  0 part
-      sdb      8:16   1  14.8G  0 disk
-      └─sdb1   8:17   1  14.8G  0 part /run/media/user1/PATRIOT_USB
-      sdc      8:32   1   7.3G  0 disk
-      └─sdc1   8:33   1   7.3G  0 part /run/media/user1/LINUX MINT
-      sda      8:0    0 335.4G  0 disk
-      ├─sda4   8:4    0    28G  0 part
-      ├─sda2   8:2    0   3.7G  0 part [SWAP]
-      ├─sda7   8:7    0     6G  0 part /home
-      ├─sda5   8:5    0     1G  0 part /boot
-      ├─sda3   8:3    0   954M  0 part /boot/efi
-      ├─sda1   8:1    0    28G  0 part
-      ├─sda8   8:8    0    30G  0 part /
-      └─sda6   8:6    0   7.9G  0 part [SWAP]
-
-#. You must unmount a USB drive before burning an image onto it. Note that
-   some Linux distros automatically mount a USB drive when it is plugged in.
-   Unmount a USB drive with the :command:`umount` command followed by the device
-   identifier/partition. For example:
-
-   .. code-block:: bash
-
-      umount /dev/sdd2
-      umount /dev/sdd3
-
-#. Burn the image onto the USB drive. The example below burns an uncompressed
-   image onto `<your USB device>`:
-
-   .. code-block:: bash
-
-      dd if=./clear-[version number]-[image type] of=<your USB device> oflag=sync bs=4M status=progress
-
-.. caution::
-
-   |CAUTION-UNMOUNT-USB-PARTITIONS|
-
-.. _bootable-usb-mac:
-
-Create a bootable USB drive on macOS\*
-**************************************
-
-Make sure you have have completed all `Prerequisites`_.
-
-Before burning the image onto your USB drive,
-:ref:`verify and decompress your image <verify-mac>`.
-
-Burn the |CL| image onto a USB drive
-====================================
-
-.. caution::
-
-   |CAUTION-BACKUP-USB|
-
-#. Launch the Terminal app.
-
-#. Go to the directory with the decompressed image.
-
-#. Plug in a USB drive and get its identifier:
-
-   .. code-block:: bash
-
-      diskutil list
-
-   This will list available disks and their partitions, as shown in Figure 1.
-
-   .. figure:: figures/bootable-usb-mac-01.png
-      :scale: 100 %
-      :alt: Get USB drive identifier
-
-      Figure 1: macOS - Get USB drive identifier
-
-#. Unmount the USB drive identified in the previous step. For example:
-
-   .. code-block:: bash
-
-      diskutil umountDisk /dev/disk2
-
-#. Burn the image onto the drive using the :command:`dd` command.
-   The example below burns an uncompressed image onto `<your USB device>`:
-
-   .. code-block:: bash
-
-      sudo dd if=./clear-[version number]-[image type] of=<your USB device> bs=4m
-
-   To speed up the imaging process, add an ‘r’ in front of the disk identifier.
-   For example `/dev/rdisk2`.
-
-   Press :kbd:`<CTL>-T` to check imaging progress.
-
-#. Eject the USB drive.
-
-   .. code-block:: bash
-
-      diskutil eject /dev/disk2
-
-.. _bootable-usb-windows:
-
-Create a bootable USB drive on Windows\*
-****************************************
-
-Make sure you have have completed all `Prerequisites`_.
-
-Before burning the image onto your USB drive,
-:ref:`verify and decompress your image <verify-windows>`.
-
-Burn the |CL| image onto a USB drive
-====================================
-
-.. caution::
-
-   |CAUTION-BACKUP-USB|
-
-#. Download the `Rufus`_ utility to burn the image onto a USB drive.
-   We use Rufus 3.5 here. **Only use the latest version of Rufus**.
-
-#. Plug in the USB drive and open Rufus.
-
-#. Under `Boot selection`, click the :guilabel:`SELECT` button.
-
-#. Find and select the previously extracted |CL| image file.
-
-#. Click the :guilabel:`START` button. See Figure 2.
-
-   .. figure:: figures/bootable-usb-windows-02.png
-      :scale: 80 %
-      :alt: Rufus utility
-
-      Figure 2: Rufus utility
-
-#. When the dialogue appears, select
-   :guilabel:`Write in ISO image mode (Recommended)`. See Figure 3.
-
-   .. figure:: figures/bootable-usb-windows-03.png
-      :scale: 80 %
-      :alt: ISOHybrid image detected
-
-      Figure 3: ISOHybrid image detected
-
-#. Select the Windows taskbar menu for USB and select eject.
-
-.. _Rufus: https://rufus.ie/
-.. _Downloads: https://clearlinux.org/downloads

_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-preconf.rst.txt

@@ -1,308 +0,0 @@
-.. _vmw-player-preconf:
-
-Run pre-configured |CL-ATTR| image as a VMware\* Workstation Player guest OS
-############################################################################
-
-This page explains how to deploy a pre-configured |CL| VMware image on
-`VMware Workstation 14 Player`_.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-VMware Workstation 14 Player is a type 2 hypervisor. It runs on top of
-another operating system such as Windows\* or Linux\*. With VMware ESXi, you
-can create, configure, manage, and run |CL-ATTR| :abbr:`VMs (Virtual Machines)`
-on your local system.
-
-.. note::
-
-   Screenshots in this document show VMware Workstation 14 Player for Windows.
-   Menus and prompts in the Linux version have minor wording differences.
-
-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 14 Player`_ is available for Windows and Linux.
-   Download your preferred version.
-
-#. Depending on which OS you're running, install it by following one of these
-   instructions:
-
-   * On supported Linux distros:
-
-     #. Enable a GUI desktop.
-
-     #. Start a terminal emulator.
-
-     #. Start the installer by issuing the command below and following the
-        guided steps.
-
-        .. code-block:: bash
-
-           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| VMware image
-*************************************
-
-Get the latest |CL| VMware image from the `image`_ repository.
-Look for :file:`clear-[version number]-vmware.vmdk.xz`. You can also use
-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.
-
-.. include:: ../../guides/maintenance/download-verify-decompress.rst
-   :Start-after: verify-windows:
-
-We also provide instructions for other operating systems:
-
-* :ref:`download-verify-decompress-linux`
-
-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-preconf/vmw-player-preconf-01.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Create a new virtual machine
-
-      Figure 1: VMware Workstation 14 Player - Create a new virtual machine
-
-#. On the :guilabel:`Welcome to the New Virtual Machine Wizard` screen,
-   select the :guilabel:`I will install the operating system later` option.
-   See figure 2.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-02.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Select install operating system
-
-      Figure 2: VMware Workstation 14 Player - Select install operating
-      system later.
-
-#. Click the :guilabel:`Next` button.
-
-#. On the :guilabel:`Select a Guest Operating System` screen, set the
-   :guilabel:`Guest operating system` setting to :guilabel:`Linux`.
-   See figure 3.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-03.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Select guest operating system type
-
-      Figure 3: VMware Workstation 14 Player - Select guest operating system
-      type
-
-#. Set :guilabel:`Version` setting to
-   :guilabel:`Other Linux 3.x or later kernel 64-bit`.
-
-#. Click the :guilabel:`Next` button.
-
-#. On the :guilabel:`Name the Virtual Machine` screen, give your new VM a
-   name. See figure 4.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-04.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Name virtual machine
-
-      Figure 4: VMware Workstation 14 Player - Name virtual machine
-
-#. Click the :guilabel:`Next` button.
-
-#. On the :guilabel:`Specify Disk Capacity` screen, click 
-   the :guilabel:`Next` button. Keep the default disk settings unchanged.
-   When we attach the pre-configured |CL| VMware image, we will remove the
-   default virtual disk and replace it with the pre-configured one. See
-   figure 5.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-05.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Set disk capacity
-
-      Figure 5: VMware Workstation 14 Player - Set disk capacity
-
-#. On the :guilabel:`Ready to Create Virtual Machine` screen, click the
-   :guilabel:`Customize Hardware...` button. See figure 6.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-06.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Customize hardware
-
-      Figure 6: VMware Workstation 14 Player - Customize hardware
-
-#. Under the :guilabel:`Device` list, select :guilabel:`Processors`. See
-   figure 7.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-07.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Set virtualization engine option
-
-      Figure 7: VMware Workstation 14 Player - Set virtualization engine
-      option
-
-#. Under the :guilabel:`Virtualization engine` section,
-   check :guilabel:`Virtualize Intel VT-x/EPT or AMD-V/RVI`.
-
-#. To disconnect the virtual CD/DVD (IDE) since it is not needed, under the
-   :guilabel:`Device` list, select :guilabel:`New CD/DVD (IDE)`. See figure 8.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-08.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Disconnect CD/DVD (IDE)
-
-      Figure 8: VMware Workstation 14 Player - Disconnect CD/DVD (IDE)
-
-#. Under the :guilabel:`Device status` section, uncheck
-   :guilabel:`Connect at power on`.
-
-#. Click the :guilabel:`Close` button.
-
-#. Click the :guilabel:`Finish` button.
-
-Attach the pre-configured |CL| VMware image
-*******************************************
-
-#. Move the downloaded and decompressed pre-configured |CL| VMware image file
-   :file:`clear-[version number]-basic.vmdk` to the directory where your
-   newly-created VM resides.
-
-   .. 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`
-
-#. On the :guilabel:`VMware Workstation Player` home screen, select your 
-   newly-created VM. See figure 9.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-09.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Edit virtual machine settings
-
-      Figure 9: VMware Workstation 14 Player - Edit virtual machine settings
-
-#. Click :guilabel:`Edit virtual machine settings`.
-
-#. To remove the default hard disk, under the :guilabel:`Device` list, select
-   :guilabel:`Hard Disk (SCSI)`. See figure 10.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-10.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Remove hard drive
-
-      Figure 10: VMware Workstation 14 Player - Remove hard drive
-
-#. Click the :guilabel:`Remove` button.
-
-#. To add a new hard disk and attach the pre-configured |CL| VMware image,
-   click the :guilabel:`Add...` button. See Figure 11.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-11.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Add new hard drive
-
-      Figure 11: VMware Workstation 14 Player - Add new hard drive
-
-#. Under the :guilabel:`Hardware types` section, select :guilabel:`Hard Disk`.
-
-#. Click the :guilabel:`Next` button.
-
-#. Select your preferred :guilabel:`Virtual disk type`. See figure 12.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-12.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Select virtual disk type
-
-      Figure 12: VMware Workstation 14 Player - Select virtual disk type
-
-#. Select the :guilabel:`Use an existing virtual disk` option. See figure 13.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-13.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Use existing virtual disk
-
-      Figure 13: VMware Workstation 14 Player - Use existing virtual disk
-
-#. Click the :guilabel:`Browse` button and select the pre-configured |CL|
-   VMware image file. See figure 14.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-14.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Select ready-made VMware |CL|
-
-      Figure 14: VMware Workstation 14 Player - Select ready-made VMware |CL|
-      image file
-
-#. Click the :guilabel:`Finish` button.
-
-   .. note::
-
-      When asked to convert the existing virtual disk to a newer format,
-      selecting either option works.
-
-Enable UEFI boot support
-************************
-
-|CL| needs UEFI support to boot. To enable it, 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`
-
-Power on the VM
-***************
-
-After configuring the settings above, power on your |CL| virtual machine.
-
-#. On the :guilabel:`VMware Workstation Player` home screen, select your 
-   VM. See figure 15.
-
-   .. figure:: figures/vmw-player-preconf/vmw-player-preconf-15.png
-      :scale: 100%
-      :alt: VMware Workstation 14 Player - Power on virtual machine
-
-      Figure 15: VMware Workstation 14 Player - Power on virtual machine
-
-#. Click :guilabel:`Play virtual machine`.
-
-Related topics
-**************
-
-For other guides on using the VMWare Player and ESXi, see:
-
-* :ref:`vmw-player`
-* :ref:`vmware-esxi-install-cl`
-* :ref:`vmware-esxi-preconfigured-cl-image`
-
-.. _VMware ESXi: https://www.vmware.com/products/esxi-and-esx.html
-.. _VMware Workstation 14 Player: https://www.vmware.com/products/workstation-player.html
-.. _VMware Workstation Player Documentation: https://docs.vmware.com/en/VMware-Workstation-Player/index.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-install-cl.rst.txt

@@ -1,288 +0,0 @@
-.. _vmware-esxi-install-cl:
-
-Install |CL-ATTR| as a VMware\* ESXi guest OS
-#############################################
-
-This page explains how to create a new :abbr:`VM (Virtual Machine)` and
-manually install |CL-ATTR| on the new VM with VMware ESXi 6.5.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-`VMware ESXi`_ is a type 1 bare-metal hypervisor that runs directly on top
-of server hardware. With VMware ESXi, you can create, configure, manage, and
-run |CL| virtual machines in the cloud.
-
-Manually installing |CL| on a new VM gives additional configuration flexibility
-during installation. For example: alternate disk sizes, number of partitions,
-pre-installed bundles, etc.
-
-If you prefer to use a preconfigured |CL| VMware image instead, refer to
-:ref:`vmware-esxi-preconfigured-cl-image`.
-
-.. 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.
-
-   Visit :ref:`image-types` to learn more about all available images.
-
-Download the latest |CL| installer ISO
-**************************************
-
-Get the latest |CL| installer ISO image from the `image`_ repository.
-Look for :file:`clear-[version number]-installer.iso.xz`.
-
-We also provide instructions for downloading and verifying a Clear Linux ISO.
-For more information, refer to :ref:`download-verify-decompress`.
-
-Upload the |CL| installer ISO to the VMware server
-**************************************************
-
-#.  Connect to the VMware server and log into an account with sufficient 
-    permission to create and manage VMs.  
-#.  Under the :guilabel:`Navigator` window, select :guilabel:`Storage`. 
-    See Figure 1.
-#.  Under the :guilabel:`Datastores` tab, click the :guilabel:`Datastore browser` 
-    button.   
-    
-    .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-1.png
-      :scale: 100 %
-      :alt: VMware ESXi - Navigator > Storage 
-
-      Figure 1: VMware ESXi - Navigator > Storage 
-
-#.  Click the :guilabel:`Create directory` button and name the directory `ISOs`.
-    See Figure 2.
-
-    .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-2.png
-      :scale: 100 %
-      :alt: VMware ESXi - Datastore > Create directory 
-
-      Figure 2: VMware ESXi - Datastore > Create directory 
-   
-#.  Select the newly-created directory and click the :guilabel:`Upload` button.
-    See Figure 3.
-
-    .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-3.png
-      :scale: 100 %
-      :alt: VMware ESXi - Datastore > Upload ISO 
-
-      Figure 3: VMware ESXi - Datastore > Upload ISO 
-   
-#.  Select the decompressed |CL| installer ISO file :file:`clear-[version number]-installer.iso` 
-    and upload it.
-
-Create and configure a new VM
-*****************************
-
-In this section, you will create a new VM, configure its basic parameters such 
-as drive size, number of CPUs, memory size, and then attach the |CL| installer ISO. 
-
-#.  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-install-cl-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-install-cl-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-install-cl-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-install-cl-7.png
-          :scale: 100 %
-          :alt: VMware ESXi - Enable hardware virtualization
-      
-          Figure 7: VMware ESXi - Enable hardware virtualization
-
-    #.  Set :guilabel:`Memory` size to 2048MB (2GB). See Figure 8.
-
-        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-8.png
-          :scale: 100 %
-          :alt: VMware ESXi - Set memory size
-
-          Figure 8: VMware ESXi - Set memory size
-
-        .. note:: 
-
-          The |CL| installer ISO needs a minimum of 2GB of RAM to work properly.
-          You can reduce the memory size after the installation completes if you want, 
-          because a minimum |CL| installation can function on as little as 128MB of RAM.
-          See :ref:`system-requirements` for more details.  
-
-    #.  Set :guilabel:`Hard disk 1` to the desired capacity. See Figure 9.
-
-        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-9.png
-          :scale: 100 %
-          :alt: VMware ESXi - Set hard disk size
-
-          Figure 9: VMware ESXi - Set hard disk size
-
-        .. note::
-
-          A minimum |CL| installation can exist on 600MB of drive space.  
-          See :ref:`system-requirements` for more details.       
-
-    #.  Attach the |CL| installer ISO.  For the :guilabel:`CD/DVD Drive 1` setting, 
-        click the drop-down list to the right of it and select the :guilabel:`Datastore ISO file`
-        option.  Then select the |CL| installer ISO :file:`clear-[version number]-installer.iso` 
-        that you previously uploaded to the VMware server. See Figure 10.
-
-        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-10.png
-          :scale: 100 %
-          :alt: VMware ESXi - Set CD/DVD to boot installer ISO
-
-          Figure 10: VMware ESXi - Set CD/DVD to boot installer ISO
-
-#.  Click the :guilabel:`Next` button.
-#.  Click the :guilabel:`Finish` button.
-
-Install |CL| into the new VM
-****************************
-
-#.  Power on the VM.
-    
-    #.  Under the :guilabel:`Navigator` window, select :guilabel:`Virtual Machines`.
-        See Figure 11.
-    #.  In the right window, select the newly-created VM.
-    #.  Click the :guilabel:`Power on` button.  
-    #.  Click on the icon representing the VM to bring it into view and maximize
-        its window.  
-
-        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-11.png
-          :scale: 100 %
-          :alt: VMware ESXi - Navigator > Virtual Machines > Power on VM
-
-          Figure 11: VMware ESXi - Navigator > Virtual Machines > Power on VM
-
-#.  Follow the :ref:`install-on-target-start` guide to complete the installation of 
-    |CL|.
-#.  After the installation is complete, follow the |CL| instruction to reboot it.  
-    This will restart the installer again. 
-
-Reconfigure the VM's settings to boot the newly-installed |CL|
-**************************************************************
-
-After |CL| has been installed using the installer ISO, it must be detached so
-it will not run again.  Also, in order to boot the newly-installed |CL|, you must
-enable UEFI support. 
-
-#.  Power off the VM.
-
-    #.  Click the :guilabel:`Actions` button - located on the top-right corner 
-        of the VM's windows - and go to the :guilabel:`Power` setting and  
-        select the :guilabel:`Power off` option. See Figure 12. 
-
-        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-12.png
-          :scale: 100 %
-          :alt: VMware ESXi - Actions > Power off
-
-          Figure 12: VMware ESXi - Actions > Power off
-
-#.  Edit the VM settings.
-
-    #.  Click the :guilabel:`Actions` button again and select :guilabel:`Edit settings`.  
-        See Figure 13.
-
-        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-13.png
-          :scale: 100 %
-          :alt: VMware ESXi - Actions > Edit settings
-
-          Figure 13: VMware ESXi - Actions > Edit settings
-
-#.  Disconnect the CD/DVD to stop it from booting the |CL| installer ISO again.
-    
-    #.  Click the :guilabel:`Virtual Hardware` button.  See Figure 14.
-    #.  For the :guilabel:`CD/DVD Drive 1` setting, uncheck the 
-        :guilabel:`Connect` checkbox.
-
-        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-14.png
-          :scale: 100 %
-          :alt: VMware ESXi - Disconnect the CD/DVD drive
-
-          Figure 14: VMware ESXi - Disconnect the CD/DVD drive
-
-#.  |CL| needs UEFI support in order to boot.  Enable it.
-
-    #.  Click the :guilabel:`VM Options` button. See Figure 15.
-    #.  Expand the :guilabel:`Boot Options` setting.
-    #.  For the :guilabel:`Firmware` setting, click the drop-down list to the right 
-        of it and select the :guilabel:`EFI` option.
-
-        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-15.png
-          :scale: 100 %
-          :alt: VMware ESXi - Set boot firmware to EFI
-
-          Figure 15: VMware ESXi - Set boot firmware to EFI
-
-#.  Click the :guilabel:`Save` 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 16.
-#.  In the right window, select the 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-install-cl-16.png
-      :scale: 100 %
-      :alt: VMware ESXi - Navigator > Virtual Machines > Power on VM
-
-      Figure 16: VMware ESXi - Navigator > Virtual Machines > Power on VM
-
-Related topics
-**************
-
-* :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
-.. _image: https://cdn.download.clearlinux.org/image

_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/autospec.rst.txt

@@ -1,511 +0,0 @@
-.. _autospec:
-
-autospec
-########
-
-**autospec** is a tool used to assist with the automated creation and maintenance of
-RPM packaging in |CL-ATTR|. Where a standard :abbr:`RPM (RPM Package Manager)` build process using
-:command:`rpmbuild` requires a tarball and :file:`.spec` file to start, autospec
-requires only a tarball and package name to start.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Description
-***********
-
-The autospec tool attempts to infer the requirements of the :file:`.spec` file
-by analyzing the source code and :file:`Makefile` information. It 
-continuously runs updated builds based on new information discovered from build
-failures until it has a complete and valid :file:`.spec` file. If needed, you
-can influence the behavior of autospec and customize the build by providing
-optional `control files`_ to the autospec tool.
-
-autospec uses **mock** as a sandbox to run the builds. Visit the `mock wiki`_ for
-additional information on using mock.
-
-For a general understanding of how an RPM works, visit 
-the `rpm website`_ or the `RPM Packaging Guide`_ .
-
-How it works
-************
-
-Learn the autospec tool set up and process.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Prerequisites
-=============
-
-The setup for building source in |CL| must be completed before using the
-autospec tool.
-
-Refer to `Setup environment to build source`_ for instructions on completing
-the setup.
-
-Create an RPM
-=============
-
-The basic autospec process is described in the following steps:
-
-#. The :command:`make autospec` command generates a :file:`.spec` file based on
-   the analysis of code and existing control files.
-
-   Any control files should be located in the same directory as the resulting
-   :file:`.spec` file.
-
-   View the `autospec README`_ for more information on `control files`_.
-
-#. autospec creates a build root with mock config.
-
-#. autospec attempts to build an RPM from the generated :file:`.spec`.
-
-#. autospec detects any missed declarations in the :file:`.spec`.
-
-#. If build errors occur, autospec scans the build log to try to detect
-   the root cause.
-
-#. If autospec detects the root cause and knows how to continue, it restarts
-   the build automatically at step 1 with updated build instructions.
-
-#. Otherwise, autospec stops the build for user inspection to resolve the
-   errors. Respond to the build process output by fixing source code issues
-   and/or editing control files to resolve issues, which may include
-   dependencies or exclusions. See `autospec README`_ for more information on
-   control files.
-
-   The user resumes the process at step 1 after errors are resolved.
-
-   If a binary dependency doesn't exist in |CL|, you must build it
-   before running autospec again.
-
-Following these steps, autospec continues to rebuild the package, based on
-new information discovered from build failures, until it has a valid
-:file:`.spec`. If no build errors occur, RPM packages are successfully built.
-
-Examples
-********
-
-Complete `Setup environment to build source`_ before using these examples.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Example 1: Build RPM with an existing spec file
-===============================================
-
-This example shows how to build a RPM from a pre-packaged upstream package with
-an existing spec file. The example uses the ``dmidecode`` package.
-
-#. Navigate to the autospec workspace and clone the ``dmidecode`` package:
-
-   .. code-block:: bash
-
-      cd ~/clearlinux
-      make clone_dmidecode
-
-   .. note::
-
-      You can clone all package repos at once using the following command:
-
-      .. code-block:: bash
-
-         make [-j NUM] clone-packages
-
-      The optional NUM is the number of threads to use.
-
-      For a list of available packages, view the
-      :file:`~/clearlinux/projects/common/packages` file.
-
-#. Navigate to the local copy of the ``dmidecode`` package and build it:
-
-   .. code-block:: bash
-
-      cd ~/clearlinux/packages/dmidecode/
-      make build
-
-#. The resulting RPMs are in :file:`./rpms`. Build logs and additional RPMs are
-   in :file:`./results`.
-
-Example 2: Build a new RPM
-==========================
-
-This example shows how to build a new RPM with no spec file. The example will
-create a simple helloclear RPM.
-
-#. Navigate to the autospec workspace and build the helloclear RPM. The
-   :file:`Makefile` provides a :command:`make autospecnew` that can
-   automatically generate an RPM package using the autospec tool. You must pass
-   the URL to the source tarball and the NAME of the RPM you wish to create:
-
-   .. code-block:: bash
-
-      cd ~/clearlinux
-      make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz" NAME="helloclear"
-
-   The resulting RPMs are in :file:`./packages/helloclear/rpms`. Build logs and
-   additional RPMs are in :file:`./packages/helloclear/results`.
-
-Example 3: Generate a new spec file with a pre-defined package
-==============================================================
-
-This example shows how to modify an existing package to create a custom RPM. In
-this example you will make a simple change to the ``dmidecode`` package and
-rebuild the package.
-
-#. Navigate to the autospec workspace and clone the ``dmidecode`` package:
-
-   .. code-block:: bash
-
-      cd ~/clearlinux
-      make clone_dmidecode
-
-#. Navigate into the *dmidecode* directory:
-
-   .. code-block:: bash
-
-      cd packages/dmidecode
-
-#. Open the :file:`excludes` file with an editor and add these lines:
-
-   .. code-block:: console
-
-      /usr/bin/biosdecode
-      /usr/bin/ownership
-      /usr/bin/vpddecode
-      /usr/share/man/man8/biosdecode.8
-      /usr/share/man/man8/ownership.8
-      /usr/share/man/man8/vpddecode.8
-
-   .. note::
-
-      These files aren't needed by dmidecode, so we can remove them without
-      any issues.
-
-#. In the :file:`dmidecode` directory, build the modified ``dmidecode`` package:
-
-   .. code-block:: bash
-
-      make autospec
-
-#. The resulting RPMs are in :file:`./rpms`. Logs are in :file:`./results`.
-
-Example 4: Provide control files to autospec
-============================================
-
-This example shows how to modify control files to correct build failures that
-autospec is unable to resolve. In this example, you will add a missing license
-and dependencies so autospec can complete a successful build.
-
-#. Navigate to the autospec workspace:
-
-   .. code-block:: bash
-
-      cd ~/clearlinux
-
-#. If you have not already, clone all upstream package repos:
-
-   .. code-block:: bash
-
-      make [-j NUM] clone-packages
-
-   The optional NUM is the number of threads to use.
-
-   .. note::
-
-      In a later step of this example, we will search the cloned package repos
-      for a missing dependency.
-
-#. Build the opae-sdk RPM:
-
-   .. code-block:: bash
-
-      make autospecnew URL="https://github.com/OPAE/opae-sdk/archive/0.13.0.tar.gz" NAME="opae-sdk"
-
-   This results in an error for a missing license file:
-
-   .. code-block:: console
-
-      [FATAL]    Cannot find any license or opae-sdk.license file!
-
-#. Navigate to the package with build failures:
-
-   .. code-block:: bash
-
-      cd packages/opae-sdk
-
-#. Add one or more valid license identifiers from the
-   `SPDX License List <https://spdx.org/licenses/>`_.
-   In the example below, two different licenses are appropriate based on the 
-   opae-sdk project licensing:
-
-   .. code-block:: bash
-
-      echo "BSD-3-Clause MIT" > opae-sdk.license
-
-#. Run autospec again:
-
-   .. code-block:: bash
-
-      make autospec
-
-   This results in a generic error:
-
-   .. code-block:: console
-
-      [FATAL]    Build failed, aborting
-
-#. Open the build log to view the error details:
-
-   .. code-block:: bash
-
-      cat ./results/build.log
-
-   The build log contains details for the specific failures. In this
-   instance, there are missing dependencies:
-
-   .. code-block:: console
-
-      CMake Error: The following variables are used in this project, but they are set to NOTFOUND.  Please set them or make sure they are set and tested correctly in the CMake files:
-      CJSON_LIBRARY
-         linked by target "opae-c++-utils" in directory /builddir/build/BUILD/opae-sdk-0.13.0/tools/c++utilslib
-      json-c_LIBRARIES
-         linked by target "opae-c" in directory /builddir/build/BUILD/opae-sdk-0.13.0/libopae
-      libuuid_LIBRARIES
-         linked by target "opae-c" in directory /builddir/build/BUILD/opae-sdk-0.13.0/libopae
-
-#. Search the spec files of upstream |CL| packages to see if the json-c library
-   is available. In this case, it does exist and we'll add the json-c 'dev'
-   package into the buildreq_add:
-
-   .. code-block:: bash
-
-      grep 'json-c\.so$' ~/clearlinux/packages/*/*.spec
-      echo "json-c-dev" >> buildreq_add
-
-   .. note::
-
-      This search step works only if the user cloned all of the upstream package
-      repos. In this example, upstream package repos were cloned in a previous
-      step.
-
-#. Search the spec files of upstream |CL| packages to see if the libuuid library
-   is available. In this case, it exists in the util-linux package, so we'll add
-   util-linux-dev package into the buildreq_add:
-
-   .. code-block:: bash
-
-      grep 'libuuid\.so$' ~/clearlinux/packages/*/*.spec
-      echo "util-linux-dev" >> buildreq_add
-
-#. Run autospec again and find the successfully-generated RPMs in the :file:`rpms`
-   directory:
-
-   .. code-block:: bash
-
-      make autospec
-
-.. note::
-
-   If you need a dependency that does not exist in the |CL| repo, you must first
-   build it manually (see `Example 2: Build a new RPM`_), then add the repo so
-   that autospec knows the package exists. For example:
-
-   .. code-block:: bash
-
-      cd ~/clearlinux/packages/<package-name>
-      make repoadd
-      make repostatus
-
-   You only need to add the dependency to the :file:`buildreq_add` control file
-   if autospec is not able to automatically find the correct dependency on its
-   own.
-
-Test packaged software
-**********************
-
-After software has been packaged with autospec, the resulting RPMs can be
-tested for functionality before being integrated and deployed into a |CL|
-image with the :ref:`Mixer tool <mixer>`.
-
-The |CL| development tooling offers two ways to quickly test autospec
-generated RPMs.
-
-.. note::
-   The methods outlined below should only be used for temporary testing on
-   development systems. 
-
-
-Test in a |CL| virtual machine
-==============================
-
-The |CL| development tooling includes a method to install RPMs into a |CL|
-virtual machine running on the KVM hypervisor. Using a :abbr:`VM (Virtual
-Machine)` allows testing in a completely isolated environment. 
-
-To test an autospec-created package inside a VM:
-
-#. Download the |CL| KVM image into the :file:`~/clearlinux` directory as
-   :file:`clear.img`. The location and name :file:`clear.img.xz` is important
-   for the tooling to work:
-
-   .. code-block:: bash
-
-      cd ~/clearlinux
-      curl -o clear.img.xz https://download.clearlinux.org/image/$(curl https://download.clearlinux.org/image/latest-images | grep '[0-9]'-kvm)
-
-#. Extract the downloaded |CL| KVM image:
-
-   .. code-block:: bash
-
-      unxz -v clear.img.xz
-
-#. Copy the QEMU start script and virtual firmware needed for KVM into the
-   :file:`~/clearlinux` directory:
-
-   .. code-block:: bash
-
-      cp ~/clearlinux/projects/common/start_qemu.sh .
-      cp /usr/share/qemu/OVMF.fd .
-
-#. Run :command:`make install` from the package's autospec directory. The
-   :command:`make install` command mounts the downloaded |CL| KVM image and
-   installs the autospec-created RPM into it:
-
-   .. code-block:: bash
-
-      cd ~/clearlinux/packages/<package-name>
-      make install
-
-   The code that makes this possible can be viewed by searching for the
-   *install:*  target in the `Makefile.common`_ file on GitHub.
-
-#. Return to the :file:`~/clearlinux` directory and start the |CL| VM:
-
-   .. code-block:: bash
-
-      cd ~/clearlinux/
-      sudo ./start_qemu.sh clear.img
-
-#. A new |CL| VM will launch in the console. Log into the VM as *root* and set
-   a new pasword for the VM.
-
-#. Check that the software is installed in the |CL| VM as expected and perform
-   any relevant tests.
-
-#. After testing has been completed, the |CL| VM can be powered off and
-   deleted:
-
-   .. code-block:: bash
-      
-      poweroff 
-      rm clear.img
-
-
-Test directly on a development machine
-======================================
-
-The |CL| development tooling also includes a method to extract
-autospec-created RPMs locally onto a |CL| development system for testing.
-Extracting an RPM directly onto a system  offers quicker testing; however
-conflicts may occur and responsibility to remove the software after testing is
-up to the developer.
-
-To test an autospec created package directly on the |CL| development system:
-
-#. Run :command:`make install-local` from the package's autospec directory.
-   The :command:`make install-local` command extracts the RPM directly onto
-   the filesystem of the running |CL| system:
-
-   .. code-block:: bash
-
-      cd ~/clearlinux/packages/<package-name>
-      make install-local
-
-   The code that makes this possible can be viewed by searching for the
-   *install-local:*  target in the `Makefile.common`_  file on GitHub.
-
-#. Check that the software is installed as expected and perform any relevant
-   tests.
-
-#. After testing has been completed, the software and any related files must
-   be identified and deleted. The :command:`swupd repair --picky`
-   command can help restore the state of the :file:`/usr` directory (see
-   :ref:`swupd <swupd-about>`) however any other files must be cleaned up
-   manually.
-
-
-References
-**********
-
-Reference the `autospec README`_ for details regarding `autospec` commands and options.
-
-Setup environment to build source
-=================================
-
-.. _install-tooling-after-header:
-
-Setup of the workspace and tooling used for building source in |CL| is mostly
-automated for you with a setup script. It uses tools from the
-:command:`os-clr-on-clr` bundle.
-
-The setup script creates a workspace in the :file:`clearlinux` folder, with the
-subfolders :file:`Makefile`, :file:`packages`, and :file:`projects`. The
-:file:`projects` folder contains the main tools used for making packages in
-|CL| :file:`autospec` and :file:`common`.
-
-Follow these steps to setup the workspace and tooling for building source:
-
-#. Install the :command:`os-clr-on-clr` bundle:
-
-   .. code-block:: bash
-
-        sudo swupd bundle-add os-clr-on-clr
-
-#. Download the :file:`user-setup.sh` script:
-
-   .. code-block:: bash
-
-      curl -O https://raw.githubusercontent.com/clearlinux/common/master/user-setup.sh
-
-#. Make :file:`user-setup.sh` executable:
-
-   .. code-block:: bash
-
-      chmod +x user-setup.sh
-
-#. Run the script as an unprivileged user:
-
-   .. code-block:: bash
-
-      ./user-setup.sh
-
-#. After the script completes, log out and log in again to complete the setup
-   process.
-
-#. Set your Git user email and username for the repos on your system:
-
-   .. code-block:: bash
-
-      git config --global user.email "you@example.com"
-      git config --global user.name "Your Name"
-
-   This global setting is used by |CL| tools that make use of Git.
-
-.. _install-tooling-end:
-
-Related topics
-**************
-
-* :ref:`Mixer tool <mixer>`
-
-.. _`Makefile.common`: https://github.com/clearlinux/common/blob/master/Makefile.common
-.. _autospec README: https://github.com/clearlinux/autospec
-.. _control files: https://github.com/clearlinux/autospec#control-files
-.. _mock wiki: https://github.com/rpm-software-management/mock/wiki
-.. _rpm website: http://rpm.org
-.. _RPM Packaging Guide: https://rpm-packaging-guide.github.io/

_sources/guides/clear/ister.rst.txt

@@ -1,93 +0,0 @@
-.. _ister:
-
-ister.py image builder
-######################
-
-The `ister.py`_ tool is a template-based installer used by |CL-ATTR| to produce
-images for each release. The same ister tool is available for use in |CL| to
-create custom images based on an upstream image.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Description
-***********
-
-|CL| is a rolling release and produces an average of 10 releases per week using the
-ister tool. With each release we produce multiple
-:ref:`image types for different environments <image-types>` and use cases such
-as installers, Hyper-V, KVM, or VMWare.
-
-Each image has a JSON configuration file that is used by ister to generate the 
-image. These JSON configuration files describe the image type, partitions, version,
-and bundles that will be preinstalled by default with the image. For each image
-type we produce, the corresponding JSON configuration file for the image also is
-published.
-
-The :ref:`mixer<mixer>` tool also uses ister to build images for your custom
-mix. Like upstream images, a JSON configuration file is defined for the image,
-which ister uses to generate the image. Refer to the :ref:`mixer<mixer>` guide
-for instructions on using ister to build an image for a custom mix.
-
-Examples
-********
-
-Recreate an upstream image
-==========================
-
-The published configuration files for upstream images may be used to recreate an
-image. Here are some examples:
-
-* Use an older version of |CL| and the image is no longer available (only after
-  March 2017).
-* Customize the partitions of an image.
-* Customize the bundles preinstalled in an image.
-* Run your own post installation script.
-
-
-Follow these steps to recreate an upstream image based on the image's JSON
-configuration file:
-
-#. Install the :command:`os-installer` bundle. Refer to :ref:`swupd-guide` for
-   more information on installing bundles.
-
-#. Download the `ister.py`_ tool and grant it sudo privileges.
-
-#. Download the JSON configuration file for the desired image (located in
-   :file:`config/image/`):
-
-   * `Current release`_
-   * `Previous releases`_ (only after March 2017)
-
-   For a previous release, navigate to `Previous releases`_, select the version
-   you want, and find the JSON configuration file under
-   :file:`/clear/config/image`. For example:
-   ``https://cdn.download.clearlinux.org/releases/15700/clear/config/image/``
-
-#. Download the “PostNonChroot” script (if applicable).
-
-   The JSON configuration file for the image may have an accompanying
-   “PostNonChroot” script that is executed at the end of the image creation
-   process. If it does, download the script and make it executable.
-
-#. Edit the JSON configuration file as needed.
-
-#. If your configuration file has an accompanying "PostNonChroot" script, change
-   the default path of the script to match your path.
-
-#. Generate the new image with the following command:
-
-   .. code-block:: bash
-
-   	sudo ister.py -t [JSON configuration]
-
-Related topics
-**************
-
-* :ref:`mixer`
-* :ref:`bulk-provision`
-
-.. _ister.py: https://github.com/bryteise/ister
-.. _Current release: https://cdn.download.clearlinux.org/current/
-.. _Previous releases: https://cdn.download.clearlinux.org/releases/

_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/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/deploy-at-scale.rst.txt

@@ -1,255 +0,0 @@
-.. _deploy-at-scale:
-
-Deploy at Scale
-###############
-
-This guide describes deployment considerations and strategies when deploying
-|CL-ATTR| at scale in your environment.
-
-.. contents::
-    :local:
-    :depth: 1
-
-Overview
-********
-
-In this guide the term *endpoint* refers to a system targeted for |CL|
-installation, whether that is a datacenter system or unit deployed in field.
-
-.. note::
-
-    This guide is not a replacement or blueprint for designing your own IT
-    operating environment.
-
-    Implementation details for a scale deployment are beyond the scope of this
-    guide.
-
-    Your |CL| deployment should complement your existing environment and
-    available tools. It is assumed core IT dependencies of your environment,
-    such as your network, are healthy and scaled to suit the deployment.
-
-Pick a usage and update strategy
-********************************
-
-Different business scenarios call for different deployment methodologies.
-|CL| offers the flexibility to continue consuming the upstream |CL|
-distribution or the option to fork away from the |CL| distribution and
-act as your own :abbr:`OSV (Operating System Vendor)`.
-
-Below is an overview of some considerations.
-
-Create your own Linux distribution (mix)
-========================================
-
-This approach forks away from the |CL| upstream and has you act as your own
-:abbr:`OSV (Operating System Vendor)` by leveraging the :ref:`mixer` process to
-create customized images based on |CL|. This is a level of responsibility
-that requires having more infrastructure and processes to adopt. In return,
-this approach *offers you a high degree of control and customization*. Consider:
-
-* Development systems that generate bundles and updates should have
-  sufficient performance for the task and be separate from the swupd update
-  webservers that serve update content to production machines.
-
-* swupd update webservers that serve update content to production machines
-  should be appropriately scaled. Specific implementation details for a scalable,
-  resilient web server are beyond the scope of this document.
-
-  (See :ref:`mixer` for more information about update servers.)
-
-Adopt an agile methodology
-==========================
-
-The cloud, and other scaled deployments, are all about flexibility and speed.
-It only makes sense that any |CL| deployment strategy should follow suit.
-
-Manually rebuilding your own bundles or mix for every release is not
-sustainable at a large scale. A |CL| deployment pipeline should be agile
-enough to validate and produce new versions with speed. Whether or not those
-updates actually make their way to your production can be separate
-business decision. However this *ability to frequently roll new versions* of
-software to your endpoints is an important prerequisite.
-
-You own the validation and lifecycle of the OS and should treat it like any
-other software development lifecycle. Below are some pointers:
-
-* Thoroughly understand the custom software packages that you will need to
-  integrate with |CL| and maintain along with their dependencies.
-
-* Setup a path to production for building |CL| based images. At minimum this
-  should include:
-
-  * A development clr-on-clr environment to test building packages and
-    bundles for |CL| systems.
-
-  * A pre-production environment to deploy |CL| versions to before
-    production
-
-* Employ a continuous integration and continuous deployment (CI/CD)
-  philosophy in order to:
-
-  - Automatically pull custom packages as they are updated from their
-    upstream projects or vendors.
-
-  - Generate |CL| bundles and potentially bootable images with your
-    customizations, if any.
-
-  - Measure against metrics and indicators which are relevant to your
-    business (e.g. performance, power, etc) from release to release.
-
-  - Integrate with your organization's governance processes, such as change
-    control.
-
-Versioning infrastructure
-=========================
-
-|CL| version numbers are very important as they apply to the whole
-infrastructure stack from OS components to libraries and applications.
-
-Good record keeping is important, so you should keep a detailed registry and
-history of previously deployed versions and their contents.
-
-With a glance at the |CL| version numbers deployed, you should be able to
-tell if your Clear systems are patched against a particular security
-vulnerability or incorporate a critical new feature.
-
-Pick an image distribution strategy
-***********************************
-
-Once you have decided on a usage and update strategy, you should understand
-*how* |CL| will be deployed to your endpoints. In a large scale deployment,
-interactive installers should be avoided in favor of automated installations
-or prebuilt images.
-
-There are many well-known ways to install an operating system at scale. Each
-have their own benefits, and one may lend itself easier in your environment
-depending on the resources available to you.
-
-See the available :ref:`image-types`.
-
-Below are some common ways to install |CL| to systems at scale:
-
-Bare metal
-==========
-
-Preboot Execution Environments (PXE) or other out-of-band booting options are
-one way to distribute |CL| to physical bare metal systems on a LAN.
-
-This option works well if your customizations are fairly small in size
-and infrastructure can be stateless.
-
-The |CL| `Downloads`_ page offers a live image that can be deployed as
-a PXE boot server if one doesn't already exist in your environment. Also see
-documentation on how to :ref:`bare-metal-install-server`.
-
-Cloud instances or virtual machines
-===================================
-
-Image templates in the form of cloneable disks are an effective way to
-distribute |CL| for virtual machine environments, whether on-premises or
-hosted by a Cloud Solution Provider (CSP).
-
-When used in concert with cloud VM migration features, this can be a good option
-for allowing your applications a degree of high availability and workload
-mobility; VMs can be restarted on a cluster of hypervisor host or moved between
-datacenters transparently.
-
-The |CL| `Downloads`_ page offers example prebuilt VM images and is readily
-available on popular CSPs. Also see documentation on how to
-:ref:`virtual-machine-install`.
-
-Containers
-==========
-
-Containerization platforms allow images to be pulled from a repository and
-deployed repeatedly as isolated containers.
-
-Containers with a |CL| image can be a good option to blueprint and ship
-your application, including all its dependencies, as an artifact while
-allowing you or your customers to dynamically orchestrate and scale
-applications.
-
-|CL| is capable of running a Docker host, has a container image which can
-be pulled from DockerHub, or can be built as a customized container.
-For more information visit the `Containers`_ page.
-
-Considerations with stateless systems
-*************************************
-
-An important |CL| concept is statelessness and partitioning of system data
-from user data. This concept can change the way you think about an at scale
-deployment.
-
-Backup strategy
-===============
-
-A |CL| system and its infrastructure should be considered a commodity and
-be easily reproducible. Avoid focusing on backing up the operating system
-itself or default values.
-
-Instead, focus on backing up what's important and unique - the application
-and data.  In other words, only focus on backing up critical areas like
-:file:`/home`, :file:`/etc`, and :file:`/var`.
-
-Meaningful logging & telemetry
-==============================
-
-Offload logging and telemetry from endpoints to external servers, so it is
-persistent and can be accessed on another server when an issue occurs.
-
-* Remote syslogging in |CL| is available through the
-  `systemd-journal-remote.service`_
-
-* |CL| offers a :ref:`telem-guide`, which can be a powerful tool
-  for a large deployment to quickly crowdsource issues of interest. Take
-  advantage of this feature with careful consideration of the target audience
-  and the kind of data that would be valuable, and expose events
-  appropriately.
-
-  Like any web server, the telemetry server should be appropriately scaled and
-  resilient. Specific implementation details for a scalable, resilient web
-  server are beyond the scope of this document.
-
-Orchestration and configuration management
-==========================================
-
-In cloud environments, where systems can be ephemeral, being able to
-configure and maintain generic instances is valuable.
-
-|CL| offers an efficient cloud-init style solution, `micro-config-drive`_,
-through the *os-cloudguest* bundles which allow you to configure many Day 1
-tasks such as setting hostname, creating users, or placing
-SSH keys in an automated way at boot. For more information on
-automating configuration during deployment of |CL| endpoints see the
-:ref:`bulk-provision` guide.
-
-A configuration management tool is useful for maintaining consistent system
-and application-level configuration. Ansible\* is offered through the
-*sysadmin-hostmgmt* bundle as a configuration management and automation
-tool.
-
-Cloud-native applications
-=========================
-
-An Infrastructure OS can design for good behavior, but it is ultimately up
-to applications to make agile design choices. Applications deployed
-on |CL| should aim to be host-aware but not depend on any specific host to
-run. References should be relative and dynamic when possible.
-
-The application architecture should incorporate an appropriate tolerance for
-infrastructure outages. Don't just keep stateless design as a noted feature.
-Continuously test its use; Automate its use by redeploying |CL| and
-application on new hosts. This naturally minimizes configuration drift,
-challenges your monitoring systems, and business continuity plans.
-
-.. _`Downloads`: https://clearlinux.org/downloads/
-.. _`Containers`: https://clearlinux.org/downloads/containers
-.. _`systemd-journal-remote.service`: https://www.freedesktop.org/software/systemd/man/systemd-journal-remote.service.html
-.. _`micro-config-drive`: https://github.com/clearlinux/micro-config-drive
-
-.. |WEB-SERVER-SCALE| replace::
-   There are many well-known ways to achieve a scalable and resilient web
-   server for this purpose, however implementation details are not in the
-   scope of this document. In general, they should be close to your
-   endpoints, highly available, and easy to scale with a load balancer when
-   necessary.

_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/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/bulk-provision.rst.txt

@@ -1,172 +0,0 @@
-.. _bulk-provision:
-
-Bulk provision
-##############
-
-This guide explains how to perform a bulk provision of |CL-ATTR| using a
-combination of the |CL| installer, Ister, and
-:abbr:`ICIS (Ister Cloud Init Service)`.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-To configure a bulk provision:
-
-* Define Ister configuration files to customize the installation process
-* Define cloud-init\* files to customize the installation instance
-* Host the configuration files in ICIS to allow Ister to use them during
-  the installation
-
-Figure 1 depicts the flow of information between a PXE server and a PXE
-client that needs to be set up to perform a bulk provision.
-
-.. figure:: ./figures/bulk-provision-flow.png
-   :alt: Bulk provision information flow
-
-   Figure 1: Bulk provision information flow
-
-Prerequisites
-*************
-
-Before performing a bulk provision, verify you have a PXE server capable
-of performing network boots of |CL|. Please refer to our
-:ref:`guide on how to perform an iPXE boot<ipxe-install>` using
-:abbr:`NAT (network address translation)` for details.
-
-Because a bulk provision relies on a reboot, ensure the following
-preparations have been made:
-
-* No existing disks are bootable.
-* The network boot option must come immediately after the disk boot option
-  on any computer performing the installation.
-
-Configuration
-*************
-
-#. Install ICIS by following the getting started guide on the
-   `ICIS`_ GitHub\* repository.
-
-#. Create an Ister installation file and save it to the
-   :file:`static/ister` directory within the web hosting directory for
-   ICIS. The installation file is a JSON block and provides Ister
-   with the steps it needs to perform an installation. The file outlines
-   what partitions, file systems, and mount points Ister should set
-   up. Lastly, the file outlines which bundles to install. See our
-   :ref:`bundles` document for the list of available bundles. The
-   following example shows the contents of an Ister installation file:
-
-   .. code-block:: json
-
-      {
-          "DestinationType":"physical",
-          "PartitionLayout":[
-              {"disk":"sda", "partition":1, "size":"512M", "type":"EFI"},
-              {"disk":"sda", "partition":2, "size":"512M", "type":"swap"},
-              {"disk":"sda", "partition":3, "size":"rest", "type":"linux"}
-          ],
-          "FilesystemTypes":[
-              {"disk":"sda", "partition":1, "type":"vfat"},
-              {"disk":"sda", "partition":2, "type":"swap"},
-              {"disk":"sda", "partition":3, "type":"ext4"}
-          ],
-          "PartitionMountPoints":[
-              {"disk":"sda", "partition":1, "mount":"/boot"},
-              {"disk":"sda", "partition":3, "mount":"/"}
-          ],
-          "Version":"latest",
-          "Bundles":[
-              "kernel-native",
-              "os-core",
-              "os-core-update",
-              "os-cloudguest"
-          ],
-          "IsterCloudInitSvc":"http://192.168.1.1:60000/icis/"
-      }
-
-   .. important::
-
-      Every Ister installation file hosted on ICIS must contain the
-      the `IsterCloudInitSvc` parameter as well as the :command:`os-cloudguest`
-      bundle. These entries allow Ister to customize an instance of of an
-      install.
-
-#. Create an Ister configuration file to define the location of the
-   Ister installation file. Save it to the :file:`static/ister` directory
-   within the web hosting directory of ICIS. The following example shows
-   an Ister configuration file:
-
-   .. code-block:: none
-
-      template=http://192.168.1.1:60000/icis/static/ister/ister.json
-
-#. Modify the iPXE boot script by adding a kernel parameter to the command line
-   for booting the network image. Add the kernel parameter `isterconf` with
-   the location of the Ister configuration file hosted on ICIS as the
-   kernel parameter value.  The following example shows an iPXE boot script
-   with the `isterconf` parameter:
-
-   .. code-block:: none
-
-      #!ipxe
-      kernel linux quiet init=/usr/lib/systemd/systemd-bootchart initcall_debug tsc=reliable no_timer_check noreplace-smp rw initrd=initrd isterconf=http://192.168.1.1:60000/icis/static/ister/ister.conf
-      initrd initrd
-      boot
-
-   .. note::
-
-      After the network image of |CL| boots, Ister inspects the
-      parameters used during boot in :file:`/proc/cmdline` to find the
-      location of the Ister configuration file.
-
-#. Write a cloud-init document to customize the instance of the installation
-   according to your requirements. The `cloud-init`_ documentation provides a
-   guide on how to write a cloud-init document. The guide covers the
-   customization options provided by cloud-init after an installation.
-
-#. Save the cloud-init document to the :file:`static/roles` directory within
-   the web hosting directory for ICIS with the name of a role you would
-   like to create. For example, a role may be "database", "web", or "ciao".
-
-#. After creating the roles, also known as cloud-init files, assign roles to
-   MAC addresses of PXE clients. To do so, modify the :file:`config.txt` file
-   in the :file:`static` directory within the web hosting directory of ICIS.
-   The following example shows an example assignment:
-
-   .. code-block:: none
-
-      # MAC address,role
-      00:01:02:03:04:05,ciao
-
-   If MAC addresses of PXE clients are not listed within the
-   :file:`config.txt` file, a default role for those MAC address may be
-   defined as follows:
-
-   .. code-block:: none
-
-      # MAC address,role
-      default,ciao
-
-#. Verify the following URLs are accessible on your local network:
-
-   * \http://192.168.1.1:60000/icis/static/ister/ister.conf
-   * \http://192.168.1.1:60000/icis/static/ister/ister.json
-   * \http://192.168.1.1:60000/icis/get_config/<MAC address>
-   * \http://192.168.1.1:60000/icis/get_role/<role>
-   * \http://192.168.1.1:60000/ipxe/ipxe_boot_script.txt
-
-#. Power on the PXE client and watch it boot and install |CL|.
-
-#. Power-cycle the PXE client and watch it customize the |CL| installation.
-
-**Congratulations!** You have successfully performed a bulk provision of |CL|.
-
-
-.. _ICIS:
-   https://github.com/clearlinux/ister-cloud-init-svc
-
-.. _cloud-init:
-   https://cloudinit.readthedocs.io

_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/developer-workstation.rst.txt

@@ -1,112 +0,0 @@
-.. _developer-workstation:
-
-Developer Workstation
-#####################
-
-This guide helps you find the minimum set of bundles needed to start your
-|CL-ATTR| development project.
-
-Before continuing, review the :ref:`swupd <swupd-guide>` guide to learn more
-about the swupd tool and how |CL| simplifies software versioning compared to
-other Linux\* distributions.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Workstation Setup
-*****************
-
-After installing the minimum set of bundles required to get started, you can add
-more bundles relevant to your specific use case.
-
-To run any process required for |CL| development, you can add the large bundle
-:ref:`*os-clr-on-clr* <enable-user-space>`. However, given how many packages this
-bundle contains, you may want to deploy a leaner OS with only bundles relevant to
-your project.
-
-Use Table 1, *Developer Profiles*, to identify the *minimum
-required bundles* to get started developing based on your role or project.
-While your role may not neatly fit in one of these categories, consider
-Table 1 as a starting point.
-
-.. list-table:: **Table 1. Developer Profiles**
-   :widths: 20, 20, 20, 20
-   :header-rows: 1
-
-   * - |CL| Bundle
-     - *Internet of Things (IoT)*
-     - *System Administrator*
-     - *Client/Cloud/Web Developer*
-
-   * - :command:`editors`
-     - ✓
-     - ✓
-     - ✓
-
-   * - :command:`network-basic`
-     - ✓
-     - ✓
-     - ✓
-
-   * - :command:`openssh-server`
-     - ✓
-     - ✓
-     - ✓
-
-   * - :command:`webserver-basic`
-     -
-     - ✓
-     - ✓
-
-   * - :command:`application-server`
-     -
-     - ✓
-     - ✓
-
-   * - :command:`database-basic`
-     -
-     - ✓
-     - ✓
-
-   * - :command:`desktop-autostart`
-     - ✓
-     - ✓
-     - ✓
-
-   * - :command:`dev-utils`
-     -
-     -
-     - ✓
-
-swupd search
-************
-
-We recommend learning about :ref:`swupd <swupd-guide>`, to learn the
-commands to search for and add bundles relevant to your project.
-
-The guide provides an :ref:`example <swupd-guide-example-install-bundle>`
-that shows you how to:
-
-* Use swupd to search for bundles
-* Use swupd to add bundles
-
-Core Concepts
-*************
-
-We recommend that you understand these core concepts in |CL| *before*
-developing your project.
-
-* :ref:`Software update <swupd-guide>`
-* :ref:`Mixer <mixer>`
-* :ref:`Autospec <autospec>`
-
-Other resources for developers
------------------------------------
-
-* `Developer Tooling Framework`_ for |CL|
-* `Bundle Definition Files`_
-
-.. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles
-
-.. _Developer Tooling Framework: https://github.com/clearlinux/common

_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/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/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/time.rst.txt

@@ -1,59 +0,0 @@
-.. _time:
-
-Set the time
-############
-
-This guide describes how to reset the time in your |CL-ATTR| system when
-the default :abbr:`NTP (Network Time Protocol)` servers cannot be reached.
-
-|CL| uses the `systemd-timesyncd.service` daemon to synchronize time.
-
-
-#. Install the :command:`sysadmin-basic` bundle.
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add sysadmin-basic
-
-#. Set your time zone. This example uses Los Angeles.
-
-   .. code-block:: bash
-
-      timedatectl set-timezone America/Los_Angeles
-
-   .. note::
-
-      To see a list of time zones, use the command:
-      :command:`timedatectl list-timezones | grep <locale>`
-
-#. Create a :file:`/etc/systemd/` directory.
-
-   .. code-block:: bash
-
-      sudo mkdir -p /etc/systemd/
-
-#. Create a new file named :file:`/etc/systemd/timesyncd.conf` and enter the
-   following text.
-
-   .. code-block:: console
-
-      [Time]
-      NTP=<Preferred Server>
-      FallbackNTP=<backup server 1> <backup server 2>
-
-#. Enable the `systemd-timesyncd` service.
-
-   .. code-block:: bash
-
-      timedatectl set-ntp true
-
-.. note::
-
-   To check the service status, use the :command:`timedatectl status` command.
-
-   To restart the `timesyncd` daemon, enter :command:`systemctl restart
-   systemd-timesyncd` into your terminal emulator.
-
-**Congratulations!** You successfully set up the time in your |CL| system.
-
-

_sources/guides/network/dpdk.rst.txt

@@ -1,352 +0,0 @@
-.. _dpdk:
-
-Use DPDK to send packets between platforms
-##########################################
-
-This guide describes how to send packets between two platforms.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-Figure 1 shows how to send packets between two platforms in a simple
-configuration. The example uses the :abbr:`Data Plane Development Kit (DPDK)`,
-which is a set of libraries, drivers, sample applications, and tools for fast
-packet processing.
-
-.. figure:: ./figures/pktgen_lw3fd.png
-   :align: center
-   :alt: Platform A and B
-
-   Figure 1: Environment for l3fwd DPDK application
-
-This example uses the following DPDK components:
-
-*  pktgen: Traffic generator. See `pktgen`_ documentation for details.
-*  l3fwd: Layer 3 forwarding example application. See
-   `l3fwd`_ documentation for details.
-
-Prerequisites
-*************
-
-*  Two platforms using |CL-ATTR| release `13330`_ or higher.
-*  Both images must include the :command:`kernel-native` bundle.
-*  Install the :command:`network-basic-dev` bundle with the command:
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add network-basic-dev
-
-*  Each platform must have at least one :abbr:`NIC (Network Interface Card)`.
-   Check the `DPDK project`_ for the list of supported `dpdk.org NICs`_.
-
-* Two network cables.
-
-Install dpdk and build l3fwd example (Platform B)
-*************************************************
-
-#. Change to the :file:`l3fwd` example directory.
-
-   .. code-block:: bash
-
-      sudo cd /usr/share/dpdk/examples/l3fwd
-
-#. Assign :envvar:`RTE_SDK` variable to the makefiles path.
-
-   .. code-block:: bash
-
-      sudo export RTE_SDK=/usr/share/dpdk/
-
-#. Assign :envvar:`RTE_TARGET` variable to the location of the gcc\* config
-   file.
-
-   .. code-block:: bash
-
-      sudo export RTE_TARGET=x86_64-native-linuxapp-gcc
-
-#. Build the `l3fwd` application and add the configuration header to
-   the :makevar:`CFLAGS` variable.
-
-   .. code-block:: bash
-
-      sudo make CFLAGS+="-include /usr/include/rte_config.h"
-
-
-Build pktgen (Platform A)
-*************************
-
-#. Download the `pktgen tar package`_ v3.1.2 or newer.
-
-#. Decompress packages and move to uncompressed source directory.
-
-#. Assign :envvar:`RTE_SDK` variable to the path where makefiles are located.
-
-   .. code-block:: bash
-
-      sudo export RTE_SDK=/usr/share/dpdk/
-
-#. Assign :envvar:`RTE_TARGET` to the location of the gcc config file.
-
-   .. code-block:: bash
-
-      sudo export RTE_TARGET=x86_64-native-linuxapp-gcc
-
-#. Build the `pktgen` project and set the :makevar:`CONFIG_RTE_BUILD_SHARED_LIB` variable
-   to "n".
-
-   .. code-block:: bash
-
-      sudo make CONFIG_RTE_BUILD_SHARED_LIB=n
-
-Bind NICs to DPDK kernel drivers (Platforms A and B)
-****************************************************
-
-The `l3fwd` application uses two NICs. The DPDK includes tools for binding
-NICs to DPDK modules to run DPDK applications.
-
-#. Load the DPDK I/O kernel module.
-
-   .. code-block:: bash
-
-      sudo modprobe vfio-pci
-
-#. Check the NIC status to determine which network cards are not
-   busy. When another application is using them, the status shows "Active",
-   and those NICs cannot be bound.
-
-   .. code-block:: bash
-
-      sudo dpdk-devbind --status
-
-#. Bind two available NICs. The general syntax for binding is:
-   :command:`dpdk-devbind --bind=vfio-pci <device-entry>`.
-   A working example is shown below:
-
-   .. code-block:: bash
-
-      sudo dpdk-devbind --bind=vfio-pci 01:00.0
-
-#. Check the NIC status to verify that the NICs are bound correctly. If
-   successful, `drv` displays the value `igb_uio`, which confirms
-   that the NICs are using the DPDK modules.
-
-
-Set hugepages (Platforms A and B)
-*********************************
-
-|CL| supports `hugepages` for the large memory pool allocation used for
-packet buffers.
-
-#. Set the number of hugepages.
-
-   .. code-block:: bash
-
-      sudo echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
-
-#. Allocate pages on NUMA machines.
-
-   .. code-block:: bash
-
-      sudo echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
-      sudo echo 1024 > /sys/devices/system/node/node1/hugepages/hugepages-2048kB/nr_hugepages
-
-#. Make memory available for DPDK.
-
-   .. code-block:: bash
-
-      sudo mkdir -p /mnt/huge $ mount -t hugetlbfs nodev /mnt/huge
-
-   For more information, refer to the `DPDK guide`_ System Requirements
-   section.
-
-
-Set up the physical environment (Platforms A and B)
-***************************************************
-
-Connect the NICs on Platform A to the NICs on Platform B using the network
-cables as shown in figure 2.
-
-.. figure:: ./figures/pyshical_net.png
-
-    Figure 2: Physical network environment
-
-
-Run l3fwd application (Platform B)
-**********************************
-
-The `l3fwd` application is one of the DPDK examples available when you
-install the :file:`dpdk-dev` bundle. `l3fwd` forwards packets from one
-NIC to another. For details, refer to the `l3fwd`_ documentation.
-
-#. Open the l3fwd example directory.
-
-   .. code-block:: bash
-
-      sudo cd  /usr/share/dpdk/examples/l3fwd
-
-#. **This step is very important.**
-
-   #. DPDK needs poll mode drivers to operate.
-   #. Poll mode drivers are shared objects in :file:`/usr/lib64`.
-   #. See the full list of supported NICs at `dpdk.org NICs`_.
-   #. You must know which kernel module each NIC is using and choose a poll
-      mode driver that corresponds to your NICs.
-
-#. NIC binding and `pktgen` configuration depends upon network use cases and
-   available system resources. Use the :command:`-d` flag to set the poll mode
-   driver.
-
-   The following example assumes that the NICs use the `e1000` network driver
-   and the `e1000` poll mode driver. The :file:`librte_pmd_e1000.so` is
-   located in :file:`/usr/lib64` in |CL|.
-
-   .. code-block:: bash
-
-      sudo ./build/l3fwd -c 0x3 -n 2 -d librte_pmd_e1000.so -- -p 0x3 --config="(0,0,0),(1,0,1)"
-
-#. The `l3fwd` application shows port initialization details at startup.
-   After port 0 initialization completes, `l3fwd` shows a MAC address and
-   information for port 1.
-
-   Save the MAC address for configuring the `pktgen` project.
-
-Run pktgen application (Platform A)
-***********************************
-
-`pktgen` is a network traffic generator included in the DPDK.
-
-#. `pktgen` configuration depends upon the network setup and the
-   available system resources. The following example shows a basic
-   configuration.
-
-   .. code-block:: bash
-
-      sudo ./app/app/x86_64-native-linuxapp-gcc/pktgen -c 0xf -n 4 -- -p 0xf -P -m "1.0, 2.1"
-
-#. Enable active colorful output (optional).
-
-   .. code-block:: bash
-
-      Pktgen> theme enable
-
-#. Use the MAC addresses shown by the `l3fwd` application during initialization.
-   The command to set the MAC addresses in `pktgen` has the format:
-
-   .. code-block:: bash
-
-      set mac <port number> <mac address>
-
-   Here is a working example:
-
-   .. code-block:: bash
-
-      Pktgen> set mac 0 00:1E:67:CB:E8:C9
-      Pktgen> set mac 1 00:1E:67:CB:E8:C9
-
-#. Send packets.
-
-   .. code-block:: bash
-
-      Pktgen> start 0-1
-
-For more details, see the `pktgen`_ documentation.
-
-Appendix A: Use pass-through for virtual machines
-*************************************************
-
-This section explains how to set up a virtual environment where virtual
-machines control the NICs on the host.
-
-#. Create a new directory and move to it.
-
-#. Download or create a :file:`start_qemu.sh` script for running a kvm virtual
-   machine:
-
-   .. code-block:: bash
-
-      sudo curl -O https://cdn.download.clearlinux.org/image/start_qemu.sh
-
-#. Download a bare-metal image of |CL| and rename it as :file:`clear.img`.
-
-#. Look for an Ethernet\* device entry that contains vendor and device ID:
-
-   .. code-block:: bash
-
-      sudo lspci -nn | grep Ethernet
-
-   An example output:
-
-   .. code-block:: console
-
-       03:00.0 Ethernet controller [0200]: Intel Corporation I350 Gigabit Network Connection [8086:1521]
-
-   where `03:00.0` is the device entry and `8086:1521` is the `vendor:device
-   ID`. Record this information, because you need it to unbind the NICs from a
-   host.
-
-
-#. Unbind the NICs from the host to do pass-through with virtual machines. |CL|
-   supports this action. The commands take the format:
-
-   .. code-block:: bash
-
-      echo "vendor device_ID" > /sys/bus/pci/drivers/pci-stub/new_id
-      echo "entry for device" > /sys/bus/pci/drivers/igb/unbind
-      echo "entry for device" > /sys/bus/pci/drivers/pci-stub/bind
-      echo "vendor device_ID" > /sys/bus/pci/drivers/pci-stub/remove_id
-
-   Here is a working example:
-
-   .. code-block:: bash
-
-      sudo echo "8086 1521" > /sys/bus/pci/drivers/pci-stub/new_id
-      sudo echo "0000:03:00.0" > /sys/bus/pci/drivers/igb/unbind
-      sudo echo "0000:03:00.0" > /sys/bus/pci/drivers/pci-stub/bind
-      sudo echo "8086 1521" > /sys/bus/pci/drivers/pci-stub/remove_id
-
-#. Assign the unbound NICs to the KVM virtual machine (guest).
-   Modify the :file:`start_qemu.sh` script in `qemu-system-x86_64` arguments, and
-   add the lines with the host's NICs information in the format:
-
-   .. code-block:: bash
-
-      -device pci-assign,host="<entry for device>",id=passnic0,addr=03.0
-      -device pci-assign,host="<entry for device>",id=passnic1,addr=04.0
-
-   Here is a working example:
-
-   .. code-block:: bash
-
-      -device pci-assign,host=03:00.0,id=passnic0,addr=03.0 \
-      -device pci-assign,host=03:00.3,id=passnic1,addr=04.0 \
-
-#. Add more NUMA machines to the virtual machine by adding lines to the
-   Makefile boot target in the format:
-
-   .. code-block:: bash
-
-      -numa node,mem=<memory>,cpus=<number of cpus>
-
-   Here is a working example for a virtual machine with 4096 memory and four
-   CPUs:
-
-   .. code-block:: bash
-
-    -numa node,mem=2048,cpus=0-1 \
-    -numa node,mem=2048,cpus=2-3 \
-
-   .. note:: Each NUMA machine must use the same quantity of memory.
-
-#. Run the :file:`start_qemu.sh` script.
-
-
-.. _13330: https://cdn.download.clearlinux.org/releases/13330/
-.. _DPDK project: http://dpdk.org
-.. _dpdk.org NICs: http://dpdk.org/doc/nics
-.. _pktgen tar package: http://dpdk.org/browse/apps/pktgen-dpdk/refs
-.. _DPDK guide: http://dpdk.org/doc/guides/linux_gsg/sys_reqs.html
-.. _l3fwd: http://dpdk.org/doc/guides/sample_app_ug/l3_forward.html
-.. _pktgen: http://pktgen-dpdk.readthedocs.io/en/latest/index.html

_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/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/stacks/dlrs/dlrs.rst.txt

@@ -1,592 +0,0 @@
-.. _dlrs:
-
-Deep Learning Reference Stack
-#############################
-
-This guide describes how to run benchmarking workloads for TensorFlow\*,
-PyTorch\*, and Kubeflow in |CL-ATTR| using the Deep Learning Reference Stack.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-We created the Deep Learning Reference Stack to help AI developers deliver
-the best experience on Intel® Architecture. This stack reduces complexity
-common with deep learning software components, provides flexibility for
-customized solutions, and enables you to quickly prototype and deploy Deep
-Learning workloads. Use this guide to run benchmarking workloads on your
-solution.
-
-The Deep Learning Reference Stack is available in the following versions:
-
-* `Intel MKL-DNN-VNNI`_, which is optimized using Intel® Math Kernel Library
-  for Deep Neural Networks (Intel® MKL-DNN) primitives and introduces support
-  for Intel® AVX-512 Vector Neural Network Instructions (VNNI).
-* `Intel MKL-DNN`_, which includes the TensorFlow framework optimized using
-  Intel® Math Kernel Library for Deep Neural Networks (Intel® MKL-DNN)
-  primitives.
-* `Eigen`_, which includes `TensorFlow`_ optimized for Intel® architecture.
-* `PyTorch with OpenBLAS`_, which includes PyTorch with OpenBlas.
-* `PyTorch with Intel MKL-DNN`_, which includes PyTorch optimized using Intel®
-  Math Kernel Library (Intel® MKL) and Intel MKL-DNN.
-
-.. important::
-
-   To take advantage of the Intel® AVX-512 and VNNI functionality with the Deep
-   Learning Reference Stack, you must use the following hardware:
-
-   * Intel® AVX-512 images require an Intel® Xeon® Scalable Platform
-   * VNNI requires a 2nd generation Intel® Xeon® Scalable Platform
-
-Stack features
-==============
-
-* `DLRS V3.0`_  release announcement.
-* Deep Learning Reference Stack v2.0 including current
-  `PyTorch benchmark`_.
-* Deep Learning Reference Stack v1.0 including current
-  `TensorFlow benchmark`_ results.
-* `DLRS Release notes`_  on Github\* for the latest release of Deep Learning
-  Reference Stack.
-
-.. note::
-
-   The Deep Learning Reference Stack is a collective work, and each piece of
-   software within the work has its own license.  Please see the `DLRS Terms of Use`_
-   for more details about licensing and usage of the Deep Learning Reference Stack.
-
-Prerequisites
-=============
-
-* :ref:`Install <bare-metal-install-desktop>` |CL| on your host system
-* :command:`containers-basic` bundle
-* :command:`cloud-native-basic` bundle
-
-In |CL|, :command:`containers-basic` includes Docker\*, which is required for
-TensorFlow and PyTorch benchmarking. Use the :command:`swupd` utility to
-check if :command:`containers-basic` and :command:`cloud-native-basic` are
-present:
-
-.. code-block:: bash
-
-   sudo swupd bundle-list
-
-To install the :command:`containers-basic` or :command:`cloud-native-basic`
-bundles, enter:
-
-.. code-block:: bash
-
-   sudo swupd bundle-add containers-basic cloud-native-basic
-
-Docker is not started upon installation of the :command:`containers-basic`
-bundle. To start Docker, enter:
-
-.. code-block:: bash
-
-   sudo systemctl start docker
-
-To ensure that Kubernetes is correctly installed and configured, follow the
-instructions in :ref:`kubernetes`.
-
-Version compatibility
-=====================
-
-We validated these steps against the following software package versions:
-
-* |CL| 26240 (Minimum supported version)
-* Docker 18.06.1
-* Kubernetes 1.11.3
-* Go 1.11.12
-
-
-.. note::
-
-   The Deep Learning Reference Stack was developed to provide the best user
-   experience when executed on a |CL| host.  However, as the stack runs in a
-   container environment, you should be able to complete the following sections of this guide on other Linux* distributions, provided they comply with the Docker*, Kubernetes* and Go* package versions listed above. Look for your distribution documentation on how to update packages and manage Docker services.
-
-TensorFlow single and multi-node benchmarks
-*******************************************
-
-This section describes running the `TensorFlow Benchmarks`_ in single node.
-For multi-node testing, replicate these steps for each node. These steps
-provide a template to run other benchmarks, provided that they can invoke
-TensorFlow.
-
-.. note::
-
-   Performance test results for the Deep Learning Reference Stack and for this
-   guide were obtained using `runc` as the runtime.
-
-#. Download either the `Eigen`_ or the `Intel MKL-DNN`_ Docker image
-   from `Docker Hub`_.
-
-#. Run the image with Docker:
-
-   .. code-block:: bash
-
-      docker run --name <image name>  --rm -i -t <clearlinux/
-      stacks-dlrs-TYPE> bash
-
-   .. note::
-
-      Launching the Docker image with the :command:`-i` argument starts
-      interactive mode within the container. Enter the following commands in
-      the running container.
-
-#. Clone the benchmark repository in the container:
-
-   .. code-block:: bash
-
-      git clone http://github.com/tensorflow/benchmarks -b cnn_tf_v1.12_compatible
-
-#. Execute the benchmark script:
-
-   .. code-block:: bash
-
-      python benchmarks/scripts/tf_cnn_benchmarks/tf_cnn_benchmarks.py --device=cpu --model=resnet50 --data_format=NHWC
-
-.. note::
-
-   You can replace the model with one of your choice supported by the
-   TensorFlow benchmarks.
-
-   If you are using an FP32 based model, it can be converted to an int8 model
-   using `Intel® quantization tools`_.
-
-PyTorch single and multi-node benchmarks
-****************************************
-
-This section describes running the `PyTorch benchmarks`_ for Caffe2 in
-single node.
-
-#. Download either the `PyTorch with OpenBLAS`_ or the `PyTorch with Intel
-   MKL-DNN`_ Docker image from `Docker Hub`_.
-
-#. Run the image with Docker:
-
-   .. code-block:: bash
-
-      docker run --name <image name>  --rm -i -t <clearlinux/stacks-dlrs-TYPE> bash
-
-   .. note::
-
-      Launching the Docker image with the :command:`-i` argument starts
-      interactive mode within the container. Enter the following commands in
-      the running container.
-
-#. Clone the benchmark repository:
-
-   .. code-block:: bash
-
-      git clone https://github.com/pytorch/pytorch.git
-
-#. Execute the benchmark script:
-
-   .. code-block:: bash
-
-       cd pytorch/caffe2/python
-       python convnet_benchmarks.py --batch_size 32 \
-                             --cpu \
-                             --model AlexNet
-
-Kubeflow multi-node benchmarks
-******************************
-
-The benchmark workload runs in a Kubernetes cluster. The guide uses
-`Kubeflow`_ for the Machine Learning workload deployment on three nodes.
-
-.. warning::
-
-   If you choose the Intel® MKL-DNN or Intel® MKL-DNN-VNNI image, your platform
-   must support the Intel® AVX-512 instruction set. Otherwise, an
-   *illegal instruction* error may appear, and you won’t be able to complete this guide.
-
-
-Kubernetes setup
-================
-
-Follow the instructions in the :ref:`kubernetes` tutorial to get set up on
-|CL|. The Kubernetes community also has instructions for creating a cluster,
-described in `Creating a single control-plane cluster with kubeadm`_.
-
-Kubernetes networking
-=====================
-
-We used `flannel`_ as the network provider for these tests. If you
-prefer a different network layer, refer to the Kubernetes network documentation
-described in `Creating a single control-plane cluster with kubeadm`_ for setup.
-
-Kubectl
-=======
-
-You can use kubectl to run commands against your Kubernetes cluster.  Refer to
-the `Overview of kubectl`_ for details on syntax and operations. Once you have a
-working cluster on Kubernetes, use the following YAML script to start a pod with
-a simple shell script, and keep the pod open.
-
-#. Copy this example.yaml script to your system:
-
-   .. code-block:: console
-
-      apiVersion: v1
-      kind: Pod
-      metadata:
-        name: example-pod
-        labels:
-          app: ex-pod
-      spec:
-        containers:
-        - name: ex-pod-container
-          image: clearlinux/stacks-dlrs-mkl:latest
-          command: ['/bin/bash', '-c', '--']
-          args: [ "while true; do sleep 30; done" ]
-
-#. Execute the script with kubectl:
-
-   .. code-block:: bash
-
-      kubectl apply –f <path-to-yaml-file>/example.yaml
-
-This script opens a single pod. More robust solutions would create a deployment
-or inject a python script or larger shell script into the container.
-
-Images
-======
-
-You must add `launcher.py`_ to the Docker image to include the Deep
-Learning Reference Stack and put the benchmarks repo in the correct
-location. Note that this guide uses Kubeflow v0.4.0, and cannot guarantee results if you use a different version.
-
-From the Docker image, run the following:
-
-.. code-block:: bash
-
-   mkdir -p /opt
-   git clone https://github.com/tensorflow/benchmarks.git /opt/tf-benchmarks
-   cp launcher.py /opt
-   chmod u+x /opt/*
-
-Your entry point becomes: :file:`/opt/launcher.py`.
-
-This builds an image that can be consumed directly by TFJob from Kubeflow.
-
-ksonnet\*
-=========
-
-Kubeflow uses ksonnet\* to manage deployments, so you must install it
-before setting up Kubeflow.
-
-ksonnet was added to the :command:`cloud-native-basic` bundle in |CL| version
-27550. If you are using an older |CL| version (not recommended), you must
-manually install ksonnet as described below.
-
-On |CL|, follow these steps:
-
-.. code-block:: bash
-
-   swupd bundle-add go-basic-dev
-   export GOPATH=$HOME/go
-   export PATH=$PATH:$GOPATH/bin
-   go get github.com/ksonnet/ksonnet
-   cd $GOPATH/src/github.com/ksonnet/ksonnet
-   make install
-
-After the ksonnet installation is complete, ensure that binary `ks` is
-accessible across the environment.
-
-Kubeflow
-========
-
-Once you have Kubernetes running on your nodes, set up `Kubeflow`_ by
-following these instructions from the `Getting Started with Kubeflow`_ guide.
-
-.. code-block:: bash
-
-   export KUBEFLOW_SRC=$HOME/kflow
-   export KUBEFLOW_TAG="v0.4.1"
-   export KFAPP="kflow_app"
-   export K8S_NAMESPACE="kubeflow"
-
-   mkdir ${KUBEFLOW_SRC}
-   cd ${KUBEFLOW_SRC}
-   ks init ${KFAPP}
-   cd ${KFAPP}
-   ks registry add kubeflow github.com/kubeflow/kubeflow/tree/${KUBEFLOW_TAG}/kubeflow
-   ks pkg install kubeflow/common
-   ks pkg install kubeflow/tf-training
-
-Next, deploy the primary package for our purposes: tf-job-operator.
-
-.. code-block:: bash
-
-   ks env rm default
-   kubectl create namespace ${K8S_NAMESPACE}
-   ks env add default --namespace "${K8S_NAMESPACE}"
-   ks generate tf-job-operator tf-job-operator
-   ks apply default -c tf-job-operator
-
-This creates the CustomResourceDefinition (CRD) endpoint to launch a TFJob.
-
-Run a TFJob
-===========
-
-#. Get the ksonnet registries for deploying TFJobs from `dlrs-tfjob`_.
-
-#. Install the TFJob components as follows:
-
-   .. code-block:: bash
-
-      ks registry add dlrs-tfjob github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow/dlrs-tfjob
-
-      ks pkg install dlrs-tfjob/dlrs-bench
-
-#. Export the image name to use for the deployment:
-
-   .. code-block:: bash
-
-      export DLRS_IMAGE=<docker_name>
-
-   .. note::
-
-      Replace <docker_name> with the image name you specified in previous steps.
-
-#. Generate Kubernetes manifests for the workloads and apply them using these
-   commands:
-
-   .. code-block:: bash
-
-      ks generate dlrs-resnet50 dlrsresnet50 --name=dlrsresnet50 --image=${DLRS_IMAGE}
-      ks generate dlrs-alexnet dlrsalexnet --name=dlrsalexnet --image=${DLRS_IMAGE}
-      ks apply default -c dlrsresnet50
-      ks apply default -c dlrsalexnet
-
-This replicates and deploys three test setups in your Kubernetes cluster.
-
-Results of running this guide
-=============================
-
-You must parse the logs of the Kubernetes pod to retrieve performance
-data. The pods will still exist post-completion and will be in
-‘Completed’ state. You can get the logs from any of the pods to inspect the
-benchmark results. More information about Kubernetes logging is available
-in the Kubernetes `Logging Architecture`_ documentation.
-
-Use Jupyter Notebook
-********************
-
-This example uses the `PyTorch with OpenBLAS`_ container image. After it is
-downloaded, run the Docker image with :command:`-p` to specify the shared port
-between the container and the host. This example uses port 8888.
-
-.. code-block:: bash
-
-   docker run --name pytorchtest --rm -i -t -p 8888:8888 clearlinux/stacks-pytorch-oss bash
-
-After you start the container, launch the Jupyter Notebook. This
-command is executed inside the container image.
-
-.. code-block:: bash
-
-   jupyter notebook --ip 0.0.0.0 --no-browser --allow-root
-
-After the notebook has loaded, you will see output similar to the following:
-
-.. code-block:: console
-
-   To access the notebook, open this file in a browser: file:///.local/share/jupyter/runtime/nbserver-16-open.html
-   Or copy and paste one of these URLs:
-   http://(846e526765e3 or 127.0.0.1):8888/?token=6357dbd072bea7287c5f0b85d31d70df344f5d8843fbfa09
-
-From your host system, or any system that can access the host's IP address,
-start a web browser with the following. If you are not running the browser on
-the host system, replace :command:`127.0.0.1` with the IP address of the host.
-
-.. code-block:: bash
-
-  http://127.0.0.1:8888/?token=6357dbd072bea7287c5f0b85d31d70df344f5d8843fbfa09
-
-Your browser displays the following:
-
-.. figure:: figures/dlrs-fig-1.png
-   :scale: 50 %
-   :alt: Jupyter Notebook
-
-Figure 1: :guilabel:`Jupyter Notebook`
-
-
-To create a new notebook, click :guilabel:`New` and select :guilabel:`Python 3`.
-
-.. figure:: figures/dlrs-fig-2.png
-   :scale: 50%
-   :alt: Create a new notebook
-
-Figure 2: Create a new notebook
-
-A new, blank notebook is displayed, with a cell ready for input.
-
-.. figure:: figures/dlrs-fig-3.png
-   :scale: 50%
-   :alt: New blank notebook
-
-
-To verify that PyTorch is working, copy the following snippet into the blank
-cell, and run the cell.
-
-.. code-block:: console
-
-   from __future__ import print_function
-   import torch
-   x = torch.rand(5, 3)
-   print(x)
-
-.. figure:: figures/dlrs-fig-4.png
-   :scale: 50%
-   :alt: Sample code snippet
-
-When you run the cell, your output will look something like this:
-
-.. figure:: figures/dlrs-fig-5.png
-   :scale: 50%
-   :alt: code output
-
-You can continue working in this notebook, or you can download existing
-notebooks to take advantage of the Deep Learning Reference Stack's optimized
-deep learning frameworks. Refer to `Jupyter Notebook`_ for details.
-
-Uninstallation
-**************
-
-To uninstall the Deep Learning Reference Stack, you can choose to stop the
-container so that it is not using system resources, or you can stop the
-container and delete it to free storage space.
-
-To stop the container, execute the following from your host system:
-
-#. Find the container's ID
-
-   .. code-block:: bash
-
-      docker container ls
-
-   This will result in output similar to the following:
-
-   .. code-block:: console
-
-      CONTAINER ID        IMAGE                        COMMAND               CREATED             STATUS              PORTS               NAMES
-      e131dc71d339        clearlinux/stacks-dlrs-oss   "/bin/sh -c 'bash'"   23 seconds ago      Up 21 seconds                           oss
-
-#. You can then use the ID or container name to stop the container. This example
-   uses the name "oss":
-
-   .. code-block:: bash
-
-      docker container stop oss
-
-
-#. Verify that the container is not running
-
-   .. code-block:: bash
-
-      docker container ls
-
-
-#. To delete the container from your system you need to know the Image ID:
-
-   .. code-block:: bash
-
-      docker images
-
-   This command results in output similar to the following:
-
-   .. code-block:: console
-
-      REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
-      clearlinux/stacks-dlrs-oss   latest              82757ec1648a        4 weeks ago         3.43GB
-      clearlinux/stacks-dlrs-mkl   latest              61c178102228        4 weeks ago         2.76GB
-
-#. To remove an image use the image ID:
-
-   .. code-block:: bash
-
-      docker rmi 82757ec1648a
-
-   .. code-block:: console
-
-      # docker rmi 827
-      Untagged: clearlinux/stacks-dlrs-oss:latest
-      Untagged: clearlinux/stacks-dlrs-oss@sha256:381f4b604537b2cb7fb5b583a8a847a50c4ed776f8e677e2354932eb82f18898
-      Deleted: sha256:82757ec1648a906c504e50e43df74ad5fc333deee043dbfe6559c86908fac15e
-      Deleted: sha256:e47ecc039d48409b1c62e5ba874921d7f640243a4c3115bb41b3e1009ecb48e4
-      Deleted: sha256:50c212235d3c33a3c035e586ff14359d03895c7bc701bb5dfd62dbe0e91fb486
-
-
-   Note that you can execute the :command:`docker rmi` command using only the first few characters of the image ID, provided they are unique on the system.
-
-#. Once you have removed the image, you can verify it has been deleted with:
-
-   .. code-block:: bash
-
-       docker images
-
-
-Related topics
-**************
-
-* `DLRS V3.0`_ release announcement
-* `TensorFlow Benchmarks`_
-* `PyTorch benchmarks`_
-* `Kubeflow`_
-* :ref:`kubernetes` tutorial
-* `Jupyter Notebook`_
-
-.. _TensorFlow: https://www.tensorflow.org/
-
-.. _Kubeflow: https://www.kubeflow.org/
-
-.. _Docker Hub: https://hub.docker.com/
-
-.. _TensorFlow Benchmarks: https://www.tensorflow.org/guide/performance/benchmarks
-
-.. _PyTorch benchmarks: https://github.com/pytorch/pytorch/blob/master/caffe2/python/convnet_benchmarks.py
-
-.. _Creating a single control-plane cluster with kubeadm: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/
-
-.. _flannel: https://github.com/coreos/flannel
-
-.. _Getting Started with Kubeflow: https://www.kubeflow.org/docs/started/getting-started/
-
-.. _Eigen: https://hub.docker.com/r/clearlinux/stacks-dlrs-oss/
-
-.. _Intel MKL-DNN: https://hub.docker.com/r/clearlinux/stacks-dlrs-mkl/
-
-.. _PyTorch with OpenBLAS: https://hub.docker.com/r/clearlinux/stacks-pytorch-oss
-
-.. _PyTorch with Intel MKL-DNN: https://hub.docker.com/r/clearlinux/stacks-pytorch-mkl
-
-.. _Intel MKL-DNN-VNNI: https://hub.docker.com/r/clearlinux/stacks-dlrs-mkl-vnni
-
-.. _DLRS V3.0:  https://clearlinux.org/stacks/deep-learning-reference-stack-v3
-
-.. _dlrs-tfjob: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow/dlrs-tfjob
-
-.. _Logging Architecture: https://kubernetes.io/docs/concepts/cluster-administration/logging/
-
-.. _TensorFlow benchmark: https://clearlinux.org/stacks/deep-learning-reference-stack
-
-.. _PyTorch benchmark: https://clearlinux.org/stacks/deep-learning-reference-stack-pytorch
-
-.. _Jupyter Notebook: https://jupyter.org/
-
-.. _Overview of kubectl: https://kubernetes.io/docs/reference/kubectl/overview/
-
-.. _launcher.py: https://github.com/clearlinux/dockerfiles/tree/master/stacks/dlrs/kubeflow
-
-.. _DLRS Terms of Use: https://clearlinux.org/stacks/deep-learning/terms-of-use
-
-.. _DLRS Release notes: https://github.com/clearlinux/dockerfiles/blob/master/stacks/dlrs/releasenote.md
-
-.. _Intel® quantization tools:  https://github.com/IntelAI/tools/blob/master/tensorflow_quantization/README.md#quantization-tools