From owner-svn-doc-head@FreeBSD.ORG Wed Mar 19 17:14:09 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 279872AD; Wed, 19 Mar 2014 17:14:09 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 12369212; Wed, 19 Mar 2014 17:14:09 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s2JHE9Kr042633; Wed, 19 Mar 2014 17:14:09 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s2JHE8xn042632; Wed, 19 Mar 2014 17:14:08 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201403191714.s2JHE8xn042632@svn.freebsd.org> From: Dru Lavigne Date: Wed, 19 Mar 2014 17:14:08 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44289 - head/en_US.ISO8859-1/books/handbook/kernelconfig X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 19 Mar 2014 17:14:09 -0000 Author: dru Date: Wed Mar 19 17:14:08 2014 New Revision: 44289 URL: http://svnweb.freebsd.org/changeset/doc/44289 Log: White space fix only. Translators can ignore. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Wed Mar 19 16:52:25 2014 (r44288) +++ head/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml Wed Mar 19 17:14:08 2014 (r44289) @@ -69,17 +69,17 @@ All of the commands listed in the examples in this chapter - should be executed as root. + should be executed as root. Why Build a Custom Kernel? - Traditionally, &os; used a monolithic kernel. - The kernel was one large program, supported a fixed list of - devices, and in order to change the kernel's behavior, one had - to compile and then reboot into a new - kernel. + Traditionally, &os; used a monolithic kernel. The kernel + was one large program, supported a fixed list of devices, and in + order to change the kernel's behavior, one had to compile and + then reboot into a new kernel. Today, most of the functionality in the &os; kernel is contained in modules which can be dynamically loaded and @@ -132,12 +132,11 @@ doing so. If there is a need for specific hardware support, it may already exist as a module. - Kernel modules exist in /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: + Kernel modules exist in /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: Alternatively, to load the driver as a module at boot time, place the following line in &man.loader.conf.5;: @@ -145,11 +144,12 @@ following line in &man.loader.conf.5;: if_ath_load="YES" Adding if_ath_load="YES" to - /boot/loader.conf will load this - module dynamically at boot time. + /boot/loader.conf will load this module + dynamically at boot time. - In some cases, there is no associated module in /boot/kernel. This is - mostly true for certain subsystems. + In some cases, there is no associated module in + /boot/kernel. This is mostly true for + certain subsystems. @@ -166,11 +166,10 @@ following line in &man.loader.conf.5;: --> Finding the System Hardware - Before editing the kernel configuration file, it is recommended - to perform an inventory of the machine's hardware. On a dual-boot - system, the inventory - can be created from the other operating system. - For example, µsoft;'s + Before editing the kernel configuration file, it is + recommended to perform an inventory of the machine's hardware. + On a dual-boot system, the inventory can be created from the + other operating system. For example, µsoft;'s Device Manager contains information about installed devices. @@ -180,12 +179,11 @@ following line in &man.loader.conf.5;: access Device Manager. - If &os; is the only installed operating system, - use &man.dmesg.8; to determine the hardware that was found and - listed during the boot probe. Most device - drivers on &os; have a manual page which lists the hardware supported by that driver. - For - example, the following lines indicate that the &man.psm.4; + If &os; is the only installed operating system, use + &man.dmesg.8; to determine the hardware that was found and + listed during the boot probe. Most device drivers on &os; have + a manual page which lists the hardware supported by that driver. + For example, the following lines indicate that the &man.psm.4; driver found a mouse: psm0: <PS/2 Mouse> irq 12 on atkbdc0 @@ -197,12 +195,11 @@ psm0: model Generic PS/2 mouse, device I removed from a custom kernel configuration file. If the output of dmesg does not display - the results of the boot probe output, instead read the contents of - /var/run/dmesg.boot. + the results of the boot probe output, instead read the contents + of /var/run/dmesg.boot. - Another tool for finding hardware is - &man.pciconf.8;, which provides more verbose output. For - example: + Another tool for finding hardware is &man.pciconf.8;, which + provides more verbose output. For example: &prompt.user; pciconf -lv ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 @@ -211,14 +208,12 @@ ath0@pci0:3:0:0: class=0x020000 c class = network subclass = ethernet - This output shows that the - ath driver located a wireless Ethernet - device. - - The flag of &man.man.1; - can be used to provide useful information. For example, to - display a list of manual pages which contain the specified - word: + This output shows that the ath driver + located a wireless Ethernet device. + + The flag of &man.man.1; can be used to + provide useful information. For example, to display a list of + manual pages which contain the specified word: &prompt.root; man -k Atheros @@ -252,36 +247,39 @@ ath_hal(4) - Atheros Hardw empty, source has not been installed. Source can be installed using Subversion and the instructions in . - + Once source is installed, review the contents of /usr/src/sys. This directory contains a - number of subdirectories, including those which represent the following - supported architectures: amd64, i386, ia64, pc98, powerpc, and sparc64. Everything inside a - particular architecture's directory deals with that architecture - only and the rest of the code is machine independent code common - to all platforms. Each supported architecture has a conf subdirectory - which contains the GENERIC kernel - configuration file for that architecture. - + number of subdirectories, including those which represent the + following supported architectures: amd64, + i386, ia64, + pc98, powerpc, and + sparc64. Everything inside a particular + architecture's directory deals with that architecture only and + the rest of the code is machine independent code common to all + platforms. Each supported architecture has a + conf subdirectory which contains the + GENERIC kernel configuration file for that + architecture. + Do not make edits to GENERIC. Instead, copy the file to a different name and make edits to the copy. The convention is to use a name with all capital letters. When maintaining multiple &os; machines with different hardware, it is a good idea to name it after the machine's hostname. This - example creates a copy, named MYKERNEL, of the - GENERIC configuration file for the + example creates a copy, named MYKERNEL, of + the GENERIC configuration file for the amd64 architecture: &prompt.root; cd /usr/src/sys/amd64/conf &prompt.root; cp GENERIC MYKERNEL - The configuration file - MYKERNEL can now be customized - with any ASCII text editor. The default editor is - vi, though an easier editor - for beginners, called ee, is also + The configuration file MYKERNEL can now + be customized with any ASCII text editor. The default editor is + vi, though an easier editor for + beginners, called ee, is also installed with &os;. - + kernel NOTES @@ -299,9 +297,10 @@ ath_hal(4) - Atheros Hardw 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. + # for any line that you do not + understand. - + It is easy to remove support for a device or option and end up with a broken kernel. For example, if the &man.ata.4; driver is removed from the kernel configuration file, a system @@ -309,8 +308,8 @@ ath_hal(4) - Atheros Hardw in doubt, just leave support in the kernel. - In addition to the brief descriptions provided in this file, additional - descriptions are contained in + In addition to the brief descriptions provided in this file, + additional descriptions are contained in NOTES, which can be found in the same directory as GENERIC for that architecture. For architecture independent options, refer to @@ -318,7 +317,8 @@ ath_hal(4) - Atheros Hardw When finished customizing the kernel configuration file, - save a backup copy to a location outside of /usr/src. + save a backup copy to a location outside of + /usr/src. Alternately, keep the kernel configuration file elsewhere and create a symbolic link to the file: @@ -332,10 +332,10 @@ ath_hal(4) - Atheros Hardw An include directive is available for use in configuration files. This allows another configuration file to be included in the current one, making it easy to maintain - small changes relative to an existing file. If - only a small number of additional options or drivers are - required, this allows a delta to be maintained with respect - to GENERIC, as seen in this example: + small changes relative to an existing file. If only a small + number of additional options or drivers are required, this + allows a delta to be maintained with respect to + GENERIC, as seen in this example: include GENERIC ident MYKERNEL @@ -346,17 +346,19 @@ options IPFIREWALL_DEFAULT_TO_AC options IPDIVERT Using this method, the local configuration file expresses - local differences from a GENERIC - kernel. As upgrades are performed, new features added to + local differences from a GENERIC kernel. + As upgrades are performed, new features added to GENERIC will also be added to the local kernel unless they are specifically prevented using - nooptions or nodevice. - A comprehensive list of configuration directives and their + nooptions or nodevice. A + comprehensive list of configuration directives and their descriptions may be found in &man.config.5;. To build a file which contains all available options, - run the following command as root: + run the following command as root: + &prompt.root; cd /usr/src/sys/arch/conf && make LINT @@ -461,9 +463,10 @@ options NFS_ROOT # NFS The &ms-dos; file system. Unless the system needs to mount a DOS formatted hard drive partition at boot time, comment this out. It will be automatically loaded the first time a DOS - partition is mounted. The emulators/mtools package allows - access to DOS floppies without having to mount and unmount - them and does not require MSDOSFS. + partition is mounted. The emulators/mtools + package allows access to DOS floppies without having to mount + and unmount them and does not require + MSDOSFS. options CD9660 # ISO 9660 Filesystem @@ -476,24 +479,26 @@ options NFS_ROOT # NFS options PROCFS # Process filesystem (requires PSEUDOFS) The process file system. This is a pretend - file system mounted on /proc which allows some programs - to provide more information on what processes are running. Use - of PROCFS is not required under most - circumstances, as most debugging and monitoring tools have been - adapted to run without PROCFS. The default - installation will not mount this file system by default. + file system mounted on /proc which allows + some programs to provide more information on what processes are + running. Use of PROCFS is not required under + most circumstances, as most debugging and monitoring tools have + been adapted to run without PROCFS. The + default installation will not mount this file system by + default. options PSEUDOFS # Pseudo-filesystem framework - Kernels making use of PROCFS must - also include support for PSEUDOFS. + Kernels making use of PROCFS must + also include support for PSEUDOFS. options GEOM_PART_GPT # GUID Partition Tables. - Adds support for GUID - Partition Tables (GPT). GPT - provides the ability to have a large number of partitions per - disk, 128 in the standard configuration. + Adds support for GUID + Partition Tables (GPT). GPT + provides the ability to have a large number of partitions per + disk, 128 in the standard configuration. options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!] @@ -995,7 +1000,8 @@ device loop # Network loopbac device tun # Packet tunnel. - This is used by the userland PPP software. See the PPP section of the Handbook for more + This is used by the userland PPP software. See the PPP section of the Handbook for more information. @@ -1076,7 +1082,7 @@ device fwe # Ethernet &os;, see /usr/src/sys/arch/conf/NOTES. --> - + - + Building and Installing a Custom Kernel Once the edits to the custom configuration file have been - saved, the source code for the - kernel can be compiled using the following steps: + saved, the source code for the kernel can be compiled using the + following steps: Building a Kernel - - kernel - building / installing - + + + kernel + building / installing + Change to this directory: @@ -1197,13 +1204,14 @@ device fwe # Ethernet Install the new kernel associated with the specified - kernel configuration file. This command will copy the new kernel to - /boot/kernel/kernel and save the old kernel - to /boot/kernel.old/kernel: + kernel configuration file. This command will copy the new + kernel to /boot/kernel/kernel and save + the old kernel to + /boot/kernel.old/kernel: &prompt.root; make installkernel KERNCONF=MYKERNEL - + Shutdown the system and reboot into the new kernel. If something goes wrong, refer to - 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 /etc/make.conf before starting to - build the kernel. + 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 /etc/make.conf + before starting to build the kernel. - For example, this variable specifies the list of modules to build - instead of using the default of building all modules: + For example, this variable specifies the list of modules to + build instead of using the default of building all + modules: - MODULES_OVERRIDE = linux acpi ntfs + MODULES_OVERRIDE = linux acpi ntfs - Alternately, this variable lists which modules to - exclude from the build process: + Alternately, this variable lists which modules to exclude + from the build process: - WITHOUT_MODULES = linux acpi sound ntfs + WITHOUT_MODULES = linux acpi sound ntfs - Additional variables are available. - Refer to &man.make.conf.5; for details. + Additional variables are available. Refer to + &man.make.conf.5; for details. /boot/kernel.old - - If Something Goes Wrong + + If Something Goes Wrong - There are four categories of trouble that can occur when - building a custom kernel: + There are four categories of trouble that can occur when + building a custom kernel: - - - config fails + + + config fails - - If config fails, it will print the line - number that is incorrect. As an example, for - the following message, make sure that line 17 is typed correctly by - comparing it to - GENERIC or NOTES: + + If config fails, it will print the + line number that is incorrect. As an example, for the + following message, make sure that line 17 is typed + correctly by comparing it to GENERIC + or NOTES: config: line 17: syntax error @@ -1261,16 +1269,17 @@ device fwe # Ethernet If make fails, it is usually due to - an error in the kernel configuration file which is not severe - enough for config to catch. Review the - configuration, and if the problem is not apparent, - send an email to the &a.questions; which contains the - kernel configuration file. + an error in the kernel configuration file which is not + severe enough for config to catch. + Review the configuration, and if the problem is not + apparent, send an email to the &a.questions; which + contains the kernel configuration file. - The kernel does not boot + The kernel does not boot If the new kernel does not boot or fails to recognize @@ -1280,9 +1289,8 @@ device fwe # Ethernet loader. This can be accessed when the system boot menu appears by selecting the Escape to a loader prompt option. At the prompt, type - boot - kernel.old, or - the name of any other kernel that is known to boot properly. + boot kernel.old, or the name of any + other kernel that is known to boot properly. After booting with a good kernel, check over the configuration file and try to build it again. One helpful @@ -1293,19 +1301,17 @@ device fwe # Ethernet When troubleshooting a kernel, make sure to keep - a copy of GENERIC, or some other kernel that - is known to work, as a different name that will - not get erased on the next build. This is important - because every time - a new kernel is installed, 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: + a copy of GENERIC, or some other + kernel that is known to work, as a different name that + will not get erased on the next build. This is + important because every time a new kernel is installed, + 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: &prompt.root; mv /boot/kernel /boot/kernel.bad &prompt.root; mv /boot/kernel.good /boot/kernel - @@ -1316,13 +1322,14 @@ device fwe # Ethernet If the kernel version differs from the one that the system utilities have been built with, for example, a - kernel built from -CURRENT sources is installed on a -RELEASE system, many system status commands - like &man.ps.1; and &man.vmstat.8; will not work. To fix - this, recompile and install a - world built with the same version of the - source tree as the kernel. It is - never a good idea to use a different version of the kernel - than the rest of the operating system. + kernel built from -CURRENT sources is installed on a + -RELEASE system, many system status commands like + &man.ps.1; and &man.vmstat.8; will not work. To fix this, + recompile and install a + world built with the same version of the source + tree as the kernel. It is never a good idea to use a + different version of the kernel than the rest of the + operating system.