Remove redundant content + associated clean up

- Remove concepts (content migrated to Clear guides)
- Remove reference for bundle commands (quick ref in swupd guide)
- Moved bundle about page to Clear guide
- Updated links to concepts page, to instead link to the associated guide

Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
Kristal Dale
2019-08-07 16:54:15 -07:00
parent 2898310fae
commit a8aa87ec9d
23 changed files with 45 additions and 459 deletions
+5 -5
View File
@@ -44,7 +44,7 @@ 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.
:ref:`telem-guide` guide for more information.
|
@@ -75,8 +75,8 @@ 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>`.
|CL| provides software in the form of :ref:`bundles-guide` and
updates software with :ref:`swupd <swupd-guide>`.
:ref:`FlatPak\* <flatpak>` is an application virtualization solution that allows
more software to be available to |CL| users by augmenting the software |CL|
@@ -90,7 +90,7 @@ bundles whenever possible.
Does |CL| use RPMs like other distros?
======================================
|CL| provides software in the form of :ref:`bundles <bundles-about>`. The RPM
|CL| provides software in the form of :ref:`bundles-guide`. The RPM
format is used as an intermediary step for packaging and determining software
dependencies at OS build time.
@@ -118,7 +118,7 @@ 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>`.
Software application on the desktop, or by using :ref:`swupd search <swupd-quick-ref>`.
|
-106
View File
@@ -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
Binary file not shown.

Before

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 131 KiB

