mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-04-29 03:23:42 +00:00
336 lines
20 KiB
HTML
336 lines
20 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
|
||
<title>Add kernel modules manually — Documentation for Clear Linux* project</title>
|
||
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
|
||
<link rel="stylesheet" type="text/css" href="../../_static/bizstyle.css?v=5283bb3d" />
|
||
<link rel="stylesheet" type="text/css" href="../../_static/copybutton.css?v=76b2166b" />
|
||
|
||
<script src="../../_static/documentation_options.js?v=5929fcd5"></script>
|
||
<script src="../../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
<script src="../../_static/clipboard.min.js?v=a7894cd8"></script>
|
||
<script src="../../_static/copybutton.js?v=a56c686a"></script>
|
||
<script src="../../_static/bizstyle.js"></script>
|
||
<link rel="canonical" href="https://clearlinux.github.io/clear-linux-documentation/guides/kernel/kernel-modules.html" />
|
||
<link rel="icon" href="../../_static/favicon.ico"/>
|
||
<link rel="author" title="About these documents" href="../../about.html" />
|
||
<link rel="index" title="Index" href="../../genindex.html" />
|
||
<link rel="search" title="Search" href="../../search.html" />
|
||
<link rel="next" title="Add kernel modules with DKMS" href="kernel-modules-dkms.html" />
|
||
<link rel="prev" title="Kernel development" href="kernel-development.html" />
|
||
<meta name="viewport" content="width=device-width,initial-scale=1.0" />
|
||
<!--[if lt IE 9]>
|
||
<script src="_static/css3-mediaqueries.js"></script>
|
||
<![endif]-->
|
||
</head><body>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="kernel-modules-dkms.html" title="Add kernel modules with DKMS"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="kernel-development.html" title="Kernel development"
|
||
accesskey="P">previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../../index.html">Documentation for Clear Linux* project</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="../index.html" accesskey="U">Guides</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Add kernel modules manually</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="add-kernel-modules-manually">
|
||
<span id="kernel-modules"></span><h1>Add kernel modules manually<a class="headerlink" href="#add-kernel-modules-manually" title="Link to this heading">¶</a></h1>
|
||
<p>This guide describes how to add kernel modules manually.</p>
|
||
<nav class="contents local" id="contents">
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#overview" id="id1">Overview</a></p></li>
|
||
<li><p><a class="reference internal" href="#description" id="id2">Description</a></p></li>
|
||
<li><p><a class="reference internal" href="#kernel-module-availability" id="id3">Kernel module availability</a></p></li>
|
||
<li><p><a class="reference internal" href="#build-install-and-load-an-out-of-tree-module" id="id4">Build, install, and load an out-of-tree module</a></p></li>
|
||
<li><p><a class="reference internal" href="#examples" id="id5">Examples</a></p></li>
|
||
<li><p><a class="reference internal" href="#related-topic" id="id6">Related topic</a></p></li>
|
||
</ul>
|
||
</nav>
|
||
<section id="overview">
|
||
<h2><a class="toc-backref" href="#contents" role="doc-backlink">Overview</a><a class="headerlink" href="#overview" title="Link to this heading">¶</a></h2>
|
||
<p>Certain kernel modules are enabled by default in Clear Linux* OS. 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 <a class="reference internal" href="kernel-modules-dkms.html#kernel-modules-dkms"><span class="std std-ref">Add kernel modules with DKMS</span></a>.</p>
|
||
</section>
|
||
<section id="description">
|
||
<h2><a class="toc-backref" href="#contents" role="doc-backlink">Description</a><a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>
|
||
<p>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).</p>
|
||
</section>
|
||
<section id="kernel-module-availability">
|
||
<span id="kernel-modules-availability-begin"></span><h2><a class="toc-backref" href="#contents" role="doc-backlink">Kernel module availability</a><a class="headerlink" href="#kernel-module-availability" title="Link to this heading">¶</a></h2>
|
||
<p>Clear Linux OS comes with many upstream kernel modules available for use. Using an
|
||
existing module is significantly easier to maintain and retains signature
|
||
verification of the Clear Linux OS kernel. For more information on Clear Linux OS security
|
||
practices, see the <a class="reference internal" href="../clear/security.html#security"><span class="std std-ref">OS Security</span></a> page.</p>
|
||
<p>Before continuing, check if the kernel module you’re looking for is already
|
||
available in Clear Linux OS or submit a request to add the module.</p>
|
||
<section id="check-if-the-module-is-already-available">
|
||
<h3>Check if the module is already available<a class="headerlink" href="#check-if-the-module-is-already-available" title="Link to this heading">¶</a></h3>
|
||
<p>You can search for kernel module file names, which end with the <code class="file docutils literal notranslate"><span class="pre">.ko</span></code>
|
||
file extension, using the <strong class="command">swupd search</strong> command, as shown in the
|
||
following example. See <a class="reference internal" href="../clear/swupd.html#swupd-guide"><span class="std std-ref">swupd</span></a> for more information.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>swupd<span class="w"> </span>search<span class="w"> </span><span class="si">${</span><span class="nv">module_name</span><span class="si">}</span>.ko
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="submit-a-request-to-add-the-module">
|
||
<h3>Submit a request to add the module<a class="headerlink" href="#submit-a-request-to-add-the-module" title="Link to this heading">¶</a></h3>
|
||
<p>If the kernel module you need is already open source (for example, in the
|
||
Linux kernel upstream) and likely to be useful to others, consider submitting
|
||
a request to add or enable it in the Clear Linux OS kernel.</p>
|
||
<p>Make enhancement requests to the Clear Linux OS <a class="reference external" href="https://github.com/clearlinux/distribution">Distribution Project on GitHub</a>.</p>
|
||
</section>
|
||
</section>
|
||
<section id="build-install-and-load-an-out-of-tree-module">
|
||
<span id="kernel-modules-availability-end"></span><h2><a class="toc-backref" href="#contents" role="doc-backlink">Build, install, and load an out-of-tree module</a><a class="headerlink" href="#build-install-and-load-an-out-of-tree-module" title="Link to this heading">¶</a></h2>
|
||
<p>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 Clear Linux OS. For
|
||
a more scalable and customizable approach, we recommend using the
|
||
<a class="reference internal" href="../clear/mixer.html#mixer"><span class="std std-ref">mixer</span></a> to provide a custom kernel and updates.</p>
|
||
<section id="prerequisites">
|
||
<h3>Prerequisites<a class="headerlink" href="#prerequisites" title="Link to this heading">¶</a></h3>
|
||
<p>Before you begin, you must:</p>
|
||
<ul class="simple">
|
||
<li><p>Disable Secure Boot.</p></li>
|
||
<li><p>Disable kernel module integrity checking.</p></li>
|
||
<li><p>Have a kernel module package in the form of source code.</p></li>
|
||
<li><p>Rebuild the module against new versions of the Linux kernel.</p></li>
|
||
</ul>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Any time the kernel is upgraded on your Clear Linux system, you must
|
||
rebuild your out-of-tree modules.</p>
|
||
</div>
|
||
</section>
|
||
<section id="build-and-install-kernel-module">
|
||
<h3>Build and install kernel module<a class="headerlink" href="#build-and-install-kernel-module" title="Link to this heading">¶</a></h3>
|
||
<ol class="arabic">
|
||
<li><p>Determine which kernel variant is running on Clear Linux OS. In the example below,
|
||
the <em>native</em> kernel is in use.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>uname<span class="w"> </span>-r
|
||
<span class="m">5</span>.XX.YY-ZZZZ.native
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Install the kernel dev bundle corresponding to the installed kernel. The
|
||
kernel dev bundle contains the kernel headers, which are placed under
|
||
<code class="file docutils literal notranslate"><span class="pre">/usr/lib/modules/$(uname</span> <span class="pre">-r)/build/include/</span></code> and are required to
|
||
compile kernel modules. For example:</p>
|
||
<ul class="simple">
|
||
<li><p><strong class="command">linux-dev</strong> for developing against the native kernel.</p></li>
|
||
<li><p><strong class="command">linux-lts-dev</strong> for developing against the LTS kernel.</p></li>
|
||
</ul>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>swupd<span class="w"> </span>bundle-add<span class="w"> </span>linux-dev
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Follow instructions from the kernel module source code to compile the
|
||
kernel module. For example:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>curl<span class="w"> </span>-O<span class="w"> </span>http://<URL-TO-KERNEL-MODULE-SOURCE>.tar.gz
|
||
tar<span class="w"> </span>-xvf<span class="w"> </span><KERNEL-MODULE-SOURCE>.tar.gz
|
||
<span class="nb">cd</span><span class="w"> </span><KERNEL-MODULE-SOURCE>/
|
||
cat<span class="w"> </span>README
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
<section id="load-kernel-module">
|
||
<h3>Load kernel module<a class="headerlink" href="#load-kernel-module" title="Link to this heading">¶</a></h3>
|
||
<ol class="arabic">
|
||
<li><p>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 that
|
||
Secure Boot relies on for trust.</p></li>
|
||
<li><p>Disable signature checking for the kernel by modifying the kernel boot
|
||
parameters and reboot the system.</p>
|
||
<p>All kernel modules from Clear Linux OS have been signed to enforce kernel security.
|
||
However, out-of-tree modules break this chain of trust so this mechanism
|
||
needs to be disabled.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>mkdir<span class="w"> </span>-p<span class="w"> </span>/etc/kernel/cmdline.d
|
||
<span class="nb">echo</span><span class="w"> </span><span class="s2">"module.sig_unenforce"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>sudo<span class="w"> </span>tee<span class="w"> </span>/etc/kernel/cmdline.d/allow-unsigned-modules.conf
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Update the boot manager and reboot the system to implement the changed
|
||
kernel parameters.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>clr-boot-manager<span class="w"> </span>update
|
||
sudo<span class="w"> </span>reboot
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>If successful, the <strong class="command">clr-boot-manager update</strong> command does not
|
||
return any console output.</p>
|
||
</div>
|
||
</li>
|
||
<li><p>After rebooting, manually load out-of-tree modules using the
|
||
<strong class="command">insmod</strong> command.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>insmod<span class="w"> </span></PATH/TO/MODULE.ko>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ol>
|
||
</section>
|
||
</section>
|
||
<section id="examples">
|
||
<h2><a class="toc-backref" href="#contents" role="doc-backlink">Examples</a><a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>
|
||
<section id="optional-specify-module-options-and-aliases">
|
||
<span id="kernel-modules-autoload-begin"></span><h3>Optional: Specify module options and aliases<a class="headerlink" href="#optional-specify-module-options-and-aliases" title="Link to this heading">¶</a></h3>
|
||
<p>Use the <strong class="command">modprobe</strong> command to load a module and set options.</p>
|
||
<p><strong class="command">modprobe</strong> 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 <code class="file docutils literal notranslate"><span class="pre">/etc/modprobe.d</span></code>
|
||
directory.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>mkdir<span class="w"> </span>/etc/modprobe.d
|
||
</pre></div>
|
||
</div>
|
||
<p>All files underneath the <code class="file docutils literal notranslate"><span class="pre">/etc/modprobe.d</span></code> directory that end with the
|
||
<code class="file docutils literal notranslate"><span class="pre">.conf</span></code> extension specify module options to use when loading. You can
|
||
use <code class="file docutils literal notranslate"><span class="pre">.conf</span></code> files to create convenient aliases for modules or to
|
||
override the normal loading behavior altogether for those with special
|
||
requirements.</p>
|
||
<p>Learn more about <strong class="command">modprobe</strong> on the modprobe.d manual page:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>man<span class="w"> </span>modprobe.d
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="optional-configure-kernel-modules-to-load-at-boot">
|
||
<h3>Optional: Configure kernel modules to load at boot<a class="headerlink" href="#optional-configure-kernel-modules-to-load-at-boot" title="Link to this heading">¶</a></h3>
|
||
<p>Use the <code class="file docutils literal notranslate"><span class="pre">/etc/modules-load.d</span></code> configuration directory to specify kernel
|
||
modules to load automatically at boot.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>mkdir<span class="w"> </span>/etc/modules-load.d
|
||
</pre></div>
|
||
</div>
|
||
<p>All files underneath the <code class="file docutils literal notranslate"><span class="pre">/etc/modules-load.d</span></code> directory that end with
|
||
the <code class="file docutils literal notranslate"><span class="pre">.conf</span></code> extension contain a list of module names of aliases (one per
|
||
line) to load at boot.</p>
|
||
<p>Learn more about module loading in the modules-load.d manual page:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>man<span class="w"> </span>modules-load.d
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="related-topic">
|
||
<span id="kernel-modules-autoload-end"></span><h2><a class="toc-backref" href="#contents" role="doc-backlink">Related topic</a><a class="headerlink" href="#related-topic" title="Link to this heading">¶</a></h2>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="kernel-modules-dkms.html#kernel-modules-dkms"><span class="std std-ref">Add kernel modules with DKMS</span></a></p></li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<p class="logo"><a href="../../index.html">
|
||
<img class="logo" src="../../_static/clearlinux.png" alt="Logo of Clear Linux* Project Docs"/>
|
||
</a></p>
|
||
<div>
|
||
<h3><a href="../../index.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Add kernel modules manually</a><ul>
|
||
<li><a class="reference internal" href="#overview">Overview</a></li>
|
||
<li><a class="reference internal" href="#description">Description</a></li>
|
||
<li><a class="reference internal" href="#kernel-module-availability">Kernel module availability</a><ul>
|
||
<li><a class="reference internal" href="#check-if-the-module-is-already-available">Check if the module is already available</a></li>
|
||
<li><a class="reference internal" href="#submit-a-request-to-add-the-module">Submit a request to add the module</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#build-install-and-load-an-out-of-tree-module">Build, install, and load an out-of-tree module</a><ul>
|
||
<li><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
|
||
<li><a class="reference internal" href="#build-and-install-kernel-module">Build and install kernel module</a></li>
|
||
<li><a class="reference internal" href="#load-kernel-module">Load kernel module</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#examples">Examples</a><ul>
|
||
<li><a class="reference internal" href="#optional-specify-module-options-and-aliases">Optional: Specify module options and aliases</a></li>
|
||
<li><a class="reference internal" href="#optional-configure-kernel-modules-to-load-at-boot">Optional: Configure kernel modules to load at boot</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#related-topic">Related topic</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="kernel-development.html"
|
||
title="previous chapter">Kernel development</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="kernel-modules-dkms.html"
|
||
title="next chapter">Add kernel modules with DKMS</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../../_sources/guides/kernel/kernel-modules.rst.txt"
|
||
rel="nofollow">Show Source</a></li>
|
||
</ul>
|
||
</div>
|
||
<search id="searchbox" style="display: none" role="search">
|
||
<h3 id="searchlabel">Quick search</h3>
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="../../search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</search>
|
||
<script>document.getElementById('searchbox').style.display = "block"</script>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="kernel-modules-dkms.html" title="Add kernel modules with DKMS"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="kernel-development.html" title="Kernel development"
|
||
>previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../../index.html">Documentation for Clear Linux* project</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="../index.html" >Guides</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Add kernel modules manually</a></li>
|
||
</ul>
|
||
</div>
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2022 Intel Corporation. All Rights Reserved..
|
||
Last updated on Nov 04, 2024.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3.
|
||
</div>
|
||
</body>
|
||
</html> |