From 7a009837718b3d9caf2b5c38863497d1ad2f591d Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Thu, 6 Jun 2019 15:31:47 -0700 Subject: [PATCH 1/4] Replaces `swupd verify` and related flag commands per @castulo. - Closes #522 - Deprecates use of: `swupd verify` `swupd verify --fix` `swupd verify --install` `-m / --manifest` Signed-off-by: Michael Vincerra --- source/clear-linux/concepts/swupd-about.rst | 4 ++-- .../guides/maintenance/fix-broken-install.rst | 4 ++-- .../guides/network/custom-clear-container.rst | 9 ++++----- source/clear-linux/guides/tooling/autospec.rst | 2 +- source/clear-linux/guides/tooling/swupd-guide.rst | 6 +++--- source/clear-linux/tutorials/kata.rst | 2 +- source/clear-linux/tutorials/nvidia.rst | 10 ++++------ 7 files changed, 17 insertions(+), 20 deletions(-) diff --git a/source/clear-linux/concepts/swupd-about.rst b/source/clear-linux/concepts/swupd-about.rst index 99edfa1b..ec0d1446 100644 --- a/source/clear-linux/concepts/swupd-about.rst +++ b/source/clear-linux/concepts/swupd-about.rst @@ -62,9 +62,9 @@ Update integrity :command:`swupd` operates against a published manifest of files for a particular |CL| version that contains the unique hash of each file. This is -the basis of the :command:`swupd verify` subcommand, which allows a |CL| +the basis of the :command:`swupd diagnose` subcommand, which allows a |CL| system to check for and remediate any discrepancies to system files. As -necessary, :command:`swupd verify` provides a useful way for software +necessary, :command:`swupd diagnose` provides a useful way for software developers to return to a known filesystem state. Bundles diff --git a/source/clear-linux/guides/maintenance/fix-broken-install.rst b/source/clear-linux/guides/maintenance/fix-broken-install.rst index 864c9972..1ffe275d 100644 --- a/source/clear-linux/guides/maintenance/fix-broken-install.rst +++ b/source/clear-linux/guides/maintenance/fix-broken-install.rst @@ -48,7 +48,7 @@ Mount root partition, verify, and fix sudo mount /dev/sda3 /mnt -#. Verify that you mounted the correct root partition by checking for some +#. Verify that you mounted the correct root partition by checking for some files commonly found on |CL| systems. .. code-block:: bash @@ -60,7 +60,7 @@ Mount root partition, verify, and fix .. code-block:: bash - sudo swupd verify --fix --picky --path=/mnt + sudo swupd repair --picky --path=/mnt :ref:`Learn more about how swupd works `. diff --git a/source/clear-linux/guides/network/custom-clear-container.rst b/source/clear-linux/guides/network/custom-clear-container.rst index bcc0fcac..062c39de 100644 --- a/source/clear-linux/guides/network/custom-clear-container.rst +++ b/source/clear-linux/guides/network/custom-clear-container.rst @@ -133,25 +133,24 @@ Build the base container image .. code-block:: bash - swupd verify --install --path="base" --manifest 17870 \ + swupd os-install --path="base" --version 17870 \ --url https://cdn.download.clearlinux.org/update \ --statedir "$PWD/swupd-state" --no-boot-update The `swupd` example uses the following flags: - * :command:`verify –-install` tells `swupd` to download and install. + * :command:`os-install` tells `swupd` to download and install. * :command:`--path` specifies the root path where the bundles are to be installed. - * :command:`--manifest` specifies the version of the |CL| bundles. + * :command:`-V / --version` specifies the version of the |CL| bundles. * :command:`--url` specifies the URL of the bundles repository. * :command:`--statedir` specifies the state directory where downloaded bundles and any state information are stored. * :command:`--no-boot-update` tells `swupd` to skip updating boot files because boot files are not required for a container. - For more information on `swupd` flags, enter the :command:`swupd verify -h` - command. + For more information on `swupd` flags, enter the :command:`swupd diagnose -h` command. Example output: diff --git a/source/clear-linux/guides/tooling/autospec.rst b/source/clear-linux/guides/tooling/autospec.rst index 3779e52c..59cb9bfe 100644 --- a/source/clear-linux/guides/tooling/autospec.rst +++ b/source/clear-linux/guides/tooling/autospec.rst @@ -433,7 +433,7 @@ To test an autospec created package directly on the |CL| development system: tests. #. After testing has been completed, the software and any related files must - be identified and deleted. The :command:`swupd verify --picky --fix` + be identified and deleted. The :command:`swupd diagnose --picky --fix` command can help restore the state of the :file:`/usr` directory (see :ref:`swupd `) however any other files must be cleaned up manually. diff --git a/source/clear-linux/guides/tooling/swupd-guide.rst b/source/clear-linux/guides/tooling/swupd-guide.rst index 72cb8351..69fc78bb 100644 --- a/source/clear-linux/guides/tooling/swupd-guide.rst +++ b/source/clear-linux/guides/tooling/swupd-guide.rst @@ -187,7 +187,7 @@ on demand. .. code-block:: bash - sudo swupd update -m + sudo swupd update --version #. Re-enable automatic installs. @@ -276,7 +276,7 @@ been added to, overwritten, removed, or modified (e.g., permissions). .. code-block:: bash - sudo swupd verify + 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: @@ -307,7 +307,7 @@ ignore files or directories matching `/usr/lib/python`: .. code-block:: bash - sudo swupd verify --fix --picky --picky-whitelist=/usr/lib/python + sudo swupd repair --picky --picky-whitelist=/usr/lib/python Quick Reference *************** diff --git a/source/clear-linux/tutorials/kata.rst b/source/clear-linux/tutorials/kata.rst index 1fb1fd4f..cecd365e 100644 --- a/source/clear-linux/tutorials/kata.rst +++ b/source/clear-linux/tutorials/kata.rst @@ -110,7 +110,7 @@ Troubleshooting .. code-block:: bash - sudo swupd verify + sudo swupd info .. _Kata Containers: https://katacontainers.io/ diff --git a/source/clear-linux/tutorials/nvidia.rst b/source/clear-linux/tutorials/nvidia.rst index 55c84a88..6b1bedb5 100644 --- a/source/clear-linux/tutorials/nvidia.rst +++ b/source/clear-linux/tutorials/nvidia.rst @@ -179,17 +179,15 @@ Install the NVIDIA Drivers .. code-block:: bash - sudo swupd verify --quick --fix --bundles=lib-opengl + sudo swupd repair --quick --bundles=lib-opengl .. note:: The NVIDIA software places some files under the :file:`/usr` subdirectory which are not managed by |CL| and conflict with the |CL| stateless design. - Although a limited version of :command:`swupd verify --fix` is ran above, - other uses of the :command:`swupd verify --fix` command should be avoided + Although a limited version of :command:`swupd repair` is ran above, + other uses of the :command:`swupd repair` command should be avoided with the proprietary NVIDIA drivers installed. - - Updating the NVIDIA Drivers @@ -200,7 +198,7 @@ The proprietary NVIDIA drivers are installed manually outside of :ref:`swupd Updating the NVIDIA drivers follows the same steps as initial installation, however the desktop environment must first be stopped so that the drivers are -not in use. +not in use. #. Follow the steps in `Download the NVIDIA Drivers for Linux`_ section to get the latest NVIDIA drivers. From 655ec84042a5f03de956706ea0e8c8e866fb07aa Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Thu, 6 Jun 2019 15:42:52 -0700 Subject: [PATCH 2/4] Revise instance where `swupd repair` is better option than `diagnose`. Signed-off-by: Michael Vincerra --- source/clear-linux/guides/tooling/autospec.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/guides/tooling/autospec.rst b/source/clear-linux/guides/tooling/autospec.rst index 59cb9bfe..299c5b44 100644 --- a/source/clear-linux/guides/tooling/autospec.rst +++ b/source/clear-linux/guides/tooling/autospec.rst @@ -433,7 +433,7 @@ To test an autospec created package directly on the |CL| development system: tests. #. After testing has been completed, the software and any related files must - be identified and deleted. The :command:`swupd diagnose --picky --fix` + be identified and deleted. The :command:`swupd repair --picky` command can help restore the state of the :file:`/usr` directory (see :ref:`swupd `) however any other files must be cleaned up manually. From 5086e9180d4e163c898d9389b28d1eaf234689c7 Mon Sep 17 00:00:00 2001 From: Michael Vincerra Date: Fri, 7 Jun 2019 11:14:21 -0700 Subject: [PATCH 3/4] Incorporates feedback from @castulo on revised swupd commands. Signed-off-by: Michael Vincerra --- source/clear-linux/concepts/swupd-about.rst | 8 +-- .../guides/network/custom-clear-container.rst | 57 +------------------ .../clear-linux/guides/tooling/autospec.rst | 3 +- 3 files changed, 6 insertions(+), 62 deletions(-) diff --git a/source/clear-linux/concepts/swupd-about.rst b/source/clear-linux/concepts/swupd-about.rst index ec0d1446..c6d6b749 100644 --- a/source/clear-linux/concepts/swupd-about.rst +++ b/source/clear-linux/concepts/swupd-about.rst @@ -60,12 +60,8 @@ to update. Update integrity ---------------- -:command:`swupd` operates against a published manifest of files for a -particular |CL| version that contains the unique hash of each file. This is -the basis of the :command:`swupd diagnose` subcommand, which allows a |CL| -system to check for and remediate any discrepancies to system files. As -necessary, :command:`swupd diagnose` provides a useful way for software -developers to return to a known filesystem state. +This is the basis of the :command:`swupd diagnose` subcommand, which allows a |CL| system to check for any discrepancies to system files. As necessary, +:command: `swupd repair` provides a useful way for software developers to remediate these discrepancies and return to a known filesystem state. Bundles ======= diff --git a/source/clear-linux/guides/network/custom-clear-container.rst b/source/clear-linux/guides/network/custom-clear-container.rst index 062c39de..88ac8e7c 100644 --- a/source/clear-linux/guides/network/custom-clear-container.rst +++ b/source/clear-linux/guides/network/custom-clear-container.rst @@ -82,67 +82,16 @@ Build the base container image swupd bundle-add containers-basic systemctl start docker -#. Create the directory structure to build the |CL| container. +#. Use `os-install` to download and install the bundles. .. code-block:: bash - mkdir -p ./custom-clear-linux-container/base/usr/share/clear/bundles - cd custom-clear-linux-container - - .. note:: - - * The directories :file:`custom-clear-linux-container` and - :file:`base` are used for staging. You can rename these directories. - - * The directories :file:`/usr/share/clear/bundles` are mandatory and - cannot be renamed. - -#. Create the reference files of the minimum required |CL| bundles, - :file:`os-core` and :file:`os-core-update`. The software updater - uses the reference filenames to determine which bundles to download and - install. - - - .. code-block:: bash - - touch ./base/usr/share/clear/bundles/os-core - touch ./base/usr/share/clear/bundles/os-core-update - - .. note:: - - * :file:`os-core` provides the minimal Linux namespace. - * :file:`os-core-update` provides the basic suite for running the |CL| - updater. - -#. Optionally, you can include additional bundles with the base image. - - #. Identify the desired bundles on the |CL| website's - :ref:`bundles` page or execute the - :command:`swupd bundle-list -a` command. - - #. Create reference files for the identified bundles. For example, - to include the :file:`editors` and :file:`network-basic` bundles, - enter the commands: - - .. code-block:: bash - - touch ./base/usr/share/clear/bundles/editors - touch ./base/usr/share/clear/bundles/network-basic - -#. Use `swupd` to download and install the bundles. - - .. code-block:: bash - - swupd os-install --path="base" --version 17870 \ - --url https://cdn.download.clearlinux.org/update \ - --statedir "$PWD/swupd-state" --no-boot-update + swupd os-install --url https://cdn.download.clearlinux.org/update --statedir "$PWD"/swupd-state --no-boot-update --version 29790 -B os-core-update,editors,network-basic base The `swupd` example uses the following flags: * :command:`os-install` tells `swupd` to download and install. - * :command:`--path` specifies the root path where the bundles are to be - installed. * :command:`-V / --version` specifies the version of the |CL| bundles. * :command:`--url` specifies the URL of the bundles repository. * :command:`--statedir` specifies the state directory where downloaded bundles @@ -150,7 +99,7 @@ Build the base container image * :command:`--no-boot-update` tells `swupd` to skip updating boot files because boot files are not required for a container. - For more information on `swupd` flags, enter the :command:`swupd diagnose -h` command. + For more information on `swupd` flags, enter the :command:`swupd os-install -h` command. Example output: diff --git a/source/clear-linux/guides/tooling/autospec.rst b/source/clear-linux/guides/tooling/autospec.rst index 299c5b44..f07252f2 100644 --- a/source/clear-linux/guides/tooling/autospec.rst +++ b/source/clear-linux/guides/tooling/autospec.rst @@ -442,8 +442,7 @@ To test an autospec created package directly on the |CL| development system: References ********** -Reference the `autospec README`_ for details regarding autospec commands and -options. +Reference the `autospec README`_ for details regarding `autospec` commands and options. Setup environment to build source ================================= From b302966d26d3308648139a2b202bec4db8020a80 Mon Sep 17 00:00:00 2001 From: Kevin Putnam Date: Mon, 10 Jun 2019 15:13:02 -0700 Subject: [PATCH 4/4] Fixed broken :command: role. Signed-off-by: Kevin Putnam --- source/clear-linux/concepts/swupd-about.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/concepts/swupd-about.rst b/source/clear-linux/concepts/swupd-about.rst index c6d6b749..8d6e5bb4 100644 --- a/source/clear-linux/concepts/swupd-about.rst +++ b/source/clear-linux/concepts/swupd-about.rst @@ -61,7 +61,7 @@ Update integrity ---------------- This is the basis of the :command:`swupd diagnose` subcommand, which allows a |CL| system to check for any discrepancies to system files. As necessary, -:command: `swupd repair` provides a useful way for software developers to remediate these discrepancies and return to a known filesystem state. +:command:`swupd repair` provides a useful way for software developers to remediate these discrepancies and return to a known filesystem state. Bundles =======