docs/handbook/handbook-kernelconfig-trouble.mdwn

   1 ## If Something Goes Wrong \r
   2 \r
   3 There are five categories of trouble that can occur when building a custom kernel. They are:\r
   4 \r
   5
   6 * `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.\r
   7 \r
   8
   9 * `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.\r
  10 \r
  11
  12 * 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.\r
  13 \r
  14
  15 * 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.\r
  16 \r
  17  **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:\r
  18     \r
  19     # chflags noschg /boot/kernel\r
  20 \r
  21 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.\r
  22 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:\r
  23     \r
  24     # chflags schg /boot/kernel\r
  25 \r
  26 \r
  27
  28 * 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.\r
  29 \r
  30 \r
  31 CategoryHandbook\r
  32 CategoryHandbook-kernelconfig\r
  33 \r
  34 \r