path: root/handbook/kernelconfig.sgml
diff options
Diffstat (limited to 'handbook/kernelconfig.sgml')
1 files changed, 1206 insertions, 0 deletions
diff --git a/handbook/kernelconfig.sgml b/handbook/kernelconfig.sgml
new file mode 100644
index 0000000000..a565ee4957
--- /dev/null
+++ b/handbook/kernelconfig.sgml
@@ -0,0 +1,1206 @@
+<!-- $Id: kernelconfig.sgml,v 1.1 1995-10-07 04:31:31 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+<!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> -->
+ <chapt><heading>Configuring the FreeBSD Kernel<label id="kernelconfig"></heading>
+ <p><em>Contributed by &a.jehamby;.<newline>6 October 1995.</em>
+ This large section of the handbook discusses the basics of
+ building your own custom kernel for FreeBSD. This section
+ is appropriate for both novice system administrators and
+ those with advanced Unix experience.
+ <sect><heading>Why build a custom kernel?</heading>
+ <p>Building a custom kernel is one of the most important
+ rites of passage every Unix system administrator must
+ learn. This process, while time-consuming, will provide
+ many benefits to your FreeBSD system. Unlike the GENERIC
+ kernel, which must support every possible SCSI and
+ network card, along with tons of other rarely used
+ hardware support, a custom kernel only contains support
+ for <em>your</em> PC's hardware. This has a number of
+ benefits:
+ <itemize>
+ <item>It will take less time to boot because it does not
+ have to spend time probing for hardware which you
+ do not have.
+ <item>A custom kernel often uses less memory, which is
+ important because the kernel is the one process which
+ must always be present in memory, and so all of that
+ unused code ties up pages of RAM that your programs
+ would otherwise be able to use. Therefore, on a
+ system with limited RAM, building a custom kernel is
+ of critical importance.
+ <item>Finally, there are several kernel options which
+ you can tune to fit your needs, and device driver
+ support for things like sound cards which you can
+ include in your kernel but are <em>not</em> present
+ in the GENERIC kernel.
+ </itemize></p>
+ <sect><heading>Building and Installing a Custom Kernel</heading>
+ <p>First, let us take a quick tour of the kernel build
+ directory. All directories mentioned will be relative to
+ the main <tt>/usr/src/sys</tt> directory, which is also
+ accessible through <tt>/sys</tt>. There are a number of
+ subdirectories here representing different parts of the
+ kernel, but the most important, for our purposes, are
+ <tt>i386/conf</tt>, where you will edit your custom
+ kernel configuration, and <tt>compile</tt>, which is the
+ staging area where your kernel will be built. Notice the
+ logical organization of the directory tree, with each
+ supported device, filesystem, and option in its own
+ subdirectory. Also, anything inside the <tt>i386</tt>
+ directory deals with PC hardware only, while everything
+ outside the <tt>i386</tt> directory is common to all
+ platforms which FreeBSD could potentially be ported to.
+ <quote><em/Note:/ If there is <em>not</em> a
+ <tt>/usr/src/sys</tt> directory on your system, then the
+ kernel source has not been been installed. Follow the
+ instructions for installing packages to add this package
+ to your system.</quote>
+ Next, move to the <tt>i386/conf</tt> directory and copy
+ the GENERIC configuration file to the name you want to
+ give your kernel. For example:
+# cd /usr/src/sys/i386/conf
+ Traditionally, this name is in all capital letters and,
+ if you are maintaining multiple FreeBSD machines with
+ different hardware, it's a good idea to name it after
+ your machine's hostname. We will call it MYKERNEL for
+ the purpose of this example.
+ <quote><em/Note:/ You must execute these and all of the
+ following commands under the root account or you will get
+ ``permission denied'' errors.</quote>
+ Now, edit MYKERNEL with your favorite text editor. If
+ you're just starting out, the only editor available will
+ probably be <tt>vi</tt>, which is too complex to explain
+ here, but is covered well in many books in the <ref
+ id="bibliography" name="bibliography">. Feel free to change the comment
+ lines at the top to reflect your configuration or the
+ changes you've made to differentiate it from GENERIC.
+ If you've build a kernel under SunOS or some other BSD
+ operating system, much of this file will be very familiar
+ to you. If you're coming from some other operating
+ system such as DOS, on the other hand, the GENERIC
+ configuration file might seem overwhelming to you, so
+ follow the descriptions in the <ref
+ id="kernelconfig:config" name="Configuration File">
+ section slowly and carefully.
+ When you're finished, type the following to compile and
+ install your kernel:
+# /usr/sbin/config MYKERNEL
+# cd ../../compile/MYKERNEL
+# make
+# make install
+ The new kernel will be copied to the root directory as
+ <tt>/kernel</tt> and the old kernel will be moved to
+ <tt>/kernel.old</tt>. Now, shutdown the system and
+ reboot to use your kernel. In case something goes wrong,
+ there are some <ref id="kernelconfig:trouble" name=
+ "troubleshooting"> instructions at the end of this
+ document. Be sure to read the section which explains how
+ to recover in case your new kernel <ref
+ id="kernelconfig:noboot" name="does not boot">.
+ <quote><em/Note:/ If you've added any new devices (such
+ as sound cards) you may have to add some <ref
+ id="kernelconfig:nodes" name="device nodes"> to your
+ <tt>/dev</tt> directory before you can use them.</quote>
+ <sect><heading>The Configuration File<label id="kernelconfig:config"></heading>
+ <p>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 <tt>#</tt> is considered
+ a comment and ignored. The following sections describe
+ each keyword, generally in the order they are listed in
+ GENERIC, although some related keywords have been grouped
+ together in a single section (such as Networking) even
+ though they are actually scattered throughout the GENERIC
+ file. An exhaustive list of options is present in the
+ LINT configuration file, located in the same directory as
+ <sect1><heading>Mandatory Keywords</heading>
+ <p>These keywords are required in every kernel you build.
+ <descrip>
+ <tag>machine ``i386''</tag>
+ <p>The first keyword is <tt>machine</tt>, which,
+ since FreeBSD only runs on Intel 386 and compatible
+ chips, is i386.
+ <quote><em>Note:</em> that any keyword which
+ contains numbers used as text must be enclosed in
+ quotation marks, otherwise <tt>config</tt> gets
+ confused and thinks you mean the actual number
+ 386.</quote>
+ <tag>cpu ``<em>cpu_type</em>''</tag>
+ <p>The next keyword is <tt>cpu</tt>, which includes
+ support for each CPU supported by FreeBSD. The
+ possible values of <tt><em>cpu_type</em></tt>
+ include:
+ <itemize>
+ <item>I386_CPU
+ <item>I486_CPU
+ <item>I586_CPU
+ </itemize>
+ and multiple instances of the <tt>cpu</tt> line may
+ be present with different values of
+ <tt><em>cpu_type</em></tt> as are present in the
+ GENERIC kernel. For a custom kernel, it is best to
+ specify only the cpu you have. If, for example,
+ you have an Intel Pentium, use <tt>I586_CPU</tt>
+ for <tt><em>cpu_type</em></tt>.
+ <tag>ident <em>machine_name</em></tag>
+ <p>Next, we have <tt>ident</tt>, which is the
+ identification of the kernel. You should change
+ this from GENERIC to whatever you named your
+ kernel, in this example, MYKERNEL. The value you
+ put in <tt>ident</tt> will print when you boot up
+ the kernel, so it's useful to give a kernel a
+ different name if you want to keep it separate from
+ your usual kernel (if you want to build an
+ experimental kernel, for example). Note that, as
+ with <tt>machine</tt> and <tt> cpu</tt>, enclose
+ your kernel's name in quotation marks if it
+ contains any numbers.
+ <tag>maxusers <em>number</em></tag>
+ <p>This file 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
+ <tt>maxusers</tt> to at least four, especially if
+ you're using X Windows or compiling software. The
+ reason is that the most important table set by
+ <tt>maxusers</tt> is the maximum number of
+ processes, which is set to <bf><tt>20 + 16 *
+ maxusers</tt></bf>, so if you set <tt>maxusers</tt>
+ to one, 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 X Windows. Even a
+ simple task like reading a <tt>man</tt> page will
+ start up nine processes to filter, decompress, and
+ view it. Setting <tt>maxusers</tt> to 4 will allow
+ you to have up to 84 simultaneous processes, which
+ should be enough for anyone. If, however, you see
+ the dreaded ``proc table full'' error when trying
+ to start another program, or are running a server
+ with a large number of simultaneous users (like
+ Walnut Creek CDROM's FTP site!), you can always
+ increase this number and rebuild.
+ <quote><em/Note:/ <tt>maxuser</tt> does
+ <em>not</em> 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
+ <em>does</em> limit the number of simultaneous
+ <em>remote logins</em> is <ref
+ id="kernelconfig:ptys" name="pseudo-device pty
+ 16">.</quote>
+ <tag>config <em>kernel_name</em> root on <em>root_device</em></tag>
+ <p>This line specifies the location and name of the
+ kernel. Traditionally the kernel is called
+ <tt>vmunix</tt> but in FreeBSD, it is aptly named
+ <tt>kernel</tt>. You should always use
+ <tt>kernel</tt> for <em>kernel_name</em> because
+ changing it will render numerous system utilities
+ inoperative. The second part of the line specifies
+ the disk and partition where the root filesystem
+ and kernel can be found. Typically this will be
+ <tt>wd0</tt> for systems with non-SCSI drives, or
+ <tt>sd0</tt> for systems with SCSI drives.
+ </descrip>
+ <sect1><heading>General Options</heading>
+ <p>These lines provide kernel support for various
+ filesystems and other options.
+ <descrip>
+ <label id="kernelconfig:mathemu">
+ <tag>options MATH_EMULATE</tag>
+ <p>This line allows the kernel to simulate a math
+ coprocessor if your computer does not have one (386
+ or 486SX). If you have a Pentium, a 486DX, or a
+ 386 or 486SX with a separate 387 or 487 chip, you
+ can comment this line out.
+ <quote><em>Note:</em> The normal math coprocessor
+ emulation routines that come with FreeBSD are
+ <em>not</em> very accurate. If you do not have a
+ math coprocessor, and you need the best accuracy,
+ I recommend that you change this option to
+ <tt>GPL_MATH_EMULATE</tt> to use the superior GNU
+ math support, which is not included by default
+ for licensing reasons.</quote>
+ <tag>options ``COMPAT_43''</tag>
+ <p>Compatibility with BSD 4.3. Leave this in; some
+ programs will act strangely if you comment this
+ out.
+ <tag>options BOUNCE_BUFFERS</tag>
+ <p>ISA devices and EISA devices operating in an ISA
+ compatibilty mode can only perform DMA (Direct
+ Memory Access) to memory below 16 megabytes. This
+ option enables such devices to work in systems with
+ more than 16 megabytes of memory.
+ <tag>options UCONSOLE</tag>
+ <p>Allow users to grab the console, useful for X
+ Windows. For example, you can create a console
+ xterm by typing <tt>xterm -C</tt>, which will
+ display any `write', `talk', and other messages you
+ receive.
+ <tag>options SYSVSHM</tag>
+ <p>This option
+ provides for System V shared memory. The most
+ common use of this is the XSHM extension in X
+ Windows, which many graphics-intensive programs
+ (such as the movie player XAnim, and Linux DOOM)
+ will automatically take advantage of for extra
+ speed. If you use X Windows, you'll definitely
+ want to include this.
+ <tag>options SYSVSEM</tag>
+ <p>Support for System V
+ semaphores. Less commonly used but only adds a few
+ hundred bytes to the kernel.
+ <tag>options SYSVMSG</tag>
+ <p>Support for System V
+ messages. Again, only adds a few hundred bytes to
+ the kernel.
+ <quote><em/Note:/ The <tt>ipcs(1)</tt> command will
+ tell will list any processes using using each of
+ these System V facilities.</quote>
+ </descrip>
+ <sect1><heading>Filesystem Options</heading>
+ <p>These options add support for various filesystems.
+ You must include at least one of these to support the
+ device you boot from; typically this will be
+ <tt>FFS</tt> if you boot from a hard drive, or
+ <tt>NFS</tt> if you are booting a diskless workstation
+ from Ethernet. You can include other commonly-used
+ filesystems in the kernel, but feel free to comment out
+ support for filesystems you use less often (perhaps the
+ MS-DOS filesystem?), since they will be dynamically
+ loaded from the Loadable Kernel Module directory
+ <tt>/lkm</tt> the first time you mount a partition of
+ that type.
+ <descrip>
+ <tag>options FFS</tag>
+ <p>The basic hard drive
+ filesystem; leave it in if you boot from the hard
+ disk.
+ <tag>options NFS</tag>
+ <p>Network Filesystem. Unless
+ you plan to mount partitions from a Unix file
+ server over Ethernet, you can comment this out.
+ <tag>options MSDOSFS</tag>
+ <p>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 <tt>mtools</tt> software (in
+ the ports collection) allows you to access DOS
+ floppies without having to mount and unmount them
+ (and does not require MSDOSFS at all).
+ <tag>options ``CD9660''</tag>
+ <p>ISO 9660 filesystem for
+ CD-ROMs. Comment it out if you do not have a
+ CD-ROM drive or only mount data CD's occasionally
+ (since it will be dynamically loaded the first time
+ you mount a data CD). Audio CD's do not need this
+ filesystem.
+ <tag>options PROCFS</tag>
+ <p>Process filesystem. This
+ is a pretend filesystem mounted on /proc which
+ allows programs like <tt>ps(1)</tt> to give you
+ more information on what processes are running.
+ Leave it in.
+ <tag>options MFS</tag>
+ <p>Memory-mapped file system.
+ 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
+ <tt>/tmp</tt> directory, since many programs store
+ temporary data here. To mount an MFS RAM disk on
+ <tt>/tmp</tt>, add the following line to
+ <tt>/etc/fstab</tt> and then reboot or type
+ <tt>mount /tmp</tt>:
+/dev/wd1s2b /tmp mfs rw 0 0
+ <quote><em/Note:/ Replace the <tt>/dev/wd1s2b</tt>
+ with the name of your swap partition, which will
+ be listed in your <tt>/etc/fstab</tt> as follows:
+/dev/wd1s2b none swap sw 0 0
+ </quote>
+ <quote><em/Note:/ <!-- MFS is currently a bit
+ limited (for example, I noticed that two programs
+ ca not access the <tt>/tmp</tt> device
+ simultaneously). As such, you may want to avoid
+ it for now. --> Also, the <tt>MFS</tt> filesystem
+ can <em>not</em> be dynamically loaded, so you
+ <em>must</em> compile it into your kernel if you
+ want to experiment with it.</quote>
+ <tag>options QUOTA</tag>
+ <p>Enable disk quotas. If you
+ have a public access system, and do not want users
+ to be able to overflow the <tt>/home</tt>
+ partition, you can establish disk quotas for each
+ user. This code is a little buggy, so do not
+ enable it unless you have to. View the manual page
+ for <tt>quota(1)</tt> to learn more about disk
+ quotas.
+ </descrip>
+ <sect1><heading>Basic Controllers and Devices</heading>
+ <p>These sections describe the basic disk, tape, and
+ CD-ROM controllers supported by FreeBSD. There are
+ separate sections for <ref id="kernelconfig:scsi"
+ name="SCSI"> controllers and <ref
+ id="kernelconfig:network" name="network"> cards.
+ <descrip>
+ <tag>controller isa0</tag>
+ <p>All PC's supported by
+ FreeBSD have one of these. If you have an IBM PS/2
+ (Micro Channel Architecture), then you cannot run
+ FreeBSD at this time.
+ <tag>controller pci0</tag>
+ <p>Include this if you have a
+ PCI motherboard. This enables auto-detection of
+ PCI cards and gatewaying from the PCI to the ISA
+ bus.
+ <tag>controller fdc0</tag>
+ <p>Floppy drive controller:
+ <tt>fd0</tt> is the ``A:'' floppy drive, and
+ <tt>fd1</tt> is the ``B:'' drive. <tt>ft0</tt> is
+ a QIC-80 tape drive attached to the floppy
+ controller. Comment out any lines corresponding to
+ devices you do not have.
+ <quote><em/Note:/ QIC-80 tape support requires a
+ separate filter program called <tt>ft(8)</tt>, see
+ the manual page for details.</quote>
+ <tag>controller wdc0</tag>
+ <p>This is the primary IDE
+ controller. <tt>wd0</tt> and <tt>wd1</tt> are the
+ master and slave hard drive, respectively.
+ <tt>wdc1</tt> is a secondary IDE controller where
+ you might have a third or fourth hard drive, or an
+ IDE CD-ROM. Comment out the lines which do not
+ apply (if you have a SCSI hard drive, you'll
+ probably want to comment out all six lines, for
+ example).
+ <tag>controller wcd0<label id="kernelconfig:atapi"></tag>
+ <p>This device
+ provides IDE CD-ROM support. Be sure to leave
+ <tt>wdc1</tt> uncommented if your CD-ROM is on
+ its own controller card. To use this, you must
+ also include the line <tt>options ATAPI</tt>.
+ <tag>device npx0 at isa? port ``IO_NPX'' irq 13 vector npxintr</tag>
+ <p><tt>npx0</tt> is the interface to the
+ math coprocessor. If you have one then make sure
+ you've commented out <ref id="kernelconfig:mathemu"
+ name="MATH_EMULATE"> above. If you do not have a
+ math coprocessor, you can comment this out.
+ <tag>device wt0 at isa? port 0x300 bio irq 5 drq 1 vector wtintr</tag>
+ <p>Wangtek and Archive
+ QIC-02/QIC-36 tape drive support
+ <tag>Proprietary CD-ROM support</tag>
+ <p>The following
+ drivers are for the so-called <em>proprietary</em>
+ CD-ROM drives. These drives have their own
+ controller card or might plug into a sound card
+ such as the Soundblaster 16. They are <em>not</em>
+ IDE or SCSI. Most older single-speed and
+ double-speed CD-ROMs use these interfaces, while
+ newer quad-speeds are likely to be <ref
+ id="kernelconfig:atapi" name="IDE"> or <ref
+ id="kernelconfig:scsi" name="SCSI">.
+ <descrip>
+ <tag>device mcd0 at isa? port 0x300 bio irq 10 vector mcdintr</tag>
+ <p>Mitsumi CD-ROM (LU002,
+ LU005, FX001D).
+ <tag>device scd0 at isa? port 0x230 bio</tag>
+ <p>Sony CD-ROM (CDU31, CDU33A).
+ <tag>controller matcd0 at isa? port ? bio</tag>
+ <p>Matsushita/Panasonic CD-ROM (sold by Creative
+ Labs for Soundblaster).
+ </descrip>
+ </descrip>
+ <sect1><heading>SCSI Device Support<label id="kernelconfig:scsi"></heading>
+ <p>This section describes the various SCSI controllers
+ and devices supported by FreeBSD.
+ <descrip>
+ <tag>SCSI Controllers</tag>
+ <p>The next ten or so lines include support for
+ different kinds of SCSI controllers. Comment out
+ all except for the one(s) you have:
+ <descrip>
+ <tag>controller bt0 at isa? port ``IO_BT0'' bio irq ? vector btintr</tag>
+ <p>Most Buslogic controllers
+ <tag>controller uha0 at isa? port ``IO_UHA0'' bio irq ? drq 5 vector uhaintr</tag>
+ <p>UltraStor 14F and 34F
+ <tag>controller ahc0</tag>
+ <p>Adaptec 274x/284x/294x
+ <tag>controller ahb0 at isa? bio irq ? vector ahbintr</tag>
+ <p>Adaptec 174x
+ <tag>controller aha0 at isa? port ``IO_AHA0'' bio irq ? drq 5 vector ahaintr</tag>
+ <p>Adaptec 154x
+ <tag>controller aic0 at isa? port 0x340 bio irq 11 vector aicintr
+ <p>Adaptec 152x and sound cards using Adaptec AIC-6360 (slow!)
+ <tag>controller nca0 at isa? port 0x1f88 bio irq 10 vector ncaintr
+ <p>ProAudioSpectrum cards using NCR 5380 or Trantor T130
+ <tag>controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr</tag>
+ <p>Seagate ST01/02 8 bit controller (slow!)
+ <tag>controller wds0 at isa? port 0x350 bio irq 15 drq 6 vector wdsintr</tag>
+ <p>Western Digital WD7000 controller
+ <tag>controller ncr0</tag>
+ <p>NCR 53C810 and 53C825 PCI SCSI controller
+ </descrip>
+ <tag>options ``SCSI_DELAY=15''</tag>
+ <p>This causes the
+ kernel to pause 15 seconds before probing each SCSI
+ device in your system. If you only have IDE hard
+ drives, you can ignore this, otherwise you'll
+ 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'll have to raise it back up.
+ <tag>controller scbus0</tag>
+ <p>If you have any SCSI
+ controllers, this line provides generic SCSI
+ support. If you do not have SCSI, you can comment
+ this, and the following three lines, out.
+ <tag>device sd0</tag>
+ <p>Support for SCSI hard
+ drives.
+ <tag>device st0</tag>
+ <p>Support for SCSI tape
+ drives.
+ <tag>device cd0</tag>
+ <p>Support for SCSI CD-ROM
+ drives.
+ </descrip>
+ <sect1><heading>Console, Bus Mouse, and X Server Support</heading>
+ <p>You must choose one of these two console types, and, if you plan
+ to use X Windows, enable the XSERVER option and optionally, a bus
+ mouse or PS/2 mouse device.
+ <descrip>
+ <tag>device sc0 at isa? port ``IO_KBD' tty irq 1 vector scintr</tag>
+ <p><tt>sc0</tt> is the default
+ console driver, which resembles an SCO console.
+ Since most full-screen programs access the console
+ through a terminal database library like
+ <em>termcap</em>, it should not matter much whether
+ you use this or <tt>vt0</tt>, the VT220 compatible
+ console driver. When you log in, set your TERM
+ variable to ``scoansi'' if full-screen programs
+ have trouble running under this console.
+ <tag>device vt0 at isa? port ``IO_KBD'' tty irq 1 vector pcrint</tag>
+ <p>This is a VT220-compatible
+ console driver, backwards compatible to VT100/102.
+ It works well on some laptops which have hardware
+ incompatibilities with <tt>sc0</tt>. Also, set
+ your TERM variable to ``vt220'' when you log in if
+ full-screen programs do not run correctly on this
+ console.
+ <descrip>
+ <tag>options ``PCVT_FREEBSD=210''</tag>
+ <p>Required
+ with the <tt>vt0</tt> console driver.
+ <tag>options XSERVER</tag>
+ <p>This includes code
+ required to run the <tt>XFree86</tt> X Window
+ Server.
+ </descrip>
+ <tag>device mse0 at isa? port 0x23c tty irq 5 vector ms</tag>
+ <p>Use this device if you have a Logitech or
+ ATI InPort bus mouse card.
+ <quote><em/Note:/ If you have a serial mouse,
+ ignore these two lines, and instead, make sure
+ the appropriate <ref id="kernelconfig:serial"
+ name="serial"> port is enabled (probably
+ COM1).</quote>
+ <tag>device psm0 at isa? port ``IO_KBD'' conflicts tty irq 12 vector psmintr</tag>
+ <p>Use this device if your
+ mouse plugs into the PS/2 mouse port.
+ </descrip>
+ <sect1><heading>Serial and Parallel Ports</heading>
+ <p>Nearly all systems have these. If you are attaching a
+ printer to one of these ports, the <ref id="printing"
+ name="Printing"> section of the handbook is very
+ useful. If you are using modem, <ref id="dialup"
+ name="Dialup access"> provides extensive detail on
+ serial port configuration for use with such devices.
+ <descrip>
+ <tag>device sio0 at isa? port ``IO_COM1'' tty irq 4 vector siointr<label id="kernelconfig:serial"></tag>
+ <p><tt>sio0</tt>
+ through <tt>sio3</tt> are the four serial ports
+ referred to as COM1 through COM4 in the MS-DOS
+ world. Note that 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 IRQ 2 = IRQ 9) in order to access
+ it from FreeBSD. If you have a multiport serial
+ card, check the manual page for <tt>sio(4)</tt> for
+ more information on the proper values for these
+ lines.
+ <tag>device lpt0 at isa? port? tty irq 7 vector lptintr</tag>
+ <p><tt>lpt0</tt> through <tt>lpt2</tt>
+ are the three printer ports you could conceivably
+ have. Most people just have one, though, so feel
+ free to comment out the other two lines if you do
+ not have them.
+ </descrip>
+ <sect1><heading>Networking<label id="kernelconfig:network"></heading>
+ <p>FreeBSD, as with Unix in general, places a
+ <em>big</em> emphasis on networking. Therefore, even
+ if you do not have an Ethernet card, pay attention to
+ the mandatory options and the dial-up networking
+ support.
+ <descrip>
+ <tag>options INET</tag>
+ Networking support. Leave it 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.
+ <tag>Ethernet cards</tag>
+ <p>The next lines enable support for various Ethernet
+ cards. If you do not have a network card, you can
+ comment out all of these lines. Otherwise, you'll
+ want to leave in support for your particular
+ Ethernet card(s):
+ <descrip>
+ <tag>device de0</tag>
+ <p>Digital Equipment DC21040 PCI Ethernet adapter
+ <tag>device cx0 at isa? port 0x240 net irq 15 drq 7 vector cxintr</tag>
+ <p>Cronyx/Sigma multiport
+ sync/async (with Cisco or PPP framing)
+ <tag>device ed0 at isa? port 0x280 net irq 5 iomem 0xd8000 vector edintr</tag>
+ <p>Western Digital and SMC 80xx; Novell NE1000
+ and NE2000; 3Com 3C503
+ <tag>device el0 at isa? port 0x300 net irq 9 vector elintr</tag>
+ <p>3Com 3C501 (slow!)
+ <tag>device eg0 at isa? port 0x310 net irq 5 vector egintr</tag>
+ <p>3Com 3C505
+ <tag>device ep0 at isa? port 0x300 net irq 10 vector epintr</tag>
+ <p>3Com 3C509 (buggy)
+ <tag>device fe0 at isa? port 0x240 net irq ? vector feintr</tag>
+ <p>Fujitsu MB86960A/MB86965A Ethernet
+ <tag>device fea0 at isa? net irq ? vector feaintr</tag>
+ <p>DEC DEFEA EISA FDDI adapter
+ <tag>device ie0 at isa? port 0x360 net irq 7 iomem 0xd0000 vector ieintr</tag>
+ <p>AT&amp;T StarLAN 10 and EN100; 3Com 3C507;
+ unknown NI5210
+ <tag>device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixintr</tag>
+ <p>Intel EtherExpress 16
+ <tag>device le0 at isa? port 0x300 net irq 5 iomem 0xd0000 vector le_intr</tag>
+ <p>Digital Equipment EtherWorks 2 and EtherWorks
+ 3 (DEPCA, DE100, DE101, DE200, DE201, DE202,
+ DE203, DE204, DE205, DE422)
+ <tag>device lnc0 at isa? port 0x300 net irq 10 drq 0 vector lncintr</tag>
+ <p>Lance/PCnet cards (Isolan, Novell NE2100,
+ NE32-VL)
+ <tag>device ze0 at isa? port 0x300 net irq 5 iomem 0xd8000 vector zeintr</tag>
+ <p>IBM/National Semiconductor PCMCIA ethernet
+ controller.
+ <tag>device zp0 at isa? port 0x300 net irq 10 iomem 0xd8000 vector zpintr</tag>
+ <p>3Com PCMCIA Etherlink III
+ </descrip>
+ <quote><em/Note:/ With certain cards (notably the
+ NE2000) you'll have to change the port and/or IRQ
+ since there is no ``standard'' location for these
+ cards.</quote>
+ <tag>pseudo-device loop</tag>
+ <p><tt>loop</tt> is the
+ generic loopback device for TCP/IP. If you telnet
+ or FTP to <em>localhost</em>
+ (a.k.a. <tt></tt>) it will come back at
+ you through this pseudo-device. Mandatory.
+ <tag>pseudo-device ether</tag>
+ <p><tt>ether</tt> is only
+ needed if you have an Ethernet card and includes
+ generic Ethernet protocol code.
+ <tag>pseudo-device sl <em>number</em></tag>
+ <p><tt>sl</tt> is for SLIP (Serial Line Internet
+ Protocol) support. This has been almost entirely
+ supplanted by PPP, which is easier to set up,
+ better suited for modem-to-modem connections, as
+ well as more powerful. The <em>number</em> after
+ <tt>sl</tt> specifies how many simultaneous SLIP
+ sessions to support. This handbook has more
+ information on setting up a SLIP <ref id="slipc"
+ name="client"> or <ref id="slips" name="server">.
+ <tag>pseudo-device ppp <em>number</em></tag>
+ <p><tt>ppp</tt> is for kernel-mode PPP (Point-to-Point
+ Protocol) support for dial-up Internet connections.
+ There is also version of PPP implemented as a user
+ application that uses the <tt>tun</tt> and offers
+ more flexibility and features such as demand
+ dialing. If you still want to use this PPP driver,
+ read the <ref id="ppp" name="kernel-mode PPP">
+ section of the handbook. As with the <tt>sl</tt>
+ device, <em>number</em> specifies how many
+ simultaneous PPP connections to support.
+ <tag>pseudo-device tun <em>number</em></tag>
+ <p><tt>tun</tt> is used by the user-mode PPP software.
+ This program is easy to set up and very fast. It
+ also has special features such as automatic
+ dial-on-demand. The number after <tt>tun</tt>
+ specifies the number of simultaneous PPP sessions
+ to support. See the <ref id="userppp"
+ name="user-mode PPP"> section of the handbook for
+ more information.
+ <tag>pseudo-device bpfilter <em>number</em></tag>
+ <p>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
+ <tt>tcpdump(1)</tt> program. Note that
+ implementation of this capability can seriously
+ compromise your overall network security.
+ The <em>number</em> after bpfilter is the number of
+ interfaces that can be examined
+ simultaneously. Optional, not recommended except
+ for those who are fully aware of the potential
+ pitfalls. Not all network cards support this
+ capability.
+ </descrip>
+ <sect1><heading>Sound cards</heading>
+ <p>This is the first section containing lines that are
+ not in the GENERIC kernel. To include sound card
+ support, you'll have to copy the appropriate lines from
+ the LINT kernel (which contains support for
+ <em>every</em> device) as follows:
+ <descrip>
+ <tag>controller snd0</tag>
+ <p>Generic sound driver code.
+ Required for all of the following sound cards
+ except <tt>pca</tt>.
+ <tag>device pas0 at isa? port 0x388 irq 10 drq 6 vector pasintr</tag>
+ <p>ProAudioSpectrum digital audio and MIDI.
+ <tag>device sb0 at isa? port 0x220 irq 7 conflicts drq 1 vector sbintr</tag>
+ <p>SoundBlaster digital audio.
+ <quote><em/Note:/ If your Soundblaster is on a
+ different IRQ (such as 5), change <tt>irq 7</tt>
+ to, for example, <tt>irq 5</tt> and remove the
+ <tt>conflicts</tt> keyword. Also, you must add
+ the line: <tt>options ``SBC_IRQ=5''</tt></quote>
+ <tag>device sbxvi0 at isa? drq 5</tag>
+ <p>SoundBlaster 16 digital 16-bit audio.
+ <quote><em/Note:/ If your SB16 is on a different
+ 16-bit DMA channel (such as 6 or 7), change the
+ <tt>drq 5</tt> keyword appropriately, and then
+ add the line: <tt>options
+ "SB16_DMA=6"</tt></quote>
+ <tag>device sbmidi0 at isa? port 0x330</tag>
+ <p>SoundBlaster 16 MIDI interface. If you have a
+ SoundBlaster 16, you must include this line, or the
+ kernel will not compile.
+ <tag>device gus0 at isa? port 0x220 irq 10 drq 1 vector gusintr</tag>
+ <p>Gravis Ultrasound.
+ <tag>device mss0 at isa? port 0x530 irq 10 drq 1 vector adintr</tag>
+ <p>Microsoft Sound System.
+ <tag>device opl0 at isa? port 0x388 conflicts</tag>
+ <p>AdLib FM-synthesis audio. Include this line for
+ AdLib, SoundBlaster, and ProAudioSpectrum users, if
+ you want to play MIDI songs with a program such as
+ <tt>playmidi</tt> (in the ports collection).
+ <tag>device mpu0 at isa? port 0x330 irq 6 drq 0</tag>
+ <p>Roland MPU-401 stand-alone card.
+ <tag>device uart0 at isa? port 0x330 irq 5 vector ``m6850intr''</tag>
+ <p>Stand-alone 6850 UART for MIDI.
+ <tag>device pca0 at isa? port ``IO_TIMER1'' tty</tag>
+ <p>Digital audio through PC speaker. This is going to
+ be very poor sound quality and quite CPU-intensive,
+ so you have been warned (but it does not require a
+ sound card)!
+ </descrip>
+ <quote><em/Note:/ There is some additional
+ documentation in
+ <tt>/usr/src/sys/i386/isa/sound/sound.doc</tt>.
+ Also, if you add any of these devices, be sure to
+ create the sound <ref id="kernelconfig:nodes"
+ name="device nodes">.</quote>
+ <sect1><heading>Pseudo-devices</heading>
+ <p>Pseudo-device drivers are parts of the kernel that act
+ like device drivers but do not correspond to any actual
+ hardware in the machine. The <ref
+ id="kernelconfig:network" name="network-related">
+ pseudo-devices are in that section, while the remainder
+ are here.
+ <descrip>
+ <tag>pseudo-device gzip</tag>
+ <p><tt>gzip</tt> allows you to run FreeBSD programs
+ that have been compressed with <tt>gzip</tt>. This
+ is really only useful when you need to compress
+ FreeBSD programs to fit on a boot floppy. You will
+ probably never need to compress programs on your
+ hard drive in this fashion, so you'll probably want
+ to comment out this line.
+ <tag>pseudo-device log</tag>
+ <p><tt>log</tt> is used for logging of kernel error
+ messages. Mandatory.
+ <tag>pseudo-device pty <em>number</em><label id="kernelconfig:ptys"></tag>
+ <p><tt>pty</tt> is a ``pseudo-terminal'' or simulated
+ login port. It's used by incoming <bf>telnet</bf>
+ and <bf>rlogin</bf> sessions, xterm, and some other
+ applications such as emacs. The <em>number</em>
+ indicates the number of <tt>pty</tt>s to create.
+ If you need more than GENERIC default of 16
+ simultaneous xterm windows and/or remote logins, be
+ sure to increase this number accordingly, up to a
+ maximum of 64.
+ <tag>pseudo-device snp <em>number</em></tag>
+ <p>Snoop device. This pseudo-device allows one
+ terminal session to watch another using the
+ <tt>watch(8)</tt> command. Note that
+ implementation of this capability has important
+ security and privacy implications. The
+ <em>number</em> after snp is the total number of
+ simultaneous snoop sessions. Optional.
+ <tag>pseudo-device vn</tag>
+ <p>Vnode driver. Allows a file to be treated as a
+ device after being set up with the
+ <tt>vnconfig(8)</tt> command. This driver can be
+ useful for manipulating floppy disk images and
+ using a file as a swap device (e.g. an MS Windows
+ swap file). Optional.
+ </descrip>
+ <sect1><heading>Joystick, PC Speaker, Miscellaneous</heading>
+ <p>This section describes some miscellaneous hardware
+ devices supported by FreeBSD. Note that none of these
+ lines are included in the GENERIC kernel, you'll have
+ to copy them from this handbook or the LINT kernel
+ (which contains support for <em>every</em> device):
+ <descrip>
+ <tag>device joy0 at isa? port ``IO_GAME''</tag>
+ <p>PC joystick device.
+ <tag>pseudo-device speaker</tag>
+ <p>Supports IBM BASIC-style noises through the PC
+ speaker. Some fun programs which use this are
+ <tt>/usr/sbin/spkrtest</tt>, which is a shell
+ script that plays some simple songs, and
+ <tt>/usr/games/piano</tt> which lets you play songs
+ using the keyboard as a simple piano (this file
+ only exists if you've installed the <em>games</em>
+ package). Also, the excellent text role-playing
+ game NetHack (in the ports collection) can be
+ configured to use this device to play songs when
+ you play musical instruments in the game.
+ </descrip>
+ <sect><heading>Making Device Nodes<label id="kernelconfig:nodes"></heading>
+ <p>Almost every device in the kernel has a corresponding
+ ``node'' entry in the <tt>/dev</tt> 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 <tt>/dev/MAKEDEV</tt>, which is
+ executed when you first install the operating system,
+ creates nearly all of the device nodes supported.
+ However, it does not create <em>all</em> 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:
+ Suppose you add the IDE CD-ROM support to the kernel.
+ The line to add is:
+controller wcd0
+ This means that you should look for some entries that
+ start with <tt>wcd0</tt> in the <tt>/dev</tt> directory,
+ possibly followed by a letter, such as `c', or preceded
+ by the letter 'r', which means a `raw' device. It turns
+ out that those files are not there, so I must change to
+ the <tt>/dev</tt> directory and type:
+# sh MAKEDEV wcd0
+ When this script finishes, you will find that there are
+ now <tt>wcd0c</tt> and <tt>rwcd0c</tt> entries in
+ <tt>/dev</tt> so you know that it executed correctly.
+ For sound cards, the command:
+# sh MAKEDEV snd0
+ creates the appropriate entries. Follow this simple
+ procedure for any other non-GENERIC devices which do not
+ have entries.
+ <quote><em/Note:/ All SCSI controllers use the same set
+ of <tt>/dev</tt> entries, so you do not need to create
+ these. Also, network cards and SLIP/PPP pseudo-devices
+ do not have entries in <tt>/dev</tt> at all, so you do
+ not have to worry about these either.</quote>
+<sect><heading>If Something Goes Wrong<label id="kernelconfig:trouble"></heading>
+ <p>There are four categories of trouble that can occur when
+ building a custom kernel. They are:
+ <descrip>
+ <tag>Config command fails</tag>
+ <p>If the <tt>config</tt>
+ command fails when you give it your kernel
+ description, you've probably made a simple error
+ somewhere. Fortunately, <tt>config</tt> will print
+ the line number that it had trouble with, so you can
+ quickly skip to it with <tt>vi</tt>. For example, if
+ you see:
+config: line 17: syntax error
+ you can skip to the problem in <tt>vi</tt> by typing
+ ``17G'' in command mode. Make sure the keyword is
+ typed correctly, by comparing it to the GENERIC
+ kernel or another reference.
+ <tag>Make command fails</tag>
+ <p>If the <tt>make</tt>
+ command fails, it usually signals an error in your
+ kernel description, but not severe enough for
+ <tt>config</tt> to catch it. Again, look over your
+ configuration, and if you still cannot resolve the
+ problem, send mail to <tt><htmlurl
+ url="mailto:questions@freebsd.org"
+ name="questions@FreeBSD.ORG"></tt> with your kernel
+ configuration, and it should be diagnosed very
+ quickly.
+ <tag>Kernel will not boot<label id="kernelconfig:noboot"></tag>
+ <p>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 type the name of the kernel you want to boot
+ from (i.e. ``kernel.old'') at the FreeBSD boot
+ prompt instead of pressing return. When
+ reconfiguring a kernel, it is always a good idea to
+ keep a kernel that is known to work on hand.
+ After booting with a good kernel you can check over
+ your configuration file and try to build it again.
+ One helpful resource is the
+ <tt>/var/log/messages</tt> file which records, among
+ other things, all of the kernel messages from every
+ successful boot. Also, the <tt>dmesg(8)</tt> command
+ will print the kernel messages from the current boot.
+ <quote><em/Note:/ If you are having trouble building
+ a kernel, make sure to keep a GENERIC, 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 <tt>kernel.old</tt>
+ because when installing a new kernel,
+ <tt>kernel.old</tt> is overwritten with the last
+ installed kernel which may be non-functional.
+ Also, as soon as possible, move the working kernel
+ to the proper ``kernel'' location or commands such
+ as <tt>ps(1)</tt> will not work properly. The
+ proper command to ``unlock'' the kernel file that
+ <tt>make</tt> installs (in order to move another
+ kernel back permanently) is:
+# chflags noschg /kernel
+ And, if you want to ``lock'' your new kernel into place, or any file
+ for that matter, so that it cannot be moved or tampered with:
+# chflags schg /kernel
+ </quote>
+ <tag>Kernel works, but <tt>ps</tt> does not work any more!</tag>
+ <p>If you've installed a different version
+ of the kernel from the one that the system utilities
+ have been built with, for example, an experimental
+ ``2.2.0'' kernel on a 2.1.0-RELEASE system, many
+ system-status commands like <tt>ps(1)</tt> and
+ <tt>vmstat(8)</tt> will not work any more. You must
+ recompile the <tt>libkvm</tt> 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.
+ </descrip>