How to Load and Unload Kernel Modules with `kldload` and `kldunload` on FreeBSD

Introduction

FreeBSD is a powerful and versatile Unix-like operating system known for its stability and advanced networking capabilities. Like other Unix-based systems, FreeBSD allows for modular kernel configuration, meaning you can dynamically load and unload kernel modules as needed without rebooting the system. This is particularly useful for adding support for new hardware, enabling additional kernel functionalities, or troubleshooting system components.

This article will explore how to use kldload and kldunload to manage kernel modules on FreeBSD, including checking loaded modules, handling dependencies, and troubleshooting common issues.

Understanding Kernel Modules in FreeBSD

Kernel modules in FreeBSD are dynamically loadable extensions to the kernel, allowing for functionality to be added or removed without recompiling or rebooting. These modules typically reside in /boot/kernel/ or /boot/modules/ and have a .ko (kernel object) extension.

Some common kernel modules include:

• if_bridge.ko – Provides Ethernet bridging support.
• ipfw.ko – Enables the IP firewall.
• linux.ko – Adds Linux binary compatibility.
• snd_driver.ko – Loads sound card drivers.

Managing these modules efficiently ensures better system performance, security, and flexibility.

Checking Loaded Kernel Modules

Before loading or unloading kernel modules, it’s useful to check what is currently loaded. The kldstat command lists all loaded modules along with their memory usage and load order.

kldstat

Example output:

Id Refs Address            Size     Name
 1   48  0xffffffff80200000 1d8f4e0  kernel
 2    1  0xffffffff81f97000 18a8    accf_http.ko
 3    1  0xffffffff81f9a000 2030    ipfw.ko

This output provides:

• Id – Module ID.
• Refs – Number of references (dependencies using the module).
• Address – Memory address where the module is loaded.
• Size – Memory size of the module.
• Name – Module name.

If a module is missing, it may need to be manually loaded using kldload.

Loading Kernel Modules with kldload

The kldload command dynamically loads a kernel module into the running system. The basic syntax is:

kldload module_name

For example, to load the ipfw firewall module:

kldload ipfw

If the module file (.ko) is located in a non-standard directory, you can specify the full path:

kldload /boot/modules/custom_module.ko

Checking if the Module Loaded Successfully

After loading the module, verify its presence using kldstat:

kldstat | grep ipfw

If the module does not appear in the list, check for errors:

dmesg | tail -20

Loading Modules at Boot

To ensure a module loads automatically at boot, add it to /etc/rc.conf or /boot/loader.conf:

• For rc.conf (preferred for most modules):

  echo 'firewall_enable="YES"' >> /etc/rc.conf
  

• For loader.conf (for modules needed at early boot):

  echo 'ipfw_load="YES"' >> /boot/loader.conf
  

Modules in loader.conf are loaded by the FreeBSD bootloader before the kernel is fully initialized.

Unloading Kernel Modules with kldunload

The kldunload command removes a kernel module from the system. The syntax is:

kldunload module_name

For example, to unload the ipfw module:

kldunload ipfw

Checking if the Module Unloaded Successfully

Verify that the module is no longer listed using kldstat:

kldstat | grep ipfw

If the module is still present, it may be in use by another process. Check dependencies using:

kldstat -v | grep module_name

If the module has active references, close any processes or services using it before unloading.

Preventing a Module from Loading at Boot

If a module is configured to load at boot but you want to disable it:

• Remove it from rc.conf (if applicable):

  sed -i '' '/firewall_enable/d' /etc/rc.conf
  

• Remove it from loader.conf:

  sed -i '' '/ipfw_load/d' /boot/loader.conf
  

Handling Dependencies

Some modules depend on others to function correctly. Unloading a module that others depend on will fail unless dependencies are removed first.

To check module dependencies:

kldstat -v

To unload multiple modules, use a sequential approach:

kldunload dependent_module
kldunload main_module

For example, if snd_driver.ko depends on sound.ko, unload in the correct order:

kldunload snd_driver
kldunload sound

Troubleshooting Module Loading Issues

1. Module Not Found

If kldload returns an error like:

kldload: can't load module: No such file or directory

Check that the module exists:

ls /boot/kernel | grep module_name

If missing, reinstall the kernel or fetch the module from FreeBSD’s package repositories.

2. Module Already Loaded

If a module is already loaded, kldload may return:

kldload: can't load module: File exists

Check with kldstat to confirm the module is loaded.

3. Module in Use and Cannot be Unloaded

If kldunload fails with:

kldunload: can't unload module: Device busy

Check dependencies:

kldstat -v

Stop any related services or applications before retrying.

Conclusion

Managing kernel modules with kldload and kldunload on FreeBSD is straightforward but requires careful handling of dependencies and configuration files. By understanding how to dynamically load and unload modules, you can optimize system performance, troubleshoot issues, and customize FreeBSD to suit your needs.

For persistent configurations, ensure modules are correctly set up in /etc/rc.conf or /boot/loader.conf. When troubleshooting, use kldstat, dmesg, and service management tools to identify and resolve issues efficiently.

Mastering these tools will make you more proficient in FreeBSD system administration and improve overall system management.