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, in the order they are listed in GENERIC. For an exhaustive list of architecture dependent options and devices, refer to NOTES in the same directory as GENERIC for that architecture. For architecture independent options, refer to /usr/src/sys/conf/NOTES.

An include directive is available for use in configuration files. This allows another configuration file to be included in the current one, making it easy to maintain small changes relative to an existing file. For example, if only a small number of additional options or drivers are required, this allows a delta to be maintained with respect to GENERIC:

Using this method, the local configuration file expresses local differences from a GENERIC kernel. As upgrades are performed, new features added to GENERIC will be also be added to the local kernel unless they are specifically prevented using nooptions or nodevice. A comprehensive list of configuration directives and their descriptions may be found in config(5).

The remainder of this chapter addresses the contents of a typical configuration file and the role various options and devices play.

The following is an example of the GENERIC kernel configuration file with various additional comments where needed for clarity. This example should match the copy in /usr/src/sys/i386/conf/GENERIC fairly closely.

This is the machine architecture. It must be either amd64, i386, ia64, pc98, powerpc, or sparc64.

This option specifies the type of CPU. It is fine to have multiple instances of the CPU entries, but for a custom kernel it is best to specify the CPU. To determine the CPU type, review the boot messages in /var/run/dmesg.boot.

This is the identification of the kernel. Change this to the new kernel name, such as MYKERNEL. The value in the ident string will print when the kernel boots.

device.hints(5) is used to configure options for device drivers. The default location is /boot/device.hints. The hints option compiles these hints statically into the kernel so that there is no need to create /boot/device.hints.

This option enables debugging information when passed to gcc(1).

The default system scheduler for FreeBSD. Keep this.

Allows kernel threads to be preempted by higher priority threads. This helps with interactivity and allows interrupt threads to run sooner rather than waiting.

Networking support. This is mandatory as most programs require at least loopback networking.

This enables the IPv6 communication protocols.

This is the basic hard drive file system. Leave it in if the system boots from the hard disk.

This option enables Soft Updates in the kernel which helps to speed up write access on the disks. Even when this functionality is provided by the kernel, it must be turned on for specific disks. Review the output of mount(8) to determine if Soft Updates is enabled. If the soft-updates option is not in the output, it can be activated using tunefs(8) for existing file systems or newfs(8) for new file systems.

This option enables kernel support for access control lists (ACLs). This relies on the use of extended attributes and UFS2, and the feature is described in detail in Section 15.11, “Filesystem Access Control Lists (ACL)s”. ACLs are enabled by default and should not be disabled in the kernel if they have been used previously on a file system, as this will remove the ACLs, changing the way files are protected in unpredictable ways.

This option includes functionality to speed up disk operations on large directories, at the expense of using additional memory. Keep this for a large server or interactive workstation, and remove it from smaller systems where memory is at a premium and disk access speed is less important, such as a firewall.

This option enables support for a memory backed virtual disk used as a root device.

The network file system (NFS). These lines can be commented unless the system needs to mount partitions from a NFS file server over TCP/IP.

The MS-DOS® file system. Unless the system needs to mount a DOS formatted hard drive partition at boot time, comment this out. It will be automatically loaded the first time a DOS partition is mounted. The emulators/mtools package allows access to DOS floppies without having to mount and unmount them and does not require MSDOSFS.

The ISO 9660 file system for CDROMs. Comment it out if the system does not have a CDROM drive or only mounts data CDs occasionally since it will be dynamically loaded the first time a data CD is mounted. Audio CDs do not need this file system.

The process file system. This is a “pretend” file system mounted on /proc which allows some programs to provide more information on what processes are running. Use of PROCFS is not required under most circumstances, as most debugging and monitoring tools have been adapted to run without PROCFS. The default installation will not mount this file system by default.

Kernels making use of PROCFS must also include support for PSEUDOFS.

Adds support for GUID Partition Tables (GPT). GPT provides the ability to have a large number of partitions per disk, 128 in the standard configuration.

Compatibility with 4.3BSD. Leave this in as some programs will act strangely if this is commented out.

This option is required to support applications compiled on older versions of FreeBSD that use older system call interfaces. It is recommended that this option be used on all i386™ systems that may run older applications. Platforms that gained support after FreeBSD 4.X, such as ia64 and SPARC64®, do not require this option.

This option is required to support applications compiled on FreeBSD 5.X versions that use FreeBSD 5.X system call interfaces.

This option is required to support applications compiled on FreeBSD 6.X versions that use FreeBSD 6.X system call interfaces.

This option is required on FreeBSD 8 and above to support applications compiled on FreeBSD 7.X versions that use FreeBSD 7.X system call interfaces.

This causes the kernel to pause for 5 seconds before probing each SCSI device in the system. If the system only has IDE hard drives, ignore this or lower the number to speed up booting. However, if FreeBSD has trouble recognizing the SCSI devices, the number will have to be raised again.

