diff --git a/en/handbook/kernelconfig/chapter.sgml b/en/handbook/kernelconfig/chapter.sgml index 24883ca2d2..f40cd2f2d3 100644 --- a/en/handbook/kernelconfig/chapter.sgml +++ b/en/handbook/kernelconfig/chapter.sgml @@ -1,1709 +1,1709 @@ Configuring the FreeBSD Kernel Contributed by &a.jehamby;.6 October 1995. 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. Why Build a Custom Kernel? Building a custom kernel is one of the most important rites of passage every Unix system administrator must endure. 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: It will take less time to boot because it does not have to spend time probing for hardware which you do not have. 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. 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 not present in the GENERIC kernel. Building and Installing a Custom Kernel 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. If there is 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: &prompt.root; cd /usr/src/sys/i386/conf &prompt.root; cp GENERIC MYKERNEL 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 MYKERNEL for the purpose of this example. You must execute these and all of the following commands under the root account or you will get permission denied errors. Now, edit MYKERNEL with your favorite text editor. If you are 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 bibliography. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from GENERIC. 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 GENERIC configuration file might seem overwhelming to you, so follow the descriptions in the Configuration File section slowly and carefully. If you are trying to upgrade your kernel from an older version of FreeBSD, you will probably have to get a new version of config8 from the same place you got the new kernel sources. It is located in /usr/src/usr.sbin, so you will need to download those sources as well. Re-build and install it before running the next commands. When you are finished, type the following to compile and install your kernel: &prompt.root; /usr/sbin/config MYKERNEL &prompt.root; cd ../../compile/MYKERNEL &prompt.root; make depend &prompt.root; make &prompt.root; make install The new kernel will be copied to the root directory as /kernel and the old kernel will be moved to /kernel.old. Now, shutdown the system and reboot to use your kernel. In case something goes wrong, there are some troubleshooting instructions at the end of this document. Be sure to read the section which explains how to recover in case your new kernel does not boot. If you have added any new devices (such as sound cards) you may have to add some device nodes to your /dev directory before you can use them. The Configuration File 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 and more detailed explanations of the device lines is present in the LINT configuration file, located in the same directory as GENERIC. If you are in doubt as to the purpose or necessity of a line, check first in LINT. The kernel is currently being moved to a better organization of the option handling. Traditionally, each option in the config file was simply converted into a switch for the CFLAGS line of the kernel Makefile. Naturally, this caused a creeping optionism, with nobody really knowing which option has been referenced in what files. In the new scheme, every #ifdef that is intended to be dependent upon an option gets this option out of an opt_foo.h declaration file created in the compile directory by config. The list of valid options for config lives in two files: options that do not depend on the architecture are listed in /sys/conf/options, architecture-dependent ones in /sys/arch/conf/options.arch, with arch being for example i386. Mandatory Keywords These keywords are required in every kernel you build. machine "i386" The first keyword is machine, which, since FreeBSD only runs on Intel 386 and compatible chips, is i386. 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. cpu "cpu_type" The next keyword is cpu, which includes support for each CPU supported by FreeBSD. The possible values of cpu_type include: I386_CPU I486_CPU I586_CPU I686_CPU Multiple instances of the cpu line may be present with different values of cpu_type 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 I586_CPU for cpu_type. ident machine_name 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 is 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. Since this name is passed to the C compiler as a switch, do not use names like DEBUG, or something that could be confused with another machine or CPU name, like vax. maxusers number 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 4, especially if you are using the X Window System or compiling software. The reason is that the most important table set by maxusers is the maximum number of processes, which is set to 20 + 16 * maxusers, so if you set maxusers 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 maxusers 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. 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 pseudo-device pty 16. config kernel_name root on root_device 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. General Options These lines provide kernel support for various filesystems and other options. options MATH_EMULATE 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 Pentium, a 486DX, or a 386 or 486SX with a separate 387 or 487 chip, you can comment this line out. The normal math co-processor emulation routines that come with FreeBSD are not very accurate. If you do not have a math co-processor, and you need the best accuracy, I recommend that you change this option to GPL_MATH_EMULATE to use the superior GNU math support, which is not included by default for licensing reasons. options "COMPAT_43" Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out. options BOUNCE_BUFFERS ISA devices and EISA devices operating in an ISA compatibility 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. options UCONSOLE Allow users to grab the console, useful for X Windows. For example, you can create a console xterm by typing xterm -C, which will display any write, talk, and other messages you receive, as well as any console messages sent by the kernel. options SYSVSHM 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 the X Window System, you will definitely want to include this. options SYSVSEM Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel. options SYSVMSG Support for System V messages. Again, only adds a few hundred bytes to the kernel. The ipcs1 command will tell will list any processes using each of these System V facilities. Filesystem 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. options FFS The basic hard drive filesystem; leave it in if you boot from the hard disk. options NFS Network Filesystem. Unless you plan to mount partitions from a Unix file server over Ethernet, you can comment this out. options MSDOSFS 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). options "CD9660" 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. options PROCFS Process filesystem. This is a pretend filesystem mounted on /proc which allows programs like ps1 to give you more information on what processes are running. options MFS 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: /dev/wd1s2b /tmp mfs rw 0 0 Replace the /dev/wd1s2b with the name of your swap partition, which will be listed in your /etc/fstab as follows: /dev/wd1s2b none swap sw 0 0 Also, the MFS filesystem can not be dynamically loaded, so you must compile it into your kernel if you want to experiment with it. options "EXT2FS" Linux's native file system. With ext2fs support you are able to read and write to Linux partitions. This is useful if you dual-boot FreeBSD and Linux and want to share data between the two systems. options QUOTA 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. Refer to the Disk Quotas section for more information. Basic Controllers and Devices These sections describe the basic disk, tape, and CD-ROM controllers supported by FreeBSD. There are separate sections for SCSI controllers and network cards. controller isa0 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. controller pci0 Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to the ISA bus. controller fdc0 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. QIC-80 tape support requires a separate filter program called ft8, see the manual page for details. controller wdc0 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 will probably want to comment out all six lines, for example). device wcd0 This device provides IDE CD-ROM support. Be sure to leave wdc0 uncommented, and wdc1 if you have more than one IDE controller and your CD-ROM is on the second one card. To use this, you must also include the line options ATAPI. device npx0 at isa? port "IO_NPX" irq 13 vector npxintr npx0 is the interface to the floating point math unit in FreeBSD, either the hardware co-processor or the software math emulator. It is not optional. device wt0 at isa? port 0x300 bio irq 5 drq 1 vector wtintr Wangtek and Archive QIC-02/QIC-36 tape drive support Proprietary CD-ROM 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 IDE or SCSI. device mcd0 at isa? port 0x300 bio irq 10 vector mcdintr Mitsumi CD-ROM (LU002, LU005, FX001D). device scd0 at isa? port 0x230 bio Sony CD-ROM (CDU31, CDU33A). controller matcd0 at isa? port ? bio Matsushita/Panasonic CD-ROM (sold by Creative Labs for SoundBlaster). SCSI Device Support This section describes the various SCSI controllers and devices supported by FreeBSD. SCSI Controllers The next ten or so lines include support for different kinds of SCSI controllers. Comment out all except for the one(s) you have: controller bt0 at isa? port "IO_BT0" bio irq ? vector btintr Most Buslogic controllers controller uha0 at isa? port "IO_UHA0" bio irq ? drq 5 vector uhaintr UltraStor 14F and 34F controller ahc0 Adaptec 274x/284x/294x controller ahb0 at isa? bio irq ? vector ahbintr Adaptec 174x controller aha0 at isa? port "IO_AHA0" bio irq ? drq 5 vector ahaintr Adaptec 154x controller aic0 at isa? port 0x340 bio irq 11 vector aicintr Adaptec 152x and sound cards using Adaptec AIC-6360 (slow!) controller nca0 at isa? port 0x1f88 bio irq 10 vector ncaintr ProAudioSpectrum cards using NCR 5380 or Trantor T130 controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr Seagate ST01/02 8 bit controller (slow!) controller wds0 at isa? port 0x350 bio irq 15 drq 6 vector wdsintr Western Digital WD7000 controller controller ncr0 NCR 53C810, 53C815, 53C825, 53C860, 53C875 PCI SCSI controller options "SCSI_DELAY=15" 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 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. controller scbus0 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. device sd0 Support for SCSI hard drives. device st0 Support for SCSI tape drives. device cd0 Support for SCSI CD-ROM drives. Note that the number 0 in the above entries is slightly misleading: all these devices are automatically configured as they are found, regardless of how many of them are hooked up to the SCSI bus(es), and which target IDs they have. If you want to “wire down” specific target IDs to particular devices, refer to the appropriate section of the LINT kernel config file. Console, Bus Mouse, and X Server Support You must choose one of these two console types, and, if you plan to use the X Window System with the vt220 console, enable the XSERVER option and optionally, a bus mouse or PS/2 mouse device. device sc0 at isa? port "IO_KBD" tty irq 1 vector scintr 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. device vt0 at isa? port "IO_KBD" tty irq 1 vector pcrint 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 vt100 or vt220 when you log in. This driver might also prove useful when connecting to a large number of different machines over the network, where the termcap or terminfo entries for the sc0 device are often not available — vt100 should be available on virtually any platform. options "PCVT_FREEBSD=210" Required with the vt0 console driver. options XSERVER Only applicable with the vt0 console driver. This includes code required to run the XFree86 X Window Server under the vt0 console driver. device mse0 at isa? port 0x23c tty irq 5 vector ms Use this device if you have a Logitech or ATI InPort bus mouse card. If you have a serial mouse, ignore these two lines, and instead, make sure the appropriate serial port is enabled (probably COM1). device psm0 at isa? port "IO_KBD" conflicts tty irq 12 vector psmintr Use this device if your mouse plugs into the PS/2 mouse port. Serial and Parallel Ports Nearly all systems have these. If you are attaching a printer to one of these ports, the Printing section of the handbook is very useful. If you are using modem, Dialup access provides extensive detail on serial port configuration for use with such devices. device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr 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 sio4 for more information on the proper values for these lines. Some video cards (notably those based on S3 chips) use IO addresses of the form 0x*2e8, 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. 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. device lpt0 at isa? port? tty irq 7 vector lptintr 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. Networking 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. options INET 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. Ethernet cards 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 will want to leave in support for your particular Ethernet card(s): device de0 Ethernet adapters based on Digital Equipment DC21040, DC21041 or DC21140 chips device fxp0 Intel EtherExpress Pro/100B device vx0 3Com 3C590 and 3C595 (buggy) device cx0 at isa? port 0x240 net irq 15 drq 7 vector cxintr Cronyx/Sigma multiport sync/async (with Cisco or PPP framing) device ed0 at isa? port 0x280 net irq 5 iomem 0xd8000 vector edintr Western Digital and SMC 80xx and 8216; Novell NE1000 and NE2000; 3Com 3C503; HP PC Lan Plus (HP27247B and HP27252A) device el0 at isa? port 0x300 net irq 9 vector elintr 3Com 3C501 (slow!) device eg0 at isa? port 0x310 net irq 5 vector egintr 3Com 3C505 device ep0 at isa? port 0x300 net irq 10 vector epintr 3Com 3C509 (buggy) device fe0 at isa? port 0x240 net irq ? vector feintr Fujitsu MB86960A/MB86965A Ethernet device fea0 at isa? net irq ? vector feaintr DEC DEFEA EISA FDDI adapter device ie0 at isa? port 0x360 net irq 7 iomem 0xd0000 vector ieintr AT&T StarLAN 10 and EN100; 3Com 3C507; unknown NI5210; Intel EtherExpress 16 device le0 at isa? port 0x300 net irq 5 iomem 0xd0000 vector le_intr Digital Equipment EtherWorks 2 and EtherWorks 3 (DEPCA, DE100, DE101, DE200, DE201, DE202, DE203, DE204, DE205, DE422) device lnc0 at isa? port 0x300 net irq 10 drq 0 vector lncintr Lance/PCnet cards (Isolan, Novell NE2100, NE32-VL) device xl0 3Com Etherlink XL series PCI ethernet - controllers (3C905B and related). + controllers (3C905B and related). device ze0 at isa? port 0x300 net irq 5 iomem 0xd8000 vector zeintr IBM/National Semiconductor PCMCIA ethernet controller. device zp0 at isa? port 0x300 net irq 10 iomem 0xd8000 vector zpintr 3Com PCMCIA Etherlink III With certain cards (notably the NE2000) you will have to change the port and/or IRQ since there is no “standard” location for these cards. pseudo-device loop 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. pseudo-device ether ether is only needed if you have an Ethernet card and includes generic Ethernet protocol code. pseudo-device sl number 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 client or server. pseudo-device ppp number 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 kernel-mode PPP section of the handbook. As with the sl device, number specifies how many simultaneous PPP connections to support. pseudo-device tun number 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 user-mode PPP section of the handbook for more information. pseudo-device bpfilter number 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 tcpdump1 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. Sound cards This is the first section containing lines that are not in the GENERIC kernel. To include sound card support, you will have to copy the appropriate lines from the LINT kernel (which contains support for every device) as follows: controller snd0 Generic sound driver code. Required for all of the following sound cards except pca. device pas0 at isa? port 0x388 irq 10 drq 6 vector pasintr ProAudioSpectrum digital audio and MIDI. device sb0 at isa? port 0x220 irq 7 conflicts drq 1 vector sbintr SoundBlaster digital audio. If your SoundBlaster is on a different IRQ (such as 5), change irq 7 to, for example, irq 5 and remove the conflicts keyword. Also, you must add the line: options "SBC_IRQ=5" device sbxvi0 at isa? drq 5 SoundBlaster 16 digital 16-bit audio. If your SB16 is on a different 16-bit DMA channel (such as 6 or 7), change the drq 5 keyword appropriately, and then add the line: options "SB16_DMA=6" device sbmidi0 at isa? port 0x330 SoundBlaster 16 MIDI interface. If you have a SoundBlaster 16, you must include this line, or the kernel will not compile. device gus0 at isa? port 0x220 irq 10 drq 1 vector gusintr Gravis Ultrasound. device mss0 at isa? port 0x530 irq 10 drq 1 vector adintr Microsoft Sound System. device opl0 at isa? port 0x388 conflicts 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). device mpu0 at isa? port 0x330 irq 6 drq 0 Roland MPU-401 stand-alone card. device uart0 at isa? port 0x330 irq 5 vector "m6850intr" Stand-alone 6850 UART for MIDI. device pca0 at isa? port "IO_TIMER1" tty 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). There is some additional documentation in /usr/src/sys/i386/isa/sound/sound.doc. Also, if you add any of these devices, be sure to create the sound device nodes. Pseudo-devices 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 network-related pseudo-devices are in that section, while the remainder are here. pseudo-device gzip gzip allows you to run FreeBSD programs that have been compressed with gzip. The programs in /stand are compressed so it is a good idea to have this option in your kernel. pseudo-device log log is used for logging of kernel error messages. Mandatory. pseudo-device pty number pty 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. The number indicates the number of ptys 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 256. pseudo-device snp number Snoop device. This pseudo-device allows one terminal session to watch another using the watch8 command. Note that implementation of this capability has important security and privacy implications. The number after snp is the total number of simultaneous snoop sessions. Optional. pseudo-device vn Vnode driver. Allows a file to be treated as a device after being set up with the vnconfig8 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. pseudo-device ccd number Concatenated disks. This pseudo-device allows you to concatenate multiple disk partitions into one large “meta”-disk. The number after ccd is the total number of concatenated disks (not total number of disks that can be concatenated) that can be created. (See ccd4 and ccdconfig8 man pages for more details.) Optional. Joystick, PC Speaker, Miscellaneous This section describes some miscellaneous hardware devices supported by FreeBSD. Note that none of these lines are included in the GENERIC kernel, you will have to copy them from this handbook or the LINT kernel (which contains support for every device): device joy0 at isa? port "IO_GAME" PC joystick device. pseudo-device speaker Supports IBM BASIC-style noises through the PC speaker. Some fun programs which use this are /usr/sbin/spkrtest, which is a shell script that plays some simple songs, and /usr/games/piano which lets you play songs using the keyboard as a simple piano (this file only exists if you have installed the games 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. See also the pca0 device. Making Device Nodes Almost every device in the kernel has a corresponding “node” entry in the /dev 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 /dev/MAKEDEV, which is executed when you first install the operating system, creates nearly all of the device nodes supported. However, it does not create all 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 wcd0 in the /dev 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 /dev directory and type: &prompt.root; sh MAKEDEV wcd0 When this script finishes, you will find that there are now wcd0c and rwcd0c entries in /dev so you know that it executed correctly. For sound cards, the command: &prompt.root; sh MAKEDEV snd0 creates the appropriate entries. 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 /etc/fbtab file. See man fbtab for more information. Follow this simple procedure for any other non-GENERIC devices which do not have entries. All SCSI controllers use the same set of /dev entries, so you do not need to create these. Also, network cards and SLIP/PPP pseudo-devices do not have entries in /dev at all, so you do not have to worry about these either. If Something Goes Wrong There are four categories of trouble that can occur when building a custom kernel. They are: Config command fails If the config command fails when you give it your kernel description, you have probably made a simple error somewhere. Fortunately, config will print the line number that it had trouble with, so you can quickly skip to it with vi. For example, if you see: config: line 17: syntax error you can skip to the problem in vi by typing 17G in command mode. Make sure the keyword is typed correctly, by comparing it to the GENERIC kernel or another reference. Make command fails If the make command fails, it usually signals an error in your kernel description, but not severe enough for config 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. Kernel will not boot 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 /var/log/messages file which records, among other things, all of the kernel messages from every successful boot. Also, the dmesg8 command will print the kernel messages from the current boot. 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 kernel.old because when installing a new kernel, kernel.old 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 ps1 will not work properly. The proper command to “unlock” the kernel file that make installs (in order to move another kernel back permanently) is: &prompt.root; 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: &prompt.root; chflags schg /kernel Kernel works, but ps does not work any more! If you have 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 ps1 and vmstat8 will not work any more. You must recompile the libkvm 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. diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml index 24883ca2d2..f40cd2f2d3 100644 --- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml @@ -1,1709 +1,1709 @@ Configuring the FreeBSD Kernel Contributed by &a.jehamby;.6 October 1995. 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. Why Build a Custom Kernel? Building a custom kernel is one of the most important rites of passage every Unix system administrator must endure. 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: It will take less time to boot because it does not have to spend time probing for hardware which you do not have. 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. 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 not present in the GENERIC kernel. Building and Installing a Custom Kernel 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. If there is 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: &prompt.root; cd /usr/src/sys/i386/conf &prompt.root; cp GENERIC MYKERNEL 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 MYKERNEL for the purpose of this example. You must execute these and all of the following commands under the root account or you will get permission denied errors. Now, edit MYKERNEL with your favorite text editor. If you are 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 bibliography. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from GENERIC. 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 GENERIC configuration file might seem overwhelming to you, so follow the descriptions in the Configuration File section slowly and carefully. If you are trying to upgrade your kernel from an older version of FreeBSD, you will probably have to get a new version of config8 from the same place you got the new kernel sources. It is located in /usr/src/usr.sbin, so you will need to download those sources as well. Re-build and install it before running the next commands. When you are finished, type the following to compile and install your kernel: &prompt.root; /usr/sbin/config MYKERNEL &prompt.root; cd ../../compile/MYKERNEL &prompt.root; make depend &prompt.root; make &prompt.root; make install The new kernel will be copied to the root directory as /kernel and the old kernel will be moved to /kernel.old. Now, shutdown the system and reboot to use your kernel. In case something goes wrong, there are some troubleshooting instructions at the end of this document. Be sure to read the section which explains how to recover in case your new kernel does not boot. If you have added any new devices (such as sound cards) you may have to add some device nodes to your /dev directory before you can use them. The Configuration File 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 and more detailed explanations of the device lines is present in the LINT configuration file, located in the same directory as GENERIC. If you are in doubt as to the purpose or necessity of a line, check first in LINT. The kernel is currently being moved to a better organization of the option handling. Traditionally, each option in the config file was simply converted into a switch for the CFLAGS line of the kernel Makefile. Naturally, this caused a creeping optionism, with nobody really knowing which option has been referenced in what files. In the new scheme, every #ifdef that is intended to be dependent upon an option gets this option out of an opt_foo.h declaration file created in the compile directory by config. The list of valid options for config lives in two files: options that do not depend on the architecture are listed in /sys/conf/options, architecture-dependent ones in /sys/arch/conf/options.arch, with arch being for example i386. Mandatory Keywords These keywords are required in every kernel you build. machine "i386" The first keyword is machine, which, since FreeBSD only runs on Intel 386 and compatible chips, is i386. 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. cpu "cpu_type" The next keyword is cpu, which includes support for each CPU supported by FreeBSD. The possible values of cpu_type include: I386_CPU I486_CPU I586_CPU I686_CPU Multiple instances of the cpu line may be present with different values of cpu_type 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 I586_CPU for cpu_type. ident machine_name 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 is 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. Since this name is passed to the C compiler as a switch, do not use names like DEBUG, or something that could be confused with another machine or CPU name, like vax. maxusers number 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 4, especially if you are using the X Window System or compiling software. The reason is that the most important table set by maxusers is the maximum number of processes, which is set to 20 + 16 * maxusers, so if you set maxusers 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 maxusers 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. 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 pseudo-device pty 16. config kernel_name root on root_device 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. General Options These lines provide kernel support for various filesystems and other options. options MATH_EMULATE 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 Pentium, a 486DX, or a 386 or 486SX with a separate 387 or 487 chip, you can comment this line out. The normal math co-processor emulation routines that come with FreeBSD are not very accurate. If you do not have a math co-processor, and you need the best accuracy, I recommend that you change this option to GPL_MATH_EMULATE to use the superior GNU math support, which is not included by default for licensing reasons. options "COMPAT_43" Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out. options BOUNCE_BUFFERS ISA devices and EISA devices operating in an ISA compatibility 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. options UCONSOLE Allow users to grab the console, useful for X Windows. For example, you can create a console xterm by typing xterm -C, which will display any write, talk, and other messages you receive, as well as any console messages sent by the kernel. options SYSVSHM 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 the X Window System, you will definitely want to include this. options SYSVSEM Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel. options SYSVMSG Support for System V messages. Again, only adds a few hundred bytes to the kernel. The ipcs1 command will tell will list any processes using each of these System V facilities. Filesystem 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. options FFS The basic hard drive filesystem; leave it in if you boot from the hard disk. options NFS Network Filesystem. Unless you plan to mount partitions from a Unix file server over Ethernet, you can comment this out. options MSDOSFS 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). options "CD9660" 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. options PROCFS Process filesystem. This is a pretend filesystem mounted on /proc which allows programs like ps1 to give you more information on what processes are running. options MFS 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: /dev/wd1s2b /tmp mfs rw 0 0 Replace the /dev/wd1s2b with the name of your swap partition, which will be listed in your /etc/fstab as follows: /dev/wd1s2b none swap sw 0 0 Also, the MFS filesystem can not be dynamically loaded, so you must compile it into your kernel if you want to experiment with it. options "EXT2FS" Linux's native file system. With ext2fs support you are able to read and write to Linux partitions. This is useful if you dual-boot FreeBSD and Linux and want to share data between the two systems. options QUOTA 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. Refer to the Disk Quotas section for more information. Basic Controllers and Devices These sections describe the basic disk, tape, and CD-ROM controllers supported by FreeBSD. There are separate sections for SCSI controllers and network cards. controller isa0 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. controller pci0 Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to the ISA bus. controller fdc0 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. QIC-80 tape support requires a separate filter program called ft8, see the manual page for details. controller wdc0 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 will probably want to comment out all six lines, for example). device wcd0 This device provides IDE CD-ROM support. Be sure to leave wdc0 uncommented, and wdc1 if you have more than one IDE controller and your CD-ROM is on the second one card. To use this, you must also include the line options ATAPI. device npx0 at isa? port "IO_NPX" irq 13 vector npxintr npx0 is the interface to the floating point math unit in FreeBSD, either the hardware co-processor or the software math emulator. It is not optional. device wt0 at isa? port 0x300 bio irq 5 drq 1 vector wtintr Wangtek and Archive QIC-02/QIC-36 tape drive support Proprietary CD-ROM 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 IDE or SCSI. device mcd0 at isa? port 0x300 bio irq 10 vector mcdintr Mitsumi CD-ROM (LU002, LU005, FX001D). device scd0 at isa? port 0x230 bio Sony CD-ROM (CDU31, CDU33A). controller matcd0 at isa? port ? bio Matsushita/Panasonic CD-ROM (sold by Creative Labs for SoundBlaster). SCSI Device Support This section describes the various SCSI controllers and devices supported by FreeBSD. SCSI Controllers The next ten or so lines include support for different kinds of SCSI controllers. Comment out all except for the one(s) you have: controller bt0 at isa? port "IO_BT0" bio irq ? vector btintr Most Buslogic controllers controller uha0 at isa? port "IO_UHA0" bio irq ? drq 5 vector uhaintr UltraStor 14F and 34F controller ahc0 Adaptec 274x/284x/294x controller ahb0 at isa? bio irq ? vector ahbintr Adaptec 174x controller aha0 at isa? port "IO_AHA0" bio irq ? drq 5 vector ahaintr Adaptec 154x controller aic0 at isa? port 0x340 bio irq 11 vector aicintr Adaptec 152x and sound cards using Adaptec AIC-6360 (slow!) controller nca0 at isa? port 0x1f88 bio irq 10 vector ncaintr ProAudioSpectrum cards using NCR 5380 or Trantor T130 controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr Seagate ST01/02 8 bit controller (slow!) controller wds0 at isa? port 0x350 bio irq 15 drq 6 vector wdsintr Western Digital WD7000 controller controller ncr0 NCR 53C810, 53C815, 53C825, 53C860, 53C875 PCI SCSI controller options "SCSI_DELAY=15" 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 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. controller scbus0 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. device sd0 Support for SCSI hard drives. device st0 Support for SCSI tape drives. device cd0 Support for SCSI CD-ROM drives. Note that the number 0 in the above entries is slightly misleading: all these devices are automatically configured as they are found, regardless of how many of them are hooked up to the SCSI bus(es), and which target IDs they have. If you want to “wire down” specific target IDs to particular devices, refer to the appropriate section of the LINT kernel config file. Console, Bus Mouse, and X Server Support You must choose one of these two console types, and, if you plan to use the X Window System with the vt220 console, enable the XSERVER option and optionally, a bus mouse or PS/2 mouse device. device sc0 at isa? port "IO_KBD" tty irq 1 vector scintr 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. device vt0 at isa? port "IO_KBD" tty irq 1 vector pcrint 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 vt100 or vt220 when you log in. This driver might also prove useful when connecting to a large number of different machines over the network, where the termcap or terminfo entries for the sc0 device are often not available — vt100 should be available on virtually any platform. options "PCVT_FREEBSD=210" Required with the vt0 console driver. options XSERVER Only applicable with the vt0 console driver. This includes code required to run the XFree86 X Window Server under the vt0 console driver. device mse0 at isa? port 0x23c tty irq 5 vector ms Use this device if you have a Logitech or ATI InPort bus mouse card. If you have a serial mouse, ignore these two lines, and instead, make sure the appropriate serial port is enabled (probably COM1). device psm0 at isa? port "IO_KBD" conflicts tty irq 12 vector psmintr Use this device if your mouse plugs into the PS/2 mouse port. Serial and Parallel Ports Nearly all systems have these. If you are attaching a printer to one of these ports, the Printing section of the handbook is very useful. If you are using modem, Dialup access provides extensive detail on serial port configuration for use with such devices. device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr 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 sio4 for more information on the proper values for these lines. Some video cards (notably those based on S3 chips) use IO addresses of the form 0x*2e8, 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. 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. device lpt0 at isa? port? tty irq 7 vector lptintr 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. Networking 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. options INET 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. Ethernet cards 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 will want to leave in support for your particular Ethernet card(s): device de0 Ethernet adapters based on Digital Equipment DC21040, DC21041 or DC21140 chips device fxp0 Intel EtherExpress Pro/100B device vx0 3Com 3C590 and 3C595 (buggy) device cx0 at isa? port 0x240 net irq 15 drq 7 vector cxintr Cronyx/Sigma multiport sync/async (with Cisco or PPP framing) device ed0 at isa? port 0x280 net irq 5 iomem 0xd8000 vector edintr Western Digital and SMC 80xx and 8216; Novell NE1000 and NE2000; 3Com 3C503; HP PC Lan Plus (HP27247B and HP27252A) device el0 at isa? port 0x300 net irq 9 vector elintr 3Com 3C501 (slow!) device eg0 at isa? port 0x310 net irq 5 vector egintr 3Com 3C505 device ep0 at isa? port 0x300 net irq 10 vector epintr 3Com 3C509 (buggy) device fe0 at isa? port 0x240 net irq ? vector feintr Fujitsu MB86960A/MB86965A Ethernet device fea0 at isa? net irq ? vector feaintr DEC DEFEA EISA FDDI adapter device ie0 at isa? port 0x360 net irq 7 iomem 0xd0000 vector ieintr AT&T StarLAN 10 and EN100; 3Com 3C507; unknown NI5210; Intel EtherExpress 16 device le0 at isa? port 0x300 net irq 5 iomem 0xd0000 vector le_intr Digital Equipment EtherWorks 2 and EtherWorks 3 (DEPCA, DE100, DE101, DE200, DE201, DE202, DE203, DE204, DE205, DE422) device lnc0 at isa? port 0x300 net irq 10 drq 0 vector lncintr Lance/PCnet cards (Isolan, Novell NE2100, NE32-VL) device xl0 3Com Etherlink XL series PCI ethernet - controllers (3C905B and related). + controllers (3C905B and related). device ze0 at isa? port 0x300 net irq 5 iomem 0xd8000 vector zeintr IBM/National Semiconductor PCMCIA ethernet controller. device zp0 at isa? port 0x300 net irq 10 iomem 0xd8000 vector zpintr 3Com PCMCIA Etherlink III With certain cards (notably the NE2000) you will have to change the port and/or IRQ since there is no “standard” location for these cards. pseudo-device loop 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. pseudo-device ether ether is only needed if you have an Ethernet card and includes generic Ethernet protocol code. pseudo-device sl number 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 client or server. pseudo-device ppp number 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 kernel-mode PPP section of the handbook. As with the sl device, number specifies how many simultaneous PPP connections to support. pseudo-device tun number 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 user-mode PPP section of the handbook for more information. pseudo-device bpfilter number 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 tcpdump1 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. Sound cards This is the first section containing lines that are not in the GENERIC kernel. To include sound card support, you will have to copy the appropriate lines from the LINT kernel (which contains support for every device) as follows: controller snd0 Generic sound driver code. Required for all of the following sound cards except pca. device pas0 at isa? port 0x388 irq 10 drq 6 vector pasintr ProAudioSpectrum digital audio and MIDI. device sb0 at isa? port 0x220 irq 7 conflicts drq 1 vector sbintr SoundBlaster digital audio. If your SoundBlaster is on a different IRQ (such as 5), change irq 7 to, for example, irq 5 and remove the conflicts keyword. Also, you must add the line: options "SBC_IRQ=5" device sbxvi0 at isa? drq 5 SoundBlaster 16 digital 16-bit audio. If your SB16 is on a different 16-bit DMA channel (such as 6 or 7), change the drq 5 keyword appropriately, and then add the line: options "SB16_DMA=6" device sbmidi0 at isa? port 0x330 SoundBlaster 16 MIDI interface. If you have a SoundBlaster 16, you must include this line, or the kernel will not compile. device gus0 at isa? port 0x220 irq 10 drq 1 vector gusintr Gravis Ultrasound. device mss0 at isa? port 0x530 irq 10 drq 1 vector adintr Microsoft Sound System. device opl0 at isa? port 0x388 conflicts 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). device mpu0 at isa? port 0x330 irq 6 drq 0 Roland MPU-401 stand-alone card. device uart0 at isa? port 0x330 irq 5 vector "m6850intr" Stand-alone 6850 UART for MIDI. device pca0 at isa? port "IO_TIMER1" tty 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). There is some additional documentation in /usr/src/sys/i386/isa/sound/sound.doc. Also, if you add any of these devices, be sure to create the sound device nodes. Pseudo-devices 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 network-related pseudo-devices are in that section, while the remainder are here. pseudo-device gzip gzip allows you to run FreeBSD programs that have been compressed with gzip. The programs in /stand are compressed so it is a good idea to have this option in your kernel. pseudo-device log log is used for logging of kernel error messages. Mandatory. pseudo-device pty number pty 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. The number indicates the number of ptys 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 256. pseudo-device snp number Snoop device. This pseudo-device allows one terminal session to watch another using the watch8 command. Note that implementation of this capability has important security and privacy implications. The number after snp is the total number of simultaneous snoop sessions. Optional. pseudo-device vn Vnode driver. Allows a file to be treated as a device after being set up with the vnconfig8 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. pseudo-device ccd number Concatenated disks. This pseudo-device allows you to concatenate multiple disk partitions into one large “meta”-disk. The number after ccd is the total number of concatenated disks (not total number of disks that can be concatenated) that can be created. (See ccd4 and ccdconfig8 man pages for more details.) Optional. Joystick, PC Speaker, Miscellaneous This section describes some miscellaneous hardware devices supported by FreeBSD. Note that none of these lines are included in the GENERIC kernel, you will have to copy them from this handbook or the LINT kernel (which contains support for every device): device joy0 at isa? port "IO_GAME" PC joystick device. pseudo-device speaker Supports IBM BASIC-style noises through the PC speaker. Some fun programs which use this are /usr/sbin/spkrtest, which is a shell script that plays some simple songs, and /usr/games/piano which lets you play songs using the keyboard as a simple piano (this file only exists if you have installed the games 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. See also the pca0 device. Making Device Nodes Almost every device in the kernel has a corresponding “node” entry in the /dev 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 /dev/MAKEDEV, which is executed when you first install the operating system, creates nearly all of the device nodes supported. However, it does not create all 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 wcd0 in the /dev 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 /dev directory and type: &prompt.root; sh MAKEDEV wcd0 When this script finishes, you will find that there are now wcd0c and rwcd0c entries in /dev so you know that it executed correctly. For sound cards, the command: &prompt.root; sh MAKEDEV snd0 creates the appropriate entries. 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 /etc/fbtab file. See man fbtab for more information. Follow this simple procedure for any other non-GENERIC devices which do not have entries. All SCSI controllers use the same set of /dev entries, so you do not need to create these. Also, network cards and SLIP/PPP pseudo-devices do not have entries in /dev at all, so you do not have to worry about these either. If Something Goes Wrong There are four categories of trouble that can occur when building a custom kernel. They are: Config command fails If the config command fails when you give it your kernel description, you have probably made a simple error somewhere. Fortunately, config will print the line number that it had trouble with, so you can quickly skip to it with vi. For example, if you see: config: line 17: syntax error you can skip to the problem in vi by typing 17G in command mode. Make sure the keyword is typed correctly, by comparing it to the GENERIC kernel or another reference. Make command fails If the make command fails, it usually signals an error in your kernel description, but not severe enough for config 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. Kernel will not boot 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 /var/log/messages file which records, among other things, all of the kernel messages from every successful boot. Also, the dmesg8 command will print the kernel messages from the current boot. 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 kernel.old because when installing a new kernel, kernel.old 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 ps1 will not work properly. The proper command to “unlock” the kernel file that make installs (in order to move another kernel back permanently) is: &prompt.root; 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: &prompt.root; chflags schg /kernel Kernel works, but ps does not work any more! If you have 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 ps1 and vmstat8 will not work any more. You must recompile the libkvm 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. diff --git a/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml index 24883ca2d2..f40cd2f2d3 100644 --- a/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml +++ b/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml @@ -1,1709 +1,1709 @@ Configuring the FreeBSD Kernel Contributed by &a.jehamby;.6 October 1995. 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. Why Build a Custom Kernel? Building a custom kernel is one of the most important rites of passage every Unix system administrator must endure. 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: It will take less time to boot because it does not have to spend time probing for hardware which you do not have. 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. 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 not present in the GENERIC kernel. Building and Installing a Custom Kernel 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. If there is 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: &prompt.root; cd /usr/src/sys/i386/conf &prompt.root; cp GENERIC MYKERNEL 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 MYKERNEL for the purpose of this example. You must execute these and all of the following commands under the root account or you will get permission denied errors. Now, edit MYKERNEL with your favorite text editor. If you are 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 bibliography. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from GENERIC. 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 GENERIC configuration file might seem overwhelming to you, so follow the descriptions in the Configuration File section slowly and carefully. If you are trying to upgrade your kernel from an older version of FreeBSD, you will probably have to get a new version of config8 from the same place you got the new kernel sources. It is located in /usr/src/usr.sbin, so you will need to download those sources as well. Re-build and install it before running the next commands. When you are finished, type the following to compile and install your kernel: &prompt.root; /usr/sbin/config MYKERNEL &prompt.root; cd ../../compile/MYKERNEL &prompt.root; make depend &prompt.root; make &prompt.root; make install The new kernel will be copied to the root directory as /kernel and the old kernel will be moved to /kernel.old. Now, shutdown the system and reboot to use your kernel. In case something goes wrong, there are some troubleshooting instructions at the end of this document. Be sure to read the section which explains how to recover in case your new kernel does not boot. If you have added any new devices (such as sound cards) you may have to add some device nodes to your /dev directory before you can use them. The Configuration File 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 and more detailed explanations of the device lines is present in the LINT configuration file, located in the same directory as GENERIC. If you are in doubt as to the purpose or necessity of a line, check first in LINT. The kernel is currently being moved to a better organization of the option handling. Traditionally, each option in the config file was simply converted into a switch for the CFLAGS line of the kernel Makefile. Naturally, this caused a creeping optionism, with nobody really knowing which option has been referenced in what files. In the new scheme, every #ifdef that is intended to be dependent upon an option gets this option out of an opt_foo.h declaration file created in the compile directory by config. The list of valid options for config lives in two files: options that do not depend on the architecture are listed in /sys/conf/options, architecture-dependent ones in /sys/arch/conf/options.arch, with arch being for example i386. Mandatory Keywords These keywords are required in every kernel you build. machine "i386" The first keyword is machine, which, since FreeBSD only runs on Intel 386 and compatible chips, is i386. 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. cpu "cpu_type" The next keyword is cpu, which includes support for each CPU supported by FreeBSD. The possible values of cpu_type include: I386_CPU I486_CPU I586_CPU I686_CPU Multiple instances of the cpu line may be present with different values of cpu_type 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 I586_CPU for cpu_type. ident machine_name 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 is 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. Since this name is passed to the C compiler as a switch, do not use names like DEBUG, or something that could be confused with another machine or CPU name, like vax. maxusers number 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 4, especially if you are using the X Window System or compiling software. The reason is that the most important table set by maxusers is the maximum number of processes, which is set to 20 + 16 * maxusers, so if you set maxusers 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 maxusers 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. 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 pseudo-device pty 16. config kernel_name root on root_device 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. General Options These lines provide kernel support for various filesystems and other options. options MATH_EMULATE 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 Pentium, a 486DX, or a 386 or 486SX with a separate 387 or 487 chip, you can comment this line out. The normal math co-processor emulation routines that come with FreeBSD are not very accurate. If you do not have a math co-processor, and you need the best accuracy, I recommend that you change this option to GPL_MATH_EMULATE to use the superior GNU math support, which is not included by default for licensing reasons. options "COMPAT_43" Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out. options BOUNCE_BUFFERS ISA devices and EISA devices operating in an ISA compatibility 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. options UCONSOLE Allow users to grab the console, useful for X Windows. For example, you can create a console xterm by typing xterm -C, which will display any write, talk, and other messages you receive, as well as any console messages sent by the kernel. options SYSVSHM 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 the X Window System, you will definitely want to include this. options SYSVSEM Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel. options SYSVMSG Support for System V messages. Again, only adds a few hundred bytes to the kernel. The ipcs1 command will tell will list any processes using each of these System V facilities. Filesystem 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. options FFS The basic hard drive filesystem; leave it in if you boot from the hard disk. options NFS Network Filesystem. Unless you plan to mount partitions from a Unix file server over Ethernet, you can comment this out. options MSDOSFS 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). options "CD9660" 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. options PROCFS Process filesystem. This is a pretend filesystem mounted on /proc which allows programs like ps1 to give you more information on what processes are running. options MFS 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: /dev/wd1s2b /tmp mfs rw 0 0 Replace the /dev/wd1s2b with the name of your swap partition, which will be listed in your /etc/fstab as follows: /dev/wd1s2b none swap sw 0 0 Also, the MFS filesystem can not be dynamically loaded, so you must compile it into your kernel if you want to experiment with it. options "EXT2FS" Linux's native file system. With ext2fs support you are able to read and write to Linux partitions. This is useful if you dual-boot FreeBSD and Linux and want to share data between the two systems. options QUOTA 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. Refer to the Disk Quotas section for more information. Basic Controllers and Devices These sections describe the basic disk, tape, and CD-ROM controllers supported by FreeBSD. There are separate sections for SCSI controllers and network cards. controller isa0 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. controller pci0 Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to the ISA bus. controller fdc0 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. QIC-80 tape support requires a separate filter program called ft8, see the manual page for details. controller wdc0 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 will probably want to comment out all six lines, for example). device wcd0 This device provides IDE CD-ROM support. Be sure to leave wdc0 uncommented, and wdc1 if you have more than one IDE controller and your CD-ROM is on the second one card. To use this, you must also include the line options ATAPI. device npx0 at isa? port "IO_NPX" irq 13 vector npxintr npx0 is the interface to the floating point math unit in FreeBSD, either the hardware co-processor or the software math emulator. It is not optional. device wt0 at isa? port 0x300 bio irq 5 drq 1 vector wtintr Wangtek and Archive QIC-02/QIC-36 tape drive support Proprietary CD-ROM 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 IDE or SCSI. device mcd0 at isa? port 0x300 bio irq 10 vector mcdintr Mitsumi CD-ROM (LU002, LU005, FX001D). device scd0 at isa? port 0x230 bio Sony CD-ROM (CDU31, CDU33A). controller matcd0 at isa? port ? bio Matsushita/Panasonic CD-ROM (sold by Creative Labs for SoundBlaster). SCSI Device Support This section describes the various SCSI controllers and devices supported by FreeBSD. SCSI Controllers The next ten or so lines include support for different kinds of SCSI controllers. Comment out all except for the one(s) you have: controller bt0 at isa? port "IO_BT0" bio irq ? vector btintr Most Buslogic controllers controller uha0 at isa? port "IO_UHA0" bio irq ? drq 5 vector uhaintr UltraStor 14F and 34F controller ahc0 Adaptec 274x/284x/294x controller ahb0 at isa? bio irq ? vector ahbintr Adaptec 174x controller aha0 at isa? port "IO_AHA0" bio irq ? drq 5 vector ahaintr Adaptec 154x controller aic0 at isa? port 0x340 bio irq 11 vector aicintr Adaptec 152x and sound cards using Adaptec AIC-6360 (slow!) controller nca0 at isa? port 0x1f88 bio irq 10 vector ncaintr ProAudioSpectrum cards using NCR 5380 or Trantor T130 controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr Seagate ST01/02 8 bit controller (slow!) controller wds0 at isa? port 0x350 bio irq 15 drq 6 vector wdsintr Western Digital WD7000 controller controller ncr0 NCR 53C810, 53C815, 53C825, 53C860, 53C875 PCI SCSI controller options "SCSI_DELAY=15" 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 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. controller scbus0 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. device sd0 Support for SCSI hard drives. device st0 Support for SCSI tape drives. device cd0 Support for SCSI CD-ROM drives. Note that the number 0 in the above entries is slightly misleading: all these devices are automatically configured as they are found, regardless of how many of them are hooked up to the SCSI bus(es), and which target IDs they have. If you want to “wire down” specific target IDs to particular devices, refer to the appropriate section of the LINT kernel config file. Console, Bus Mouse, and X Server Support You must choose one of these two console types, and, if you plan to use the X Window System with the vt220 console, enable the XSERVER option and optionally, a bus mouse or PS/2 mouse device. device sc0 at isa? port "IO_KBD" tty irq 1 vector scintr 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. device vt0 at isa? port "IO_KBD" tty irq 1 vector pcrint 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 vt100 or vt220 when you log in. This driver might also prove useful when connecting to a large number of different machines over the network, where the termcap or terminfo entries for the sc0 device are often not available — vt100 should be available on virtually any platform. options "PCVT_FREEBSD=210" Required with the vt0 console driver. options XSERVER Only applicable with the vt0 console driver. This includes code required to run the XFree86 X Window Server under the vt0 console driver. device mse0 at isa? port 0x23c tty irq 5 vector ms Use this device if you have a Logitech or ATI InPort bus mouse card. If you have a serial mouse, ignore these two lines, and instead, make sure the appropriate serial port is enabled (probably COM1). device psm0 at isa? port "IO_KBD" conflicts tty irq 12 vector psmintr Use this device if your mouse plugs into the PS/2 mouse port. Serial and Parallel Ports Nearly all systems have these. If you are attaching a printer to one of these ports, the Printing section of the handbook is very useful. If you are using modem, Dialup access provides extensive detail on serial port configuration for use with such devices. device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr 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 sio4 for more information on the proper values for these lines. Some video cards (notably those based on S3 chips) use IO addresses of the form 0x*2e8, 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. 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. device lpt0 at isa? port? tty irq 7 vector lptintr 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. Networking 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. options INET 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. Ethernet cards 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 will want to leave in support for your particular Ethernet card(s): device de0 Ethernet adapters based on Digital Equipment DC21040, DC21041 or DC21140 chips device fxp0 Intel EtherExpress Pro/100B device vx0 3Com 3C590 and 3C595 (buggy) device cx0 at isa? port 0x240 net irq 15 drq 7 vector cxintr Cronyx/Sigma multiport sync/async (with Cisco or PPP framing) device ed0 at isa? port 0x280 net irq 5 iomem 0xd8000 vector edintr Western Digital and SMC 80xx and 8216; Novell NE1000 and NE2000; 3Com 3C503; HP PC Lan Plus (HP27247B and HP27252A) device el0 at isa? port 0x300 net irq 9 vector elintr 3Com 3C501 (slow!) device eg0 at isa? port 0x310 net irq 5 vector egintr 3Com 3C505 device ep0 at isa? port 0x300 net irq 10 vector epintr 3Com 3C509 (buggy) device fe0 at isa? port 0x240 net irq ? vector feintr Fujitsu MB86960A/MB86965A Ethernet device fea0 at isa? net irq ? vector feaintr DEC DEFEA EISA FDDI adapter device ie0 at isa? port 0x360 net irq 7 iomem 0xd0000 vector ieintr AT&T StarLAN 10 and EN100; 3Com 3C507; unknown NI5210; Intel EtherExpress 16 device le0 at isa? port 0x300 net irq 5 iomem 0xd0000 vector le_intr Digital Equipment EtherWorks 2 and EtherWorks 3 (DEPCA, DE100, DE101, DE200, DE201, DE202, DE203, DE204, DE205, DE422) device lnc0 at isa? port 0x300 net irq 10 drq 0 vector lncintr Lance/PCnet cards (Isolan, Novell NE2100, NE32-VL) device xl0 3Com Etherlink XL series PCI ethernet - controllers (3C905B and related). + controllers (3C905B and related). device ze0 at isa? port 0x300 net irq 5 iomem 0xd8000 vector zeintr IBM/National Semiconductor PCMCIA ethernet controller. device zp0 at isa? port 0x300 net irq 10 iomem 0xd8000 vector zpintr 3Com PCMCIA Etherlink III With certain cards (notably the NE2000) you will have to change the port and/or IRQ since there is no “standard” location for these cards. pseudo-device loop 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. pseudo-device ether ether is only needed if you have an Ethernet card and includes generic Ethernet protocol code. pseudo-device sl number 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 client or server. pseudo-device ppp number 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 kernel-mode PPP section of the handbook. As with the sl device, number specifies how many simultaneous PPP connections to support. pseudo-device tun number 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 user-mode PPP section of the handbook for more information. pseudo-device bpfilter number 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 tcpdump1 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. Sound cards This is the first section containing lines that are not in the GENERIC kernel. To include sound card support, you will have to copy the appropriate lines from the LINT kernel (which contains support for every device) as follows: controller snd0 Generic sound driver code. Required for all of the following sound cards except pca. device pas0 at isa? port 0x388 irq 10 drq 6 vector pasintr ProAudioSpectrum digital audio and MIDI. device sb0 at isa? port 0x220 irq 7 conflicts drq 1 vector sbintr SoundBlaster digital audio. If your SoundBlaster is on a different IRQ (such as 5), change irq 7 to, for example, irq 5 and remove the conflicts keyword. Also, you must add the line: options "SBC_IRQ=5" device sbxvi0 at isa? drq 5 SoundBlaster 16 digital 16-bit audio. If your SB16 is on a different 16-bit DMA channel (such as 6 or 7), change the drq 5 keyword appropriately, and then add the line: options "SB16_DMA=6" device sbmidi0 at isa? port 0x330 SoundBlaster 16 MIDI interface. If you have a SoundBlaster 16, you must include this line, or the kernel will not compile. device gus0 at isa? port 0x220 irq 10 drq 1 vector gusintr Gravis Ultrasound. device mss0 at isa? port 0x530 irq 10 drq 1 vector adintr Microsoft Sound System. device opl0 at isa? port 0x388 conflicts 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). device mpu0 at isa? port 0x330 irq 6 drq 0 Roland MPU-401 stand-alone card. device uart0 at isa? port 0x330 irq 5 vector "m6850intr" Stand-alone 6850 UART for MIDI. device pca0 at isa? port "IO_TIMER1" tty 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). There is some additional documentation in /usr/src/sys/i386/isa/sound/sound.doc. Also, if you add any of these devices, be sure to create the sound device nodes. Pseudo-devices 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 network-related pseudo-devices are in that section, while the remainder are here. pseudo-device gzip gzip allows you to run FreeBSD programs that have been compressed with gzip. The programs in /stand are compressed so it is a good idea to have this option in your kernel. pseudo-device log log is used for logging of kernel error messages. Mandatory. pseudo-device pty number pty 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. The number indicates the number of ptys 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 256. pseudo-device snp number Snoop device. This pseudo-device allows one terminal session to watch another using the watch8 command. Note that implementation of this capability has important security and privacy implications. The number after snp is the total number of simultaneous snoop sessions. Optional. pseudo-device vn Vnode driver. Allows a file to be treated as a device after being set up with the vnconfig8 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. pseudo-device ccd number Concatenated disks. This pseudo-device allows you to concatenate multiple disk partitions into one large “meta”-disk. The number after ccd is the total number of concatenated disks (not total number of disks that can be concatenated) that can be created. (See ccd4 and ccdconfig8 man pages for more details.) Optional. Joystick, PC Speaker, Miscellaneous This section describes some miscellaneous hardware devices supported by FreeBSD. Note that none of these lines are included in the GENERIC kernel, you will have to copy them from this handbook or the LINT kernel (which contains support for every device): device joy0 at isa? port "IO_GAME" PC joystick device. pseudo-device speaker Supports IBM BASIC-style noises through the PC speaker. Some fun programs which use this are /usr/sbin/spkrtest, which is a shell script that plays some simple songs, and /usr/games/piano which lets you play songs using the keyboard as a simple piano (this file only exists if you have installed the games 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. See also the pca0 device. Making Device Nodes Almost every device in the kernel has a corresponding “node” entry in the /dev 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 /dev/MAKEDEV, which is executed when you first install the operating system, creates nearly all of the device nodes supported. However, it does not create all 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 wcd0 in the /dev 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 /dev directory and type: &prompt.root; sh MAKEDEV wcd0 When this script finishes, you will find that there are now wcd0c and rwcd0c entries in /dev so you know that it executed correctly. For sound cards, the command: &prompt.root; sh MAKEDEV snd0 creates the appropriate entries. 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 /etc/fbtab file. See man fbtab for more information. Follow this simple procedure for any other non-GENERIC devices which do not have entries. All SCSI controllers use the same set of /dev entries, so you do not need to create these. Also, network cards and SLIP/PPP pseudo-devices do not have entries in /dev at all, so you do not have to worry about these either. If Something Goes Wrong There are four categories of trouble that can occur when building a custom kernel. They are: Config command fails If the config command fails when you give it your kernel description, you have probably made a simple error somewhere. Fortunately, config will print the line number that it had trouble with, so you can quickly skip to it with vi. For example, if you see: config: line 17: syntax error you can skip to the problem in vi by typing 17G in command mode. Make sure the keyword is typed correctly, by comparing it to the GENERIC kernel or another reference. Make command fails If the make command fails, it usually signals an error in your kernel description, but not severe enough for config 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. Kernel will not boot 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 /var/log/messages file which records, among other things, all of the kernel messages from every successful boot. Also, the dmesg8 command will print the kernel messages from the current boot. 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 kernel.old because when installing a new kernel, kernel.old 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 ps1 will not work properly. The proper command to “unlock” the kernel file that make installs (in order to move another kernel back permanently) is: &prompt.root; 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: &prompt.root; chflags schg /kernel Kernel works, but ps does not work any more! If you have 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 ps1 and vmstat8 will not work any more. You must recompile the libkvm 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.