diff options
Diffstat (limited to 'documentation/content/en/books/handbook/kernelconfig/_index.adoc')
| -rw-r--r-- | documentation/content/en/books/handbook/kernelconfig/_index.adoc | 42 |
1 files changed, 27 insertions, 15 deletions
diff --git a/documentation/content/en/books/handbook/kernelconfig/_index.adoc b/documentation/content/en/books/handbook/kernelconfig/_index.adoc index aa6e412569..5e035105b6 100644 --- a/documentation/content/en/books/handbook/kernelconfig/_index.adoc +++ b/documentation/content/en/books/handbook/kernelconfig/_index.adoc @@ -1,13 +1,14 @@ --- -title: Chapter 8. Configuring the FreeBSD Kernel +title: Chapter 10. Configuring the FreeBSD Kernel part: Part II. Common Tasks prev: books/handbook/multimedia next: books/handbook/printing description: This chapter covers how to configure the FreeBSD Kernel. When to build a custom kernel, how to take a hardware inventory, how to customize a kernel configuration file, etc tags: ["configuring", "kernel", "custom kernel", "hardware requirements", "pciconf"] showBookMenu: true -weight: 11 -path: "/books/handbook/" +weight: 13 +params: + path: "/books/handbook/kernelconfig/" --- [[kernelconfig]] @@ -18,7 +19,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 8 +:sectnumoffset: 10 :partnums: :source-highlighter: rouge :experimental: @@ -53,7 +54,7 @@ endif::[] The kernel is the core of the FreeBSD operating system. It is responsible for managing memory, enforcing security controls, networking, disk access, and much more. -While much of FreeBSD is dynamically configurable, it is still occasionally necessary to configure and compile a custom kernel. +While much of FreeBSD is dynamically configurable, some users may wish to configure and compile a custom kernel. After reading this chapter, you will know: @@ -89,12 +90,19 @@ This has a number of benefits, such as: * Lower memory usage. A custom kernel often uses less memory than the [.filename]#GENERIC# kernel by omitting unused features and device drivers. This is important because the kernel code remains resident in physical memory at all times, preventing that memory from being used by applications. For this reason, a custom kernel is useful on a system with a small amount of RAM. * Additional hardware support. A custom kernel can add support for devices which are not present in the [.filename]#GENERIC# kernel. +[WARNING] +==== +When building a custom kernel, it is important to note that non-default configurations are less thoroughly tested than the GENERIC configuration. +While customizing the kernel can provide specific benefits it also increases the risk of encountering build or runtime issues. +Custom kernel configurations are recommended only for advanced users who have a specific reason for making changes and are willing to engage in the debugging process if necessary. +==== + Before building a custom kernel, consider the reason for doing so. If there is a need for specific hardware support, it may already exist as a module. Kernel modules exist in [.filename]#/boot/kernel# and may be dynamically loaded into the running kernel using man:kldload[8]. Most kernel drivers have a loadable module and manual page. -For example, the man:ath[4] wireless Ethernet driver has the following information in its manual page: +For example, the man:ath[4] wireless network driver has the following information in its manual page: [source,shell,subs="macros"] .... @@ -170,7 +178,7 @@ Once the hardware inventory list is created, refer to it to ensure that drivers In order to create a custom kernel configuration file and build a custom kernel, the full FreeBSD source tree must first be installed. If [.filename]#/usr/src/# does not exist or it is empty, source has not been installed. -Source can be installed using Git and the instructions in crossref:mirrors[git,“Using Git”]. +Source can be installed with Git using the instructions in crossref:mirrors[git,“Using Git”]. Once source is installed, review the contents of [.filename]#/usr/src/sys#. This directory contains a number of subdirectories, including those which represent the following supported architectures: [.filename]#amd64#, [.filename]#i386#, [.filename]#powerpc#, and [.filename]#sparc64#. @@ -194,9 +202,9 @@ The default editor is vi, though an easier editor for beginners, called ee, is a The format of the kernel configuration file is simple. Each line contains a keyword that represents a device or subsystem, an argument, and a brief description. -Any text after a `#` is considered a comment and ignored. -To remove kernel support for a device or subsystem, put a `#` at the beginning of the line representing that device or subsystem. -Do not add or remove a `#` for any line that you do not understand. +Any text after a `+#+` is considered a comment and ignored. +To remove kernel support for a device or subsystem, put a `+#+` at the beginning of the line representing that device or subsystem. +Do not add or remove a `+#+` for any line that you do not understand. [WARNING] ==== @@ -260,29 +268,33 @@ To build a file which contains all available options, run the following command Once the edits to the custom configuration file have been saved, the source code for the kernel can be compiled using the following steps: [.procedure] +==== *Procedure: Building a Kernel* + . Change to this directory: + [source,shell] .... # cd /usr/src .... - ++ . Compile the new kernel by specifying the name of the custom kernel configuration file: + [source,shell] .... # make buildkernel KERNCONF=MYKERNEL .... - ++ . Install the new kernel associated with the specified kernel configuration file. This command will copy the new kernel to [.filename]#/boot/kernel/kernel# and save the old kernel to [.filename]#/boot/kernel.old/kernel#: + [source,shell] .... # make installkernel KERNCONF=MYKERNEL .... - -. Shutdown the system and reboot into the new kernel. If something goes wrong, refer to <<kernelconfig-noboot, The kernel does not boot>>. ++ +. Shutdown the system and reboot into the new kernel. If something goes wrong, + refer to crossref:kernelconfig[kernelconfig-noboot, The kernel does not boot]. +==== By default, when a custom kernel is compiled, all kernel modules are rebuilt. To update a kernel faster or to build only custom modules, edit [.filename]#/etc/make.conf# before starting to build the kernel. @@ -335,7 +347,7 @@ Also, man:dmesg[8] will print the kernel messages from the current boot. + [NOTE] ==== -When troubleshooting a kernel, make sure to keep a copy of [.filename]#GENERIC#, or some other kernel that is known to work, as a different name that will not get erased on the next build. +When troubleshooting a kernel make sure to keep a copy of a kernel that is known to work, such as [.filename]#GENERIC#. This is important because every time a new kernel is installed, [.filename]#kernel.old# is overwritten with the last installed kernel, which may or may not be bootable. As soon as possible, move the working kernel by renaming the directory containing the good kernel: |