path: root/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml

<!--
     The FreeBSD Documentation Project

     $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml,v 1.25 2000/04/06 00:07:13 jim Exp $
-->

<chapter id="kernelconfig">
  <title>Configuring the FreeBSD Kernel</title>

  <sect1>
    <title>Synopsis</title>

    <para><emphasis>Updated and restructured by &a.jim;, March 2000.
      Originally contributed by &a.jehamby;, 6 October
      1995.</emphasis></para>

    <para>The following chapter of the handbook covers everything you will
      need to know in order to build a custom kernel.  If you are
      wondering what the benefits of a custom kernel are, or would like to
      know how to configure, compile, and install a custom kernel, this
      chapter is for you.</para>
  </sect1>

  <sect1>
    <title>Why Build a Custom Kernel?</title>

    <para>Building a custom kernel is one of the most important rites of
      passage nearly every UNIX user must endure.  This process, while
      time consuming, will provide many benefits to your FreeBSD system.
      Unlike the <filename>GENERIC</filename> kernel, which must support a
      wide range of hardware, a custom kernel only contains support for
      <emphasis>your</emphasis> PC's hardware.  This has a number of
      benefits, such as:</para>

    <itemizedlist>
      <listitem>
	<para>Faster boot time.  Since the kernel will only probe the
	hardware you have on your system, the time it takes your system to
	boot will decrease dramatically.</para>
      </listitem>

      <listitem>
	<para>Less memory use.  A custom kernel often uses less memory
	  than the <literal>GENERIC</literal> kernel, which is important
	  because the kernel is one process that must always be present in
	  memory.  For this reason, a custom kernel is especially useful
	  on a system with a small amount of RAM.</para>
      </listitem>

      <listitem>
	<para>Additional hardware support.  A custom kernel allows you to
	  add in support for devices such as sound cards, which are not
	  present in the <literal>GENERIC</literal> kernel.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="kernelconfig-building">
    <title>Building and Installing a Custom Kernel</title>

    <para>First, let us take a quick tour of the kernel build directory.
      All directories mentioned will be relative to the main
      <filename>/usr/src/sys</filename> directory, which is also
      accessible through <filename>/sys</filename>.  There are a number of
      subdirectories here representing different parts of the kernel, but
      the most important, for our purposes, are
      <filename><replaceable>arch</replaceable>/conf</filename>, where you
      will edit your custom kernel configuration, and
      <filename>compile</filename>, which is the staging area where your
      kernel will be built.  <replaceable>arch</replaceable> represents
      either <filename>i386</filename>, <filename>alpha</filename>, or
      <filename>pc98</filename> (an alternative development branch of PC
      hardware, popular in Japan).  Everything inside a particular
      architecture's directory deals with that architecture only; the rest
      of the code is common to all platforms to which FreeBSD could
      potentially be ported.  Notice the logical organization of the
      directory structure, with each supported device, filesystem, and
      option in its own subdirectory.</para>

    <note>
      <para>If there is <emphasis>not</emphasis> a
	<filename>/usr/src/sys</filename> directory on your system, then
	the kernel source has not been been installed.  The easiest way to
	do this is by running <command>/stand/sysinstall</command> as
	<username>root</username>, choosing <literal>Configure</literal>,
	then <literal>Distributions</literal>, then
	<literal>src</literal>, then <literal>sys</literal>.</para>
    </note>

    <para>Next, move to the
      <filename><replaceable>arch</replaceable>/conf</filename> directory
      and copy the <filename>GENERIC</filename> configuration file to the
      name you want to give your kernel.  For example:</para>

    <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf</userinput>
&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>

    <para>Traditionally, this name is in all capital letters and, if you
      are maintaining multiple FreeBSD machines with different hardware,
      it is a good idea to name it after your machine's hostname.  We will
      call it <filename>MYKERNEL</filename> for the purpose of this
      example.</para>

    <note>
      <para>You must execute these and all of the following commands under
	the root account or you will get <errortype>permission
	denied</errortype> errors.</para>
    </note>

    <para>Now, edit <filename>MYKERNEL</filename> with your favorite text
      editor.  If you are just starting out, the only editor available
      will probably be <command>vi</command>, which is too complex to
      explain here, but is covered well in many books in the <link
      linkend="bibliography">bibliography</link>.  However, FreeBSD does
      offer an easier editor called <quote>ee</quote> which, if you are a
      beginner, should be your editor of choice.  Feel free to change the
      comment lines at the top to reflect your configuration or the
      changes you have made to differentiate it from
      <filename>GENERIC</filename>.</para>

    <para>If you have build a kernel under SunOS or some other BSD
      operating system, much of this file will be very familiar to you.
      If you are coming from some other operating system such as DOS, on
      the other hand, the <filename>GENERIC</filename> configuration file
      might seem overwhelming to you, so follow the descriptions in the
      <link linkend="kernelconfig-config">Configuration File</link>
      section slowly and carefully.</para>

    <note>
      <para>If you are trying to upgrade your kernel from an older version
	of FreeBSD, you will probably have to get a new version of
	&man.config.8; from the same place you got the new kernel sources.
	It is located in <filename>/usr/src/usr.sbin</filename>, so you
	will need to download those sources as well.  Re-build and install
	it before running the next commands.</para>
    </note>

    <para>When you are finished, type the following to compile and install
      your kernel:</para>

    <screen>&prompt.root; <userinput>/usr/sbin/config MYKERNEL</userinput>
