2 The FreeBSD Documentation Project
4 $FreeBSD: doc/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml,v 1.132 2004/05/20 14:40:08 simon Exp $
5 $DragonFly: doc/en/books/handbook/kernelconfig/chapter.sgml,v 1.3 2004/08/24 19:32:44 justin Exp $
8 <chapter id="kernelconfig">
12 <firstname>Jim</firstname>
13 <surname>Mock</surname>
14 <contrib>Updated and restructured by </contrib>
20 <firstname>Jake</firstname>
21 <surname>Hamby</surname>
22 <contrib>Originally contributed by </contrib>
28 <title>Configuring the &os; Kernel</title>
30 <sect1 id="kernelconfig-synopsis">
31 <title>Synopsis</title>
34 <primary>kernel</primary>
35 <secondary>building a custom kernel</secondary>
38 <para>The kernel is the core of the &os; operating system. It is
39 responsible for managing memory, enforcing security controls,
40 networking, disk access, and much more. While more and more of &os;
41 becomes dynamically configurable it is still occasionally necessary to
42 reconfigure and recompile your kernel.</para>
44 <para>After reading this chapter, you will know:</para>
48 <para>Why you might need to build a custom kernel.</para>
52 <para>How to write a kernel configuration file, or alter an existing
53 configuration file.</para>
57 <para>How to use the kernel configuration file to create and build a
62 <para>How to install the new kernel.</para>
66 <para>How to create any entries in <filename>/dev</filename> that may
71 <para>How to troubleshoot if things go wrong.</para>
76 <sect1 id="kernelconfig-custom-kernel">
77 <title>Why Build a Custom Kernel?</title>
79 <para>Traditionally, &os; has had what is called a
80 <quote>monolithic</quote> kernel. This means that the kernel was one
81 large program, supported a fixed list of devices, and if you wanted to
82 change the kernel's behavior then you had to compile a new kernel, and
83 then reboot your computer with the new kernel.</para>
85 <para>Today, &os; is rapidly moving to a model where much of the
86 kernel's functionality is contained in modules which can be
87 dynamically loaded and unloaded from the kernel as necessary.
88 This allows the kernel to adapt to new hardware suddenly
89 becoming available (such as PCMCIA cards in a laptop), or for
90 new functionality to be brought into the kernel that was not
91 necessary when the kernel was originally compiled. This is
92 known as a modular kernel. Colloquially these are called
95 <para>Despite this, it is still necessary to carry out some static kernel
96 configuration. In some cases this is because the functionality is so
97 tied to the kernel that it can not be made dynamically loadable. In
98 others it may simply be because no one has yet taken the time to write a
99 dynamic loadable kernel module for that functionality yet.</para>
101 <para>Building a custom kernel is one of the most important rites of
102 passage nearly every &unix; user must endure. This process, while
103 time consuming, will provide many benefits to your &os; system.
104 Unlike the <filename>GENERIC</filename> kernel, which must support a
105 wide range of hardware, a custom kernel only contains support for
106 <emphasis>your</emphasis> PC's hardware. This has a number of
107 benefits, such as:</para>
111 <para>Faster boot time. Since the kernel will only probe the
112 hardware you have on your system, the time it takes your system to
113 boot will decrease dramatically.</para>
117 <para>Less memory usage. A custom kernel often uses less memory
118 than the <filename>GENERIC</filename> kernel, which is important
119 because the kernel must always be present in real
120 memory. For this reason, a custom kernel is especially useful
121 on a system with a small amount of RAM.</para>
125 <para>Additional hardware support. A custom kernel allows you to
126 add in support for devices such as sound cards, which are not
127 present in the <filename>GENERIC</filename> kernel.</para>
132 <sect1 id="kernelconfig-building">
133 <title>Building and Installing a Custom Kernel</title>
135 <primary>kernel</primary>
136 <secondary>building / installing</secondary>
139 <para>First, let us take a quick tour of the kernel build directory.
140 All directories mentioned will be relative to the main
141 <filename>/usr/src/sys</filename> directory, which is also
142 accessible through <filename>/sys</filename>. There are a number of
143 subdirectories here representing different parts of the kernel, but
144 the most important, for our purposes, are
145 <filename><replaceable>arch</replaceable>/conf</filename>, where you
146 will edit your custom kernel configuration, and
147 <filename>compile</filename>, which is the staging area where your
148 kernel will be built. <replaceable>arch</replaceable> represents
149 either <filename>i386</filename> or <filename>amd64</filename>,
150 at this point in development. Everything inside a particular
151 architecture's directory deals with that architecture only; the rest
152 of the code is common to all platforms to which &os; could
153 potentially be ported. Notice the logical organization of the
154 directory structure, with each supported device, file system, and
155 option in its own subdirectory. </para>
158 <para>If there is <emphasis>not</emphasis> a
159 <filename>/usr/src/sys</filename> directory on your system,
160 then the kernel source has not been installed. The easiest
161 way to do this is via cvsup.
162 <!-- XXX need link to cvsup section here -->
165 <para>Next, move to the
166 <filename><replaceable>arch</replaceable>/conf</filename> directory
167 and copy the <filename>GENERIC</filename> configuration file to the
168 name you want to give your kernel. For example:</para>
170 <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
171 &prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>
173 <para>Traditionally, this name is in all capital letters and, if you
174 are maintaining multiple &os; machines with different hardware,
175 it is a good idea to name it after your machine's hostname. We will
176 call it <filename>MYKERNEL</filename> for the purpose of this
180 <para>Storing your kernel config file directly under
181 <filename>/usr/src</filename> can be a bad idea. If you are
182 experiencing problems it can be tempting to just delete
183 <filename>/usr/src</filename> and start again. Five seconds after
184 you do that you realize that you have deleted your custom kernel
185 config file. Do not edit <filename>GENERIC</filename>
186 directly, as it may get overwritten the next time you
187 <link linkend="updating-setup">update your source tree</link>, and
188 your kernel modifications will be lost.</para>
190 <para>You might want to keep your kernel config file elsewhere, and then
191 create a symbolic link to the file in the <filename>i386</filename>
194 <para>For example:</para>
196 <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
197 &prompt.root; <userinput>mkdir /root/kernels</userinput>
198 &prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput>
199 &prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
203 <para>You must execute these and all of the following commands under
204 the <username>root</username> account or you will get
205 <errortype>permission denied</errortype> errors.</para>
208 <para>Now, edit <filename>MYKERNEL</filename> with your favorite text
209 editor. If you are just starting out, the only editor available
210 will probably be <application>vi</application>, which is too complex to
211 explain here, but is covered well in many books in the <link
212 linkend="bibliography">bibliography</link>. However, &os; does
213 offer an easier editor called <application>ee</application> which, if
214 you are a beginner, should be your editor of choice. Feel free to
215 change the comment lines at the top to reflect your configuration or
216 the changes you have made to differentiate it from
217 <filename>GENERIC</filename>.</para>
218 <indexterm><primary>SunOS</primary></indexterm>
220 <para>If you have built a kernel under &sunos; or some other BSD
221 operating system, much of this file will be very familiar to you.
222 If you are coming from some other operating system such as DOS, on
223 the other hand, the <filename>GENERIC</filename> configuration file
224 might seem overwhelming to you, so follow the descriptions in the
225 <link linkend="kernelconfig-config">Configuration File</link>
226 section slowly and carefully.</para>
229 <para>Be sure to always check the file
230 <filename>/usr/src/UPDATING</filename>, before you perform any update
231 steps, in the case you <link
232 linkend="updating-setup">sync your source tree</link> with the
233 latest sources of the &os; project.
234 In this file all important issues with updating &os;
235 are typed out. <filename>/usr/src/UPDATING</filename> always fits
236 your version of the &os; source, and is therefore more accurate
237 for new information than the handbook.</para>
241 <title>Building a Kernel</title>
244 <para>Change to the <filename>/usr/src</filename> directory.</para>
246 <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
250 <para>Compile the kernel.</para>
252 <screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
256 <para>Install the new kernel.</para>
258 <screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
263 <primary><command>cvsup</command></primary>
265 <indexterm><primary>anonymous CVS</primary></indexterm>
266 <indexterm><primary>CTM</primary></indexterm>
268 <primary>CVS</primary>
269 <secondary>anonymous</secondary>
272 <para>If you have <emphasis>not</emphasis> upgraded your source
273 tree in any way since the last time you successfully completed
274 a <maketarget>buildworld</maketarget>-<maketarget>installworld</maketarget> cycle
275 (you have not run <application>CVSup</application>), then it is safe to use the
276 <command>quickworld</command> and <maketarget>quickkernel</maketarget>,
277 <command>buildworld</command>, <maketarget>buildkernel</maketarget> sequence.
281 <primary><filename>kernel.old</filename></primary>
284 <para>The new kernel will be copied to the root directory as
285 <filename>/kernel</filename> and the old kernel will be moved to
286 <filename>/kernel.old</filename>. Now, shutdown the system and
287 reboot to use your new kernel. In case something goes wrong, there are
288 some <link linkend="kernelconfig-trouble">troubleshooting</link>
289 instructions at the end of this chapter. Be sure to read the
290 section which explains how to recover in case your new kernel <link
291 linkend="kernelconfig-noboot">does not boot</link>.</para>
294 <para>If you have added any new devices (such as sound cards),
295 you may have to add some device nodes to your
296 <filename>/dev</filename> directory before you can use
297 them. For more information, take a look at <link
298 linkend="kernelconfig-nodes">Making Device Nodes</link>
299 section later on in this chapter.</para>
303 <sect1 id="kernelconfig-config">
304 <title>The Configuration File</title>
306 <primary>kernel</primary>
307 <secondary>LINT</secondary>
309 <indexterm><primary>LINT</primary></indexterm>
311 <primary>kernel</primary>
312 <secondary>config file</secondary>
315 <para>The general format of a configuration file is quite simple.
316 Each line contains a keyword and one or more arguments. For
317 simplicity, most lines only contain one argument. Anything
318 following a <literal>#</literal> is considered a comment and
319 ignored. The following sections describe each keyword, generally in
320 the order they are listed in <filename>GENERIC</filename>, although
321 some related keywords have been grouped together in a single section
322 (such as Networking) even though they are actually scattered
323 throughout the <filename>GENERIC</filename> file. <anchor
324 id="kernelconfig-options"> An exhaustive list of options and more
325 detailed explanations of the device lines is present in the
326 <filename>LINT</filename> configuration file, located in the same
327 directory as <filename>GENERIC</filename>. If you are in doubt as
328 to the purpose or necessity of a line, check first in
329 <filename>LINT</filename>.</para>
332 <primary>kernel</primary>
333 <secondary>example config file</secondary>
336 <para>The following is an example <filename>GENERIC</filename> kernel
337 configuration file with various additional comments where needed for
338 clarity. This example should match your copy in
339 <filename>/usr/src/sys/i386/conf/GENERIC</filename> fairly
340 closely. For details of all the possible kernel options, see
341 <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
345 # GENERIC -- Generic kernel configuration file for DragonFly/i386
347 # Check the LINT configuration file in sys/i386/conf, for an
348 # exhaustive list of options.
350 # $DragonFly: src/sys/i386/conf/GENERIC,v 1.17 2004/06/25 05:09:38 hmp Exp $
353 <para>The following are the mandatory keywords required in
354 <emphasis>every</emphasis> kernel you build:</para>
356 <primary>kernel options</primary>
357 <secondary>machine</secondary>
360 <programlisting>machine i386</programlisting>
362 <para>This is the machine architecture. It must be either
363 <literal>i386</literal>, or <literal>amd64</literal>.</para>
366 <primary>kernel options</primary>
367 <secondary>cpu</secondary>
369 <programlisting>cpu I386_CPU
372 cpu I686_CPU</programlisting>
374 <para>The above option specifies the type of CPU you have in your
375 system. You may have multiple instances of the CPU line (i.e.,
376 you are not sure whether you should use
377 <literal>I586_CPU</literal> or <literal>I686_CPU</literal>),
378 however, for a custom kernel, it is best to specify only the CPU
379 you have. If you are unsure of your CPU type, you can check the
380 <filename>/var/run/dmesg.boot</filename> file to view your boot
384 <primary>kernel options</primary>
385 <secondary>ident</secondary>
388 <programlisting>ident GENERIC</programlisting>
390 <para>This is the identification of the kernel. You should change
391 this to whatever you named your kernel,
392 i.e. <literal>MYKERNEL</literal> if you have followed the
393 instructions of the previous examples. The value you put in the
394 <literal>ident</literal> string will print when you boot up the
395 kernel, so it is useful to give the new kernel a different name if you
396 want to keep it separate from your usual kernel (i.e. you want to
397 build an experimental kernel).</para>
399 <primary>kernel options</primary>
400 <secondary>maxusers</secondary>
403 <programlisting>maxusers <replaceable>n</replaceable></programlisting>
405 <para>The <literal>maxusers</literal> option sets the size of a number
406 of important system tables. This number is supposed to be roughly
407 equal to the number of simultaneous users you expect to have on your
410 <para>(Recommended) The system will auto-tune this setting
411 for you if you explicitly set it to <literal>0</literal><footnote>
412 <para>The auto-tuning algorithm sets <literal>maxuser</literal> equal
413 to the amount of memory in the system, with a minimum of 32, and a
414 maximum of 384.</para></footnote>.
415 If you want to manage it yourself you will want to set
416 <literal>maxusers</literal> to at least 4, especially if you are
417 using the X Window System or compiling software. The reason is that
418 the most important table set by <literal>maxusers</literal> is the
419 maximum number of processes, which is set to <literal>20 + 16 *
420 maxusers</literal>, so if you set <literal>maxusers</literal> to 1,
421 then you can only have 36 simultaneous processes, including the 18
422 or so that the system starts up at boot time, and the 15 or so you
423 will probably create when you start the X Window System. Even a
424 simple task like reading a manual page will start up nine processes to
425 filter, decompress, and view it. Setting
426 <literal>maxusers</literal> to 64 will allow you to have up to 1044
427 simultaneous processes, which should be enough for nearly all uses.
428 If, however, you see the dreaded <errortype>proc table
429 full</errortype> error when trying to start another program, or are
430 running a server with a large number of simultaneous users, you
431 can always increase the number and rebuild.</para>
434 <para><literal>maxusers</literal> does <emphasis>not</emphasis>
435 limit the number of users which can log into your machine. It
436 simply sets various table sizes to reasonable values considering
437 the maximum number of users you will likely have on your system
438 and how many processes each of them will be running. One keyword
439 which <emphasis>does</emphasis> limit the number of simultaneous
440 <emphasis>remote logins and X terminal windows</emphasis> is <link
441 linkend="kernelconfig-ptys"><literal>pseudo-device pty
442 16</literal></link>. </para>
445 <programlisting># Floating point support - do not disable.
446 device npx0 at nexus? port IO_NPX irq 13</programlisting>
448 <para><literal>npx0</literal> is the interface to the floating point
449 math unit in &os;, which is either the hardware co-processor or
450 the software math emulator. This is <emphasis>not</emphasis>
453 <programlisting># Pseudo devices - the number indicates how many units to allocate.
454 pseudo-device loop # Network loopback</programlisting>
456 <para>This is the generic loopback device for TCP/IP. If you telnet
457 or FTP to <hostid>localhost</hostid> (a.k.a., <hostid
458 role="ipaddr">127.0.0.1</hostid>) it will come back at you through
459 this device. This is <emphasis>mandatory</emphasis>. </para>
461 <para>Everything that follows is more or less optional. See the notes
462 underneath or next to each option for more information.</para>
464 <programlisting>#makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols</programlisting>
466 <para>The normal build process of the &os; does not include
467 debugging information when building the kernel and strips most
468 symbols after the resulting kernel is linked, to save some space
469 at the install location. If you are going to do tests of kernels
470 in the -CURRENT branch or develop changes of your own for the &os;
471 kernel, you might want to uncomment this line. It will enable the
472 use of the <option>-g</option> option which enables debugging
473 information when passed to &man.gcc.1;. </para>
475 <programlisting>options MATH_EMULATE #Support for x87 emulation</programlisting>
477 <para>This line allows the kernel to simulate a math co-processor if
478 your computer does not have one (386 or 486SX). If you have a
479 486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or
480 higher (&pentium;, &pentium; II, etc.), you can comment this line
484 <para>The normal math co-processor emulation routines that come with
485 &os; are <emphasis>not</emphasis> very accurate. If you do not
486 have a math co-processor, and you need the best accuracy, it is
487 recommended that you change this option to
488 <literal>GPL_MATH_EMULATE</literal> to use the GNU math support,
489 which is not included by default for licensing reasons.</para>
492 <programlisting>options INET #InterNETworking</programlisting>
494 <para>Networking support. Leave this in, even if you do not plan to
495 be connected to a network. Most programs require at least loopback
496 networking (i.e., making network connections within your PC), so
497 this is essentially mandatory.</para>
499 <programlisting>options INET6 #IPv6 communications protocols</programlisting>
501 <para>This enables the IPv6 communication protocols.</para>
503 <programlisting>options FFS #Berkeley Fast Filesystem
504 options FFS_ROOT #FFS usable as root device [keep this!]</programlisting>
506 <para>This is the basic hard drive Filesystem. Leave it in if you
507 boot from the hard disk.</para>
509 <programlisting>options UFS_DIRHASH #Improve performance on big directories</programlisting>
511 <para>This option includes functionality to speed up disk
512 operations on large directories, at the expense of using
513 additional memory. You would normally keep this for a large
514 server, or interactive workstation, and remove it if you are
515 using &os; on a smaller system where memory is at a premium and
516 disk access speed is less important, such as a firewall.</para>
518 <programlisting>options SOFTUPDATES #Enable FFS Soft Updates support</programlisting>
520 <para>This option enables Soft Updates in the kernel, this will
521 help speed up write access on the disks. Even when this
522 functionality is provided by the kernel, it must be turned on
523 for specific disks. Review the output from &man.mount.8; to see
524 if Soft Updates is enabled for your system disks. If you do not
525 see the <literal>soft-updates</literal> option then you will
526 need to activate it using the &man.tunefs.8; (for existing
527 filesystems) or &man.newfs.8; (for new filesystems)
530 <programlisting>options MFS #Memory Filesystem
531 options MD_ROOT #MD is a potential root device</programlisting>
533 <para>This is the memory-mapped filesystem. This is basically a RAM
534 disk for fast storage of temporary files, useful if you have a lot
535 of swap space that you want to take advantage of. A perfect place
536 to mount an MFS partition is on the <filename>/tmp</filename>
537 directory, since many programs store temporary data here. To mount
538 an MFS RAM disk on <filename>/tmp</filename>, add the following line
539 to <filename>/etc/fstab</filename>:</para>
542 <programlisting>/dev/ad1s2b /tmp mfs rw 0 0</programlisting>
545 <para>Now you simply need to either reboot, or run the command
546 <command>mount /tmp</command>.</para>
549 <primary>kernel options</primary>
550 <secondary>NFS</secondary>
553 <primary>kernel options</primary>
554 <secondary>NFS_ROOT</secondary>
556 <programlisting>options NFS #Network Filesystem
557 options NFS_ROOT #NFS usable as root device, NFS required</programlisting>
559 <para>The network Filesystem. Unless you plan to mount partitions
560 from a &unix; file server over TCP/IP, you can comment these
564 <primary>kernel options</primary>
565 <secondary>MSDOSFS</secondary>
567 <programlisting>options MSDOSFS #MSDOS Filesystem</programlisting>
569 <para>The &ms-dos; Filesystem. Unless you plan to mount a DOS formatted
570 hard drive partition at boot time, you can safely comment this out.
571 It will be automatically loaded the first time you mount a DOS
572 partition, as described above. Also, the excellent
573 <application>mtools</application> software (in the ports collection)
574 allows you to access DOS floppies without having to mount and
575 unmount them (and does not require <literal>MSDOSFS</literal> at
578 <programlisting>options CD9660 #ISO 9660 Filesystem
579 options CD9660_ROOT #CD-ROM usable as root, CD9660 required</programlisting>
581 <para>The ISO 9660 Filesystem for CDROMs. Comment it out if you do
582 not have a CDROM drive or only mount data CDs occasionally (since it
583 will be dynamically loaded the first time you mount a data CD).
584 Audio CDs do not need this Filesystem.</para>
586 <programlisting>options PROCFS #Process filesystem</programlisting>
588 <para>The process filesystem. This is a <quote>pretend</quote>
589 filesystem mounted on <filename>/proc</filename> which allows
590 programs like &man.ps.1; to give you more information on what
591 processes are running. </para>
593 <programlisting>options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
595 <para>Compatibility with 4.3BSD. Leave this in; some programs will
596 act strangely if you comment this out.</para>
598 <programlisting>options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI</programlisting>
600 <para>This causes the kernel to pause for 15 seconds before probing
601 each SCSI device in your system. If you only have IDE hard drives,
602 you can ignore this, otherwise you will probably want to lower this
603 number, perhaps to 5 seconds, to speed up booting. Of course, if
604 you do this, and &os; has trouble recognizing your SCSI devices,
605 you will have to raise it back up.</para>
607 <programlisting>options UCONSOLE #Allow users to grab the console</programlisting>
609 <para>Allow users to grab the console, which is useful for X users.
610 For example, you can create a console <application>xterm</application>
611 by typing <command>xterm
612 -C</command>, which will display any &man.write.1;,
613 &man.talk.1;, and any other messages you receive, as well
614 as any console messages sent by the kernel.</para>
616 <programlisting>options USERCONFIG #boot -c editor</programlisting>
618 <para>This option allows you to boot the configuration editor from the
621 <programlisting>options VISUAL_USERCONFIG #visual boot -c editor</programlisting>
623 <para>This option allows you to boot the visual configuration editor
624 from the boot menu.</para>
626 <programlisting>options KTRACE #ktrace(1) support</programlisting>
628 <para>This enables kernel process tracing, which is useful in
631 <programlisting>options SYSVSHM #SYSV-style shared memory</programlisting>
633 <para>This option provides for System V shared memory. The most
634 common use of this is the XSHM extension in X, which many
635 graphics-intensive programs will automatically take advantage of for
636 extra speed. If you use X, you will definitely want to include
639 <programlisting>options SYSVSEM #SYSV-style semaphores</programlisting>
641 <para>Support for System V semaphores. Less commonly used but only
642 adds a few hundred bytes to the kernel.</para>
644 <programlisting>options SYSVMSG #SYSV-style message queues</programlisting>
646 <para>Support for System V messages. Again, only adds a few hundred
647 bytes to the kernel.</para>
650 <para>The &man.ipcs.1; command will list any processes using each of
651 these System V facilities.</para>
654 <programlisting>options P1003_1B #Posix P1003_1B real-time extensions
655 options _KPOSIX_PRIORITY_SCHEDULING</programlisting>
657 <para>Real-time extensions added in the 1993 &posix;. Certain
658 applications in the ports collection use these
659 (such as <application>&staroffice;</application>).</para>
662 <primary>kernel options</primary>
663 <secondary>ICMP_BANDLIM</secondary>
666 <primary>Denial of Service (DoS)</primary>
668 <programlisting>options ICMP_BANDLIM #Rate limit bad replies</programlisting>
670 <para>This option enables ICMP error response bandwidth limiting. You
671 typically want this option as it will help protect the machine from
672 denial of service packet attacks.</para>
675 <primary>kernel options</primary>
676 <secondary>SMP</secondary>
678 <programlisting># To make an SMP kernel, the next two are needed
679 #options SMP # Symmetric MultiProcessor Kernel
680 #options APIC_IO # Symmetric (APIC) I/O</programlisting>
682 <para>The above are both required for SMP support.</para>
684 <programlisting>device isa</programlisting>
686 <para>All PCs supported by &os; have one of these. Do not remove,
687 even if you have no ISA slots. If you have an
688 IBM PS/2 (Micro Channel Architecture), &os; provides some
689 limited support at this time. For more information about the
691 <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
693 <programlisting>device eisa</programlisting>
695 <para>Include this if you have an EISA motherboard. This enables
696 auto-detection and configuration support for all devices on the EISA
699 <programlisting>device pci</programlisting>
701 <para>Include this if you have a PCI motherboard. This enables
702 auto-detection of PCI cards and gatewaying from the PCI to ISA
705 <programlisting>device agp</programlisting>
707 <para>Include this if you have an AGP card in the system. This
708 will enable support for AGP, and AGP GART for boards which
709 have these features.</para>
711 <programlisting># Floppy drives
712 device fdc0 at isa? port IO_FD1 irq 6 drq 2
713 device fd0 at fdc0 drive 0
714 device fd1 at fdc0 drive 1</programlisting>
716 <para>This is the floppy drive controller. <literal>fd0</literal> is
717 the <devicename>A:</devicename> floppy drive, and
718 <literal>fd1</literal> is the <devicename>B:</devicename>
721 <programlisting>device ata</programlisting>
723 <para>This driver supports all ATA and ATAPI devices. You only need
724 one <literal>device ata</literal> line for the kernel to detect all
725 PCI ATA/ATAPI devices on modern machines.</para>
727 <programlisting>device atadisk # ATA disk drives</programlisting>
729 <para>This is needed along with <literal>device ata</literal> for
730 ATA disk drives.</para>
732 <programlisting><anchor id="kernelconfig-atapi">
733 device atapicd # ATAPI CDROM drives</programlisting>
735 <para>This is needed along with <literal>device ata</literal> for
736 ATAPI CDROM drives.</para>
738 <programlisting>device atapifd # ATAPI floppy drives</programlisting>
740 <para>This is needed along with <literal>device ata</literal> for
741 ATAPI floppy drives.</para>
743 <programlisting>device atapist # ATAPI tape drives</programlisting>
745 <para>This is needed along with <literal>device ata</literal> for
746 ATAPI tape drives.</para>
748 <programlisting>options ATA_STATIC_ID #Static device numbering</programlisting>
750 <para>This makes the controller number static (like the old driver) or
751 else the device numbers are dynamically allocated.</para>
753 <programlisting># ATA and ATAPI devices
754 device ata0 at isa? port IO_WD1 irq 14
755 device ata1 at isa? port IO_WD2 irq 15</programlisting>
757 <para>Use the above for older, non-PCI systems.</para>
759 <programlisting># SCSI Controllers
760 device ahb # EISA AHA1742 family
761 device ahc # AHA2940 and onboard AIC7xxx devices
762 device amd # AMD 53C974 (Teckram DC-390(T))
763 device dpt # DPT Smartcache - See LINT for options!
764 device isp # Qlogic family
765 device ncr # NCR/Symbios Logic
766 device sym # NCR/Symbios Logic (newer chipsets)
772 device aic0 at isa?</programlisting>
774 <para>SCSI controllers. Comment out any you do not have in your
775 system. If you have an IDE only system, you can remove these
778 <programlisting># SCSI peripherals
779 device scbus # SCSI bus (required)
780 device da # Direct Access (disks)
781 device sa # Sequential Access (tape etc)
783 device pass # Passthrough device (direct SCSI
784 access)</programlisting>
786 <para>SCSI peripherals. Again, comment out any you do not have, or if
787 you have only IDE hardware, you can remove them completely.</para>
790 <para>The USB &man.umass.4; driver (and a few other drivers) use
791 the SCSI subsystem even though they are not real SCSI devices.
792 Therefore make sure not to remove SCSI support, if any such
793 drivers are included in the kernel configuration.</para>
796 <programlisting># RAID controllers
797 device ida # Compaq Smart RAID
798 device amr # AMI MegaRAID
799 device mlx # Mylex DAC960 family</programlisting>
801 <para>Supported RAID controllers. If you do not have any of these,
802 you can comment them out or remove them.</para>
804 <programlisting># atkbdc0 controls both the keyboard and the PS/2 mouse
805 device atkbdc0 at isa? port IO_KBD</programlisting>
807 <para>The keyboard controller (<literal>atkbdc</literal>) provides I/O
808 services for the AT keyboard and PS/2 style pointing devices. This
809 controller is required by the keyboard driver
810 (<literal>atkbd</literal>) and the PS/2 pointing device driver
811 (<literal>psm</literal>).</para>
813 <programlisting>device atkbd0 at atkbdc? irq 1</programlisting>
815 <para>The <literal>atkbd</literal> driver, together with
816 <literal>atkbdc</literal> controller, provides access to the AT 84
817 keyboard or the AT enhanced keyboard which is connected to the AT
818 keyboard controller.</para>
820 <programlisting>device psm0 at atkbdc? irq 12</programlisting>
822 <para>Use this device if your mouse plugs into the PS/2 mouse
825 <programlisting>device vga0 at isa?</programlisting>
827 <para>The video card driver.</para>
829 <programlisting># splash screen/screen saver
830 pseudo-device splash</programlisting>
832 <para>Splash screen at start up! Screen savers require this
835 <programlisting># syscons is the default console driver, resembling an SCO console
836 device sc0 at isa?</programlisting>
838 <para><literal>sc0</literal> is the default console driver, which
839 resembles a SCO console. Since most full-screen programs access the
840 console through a terminal database library like
841 <filename>termcap</filename>, it should not matter whether you use
842 this or <literal>vt0</literal>, the <literal>VT220</literal>
843 compatible console driver. When you log in, set your
844 <envar>TERM</envar> variable to <literal>scoansi</literal> if
845 full-screen programs have trouble running under this console.</para>
847 <programlisting># Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
849 #options XSERVER # support for X server on a vt console
850 #options FAT_CURSOR # start with block cursor
851 # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
852 #options PCVT_SCANSET=2 # IBM keyboards are non-std</programlisting>
854 <para>This is a VT220-compatible console driver, backward compatible to
855 VT100/102. It works well on some laptops which have hardware
856 incompatibilities with <literal>sc0</literal>. Also set your
857 <envar>TERM</envar> variable to <literal>vt100</literal> or
858 <literal>vt220</literal> when you log in. This driver might also
859 prove useful when connecting to a large number of different machines
860 over the network, where <filename>termcap</filename> or
861 <filename>terminfo</filename> entries for the <literal>sc0</literal>
862 device are often not available — <literal>vt100</literal>
863 should be available on virtually any platform.</para>
865 <programlisting># Power management support (see LINT for more options)
866 device apm0 at nexus? disable flags 0x20 # Advanced Power Management</programlisting>
868 <para>Advanced Power Management support. Useful for laptops.</para>
870 <programlisting># PCCARD (PCMCIA) support
872 device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
873 device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable</programlisting>
875 <para>PCMCIA support. You want this if you are using a
878 <programlisting># Serial (COM) ports
879 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
880 device sio1 at isa? port IO_COM2 irq 3
881 device sio2 at isa? disable port IO_COM3 irq 5
882 device sio3 at isa? disable port IO_COM4 irq 9</programlisting>
884 <para>These are the four serial ports referred to as COM1 through COM4
885 in the &ms-dos/&windows; world.</para>
888 <para>If you have an internal modem on COM4 and a serial port at
889 COM2, you will have to change the IRQ of the modem to 2 (for
890 obscure technical reasons, IRQ2 = IRQ 9) in order to access it
891 from &os;. If you have a multiport serial card, check the
892 manual page for &man.sio.4; for more information on the proper
893 values for these lines. Some video cards (notably those based on
894 S3 chips) use IO addresses in the form of
895 <literal>0x*2e8</literal>, and since many cheap serial cards do
896 not fully decode the 16-bit IO address space, they clash with
897 these cards making the COM4 port practically unavailable.</para>
899 <para>Each serial port is required to have a unique IRQ (unless you
900 are using one of the multiport cards where shared interrupts are
901 supported), so the default IRQs for COM3 and COM4 cannot be
905 <programlisting># Parallel port
906 device ppc0 at isa? irq 7</programlisting>
908 <para>This is the ISA-bus parallel port interface.</para>
910 <programlisting>device ppbus # Parallel port bus (required)</programlisting>
912 <para>Provides support for the parallel port bus.</para>
914 <programlisting>device lpt # Printer</programlisting>
916 <para>Support for parallel port printers.</para>
919 <para>All three of the above are required to enable parallel printer
923 <programlisting>device plip # TCP/IP over parallel</programlisting>
925 <para>This is the driver for the parallel network interface.</para>
927 <programlisting>device ppi # Parallel port interface device</programlisting>
929 <para>The general-purpose I/O (<quote>geek port</quote>) + IEEE1284
932 <programlisting>#device vpo # Requires scbus and da</programlisting>
934 <indexterm><primary>zip drive</primary></indexterm>
935 <para>This is for an Iomega Zip drive. It requires
936 <literal>scbus</literal> and <literal>da</literal> support. Best
937 performance is achieved with ports in EPP 1.9 mode.</para>
939 <programlisting># PCI Ethernet NICs.
940 device de # DEC/Intel DC21x4x (<quote>Tulip</quote>)
941 device fxp # Intel EtherExpress PRO/100B (82557, 82558)
942 device tx # SMC 9432TX (83c170 <quote>EPIC</quote>)
943 device vx # 3Com 3c590, 3c595 (<quote>Vortex</quote>)
944 device wx # Intel Gigabit Ethernet Card (<quote>Wiseman</quote>)</programlisting>
946 <para>Various PCI network card drivers. Comment out or remove any of
947 these not present in your system.</para>
949 <programlisting># PCI Ethernet NICs that use the common MII bus controller code.
950 device miibus # MII bus support</programlisting>
952 <para>MII bus support is required for some PCI 10/100 Ethernet NICs,
953 namely those which use MII-compliant transceivers or implement
954 transceiver control interfaces that operate like an MII. Adding
955 <literal>device miibus</literal> to the kernel config pulls in
956 support for the generic miibus API and all of the PHY drivers,
957 including a generic one for PHYs that are not specifically handled
958 by an individual driver.</para>
960 <programlisting>device dc # DEC/Intel 21143 and various workalikes
961 device rl # RealTek 8129/8139
962 device sf # Adaptec AIC-6915 (<quote>Starfire</quote>)
963 device sis # Silicon Integrated Systems SiS 900/SiS 7016
964 device ste # Sundance ST201 (D-Link DFE-550TX)
965 device tl # Texas Instruments ThunderLAN
966 device vr # VIA Rhine, Rhine II
967 device wb # Winbond W89C840F
968 device xl # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting>
970 <para>Drivers that use the MII bus controller code.</para>
972 <programlisting># ISA Ethernet NICs.
973 device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
976 # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
977 # exists only as a PCMCIA device, so there is no ISA attachment needed
978 # and resources will always be dynamically assigned by the pccard code.
980 # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
981 # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
982 # mode (the factory default). If you set the switches on your ISA
983 # card for a manually chosen I/O address and IRQ, you must specify
984 # those parameters here.
986 # The probe order of these is presently determined by i386/isa/isa_compat.c.
987 device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
988 device fe0 at isa? port 0x300
989 device le0 at isa? port 0x300 irq 5 iomem 0xd0000
990 device lnc0 at isa? port 0x280 irq 10 drq 0
991 device cs0 at isa? port 0x300
992 device sn0 at isa? port 0x300 irq 10
993 # requires PCCARD (PCMCIA) support to be activated
994 #device xe0 at isa?</programlisting>
996 <para>ISA Ethernet drivers. See
997 <filename>/usr/src/sys/i386/conf/LINT</filename> for which cards are
998 supported by which driver.</para>
1000 <programlisting>pseudo-device ether # Ethernet support</programlisting>
1002 <para><literal>ether</literal> is only needed if you have an Ethernet
1003 card. It includes generic Ethernet protocol code. </para>
1005 <programlisting>pseudo-device sl 1 # Kernel SLIP</programlisting>
1007 <para><literal>sl</literal> is for SLIP support. This has been almost
1008 entirely supplanted by PPP, which is easier to set up, better suited
1009 for modem-to-modem connection, and more powerful. The
1010 <replaceable>number</replaceable> after <literal>sl</literal>
1011 specifies how many simultaneous SLIP sessions to support.</para>
1013 <programlisting>pseudo-device ppp 1 # Kernel PPP</programlisting>
1015 <para>This is for kernel PPP support for dial-up connections. There
1016 is also a version of PPP implemented as a userland application that
1017 uses <literal>tun</literal> and offers more flexibility and features
1018 such as demand dialing. The <replaceable>number</replaceable> after
1019 <literal>ppp</literal> specifies how many simultaneous PPP
1020 connections to support. .</para>
1022 <programlisting>device tun # Packet tunnel.</programlisting>
1024 <para>This is used by the userland PPP software. A
1025 <replaceable>number</replaceable> after <literal>tun</literal>
1026 specifies the number of simultaneous PPP sessions to support. See
1027 the <link linkend="userppp">PPP</link> section of this book for more
1030 <programlisting><anchor id="kernelconfig-ptys">
1031 pseudo-device pty # Pseudo-ttys (telnet etc)</programlisting>
1033 <para>This is a <quote>pseudo-terminal</quote> or simulated login port.
1034 It is used by incoming <command>telnet</command> and
1035 <command>rlogin</command> sessions,
1036 <application>xterm</application>, and some other applications such
1037 as <application>Emacs</application>. The
1038 <replaceable>number</replaceable> after <literal>pty</literal> indicates the number of
1039 <literal>pty</literal>s to create. If you need more than the
1040 default of 16 simultaneous <application>xterm</application> windows
1041 and/or remote logins, be sure to increase this number accordingly,
1042 up to a maximum of 256.</para>
1044 <programlisting>pseudo-device md # Memory <quote>disks</quote></programlisting>
1046 <para>Memory disk pseudo-devices. </para>
1048 <programlisting>pseudo-device gif # IPv6 and IPv4 tunneling</programlisting>
1050 <para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling,
1051 IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. </para>
1053 <programlisting>pseudo-device faith # IPv6-to-IPv4 relaying (translation)</programlisting>
1055 <para>This pseudo-device captures packets that are sent to it and
1056 diverts them to the IPv4/IPv6 translation daemon. </para>
1058 <programlisting># The `bpf' device enables the Berkeley Packet Filter.
1059 # Be aware of the administrative consequences of enabling this!
1060 pseudo-device bpf # Berkeley packet filter</programlisting>
1062 <para>This is the Berkeley Packet Filter. This pseudo-device allows
1063 network interfaces to be placed in promiscuous mode, capturing every
1064 packet on a broadcast network (e.g., an Ethernet). These packets
1065 can be captured to disk and or examined with the &man.tcpdump.1;
1069 <para>The &man.bpf.4; device is also used by
1070 &man.dhclient.8; to obtain the IP address of the default router
1071 (gateway) and so on. If you use DHCP, leave this
1075 <programlisting># USB support
1076 #device uhci # UHCI PCI->USB interface
1077 #device ohci # OHCI PCI->USB interface
1078 #device usb # USB Bus (required)
1079 #device ugen # Generic
1080 #device uhid # <quote>Human Interface Devices</quote>
1081 #device ukbd # Keyboard
1082 #device ulpt # Printer
1083 #device umass # Disks/Mass storage - Requires scbus and da
1085 # USB Ethernet, requires mii
1086 #device aue # ADMtek USB ethernet
1087 #device cue # CATC USB ethernet
1088 #device kue # Kawasaki LSI USB ethernet</programlisting>
1090 <para>Support for various USB devices.</para>
1092 <para>For more information and additional devices supported by
1094 <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
1097 <sect1 id="kernelconfig-nodes">
1098 <title>Making Device Nodes</title>
1100 <indexterm><primary>device nodes</primary></indexterm>
1102 <primary><command>MAKEDEV</command></primary>
1105 <para>Almost every device in the kernel has a corresponding
1106 <quote>node</quote> entry in the <filename>/dev</filename> directory.
1107 These nodes look like regular files, but are actually special
1108 entries into the kernel which programs use to access the device.
1109 The shell script <filename>/dev/MAKEDEV</filename>, which is
1110 executed when you first install the operating system, creates
1111 nearly all of the device nodes supported. However, it does not
1112 create <emphasis>all</emphasis> of them, so when you add support for
1113 a new device, it pays to make sure that the appropriate entries are
1114 in this directory, and if not, add them. Here is a simple
1117 <para>Suppose you add the IDE CD-ROM support to the kernel. The line
1120 <programlisting>device acd0</programlisting>
1122 <para>This means that you should look for some entries that start with
1123 <filename>acd0</filename> in the <filename>/dev</filename>
1124 directory, possibly followed by a letter, such as
1125 <literal>c</literal>, or preceded by the letter
1126 <literal>r</literal>, which means a <quote>raw</quote> device. It
1127 turns out that those files are not there, so you must change to the
1128 <filename>/dev</filename> directory and type:</para>
1131 <primary><command>MAKEDEV</command></primary></indexterm>
1132 <screen>&prompt.root; <userinput>sh MAKEDEV acd0</userinput></screen>
1134 <para>When this script finishes, you will find that there are now
1135 <filename>acd0c</filename> and <filename>racd0c</filename> entries
1136 in <filename>/dev</filename> so you know that it executed
1139 <para>For sound cards, the following command creates the appropriate
1142 <screen>&prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen>
1145 <para>When creating device nodes for devices such as sound cards, if
1146 other people have access to your machine, it may be desirable to
1147 protect the devices from outside access by adding them to the
1148 <filename>/etc/fbtab</filename> file. See &man.fbtab.5; for more
1152 <para>Follow this simple procedure for any other
1153 non-<filename>GENERIC</filename> devices which do not have
1157 <para>All SCSI controllers use the same set of
1158 <filename>/dev</filename> entries, so you do not need to create
1159 these. Also, network cards and SLIP/PPP pseudo-devices do not
1160 have entries in <filename>/dev</filename> at all, so you do not
1161 have to worry about these either.</para>
1165 <sect1 id="kernelconfig-trouble">
1166 <title>If Something Goes Wrong</title>
1168 <para>There are five categories of trouble that can occur when
1169 building a custom kernel. They are:</para>
1173 <term><command>config</command> fails:</term>
1176 <para>If the &man.config.8; command fails when you
1177 give it your kernel description, you have probably made a
1178 simple error somewhere. Fortunately,
1179 &man.config.8; will print the line number that it
1180 had trouble with, so you can quickly skip to it with
1181 <application>vi</application>. For example, if you see:</para>
1183 <screen>config: line 17: syntax error</screen>
1185 <para>You can skip to the problem in <application>vi</application> by
1186 typing <command>17G</command> in command mode. Make sure the
1187 keyword is typed correctly, by comparing it to the
1188 <filename>GENERIC</filename> kernel or another
1194 <term><command>make</command> fails:</term>
1197 <para>If the <command>make</command> command fails, it usually
1198 signals an error in your kernel description, but not severe
1199 enough for &man.config.8; to catch it. Again, look
1200 over your configuration, and if you still cannot resolve the
1201 problem, send mail to the &a.bugs; with your kernel
1202 configuration, and it should be diagnosed very quickly.</para>
1207 <term>Installing the new kernel fails:</term>
1210 <para>If the kernel compiled fine, but failed to install
1211 (the <command>make install</command> or
1212 <command>make installkernel</command> command failed),
1213 the first thing to check is if your system is running at
1214 securelevel 1 or higher (see &man.init.8;). The kernel
1215 installation tries to remove the immutable flag from
1216 your kernel and set the immutable flag on the new one.
1217 Since securelevel 1 or higher prevents unsetting the immutable
1218 flag for any files on the system, the kernel installation needs
1219 to be performed at securelevel 0 or lower.</para>
1224 <term>The kernel does not boot:<anchor
1225 id="kernelconfig-noboot"></term>
1228 <para>If your new kernel does not boot, or fails to
1229 recognize your devices, do not panic! Fortunately, &os; has
1230 an excellent mechanism for recovering from incompatible
1231 kernels. Simply choose the kernel you want to boot from at
1232 the &os; boot loader. You can access this when the system
1233 counts down from 10. Hit any key except for the
1234 <keycap>Enter</keycap> key, type <command>unload</command>
1236 <command>boot <replaceable>kernel.old</replaceable></command>,
1237 or the filename of any other kernel that will boot properly.
1238 When reconfiguring a kernel, it is always a good idea to keep
1239 a kernel that is known to work on hand.</para>
1241 <para>After booting with a good kernel you can check over your
1242 configuration file and try to build it again. One helpful
1243 resource is the <filename>/var/log/messages</filename> file
1244 which records, among other things, all of the kernel messages
1245 from every successful boot. Also, the &man.dmesg.8; command
1246 will print the kernel messages from the current boot.</para>
1249 <para>If you are having trouble building a kernel, make sure
1250 to keep a <filename>GENERIC</filename>, or some other kernel
1251 that is known to work on hand as a different name that will
1252 not get erased on the next build. You cannot rely on
1253 <filename>kernel.old</filename> because when installing a
1254 new kernel, <filename>kernel.old</filename> is overwritten
1255 with the last installed kernel which may be non-functional.
1256 Also, as soon as possible, move the working kernel to the
1257 proper <filename>kernel</filename> location or commands such
1258 as &man.ps.1; will not work properly. The proper command to
1259 <quote>unlock</quote> the kernel file that
1260 <command>make</command> installs (in order to move another
1261 kernel back permanently) is:</para>
1263 <screen>&prompt.root; <userinput>chflags noschg /kernel</userinput></screen>
1265 <para>If you find you cannot do this, you are probably running
1266 at a &man.securelevel.8; greater than zero. Edit
1267 <literal>kern_securelevel</literal> in
1268 <filename>/etc/rc.conf</filename> and set it to
1269 <literal>-1</literal>, then reboot. You can change it back
1270 to its previous setting when you are happy with your new
1273 <para>And, if you want to <quote>lock</quote> your new kernel
1274 into place, or any file for that matter, so that it cannot
1275 be moved or tampered with:</para>
1277 <screen>&prompt.root; <userinput>chflags schg /kernel</userinput></screen>
1284 <term>The kernel works, but &man.ps.1; does not work
1288 <para>If you have installed a different version of the kernel
1289 from the one that the system utilities have been built with,
1291 commands like &man.ps.1; and &man.vmstat.8; will not work any
1292 more. You must recompile the <filename>libkvm</filename>
1293 library as well as these utilities. This is one reason it is
1294 not normally a good idea to use a different version of the
1295 kernel from the rest of the operating system.</para>
1305 sgml-declaration: "../chapter.decl"
1308 sgml-always-quote-attributes: t
1309 sgml-parent-document: ("../book.sgml" "part" "chapter")
projects / dragonfly.git / blob