(Removed redundant linefeeds for neatness.)
[ikiwiki.git] / docs / newhandbook / ConfigureKernel / index.mdwn
1 # Configuring the DragonFly Kernel 
2
3 ***Updated and restructured by Jim Mock. Originally contributed by Jake Hamby.***
4
5 [[!toc  levels=3]]
6
7 ## Synopsis 
8
9 The kernel is the core of the DragonFly operating system. It is responsible for managing memory, enforcing security controls, networking, disk access, and much more. While more and more of DragonFly becomes dynamically configurable it is still occasionally necessary to reconfigure and recompile your kernel.
10
11 After reading this chapter, you will know:
12
13 * Why you might need to build a custom kernel.
14 * How to write a kernel configuration file, or alter an existing configuration file.
15 * How to use the kernel configuration file to create and build a new kernel.
16 * How to install the new kernel.
17 * How to troubleshoot if things go wrong.
18
19 ## Why Build a Custom Kernel? 
20
21 Traditionally, DragonFly has had what is called a ***monolithic*** kernel. This means that the kernel was one large program, supported a fixed list of devices, and if you wanted to change the kernel's behavior then you had to compile a new kernel, and then reboot your computer with the new kernel.
22
23 Today, DragonFly is rapidly moving to a model where much of the kernel's functionality is contained in modules which can be dynamically loaded and unloaded from the kernel as necessary. This allows the kernel to adapt to new hardware suddenly becoming available (such as PCMCIA cards in a laptop), or for new functionality to be brought into the kernel that was not necessary when the kernel was originally compiled. This is known as a modular kernel. Colloquially these are called KLDs.
24
25 Despite this, it is still necessary to carry out some static kernel configuration. In some cases this is because the functionality is so tied to the kernel that it can not be made dynamically loadable. In others it may simply be because no one has yet taken the time to write a dynamic loadable kernel module for that functionality yet.
26
27 Building a custom kernel is one of the most important rites of passage nearly every UNIX® user must endure. This process, while time consuming, will provide many benefits to your DragonFly system. Unlike the `GENERIC` kernel, which must support a wide range of hardware, a custom kernel only contains support for ***your*** PC's hardware. This has a number of benefits, such as:
28
29 * Faster boot time. Since the kernel will only probe the hardware you have on your system, the time it takes your system to boot will decrease dramatically.
30
31 * Less memory usage. A custom kernel often uses less memory than the `GENERIC` kernel, which is important because the kernel must always be present in real memory. For this reason, a custom kernel is especially useful on a system with a small amount of RAM.
32
33 * Additional hardware support. A custom kernel allows you to add in support for devices such as sound cards, which are not present in the `GENERIC` kernel.
34
35 ## Building and Installing a Custom Kernel 
36
37 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, is `config`, 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 structure, with each supported device, file system, and option in its own subdirectory.
38
39 ### Installing the Source
40
41 If there is ***no*** `/usr/src/sys` directory on your system, then the kernel source has not been installed. One method to do this is via git.  An alternative is to install the kernel source tree from the archive distributed on the DragonFly CD named `src-sys.tar.bz2`.  This is especially useful when you do not have ready access to the internet. Use the Makefile in `/usr` to fetch the source or to unpack the archive. When installing kernel source only, use the alternate build procedure below.
42
43 The preferred way of installing the sources is:
44
45     # cd /usr
46     # make src-create
47     
48 This will download the whole source tree via git into /usr/src. This method also allows for easy updating of the source tree by using:
49
50     # make src-update
51
52 ### Your Custom Config File
53
54 Next, move to the `config` directory and copy the `GENERIC` configuration file to the name you want to give your kernel. For example:
55
56     # cd /usr/src/sys/config
57     # cp GENERIC MYKERNEL
58
59 Traditionally, this name is in all capital letters and, if you are maintaining multiple DragonFly 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.
60
61 **Tip:** Storing your kernel config file directly under `/usr/src` can be a bad idea. If you are experiencing problems it can be tempting to just delete `/usr/src` and start again. Five seconds after you do that you realize that you have deleted your custom kernel config file. Do not edit `GENERIC` directly, as it may get overwritten the next time you [update your source tree](updating.html#UPDATING-SETUP), and your kernel modifications will be lost.  You might want to keep your kernel config file elsewhere, and then create a symbolic link to the file in the `config` directory.
62
63 For example:
64
65     # cd /usr/src/sys/config
66     # mkdir /root/kernels
67     # cp GENERIC /root/kernels/MYKERNEL
68     # ln -s /root/kernels/MYKERNEL
69
70 **Note:** You must execute these and all of the following commands under the `root` account or you will get permission denied errors.
71
72 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](bibliography.html). However, DragonFly does offer an easier editor called ***ee*** which, if you are a beginner, should be your editor of choice. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from `GENERIC`.
73
74 If you have built 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|handbook-kernelconfig-config]] section slowly and carefully.
75
76 ### Building a Kernel - Full Source Tree
77
78 **Note:** Be sure to always check the file `/usr/src/UPDATING`, before you perform any update steps, in the case you [sync your source tree](updating.html#UPDATING-SETUP) with the latest sources of the DragonFly project. In this file all important issues with updating DragonFly are typed out. `/usr/src/UPDATING` always fits your version of the DragonFly source, and is therefore more accurate for new information than the handbook.
79
80  1. Change to the `/usr/src` directory.
81
82      
83
84           # cd /usr/src
85
86  1. Compile the kernel.
87
88           # make buildkernel KERNCONF=MYKERNEL
89
90  1. Install the new kernel.     
91
92           # make installkernel KERNCONF=MYKERNEL
93
94     
95
96 If you have ***not*** upgraded your source tree in any way since the last time you successfully completed a `buildworld`-`installworld` cycle (you have not run `git pull` ), then it is safe to use the `quickworld` and `quickkernel`, `buildworld`, `buildkernel` sequence.
97
98 ### Building a Kernel - Kernel Source Only
99
100 When only the kernel source is installed, you need to change step 2, above, to this:
101      
102
103       # make nativekernel KERNCONF=MYKERNEL
104
105 The other steps are the same.
106
107 ### Running Your New Kernel
108
109 The installer copies the new kernel and modules to `/boot/kernel/`, the kernel being `/boot/kernel/kernel` and the modules being `/boot/kernel/*.ko`. The old kernel and modules are moved to `/boot/kernel.old/`. Now, shutdown the system and reboot to use your new kernel. In case something goes wrong, there are some [troubleshooting](kernelconfig-trouble.html) instructions at the end of this chapter. Be sure to read the section which explains how to recover in case your new kernel [does not boot](kernelconfig-trouble.html#KERNELCONFIG-NOBOOT).
110
111 **Note:** 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. For more information, take a look at device nodes section later on in this chapter.
112
113 ## The Configuration File 
114 <!-- XXX: do we really want to mention all these million config options? -->
115 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`.
116
117 The following is an example `GENERIC` kernel configuration file with various additional comments where needed for clarity. This example should match your copy in `/usr/src/sys/config/GENERIC` fairly closely. For details of all the possible kernel options, see `/usr/src/sys/config/LINT`.
118
119     
120
121     #
122
123     #
124
125     # GENERIC -- Generic kernel configuration file for DragonFly/i386
126
127     #
128
129     # Check the LINT configuration file in sys/config, for an
130
131     # exhaustive list of options.
132
133     #
134
135     # $DragonFly: src/sys/config/GENERIC,v 1.56 2007/12/26 14:02:36 sephe Exp $
136
137 The following are the mandatory keywords required in ***every*** kernel you build:
138
139     
140
141     machine         i386
142
143 This is the machine architecture. It must be `i386` at the moment.  Support for `amd64` will be added in the future.
144
145     
146
147     cpu          I386_CPU
148
149     cpu          I486_CPU
150
151     cpu          I586_CPU
152
153     cpu          I686_CPU
154
155 The above option specifies the type of CPU you have in your system. You may have multiple instances of the CPU line (i.e., you are not sure whether you should use `I586_CPU` or `I686_CPU`), however, for a custom kernel, it is best to specify only the CPU you have. If you are unsure of your CPU type, you can check the `/var/run/dmesg.boot` file to view your boot up messages.
156
157     
158
159     ident          GENERIC
160
161 This is the identification of the kernel. You should change this to whatever you named your kernel, i.e. `MYKERNEL` if you have followed the instructions of the previous examples. The value you put in the `ident` string will print when you boot up the kernel, so it is useful to give the new kernel a different name if you want to keep it separate from your usual kernel (i.e. you want to build an experimental kernel).
162
163     
164
165     maxusers          0
166
167 The `maxusers` option sets the size of a number of important system tables. This number is supposed to be roughly equal to the number of simultaneous users you expect to have on your machine.
168
169 (Recommended) The system will auto-tune this setting for you if you explicitly set it to `0`[(1)](#FTN.AEN7414). If you want to manage it yourself 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 manual page will start up nine processes to filter, decompress, and view it. Setting `maxusers` to 64 will allow you to have up to 1044 simultaneous processes, which should be enough for nearly all uses. If, however, you see the dreaded proc table full error when trying to start another program, or are running a server with a large number of simultaneous users, you can always increase the number and rebuild.
170
171  **Note:** `maxusers` 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 and X terminal windows*** is [kernelconfig-config.html#KERNELCONFIG-PTYS `pseudo-device pty 16`].
172
173     
174
175     # Floating point support - do not disable.
176
177     device          npx0     at nexus? port IO_NPX irq 13
178
179 `npx0` is the interface to the floating point math unit in DragonFly, which is either the hardware co-processor or the software math emulator. This is ***not*** optional.
180
181     
182
183     # Pseudo devices - the number indicates how many units to allocate.
184
185     pseudo-device   loop          # Network loopback
186
187 This 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 device. This is ***mandatory***.
188
189 Everything that follows is more or less optional. See the notes underneath or next to each option for more information.
190
191     
192
193     #makeoptions     DEBUG=-g          #Build kernel with gdb(1) debug symbols
194
195 The normal build process of the DragonFly does not include debugging information when building the kernel and strips most symbols after the resulting kernel is linked, to save some space at the install location. If you are going to do tests of kernels in the DEVELOPMENT branch or develop changes of your own for the DragonFly kernel, you might want to uncomment this line. It will enable the use of the `-g` option which enables debugging information when passed to [gcc(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#gcc&section1).
196
197     
198
199     options          MATH_EMULATE      #Support for x87 emulation
200
201 This line allows the kernel to simulate a math co-processor if your computer does not have one (386 or 486SX). If you have a 486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or higher (Pentium®, Pentium II, etc.), you can comment this line out.
202
203  **Note:** The normal math co-processor emulation routines that come with DragonFly are ***not*** very accurate. If you do not have a math co-processor, and you need the best accuracy, it is recommended that you change this option to `GPL_MATH_EMULATE` to use the GNU math support, which is not included by default for licensing reasons.
204
205     
206
207     options          INET          #InterNETworking
208
209 Networking support. Leave this in, even if you do not plan to be connected to a network. Most programs require at least loopback networking (i.e., making network connections within your PC), so this is essentially mandatory.
210
211     
212
213     options          INET6          #IPv6 communications protocols
214
215 This enables the IPv6 communication protocols.
216
217     
218
219     options          FFS          #Berkeley Fast Filesystem
220
221     options          FFS_ROOT     #FFS usable as root device [keep this!]
222
223 This is the basic hard drive Filesystem. Leave it in if you boot from the hard disk.
224
225     
226
227     options          UFS_DIRHASH  #Improve performance on big directories
228
229 This option includes functionality to speed up disk operations on large directories, at the expense of using additional memory. You would normally keep this for a large server, or interactive workstation, and remove it if you are using DragonFly on a smaller system where memory is at a premium and disk access speed is less important, such as a firewall.
230
231     
232
233     options          SOFTUPDATES  #Enable FFS Soft Updates support
234
235 This option enables Soft Updates in the kernel, this will help speed up write access on the disks. Even when this functionality is provided by the kernel, it must be turned on for specific disks. Review the output from [mount(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#mount&section8) to see if Soft Updates is enabled for your system disks. If you do not see the `soft-updates` option then you will need to activate it using the [tunefs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=tunefs&section=8) (for existing filesystems) or [newfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newfs&section=8) (for new filesystems) commands.
236
237     
238
239     options          MFS          #Memory Filesystem
240
241     options          MD_ROOT      #MD is a potential root device
242
243 This is the memory-mapped filesystem. This is basically a RAM disk for fast storage of temporary files, useful if you have a lot of swap space that you want to take advantage of. A perfect place to mount an MFS partition is on the `/tmp` directory, since many programs store temporary data here. To mount an MFS RAM disk on `/tmp`, add the following line to `/etc/fstab`:
244
245     
246
247     /dev/ad1s2b     /tmp mfs rw 0 0
248
249 Now you simply need to either reboot, or run the command `mount /tmp`.
250
251     
252
253     options          NFS          #Network Filesystem
254
255     options          NFS_ROOT     #NFS usable as root device, NFS required
256
257 The network Filesystem. Unless you plan to mount partitions from a UNIX® file server over TCP/IP, you can comment these out.
258
259     
260
261     options          MSDOSFS      #MSDOS Filesystem
262
263 The MS-DOS® Filesystem. Unless you plan to mount a DOS formatted hard drive partition at boot time, you can safely comment this out. It will be automatically loaded the first time you mount a DOS partition, as described above. Also, the excellent ***mtools*** software (in pkgsrc®) allows you to access DOS floppies without having to mount and unmount them (and does not require `MSDOSFS` at all).
264
265     
266
267     options          CD9660       #ISO 9660 Filesystem
268
269     options          CD9660_ROOT  #CD-ROM usable as root, CD9660 required
270
271 The ISO 9660 Filesystem for CDROMs. Comment it out if you do not have a CDROM drive or only mount data CDs occasionally (since it will be dynamically loaded the first time you mount a data CD). Audio CDs do not need this Filesystem.
272
273     
274
275     options          PROCFS       #Process filesystem
276
277 The process filesystem. This is a ***pretend*** filesystem mounted on `/proc` which allows programs like [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps&section1) to give you more information on what processes are running. ***
278
279     
280
281 Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out.
282
283     
284
285     options          SCSI_DELAY=5000    #Delay (in ms) before probing SCSI
286
287 This causes the kernel to pause for 15 seconds before probing each SCSI device in your system. If you only have IDE hard drives, you can ignore this, otherwise you will probably want to lower this number, perhaps to five seconds (5000 ms), to speed up booting. Of course, if you do this, and DragonFly has trouble recognizing your SCSI devices, you will have to raise it back up.
288
289     
290
291     options          UCONSOLE            #Allow users to grab the console
292
293 Allow users to grab the console, which is useful for X users. For example, you can create a console ***xterm*** by typing `xterm -C`, which will display any [write(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#write&section1), [talk(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=talk&section=1), and any other messages you receive, as well as any console messages sent by the kernel.
294
295     
296
297     options          USERCONFIG          #boot -c editor
298
299 This option allows you to boot the configuration editor from the boot menu.
300
301     
302
303     options          VISUAL_USERCONFIG   #visual boot -c editor
304
305 This option allows you to boot the visual configuration editor from the boot menu.
306
307     
308
309     options          KTRACE              #ktrace(1) support
310
311 This enables kernel process tracing, which is useful in debugging.
312
313     
314
315     options          SYSVSHM             #SYSV-style shared memory
316
317 This option provides for System V shared memory. The most common use of this is the XSHM extension in X, which many graphics-intensive programs will automatically take advantage of for extra speed. If you use X, you will definitely want to include this.
318
319     
320
321     options          SYSVSEM             #SYSV-style semaphores
322
323 Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel.
324
325     
326
327     options          SYSVMSG             #SYSV-style message queues
328
329 Support for System V messages. Again, only adds a few hundred bytes to the kernel.
330
331  **Note:** The [ipcs(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ipcs&section1) command will list any processes using each of these System V facilities.
332
333     
334
335     options         P1003_1B                #Posix P1003_1B real-time extensions
336
337     options         _KPOSIX_PRIORITY_SCHEDULING
338
339 Real-time extensions added in the 1993 POSIX®. Certain applications in the ports collection use these (such as  **StarOffice™** ).
340
341     
342
343     options         ICMP_BANDLIM            #Rate limit bad replies
344
345 This option enables ICMP error response bandwidth limiting. You typically want this option as it will help protect the machine from denial of service packet attacks.
346
347     
348
349     # To make an SMP kernel, the next two are needed
350
351     #options        SMP                     # Symmetric MultiProcessor Kernel
352
353     #options        APIC_IO                 # Symmetric (APIC) I/O
354
355 The above are both required for SMP support.
356
357     
358
359     device          isa
360
361 All PCs supported by DragonFly have one of these. Do not remove, even if you have no ISA slots. If you have an IBM PS/2 (Micro Channel Architecture), DragonFly provides some limited support at this time. For more information about the MCA support, see `/usr/src/sys/config/LINT`.
362
363     
364
365     device          eisa
366
367 Include this if you have an EISA motherboard. This enables auto-detection and configuration support for all devices on the EISA bus.
368
369     
370
371     device          pci
372
373 Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to ISA bus.
374
375     
376
377     device          agp
378
379 Include this if you have an AGP card in the system. This will enable support for AGP, and AGP GART for boards which have these features.
380
381     
382
383     # Floppy drives
384
385     device          fdc0        at isa? port IO_FD1 irq 6 drq 2
386
387     device          fd0         at fdc0 drive 0
388
389     device          fd1         at fdc0 drive 1
390
391 This is the floppy drive controller. `fd0` is the `A:` floppy drive, and `fd1` is the `B:` drive.
392
393     
394
395     device          ata
396
397 This driver supports all ATA and ATAPI devices. You only need one `device ata` line for the kernel to detect all PCI ATA/ATAPI devices on modern machines.
398
399     
400
401     device          atadisk                 # ATA disk drives
402
403 This is needed along with `device ata` for ATA disk drives.
404
405     
406
407     device          atapicd                 # ATAPI CDROM drives
408
409 This is needed along with `device ata` for ATAPI CDROM drives.
410
411     
412
413     device          atapifd                 # ATAPI floppy drives
414
415 This is needed along with `device ata` for ATAPI floppy drives.
416
417     
418
419     device          atapist                 # ATAPI tape drives
420
421 This is needed along with `device ata` for ATAPI tape drives.
422
423     
424
425     options         ATA_STATIC_ID           #Static device numbering
426
427 This makes the controller number static (like the old driver) or else the device numbers are dynamically allocated.
428
429     
430
431     # ATA and ATAPI devices
432
433     device          ata0        at isa? port IO_WD1 irq 14
434
435     device          ata1        at isa? port IO_WD2 irq 15
436
437 Use the above for older, non-PCI systems.
438
439     
440
441     # SCSI Controllers
442
443     device          ahb        # EISA AHA1742 family
444
445     device          ahc        # AHA2940 and onboard AIC7xxx devices
446
447     device          amd        # AMD 53C974 (Teckram DC-390(T))
448
449     device          dpt        # DPT Smartcache - See LINT for options!
450
451     device          isp        # Qlogic family
452
453     device          ncr        # NCR/Symbios Logic
454
455     device          sym        # NCR/Symbios Logic (newer chipsets)
456
457     device          adv0       at isa?
458
459     device          adw
460
461     device          bt0        at isa?
462
463     device          aha0       at isa?
464
465     device          aic0       at isa?
466
467 SCSI controllers. Comment out any you do not have in your system. If you have an IDE only system, you can remove these altogether.
468
469     
470
471     # SCSI peripherals
472
473     device          scbus      # SCSI bus (required)
474
475     device          da         # Direct Access (disks)
476
477     device          sa         # Sequential Access (tape etc)
478
479     device          cd         # CD
480
481     device          pass       # Passthrough device (direct SCSI
482
483     access)
484
485 SCSI peripherals. Again, comment out any you do not have, or if you have only IDE hardware, you can remove them completely.
486
487  **Note:** The USB [umass(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#umass&section4) driver (and a few other drivers) use the SCSI subsystem even though they are not real SCSI devices. Therefore make sure not to remove SCSI support, if any such drivers are included in the kernel configuration.
488
489     
490
491     # RAID controllers
492
493     device          ida        # Compaq Smart RAID
494
495     device          amr        # AMI MegaRAID
496
497     device          mlx        # Mylex DAC960 family
498
499 Supported RAID controllers. If you do not have any of these, you can comment them out or remove them.
500
501     
502
503     # atkbdc0 controls both the keyboard and the PS/2 mouse
504
505     device          atkbdc0    at isa? port IO_KBD
506
507 The keyboard controller (`atkbdc`) provides I/O services for the AT keyboard and PS/2 style pointing devices. This controller is required by the keyboard driver (`atkbd`) and the PS/2 pointing device driver (`psm`).
508
509     
510
511     device          atkbd0     at atkbdc? irq 1
512
513 The `atkbd` driver, together with `atkbdc` controller, provides access to the AT 84 keyboard or the AT enhanced keyboard which is connected to the AT keyboard controller.
514
515     
516
517     device          psm0       at atkbdc? irq 12
518
519 Use this device if your mouse plugs into the PS/2 mouse port.
520
521     
522
523     device          vga0        at isa?
524
525 The video card driver.
526
527     
528
529     # splash screen/screen saver
530
531     pseudo-device          splash
532
533 Splash screen at start up! Screen savers require this too.
534
535     
536
537     # syscons is the default console driver, resembling an SCO console
538
539     device          sc0          at isa?
540
541 `sc0` is the default console driver, which resembles a SCO console. Since most full-screen programs access the console through a terminal database library like `termcap`, it should not matter 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.
542
543     
544
545     # Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
546
547     #device          vt0     at isa?
548
549     #options         XSERVER          # support for X server on a vt console
550
551     #options         FAT_CURSOR       # start with block cursor
552
553     # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
554
555     #options         PCVT_SCANSET=2   # IBM keyboards are non-std
556
557 This is a VT220-compatible console driver, backward 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 `termcap` or `terminfo` entries for the `sc0` device are often not available -- `vt100` should be available on virtually any platform.
558
559     
560
561     # Power management support (see LINT for more options)
562
563     device          apm0     at nexus? disable flags 0x20  # Advanced Power Management
564
565 Advanced Power Management support. Useful for laptops.
566
567     
568
569     # PCCARD (PCMCIA) support
570
571     device          card
572
573     device          pcic0    at isa? irq 10 port 0x3e0 iomem 0xd0000
574
575     device          pcic1    at isa? irq 11 port 0x3e2 iomem 0xd4000 disable
576
577 PCMCIA support. You want this if you are using a laptop.
578
579     
580
581     # Serial (COM) ports
582
583     device          sio0     at isa? port IO_COM1 flags 0x10 irq 4
584
585     device          sio1     at isa? port IO_COM2 irq 3
586
587     device          sio2     at isa? disable port IO_COM3 irq 5
588
589     device          sio3     at isa? disable port IO_COM4 irq 9
590
591 These are the four serial ports referred to as COM1 through COM4 in the MS-DOS/Windows® world.
592
593  **Note:** If you have an internal modem on COM4 and a serial port at COM2, you will have to change the IRQ of the modem to 2 (for obscure technical reasons, IRQ2 # IRQ 9) in order to access it from DragonFly. If you have a multiport serial card, check the manual page for [sio(4)](http://leaf.dragonflybsd.org/cgi/web-man?commandsio&section=4) for more information on the proper values for these lines. Some video cards (notably those based on S3 chips) use IO addresses in the form of `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.
594
595 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.
596
597     
598
599     # Parallel port
600
601     device          ppc0    at isa? irq 7
602
603 This is the ISA-bus parallel port interface.
604
605     
606
607     device          ppbus      # Parallel port bus (required)
608
609 Provides support for the parallel port bus.
610
611     
612
613     device          lpt        # Printer
614
615 Support for parallel port printers.
616
617  **Note:** All three of the above are required to enable parallel printer support.
618
619     
620
621     device          plip       # TCP/IP over parallel
622
623 This is the driver for the parallel network interface.
624
625     
626
627     device          ppi        # Parallel port interface device
628
629 The general-purpose I/O (***geek port) + IEEE1284 I/O.
630
631     
632
633     #device         vpo        # Requires scbus and da
634
635 This is for an Iomega Zip drive. It requires `scbus` and `da` support. Best performance is achieved with ports in EPP 1.9 mode.
636
637     
638
639     # PCI Ethernet NICs.
640
641     device          de         # DEC/Intel DC21x4x (Tulip)
642
643     device          fxp        # Intel EtherExpress PRO/100B (82557, 82558)
644
645     device          tx         # SMC 9432TX (83c170 EPIC)
646
647     device          vx         # 3Com 3c590, 3c595 (Vortex)
648
649     device          wx         # Intel Gigabit Ethernet Card (Wiseman)
650
651 Various PCI network card drivers. Comment out or remove any of these not present in your system.
652
653     
654
655     # PCI Ethernet NICs that use the common MII bus controller code.
656
657     device          miibus     # MII bus support
658
659 MII bus support is required for some PCI 10/100 Ethernet NICs, namely those which use MII-compliant transceivers or implement transceiver control interfaces that operate like an MII. Adding `device miibus` to the kernel config pulls in support for the generic miibus API and all of the PHY drivers, including a generic one for PHYs that are not specifically handled by an individual driver.
660
661     
662
663     device          dc         # DEC/Intel 21143 and various workalikes
664
665     device          rl         # RealTek 8129/8139
666
667     device          sf         # Adaptec AIC-6915 (Starfire)
668
669     device          sis        # Silicon Integrated Systems SiS 900/SiS 7016
670
671     device          ste        # Sundance ST201 (D-Link DFE-550TX)
672
673     device          tl         # Texas Instruments ThunderLAN
674
675     device          vr         # VIA Rhine, Rhine II
676
677     device          wb         # Winbond W89C840F
678
679     device          xl         # 3Com 3c90x (Boomerang, Cyclone)
680
681 Drivers that use the MII bus controller code.
682
683     
684
685     # ISA Ethernet NICs.
686
687     device          ed0    at isa? port 0x280 irq 10 iomem 0xd8000
688
689     device          ex
690
691     device          ep
692
693     # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
694
695     # exists only as a PCMCIA device, so there is no ISA attachment needed
696
697     # and resources will always be dynamically assigned by the pccard code.
698
699     device          wi
700
701     # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
702
703     # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
704
705     # mode (the factory default). If you set the switches on your ISA
706
707     # card for a manually chosen I/O address and IRQ, you must specify
708
709     # those parameters here.
710
711     device          an
712
713     # The probe order of these is presently determined by i386/isa/isa_compat.c.
714
715     device          ie0    at isa? port 0x300 irq 10 iomem 0xd0000
716
717     device          fe0    at isa? port 0x300
718
719     device          le0    at isa? port 0x300 irq 5 iomem 0xd0000
720
721     device          lnc0   at isa? port 0x280 irq 10 drq 0
722
723     device          cs0    at isa? port 0x300
724
725     device          sn0    at isa? port 0x300 irq 10
726
727     # requires PCCARD (PCMCIA) support to be activated
728
729     #device         xe0    at isa?
730
731 ISA Ethernet drivers. See `/usr/src/sys/config/LINT` for which cards are supported by which driver.
732
733     
734
735     pseudo-device   ether         # Ethernet support
736
737 `ether` is only needed if you have an Ethernet card. It includes generic Ethernet protocol code.
738
739     
740
741     pseudo-device   sl      1     # Kernel SLIP
742
743 `sl` is for SLIP support. This has been almost entirely supplanted by PPP, which is easier to set up, better suited for modem-to-modem connection, and more powerful. The ***number*** after `sl` specifies how many simultaneous SLIP sessions to support.
744
745     
746
747     pseudo-device   ppp     1     # Kernel PPP
748
749 This is for kernel PPP support for dial-up connections. There is also a version of PPP implemented as a userland application that uses `tun` and offers more flexibility and features such as demand dialing. The ***number*** after `ppp` specifies how many simultaneous PPP connections to support. .
750
751     
752
753     device   tun           # Packet tunnel.
754
755 This is used by the userland PPP software. A ***number*** after `tun` specifies the number of simultaneous PPP sessions to support. See the [userppp.html PPP] section of this book for more information.
756
757     
758
759     pseudo-device   pty           # Pseudo-ttys (telnet etc)
760
761 This is a ***pseudo-terminal*** or simulated login port. It is used by incoming `telnet` and `rlogin` sessions, ***xterm***, and some other applications such as ***Emacs***. The ***number*** after `pty` indicates the number of `pty`s to create. If you need more than the default of 16 simultaneous ***xterm*** windows and/or remote logins, be sure to increase this number accordingly, up to a maximum of 256. ***
762
763     
764
765 Memory disk pseudo-devices.
766
767     
768
769     pseudo-device   gif     # IPv6 and IPv4 tunneling
770
771 This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling.
772
773     
774
775     pseudo-device   faith   # IPv6-to-IPv4 relaying (translation)
776
777 This pseudo-device captures packets that are sent to it and diverts them to the IPv4/IPv6 translation daemon.
778
779     
780
781     # The `bpf' device enables the Berkeley Packet Filter.
782
783     # Be aware of the administrative consequences of enabling this!
784
785     pseudo-device   bpf           # Berkeley packet filter
786
787 This is the Berkeley Packet Filter. This pseudo-device allows network interfaces to be placed in promiscuous mode, capturing every packet on a broadcast network (e.g., an Ethernet). These packets can be captured to disk and or examined with the [tcpdump(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#tcpdump&section1) program.
788
789  **Note:** The [bpf(4)](http://leaf.dragonflybsd.org/cgi/web-man?command#bpf&section4) device is also used by [dhclient(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dhclient&section=8) to obtain the IP address of the default router (gateway) and so on. If you use DHCP, leave this uncommented.
790
791     
792
793     # USB support
794
795     #device         uhci          # UHCI PCI-&gt;USB interface
796
797     #device         ohci          # OHCI PCI-&gt;USB interface
798
799     #device         usb           # USB Bus (required)
800
801     #device         ugen          # Generic
802
803     #device         uhid          # ***Human Interface Devices***
804
805     #device         ukbd          # Keyboard
806
807     #device         ulpt          # Printer
808
809     #device         umass         # Disks/Mass storage - Requires scbus and da
810
811     #device         ums           # Mouse
812
813     # USB Ethernet, requires mii
814
815     #device         aue           # ADMtek USB ethernet
816
817     #device         cue           # CATC USB ethernet
818
819     #device         kue           # Kawasaki LSI USB ethernet
820
821 Support for various USB devices.
822
823 For more information and additional devices supported by DragonFly, see `/usr/src/sys/i386/conf/LINT`.
824
825 #### Notes 
826
827 [[!table  data="""
828 <tablewidth="100%"> [(1)](kernelconfig-config.html#AEN7414) | The auto-tuning algorithm sets `maxuser` equal to the amount of memory in the system, with a minimum of 32, and a maximum of 384. |
829 | | 
830 """]]
831
832 ## Device Nodes 
833
834 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. 
835
836 These nodes are created automatically once devfs is mounted, which happens manually for the root `/dev` during boot, just after the root mount.
837
838 ## If Something Goes Wrong 
839
840  **Note:** If you are having trouble building a kernel, make sure to keep a `GENERIC`, or some other kernel that is known to work on hand as a different name that will not get erased on the next build. You cannot rely on `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 [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps&section1) will not work properly. The proper command to ***unlock*** the kernel file that `make` installs (in order to move another kernel back permanently) is:
841
842      % chflags noschg /boot/kernel
843      
844
845 If you find you cannot do this, you are probably running at a [securelevel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#securelevel&section8) greater than zero. Edit `kern_securelevel` in `/etc/rc.conf` and set it to `-1`, then reboot. You can change it back to its previous setting when you are happy with your new kernel.
846
847 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:
848
849     
850
851     % chflags schg /boot/kernel
852     
853
854 There are five categories of trouble that can occur when building a custom kernel. They are:
855
856 * `config` fails: If the [config(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#config&section8) command fails when you give it your kernel description, you have probably made a simple error somewhere. Fortunately, [config(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=config&section=8) 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.
857
858 * `make` fails: If the `make` command fails, it usually signals an error in your kernel description, but not severe enough for [config(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#config&section8) to catch it. Again, look over your configuration, and if you still cannot resolve the problem, send mail to the [DragonFly Bugs mailing list](http://leaf.dragonflybsd.org/mailarchive/) with your kernel configuration, and it should be diagnosed very quickly.
859
860 * Installing the new kernel fails: If the kernel compiled fine, but failed to install (the `make install` or `make installkernel` command failed), the first thing to check is if your system is running at securelevel 1 or higher (see [init(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#init&section8)). The kernel installation tries to remove the immutable flag from your kernel and set the immutable flag on the new one. Since securelevel 1 or higher prevents unsetting the immutable flag for any files on the system, the kernel installation needs to be performed at securelevel 0 or lower.
861
862 * The kernel does not boot: If your new kernel does not boot, or fails to recognize your devices, do not panic! Fortunately, DragonFly has an excellent mechanism for recovering from incompatible kernels. Simply choose the kernel you want to boot from at the DragonFly boot loader. You can access this when the system counts down from 10. Hit any key except for the  **Enter**  key, type `unload` and then type `boot ***kernel.old***`, or the filename of any other kernel that will boot properly. 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 [dmesg(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#dmesg&section8) command will print the kernel messages from the current boot.
863
864 * The kernel works, but [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command#ps&section1) 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, many system-status commands like [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps&section=1) and [vmstat(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=vmstat&section=8) 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.