&prompt.root; <userinput>cd ../../compile/MYKERNEL</userinput>
&prompt.root; <userinput>make depend</userinput>
&prompt.root; <userinput>make</userinput>
&prompt.root; <userinput>make install</userinput></screen>

    <para>The new kernel will be copied to the root directory as
      <filename>/kernel</filename> and the old kernel will be moved to
      <filename>/kernel.old</filename>.  Now, shutdown the system and
      reboot to use your kernel.  In case something goes wrong, there are
      some <link linkend="kernelconfig-trouble">troubleshooting</link>
      instructions at the end of this document.  Be sure to read the
      section which explains how to recover in case your new kernel <link
      linkend="kernelconfig-noboot">does not boot</link>.</para>

    <note>
      <para>If you have added any new devices (such as sound cards) you
	may have to add some <link linkend="kernelconfig-nodes">device
	nodes</link> to your <filename>/dev</filename> directory before
	you can use them.</para>
    </note>
  </sect1>

  <sect1 id="kernelconfig-config">
    <title>The Configuration File</title>

    <para>The general format of a configuration file is quite simple.
      Each line contains a keyword and one or more arguments.  For
      simplicity, most lines only contain one argument.  Anything
      following a <literal>#</literal> is considered a comment and
      ignored.  The following sections describe each keyword, generally in
      the order they are listed in <filename>GENERIC</filename>, although
      some related keywords have been grouped together in a single section
      (such as Networking) even though they are actually scattered
      throughout the <filename>GENERIC</filename> file.  <anchor
      id="kernelconfig-options"> An exhaustive list of options and more
      detailed explanations of the device lines is present in the
      <filename>LINT</filename> configuration file, located in the same
      directory as <filename>GENERIC</filename>.  If you are in doubt as
      to the purpose or necessity of a line, check first in
      <filename>LINT</filename>.</para>

    <important>
      <title>Quoting numbers</title>

      <para>In all versions of FreeBSD up to and including 3.X,
	&man.config.8; required that any strings in the configuration file
	that contained numbers used as text had to be enclosed in double
	quotes.</para>

      <para>This requirement was removed in the 4.X branch, which this
	book covers, so if you are on a pre-4.X system, see the
	<filename>/usr/src/sys/i386/conf/LINT</filename> and
	<filename>/usr/src/sys/i386/conf/GENERIC</filename>
	files on your system for examples.</para>
    </important>

    <para>The following is an example <filename>GENERIC</filename> kernel
      configuration file with various additional comments where needed for
      clarity.  This example should match your copy in
      <filename>/usr/src/sys/i386/conf/GENERIC</filename> fairly
      closely.  For details of all the possible kernel options, see
      <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>

    <programlisting>
#
# GENERIC -- Generic kernel configuration file for FreeBSD/i386
#
# For more information on this file, please read the handbook section on
# Kernel Configuration Files:
#
#    http://www.freebsd.org/handbook/kernelconfig-config.html
#
# The handbook is also available locally in /usr/share/doc/handbook
# if you've installed the doc distribution, otherwise always see the
# FreeBSD World Wide Web server (http://www.FreeBSD.ORG/) for the
# latest information.
#
# An exhaustive list of options and more detailed explanations of the
# device lines is also present in the ./LINT configuration file. If you are
# in doubt as to the purpose or necessity of a line, check first in LINT.
#
# &dollar;FreeBSD: src/sys/i386/conf/GENERIC,v 1.246 2000/03/09 16:32:55 jlemon Exp &dollar;</programlisting>

    <para>The following are the mandatory keywords required in
      <emphasis>every</emphasis> kernel you build:</para>

    <programlisting>machine		i386</programlisting>

    <para>This is the machine architecture.  It must be either
      <literal>i386</literal>, <literal>alpha</literal>, or
      <literal>pc98</literal>.</para>

    <programlisting>
cpu          I386_CPU
cpu          I486_CPU
cpu          I586_CPU
cpu          I686_CPU</programlisting>

    <para>The above specifies the type of CPU you have in your system.
      You may have multiple instances of the CPU line (i.e., you are not
      sure whether you should use <literal>I586_CPU</literal> or
      <literal>I686_CPU</literal>), however, for a custom kernel, it is
      best to specify only the CPU you have.  If you are unsure which type
      your CPU use, you can use the <command>dmesg</command> command to
      view your boot up messages.</para>

    <para>The Alpha architechture has different values for
      <literal>cpu_type</literal>.  They include:</para>

    <programlisting>
