swupd¶
swupd links a Clear Linux* OS installation with upstream updates and software.
Description¶
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.
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¶
The device is on a well-connected network.
The device is able to connect to an update server. The default server is: https://cdn.download.clearlinux.org/update/
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.
Bundle search¶
swupd searches download manifest data for bundles that match the term. Enter only one term, or hyphenated term, per search. Use the 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¶
Clear Linux OS updates are automatic by default, but can be set to occur only on demand.
Verify your current auto-update setting.
sudo swupd autoupdate
Output:
Enabled
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.
Check manually for updates.
sudo swupd check-update
Install an update after identifying one that you need.
sudo swupd update --version <version number>
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*.
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.
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.