mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-08-25 09:27:37 +00:00
Update to the swupd Guide (#409)
* partial commit to save work * latest changes * replaced out of date swupd-guide.rst with contents of swupd-temp.rst; removed swupd-temp.rst * changed page ref to swupd-guide from swupd; too many existing dependencies * Added descriptions of manifests and delta packs from How to Clear * fixed typo * changed header organization slightly and removed unnecessary text formatting * updated a couple headers to make more sense * numerous cosmetic and readability changes based on full render review * changes to description section based on updated swupd concept page * updates based on feedback * updates based on technical review * removed swupd-search.rst; updated maintenance.rst toc tree after removal; updated references in developer-workstation.rst and kernel-module.rst that linked to swupd-search.rst
This commit is contained in:
Kevin Putnam
committed by
michael vincerra
michael vincerra
parent
1e0175b195
commit
99f9289a67
@@ -78,10 +78,11 @@ While your role may not neatly fit in one of these categories, consider using Ta
|
||||
`swupd` search
|
||||
**************
|
||||
|
||||
We recommend trying out :ref:`swupd search <swupd-search>`, to learn the
|
||||
We recommend learning about :ref:`swupd <swupd-guide>`, to learn the
|
||||
commands to search for and add bundles relevant to your project.
|
||||
|
||||
:ref:`swupd-search` shows you how to:
|
||||
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
|
||||
|
||||
@@ -45,7 +45,7 @@ security practices, see the :ref:`security` page.
|
||||
|
||||
You can search for kernel module file names, which end with the :file:`.ko`
|
||||
file extension, using the :command:`swupd search` command. For example:
|
||||
:command:`sudo swupd search ${module_name}.ko`. See :ref:`swupd-search` for
|
||||
:command:`sudo swupd search ${module_name}.ko`. See :ref:`swupd-guide` for
|
||||
more information.
|
||||
|
||||
|
||||
|
||||
@@ -12,7 +12,6 @@ completed.
|
||||
|
||||
autoproxy
|
||||
developer-workstation
|
||||
swupd-search
|
||||
enable-user-space
|
||||
swupd-guide
|
||||
bulk-provision
|
||||
|
||||
@@ -1,113 +1,285 @@
|
||||
.. _swupd-guide:
|
||||
|
||||
Use swupd
|
||||
#########
|
||||
swupd
|
||||
#####
|
||||
|
||||
*swupd* manages the software update capability of |CL-ATTR|. It can check for
|
||||
valid system updates and, if found, download and install them. It can also
|
||||
perform verification of the system software.
|
||||
|
||||
|CL| uses :ref:`bundles <bundles-about>` as the base abstraction for
|
||||
installing functionality on top of the core operating system. Use the `swupd`
|
||||
tool to install and remove bundles.
|
||||
|
||||
This guide assumes:
|
||||
|
||||
* The device is on a well-connected network.
|
||||
|
||||
* The device is able to connect to the release infrastructure
|
||||
http://update.clearlinux.org
|
||||
:command:`swupd` links a |CL-ATTR| installation with upstream updates and
|
||||
software.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 2
|
||||
|
||||
.. _man_swupd:
|
||||
Description
|
||||
***********
|
||||
|
||||
For a full listing of commands and options please see the man page found in
|
||||
the `swupd` `source code`_ or on |CL| itself.
|
||||
:command:`swupd` has two main functions:
|
||||
|
||||
.. code-block:: bash
|
||||
#. It manages software replacing APT or YUM, installing bundles
|
||||
rather than packages.
|
||||
#. It checks for system updates and installs them.
|
||||
|
||||
man swupd
|
||||
: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.
|
||||
|
||||
OS update and verification
|
||||
**************************
|
||||
Versioning
|
||||
==========
|
||||
|
||||
|CL| is designed to promote a regular update cadence. `swupd` helps to
|
||||
make sure that process is simple and secure.
|
||||
In a traditional distribution, the process of describing current software
|
||||
versioning usually involves:
|
||||
|
||||
View OS info
|
||||
============
|
||||
- Listing and keeping track of the current OS release (generally
|
||||
uninformative about any singular packages or functionality).
|
||||
|
||||
Current OS version and update server info:
|
||||
- Keeping track of packages and repositories being used, and updating them
|
||||
individually.
|
||||
|
||||
.. code-block:: bash
|
||||
- Listing and tracking every package available and installed on the
|
||||
system, none of which are directly tied to the current OS release.
|
||||
|
||||
swupd info
|
||||
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.
|
||||
|
||||
.. code-block:: console
|
||||
With |CL|, we need track:
|
||||
|
||||
Installed version: 23330
|
||||
Version URL: https://cdn.download.clearlinux.org/update/
|
||||
Content URL: https://cdn.download.clearlinux.org/update/
|
||||
- One number
|
||||
|
||||
Enable or disable automatic updates
|
||||
===================================
|
||||
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|.
|
||||
|
||||
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
|
||||
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,
|
||||
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, the |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.
|
||||
|
||||
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 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 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Bundle Search
|
||||
=============
|
||||
|
||||
:command:`swupd` search downloads manifest data and searches 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, will be 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. To verify your current auto-update setting:
|
||||
on demand.
|
||||
|
||||
.. code-block:: bash
|
||||
#. First verify your current auto-update setting.
|
||||
|
||||
sudo swupd autoupdate
|
||||
.. code-block:: bash
|
||||
|
||||
Disable automatic updates:
|
||||
sudo swupd autoupdate
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: console
|
||||
|
||||
sudo swupd autoupdate --disable
|
||||
Enabled
|
||||
|
||||
To re-enable automatic:
|
||||
#. Disable automatic updates.
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd autoupdate --enable
|
||||
sudo swupd autoupdate --disable
|
||||
|
||||
Check for updates
|
||||
=================
|
||||
.. code-block:: console
|
||||
|
||||
.. code-block:: bash
|
||||
Warning: disabling automatic updates may take you out of compliance with your IT policy
|
||||
|
||||
sudo swupd check-update
|
||||
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.
|
||||
|
||||
Perform a manual update
|
||||
=======================
|
||||
#. Check manually for updates.
|
||||
|
||||
You can update to a specific version or accept the latest as the default with
|
||||
no arguments. Initiate a manual update:
|
||||
.. code-block:: bash
|
||||
|
||||
.. code-block:: bash
|
||||
sudo swupd check-update
|
||||
|
||||
sudo swupd update -m 23330
|
||||
#. Install an update after identifying one that you need.
|
||||
|
||||
.. note::
|
||||
.. code-block:: bash
|
||||
|
||||
After a kernel update, reboot immediately for the enhancements to
|
||||
take effect.
|
||||
sudo swupd update -m <version number>
|
||||
|
||||
System Software Verification
|
||||
============================
|
||||
#. Re-enable automatic installs.
|
||||
|
||||
`swupd` can determine whether system directories and files have been added
|
||||
to, overwritten, removed, or modified (e.g., permissions).
|
||||
.. 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:`Virtual Machine (VM)` 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 right 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 simply 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 sytem 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 verify
|
||||
|
||||
All directories that are watched by `swupd` are verified according to
|
||||
the manifest data and hash mismatches are flagged as follows:
|
||||
All directories that are watched by :command:`swupd` are verified according
|
||||
to the manifest data and hash mismatches are flagged as follows:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@@ -124,15 +296,11 @@ the manifest data and hash mismatches are flagged as follows:
|
||||
Verify successful
|
||||
|
||||
In this case, python packages that were installed on top of the default
|
||||
install were flagged as mismatched. `swupd` can be directed to ignore
|
||||
or fix issues based on :ref:`command line options <man_swupd>`.
|
||||
install were flagged as mismatched. :command:`swupd` can be directed to
|
||||
ignore or fix issues based on command line options.
|
||||
|
||||
Fixing hash mismatches
|
||||
======================
|
||||
|
||||
`swupd` can correct any issues it detects. Additional directives can be
|
||||
added including a white list of directories that will be ignored, if
|
||||
desired.
|
||||
:command:`swupd` can correct any issues it detects. Additional directives
|
||||
can be added including a white list of directories that will be ignored.
|
||||
|
||||
The following command will repair issues, remove unknown items, and
|
||||
ignore files or directories matching `/usr/lib/python`:
|
||||
@@ -141,45 +309,47 @@ ignore files or directories matching `/usr/lib/python`:
|
||||
|
||||
sudo swupd verify --fix --picky --picky-whitelist=/usr/lib/python
|
||||
|
||||
Bundles
|
||||
*******
|
||||
Quick Reference
|
||||
***************
|
||||
|
||||
Listing installed bundles
|
||||
=========================
|
||||
swupd info
|
||||
To see the currently installed version and update servers.
|
||||
|
||||
You can list all of the bundles currently installed on the system
|
||||
swupd update <version number>
|
||||
To update to a specific version or with no arguments to update to latest.
|
||||
|
||||
.. code-block:: bash
|
||||
swupd bundle-list [--all]
|
||||
To list installed bundles.
|
||||
|
||||
sudo swupd bundle-list --all
|
||||
swupd bundle-add [-b] <search term>
|
||||
To find a bundle that contains your search term.
|
||||
|
||||
Finding a bundle containing a binary
|
||||
====================================
|
||||
swupd bundle-add <bundle name>
|
||||
To add a bundle.
|
||||
|
||||
Run the following to display a list of bundles that contain a particular
|
||||
binary. Note that it may be present in multiple bundles:
|
||||
swupd bundle-remove <bundle name>
|
||||
To remove a bundle.
|
||||
|
||||
.. code-block:: bash
|
||||
swupd --help
|
||||
For additional :command:`swupd` commands.
|
||||
|
||||
swupd search -b <binary you want>
|
||||
man swupd
|
||||
To reference the :command:`swupd` man page, or see the
|
||||
`source documentation`_ available on github.
|
||||
|
||||
Adding a bundle
|
||||
===============
|
||||
Related topics
|
||||
**************
|
||||
|
||||
Start by selecting a bundle from the list of :ref:`bundles`. In
|
||||
this example we're adding dev-utils-dev, which is useful for development.
|
||||
* :ref:`autospec`
|
||||
* :ref:`mixer`
|
||||
* :ref:`bundles`
|
||||
|
||||
.. code-block:: bash
|
||||
.. _source documentation: https://github.com/clearlinux/swupd-client/blob/master/docs/swupd.1.rst
|
||||
|
||||
sudo swupd bundle-add dev-utils-dev
|
||||
.. _Kata Containers: https://clearlinux.org/containers
|
||||
|
||||
Removing a bundle
|
||||
=================
|
||||
.. _one bundle: https://github.com/clearlinux/clr-bundles/blob/master/bundles/containers-virt
|
||||
|
||||
Dependencies common to other bundles will not be removed
|
||||
.. _Bundle Definition Files: https://github.com/clearlinux/clr-bundles
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-remove dev-utils-dev
|
||||
|
||||
.. _source code: https://github.com/clearlinux/swupd-client/blob/master/docs/swupd.1.rst
|
||||
.. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles
|
||||
@@ -1,140 +0,0 @@
|
||||
.. _swupd-search:
|
||||
|
||||
Use swupd search to find bundles
|
||||
################################
|
||||
|
||||
This document explains how to use `swupd search` to find and add
|
||||
bundles in |CL-ATTR|.
|
||||
|
||||
Assumptions
|
||||
***********
|
||||
|
||||
This guide assumes you:
|
||||
|
||||
* Possess a basic knowledge of :ref:`swupd <swupd-guide>`
|
||||
* Understand :ref:`how swupd differs <swupd-about>` from
|
||||
other Linux\* distributions
|
||||
* May :ref:`mixer` to produce a custom distribution/image
|
||||
|
||||
How do I search for a bundle?
|
||||
*****************************
|
||||
|
||||
Use `swupd search` to locate the bundle where the application binary exists.
|
||||
|
||||
Example: Kata\* Containers
|
||||
==========================
|
||||
|
||||
Containers have revolutionized the way we manage cloud infrastructure.
|
||||
Traditional containers often share the same OS kernel, which raises
|
||||
security concerns. Instead, with Kata Containers, each container has its own
|
||||
kernel instance and runs on its own :abbr:`Virtual Machine (VM)`. Whether you're running 3 or 300 nodes on your cluster, Kata Containers provide a
|
||||
lightweight, fast, and secure option for app/container management.
|
||||
|
||||
In |CL|, you only need to add `one bundle`_ to use `Kata Containers`_:
|
||||
`containers-virt`. Also, check out our tutorial: :ref:`kata`.
|
||||
|
||||
We need to find *kata* containers in a bundle. How do we search for it?
|
||||
|
||||
#. Enter :command:`swupd search`, followed by 'kata' as the search term:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd search kata
|
||||
|
||||
.. note::
|
||||
|
||||
`swupd search` downloads |CL| manifest data and searches for
|
||||
matching paths. Enter only one term, or hyphenated term, per
|
||||
search. Use the command :command:`man swupd` to learn more.
|
||||
|
||||
#. Alternatively, if you want to search binaries only, add the `-b`
|
||||
flag:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd search -b kata
|
||||
|
||||
.. note::
|
||||
|
||||
`-b` flag, or `--binary`, means: Restrict search to program binary paths. Omit this flag if you want a larger scope of search results.
|
||||
|
||||
Only the base bundle is returned. In |CL|, *bundles* can contain
|
||||
other *bundles* via `includes`. For more details, see `Bundle Definition Files`_ and its subdirectory *bundles*.
|
||||
|
||||
If your search does not produce results on a specific term when using
|
||||
the `-b` flag, abbreviate the search term. For example, if you search
|
||||
for *kubernetes* and it does not show results, instead abbreviate the
|
||||
term to *kube* to show results.
|
||||
|
||||
#. Optionally, you can review our `bundles`_ or individual `packages`_
|
||||
|
||||
#. Using `sudo swupd search -b kata` shows a match for our use case.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
Bundle containers-virt (834 MB to install)
|
||||
/usr/bin/kata-virtfs-lite-proxy-helper
|
||||
/usr/bin/kata-runtime
|
||||
/usr/bin/kata-qemu-lite-system-x86_64
|
||||
/usr/bin/kata-qemu-lite-pr-helper
|
||||
/usr/bin/kata-qemu-lite-ga
|
||||
/usr/bin/kata-collect-data.sh
|
||||
|
||||
.. note::
|
||||
|
||||
If the bundle is already installed, *[installed]* appears in search results. If this doesn't apppear, the bundle needs to be installed.
|
||||
|
||||
#. Add the bundle `containers-virt`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo swupd bundle-add containers-virt
|
||||
|
||||
.. note::
|
||||
|
||||
To add multiple bundles simply add a space followed by the bundle name.
|
||||
|
||||
#. When prompted, enter your password.
|
||||
|
||||
#. Upon successful installation, your console should show similar data:
|
||||
|
||||
.. 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
|
||||
|
||||
Related Topics
|
||||
==============
|
||||
|
||||
Learn how to:
|
||||
|
||||
* :ref:`kata`
|
||||
|
||||
* :ref:`kata_migration`
|
||||
|
||||
* :ref:`swupd-guide`
|
||||
|
||||
* :ref:`Show all available bundles <swupd-guide>`
|
||||
|
||||
* :ref:`Remove bundles<swupd-guide>`
|
||||
|
||||
.. _Kata Containers: https://clearlinux.org/blogs/clear-linux-os-announces-support-kata-containers
|
||||
|
||||
.. _one bundle: 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
|
||||
|
||||
.. _packages: https://github.com/clearlinux/clr-bundles/blob/master/packages
|
||||
Reference in New Issue
Block a user