cpu          EV4
cpu          EV5</programlisting>

    <para>If you are using an Alpha machine, you should be using one of
      the above CPU types.</para>

    <programlisting>ident          GENERIC</programlisting>

    <para>This is the identification of the kernel.  You should change
      this to whatever you named your kernel, in our previous example,
      <literal>MYKERNEL</literal>.  The value you put in the
      <literal>ident</literal> string will print when you boot up the
      kernel, so it is useful to give a kernel a different name if you
      want to keep it separate from your usual kernel (i.e., you want to
      build an experimental kernel).</para>

    <programlisting>maxusers          32</programlisting>

    <para>The <literal>maxusers</literal> option sets the size of a number
      of important system tables.  This number is supposed to be roughly
      equal to the number of simultaneous users you expect to have on your
      machine.  However, under normal circumstances, you will want to set
      <literal>maxusers</literal> to at least 4, especially if you are
      using the X Window System or compiling software.  The reason is that
      the most important table set by <literal>maxusers</literal> is the
      maximum number of processes,  which is set to <literal>20 + 16 *
      maxusers</literal>, so if you set <literal>maxusers</literal> to 1,
      then you can only have 36 simultaneous processes, including the 18
      or so that the system starts up at boot time, and the 15 or so you
      will probably create when you start the X Window System.  Even a
      simple task like reading a man page will start up nine processes to
      filter, decompress, and view it.  Setting
      <literal>maxusers</literal> to 64 will allow you to have up to 1044
      simultaneous processes, which should be enough for nearly all uses.
      If, however, you see the dreaded <errortype>proc table
      full</errortype> error when trying to start another program, or are
      running a server with a large number of simultaneous users (like
      <hostid role="fqdn">ftp.FreeBSD.org</hostid>), you can always
      increase the number and rebuild.</para>

    <note>
      <para><literal>maxusers</literal> does <emphasis>not</emphasis>
	limit the number of users which can log into your machine.  It
	simply sets various table sizes to reasonable values considering
	the maximum number of users you will likely have on your system
	and how many processes each of them will be running.  One keyword
	which <emphasis>does</emphasis> limit the number of simultaneous
	<emphasis>remote logins</emphasis> is <link
	linkend="kernelconfig-ptys"><literal>pseudo-device pty
	16</literal></link>.</para>
    </note>

    <para>Everything that follows is more or less optional.  See the notes
      underneath or next to each option for more information.</para>

    <programlisting>
#makeoptions     DEBUG=-g          #Build kernel with gdb(1) debug symbols
options          MATH_EMULATE      #Support for x87 emulation</programlisting>

    <para>This line allows the kernel to simulate a math co-processor if
      your computer does not have one (386 or 486SX).  If you have a
      486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or
      higher (Pentium, PentiumII, etc.), you can comment this line
      out.</para>

    <note>
      <para>The normal math co-processor emulation routines that come with
	FreeBSD are <emphasis>not</emphasis> very accurate.  If you do not
	have a math co-processor, and you need the best accuracy, it is
	recommended that you change this option to
	<literal>GPL_MATH_EMULATION</literal> to use the GNU math support,
	which is not included by default for licensing reasons.</para>
    </note>

    <programlisting>
options          INET          #InterNETworking</programlisting>

    <para>Networking support.  Leave this in, even if you do not plan to
      be connected to a network.  Most programs require at least loopback
      networking (i.e., making network connections within your PC), so
      this is essentially mandatory.</para>

    <programlisting>
options          INET6          #IPv6 communications protocols</programlisting>

    <para>This enables the IPv6 communication protocols.</para>

    <programlisting>
options          FFS          #Berkeley Fast Filesystem
options          FFS_ROOT     #FFS usable as root device [keep this!]</programlisting>

    <para>This is the basic hard drive filesystem.  Leave it in if you
      boot from the hard disk.</para>

    <programlisting>
options          MFS          #Memory Filesystem
options          MD_ROOT      #MD is a potential root device</programlisting>

    <para>This is the memory-mapped filesystem.  This is basically a RAM
      disk for fast storage of temporary files, useful if you have a lot
      of swap space that you want to take advantage of.  A perfect place
      to mount an MFS partition is on the <filename>/tmp</filename>
      directory, since many programs store temporary data here.  To mount
      an MFS RAM disk on <filename>/tmp</filename>, add the following line
      to <filename>/etc/fstab</filename>:</para>

    <informalexample>
      <programlisting>/dev/ad1s2b	/tmp mfs rw 0 0</programlisting>
    </informalexample>

    <para>Now you simply need to either reboot, or run the command
      <command>mount /tmp</command>.</para>

    <programlisting>
options          NFS          #Network Filesystem
options          NFS_ROOT     #NFS usable as root device, NFS required</programlisting>

    <para>The network filesystem.  Unless you plan to mount partitions
      from a UNIX file server over ethernet, you can comment these
      out.</para>

    <programlisting>
options          MSDOSFS      #MSDOS Filesystem</programlisting>

    <para>The MS-DOS filesystem.  Unless you plan to mount a DOS formatted
      hard drive partition at boot time, you can safely comment this out.
      It will be automatically loaded the first time you mount a DOS
      partition, as described above.  Also, the excellent
      <application>mtools</application> software (in the ports collection)
      allows you to access DOS floppies without having to mount and
      unmount them (and does not require <literal>MSDOSFS</literal> at
      all).</para>

    <programlisting>
options          CD9660       #ISO 9660 Filesystem
options          CD9660_ROOT  #CD-ROM usable as root, CD9660 required</programlisting>

    <para>The ISO 9660 filesystem for CDROMs.  Comment it out if you do
      not have a CDROM drive or only mount data CDs occasionally (since it
      will be dynamically loaded the first time you mount a data CD).
      Audio CDs do not need this filesystem.</para>

    <programlisting>
options          PROCFS       #Process filesystem</programlisting>

    <para>The process filesystem.  This is a <quote>pretend</quote>
      filesystem mounted on <filename>/proc</filename> which allows
      programs like &man.ps.1; to give you more information on what
      processes are running.</para>

    <programlisting>
