diff --git a/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst b/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst index a9718b94..3e3cf6fe 100644 --- a/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst +++ b/source/clear-linux/guides/maintenance/kernel-modules-dkms.rst @@ -3,22 +3,10 @@ Add kernel modules with DKMS ############################ -Kernel modules are additional pieces of software capable of being inserted -into the Linux kernel to add functionality, such as a hardware driver. -Kernel modules may already be part of the Linux source tree (in-tree) or may -come from an external source, such as directly from a vendor (out-of-tree). - -In cases where drivers beyond those enabled by default in |CL-ATTR| are -needed it may be necessary to manually build out-of-tree modules. - -Out-of-tree kernel modules can be can be `manually built and maintained -`_. Out-of-tree kernel modules can also be managed with the -`Dynamic Kernel Module System (DKMS)`_ on |CL| using the instructions in this -document. - -:abbr:`DKMS (Dynamic Kernel Module System)` is a framework that facilitates -the building and installation of kernel modules. This allows |CL| to provide -hooks that automatically rebuild modules against new kernel versions. +Certain kernel modules are enabled by default in |CL-ATTR|. To use additional +kernel modules that are not part of the Linux source tree, you may need to +build out-of-tree kernel modules. Use this guide to add kernel modules with +:abbr:`DKMS (Dynamic Kernel Module System)` or refer to :ref:`kernel-modules`. .. contents:: :local: @@ -26,6 +14,19 @@ hooks that automatically rebuild modules against new kernel versions. :backlinks: top +Description +*********** + +Kernel modules are additional pieces of software capable of being inserted +into the Linux kernel to add functionality, such as a hardware driver. +Kernel modules may already be part of the Linux source tree (in-tree) or may +come from an external source, such as directly from a vendor (out-of-tree). + +:abbr:`DKMS (Dynamic Kernel Module System)` is a framework that facilitates +the building and installation of kernel modules. DKMS allows |CL| to provide +hooks that automatically rebuild modules against new kernel versions. + + .. include:: kernel-modules.rst :start-after: kernel-modules-availability-begin: @@ -34,8 +35,8 @@ hooks that automatically rebuild modules against new kernel versions. -Install DKMS on |CL| -==================== +Install DKMS +************ .. _kernel-modules-dkms-install-begin: @@ -49,22 +50,23 @@ The *kernel-native-dkms* bundle also: run DKMS to rebuild modules after a kernel upgrade occurs with :ref:`swupd update `. -* Disables kernel modules signature verification by appending a kernel - command-line parameter (:command:`module.sig_unenforce`) from - :file:`/usr/share/kernel/cmdline.d/clr-ignore-mod-sig.conf`. +* Disables kernel module signature verification by appending a kernel + command-line parameter (:command:`module.sig_unenforce`) from the + :file:`/usr/share/kernel/cmdline.d/clr-ignore-mod-sig.conf` file. * Adds a notification to the Message of the Day (MOTD) indicating kernel - modules signature verification is disabled. + module signature verification is disabled. .. warning:: - #. It is important to always review the output of :command:`swupd update` to - make sure kernel modules rebuilt against the new kernel successfully. This is - especially important for systems where a successful boot relies on a kernel - module. + We recommend that you always review the :command:`swupd update` output + to make sure kernel modules were successfully rebuilt against the new + kernel. This is especially important for systems where a successful boot + relies on a kernel module. -Install the *kernel-native-dkms* or *kernel-lts-dkms* bundle: +Install the :command:`kernel-native-dkms` or :command:`kernel-lts-dkms` +bundle: #. Determine which kernel variant is running on |CL|. Only the *native* and *lts* kernels are enabled to build and load out-of-tree kernel modules @@ -77,9 +79,9 @@ Install the *kernel-native-dkms* or *kernel-lts-dkms* bundle: Ensure *.native* or *.lts* is in the kernel name. -#. Install the dkms bundle corresponding to the installed kernel. - *kernel-native-dkms* for the native kernel or *kernel-lts-dkms* for the - lts kernel. +#. Install the DKMS bundle corresponding to the installed kernel. Use + :command:`kernel-native-dkms` for the native kernel or + :command:`kernel-lts-dkms` for the lts kernel. .. code-block:: bash @@ -90,66 +92,66 @@ Install the *kernel-native-dkms* or *kernel-lts-dkms* bundle: .. code-block:: bash sudo swupd bundle-add kernel-lts-dkms - + #. Update the |CL| bootloader and reboot. .. code-block:: bash - sudo clr-boot-manager update + sudo clr-boot-manager update reboot .. _kernel-modules-dkms-install-end: Build, install, and load an out-of-tree module -============================================== -In some cases you may need an out-of-tree kernel module that is not available -through |CL|. +********************************************** + +Follow the steps in this section if you are an individual user or testing, and +you need an out-of-tree kernel module that is not available through |CL|. For +a more scalable and customizable approach, we recommend using the +`mixer tool`_ to provide a custom kernel and updates. -Prerequisites -------------- +Prerequisites +============= -You can build and load out-of-tree kernel modules, however you must: +Before you begin, you must: * Disable Secure Boot in UEFI/BIOS. The loading of new out-of-tree modules - modifies the signatures Secure Boot relies on for trust. - -* Have a kernel module package in the form of source code and/or precompiled + modifies the signatures that Secure Boot relies on for trust. + +* Obtain a kernel module package in the form of source code and/or precompiled binaries. -This approach works well for individual use or testing. For a more -scalable and customizable approach, consider using the `mixer tool`_ to -provide a custom kernel and updates. Obtain kernel module source ---------------------------- +=========================== -A :file:`dkms.conf` file inside of the kernel module's source code directory -is required to inform DKMS how the kernel module should be compiled. +A required :file:`dkms.conf` file inside of the kernel module's source code directory +informs DKMS how the kernel module should be compiled. Kernel modules may come packaged as: -- Source code without a dkms.conf -- Source code with a premade dkms.conf -- Source code with a premade dkms.conf and precompiled module binaries -- Precompiled module binaries only without source code +- Source code without a :file:`dkms.conf` file +- Source code with a premade :file:`dkms.conf` file +- Source code with a premade :file:`dkms.conf` file and precompiled module + binaries +- Precompiled module binaries only (without source code) -Precompiled kernel module binaries will not work on |CL| because it requires -kernel modules to be built against the same kernel source tree before they can -be loaded. - -If you are only able to obtain source code without a dkms.conf, a -:file:`dkms.conf` file will need to be manually created. +Of the package types listed above, only precompiled kernel module binaries +will not work, because |CL| requires kernel modules to be built against +the same kernel source tree before they can be loaded. If you are only able to +obtain source code without a :file:`dkms.conf` file, you must manually create a +:file:`dkms.conf` file, described later in this document. #. Download the kernel module's source code. - - - Review the available download options. Some kernel modules provide - separate archives which are specifically enabled for DKMS support. - - - Review the README documentation because it often provides required + + * Review the available download options. Some kernel modules provide + separate archives that are specifically enabled for DKMS support. + + * Review the README documentation, because it often provides required information to build the module with DKMS support. .. code-block:: bash @@ -161,15 +163,15 @@ If you are only able to obtain source code without a dkms.conf, a Build kernel module with an existing dkms.conf ----------------------------------------------- +============================================== If the kernel module maintainer packaged the source archive with the :command:`dkms mktarball` command, the entire archive can be passed to the -:command:`dkms ldtarball` which will complete many steps for you. +:command:`dkms ldtarball` which completes many steps for you. -The archive will contain the required :file:`dkms.conf` file, and may contain +The archive contains the required :file:`dkms.conf` file, and may contain a :file:`dkms_source_tree` directory and a :file:`dkms_binaries_only` -directory. +directory. #. Run the :command:`dkms ldtarball` command against the kernel module archive. @@ -179,20 +181,20 @@ directory. dkms ldtarball .tar.gz - :command:`dkms ldtarball` will place the kernel module source under - :file:`/usr/src/-/`, build if necessary, and - add the module into the dkms tree. + :command:`dkms ldtarball` places the kernel module source under + :file:`/usr/src/-/`, builds it if necessary, and + adds the module into the DKMS tree. -#. Verify the kernel module is detected by checking the output of - :command:`dkms status`. - +#. Verify the kernel module is detected by checking the output of the + :command:`dkms status` command. + .. code-block:: bash dkms status -#. Install the kernel module. +#. Install the kernel module. .. code-block:: bash @@ -201,31 +203,31 @@ directory. Build kernel module without an existing dkms.conf -------------------------------------------------- +================================================= If the kernel module source does not contain a :file:`dkms.conf` file or the -:command:`dkms ldtarball` command encounters errors, it needs to be manually -created. +:command:`dkms ldtarball` command encounters errors, you must manually +create the file. Review the kernel module README documentation for guidance on what needs to be -in the :file:`dkms.conf` including special variables that may be required to +in the :file:`dkms.conf` file, including special variables that may be required to build successfully. Here are some additional resources that can be used for reference: -* The DKMS manual page (:command:`man dkms`) shows detailed syntax in the - DKMS.CONF section +* DKMS manual page (:command:`man dkms`) shows detailed syntax in the + DKMS.CONF section. -* ``_ - (shows an example where a single package contains multiple modules) +* `Ubuntu community wiki`_ shows an example where a single package contains + multiple modules. -* ``_ +* `Sample dkms.conf file`_ in the GitHub\* repository for the DKMS project. The instructions below show a generic example: #. Create or modify the :file:`dkms.conf` file inside of the extracted source - code directory. + code directory. .. code-block:: bash @@ -250,33 +252,34 @@ The instructions below show a generic example: sudo cp -Rv . /usr/src/- .. note:: - ** and ** should match the entries in :file:`dkms.conf` + + ** and ** must match the entries in the + :file:`dkms.conf` file. #. Add the kernel module to the DKMS tree so that it is tracked by DKMS. .. code-block:: bash - sudo dkms add -m + sudo dkms add -m -#. Build the kernel module using DKMS. If the build encounters errors, the - :file:`dkms.conf` may need to be adjusted. +#. Build the kernel module using DKMS. If the build encounters errors, you may + need to edit the :file:`dkms.conf` file. .. code-block:: bash sudo dkms build -m -v - #. Install the kernel module using DKMS. .. code-block:: bash sudo dkms install -m -v - + Load kernel module ------------------- +================== By default, DKMS installs modules "in-tree" under :file:`/lib/modules` so the :command:`modprobe` command can be used to load them. @@ -294,7 +297,8 @@ By default, DKMS installs modules "in-tree" under :file:`/lib/modules` so the lsmod | grep - +Examples +******** .. include:: kernel-modules.rst :start-after: kernel-modules-autoload-begin: @@ -303,17 +307,23 @@ By default, DKMS installs modules "in-tree" under :file:`/lib/modules` so the -Additional resources -==================== -* `Dynamic Kernel Module System (DKMS) project on GitHub `_ +Related topics +************** + +* `Dynamic Kernel Module System (DKMS) project on GitHub `_ * `Dell Linux Engineering Dynamic Kernel Module Support: From Theory to Practice `_ * `Linux Journal: Exploring Dynamic Kernel Module Support `_ -.. _`on GitHub`: https://github.com/clearlinux/distribution +.. _`on GitHub`: https://github.com/clearlinux/distribution .. _`mixer tool`: https://clearlinux.org/features/mixer-tool .. _`Dynamic Kernel Module System (DKMS)`: https://github.com/dell/dkms + +.. _Ubuntu community wiki: https://help.ubuntu.com/community/Kernel/DkmsDriverPackage#Configure_DKMS + +.. _Sample dkms.conf file: https://github.com/dell/dkms/blob/master/sample.conf + diff --git a/source/clear-linux/guides/maintenance/kernel-modules.rst b/source/clear-linux/guides/maintenance/kernel-modules.rst index 94daac09..357bc405 100644 --- a/source/clear-linux/guides/maintenance/kernel-modules.rst +++ b/source/clear-linux/guides/maintenance/kernel-modules.rst @@ -3,75 +3,77 @@ Add kernel modules manually ########################### -Kernel modules are additional pieces of software capable of being inserted -into the Linux kernel to add functionality, such as a hardware driver. Kernel -modules may already be part of the Linux source tree (in-tree) or may come -from an external source, such as directly from a vendor (out-of-tree). - -In cases where drivers beyond those enabled by default in |CL-ATTR| are -needed it may be necessary to manually build out-of-tree modules. - -Out-of-tree kernel modules can be managed by `Dynamic Kernel Module System -(DKMS) `_ on |CL| for automatic rebuilding upon kernel -updates. Out-of-tree kernel modules can also be manually built and maintained -using the instructions in this document. - +Certain kernel modules are enabled by default in |CL-ATTR|. To use additional +kernel modules that are not part of the Linux source tree, you may need to +build out-of-tree kernel modules. Use this guide to add kernel modules +manually, or refer to :ref:`kernel-modules-dkms`. .. contents:: :local: :depth: 1 :backlinks: top +Description +*********** + +Kernel modules are additional pieces of software capable of being inserted +into the Linux kernel to add functionality, such as a hardware driver. +Kernel modules may already be part of the Linux source tree (in-tree) or may +come from an external source, such as directly from a vendor (out-of-tree). + .. _kernel-modules-availability-begin: -Kernel module availability in |CL| -================================== +Kernel module availability +************************** + +|CL| comes with many upstream kernel modules available for use. Using an +existing module is significantly easier to maintain and retains signature +verification of the |CL| kernel. For more information on |CL| security +practices, see the :ref:`security` page. Before continuing, check if the kernel module you're looking for is already -available in |CL| or can be requested. +available in |CL| or submit a request to add the module. Check if the module is already available ----------------------------------------- +======================================== -|CL| comes with many upstream kernel modules available for use. If you -require a kernel module, be sure to check whether it is already available in -|CL| first. - -Using an existing module is significantly easier to maintain and retains -signature verification of the |CL| kernel. For more information on |CL| -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-guide` for -more information. +file extension, using the :command:`swupd search` command, as shown in the +following example. See :ref:`swupd-guide` for more information. + +.. code-block:: bash + + sudo swupd search ${module_name}.ko -Request the module be added to |CL| ------------------------------------ +Submit a request to add the module +================================== -If the kernel module you need is already open source (e.g. in the Linux +If the kernel module you need is already open source (for example, in the Linux upstream) and likely to be useful to others, consider submitting a request to -add or enable in the |CL| kernel. +add or enable it in the |CL| kernel. -Make enhancement requests to the |CL| distribution `on GitHub`_ . +Make enhancement requests to the |CL| distribution `on GitHub`_. .. _kernel-modules-availability-end: Build, install, and load an out-of-tree module -============================================== +********************************************** -In some cases you may need an out-of-tree kernel module that is not available -through |CL|. +Follow the steps in this section if you are an individual user or testing, and +you need an out-of-tree kernel module that is not available through |CL|. For +a more scalable and customizable approach, we recommend using the +`mixer tool`_ to provide a custom kernel and updates. -Prerequisites -------------- +Prerequisites +============= -You can build and load out-of-tree kernel modules, however you must: +Before you begin, you must: * Disable Secure Boot. * Disable kernel module integrity checking. @@ -80,16 +82,12 @@ You can build and load out-of-tree kernel modules, however you must: .. note:: - Any time the kernel is upgraded on your Clear Linux system, you will - need to rebuild your out-of-tree modules. - -This approach works well for individual development or testing. For a more -scalable and customizable approach, consider using the `mixer tool`_ to -provide a custom kernel and updates. + Any time the kernel is upgraded on your Clear Linux system, you must + rebuild your out-of-tree modules. Build and install kernel module -------------------------------- +=============================== #. Determine which kernel variant is running on |CL|. In the example below, the *native* kernel is in use. @@ -101,8 +99,8 @@ Build and install kernel module #. Install the kernel dev bundle corresponding to the installed kernel. The kernel dev bundle contains the kernel headers, which are required for - compiling kernel modules.For example: - + compiling kernel modules. For example: + * `linux-dev` for developing against the native kernel. * `linux-lts-dev` for developing against the LTS kernel. @@ -110,7 +108,7 @@ Build and install kernel module sudo swupd bundle-add linux-dev -#. Follow instructions from the kernel module source code to compile the +#. Follow instructions from the kernel module source code to compile the kernel module. For example: .. code-block:: bash @@ -123,26 +121,25 @@ Build and install kernel module Load kernel module ------------------- +================== #. Disable Secure Boot in your system's UEFI settings, if you have enabled - it. The loading of new out-of-tree modules modifies the signatures Secure - Boot relies on for trust. + it. The loading of new out-of-tree modules modifies the signatures that + Secure Boot relies on for trust. +#. Disable signature checking for the kernel by modifying the kernel boot + parameters and reboot the system. -#. Disable signature checking for the kernel by modifying the kernel boot - parameters and reboot the system. - - All kernel modules from |CL| have been signed to enforce kernel security. - However, out-of-tree modules break this chain of trust so this mechanism + All kernel modules from |CL| have been signed to enforce kernel security. + However, out-of-tree modules break this chain of trust so this mechanism needs to be disabled. - + .. code-block:: bash sudo mkdir -p /etc/kernel/cmdline.d echo "module.sig_unenforce" | sudo tee /etc/kernel/cmdline.d/allow-unsigned-modules.conf -#. Update the boot manager and reboot the system to implement the changed +#. Update the boot manager and reboot the system to implement the changed kernel parameters. .. code-block:: bash @@ -152,41 +149,40 @@ Load kernel module .. note:: - :command:`clr-boot-manager update` does not return any - console output if successful. + If successful, the :command:`clr-boot-manager update` command does not + return any console output. - -#. After rebooting, out-of-tree modules can be manually loaded with - :command:`insmod`. +#. After rebooting, manually load out-of-tree modules using the + :command:`insmod` command. .. code-block:: bash sudo insmod - +Examples +******** .. _kernel-modules-autoload-begin: Optional: Specify module options and aliases ============================================ -Use the :command:`modprobe` command to load a module and set options. +Use the :command:`modprobe` command to load a module and set options. -Because :command:`modprobe` may add or remove more than one module due to -modules having dependencies, a method of specifying what options are to be -used with individual modules is useful. This can be done with configuration -files under the :file:`/etc/modprobe.d` directory. +:command:`modprobe` may add or remove more than one module due to module +interdependencies. You can specify which options to use with individual modules, +by using configuration files under the :file:`/etc/modprobe.d` directory. .. code-block:: bash sudo mkdir /etc/modprobe.d All files underneath the :file:`/etc/modprobe.d` directory that end with the -:file:`.conf` extension specify module options to use when loading. This can -also be used to create convenient aliases for modules or they can override the -normal loading behavior altogether for those with special requirements. +:file:`.conf` extension specify module options to use when loading. You can use +:file:`.conf` files to create convenient aliases for modules or to override the +normal loading behavior altogether for those with special requirements. -You can find more info on module loading in the modprobe.d manual page: +Learn more about :command:`modprobe` on the modprobe.d manual page: .. code-block:: bash @@ -206,7 +202,7 @@ All files underneath the :file:`/etc/modules-load.d` directory that end with the :file:`.conf` extension contain a list of module names of aliases (one per line) to load at boot. -You can find more info on module loading in the modules-load.d manual page: +Learn more about module loading in the modules-load.d manual page: .. code-block:: bash @@ -215,6 +211,11 @@ You can find more info on module loading in the modules-load.d manual page: .. _kernel-modules-autoload-end: +Related topic +************* -.. _`on GitHub`: https://github.com/clearlinux/distribution +* :ref:`kernel-modules-dkms` + + +.. _`on GitHub`: https://github.com/clearlinux/distribution .. _`mixer tool`: https://clearlinux.org/features/mixer-tool