1 # Configuring the DragonFly Kernel
3 ***Updated and restructured by Jim Mock. Originally contributed by Jake Hamby.***
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.
11 After reading this chapter, you will know:
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.
19 ## Why Build a Custom Kernel?
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.
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.
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.
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:
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 * **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.
31 * **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.
33 ## Building and Installing a Custom Kernel
35 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.
37 ### Installing the Source
39 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.
41 The preferred way of installing the sources is:
44 # make src-create-shallow
46 This will download the last revision of the source tree via git into `/usr/src`. This method also allows for easy updating of the source tree by using:
50 You should edit the makefile located in /usr and change the GITHOST variable to one of the currently available git mirrors http://www.dragonflybsd.org/mirrors/.
52 GITHOST?=avalon.dragonflybsd.git
54 ### Your Custom Config File
56 Next, move to the `config` directory and copy the `X86_64_GENERIC` (or `GENERIC` for x86) configuration file to the name you want to give your kernel. For example:
58 # cd /usr/src/sys/config
59 # cp X86_64_GENERIC MYKERNEL
61 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.
63 **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 `X86_64_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.
67 # cd /usr/src/sys/config
69 # cp X86_64_GENERIC /root/kernels/MYKERNEL
70 # ln -s /root/kernels/MYKERNEL
72 **Note:** You must execute these and all of the following commands under the `root` account or you will get permission denied errors.
74 Now, edit `MYKERNEL` with your favorite text editor. If you are just starting out and are not familiar with *vi*, you can use an easier editor called *ee*, which is also part of the base system. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from `X86_64_GENERIC`.
76 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, on the other hand, the `X86_64_GENERIC` configuration file might seem overwhelming to you, so follow the descriptions in the *Configuration File* section slowly and carefully.
78 ### Building a Kernel - Full Source Tree
80 **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.
82 1. Change to the `/usr/src` directory.
86 1. Compile the kernel.
88 # make buildkernel KERNCONF=MYKERNEL
90 1. Install the new kernel.
92 # make installkernel KERNCONF=MYKERNEL
94 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.
96 ### Building a Kernel - Kernel Source Only
98 When only the kernel source is installed, you need to change step 2, above, to this:
100 # make nativekernel KERNCONF=MYKERNEL
102 The other steps are the same.
104 ### Running Your New Kernel
106 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).
108 **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.
110 ## The Configuration File
112 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 the keywords of interest, generally in the order they are listed in `X86_64_GENERIC`, although some related keywords have been grouped together in a single section (such as Networking) even though they are actually scattered throughout the `X86_64_GENERIC` file. An exhaustive list of options and more detailed explanations of the device lines is present in the `LINT64` configuration file, located in the same directory as `X86_64_GENERIC`. If you are in doubt as to the purpose or necessity of a line, check first in `LINT64`.
116 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).
120 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.
122 The system will auto-tune this setting for you if you leave it to `0`, which is recommended (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). 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.
124 **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 `pseudo-device pty 16` (see below).
126 # Pseudo devices - the number indicates how many units to allocate.
127 pseudo-device loop # Network loopback
129 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*.
131 Everything that follows is more or less optional. See the notes underneath or next to each option for more information.
133 makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
135 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 leave this line uncommented; 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§ion=1).
137 options INET #InterNETworking
139 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.
141 options INET6 #IPv6 communications protocols
143 This enables the IPv6 communication protocols.
145 options HAMMER #Hammer Filesystem
147 This option enables the HAMMER file system; you can comment it out if your system uses only UFS/FFS as a file system.
149 options FFS #Berkeley Fast Filesystem
150 options FFS_ROOT #FFS usable as root device [keep this!]
152 This is the basic hard drive Filesystem. Leave it in if you boot from the hard disk.
154 options UFS_DIRHASH #Improve performance on big directories
156 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.
158 options SOFTUPDATES #Enable FFS Soft Updates support
160 This option enables Soft Updates in the kernel, this will help speed up write access on UFS file systems. 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§ion=8) 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§ion=8) (for existing filesystems) or [newfs(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=newfs§ion=8) (for new filesystems) commands.
162 options MFS #Memory Filesystem
163 options MD_ROOT #MD is a potential root device
165 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`:
167 /dev/ad1s2b /tmp mfs rw 0 0
169 Now you simply need to either reboot, or run the command `mount /tmp`.
171 options NFS #Network Filesystem
172 options NFS_ROOT #NFS usable as root device, NFS required
174 The network Filesystem. Unless you plan to mount partitions from a UNIX® file server over TCP/IP, you can comment these out.
176 options MSDOSFS #MSDOS Filesystem
178 The MS-DOS® FAT 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 [[DPorts|docs/howtos/HowToDPorts]]) allows you to access DOS floppies without having to mount and unmount them (and does not require `MSDOSFS` at all).
180 options CD9660 #ISO 9660 Filesystem
182 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.
184 options PROCFS #Process filesystem
186 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§ion=1) to give you more information on what processes are running.
188 #options COMPAT_43 #Compatible with BSD 4.3
190 Compatibility with 4.3BSD. This should not be needed nowadays, but might be required for some old programs.
192 options SCSI_DELAY=5000 #Delay (in ms) before probing SCSI
194 This causes the kernel to pause for 5 seconds before probing each SCSI device in your system. You may try to lower this number 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.
196 options UCONSOLE #Allow users to grab the console
198 This 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§ion=1), [talk(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=talk§ion=1), and any other messages you receive, as well as any console messages sent by the kernel.
200 options KTRACE #ktrace(1) support
202 This enables kernel process tracing, which is useful in debugging.
204 options SYSVSHM #SYSV-style shared memory
206 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.
208 options SYSVSEM #SYSV-style semaphores
210 Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel.
212 options SYSVMSG #SYSV-style message queues
214 Support for System V messages. Again, only adds a few hundred bytes to the kernel.
216 **Note:** The [ipcs(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ipcs§ion=1) command will list any processes using each of these System V facilities.
218 options P1003_1B #Posix P1003_1B real-time extensions
219 options _KPOSIX_PRIORITY_SCHEDULING
221 Real-time extensions added in the 1993 POSIX®. Certain applications use these.
223 options ICMP_BANDLIM #Rate limit bad replies
225 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.
229 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 the `LINT64` file.
233 Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to ISA bus.
237 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.
241 This driver supports all ATA and ATAPI devices.
243 device atadisk # ATA disk drives
245 This is needed along with `device nata` for ATA disk drives.
247 device atapicd # ATAPI CDROM drives
249 This is needed along with `device nata` for ATAPI CDROM drives.
251 device atapifd # ATAPI floppy drives
253 This is needed along with `device nata` for ATAPI floppy drives.
255 device atapist # ATAPI tape drives
257 This is needed along with `device nata` for ATAPI tape drives.
259 options ATA_STATIC_ID #Static device numbering
261 This makes the controller number static (like the old driver) or else the device numbers are dynamically allocated.
265 device ahc # AHA2940 and onboard AIC7xxx devices
268 SCSI controllers. Comment out any you do not have in your system. If you have an IDE only system, you can remove these altogether.
271 device scbus # SCSI bus (required)
272 device da # Direct Access (disks)
273 device sa # Sequential Access (tape etc)
275 device pass # Passthrough device (direct SCSI access)
276 device sg # Passthrough device (linux scsi generic)
278 SCSI peripherals. Again, comment out any you do not have, or if you have only IDE hardware, you can remove them completely.
280 **Note:** The USB [umass(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=umass§ion=4) 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.
282 # RAID controllers interfaced to the SCSI subsystem
287 Supported RAID controllers. If you do not have any of these, you can comment them out or remove them.
289 # atkbdc0 controls both the keyboard and the PS/2 mouse
290 device atkbdc0 at isa? port IO_KBD
292 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`).
294 device atkbd0 at atkbdc? irq 1
296 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.
298 device psm0 at atkbdc? irq 12
300 Use this device if your mouse plugs into the PS/2 mouse port.
304 The video card driver.
306 # splash screen/screen saver
309 Splash screen at start up! Screen savers require this too.
311 # syscons is the default console driver, resembling an SCO console
314 `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.
316 # PCCARD (PCMCIA) support
321 PCMCIA support. You want this if you are using a laptop.
324 device sio0 at isa? port IO_COM1 flags 0x10 irq 4
325 device sio1 at isa? port IO_COM2 irq 3
326 device sio2 at isa? disable port IO_COM3 irq 5
327 device sio3 at isa? disable port IO_COM4 irq 9
329 These are the four serial ports referred to as COM1 through COM4 in the MS-DOS/Windows® world.
331 **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?command=sio§ion=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.
333 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.
336 device ppc0 at isa? irq 7
338 This is the ISA-bus parallel port interface.
340 device ppbus # Parallel port bus (required)
342 Provides support for the parallel port bus.
346 Support for parallel port printers.
348 **Note:** All three of the above are required to enable parallel printer support.
350 device plip # TCP/IP over parallel
352 This is the driver for the parallel network interface.
354 device ppi # Parallel port interface device
356 The general-purpose I/O (***geek port) + IEEE1284 I/O.
358 #device vpo # Requires scbus and da
360 This is for an Iomega Zip drive. It requires `scbus` and `da` support. Best performance is achieved with ports in EPP 1.9 mode.
365 Various PCI network card drivers. Comment out or remove any of these not present in your system.
367 # PCI Ethernet NICs that use the common MII bus controller code.
368 device miibus # MII bus support
370 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.
372 Follows a list of drivers that use the MII bus controller code; like above, you can disable those that are not present in your system.
373 Do the same for the list of ISA network card drivers (see `LINT64` for which cards are supported by which driver), as well as for the wireless network cards.
375 pseudo-device ether # Ethernet support
377 `ether` is only needed if you have an Ethernet card. It includes generic Ethernet protocol code.
379 pseudo-device sl 1 # Kernel SLIP
381 `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.
383 pseudo-device ppp 1 # Kernel PPP
385 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.
387 device tun # Packet tunnel.
389 This is used by the userland PPP software. A number after `tun` specifies the number of simultaneous PPP sessions to support.
391 pseudo-device pty # Pseudo-ttys (telnet etc)
393 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.
395 pseudo-device md # Memory "disks"
397 Memory disk pseudo-devices.
399 pseudo-device gif # IPv6 and IPv4 tunneling
401 This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling.
403 pseudo-device faith # IPv6-to-IPv4 relaying (translation)
405 This pseudo-device captures packets that are sent to it and diverts them to the IPv4/IPv6 translation daemon.
407 # The `bpf' device enables the Berkeley Packet Filter.
408 # Be aware of the administrative consequences of enabling this!
409 pseudo-device bpf # Berkeley packet filter
411 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§ion=1) program.
413 **Note:** The [bpf(4)](http://leaf.dragonflybsd.org/cgi/web-man?command=bpf§ion=4) device is also used by [dhclient(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=dhclient§ion=8) to obtain the IP address of the default router (gateway) and so on. If you use DHCP, leave this uncommented.
415 For more information and additional devices supported by DragonFly, see `LINT64`.
419 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.
421 These nodes are created automatically once devfs is mounted, which happens manually for the root `/dev` during boot, just after the root mount.
423 ## If Something Goes Wrong
425 **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§ion=1) will not work properly. The proper command to “unlock” the kernel file that `make` installs (in order to move another kernel back permanently) is:
427 % chflags noschg /boot/kernel
429 If you find you cannot do this, you are probably running at a [securelevel(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=securelevel§ion=8) 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.
431 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:
433 % chflags schg /boot/kernel
435 There are five categories of trouble that can occur when building a custom kernel. They are:
437 * `config` fails: If the [config(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=config§ion=8) 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§ion=8) will print the line number that it had trouble with, so you can quickly skip to it with a text editor. 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 `X86_64_GENERIC` kernel configuration or another reference.
439 * `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§ion=8) to catch it. Again, look over your configuration, and if you still cannot resolve the problem, send an email to the [DragonFly Users mailing list](https://www.dragonflybsd.org/mailinglists/) with your kernel configuration, and it should be diagnosed very quickly.
441 * 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§ion=8)). 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.
443 * 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§ion8) command will print the kernel messages from the current boot.
445 * The kernel works, but [ps(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=ps§ion=1) 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§ion=1) and [vmstat(8)](http://leaf.dragonflybsd.org/cgi/web-man?command=vmstat§ion=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.
projects / ikiwiki.git / blob