options          COMPAT_43    #Compatible with BSD 4.3 [KEEP THIS!]</programlisting>

    <para>Compatibility with 4.3BSD.  Leave this in; some programs will
      act strangely if you comment this out.</para>

    <programlisting>
options          SCSI_DELAY=15000    #Delay (in ms) before probing SCSI</programlisting>

    <para>This causes the kernel to pause for 15 seconds before probing
      each SCSI device in your system.  If you only have IDE hard drives,
      you can ignore this, otherwise you will probably want to lower this
      number, perhaps to 5 seconds, to speed up booting.  Of course, if
      you do this, and FreeBSD has trouble recognizing your SCSI devices,
      you will have to raise it back up.</para>

    <programlisting>
options          UCONSOLE            #Allow users to grab the console</programlisting>

    <para>Allow users to grab the console, which is useful for X users.
      For example, you can create a console xterm by typing <command>xterm
      -C</command>, which will display any <command>write</command>,
      <command>talk</command>, and any other messages you receive, as well
      as any console messages sent by the kernel.</para>

    <programlisting>
options          USERCONFIG          #boot -c editor</programlisting>

    <para>This option allows you to boot the configuration editor from the
      boot menu.</para>

    <programlisting>
options          VISUAL_USERCONFIG   #visual boot -c editor</programlisting>

    <para>This option allows you to boot the visual configuration editor
      from the boot menu.</para>

    <programlisting>
options          KTRACE              #ktrace(1) support</programlisting>

    <para>This enables kernel process tracing, which is useful in
      debugging.</para>

    <programlisting>
options          SYSVSHM             #SYSV-style shared memory</programlisting>

    <para>This option provides for System V shared memory.  The most
      common use of this is the XSHM extension in X, which many
      graphics-intensive programs will automatically take advantage of for
      extra speed.  If you use X, you'll definitely want to include
      this.</para>

    <programlisting>
options          SYSVSEM             #SYSV-style semaphores</programlisting>

    <para>Support for System V semaphores.  Less commonly used but only
      adds a few hundred bytes to the kernel.</para>

    <programlisting>
options          SYSVMSG             #SYSV-style message queues</programlisting>

    <para>Support for System V messages.  Again, only adds a few hundred
      bytes to the kernel.</para>

    <note>
      <para>The &man.ipcs.1; command will list any processes using each of
	these System V facilities.</para>
    </note>

    <programlisting>
options 	P1003_1B		#Posix P1003_1B real-time extentions
options 	_KPOSIX_PRIORITY_SCHEDULING</programlisting>

    <para>Real-time extensions added in the 1993 POSIX.  Certain
      applications in the ports collection use these (such as Star
      Office).</para>

    <programlisting>
options		ICMP_BANDLIM		#Rate limit bad replies</programlisting>

    <para>This option enables ICMP error response bandwidth limiting.  You
      typically want this option as it will help protect the machine from
      denial of service packet attacks.</para>

    <programlisting>
# To make an SMP kernel, the next two are needed
#options        SMP                     # Symmetric MultiProcessor Kernel
#options        APIC_IO                 # Symmetric (APIC) I/O</programlisting>

    <para>The above are both required for SMP support.</para>

    <programlisting>
# Optionally these may need tweaked, (defaults shown):
#options        NCPU=2                  # number of CPUs
#options        NBUS=4                  # number of busses
#options        NAPIC=1                 # number of IO APICs
#options        NINTR=24                # number of INTs</programlisting>

    <para>These are some additional SMP knobs.</para>

    <programlisting>device          isa</programlisting>

    <para>All PCs supported by FreeBSD have one of these.  If you have an
      IBM PS/2 (Micro Channel Architecture), you cannot run FreeBSD at
      this time (support is being worked on).</para>

    <programlisting>device          eisa</programlisting>

    <para>Include this if you have an EISA motherboard.  This enables
      auto-detection and configuration support for all devices on the EISA
      bus.</para>

    <programlisting>device          pci</programlisting>

    <para>Include this if you have a PCI motherboard.  This enables
      auto-detection of PCI cards and gatewaying from the PCI to ISA
      bus.</para>

    <programlisting>
# Floppy drives
device          fdc0        at isa? port IO_FD1 irq 6 drq 2
device          fd0         at fdc0 drive 0
device          fd1         at fdc0 drive 1</programlisting>

    <para>This is the floppy drive controller.  <literal>fd0</literal> is
      the <devicename>A:</devicename> floppy drive, and
      <literal>fd1</literal> is the <devicename>B:</devicename>
      drive.</para>

    <programlisting>device          ata</programlisting>

    <para>This driver supports all ATA and ATAPI devices.  You only need
      one <literal>device ata</literal> line for the kernel to detect all
      PCI ATA/ATAPI devices on modern machines.</para>

    <programlisting>
device          atadisk                 # ATA disk drives</programlisting>

    <para>This is needed along with <literal>device ata</literal> for
      ATAPI disk drives.</para>

    <programlisting><anchor id="kernelconfig-atapi">
device          atapicd                 # ATAPI CDROM drives</programlisting>

    <para>This is needed along with <literal>device ata</literal> for
      ATAPI CDROM drives.</para>

    <programlisting>