-54
View File
@@ -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`
-97
View File
@@ -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
-82
View File
@@ -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:: /_figures/telemetrics/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`.
@@ -352,9 +352,9 @@ Optional: Skip to `Finish installation`_.
Telemetry
=========
Choose whether to participate in `telemetry`. :ref:`telem-guide` is a |CL|
Choose whether to participate in `telemetry`. Telemetry is a |CL|
feature that reports failures and crashes to the |CL| development
team for improvements. For more information, see :ref:`telemetry-about`.
team for improvements. For more information, see :ref:`telem-guide`.
#. From :guilabel:`Required Options`, select :guilabel:`Telemetry`.
@@ -392,9 +392,9 @@ be configured post-installation using the ``cryptsetup`` tool.
Telemetry
=========
:ref:`telem-guide` is a |CL| feature that reports failures and crashes to
Telemetrics is a |CL| feature that reports failures and crashes to
the |CL| development team for improvements. For more detailed information,
visit our :ref:`telemetry-about` page.
visit our :ref:`telem-guide` guide.
Select your desired option on whether to participate in `telemetry`.
+1 -1
View File
@@ -435,7 +435,7 @@ To test an autospec created package directly on the |CL| development system:
#. 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
:ref:`swupd <swupd-guide>`) however any other files must be cleaned up
manually.
@@ -1,30 +1,21 @@
.. _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`
.. _bundles-guide:
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-guide>`.
Each bundle contains as many or as few open source projects needed to provide a complete functionality.
+3 -4
View File
@@ -846,10 +846,9 @@ Set up a nginx web server for mixer with the following steps:
Related topics
**************
* :ref:`About mixer <mixer-about>`
* :ref:`autospec-about`
* :ref:`bundles-about`
* :ref:`swupd-about`
* :ref:`autospec`
* :ref:`bundles-guide`
* :ref:`swupd-guide`
.. _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
+1 -1
View File
@@ -38,7 +38,7 @@ System areas
============
File under the :file:`/usr` directory are managed by |CL| as system files.
Files written under the :file:`/usr` directory by users can get removed
through system updates with :ref:`swupd <swupd-about>`. This operating
through system updates with :ref:`swupd <swupd-guide>`. This operating
assumption allows |CL| to verify and maintain integrity of system files.
User areas
+2
View File
@@ -303,6 +303,8 @@ ignores files or directories matching :file:`/usr/lib/python`:
sudo swupd repair --picky --picky-whitelist=/usr/lib/python
.. _swupd-quick-ref:
Quick reference
***************
+1 -1
View File
@@ -92,7 +92,7 @@ Change the kernel version
|CL| tends to use the latest kernel available from `kernel.org`_, the Linux
upstream. The kernel version that will be built can be changed in the
RPM SPEC file. While most packages in Clear Linux are typically packaged
using :ref:`autospec-about`, the kernel is not. This means control files
using :ref:`autospec`, the kernel is not. This means control files
provided by autospec are not available and changes must be made manually.
#. Open the Linux kernel package RPM SPEC file in an editor.
-47
View File
@@ -1,47 +0,0 @@
.. _bundle-commands:
Useful bundle commands
######################
To see a list of currently installed bundles, enter:
.. code-block:: bash
sudo swupd bundle-list
To see the list of all available bundles, enter:
.. code-block:: bash
sudo swupd bundle-list --all
Alternatively, you can view our :ref:`available bundles <bundles>`
webpage.
To search for bundles and their contents, enter:
.. code-block:: bash
sudo swupd search [bundle name]
To add a bundle, enter:
.. code-block:: bash
sudo swupd bundle-add [bundle name]
Additional information
======================
For additional :command:`swupd` commands, enter:
.. code-block:: bash
swupd --help
To reference the :command:`swupd` man page, enter:
.. code-block:: bash
man swupd
+1 -1
View File
@@ -7,7 +7,7 @@ This document provides a current list of available bundles. View the `clr-bundle
:file:`Name` for more details.
To learn more about how |CL-ATTR| uses bundles for software deployment, visit
:ref:`bundles-about`.
:ref:`bundles-guide`.
Bundle list
===========
-14
View File
@@ -10,21 +10,7 @@ features.
:maxdepth: 1
compatible-hardware
bundle-commands
bundles/bundles
collaboration/collaboration
system-requirements
image-types
.. _concepts:
Clear Linux concepts
********************
.. toctree::
:maxdepth: 1
:glob:
../concepts/*
../guides/clear/stateless
../guides/clear/security
+1 -3
View File
@@ -45,7 +45,7 @@ Additionally, you should have:
Install the containers-basic bundle
***********************************
Software in |CL| is offered in the form of `bundles`_ to provide a
Software in |CL| is offered in the form of :ref:`bundles` to provide a
complete function. The *containers-basic* provides all the required software
packages to run Docker images as containers.
@@ -221,8 +221,6 @@ Related topics
.. _Docker proxy instructions: https://docs.docker.com/config/daemon/systemd/#httphttps-proxy
.. _bundles: https://clearlinux.org/documentation/clear-linux/concepts/bundles-about#related-concepts
.. _Docker documentation on daemon configuration: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file
.. _Kata Containers: https://katacontainers.io/
+2 -6
View File
@@ -33,7 +33,7 @@ This tutorial assumes you have already installed |CL|. For detailed
instructions on installing |CL| on a bare metal system, follow the
:ref:`bare metal installation tutorial<bare-metal-install-desktop>`.
Learn about the benefits of having an up-to-date system for cloud
orchestration on the :ref:`swupd-about` page.
orchestration on the :ref:`swupd-guide` page.
Before you install any new packages, update |CL| with the following command:
@@ -271,7 +271,7 @@ following commands:
sudo cp /usr/share/defaults/crio/crio.conf /etc/crio/
sudo $EDITOR /etc/crio/crio.conf
Learn more about :ref:`stateless` in |CL| and view the |CL| `documentation`_.
Learn more about :ref:`stateless` in |CL|.
Proxy configuration (optional)
******************************
@@ -396,8 +396,6 @@ Troubleshooting
.. _Kata Containers: https://katacontainers.io/
.. _Software Update documentation: https://clearlinux.org/documentation/clear-linux/concepts/swupd-about#updating
.. _cloud-native-basic: https://github.com/clearlinux/clr-bundles/blob/master/bundles/cloud-native-basic
.. _preflight check: https://kubernetes.io/docs/reference/setup-tools/kubeadm/implementation-details/#preflight-checks
@@ -410,6 +408,4 @@ Troubleshooting
.. _Joining your nodes: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#join-nodes
.. _documentation: https://clearlinux.org/documentation/clear-linux
.. _cloud-native-setup: https://github.com/clearlinux/cloud-native-setup/tree/master/clr-k8s-examples
+1 -1
View File
@@ -15,7 +15,7 @@ These instructions show how to install the CUDA Toolkit on |CL| after the
.. note::
Software installed outside of :ref:`swupd <swupd-about>` is not updated with |CL|
Software installed outside of :ref:`swupd <swupd-guide>` is not updated with |CL|
updates and must be updated and maintained manually.
+2 -2
View File
@@ -17,7 +17,7 @@ require a manual installation.
.. warning::
Software installed outside of :ref:`swupd <swupd-about>` is not updated
Software installed outside of :ref:`swupd <swupd-guide>` is not updated
with |CL| updates and must be updated and maintained manually.
For example, the file :file:`/usr/lib/libGL.so` conflicts with the file
@@ -228,7 +228,7 @@ Updating the NVIDIA drivers
***************************
The proprietary NVIDIA drivers are installed manually outside of :ref:`swupd
<swupd-about>` and must be updated manually when needed.
<swupd-guide>` and must be updated manually when needed.
Updating the NVIDIA drivers follows the same steps as initial installation,
however the desktop environment must first be stopped so that the drivers are