Contributed by &a.jehamby;. 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 your PC's hardware. This has a number of
benefits:
First, let us take a quick tour of the kernel build
directory. All directories mentioned will be relative to
the main /usr/src/sys directory, which is also
accessible through /sys. There are a number of
subdirectories here representing different parts of the
kernel, but the most important, for our purposes, are
i386/conf, where you will edit your custom
kernel configuration, and compile, 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 i386
directory deals with PC hardware only, while everything
outside the i386 directory is common to all
platforms which FreeBSD could potentially be ported to.
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 # 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
GENERIC.
These keywords are required in every kernel you build.
The first keyword is machine, which,
since FreeBSD only runs on Intel 386 and compatible
chips, is i386.
The next keyword is cpu, which includes
support for each CPU supported by FreeBSD. The
possible values of cpu_type
include:
Next, we have ident, 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 ident 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 machine and cpu, enclose
your kernel's name in quotation marks if it
contains any numbers.
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
maxusers to at least four, especially if
you're using X Windows or compiling software. The
reason is that the most important table set by
maxusers is the maximum number of
processes, which is set to This line specifies the location and name of the
kernel. Traditionally the kernel is called
vmunix but in FreeBSD, it is aptly named
kernel. You should always use
kernel for kernel_name 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
wd0 for systems with non-SCSI drives, or
sd0 for systems with SCSI drives.
These lines provide kernel support for various
filesystems and other options.
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
FFS if you boot from a hard drive, or
NFS 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
/lkm the first time you mount a partition of
that type.
The basic hard drive
filesystem; leave it in if you boot from the hard
disk.
Network Filesystem. Unless
you plan to mount partitions from a Unix file
server over Ethernet, you can comment this out.
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 mtools 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).
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.
Process filesystem. This
is a pretend filesystem mounted on /proc which
allows programs like ps(1) to give you
more information on what processes are running.
Leave it in.
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
/tmp directory, since many programs store
temporary data here. To mount an MFS RAM disk on
/tmp, add the following line to
/etc/fstab and then reboot or type
mount /tmp:
Enable disk quotas. If you
have a public access system, and do not want users
to be able to overflow the /home
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 quota(1) to learn more about disk
quotas.
These sections describe the basic disk, tape, and
CD-ROM controllers supported by FreeBSD. There are
separate sections for controllers and cards.
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.
Include this if you have a
PCI motherboard. This enables auto-detection of
PCI cards and gatewaying from the PCI to the ISA
bus.
Floppy drive controller:
fd0 is the ``A:'' floppy drive, and
fd1 is the ``B:'' drive. ft0 is
a QIC-80 tape drive attached to the floppy
controller. Comment out any lines corresponding to
devices you do not have.
This is the primary IDE
controller. wd0 and wd1 are the
master and slave hard drive, respectively.
wdc1 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).
This device
provides IDE CD-ROM support. Be sure to leave
wdc1 uncommented if your CD-ROM is on
its own controller card. To use this, you must
also include the line options ATAPI.
npx0 is the interface to the
math coprocessor. If you have one then make sure
you've commented out above. If you do not have a
math coprocessor, you can comment this out.
Wangtek and Archive
QIC-02/QIC-36 tape drive support
The following
drivers are for the so-called proprietary
CD-ROM drives. These drives have their own
controller card or might plug into a sound card
such as the Soundblaster 16. They are not
IDE or SCSI. Most older single-speed and
double-speed CD-ROMs use these interfaces, while
newer quad-speeds are likely to be or .
Mitsumi CD-ROM (LU002,
LU005, FX001D).
Sony CD-ROM (CDU31, CDU33A).
Matsushita/Panasonic CD-ROM (sold by Creative
Labs for Soundblaster).
This section describes the various SCSI controllers
and devices supported by FreeBSD.
The next ten or so lines include support for
different kinds of SCSI controllers. Comment out
all except for the one(s) you have:
Most Buslogic controllers
UltraStor 14F and 34F
Adaptec 274x/284x/294x
Adaptec 174x
Adaptec 154x
Adaptec 152x and sound cards using Adaptec AIC-6360 (slow!)
ProAudioSpectrum cards using NCR 5380 or Trantor T130
Seagate ST01/02 8 bit controller (slow!)
Western Digital WD7000 controller
NCR 53C810 and 53C825 PCI SCSI controller
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.
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.
Support for SCSI hard
drives.
Support for SCSI tape
drives.
Support for SCSI CD-ROM
drives.
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.
sc0 is the default
console driver, which resembles an SCO console.
Since most full-screen programs access the console
through a terminal database library like
termcap, it should not matter much whether
you use this or vt0, 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.
This is a VT220-compatible
console driver, backwards compatible to VT100/102.
It works well on some laptops which have hardware
incompatibilities with sc0. Also, set
your TERM variable to ``vt220'' when you log in if
full-screen programs do not run correctly on this
console.
Required
with the vt0 console driver.
This includes code
required to run the XFree86 X Window
Server.
Use this device if you have a Logitech or
ATI InPort bus mouse card.
Use this device if your
mouse plugs into the PS/2 mouse port.
Nearly all systems have these. If you are attaching a
printer to one of these ports, the section of the handbook is very
useful. If you are using modem, provides extensive detail on
serial port configuration for use with such devices.
sio0
through sio3 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 sio(4) for
more information on the proper values for these
lines.
lpt0 through lpt2
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.
FreeBSD, as with Unix in general, places a
big 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.
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):
Digital Equipment DC21040 PCI Ethernet adapter
Cronyx/Sigma multiport
sync/async (with Cisco or PPP framing)
Western Digital and SMC 80xx; Novell NE1000
and NE2000; 3Com 3C503
3Com 3C501 (slow!)
3Com 3C505
3Com 3C509 (buggy)
Fujitsu MB86960A/MB86965A Ethernet
DEC DEFEA EISA FDDI adapter
AT&T StarLAN 10 and EN100; 3Com 3C507;
unknown NI5210
Intel EtherExpress 16
Digital Equipment EtherWorks 2 and EtherWorks
3 (DEPCA, DE100, DE101, DE200, DE201, DE202,
DE203, DE204, DE205, DE422)
Lance/PCnet cards (Isolan, Novell NE2100,
NE32-VL)
IBM/National Semiconductor PCMCIA ethernet
controller.
3Com PCMCIA Etherlink III
loop is the
generic loopback device for TCP/IP. If you telnet
or FTP to localhost
(a.k.a. 127.0.0.1) it will come back at
you through this pseudo-device. Mandatory.
ether is only
needed if you have an Ethernet card and includes
generic Ethernet protocol code.
sl 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 number after
sl specifies how many simultaneous SLIP
sessions to support. This handbook has more
information on setting up a SLIP or .
ppp 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 tun and offers
more flexibility and features such as demand
dialing. If you still want to use this PPP driver,
read the
section of the handbook. As with the sl
device, number specifies how many
simultaneous PPP connections to support.
tun 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 tun
specifies the number of simultaneous PPP sessions
to support. See the section of the handbook for
more information.
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
tcpdump(1) program. Note that
implementation of this capability can seriously
compromise your overall network security.
The number 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.
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
every device) as follows:
Generic sound driver code.
Required for all of the following sound cards
except pca.
ProAudioSpectrum digital audio and MIDI.
SoundBlaster digital audio.
SoundBlaster 16 digital 16-bit audio.
SoundBlaster 16 MIDI interface. If you have a
SoundBlaster 16, you must include this line, or the
kernel will not compile.
Gravis Ultrasound.
Microsoft Sound System.
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
playmidi (in the ports collection).
Roland MPU-401 stand-alone card.
Stand-alone 6850 UART for MIDI.
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)!
not a
/usr/src/sys 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.
Next, move to the i386/conf directory and copy
the GENERIC configuration file to the name you want to
give your kernel. For example:
Now, edit MYKERNEL with your favorite text editor. If
you're just starting out, the only editor available will
probably be vi, which is too complex to explain
here, but is covered well in many books in the . 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
section slowly and carefully.
When you're finished, type the following to compile and
install your kernel:
to your
/dev directory before you can use them.
Note: that any keyword which
contains numbers used as text must be enclosed in
quotation marks, otherwise config gets
confused and thinks you mean the actual number
386.
maxuser does
not 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
does limit the number of simultaneous
remote logins is .
/dev/wd1s2b
with the name of your swap partition, which will
be listed in your /etc/fstab as follows:
/tmp device
simultaneously). As such, you may want to avoid
it for now. --> Also, the MFS filesystem
can not be dynamically loaded, so you
must compile it into your kernel if you
want to experiment with it.
ft(8), see
the manual page for details.
port is enabled (probably
COM1).
irq 7
to, for example, irq 5 and remove the
conflicts keyword. Also, you must add
the line: options ``SBC_IRQ=5''
drq 5 keyword appropriately, and then
add the line: options
"SB16_DMA=6"
/usr/src/sys/i386/isa/sound/sound.doc.
Also, if you add any of these devices, be sure to
create the sound .