device          atapifd                 # ATAPI floppy drives</programlisting>

    <para>This is needed along with <literal>device ata</literal> for
      ATAPI floppy drives.</para>

    <programlisting>
device          atapist                 # ATAPI tape drives</programlisting>

    <para>This is needed along with <literal>device ata</literal> for
      ATAPI tape drives.</para>

    <programlisting>
options         ATA_STATIC_ID           #Static device numbering</programlisting>

    <para>This makes the controller number static (like the old driver) or
      else the device numbers are dynamically allocated.</para>

    <programlisting>
#options        ATA_ENABLE_ATAPI_DMA    #Enable DMA on ATAPI devices</programlisting>

    <para>This enables DMA on the ATAPI device.  Since many ATAPI devices
      claim to support DMA, but it does not actually work, this is turned
      off by default.</para>

    <programlisting>
# ATA and ATAPI devices
device          ata0        at isa? port IO_WD1 irq 14
device          ata1        at isa? port IO_WD2 irq 15</programlisting>

    <para>Use the above for older, non-PCI systems.</para>

    <programlisting>
# SCSI Controllers
device          ahb        # EISA AHA1742 family
device          ahc        # AHA2940 and onboard AIC7xxx devices
device          amd        # AMD 53C974 (Teckram DC-390(T))
device          dpt        # DPT Smartcache - See LINT for options!
device          isp        # Qlogic family
device          ncr        # NCR/Symbios Logic
device          sym        # NCR/Symbios Logic (newer chipsets)

device          adv0       at isa?
device          adw
device          bt0        at isa?
device          aha0       at isa?
device          aic0       at isa?</programlisting>

    <para>SCSI controllers.  Comment out any you do not have in your
      system.  If you have an IDE only system, you can remove these
      altogether.</para>

    <programlisting>
# SCSI peripherals
device          scbus      # SCSI bus (required)
device          da         # Direct Access (disks)
device          sa         # Sequential Access (tape etc)
device          cd         # CD
device          pass       # Passthrough device (direct SCSI
access)</programlisting>

    <para>SCSI peripherals.  Again, comment out any you do not have, or if
      you have only IDE hardware, you can remove them completely.</para>

    <programlisting>
# RAID controllers
device          ida        # Compaq Smart RAID
device          amr        # AMI MegaRAID
device          mlx        # Mylex DAC960 family</programlisting>

    <para>Supported RAID controllers.  If you do not have any of these,
      you can comment them out or remove them.</para>

    <programlisting>
# atkbdc0 controls both the keyboard and the PS/2 mouse
device          atkbdc0    at isa? port IO_KBD</programlisting>

    <para>The keyboard controller (<literal>atkbdc</literal>) provides I/O
      services for the AT keyboard and PS/2 style pointing devices.  This
      controller is required by the keyboard driver
      (<literal>atkbd</literal>) and the PS/2 pointing device driver
      (<literal>psm</literal>).</para>

    <programlisting>
device          atkbd0     at atkbdc? irq 1</programlisting>

    <para>The <literal>atkbd</literal> driver, together with
      <literal>atkbdc</literal> controller, provides access to the AT 84
      keyboard or the AT enhanced keyboard which is connected to the AT
      keyboard controller.</para>

    <programlisting>
device          psm0       at atkbdc? irq 12</programlisting>

    <para>Use this device if your mouse plugs into the PS/2 mouse
      port.</para>

    <programlisting>device          vga0        at isa?</programlisting>

    <para>The video card driver.</para>

    <programlisting>
# splash screen/screen saver
pseudo-device          splash</programlisting>

    <para>Splash screen at start up!  Screen savers require this
      too.</para>

    <programlisting>
# syscons is the default console driver, resembling an SCO console
device          sc0          at isa?</programlisting>

    <para><literal>sc0</literal> is the default console driver, which
      resembles a SCO console.  Since most full-screen programs access the
      console through a terminal database library like
      <filename>termcap</filename>, it should not matter whether you use
      this or <literal>vt0</literal>, the <literal>VT220</literal>
      compatible console driver.  When you log in, set your
      <envar>TERM</envar> variable to <literal>scoansi</literal> if
      full-screen programs have trouble running under this console.</para>

    <programlisting>
# Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
#device          vt0     at isa?
#options         XSERVER          # support for X server on a vt console
#options         FAT_CURSOR       # start with block cursor
# If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
#options         PCVT_SCANSET=2   # IBM keyboards are non-std</programlisting>

    <para>This is a VT220-compatible console driver, backward compatible to
      VT100/102.  It works well on some laptops which have hardware
      incompatibilities with <literal>sc0</literal>.  Also set your
      <envar>TERM</envar> variable to <literal>vt100</literal> or
      <literal>vt220</literal> when you log in.  This driver might also
      prove useful when connecting to a large number of different machines
      over the network, where <filename>termcap</filename> or
      <filename>terminfo</filename> entries for the <literal>sc0</literal>
      device are often not available &mdash; <literal>vt100</literal>
      should be available on virtually any platform.</para>

    <programlisting>
# Floating point support - do not disable.
device          npx0     at nexus? port IO_NPX irq 13</programlisting>

    <para><literal>npx0</literal> is the interface to the floating point
      math unit in FreeBSD, which is either the hardware co-processor or
      the software math emulator.  This is <emphasis>not</emphasis>
      optional.</para>

    <programlisting>
