From 9b544a135e62d01f063a8c1257a6fa207a9237bb Mon Sep 17 00:00:00 2001 From: Mary Camp Date: Mon, 17 Jun 2019 12:36:59 -0400 Subject: [PATCH] TCS review of swupd-guide (#509) * TCS review of swupd-guide Signed-off-by: MCamp859 * Incoporated feedback. Signed-off-by: MCamp859 * Added minor edits. Signed-off-by: MCamp859 * Fixed bullets Signed-off-by: MCamp859 --- .../guides/tooling/swupd-guide.rst | 195 +++++++++--------- 1 file changed, 93 insertions(+), 102 deletions(-) diff --git a/source/clear-linux/guides/tooling/swupd-guide.rst b/source/clear-linux/guides/tooling/swupd-guide.rst index 69fc78bb..dedd7499 100644 --- a/source/clear-linux/guides/tooling/swupd-guide.rst +++ b/source/clear-linux/guides/tooling/swupd-guide.rst @@ -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 ` 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 ` 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 ` tool. +For details on how to generate update content for |CL|, see the +:ref:`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 - 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] - To find a bundle that contains your search term. + Finds a bundle that contains your search term. swupd bundle-add - To add a bundle. + Adds a bundle. swupd bundle-remove - 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 **************