diff --git a/source/clear-linux/guides/maintenance/developer-workstation.rst b/source/clear-linux/guides/maintenance/developer-workstation.rst index fc0582d9..765c44c3 100644 --- a/source/clear-linux/guides/maintenance/developer-workstation.rst +++ b/source/clear-linux/guides/maintenance/developer-workstation.rst @@ -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 `, to learn the +We recommend learning about :ref:`swupd `, 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 ` +that shows you how to: * Use `swupd` to search for bundles * Use `swupd` to add bundles diff --git a/source/clear-linux/guides/maintenance/kernel-modules.rst b/source/clear-linux/guides/maintenance/kernel-modules.rst index 2339453a..94daac09 100644 --- a/source/clear-linux/guides/maintenance/kernel-modules.rst +++ b/source/clear-linux/guides/maintenance/kernel-modules.rst @@ -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. diff --git a/source/clear-linux/guides/maintenance/maintenance.rst b/source/clear-linux/guides/maintenance/maintenance.rst index 9e93ce9a..9e8f7785 100644 --- a/source/clear-linux/guides/maintenance/maintenance.rst +++ b/source/clear-linux/guides/maintenance/maintenance.rst @@ -12,7 +12,6 @@ completed. autoproxy developer-workstation - swupd-search enable-user-space swupd-guide bulk-provision diff --git a/source/clear-linux/guides/maintenance/swupd-guide.rst b/source/clear-linux/guides/maintenance/swupd-guide.rst index 686c7a1f..adbe6a1b 100644 --- a/source/clear-linux/guides/maintenance/swupd-guide.rst +++ b/source/clear-linux/guides/maintenance/swupd-guide.rst @@ -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 ` 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 ` 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 ` 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 -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 `. +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 + 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] + To find a bundle that contains your search term. -Finding a bundle containing a binary -==================================== +swupd bundle-add + 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 + To remove a bundle. -.. code-block:: bash +swupd --help + For additional :command:`swupd` commands. - swupd search -b +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 \ No newline at end of file +.. _bundles: https://github.com/clearlinux/clr-bundles/tree/master/bundles \ No newline at end of file diff --git a/source/clear-linux/guides/maintenance/swupd-search.rst b/source/clear-linux/guides/maintenance/swupd-search.rst deleted file mode 100644 index 45764a65..00000000 --- a/source/clear-linux/guides/maintenance/swupd-search.rst +++ /dev/null @@ -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 ` -* Understand :ref:`how swupd differs ` 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 ` - -* :ref:`Remove bundles` - -.. _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