# Power management support (see LINT for more options)
device          apm0     at nexus? disable flags 0x20  # Advanced Power Management</programlisting>

    <para>Advanced Power Management support.  Useful for laptops.</para>

    <programlisting>
# PCCARD (PCMCIA) support
device          card
device          pcic0    at isa? irq 10 port 0x3e0 iomem 0xd0000
device          pcic1    at isa? irq 11 port 0x3e2 iomem 0xd4000 disable</programlisting>

    <para>PCMCIA support.  You need this if you are installing on a
      laptop.</para>

    <programlisting>
# Serial (COM) ports
device          sio0     at isa? port IO_COM1 flags 0x10 irq 4
device          sio1     at isa? port IO_COM2 irq 3
device          sio2     at isa? disable port IO_COM3 irq 5
device          sio3     at isa? disable port IO_COM4 irq 9</programlisting>

    <para>These are the four serial ports referred to as COM1 through COM4
      in the MS-DOS/Windows world.</para>

    <note>
      <para>If you have an internal modem on COM4 and a serial port at
	COM2, you will have to change the IRQ of the modem to 2 (for
	obscure technical reasons, IRQ2 = IRQ 9) in order to access it
	from FreeBSD.  If you have a multiport serial card, check the
	manual page for &man.sio.4; for more information on the proper
	values for these lines.  Some video cards (notably those based on
	S3 chips) use IO addresses in the form of
	<literal>0x*2e8</literal>, and since many cheap serial cards do
	not fully decode the 16-bit IO address space, they clash with
	these cards making the COM4 port practically unavailable.</para>

      <para>Each serial port is required to have a unique IRQ (unless you
        are using one of the multiport cards where shared interrupts are
	supported), so the default IRQs for COM3 and COM4 cannot be
	used.</para>
    </note>

    <programlisting>
# Parallel port
device          ppc0    at isa? irq 7</programlisting>

    <para>This is the ISA-bus parallel port interface.</para>

    <programlisting>
device          ppbus      # Parallel port bus (required)</programlisting>

    <para>Provides support for the parallel port bus.</para>

    <programlisting>
device          lpt        # Printer</programlisting>

    <para>Support for parallel port printers.</para>

    <note>
      <para>All three of the above are required to enable parallel printer
	support.</para>
    </note>

    <programlisting>
device          plip       # TCP/IP over parallel</programlisting>

    <para>This is the driver for the parallel network interface.</para>

    <programlisting>
device          ppi        # Parallel port interface device</programlisting>

    <para>The general-purpose I/O (<quote>geek port</quote>) + IEEE1284
      I/O.</para>

    <programlisting>
#device         vpo        # Requires scbus and da</programlisting>

    <para>This is for an Iomega Zip drive.  It requires
      <literal>scbus</literal> and <literal>da</literal> support.  Best
      performance is achieved with ports in EPP 1.9 mode.</para>

    <programlisting>
# PCI Ethernet NICs.
device          de         # DEC/Intel DC21x4x (<quote>Tulip</quote>)
device          fxp        # Intel EtherExpress PRO/100B (82557, 82558)
device          tx         # SMC 9432TX (83c170 <quote>EPIC</quote>)
device          vx         # 3Com 3c590, 3c595 (<quote>Vortex</quote>)
device          wx         # Intel Gigabit Ethernet Card (<quote>Wiseman</quote>)</programlisting>

    <para>Various PCI network card drivers.  Comment out or remove any of
      these not present in your system.</para>

    <programlisting>
# PCI Ethernet NICs that use the common MII bus controller code.
device          miibus     # MII bus support</programlisting>

    <para>MII bus support is required for some PCI 10/100 ethernet NICs,
      namely those which use MII-compliant transceivers or implement
      transceiver control interfaces taht operate like an MII.  Adding
      <literal>device miibus</literal> to the kernel config pulls in
      support for the generic miibus API and all of the PHY drivers,
      including a generic one for PHYs that are not specifically handled
      by an individual driver</para>

    <programlisting>
device          dc         # DEC/Intel 21143 and various workalikes
device          rl         # RealTek 8129/8139
device          sf         # Adaptec AIC-6915 (<quote>Starfire</quote>)
device          sis        # Silicon Integrated Systems SiS 900/SiS 7016
device          ste        # Sundance ST201 (D-Link DFE-550TX)
device          tl         # Texas Instruments ThunderLAN
device          vr         # VIA Rhine, Rhine II
device          wb         # Winbond W89C840F
device          xl         # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting>

    <para>Drivers that use the MII bus controller code.</para>

    <programlisting>
# ISA Ethernet NICs.
device          ed0    at isa? port 0x280 irq 10 iomem 0xd8000
device          ex
device          ep
# WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
# exists only as a PCMCIA device, so there is no ISA attatement needed
# and resources will always be dynamically assigned by the pccard code.
device          wi
# Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
# work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
# mode (the factory default). If you set the switches on your ISA
# card for a manually chosen I/O address and IRQ, you must specify
# those paremeters here.
device          an
# The probe order of these is presently determined by i386/isa/isa_compat.c.
device          ie0    at isa? port 0x300 irq 10 iomem 0xd0000
device          fe0    at isa? port 0x300
device          le0    at isa? port 0x300 irq 5 iomem 0xd0000
device          lnc0   at isa? port 0x280 irq 10 drq 0
device          cs0    at isa? port 0x300
device          sn0    at isa? port 0x300 irq 10
# requires PCCARD (PCMCIA) support to be activated
#device         xe0    at isa?</programlisting>

    <para>ISA ethernet drivers.  See
      <filename>/usr/src/sys/i386/conf/LINT</filename> for which cards are
      supported by which driver.</para>

    <programlisting>