This enables kernel process tracing, which is useful in debugging.

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 Xorg is installed, include this.

Support for System V messages. This option only adds a few hundred bytes to the kernel.

Support for System V semaphores. Less commonly used, but only adds a few hundred bytes to the kernel.

Real-time extensions added in the 1993 POSIX®. Certain applications in the Ports Collection use these.

This option is required to allow the creation of keyboard device nodes in /dev.

This device enables the use of the I/O APIC for interrupt delivery. It can be used in both uni-processor and SMP kernels, but is required for SMP kernels. Add options SMP to include support for multiple processors.

Include this for systems with an EISA motherboard. This enables auto-detection and configuration support for all devices on the EISA bus.

Include this for systems with a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to ISA bus.

This is the floppy drive controller.

This driver supports all ATA and ATAPI devices. Only one device ata line is needed for the kernel to detect all PCI ATA/ATAPI devices on modern machines.

This is needed along with device ata for ATA disk drives.

This is needed along with device ata for ATA RAID drives.

This is needed along with device ata for ATAPI CDROM drives.

This is needed along with device ata for ATAPI floppy drives.

This is needed along with device ata for ATAPI tape drives.

This makes the controller number static. Without this, the device numbers are dynamically allocated.

In this section, comment out any SCSI controllers not on the system. For an IDE only system, these lines can be removed. The *_REG_PRETTY_PRINT lines are debugging options for their respective drivers.

Comment out any SCSI peripherals not on the system. If the system only has IDE hardware, these lines can be removed completely.

Supported RAID controllers. If the system does not have any of these, comment them out or remove them.

The atkbdc keyboard controller provides I/O services for the AT keyboard and PS/2 style pointing devices. This controller is required by atkbd(4) and psm(4).

The atkbd(4) driver, together with the atkbdc(4) controller, provides access to the AT 84 keyboard or the AT enhanced keyboard which is connected to the AT keyboard controller.

Use this device if the mouse plugs into the PS/2 mouse port.

Basic support for keyboard multiplexing. If the system does not use more than one keyboard, this line can be safely removed.

The vga(4) video card driver.

Required by the boot splash screen and screen savers.

sc(4) is the default console driver and resembles a SCO console. Since most full-screen programs access the console through a terminal database library like termcap, it should not matter whether this or vt, the VT220 compatible console driver, is used. When a user logs in, the TERM variable can be set to scoansi if full-screen programs have trouble running under this console.

This is a VT220-compatible console driver, backward compatible to VT100/102. It works well on some laptops which have hardware incompatibilities with sc. Users may need to set TERM to vt100 or vt220 after login. This driver is useful when connecting to a large number of different machines over the network, where termcap or terminfo entries for the sc device are not available as vt100 should be available on virtually any platform.

Include this if the system has an AGP card. This will enable support for AGP and AGP GART for boards which have these features.

Timer device driver for power management events, such as APM and ACPI.

PCMCIA support. Keep this on laptop systems.

These are the serial ports referred to as COM ports in Windows®.

This is the ISA bus parallel port interface.

Provides support for the parallel port bus.

Adds support for parallel port printers.

The general-purpose I/O (“geek port”) + IEEE1284 I/O.

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

Uncomment this device if the system has a “dumb” serial or parallel PCI card that is supported by the puc(4) glue driver.

Various PCI network card drivers. Comment out or remove any of these which are not present in the system.

MII bus support is required for some PCI 10/100 Ethernet NICs, namely those which use MII-compliant transceivers or implement transceiver control interfaces that operate like an MII. Adding device miibus 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.

Drivers that use the MII bus controller code.

ISA Ethernet drivers. See /usr/src/sys/i386/conf/NOTES for details of which cards are supported by which driver.

Generic 802.11 support. This line is required for wireless networking.

Crypto support for 802.11 devices. These lines are needed on systems which use encryption and 802.11i security protocols.

Support for various wireless cards.

This is the generic loopback device for TCP/IP. This is mandatory.

Cryptographically secure random number generator.

ether is only needed if the system has an Ethernet card. It includes generic Ethernet protocol code.

sl provides 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.

This is for kernel PPP support for dial-up connections. There is also a version of PPP implemented as a userland application that uses tun and offers more flexibility and features such as demand dialing.

This is used by the userland PPP software. See the PPP section of the Handbook for more information.

This is a “pseudo-terminal” or simulated login port. It is used by incoming telnet and rlogin sessions, xterm, and some other applications such as Emacs.

Memory disk pseudo-devices.

This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. The gif device is “auto-cloning”, and will create device nodes as needed.

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

The Berkeley Packet Filter pseudo-device allows network interfaces to be placed in promiscuous mode, capturing every packet on a broadcast network such as an Ethernet network. These packets can be captured to disk and or examined using tcpdump(1).

Support for various USB devices.

Support for various Firewire devices.

For more information and additional devices supported by FreeBSD, see /usr/src/sys/i386/conf/NOTES.