swupd

swupd links a Clear Linux* OS installation with upstream updates and software.

Description

swupd has two main functions:

  1. Manage software and replace APT or YUM, by installing bundles rather than packages.

  2. Check for system updates and install them.

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.

Bundles contain everything needed to deliver a software capability. They are the smallest granularity component that is managed by Clear Linux OS. 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 Clear Linux OS swupd, versioning happens at the individual file level. This means Clear Linux OS 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 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 Clear Linux OS.

Updating

Clear Linux OS 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 Clear Linux OS are also efficient. Unlike package-based distributions, 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, Clear Linux OS is able to apply only what is needed.

For details on how to generate update content for Clear Linux OS, see the mixer tool.

How it works

Prerequisites

Updates

Clear Linux OS updates are automatic by default, but can be set to occur only on demand. 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 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

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 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.

Examples

Example 1: Disable and enable automatic updates

Clear Linux OS updates are automatic by default, but can be set to occur only on demand.

  1. Verify your current auto-update setting.

    sudo swupd autoupdate

    Output:

    Enabled

  2. Disable automatic updates.

    sudo swupd autoupdate --disable

    Output:

    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.

  3. Check manually for updates.

    sudo swupd check-update

  4. Install an update after identifying one that you need.

    sudo swupd update --version <version number>

  5. Re-enable automatic installs.

    sudo swupd autoupdate --enable

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 VM for improved security.

Clear Linux OS 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: Kata Containers*.

  1. Find the correct bundle.

    To return all possible matches for the search string, enter swupd search, followed by ‘kata’:

    sudo swupd search kata

    The output should be similar to:

    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.

  2. Add the bundle.

    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:

    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

swupd can determine whether system directories and files have been added to, overwritten, removed, or modified (e.g., permissions).

sudo swupd diagnose

All directories that are watched by swupd are verified according to the manifest data. Hash mismatches are flagged as follows:

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. swupd can be directed to ignore or fix issues based on command line options.

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 /usr/lib/python:

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 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 swupd commands.

man swupd

Opens the swupd man page.

Refer to swupd source documentation on GitHub for more details.