# Pseudo devices - the number indicates how many units to allocated.
pseudo-device   loop          # Network loopback</programlisting>

    <para>This is the generic loopback device for TCP/IP.  If you telnet
      or FTP to <hostid>localhost</hostid> (a.k.a., <hostid
      role="ipaddr">127.0.0.1</hostid> it will come back at you through
      this pseudo-device.  This is <emphasis>mandatory</emphasis>.</para>

    <programlisting>
pseudo-device   ether         # Ethernet support</programlisting>

    <para><literal>ether</literal> is only needed if you have an Ethernet
      card.  It includes generic Ethernet protocol code.</para>

    <programlisting>
pseudo-device   sl      1     # Kernel SLIP</programlisting>

    <para><literal>sl</literal> is for SLIP support.  This has been almost
      entirely supplanted by PPP, which is easier to set up, better suited
      for modem-to-modem connection, and more powerful.  The
      <replaceable>number</replaceable> after <literal>sl</literal>
      specifies how many simultaneous SLIP sessions to support.</para>

    <programlisting>
pseudo-device   ppp     1     # Kernel PPP</programlisting>

    <para>This is for kernel PPP support for dial-up connections.  There
      is also a version of PPP implemented as a userland application that
      uses <literal>tun</literal> and offers more flexibility and features
      such as demand dialing.  The <replaceable>number</replaceable> after
      <literal>ppp</literal> specifies how many simultaneous PPP
      connections to support.</para>

    <programlisting>
pseudo-device   tun           # Packet tunnel.</programlisting>

    <para>This is used by the userland PPP software.  The
      <replaceable>number</replaceable> after <literal>tun</literal>
      specifies the number of simultaneous PPP sessions to support.  See
      the <link linkend="userppp">PPP</link> section of this book for more
      information.</para>

    <programlisting><anchor id="kernelconfig-ptys">
pseudo-device   pty           # Pseudo-ttys (telnet etc)</programlisting>

    <para>This is a <quote>pseudo-terminal</quote> or simulated login port.
      It is used by incoming <command>telnet</command> and
      <command>rlogin</command> sessions,
      <application>xterm</application>, and some other applications such
      as <application>emacs</application>.  The
      <replaceable>number</replaceable> indicates the number of
      <literal>pty</literal>s to create.  If you need more than the
      default of 16 simultaneous <application>xterm</application> windows
      and/or remote logins, be sure to increase this number accordingly,
      up to a maximum of 256.</para>

    <programlisting>
pseudo-device   md            # Memory <quote>disks</quote></programlisting>

    <para>Memory disk pseudo-devices.</para>

    <programlisting>
pseudo-device   gif     4     # IPv6 and IPv4 tunneling</programlisting>

    <para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6
      tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6
      tunneling.</para>

    <programlisting>
pseudo-device   faith   1     # IPv6-to-IPv4 relaying (translation)</programlisting>

    <para>This pseudo-device captures packets that are sent to it and
      diverts them to the IPv4/IPv6 translation daemon.</para>

    <programlisting>
# The `bpf' pseudo-device enables the Berkeley Packet Filter.
# Be aware of the administrative consequences of enabling this!
pseudo-device   bpf           # Berkeley packet filter</programlisting>

    <para>This is the Berkeley Packet Filter.  This pseudo-device allows
      network interfaces to be placed in promiscuous mode, capturing every
      packet on a broadcast network (e.g., an ethernet).  These packets
      can be captured to disk and or examined with the &man.tcpdump.1;
      program.</para>

    <programlisting>
# USB support
#device         uhci          # UHCI PCI-&gt;USB interface
#device         ohci          # OHCI PCI-&gt;USB interface
#device         usb           # USB Bus (required)
#device         ugen          # Generic
#device         uhid          # <quote>Human Interface Devices</quote>
#device         ukbd          # Keyboard
#device         ulpt          # Printer
#device         umass         # Disks/Mass storage - Requires scbus and da
#device         ums           # Mouse
# USB Ethernet, requires mii
#device         aue           # ADMtek USB ethernet
#device         cue           # CATC USB ethernet
#device         kue           # Kawasaki LSI USB ethernet</programlisting>

    <para>Support for various USB devices.</para>

    <para>For more information and additional devices supported by
      FreeBSD, see
      <filename>/usr/src/sys/i386/conf/LINT</filename>.</para>
  </sect1>

  <sect1 id="kernelconfig-nodes">
    <title>Making Device Nodes</title>

    <para>Almost every device in the kernel has a corresponding
      <quote>node</quote> entry in the <filename>/dev</filename> directory.
      These nodes look like regular files, but are actually special
      entries into the kernel which programs use to access the device.
      The shell script <filename>/dev/MAKEDEV</filename>, which is
      executed when you first install the operating system, creates
      nearly all of the device nodes supported.  However, it does not
      create <emphasis>all</emphasis> of them, so when you add support for
      a new device, it pays to make sure that the appropriate entries are
      in this directory, and if not, add them.  Here is a simple
      example:</para>

    <para>Suppose you add the IDE CD-ROM support to the kernel.  The line
      to add is:</para>

    <programlisting>
device acd0</programlisting>

    <para>This means that you should look for some entries that start with
      <filename>acd0</filename> in the <filename>/dev</filename>
      directory, possibly followed by a letter, such as
      <literal>c</literal>, or preceded by the letter
      <literal>r</literal>, which means a <quote>raw</quote> device.  It
      turns out that those files are not there, so I must change to the
      <filename>/dev</filename> directory and type:</para>

    <screen>&prompt.root; <userinput>sh MAKEDEV acd0</userinput></screen>

    <para>When this script finishes, you will find that there are now
      <filename>acd0c</filename> and <filename>racd0c</filename> entries
      in <filename>/dev</filename> so you know that it executed
      correctly.</para>

    <para>For sound cards, the following command creates the appropriate
      entries:</para>

    <screen>&prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen>

    <note>
      <para>When creating device nodes for devices such as sound cards, if
	other people have access to your machine, it may be desirable to
	protect the devices from outside access by adding them to the
	<filename>/etc/fbtab</filename> file.  See &man.fbtab.5; for more
	information.</para>
    </note>

    <para>Follow this simple procedure for any other
      non-<filename>GENERIC</filename>  devices which do not have
      entries.</para>

    <note>
      <para>All SCSI controllers use the same set of
	<filename>/dev</filename> entries, so you do not need to create
	these.  Also, network cards and SLIP/PPP pseudo-devices do not
	have entries in <filename>/dev</filename> at all, so you do not
	have to worry about these either.</para>
    </note>
  </sect1>

  <sect1 id="kernelconfig-trouble">
    <title>If Something Goes Wrong</title>

    <para>There are four categories of trouble that can occur when
      building a custom kernel.  They are:</para>

    <variablelist>
      <varlistentry>
	<term><command>config</command> fails</term>

	<listitem>
	  <para>If the <command>config</command> command fails when you
	    give it your kernel description, you have probably made a
	    simple error somewhere.  Fortunately,
	    <command>config</command> will print the line number that it
	    had trouble with, so you can quickly skip to it with
	    <command>vi</command>.  For example, if you see:</para>

	  <screen>config: line 17: syntax error</screen>

	  <para>You can skip to the problem in <command>vi</command> by
	    typing <command>17G</command> in command mode.  Make sure the
	    keyword is typed correctly, by comparing it to the
	    <filename>GENERIC</filename> kernel or another
	    reference.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>make</command> fails</term>

	<listitem>
	  <para>If the <command>make</command> command fails, it usually
	    signals an error in your kernel description, but not severe
	    enough for <command>config</command> to catch it.  Again, look
	    over your configuration, and if you still cannot resolve the
	    problem, send mail to the &a.questions; with your kernel
	    configuration, and it should be diagnosed very quickly.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>The kernel will not boot<anchor
	  id="kernelconfig-noboot"></term>

	<listitem>
	  <para>If your new kernel does not boot, or fails to recognize
	    your devices, do not panic!  Fortunately, BSD has an excellent
	    mechanism for recovering from incompatible kernels.  Simply
	    choose the kernel you want to boot from at the FreeBSD boot
	    loader (i.e.,
	    <command>boot <filename>kernel.old</filename></command>).
	    When reconfiguring a kernel, it is always a good idea to keep
	    a kernel that is known to work on hand.</para>

	  <para>After booting with a good kernel you can check over your
	    configuration file and try to build it again.  One helpful
	    resource is the <filename>/var/log/messages</filename> file
	    which records, among other things, all of the kernel messages
	    from every successful boot.  Also, the &man.dmesg.8; command
	    will print the kernel messages from the current boot.</para>

	  <note>
	    <para>If you are having trouble building a kernel, make sure
	      to keep a <filename>GENERIC</filename>, or some other kernel
	      that is known to work on hand as a different name that will
	      not get erased on the next build.  You cannot rely on
	      <filename>kernel.old</filename> because when installing a
	      new kernel, <filename>kernel.old</filename> is overwritten
	      with the last installed kernel which may be non-functional.
	      Also, as soon as possible, move the working kernel to the
	      proper <filename>kernel</filename> location or commands such
	      as &man.ps.1; will not work properly.  The proper command to
	      <quote>unlock</quote> the kernel file that
	      <command>make</command> installs (in order to move another
	      kernel back permanently) is:</para>

	    <screen>&prompt.root; <userinput>chflags noschg /kernel</userinput></screen>
		    
	    <para>And, if you want to <quote>lock</quote> your new kernel
	      into place, or any file for that matter, so that it cannot
	      be moved or tampered with:</para>

	    <screen>&prompt.root; <userinput>chflags schg /kernel</userinput></screen>
	  </note>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>The kernel works, but <command>ps</command> does not work
	  any more!</term>

	<listitem>
	  <para>If you have installed a different version of the kernel
	    from the one that the system utilities have been built with,
	    for example, a 4.X kernel on a 3.X system, many system-status
	    commands like &man.ps.1; and &man.vmstat.8; will not work any
	    more.  You must recompile the <filename>libkvm</filename>
	    library as well as these utilities.  This is one reason it is
	    not normally a good idea to use a different version of the
	    kernel from the rest of the operating system.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>
</chapter>

<!-- 
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->