diff --git a/source/FAQ/index.rst b/source/FAQ/index.rst index 4b7be4f2..5766da4e 100644 --- a/source/FAQ/index.rst +++ b/source/FAQ/index.rst @@ -9,7 +9,6 @@ Below is a list of commonly asked questions with answers sourced from the .. contents:: :local: :depth: 2 - General ******* @@ -44,7 +43,7 @@ Is telemetry required? The telemetry solution provided by |CL| is entirely optional and customizable. It is disabled by default. If you do choose to enable telemetry, the data helps the |CL| team proactively identify and resolve bugs. See the -:ref:`telemetry ` page for more information. +:ref:`telem-guide` guide for more information. | @@ -75,8 +74,8 @@ Software packages How is software installed and updated? ====================================== -|CL| provides software in the form of :ref:`bundles ` and -updates software with :ref:`swupd `. +|CL| provides software in the form of :ref:`bundles-guide` and +updates software with :ref:`swupd `. :ref:`FlatPak\* ` is an application virtualization solution that allows more software to be available to |CL| users by augmenting the software |CL| @@ -90,7 +89,7 @@ bundles whenever possible. Does |CL| use RPMs like other distros? ====================================== -|CL| provides software in the form of :ref:`bundles `. The RPM +|CL| provides software in the form of :ref:`bundles-guide`. The RPM format is used as an intermediary step for packaging and determining software dependencies at OS build time. @@ -118,7 +117,7 @@ What software is available on |CL|? =================================== Available software can be found in the `Software Store`_, through the GNOME\* -Software application on the desktop, or by using :ref:`swupd search `. +Software application on the desktop, or by using :ref:`swupd search `. | diff --git a/source/concepts/autospec-about.rst b/source/concepts/autospec-about.rst deleted file mode 100644 index ed3e03d9..00000000 --- a/source/concepts/autospec-about.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. _autospec-about: - -Autospec -######## - -``autospec`` is a tool to assist in the automated creation and maintenance of -RPM packaging in |CL-ATTR|. Where a standard RPM build process using ``rpmbuild`` -requires a tarball and .spec file to start, ``autospec`` requires only a tarball -and package name to start. - -How autospec works -****************** - -``autospec`` attempts to infer the requirements of the .spec file by analyzing -the source code and :file:`Makefile` information. It will continuously run -updated builds based on new information discovered from build failures until it -has a complete and valid .spec file. Although not required, you can influence -the behavior of ``autospec`` by providing :ref:`control files `. - -The basic process is described in the following steps: - -#. The :command:`make autospec` command generates a .spec based on - analysis of code and control files, if present. - -#. ``autospec`` creates a ``build root`` with ``mock`` config. - -#. ``autospec`` attempts to build an RPM from the generated .spec. - -#. ``autospec`` detects any missed declarations in the .spec. - -#. If build errors occur, ``autospec`` will scan the build log to try and detect - the root cause. - -#. If ``autospec`` detects the root cause and knows how to continue, it will restart the build - automatically at step 1 with updated build instructions. - -#. Otherwise, ``autospec`` will stop the build for user inspection and editing of control files - to resolve the errors. The user resumes the process at step 1 after errors are resolved. - -Following these steps, ``autospec`` continues to rebuild the package, based on -new information discovered from build failures, until it has a valid .spec. If -no build errors occur, RPM packages are successfully built. - -.. _control-files: - -Control files -************* - -It is possible to influence the behavior of ``autospec`` by providing control -files. These files may be used to alter the default behavior of the configure -routine, to blacklist build dependencies, etc. Control files must be located -in the same directory as the resulting .spec. - -Table 1 shows control files used to control dependencies, for example. - -.. list-table:: **Table 1. Control files to control dependencies** - :widths: 20 80 - :header-rows: 1 - - * - Filename - - Description - * - buildreq_add - - Each line in the file provides the name of a package to add as a - build dependency to the .spec. - * - buildreq_ban - - Each line in the file is a build dependency that under no - circumstance should be automatically added to the build dependencies. - This is useful to block automatic configuration routines adding - undesired functionality, or to omit any automatically discovered - dependencies during tarball scanning. - * - pkgconfig_add - - Each line in the file is assumed to be a pkgconfig() build - dependency. Add the pkg-config names here, as ``autospec`` will - automatically transform the names into their ``pkgconfig($name)`` - style when generating the .spec. - * - pkgconfig_ban - - Each line in this file is a pkgconfig() build dependency that should - not be added automatically to the build, much the same as - `` buildreq_ban``. As with ``pkgconfig_add``, these names are - automatically transformed by ``autospec`` into their correct - ``pkgconfig($name))`` style. - * - requires_add - - Each line in the file provides the name of a package to add as a - runtime dependency to the .spec. - * - requires_ban - - Each line in the file is a runtime dependency that under no - circumstance should be automatically added to the runtime - dependencies. This is useful to block automatic configuration - routines adding undesired functionality, or to omit any automatically - discovered dependencies during tarball scanning. - -Further control of the build can be achieved through the use of the -``options.conf`` file. If this file does not exist, it is created by -``autospec`` with default values. If certain deprecated configuration -files exists ``autospec`` will use the value indicated by those files and -remove them. - -For a comprehensive list of control files, view the `autospec readme`_. - -Related topics -************** - -* :ref:`autospec` -* :ref:`mixer` - -.. _autospec readme: https://github.com/clearlinux/autospec diff --git a/source/concepts/figures/mixer-about-1.png b/source/concepts/figures/mixer-about-1.png deleted file mode 100644 index 8120a068..00000000 Binary files a/source/concepts/figures/mixer-about-1.png and /dev/null differ diff --git a/source/concepts/figures/mixer-about-2.png b/source/concepts/figures/mixer-about-2.png deleted file mode 100644 index 83f03375..00000000 Binary files a/source/concepts/figures/mixer-about-2.png and /dev/null differ diff --git a/source/concepts/figures/telemetry-about-1.png b/source/concepts/figures/telemetry-about-1.png deleted file mode 100644 index 57ede5cd..00000000 Binary files a/source/concepts/figures/telemetry-about-1.png and /dev/null differ diff --git a/source/concepts/mixer-about.rst b/source/concepts/mixer-about.rst deleted file mode 100644 index 0548ed50..00000000 --- a/source/concepts/mixer-about.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _mixer-about: - -Mixer -##### - -|CL-ATTR| is a powerful, modular, and customizable OS. Upstream |CL| offers -many images to support different environments and use-cases. There are -hundreds of bundles that will meet most, if not all, of your OS and software -needs. - -However, if you need additional customization or content, |CL| provides the -mixer tool. Depending on your needs, the mixer tool allows you to: - -* :ref:`create-mix` to create a distinct derivative of the |CL| that - contains your custom software. - -.. _create-mix: - -Create a mix -============ - -When creating a mix, you can - -* Use any existing upstream bundles with no modification. -* Redefine what goes into existing bundles. -* Create completely new, custom bundles with your own custom packages. - -With mixer you are not required to incorporate every upstream release into -your mix. You decide which upstream versions to update your derivative to, as -illustrated in Figure 1. - -.. figure:: figures/mixer-about-1.png - :scale: 75% - :alt: Creating a custom mix. - - Figure 1: With a custom mix, you add your custom bundle and decide which - upstream versions to update your mix to, on your own release cycle. - -Creating your own mix forks away from the |CL| upstream and requires that you -act as your own OSV. There is a greater level of responsibility, requiring -more infrastructure and processes to adopt. However, with this approach, you -have a higher degree of control and customization of your custom |CL|. - -Related topics -============== - -|CL| provides flexibility in how you customize your OS. Learn more about -mixer and related topics to decide which customization approach is best for -you. - -* :ref:`mixer` -* :ref:`bundles-about` -* :ref:`swupd-about` -* :ref:`deploy-at-scale` diff --git a/source/concepts/swupd-about.rst b/source/concepts/swupd-about.rst deleted file mode 100644 index 8d6e5bb4..00000000 --- a/source/concepts/swupd-about.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. _swupd-about: - -swupd: software updater -####################### - -:command:`swupd` is an operating system software manager and update program -that operates at a file-level to enable verifiable integrity and update -efficiency. - -Visit the `swupd man page`_ for more details. - -Versioning -========== - -Using package managers to keep track of software version compatibility or compare multiple systems on many Linux distributions can be cumbersome. - -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. - -While administrators can pick and choose which `bundles`_ a system has -installed, a single |CL| version number strictly represents one combination -of all software versions that can be installed onto a system of that |CL| -version. This method of whole OS versioning offers unique advantages. -Namely, system administrators can quickly compare multiple |CL| systems that share the same version for important software and security fixes. - - -Updating -======== - -|CL| promotes regular and automated updating of software to ensure -integration of new enhancements and security fixes. Refer to :ref:`security` -documentation for more information. - -Learn how to update your system using :ref:`swupd `. - -Update efficiency ------------------ - -Because :command:`swupd` operates at the individual file-level instead of a -package-level, |CL| updates are small and fast. - -On many Linux\* distributions, updates to a particular software package -require the whole software package to be downloaded and replaced ---even for one line of code. - -In |CL|, updates are generated using the :ref:`mixer ` tool. Mixer calculates the difference between two |CL| versions and makes available -*binary deltas*, which contain only the changed portion of files. This -*binary delta technology* [1]_ means :command:`swupd` on |CL| systems only -needs to download and apply a small fraction of a package in order to -receive an update. - -The :ref:`mixer ` tool additionally computes updates files in -multiple compression formats, allowing :command:`swupd` to utilize the most -efficiently compressed format for a |CL| system to minimize the cost -to update. - -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. - -Bundles -======= - -|CL-ATTR| approaches software management differently than many other -Linux-based operating systems. - -Instead of deploying granular software packages, |CL| uses the concept of -bundles with pre-associated software. Each bundle encapsulates a particular -use-case, which is enabled by composing all the required upstream open-source -projects and packages into one logical unit. - -This bundle-based approach offers some unique advantages: - -* Bundles provide a particular functionality, or stack, which - include all associated runtime dependencies. - -* Software package dependencies are resolved on the server, so file-level - conflicts do not occur on the target system after an update. - -* All combinations of bundles are able to co-exist on a |CL| system. - -For more information on bundles, visit: - -* :ref:`bundles` -* :ref:`bundles-about` -* :ref:`bundle-commands` -* :ref:`compatible-kernels` - -.. [1] The software update technology for |CL-ATTR| was first presented at the Linux Plumbers conference in 2012. - -.. _swupd man page: https://github.com/clearlinux/swupd-client/blob/master/docs/swupd.1.rst - diff --git a/source/concepts/telemetry-about.rst b/source/concepts/telemetry-about.rst deleted file mode 100644 index ecab4ec9..00000000 --- a/source/concepts/telemetry-about.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _telemetry-about: - -Telemetrics -########### - -One of the key features of |CL-ATTR| is telemetry, which is used to -monitor system health. Telemetry enables developers to observe and proactively -address issues before end users are impacted. - -*Telemetrics* is a combination word made from: - -* *Telemetry* which is sensing and reporting data. -* *Analytics* which is using visualization and statistical inferencing to make - sense of the reported data. - -|CL| telemetry reports system-level debug/crash information using specialized probes. The -probes monitor system tasks such as :abbr:`swupd (software updater)`, kernel -oops, machine error checks, and BIOS error report table for unhandled hardware -failures. Telemetry enables real-time issue reporting to allow system -developers to quickly focus on an issue and monitor corrective actions. - -|CL| telemetry is fully customizable and can be used during software development -for debugging purposes. You can use **libtelemetry** in your code to create custom -telemetry records. You can also use **telem-record-gen** in script files or call -it from another program. - -.. note:: - - The |CL| telemetry client is disabled by default until you decide to enable it. Telemetry is an **opt-in** solution and can be easily enabled or disabled. - -Architecture -************ - -|CL| telemetry has two fundamental components, which are shown in figure 1: - -* Client: generates and delivers records to the backend server via the network. -* Backend: captures records sent from the client and displays the cumulative - content through a specialized interface. - - .. note:: - - If you want to capture your own records for analysis, you must set up - your own backend server. - -.. figure:: /_figures/telemetrics/telemetry-e2e.png - :scale: 75% - :alt: Clear Linux Telemetry Architecture. - - Figure 1: Clear Linux Telemetry Architecture. - -The telemetry client provides the front end of a complete telemetrics solution -and includes the following components: - -* **telemprobd**, a daemon that prepares the telemetry records and spools them on disk prior to delivery -* **telempostd**, a daemon that sends the records to the telemetry backend server or leaves them on disk until deleting after the record expires. - -* **probes**, that collect specific types of data from the operating system. -* **libtelemetry**, that telemetrics probes use to create telemetrics records and - send them to the telemprobd daemon for further processing. - - -The telemetry backend provides the server-side component of a complete telemetrics solution and -consists of: - -* Nginx web server. -* Two Flask apps: - - * Collector, an ingestion web app for records received from telemetrics-client probes. - * TelemetryUI, a web app that exposes several views to visualize the telemetry data - and also provides a REST API to perform queries. - -* PostgreSQL as the underlying database server. - -The default telemetry backend server reports back to the |CL| development team -and is not viewable outside the Intel firewall. If you want to collect your -own records, then you must set up your own telemetry backend server. - -Next steps -********** - -To put this concept into practice, refer to :ref:`telem-guide`. - diff --git a/source/get-started/bare-metal-install-desktop.rst b/source/get-started/bare-metal-install-desktop.rst index cc3d1744..c5e75896 100644 --- a/source/get-started/bare-metal-install-desktop.rst +++ b/source/get-started/bare-metal-install-desktop.rst @@ -354,7 +354,7 @@ Telemetry Choose whether to participate in `telemetry`. :ref:`telem-guide` is a |CL| feature that reports failures and crashes to the |CL| development -team for improvements. For more information, see :ref:`telemetry-about`. +team for improvements. #. From :guilabel:`Required Options`, select :guilabel:`Telemetry`. diff --git a/source/get-started/bare-metal-install-server.rst b/source/get-started/bare-metal-install-server.rst index c0076482..1638c3db 100644 --- a/source/get-started/bare-metal-install-server.rst +++ b/source/get-started/bare-metal-install-server.rst @@ -393,10 +393,9 @@ Telemetry ========= :ref:`telem-guide` is a |CL| feature that reports failures and crashes to -the |CL| development team for improvements. For more detailed information, -visit our :ref:`telemetry-about` page. +the |CL| development team for improvements. -Select your desired option on whether to participate in `telemetry`. +Select your desired option on whether to participate in telemetry. #. In the Main Menu, navigate to :guilabel:`Telemetry` and select :kbd:`Enter`. diff --git a/source/guides/clear/autospec.rst b/source/guides/clear/autospec.rst index 84f70bed..7dabfd58 100644 --- a/source/guides/clear/autospec.rst +++ b/source/guides/clear/autospec.rst @@ -3,10 +3,11 @@ autospec ######## -**autospec** is a tool used to assist with the automated creation and maintenance of -RPM packaging in |CL-ATTR|. Where a standard :abbr:`RPM (RPM Package Manager)` build process using -:command:`rpmbuild` requires a tarball and :file:`.spec` file to start, autospec -requires only a tarball and package name to start. +**autospec** is a tool used to assist with the automated creation and +maintenance of RPM packaging in |CL-ATTR|. Where a standard +:abbr:`RPM (RPM Package Manager)` build process using :command:`rpmbuild` +requires a tarball and :file:`.spec` file to start, autospec requires only a +tarball and package name to start. .. contents:: :local: @@ -435,7 +436,7 @@ To test an autospec created package directly on the |CL| development system: #. After testing has been completed, the software and any related files must 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 + :ref:`swupd `) however any other files must be cleaned up manually. diff --git a/source/concepts/bundles-about.rst b/source/guides/clear/bundles.rst similarity index 81% rename from source/concepts/bundles-about.rst rename to source/guides/clear/bundles.rst index 0db3efb2..52cc194d 100644 --- a/source/concepts/bundles-about.rst +++ b/source/guides/clear/bundles.rst @@ -1,30 +1,27 @@ -.. _bundles-about: - -Bundles -####### - -Linux-based operating systems contain the code of several hundred, if -not thousands, of open source projects. To make this manageable, -distributions use a concept called "packages" to configure and compile -the source code of these projects into binaries. - -Many distributions then split the content of these compiled packages -into so-called sub-packages, which are the granularity at which these -distributions deploy their software. With those kinds of distributions, -system administrators can then install and update sub-packages -individually or as a set, using tools such as "yum" and "apt-get." - -The |CL-ATTR| takes a slightly different approach. While we also use the -concept of packages to manage compiling source code into binaries, we do not -use the package concept to deploy software. Instead, we provide software -"bundles" that are installed and managed using :ref:`swupd`. -Each bundle contains as many or as few open source projects needed to provide a complete functionality. - -Next steps -========== - -To put this concept into practice, see the following resources: - -* :ref:`bundles` -* :ref:`bundle-commands` -* :ref:`compatible-kernels` +.. _bundles-guide: + +Bundles +####### + +Linux-based operating systems contain the code of several hundred, if +not thousands, of open source projects. To make this manageable, +distributions use a concept called "packages" to configure and compile +the source code of these projects into binaries. + +Many distributions then split the content of these compiled packages +into so-called sub-packages, which are the granularity at which these +distributions deploy their software. With those kinds of distributions, +system administrators can then install and update sub-packages +individually or as a set, using tools such as "yum" and "apt-get." + +The |CL-ATTR| takes a slightly different approach. While we also use the +concept of packages to manage compiling source code into binaries, we do not +use the package concept to deploy software. Instead, we provide software +"bundles" that are installed and managed using :ref:`swupd`. +Each bundle contains as many or as few open source projects needed to provide a +complete functionality. + +Related topics +************** + +* :ref:`swupd-guide` \ No newline at end of file diff --git a/source/guides/clear/mixer.rst b/source/guides/clear/mixer.rst index 789178c4..a846f1a0 100644 --- a/source/guides/clear/mixer.rst +++ b/source/guides/clear/mixer.rst @@ -846,10 +846,9 @@ Set up a nginx web server for mixer with the following steps: Related topics ************** -* :ref:`About mixer ` -* :ref:`autospec-about` -* :ref:`bundles-about` -* :ref:`swupd-about` +* :ref:`autospec` +* :ref:`bundles-guide` +* :ref:`swupd-guide` .. _Docker Hub: https://hub.docker.com/r/clearlinux/mixer/tags/ .. _mixer man page: https://github.com/clearlinux/mixer-tools/blob/master/docs/mixer.1.rst diff --git a/source/guides/clear/stateless.rst b/source/guides/clear/stateless.rst index 7d7aa9f2..c80b9d9a 100644 --- a/source/guides/clear/stateless.rst +++ b/source/guides/clear/stateless.rst @@ -38,7 +38,7 @@ System areas ============ File under the :file:`/usr` directory are managed by |CL| as system files. Files written under the :file:`/usr` directory by users can get removed -through system updates with :ref:`swupd `. This operating +through system updates with :ref:`swupd `. This operating assumption allows |CL| to verify and maintain integrity of system files. User areas diff --git a/source/guides/clear/swupd.rst b/source/guides/clear/swupd.rst index b7ae2a41..0c26f209 100644 --- a/source/guides/clear/swupd.rst +++ b/source/guides/clear/swupd.rst @@ -303,6 +303,8 @@ ignores files or directories matching :file:`/usr/lib/python`: sudo swupd repair --picky --picky-whitelist=/usr/lib/python +.. _swupd-quick-ref: + Quick reference *************** diff --git a/source/guides/kernel/kernel-development.rst b/source/guides/kernel/kernel-development.rst index 841eae4d..4ca22124 100644 --- a/source/guides/kernel/kernel-development.rst +++ b/source/guides/kernel/kernel-development.rst @@ -92,7 +92,7 @@ Change the kernel version |CL| tends to use the latest kernel available from `kernel.org`_, the Linux upstream. The kernel version that will be built can be changed in the RPM SPEC file. While most packages in Clear Linux are typically packaged -using :ref:`autospec-about`, the kernel is not. This means control files +using :ref:`autospec`, the kernel is not. This means control files provided by autospec are not available and changes must be made manually. #. Open the Linux kernel package RPM SPEC file in an editor. diff --git a/source/reference/bundle-commands.rst b/source/reference/bundle-commands.rst deleted file mode 100644 index 4b5593d2..00000000 --- a/source/reference/bundle-commands.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _bundle-commands: - -Useful bundle commands -###################### - -To see a list of currently installed bundles, enter: - -.. code-block:: bash - - sudo swupd bundle-list - -To see the list of all available bundles, enter: - -.. code-block:: bash - - sudo swupd bundle-list --all - -Alternatively, you can view our :ref:`available bundles ` -webpage. - -To search for bundles and their contents, enter: - -.. code-block:: bash - - sudo swupd search [bundle name] - -To add a bundle, enter: - -.. code-block:: bash - - sudo swupd bundle-add [bundle name] - -Additional information -====================== - -For additional :command:`swupd` commands, enter: - -.. code-block:: bash - - swupd --help - -To reference the :command:`swupd` man page, enter: - -.. code-block:: bash - - man swupd - diff --git a/source/reference/bundles/bundles.rst b/source/reference/bundles/bundles.rst index a6423e9c..7572e4a6 100644 --- a/source/reference/bundles/bundles.rst +++ b/source/reference/bundles/bundles.rst @@ -7,7 +7,7 @@ This document provides a current list of available bundles. View the `clr-bundle :file:`Name` for more details. To learn more about how |CL-ATTR| uses bundles for software deployment, visit -:ref:`bundles-about`. +:ref:`bundles-guide`. Bundle list =========== diff --git a/source/reference/index.rst b/source/reference/index.rst index 74258c8b..27e2088b 100644 --- a/source/reference/index.rst +++ b/source/reference/index.rst @@ -10,21 +10,7 @@ features. :maxdepth: 1 compatible-hardware - bundle-commands bundles/bundles collaboration/collaboration system-requirements image-types - -.. _concepts: - -Clear Linux concepts -******************** - -.. toctree:: - :maxdepth: 1 - :glob: - - ../concepts/* - ../guides/clear/stateless - ../guides/clear/security \ No newline at end of file diff --git a/source/tutorials/docker.rst b/source/tutorials/docker.rst index 95eb49dc..d1868234 100644 --- a/source/tutorials/docker.rst +++ b/source/tutorials/docker.rst @@ -45,7 +45,7 @@ Additionally, you should have: Install the containers-basic bundle *********************************** -Software in |CL| is offered in the form of `bundles`_ to provide a +Software in |CL| is offered in the form of :ref:`bundles` to provide a complete function. The *containers-basic* provides all the required software packages to run Docker images as containers. @@ -221,8 +221,6 @@ Related topics .. _Docker proxy instructions: https://docs.docker.com/config/daemon/systemd/#httphttps-proxy -.. _bundles: https://clearlinux.org/documentation/clear-linux/concepts/bundles-about#related-concepts - .. _Docker documentation on daemon configuration: https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file .. _Kata Containers: https://katacontainers.io/ diff --git a/source/tutorials/kubernetes.rst b/source/tutorials/kubernetes.rst index 8fc7b841..bf74b43b 100644 --- a/source/tutorials/kubernetes.rst +++ b/source/tutorials/kubernetes.rst @@ -33,7 +33,7 @@ This tutorial assumes you have already installed |CL|. For detailed instructions on installing |CL| on a bare metal system, follow the :ref:`bare metal installation tutorial`. Learn about the benefits of having an up-to-date system for cloud -orchestration on the :ref:`swupd-about` page. +orchestration on the :ref:`swupd-guide` page. Before you install any new packages, update |CL| with the following command: @@ -271,7 +271,7 @@ following commands: sudo cp /usr/share/defaults/crio/crio.conf /etc/crio/ sudo $EDITOR /etc/crio/crio.conf -Learn more about :ref:`stateless` in |CL| and view the |CL| `documentation`_. +Learn more about :ref:`stateless` in |CL|. Proxy configuration (optional) ****************************** @@ -396,8 +396,6 @@ Troubleshooting .. _Kata Containers: https://katacontainers.io/ -.. _Software Update documentation: https://clearlinux.org/documentation/clear-linux/concepts/swupd-about#updating - .. _cloud-native-basic: https://github.com/clearlinux/clr-bundles/blob/master/bundles/cloud-native-basic .. _preflight check: https://kubernetes.io/docs/reference/setup-tools/kubeadm/implementation-details/#preflight-checks @@ -410,6 +408,4 @@ Troubleshooting .. _Joining your nodes: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#join-nodes -.. _documentation: https://clearlinux.org/documentation/clear-linux - .. _cloud-native-setup: https://github.com/clearlinux/cloud-native-setup/tree/master/clr-k8s-examples diff --git a/source/tutorials/nvidia-cuda.rst b/source/tutorials/nvidia-cuda.rst index aa056c1a..ef16d304 100644 --- a/source/tutorials/nvidia-cuda.rst +++ b/source/tutorials/nvidia-cuda.rst @@ -15,7 +15,7 @@ These instructions show how to install the CUDA Toolkit on |CL| after the .. note:: - Software installed outside of :ref:`swupd ` is not updated with |CL| + Software installed outside of :ref:`swupd ` is not updated with |CL| updates and must be updated and maintained manually. diff --git a/source/tutorials/nvidia.rst b/source/tutorials/nvidia.rst index b1be1d8d..3ca52694 100644 --- a/source/tutorials/nvidia.rst +++ b/source/tutorials/nvidia.rst @@ -4,20 +4,20 @@ NVIDIA\* Drivers ################ NVIDIA manufactures graphics processing units (GPU), also known as -graphics cards. +graphics cards. NVIDIA devices on Linux\* have two popular device driver options: the opensource drivers from the `nouveau project`_ or the proprietary drivers published by NVIDIA. The nouveau drivers are built into the |CL-ATTR| kernel and are loaded automatically at system boot if a compatible card -is detected. +is detected. These instructions show how to use the proprietary NVIDIA drivers, which require a manual installation. .. warning:: - - Software installed outside of :ref:`swupd ` is not updated + + Software installed outside of :ref:`swupd ` is not updated with |CL| updates and must be updated and maintained manually. For example, the file :file:`/usr/lib/libGL.so` conflicts with the file @@ -25,26 +25,21 @@ require a manual installation. update overwrites these files, a reinstallation of the NVIDIA driver might be required. - - .. contents:: :local: - :depth: 2 + :depth: 1 - - -Prerequisites +Prerequisites ************* * A |CL| system with a desktop installed * An NVIDIA device installed - Install DKMS ************ The :ref:`Dynamic Kernel Module System (DKMS) ` allows the NVIDIA kernel modules to be automatically -integrated when kernel updates occur in |CL|. +integrated when kernel updates occur in |CL|. Install the appropriate DKMS bundle using the instructions below: @@ -52,16 +47,13 @@ Install the appropriate DKMS bundle using the instructions below: The Long Term Support (LTS) kernel variant is more likely to remain compatible between updates with NVIDIA drivers. - .. include:: /guides/kernel/kernel-modules-dkms.rst :start-after: kernel-modules-dkms-install-begin: :end-before: kernel-modules-dkms-install-end: - Download and install the NVIDIA drivers *************************************** - Download the NVIDIA drivers for Linux ===================================== @@ -71,11 +63,9 @@ Download the NVIDIA drivers for Linux sudo lshw -C display - #. Go to the `NVIDIA Driver Downloads website`_ . Search for and download the appropriate driver based on the NVIDIA GPU model you have with *Linux - 64-bit* selected as the Operating System . - + 64-bit* selected as the Operating System . #. Open a terminal and navigate to where the :file:`NVIDIA-Linux-x86_64-.run` file was saved. In this @@ -91,7 +81,6 @@ Download the NVIDIA drivers for Linux chmod +x :file:`NVIDIA-Linux-x86_64-.run` - Disable the nouveau driver ========================== @@ -106,14 +95,10 @@ must be disabled before installation can continue. sudo mkdir /etc/modprobe.d printf "blacklist nouveau \noptions nouveau modeset=0 \n" | sudo tee --append /etc/modprobe.d/disable-nouveau.conf - #. Reboot the system and log back in. It is normal for the graphical environment not to start without the NVIDIA driver loaded. - - - Configure alternative software paths ==================================== @@ -123,19 +108,18 @@ rest of the |CL| system files under :file:`/usr`. The dynamic linker and X server must be configured to use the content under :file:`/opt/nvidia`. - #. Configure the dynamic linker to look for and to cache shared libraries under :file:`/opt/nvidia/lib` and :file:`/opt/nvidia/lib32` in addition to the default paths. .. code-block:: bash - + echo "include /etc/ld.so.conf.d/*.conf" | sudo tee --append /etc/ld.so.conf - + sudo mkdir /etc/ld.so.conf.d printf "/opt/nvidia/lib \n/opt/nvidia/lib32 \n" | sudo tee --append /etc/ld.so.conf.d/nvidia.conf -#. Reload the dynamic linker run-time bindings and library cache. +#. Reload the dynamic linker run-time bindings and library cache. .. code-block:: bash @@ -147,7 +131,7 @@ server must be configured to use the content under .. code-block:: bash sudo mkdir -p /etc/X11/xorg.conf.d/ - + sudo tee /etc/X11/xorg.conf.d/nvidia-files-opt.conf > /dev/null <<'EOF' Section "Files" ModulePath "/usr/lib64/xorg/modules" @@ -155,27 +139,23 @@ server must be configured to use the content under EndSection EOF - Install the NVIDIA drivers ========================== - #. A terminal not running on */dev/tty1* is useful to view uninterrupted installation progress. Switch to a secondary virtual terminal by pushing - :command:`CTRL + ALT + F2` or remotely login over SSH. - + :command:`CTRL + ALT + F2` or remotely login over SSH. #. Navigate to the directory where the NVIDIA installer was downloaded. .. code-block:: bash - cd ~/Downloads/ - + cd ~/Downloads/ #. Run the installer with the advanced options below. .. code-block:: bash - + sudo ./NVIDIA-Linux-x86_64-.run \ --utility-prefix=/opt/nvidia \ --opengl-prefix=/opt/nvidia \ @@ -199,13 +179,11 @@ Install the NVIDIA drivers #. The graphical interface may automatically start after the NVIDIA driver is loaded. Return to the working terminal and log back in if necessary. - #. Confirm that the NVIDIA kernel modules are loaded. .. code-block:: bash - lsmod | grep ^nvidia - + lsmod | grep ^nvidia #. Run a |CL| system verification to restore files that the NVIDIA installer likely deleted. @@ -223,16 +201,15 @@ Install the NVIDIA drivers other uses of the :command:`swupd repair` command should be avoided with the proprietary NVIDIA drivers installed. - Updating the NVIDIA drivers *************************** -The proprietary NVIDIA drivers are installed manually outside of :ref:`swupd -` and must be updated manually when needed. +The proprietary NVIDIA drivers are installed manually outside of +:ref:`swupd ` and must be updated manually when needed. 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 the `Download the NVIDIA Drivers for Linux`_ section to get the latest NVIDIA drivers. @@ -244,7 +221,6 @@ not in use. sudo systemctl set-default multi-user.target - #. Reboot the system and log back in. It is normal for the graphical environment not to start. @@ -258,8 +234,7 @@ not in use. sudo systemctl set-default graphical.target - -#. Reboot the system and log back in. +#. Reboot the system and log back in. #. Trigger a flatpak update that will download the runtime corresponding with the new NVIDIA drivers for the flatpak apps that require it. @@ -268,12 +243,11 @@ not in use. flatpak update - Uninstalling the NVIDIA drivers ******************************* The NVIDIA drivers and associated software can be uninstalled and nouveau -driver restored with the instructions in this section. +driver restored with the instructions in this section. #. Remove the :file:`modprobe.d` file that prevents nouveau from loading. @@ -281,7 +255,6 @@ driver restored with the instructions in this section. sudo rm /etc/modprobe.d/disable-nouveau.conf - #. Remove the :file:`xorg.conf.d` file that adds a search path for X modules. .. code:: bash @@ -290,23 +263,20 @@ driver restored with the instructions in this section. #. Run the :command:`sudo /opt/nvidia/bin/nvidia-uninstall` -#. Follow the prompts on the screen and reboot the system. +#. Follow the prompts on the screen and reboot the system. - -Debugging installation of NVIDIA drivers +Debugging installation of NVIDIA drivers **************************************** * The NVIDIA driver places installer and uninstaller logs under :file:`/var/log/nvidia-install` and :file:`/var/log/nvidia-uninstall`. * :file:`NVIDIA-Linux-x86_64-.run --advanced-options` shows many - parameters to control installation behavior. + parameters to control installation behavior. * :file:`NVIDIA-Linux-x86_64-.run --extract-only` extracts installation files into a directory named - :file:`NVIDIA-Linux-x86_64-`. - - + :file:`NVIDIA-Linux-x86_64-`. Additional resources ******************** @@ -320,5 +290,3 @@ Additional resources .. _`nouveau project`: https://nouveau.freedesktop.org/wiki/ .. _`NVIDIA Driver Downloads website`: https://www.nvidia.com/download/index.aspx - -