(no commit message)
[ikiwiki.git] / docs / newhandbook / ConfigureKernel / index.mdwn
CommitLineData
8a4039fa 1# Configuring the DragonFly Kernel
2
3***Updated and restructured by Jim Mock. Originally contributed by Jake Hamby.***
4
d832db48 5[[!toc levels=3]]
8a4039fa 6
7## Synopsis
8
9The 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
11After 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
20
21
22## Why Build a Custom Kernel?
23
24
25
26Traditionally, 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.
27
28Today, 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.
29
30Despite 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.
31
32Building 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:
33
34
35
36* 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.
37
38* 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.
39
40* 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.
41
42
43
44
45
46
47
48## Building and Installing a Custom Kernel
49
50First, 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.
51
52### Installing the Source
53
46931f05 54If 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.
8a4039fa 55
56The preferred way of installing the sources is:
57
58 # cd /usr
f0967515 59 # make src-create
8a4039fa 60
61This will download the whole source tree via git into /usr/src. This method also allows for easy updating of the source tree by using:
62
63 # make src-update
64
65
66
67### Your Custom Config File
68
69Next, move to the `config` directory and copy the `GENERIC` configuration file to the name you want to give your kernel. For example:
70
71 # cd /usr/src/sys/config
72 # cp GENERIC MYKERNEL
73
74Traditionally, 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.
75
76**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.
77
78
79
80For example:
81
82
83 # cd /usr/src/sys/config
84 # mkdir /root/kernels
85 # cp GENERIC /root/kernels/MYKERNEL
86 # ln -s /root/kernels/MYKERNEL
87
88
89**Note:** You must execute these and all of the following commands under the `root` account or you will get permission denied errors.
90
91Now, 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`.
92
93If 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.
94
95
96
97### Building a Kernel - Full Source Tree
98
99**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.
100
101
102
103 1. Change to the `/usr/src` directory.
104
105
106
107 # cd /usr/src
108
109 1. Compile the kernel.
110
111 # make buildkernel KERNCONF=MYKERNEL
112
113
114 1. Install the new kernel.
115
116 # make installkernel KERNCONF=MYKERNEL
117
118
119
120
121
122If 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.
123
124### Building a Kernel - Kernel Source Only
125
126When only the kernel source is installed, you need to change step 2, above, to this:
127
128
129 # make nativekernel KERNCONF=MYKERNEL
130
131
132The other steps are the same.
133
134
135
136### Running Your New Kernel
137
955f2f73 138The 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).
8a4039fa 139
140
141**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.
142
143
144
145
146## The Configuration File
147<!-- XXX: do we really want to mention all these million config options? -->
148The 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`.
149
150
151
152The 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`.
153
154
155
156
157
158 #
159
160 #
161
162 # GENERIC -- Generic kernel configuration file for DragonFly/i386
163
164 #
165
166 # Check the LINT configuration file in sys/config, for an
167
168 # exhaustive list of options.
169
170 #
171
172 # $DragonFly: src/sys/config/GENERIC,v 1.56 2007/12/26 14:02:36 sephe Exp $
173
174
175
176The following are the mandatory keywords required in ***every*** kernel you build:
177
178
179
180
181
182 machine i386
183
184
185
186This is the machine architecture. It must be `i386` at the moment. Support for `amd64` will be added in the future.
187
188
189
190
191
192 cpu I386_CPU
193
194 cpu I486_CPU
195
196 cpu I586_CPU
197
198 cpu I686_CPU
199
200
201
202The 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.
203
204
205
206
207
208 ident GENERIC
209
210
211
212This 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).
213
214
215
216
217
218 maxusers 0
219
220
221
222The `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.
223
224
225
226(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.
227
228
229
230 **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`].
231
232
233
234
235
236 # Floating point support - do not disable.
237
238 device npx0 at nexus? port IO_NPX irq 13
239
240
241
242`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.
243
244
245
246
247
248 # Pseudo devices - the number indicates how many units to allocate.
249
250 pseudo-device loop # Network loopback
251
252
253
254This 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***.
255
256
257
258Everything that follows is more or less optional. See the notes underneath or next to each option for more information.
259
260
261
262
263
264 #makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
265
266
267
268The 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).
269
270
271
272
273
274 options MATH_EMULATE #Support for x87 emulation
275
276
277
278This 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.
279
280
281
282 **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.
283
284
285
286
287
288 options INET #InterNETworking
289
290
291
292Networking 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.
293
294
295
296
297
298 options INET6 #IPv6 communications protocols
299
300
301
302This enables the IPv6 communication protocols.
303
304
305
306
307
308 options FFS #Berkeley Fast Filesystem
309
310 options FFS_ROOT #FFS usable as root device [keep this!]
311
312
313
314This is the basic hard drive Filesystem. Leave it in if you boot from the hard disk.
315
316
317
318
319
320 options UFS_DIRHASH #Improve performance on big directories
321
322
323
324This 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.
325
326
327
328
329
330 options SOFTUPDATES #Enable FFS Soft Updates support
331
332
333
334This 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.
335
336
337
338
339
340 options MFS #Memory Filesystem
341
342 options MD_ROOT #MD is a potential root device
343
344
345
346This 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`:
347
348
349
350
351
352 /dev/ad1s2b /tmp mfs rw 0 0
353
354
355
356Now you simply need to either reboot, or run the command `mount /tmp`.
357
358
359
360
361
362 options NFS #Network Filesystem
363
364 options NFS_ROOT #NFS usable as root device, NFS required
365
366
367
368The network Filesystem. Unless you plan to mount partitions from a UNIX® file server over TCP/IP, you can comment these out.
369
370
371
372
373
374 options MSDOSFS #MSDOS Filesystem
375
376
377
378The 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).
379
380
381
382
383
384 options CD9660 #ISO 9660 Filesystem
385
386 options CD9660_ROOT #CD-ROM usable as root, CD9660 required
387
388
389
390The 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.
391
392
393
394
395
396 options PROCFS #Process filesystem
397
398
399
400The 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. ***
401
402
403
404
405
406
407
408Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out.
409
410
411
412
413
414 options SCSI_DELAY=5000 #Delay (in ms) before probing SCSI
415
416
417
418This 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.
419
420
421
422
423
424 options UCONSOLE #Allow users to grab the console
425
426
427
428Allow 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.
429
430
431
432
433
434 options USERCONFIG #boot -c editor
435
436
437
438This option allows you to boot the configuration editor from the boot menu.
439
440
441
442
443
444 options VISUAL_USERCONFIG #visual boot -c editor
445
446
447
448This option allows you to boot the visual configuration editor from the boot menu.
449
450
451
452
453
454 options KTRACE #ktrace(1) support
455
456
457
458This enables kernel process tracing, which is useful in debugging.
459
460
461
462
463
464 options SYSVSHM #SYSV-style shared memory
465
466
467
468This 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.
469
470
471
472
473
474 options SYSVSEM #SYSV-style semaphores
475
476
477
478Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel.
479
480
481
482
483
484 options SYSVMSG #SYSV-style message queues
485
486
487
488Support for System V messages. Again, only adds a few hundred bytes to the kernel.
489
490
491
492 **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.
493
494
495
496
497
498 options P1003_1B #Posix P1003_1B real-time extensions
499
500 options _KPOSIX_PRIORITY_SCHEDULING
501
502
503
504Real-time extensions added in the 1993 POSIX®. Certain applications in the ports collection use these (such as **StarOffice™** ).
505
506
507
508
509
510 options ICMP_BANDLIM #Rate limit bad replies
511
512
513
514This 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.
515
516
517
518
519
520 # To make an SMP kernel, the next two are needed
521
522 #options SMP # Symmetric MultiProcessor Kernel
523
524 #options APIC_IO # Symmetric (APIC) I/O
525
526
527
528The above are both required for SMP support.
529
530
531
532
533
534 device isa
535
536
537
538All 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`.
539
540
541
542
543
544 device eisa
545
546
547
548Include this if you have an EISA motherboard. This enables auto-detection and configuration support for all devices on the EISA bus.
549
550
551
552
553
554 device pci
555
556
557
558Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to ISA bus.
559
560
561
562
563
564 device agp
565
566
567
568Include 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.
569
570
571
572
573
574 # Floppy drives
575
576 device fdc0 at isa? port IO_FD1 irq 6 drq 2
577
578 device fd0 at fdc0 drive 0
579
580 device fd1 at fdc0 drive 1
581
582
583
584This is the floppy drive controller. `fd0` is the `A:` floppy drive, and `fd1` is the `B:` drive.
585
586
587
588
589
590 device ata
591
592
593
594This 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.
595
596
597
598
599
600 device atadisk # ATA disk drives
601
602
603
604This is needed along with `device ata` for ATA disk drives.
605
606
607
608
609
610 device atapicd # ATAPI CDROM drives
611
612
613
614This is needed along with `device ata` for ATAPI CDROM drives.
615
616
617
618
619
620 device atapifd # ATAPI floppy drives
621
622
623
624This is needed along with `device ata` for ATAPI floppy drives.
625
626
627
628
629
630 device atapist # ATAPI tape drives
631
632
633
634This is needed along with `device ata` for ATAPI tape drives.
635
636
637
638
639
640 options ATA_STATIC_ID #Static device numbering
641
642
643
644This makes the controller number static (like the old driver) or else the device numbers are dynamically allocated.
645
646
647
648
649
650 # ATA and ATAPI devices
651
652 device ata0 at isa? port IO_WD1 irq 14
653
654 device ata1 at isa? port IO_WD2 irq 15
655
656
657
658Use the above for older, non-PCI systems.
659
660
661
662
663
664 # SCSI Controllers
665
666 device ahb # EISA AHA1742 family
667
668 device ahc # AHA2940 and onboard AIC7xxx devices
669
670 device amd # AMD 53C974 (Teckram DC-390(T))
671
672 device dpt # DPT Smartcache - See LINT for options!
673
674 device isp # Qlogic family
675
676 device ncr # NCR/Symbios Logic
677
678 device sym # NCR/Symbios Logic (newer chipsets)
679
680 device adv0 at isa?
681
682 device adw
683
684 device bt0 at isa?
685
686 device aha0 at isa?
687
688 device aic0 at isa?
689
690
691
692SCSI controllers. Comment out any you do not have in your system. If you have an IDE only system, you can remove these altogether.
693
694
695
696
697
698 # SCSI peripherals
699
700 device scbus # SCSI bus (required)
701
702 device da # Direct Access (disks)
703
704 device sa # Sequential Access (tape etc)
705
706 device cd # CD
707
708 device pass # Passthrough device (direct SCSI
709
710 access)
711
712
713
714SCSI peripherals. Again, comment out any you do not have, or if you have only IDE hardware, you can remove them completely.
715
716
717
718 **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.
719
720
721
722
723
724 # RAID controllers
725
726 device ida # Compaq Smart RAID
727
728 device amr # AMI MegaRAID
729
730 device mlx # Mylex DAC960 family
731
732
733
734Supported RAID controllers. If you do not have any of these, you can comment them out or remove them.
735
736
737
738
739
740 # atkbdc0 controls both the keyboard and the PS/2 mouse
741
742 device atkbdc0 at isa? port IO_KBD
743
744
745
746The 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`).
747
748
749
750
751
752 device atkbd0 at atkbdc? irq 1
753
754
755
756The `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.
757
758
759
760
761
762 device psm0 at atkbdc? irq 12
763
764
765
766Use this device if your mouse plugs into the PS/2 mouse port.
767
768
769
770
771
772 device vga0 at isa?
773
774
775
776The video card driver.
777
778
779
780
781
782 # splash screen/screen saver
783
784 pseudo-device splash
785
786
787
788Splash screen at start up! Screen savers require this too.
789
790
791
792
793
794 # syscons is the default console driver, resembling an SCO console
795
796 device sc0 at isa?
797
798
799
800`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.
801
802
803
804
805
806 # Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
807
808 #device vt0 at isa?
809
810 #options XSERVER # support for X server on a vt console
811
812 #options FAT_CURSOR # start with block cursor
813
814 # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
815
816 #options PCVT_SCANSET=2 # IBM keyboards are non-std
817
818
819
820This 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.
821
822
823
824
825
826 # Power management support (see LINT for more options)
827
828 device apm0 at nexus? disable flags 0x20 # Advanced Power Management
829
830
831
832Advanced Power Management support. Useful for laptops.
833
834
835
836
837
838 # PCCARD (PCMCIA) support
839
840 device card
841
842 device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
843
844 device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable
845
846
847
848PCMCIA support. You want this if you are using a laptop.
849
850
851
852
853
854 # Serial (COM) ports
855
856 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
857
858 device sio1 at isa? port IO_COM2 irq 3
859
860 device sio2 at isa? disable port IO_COM3 irq 5
861
862 device sio3 at isa? disable port IO_COM4 irq 9
863
864
865
866These are the four serial ports referred to as COM1 through COM4 in the MS-DOS/Windows® world.
867
868
869
870 **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.
871
872
873
874Each 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.
875
876
877
878
879
880 # Parallel port
881
882 device ppc0 at isa? irq 7
883
884
885
886This is the ISA-bus parallel port interface.
887
888
889
890
891
892 device ppbus # Parallel port bus (required)
893
894
895
896Provides support for the parallel port bus.
897
898
899
900
901
902 device lpt # Printer
903
904
905
906Support for parallel port printers.
907
908
909
910 **Note:** All three of the above are required to enable parallel printer support.
911
912
913
914
915
916 device plip # TCP/IP over parallel
917
918
919
920This is the driver for the parallel network interface.
921
922
923
924
925
926 device ppi # Parallel port interface device
927
928
929
930The general-purpose I/O (***geek port) + IEEE1284 I/O.
931
932
933
934
935
936 #device vpo # Requires scbus and da
937
938
939
940This is for an Iomega Zip drive. It requires `scbus` and `da` support. Best performance is achieved with ports in EPP 1.9 mode.
941
942
943
944
945
946 # PCI Ethernet NICs.
947
948 device de # DEC/Intel DC21x4x (Tulip)
949
950 device fxp # Intel EtherExpress PRO/100B (82557, 82558)
951
952 device tx # SMC 9432TX (83c170 EPIC)
953
954 device vx # 3Com 3c590, 3c595 (Vortex)
955
956 device wx # Intel Gigabit Ethernet Card (Wiseman)
957
958
959
960Various PCI network card drivers. Comment out or remove any of these not present in your system.
961
962
963
964
965
966 # PCI Ethernet NICs that use the common MII bus controller code.
967
968 device miibus # MII bus support
969
970
971
972MII 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.
973
974
975
976
977
978 device dc # DEC/Intel 21143 and various workalikes
979
980 device rl # RealTek 8129/8139
981
982 device sf # Adaptec AIC-6915 (Starfire)
983
984 device sis # Silicon Integrated Systems SiS 900/SiS 7016
985
986 device ste # Sundance ST201 (D-Link DFE-550TX)
987
988 device tl # Texas Instruments ThunderLAN
989
990 device vr # VIA Rhine, Rhine II
991
992 device wb # Winbond W89C840F
993
994 device xl # 3Com 3c90x (Boomerang, Cyclone)
995
996
997
998Drivers that use the MII bus controller code.
999
1000
1001
1002
1003
1004 # ISA Ethernet NICs.
1005
1006 device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
1007
1008 device ex
1009
1010 device ep
1011
1012 # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
1013
1014 # exists only as a PCMCIA device, so there is no ISA attachment needed
1015
1016 # and resources will always be dynamically assigned by the pccard code.
1017
1018 device wi
1019
1020 # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
1021
1022 # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
1023
1024 # mode (the factory default). If you set the switches on your ISA
1025
1026 # card for a manually chosen I/O address and IRQ, you must specify
1027
1028 # those parameters here.
1029
1030 device an
1031
1032 # The probe order of these is presently determined by i386/isa/isa_compat.c.
1033
1034 device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
1035
1036 device fe0 at isa? port 0x300
1037
1038 device le0 at isa? port 0x300 irq 5 iomem 0xd0000
1039
1040 device lnc0 at isa? port 0x280 irq 10 drq 0
1041
1042 device cs0 at isa? port 0x300
1043
1044 device sn0 at isa? port 0x300 irq 10
1045
1046 # requires PCCARD (PCMCIA) support to be activated
1047
1048 #device xe0 at isa?
1049
1050
1051
1052ISA Ethernet drivers. See `/usr/src/sys/config/LINT` for which cards are supported by which driver.
1053
1054
1055
1056
1057
1058 pseudo-device ether # Ethernet support
1059
1060
1061
1062`ether` is only needed if you have an Ethernet card. It includes generic Ethernet protocol code.
1063
1064
1065
1066
1067
1068 pseudo-device sl 1 # Kernel SLIP
1069
1070
1071
1072`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.
1073
1074
1075
1076
1077
1078 pseudo-device ppp 1 # Kernel PPP
1079
1080
1081
1082This 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. .
1083
1084
1085
1086
1087
1088 device tun # Packet tunnel.
1089
1090
1091
1092This 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.
1093
1094
1095
1096
1097
1098 pseudo-device pty # Pseudo-ttys (telnet etc)
1099
1100
1101
1102This 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. ***
1103
1104
1105
1106
1107
1108
1109
1110Memory disk pseudo-devices.
1111
1112
1113
1114
1115
1116 pseudo-device gif # IPv6 and IPv4 tunneling
1117
1118
1119
1120This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling.
1121
1122
1123
1124
1125
1126 pseudo-device faith # IPv6-to-IPv4 relaying (translation)
1127
1128
1129
1130This pseudo-device captures packets that are sent to it and diverts them to the IPv4/IPv6 translation daemon.
1131
1132
1133
1134
1135
1136 # The `bpf' device enables the Berkeley Packet Filter.
1137
1138 # Be aware of the administrative consequences of enabling this!
1139
1140 pseudo-device bpf # Berkeley packet filter
1141
1142
1143
1144This 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.
1145
1146
1147
1148 **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.
1149
1150
1151
1152
1153
1154 # USB support
1155
1156 #device uhci # UHCI PCI-&gt;USB interface
1157
1158 #device ohci # OHCI PCI-&gt;USB interface
1159
1160 #device usb # USB Bus (required)
1161
1162 #device ugen # Generic
1163
1164 #device uhid # ***Human Interface Devices***
1165
1166 #device ukbd # Keyboard
1167
1168 #device ulpt # Printer
1169
1170 #device umass # Disks/Mass storage - Requires scbus and da
1171
1172 #device ums # Mouse
1173
1174 # USB Ethernet, requires mii
1175
1176 #device aue # ADMtek USB ethernet
1177
1178 #device cue # CATC USB ethernet
1179
1180 #device kue # Kawasaki LSI USB ethernet
1181
1182
1183
1184Support for various USB devices.
1185
1186
1187
1188For more information and additional devices supported by DragonFly, see `/usr/src/sys/i386/conf/LINT`.
1189
1190
1191
1192#### Notes
1193
1194[[!table data="""
1195<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. |
1196| |
1197"""]]
1198
1199
1200
1201
1202
1203
1204## Device Nodes
1205
1206
1207
1208Almost 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.
1209
1210These nodes are created automatically once devfs is mounted, which happens manually for the root `/dev` during boot, just after the root mount.
1211
1212
1213
1214## If Something Goes Wrong
1215
1216
1217 **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:
1218
1219
1220 % chflags noschg /boot/kernel
1221
1222
1223If 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.
1224
1225And, 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:
1226
1227
1228
1229 % chflags schg /boot/kernel
1230
1231
1232
1233There are five categories of trouble that can occur when building a custom kernel. They are:
1234
1235
1236
1237
1238* `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.
1239
1240
1241
1242
1243* `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.
1244
1245
1246
1247
1248* 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.
1249
1250
1251
1252
1253* 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.
1254
1255
1256
1257* 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.