mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-07-11 07:07:08 +00:00
TCS review of swupd-guide (#509)
* TCS review of swupd-guide Signed-off-by: MCamp859 <maryx.camp@intel.com> * Incoporated feedback. Signed-off-by: MCamp859 <maryx.camp@intel.com> * Added minor edits. Signed-off-by: MCamp859 <maryx.camp@intel.com> * Fixed bullets Signed-off-by: MCamp859 <maryx.camp@intel.com>
This commit is contained in:
Mary Camp
@@ -8,77 +8,68 @@ software.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 2
|
||||
:depth: 1
|
||||
|
||||
Description
|
||||
***********
|
||||
|
||||
:command:`swupd` has two main functions:
|
||||
|
||||
#. It manages software replacing APT or YUM, installing bundles
|
||||
#. Manages software and replaces APT or YUM, by installing bundles
|
||||
rather than packages.
|
||||
#. It checks for system updates and installs them.
|
||||
#. Checks for system updates and installs them.
|
||||
|
||||
:ref:`Bundles <bundles>` are the smallest granularity component that is
|
||||
managed by |CL| and contain everything needed to deliver a software
|
||||
capability. Rather than downloading a cascade of package dependencies when
|
||||
installing a piece of software, a bundle comes with all of its dependencies.
|
||||
:command:`swupd` manages overlapping dependencies behind the scenes ensuring
|
||||
that all software is compatible across the system.
|
||||
: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
|
||||
==========
|
||||
|
||||
In a traditional distribution, the process of describing current software
|
||||
versioning usually involves:
|
||||
Using package managers to keep track of software version compatibility or
|
||||
compare multiple systems on many Linux distributions can be cumbersome.
|
||||
|
||||
- Listing and keeping track of the current OS release (generally
|
||||
uninformative about any singular packages or functionality).
|
||||
With |CL| :command:`swupd`, versioning happens at the individual file-level.
|
||||
This means |CL| generates an entirely new OS version with any set of software
|
||||
changes to the system (including software downgrades or removals). This
|
||||
rolling release versioning model is similar to :command:`git` internal version
|
||||
tracking, where any of the individual file commits are tracked and move the
|
||||
pointer forward when changed.
|
||||
|
||||
- Keeping track of packages and repositories being used, and updating them
|
||||
individually.
|
||||
|
||||
- Listing and tracking every package available and installed on the
|
||||
system, none of which are directly tied to the current OS release.
|
||||
|
||||
This can be done effectively, but given the nearly endless combinations of
|
||||
packages and versions of packages a server may have, it quickly becomes
|
||||
non-trivial to define what "version" the system is and what software it
|
||||
is running without explicitly going through each system and inspecting
|
||||
every package.
|
||||
|
||||
With |CL|, we need track:
|
||||
|
||||
- One number
|
||||
|
||||
A number representing the **current** release of the OS is sufficient to
|
||||
describe the versions of all the software on the OS. Each build is
|
||||
composed of a specific set of bundles made from a particular version of
|
||||
packages. This matters on a daily basis to system administrators, who
|
||||
need to determine which of their systems do not have the latest security
|
||||
fixes, or which combinations of software have been tested. Every release
|
||||
of the same number is guaranteed to contain the same versions of software,
|
||||
so there's no ambiguity between two systems running the same version of |CL|.
|
||||
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. This matters on a
|
||||
daily basis to system administrators, who need to determine which of their
|
||||
systems do not have the latest security fixes, or which combinations of
|
||||
software have been tested. Every release of the same number is guaranteed to
|
||||
contain the same versions of software, so there's no ambiguity between two
|
||||
systems running the same version of |CL|.
|
||||
|
||||
Updating
|
||||
========
|
||||
|
||||
|CL| enforces regular updating of the OS by default and will automatically
|
||||
check for updates against a version server. The content server provides the
|
||||
|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. These Manifest files list and describe file contents, symlinks,
|
||||
*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
|
||||
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, the |CL| is able to
|
||||
patch to be as small as 15 KB. Using binary deltas, |CL| is able to
|
||||
apply only what is needed.
|
||||
|
||||
To get a more detailed understanding of how to generate update content for
|
||||
|CL| see the :ref:`mixer <mixer>` tool.
|
||||
For details on how to generate update content for |CL|, see the
|
||||
:ref:`mixer <mixer>` tool.
|
||||
|
||||
How it works
|
||||
************
|
||||
@@ -93,42 +84,41 @@ Prerequisites
|
||||
Updates
|
||||
=======
|
||||
|
||||
|CL| updates are automatic by default but can be set to occur only on
|
||||
|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 correct any problems.
|
||||
software, and can correct any problems.
|
||||
|
||||
Manifests
|
||||
---------
|
||||
|
||||
The Clear Linux OS 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 |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.
|
||||
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
|
||||
---------------------------------
|
||||
|
||||
The data that an update provisions to a system can be obtained in
|
||||
three different ways. There are three different methods, and they
|
||||
exist to optimize the delivery of content and speed up updates.
|
||||
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 Clear Linux OS to obtain the exact copy of the content
|
||||
for each version directly. This would be used if the OS verification
|
||||
needed to replace a single file, for instance.
|
||||
* *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 and 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) and cannot be used without having the original file content.
|
||||
* *Packs* are available for some releases. They combine many files to speed
|
||||
up the creation of installation media and large updates.
|
||||
|
||||
Bundle Search
|
||||
* *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` search downloads manifest data and searches for
|
||||
@@ -139,21 +129,21 @@ 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, will be marked [installed] in search
|
||||
Bundles that are already installed are marked **(installed)** in search
|
||||
results.
|
||||
|
||||
Optionally, you can review our `bundles`_ on GitHub.
|
||||
Optionally, you can review our `bundles`_ on GitHub\*.
|
||||
|
||||
Examples
|
||||
********
|
||||
|
||||
Example 1: Disable and Enable automatic updates
|
||||
Example 1: Disable and enable automatic updates
|
||||
===============================================
|
||||
|
||||
|CL| updates are automatic by default but can be set to occur only
|
||||
|CL| updates are automatic by default, but can be set to occur only
|
||||
on demand.
|
||||
|
||||
#. First verify your current auto-update setting.
|
||||
#. Verify your current auto-update setting.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -202,7 +192,7 @@ 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:`Virtual Machine (VM)` for
|
||||
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
|
||||
@@ -211,34 +201,33 @@ number of dependencies. Also, check out our tutorial: :ref:`kata`.
|
||||
|
||||
#. Find the right bundle.
|
||||
|
||||
* To return all possible matches for the search string enter
|
||||
:command:`swupd search`, followed by 'kata':
|
||||
To return all possible matches for the search string, enter
|
||||
:command:`swupd search`, followed by 'kata':
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd search kata
|
||||
sudo swupd search kata
|
||||
|
||||
The output should be similar to:
|
||||
The output should be similar to:
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: console
|
||||
|
||||
Bundle with the best search result:
|
||||
Bundle with the best search result:
|
||||
|
||||
containers-virt - Run container applications from Dockerhub in lightweight virtual machines
|
||||
containers-virt - Run container applications from Dockerhub in lightweight virtual machines
|
||||
|
||||
This bundle can be installed with:
|
||||
This bundle can be installed with:
|
||||
|
||||
swupd bundle-add containers-virt
|
||||
swupd bundle-add containers-virt
|
||||
|
||||
Alternative bundle options are
|
||||
Alternative bundle options are
|
||||
|
||||
cloud-native-basic - Contains ClearLinux native software for Cloud
|
||||
cloud-native-basic - Contains ClearLinux native software for Cloud
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
If your search does not produce results with a specific
|
||||
term, shorten the search term. For example, use *kube* instead of
|
||||
*kubernetes*.
|
||||
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.
|
||||
|
||||
@@ -248,7 +237,7 @@ number of dependencies. Also, check out our tutorial: :ref:`kata`.
|
||||
|
||||
.. note::
|
||||
|
||||
To add multiple bundles simply add a space followed by the bundle name.
|
||||
To add multiple bundles, add a space followed by the bundle name.
|
||||
|
||||
The output of a successful installation should be similar to:
|
||||
|
||||
@@ -279,7 +268,7 @@ been added to, overwritten, removed, or modified (e.g., permissions).
|
||||
sudo swupd diagnose
|
||||
|
||||
All directories that are watched by :command:`swupd` are verified according
|
||||
to the manifest data and hash mismatches are flagged as follows:
|
||||
to the manifest data. Hash mismatches are flagged as follows:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -295,47 +284,49 @@ to the manifest data and hash mismatches are flagged as follows:
|
||||
423 files did not match
|
||||
Verify successful
|
||||
|
||||
In this case, python packages that were installed on top of the default
|
||||
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 that will be ignored.
|
||||
can be added including a white list of directories to be ignored.
|
||||
|
||||
The following command will repair issues, remove unknown items, and
|
||||
ignore files or directories matching `/usr/lib/python`:
|
||||
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
|
||||
Quick reference
|
||||
***************
|
||||
|
||||
swupd info
|
||||
To see the currently installed version and update servers.
|
||||
Returns the currently installed version and update servers.
|
||||
|
||||
swupd update <version number>
|
||||
To update to a specific version or with no arguments to update to latest.
|
||||
Updates to a specific version or updates to latest version if no
|
||||
arguments are used.
|
||||
|
||||
swupd bundle-list [--all]
|
||||
To list installed bundles.
|
||||
Lists installed bundles.
|
||||
|
||||
swupd bundle-add [-b] <search term>
|
||||
To find a bundle that contains your search term.
|
||||
Finds a bundle that contains your search term.
|
||||
|
||||
swupd bundle-add <bundle name>
|
||||
To add a bundle.
|
||||
Adds a bundle.
|
||||
|
||||
swupd bundle-remove <bundle name>
|
||||
To remove a bundle.
|
||||
Removes a bundle.
|
||||
|
||||
swupd --help
|
||||
For additional :command:`swupd` commands.
|
||||
Lists additional :command:`swupd` commands.
|
||||
|
||||
man swupd
|
||||
To reference the :command:`swupd` man page, or see the
|
||||
`source documentation`_ available on github.
|
||||
Opens the :command:`swupd` man page.
|
||||
|
||||
Refer to :command:`swupd` `source documentation`_ on GitHub for more details.
|
||||
|
||||
Related topics
|
||||
**************
|
||||
|
||||
Reference in New Issue
Block a user