kerneld mini-HOWTO Version 1.5, last updated: November 22, 1996 by Henrik Storner (storner@osiris.ping.dk) ---------------------------------------------------------------------------- Introduction This document explains how you can use the kerneld function now (since 1.3.57) in the Linux kernels. It describes * what is kerneld * why do I want to use it * how to get the necessary pieces * how to set them up * how to tell kerneld about modules it doesn't know * how to spy on kerneld (can be useful in setting it up). * on-demand dialing of PPP and SLIP connections * special kerneld uses * Common problems and weirdness If you see things in this document that are wrong, please send me a note about it. I also appreciate any comments and suggestions for how to improve this mini-HOWTO. The latest released version of this document can be found at http://eolicom.olicom.dk/~storner/kerneld-mini-HOWTO.html. Between releases of the mini-HOWTO you can find updates on my unstructured list of changes at http://eolicom.olicom.dk/~storner/kern.html ---------------------------------------------------------------------------- What is kerneld ? kerneld is a feature introduced in the 1.3 development kernels by Bjorn Ekwall. It allows kernel "modules" - i.e. device drivers, network drivers, filesystems - to be loaded automatically when they are needed, rather than having to do it manually with modprobe or insmod. kerneld also has some other functions: * It can start a program whenever you attempt to access another node on the network, for instance - this makes it easy to implement dial-on-demand networking if you are connected through SLIP or PPP. And for the more amusing aspects, although these are not (yet ?) integrated with the standard kernel: * It can be setup to run a user-program instead of the default screen blanker, thus letting you use any program as a screen-saver. * Similar to the screen-blanker support, you can also change the standard console "beep" into something completely different ... kerneld consists of two separate entities: * Support in the Linux kernel for sending requests to a daemon that a module is needed for a certain task. * A user-level daemon that can figure out what modules must be loaded to fulfill the request from the kernel. Both pieces must be working for the kerneld support to function - it is not enough that only one or the other has been setup. ---------------------------------------------------------------------------- Why do I want to use it ? There are some good reasons for using kerneld. The ones I will mention are mine - others may want to use it for other reasons. * If you have to build kernels for several systems that only differ slightly - different kind of network card, for instance - then you can build a single kernel and some modules, instead of having to build individual kernels for each system. * Modules are easier for developers to test - you don't need to reboot the system to load and unload the driver. (This applies to all modules, not just kerneld-loaded ones). * It cuts down on the kernel memory usage, meaning you have more memory available for applications. Memory used by the kernel is *never* swapped out, so if you have 100Kb worth of unused drivers compiled into your kernel, they are simply wasting RAM. * Some of the things I use - the ftape floppy-tape driver, for instance, or iBCS - are only available as modules. But I don't want to bother with loading and unloading them whenever I need them. * People making Linux distributions don't have to build 284 different boot images - each user loads the drivers he needs for just his hardware. This is used e.g. by RedHat 4.0 in their installation. Of course, there are also reasons why you may not want to use it - you may prefer to have just one kernel image file with all of your drivers built in. In that case, you are reading the wrong document. ---------------------------------------------------------------------------- Where can I pick up the necessary pieces ? The support in the Linux kernel was introduced with Linux 1.3.57. If you have an earlier kernel version, you will need to upgrade if you want the kerneld support. All of the major Linux ftp sites carry the kernel sources - I recommend that you upgrade to the latest stable kernel release, 2.0, now at patch-level 26: ftp://sunsite.unc.edu/pub/Linux/kernel/v2.0/linux-2.0.26.tar.gz ftp://tsx-11.mit.edu/pub/linux/sources/system/v2.0/linux-2.0.26.tar.gz ftp://ftp.funet.fi/pub/Linux/PEOPLE/Linus/v2.0/linux-2.0.26.tar.gz The user-level daemon is included with the modules-1.2.8 package, and with the newer modules-2.0 package. These are normally available from the same place as the kernel sources, but the official locations include: ftp://sunsite.unc.edu/pub/Linux/kernel/v2.0/modules-2.0.0.tar.gz ftp://tsx-11.mit.edu/pub/linux/sources/sbin/modules-2.0.0.tar.gz ftp://ftp.funet.fi/pub/Linux/tools/modules-2.0.0.tar.gz NOTE: If you want to try module-loading with the latest 2.1 development kernels, you should use modules-2.1.8 or later. But see below about the problems with modules and 2.1 kernels. ---------------------------------------------------------------------------- How do I set it up ? First get the necessary parts: A suitable kernel and the latest modules-utilities. Then you should install the modules-utilities. Pretty simple - just unpack the sources and run make install. This compiles and installs the following programs in /sbin: genksysm, insmod, lsmod, modprobe, depmod, kerneld. I recommend that you add some lines to your startup-scripts to do some necessary setup whenever you boot Linux. Add the following lines to your /etc/rc.d/rc.S file (if you are running Slackware), or to /etc/rc.d/rc.sysinit (if you are running SysVinit, i.e. Debian, RedHat, Caldera): # Start kerneld - this should happen very early in the # boot process, certainly BEFORE you run fsck on filesystems # that might need to have disk drivers autoloaded if [ -x /sbin/kerneld ] then /sbin/kerneld fi # Your standard fsck commands go here # And you mount command to mount the root fs read-write # Update kernel-module dependencies file # Your root-fs MUST be mounted read-write by now if [ -x /sbin/depmod ] then /sbin/depmod -a fi The first part starts kerneld itself. The second part calls 'depmod -a' at startup. The depmod program builds a list of all available modules and analyzes their inter-dependencies, so it knows if one module needs to have another loaded before it will itself load. NOTE: Recent versions of kerneld as an option links with the GNU dbm library, libgdbm. If you enable this when building the module-utilities, kerneld will not start if libgdbm is not available which may well be the case if you have /usr on a separate partition and start kerneld before /usr is mounted. The recommended solution is to move libgdbm from /usr/lib to /lib, or link kerneld statically. Next, unpack the kernel sources, configure and build a kernel to your liking. If you have never done this before, you should definitely read the README file at the top level of the Linux sources. When you run make config to configure the kernel, you should pay attention to some questions that appear early on: Enable loadable module support (CONFIG_MODULES) [Y/n/?] Y You need to select the loadable module support, or there will be no modules for kerneld to load! Just say Yes. Kernel daemon support (CONFIG_KERNELD) [Y/n/?] Y This, of course, is also necessary. Then, a lot of the things in the kernel can be built as modules - you will see questions like Normal floppy disk support (CONFIG_BLK_DEV_FD) [M/n/y/?] where you can answer with an 'M' for 'Module'. Generally, only the drivers necessary for you to boot up your system - the harddisk driver, the driver for the root filesystem - should be built into the kernel; the rest can be built as modules. When you have gone through the 'make config', run 'make dep', 'make clean', 'make zImage' or 'make zlilo', 'make modules' and 'make modules_install'. Phew. The 'make zImage' puts the new kernel image in the file arch/i386/boot/zImage. You will need to copy it where you keep your boot-image, or install it in LILO afterwards. For more information about configuring, building and installing your own kernel, check out the Kernel-HOWTO posted regularly to comp.os.linux.answers, and available from sunsite.unc.edu in /pub/Linux/docs/HOWTO . ---------------------------------------------------------------------------- Trying out kerneld Now reboot with the new kernel. When the system comes back up, you can run a 'ps -ax', and you should see a line for kerneld: PID TTY STAT TIME COMMAND 59 ? S 0:01 /sbin/kerneld One of the nice things with kerneld is that once you have the kernel and the daemon installed, very little setup is needed. For a start, try using one of the drivers that you built as a module - it is more likely than not that it will work without further configuration. I build the floppy driver as a module, so I could put a DOS floppy in the drive and osiris:~ $ mdir a: Volume in drive A has no label Volume Serial Number is 2E2B-1102 Directory for A:/ binuti~1 gz 1942 02-14-1996 11:35a binutils-2.6.0.6-2.6.0.7.diff.gz libc-5~1 gz 24747 02-14-1996 11:35a libc-5.3.4-5.3.5.diff.gz 2 file(s) 26689 bytes So the floppy driver works - it gets loaded automatically by kerneld when I try to use the floppy disk. To see that the floppy module is indeed loaded, you can run /sbin/lsmod which lists all currently loaded modules: osiris:~ $ /sbin/lsmod Module: #pages: Used by: floppy 11 0 (autoclean) The "(autoclean)" means that the module will automatically be removed by kerneld when it has not been used for more than one minute. So the 11 pages of memory (= 44kB, one page is 4 kB) will only be used while I access the floppy drive - if I don't use the floppy for more than a minute, they are freed. Quite nice, if you are short of memory for your applications! ---------------------------------------------------------------------------- How does kerneld know what module to load ? Although kerneld comes with builtin knowledge about the most common types of modules, there are situations where kerneld will not know how to handle a request from the kernel. This is the case with things like CD-ROM drivers or network drivers, where there are more than one possible module that can be loaded. The requests that the kerneld daemon gets from the kernel is for one of the following items: * a block-device driver * a character-device driver * a binary format * a tty line discipline * a filesystem * a network route (for demand dialing slip or ppp links) * a network device * a network service (e.g. rarp) * a network protocol (e.g. IPX) kerneld determines what module should be loaded by scanning the configuration file /etc/conf.modules There are two kinds of entries in this file: Paths (where the module-files are located), and aliases (what module should be loaded). If you don't have this file already, you could create it by running /sbin/modprobe -c | grep -v '^path' >/etc/conf.modules If you want to add yet another "path" directive to the default paths, you must include all the "default" paths as well, since a path directive in /etc/conf.modules will replace all the ones that modprobe knows by default! Normally you don't want to add any paths by your own, since the built-in set should take care of all "normal" setups (and then some...), I promise! On the other hand, if you just want to add an alias or an option directive, your new entries in /etc/conf.modules will be _added_ to the ones that modprobe already knows. If you should _redefine_ an alias or an option, your new entries in /etc/conf.modules will override the built-in ones. Block devices If you run '/sbin/modprobe -c', you will get a listing of the modules that kerneld knows about, and what requests they correspond to. For instance, the request that ends up loading the floppy driver is for the block-device that has major number 2: osiris:~ $ /sbin/modprobe -c | grep floppy alias block-major-2 floppy Why block-major-2 ? Because the floppy devices /dev/fd* use major device 2 and are block devices: osiris:~ $ ls -l /dev/fd0 /dev/fd1 brw-rw-rw- 1 root root 2, 0 Mar 3 1995 /dev/fd0 brw-r--r-- 1 root root 2, 1 Mar 3 1995 /dev/fd1 Character devices Character devices are dealt with in a similar way. E.g. the ftape floppy tape driver sits on major-device 27: osiris:~ $ ls -lL /dev/ftape crw-rw---- 1 root disk 27, 0 Jul 18 1994 /dev/ftape However, kerneld does not by default know about the ftape driver - it is not listed in the output from '/sbin/modprobe -c'. So to setup kerneld to load the ftape driver, I must add a line to the kerneld configuration file, /etc/conf.modules: alias char-major-27 ftape Network devices You can also use the device name instead of the 'char-major-xxx' / 'block-major-yyy' setup. This is especially useful for network drivers. E.g. a driver for an ne2000 netcard acting as eth0 would be loaded with alias eth0 ne If you need to pass some options to the driver - e.g. to tell the module about what IRQ the netcard is using, you add an 'options' line: options ne irq=5 This will cause kerneld to load the NE2000 driver with the command /sbin/modprobe ne irq=5 Of course, the actual options available are specific to the module you are loading. Binary formats Binary formats are handled in a similar way. Whenever you try to run a program that the kernel does not know how to load, kerneld gets a request for "binfmt-xxx", where xxx is a number determined from the first few bytes of the executable. So, the kerneld configuration to support loading the binfmt_aout module for ZMAGIC (a.out) executables is alias binfmt-267 binfmt_aout since the magic number (see /etc/magic) for ZMAGIC files is 267. (If you check /etc/magic, you will see the number 0413, but /etc/magic uses octal numbers where kerneld uses decimal, and octal 413 = decimal 267). There are actually three slightly different variants of a.out executables (NMAGIC, QMAGIC and ZMAGIC), so for full support of the binfmt_aout module we need alias binfmt-264 binfmt_aout # pure executable (NMAGIC) alias binfmt-267 binfmt_aout # demand-paged executable (ZMAGIC) alias binfmt-204 binfmt_aout # demand-paged executable (QMAGIC) a.out, Java and iBCS binary formats are recognized automatically by kerneld, without any configuration. Line disciplines (slip, cslip and ppp) Line disciplines are requested with "tty-ldisc-x", with 'x' being usually 1 (for SLIP) or 3 (for PPP). Both of these are known by kerneld automatically. Speaking of ppp, if you want kerneld to load the bsd_comp data compression module for ppp, then you must add the following two lines to your /etc/conf.modules: alias tty-ldisc-3 bsd_comp alias ppp0 bsd_comp Network protocol families (IPX, AppleTalk, AX.25) Some network protocols can be loaded as modules as well. The kernel asks kerneld for a protocol family (e.g. IPX) with a request for "net-pf-X" where X is a number indicating what family is wanted. E.g. net-pf-3 is AX.25, net-pf-4 is IPX and net-pf-5 is AppleTalk. (These numbers are determined by the AF_AX25, AF_IPX etc. definitions in the linux source file include/linux/socket.h). So to autoload the IPX module, you would need an entr like this in /etc/conf.modules: alias net-pf-4 ipx See also the section below on common problems for information about how you can avoid some annoying boot-time messages related to undefined protocol families. File systems kerneld requests for filesystems are simply the name of the filesystem type. A common use of this would be to load the isofs module for CD-ROM filesystems, i.e. filesystems of type "iso9660": alias iso9660 isofs ---------------------------------------------------------------------------- Devices requiring special configuration Some devices require a bit on configuration beyond the normal aliasing of e.g. a device to a module. * Character devices on major number 10: The miscellaneous devices * SCSI devices * Devices that require special initialization char-major-10 : Mice, watchdogs and randomness Hardware devices are usually identified through their major device numbers, e.g. ftape is char-major-27. However, if you look through the entries in /dev for char major 10, you will see that this is a bunch of very different devices, including * Mice of various sorts (bus mice, PS/2 mice) * Watchdog devices * The kernel 'random' device * APM (Advanced Power Management) interface Obviously, these devices are controlled by several different modules, not a single one. Therefore, the kerneld configuration for these misc. devices use the major number and the minor number: alias char-major-10-1 psaux # For PS/2 mouse alias char-major-10-130 wdt # For WDT watchdog You need a kernel version 1.3.82 or later to use this; earlier versions do not pass the minor number to kerneld, making it impossible for kerneld to figure out which of the misc. device modules to load. Loading SCSI drivers: The scsi_hostadapter entry Drivers for SCSI devices consist of a driver for the SCSI host adapter (e.g. an Adaptec 1542), and a driver for the type of SCSI device you use, e.g. a hard disk, a CD-ROM or a tape-drive. All of these can be loaded as modules. However, when you want to access e.g. the CD-ROM drive that is connected to the Adaptec card, the kernel and kerneld only knows that it needs to load the sr_mod module in order to support SCSI CD-ROM's - it does not know what SCSI controller the CD-ROM is connected to, and hence does not know what module to load to support the SCSI controller. To resolve this, you can add an entry for the SCSI driver module to your /etc/conf.modules that tells kerneld which of the many possible SCSI controller modules it should load: alias scd0 sr_mod # sr_mod for SCSI CD-ROM's ... alias scsi_hostadapter aha1542 # ... need the Adaptec driver This only works with kernel version 1.3.82 or later. If you have more than one SCSI controller, you are currently out of luck - there is no way of telling kerneld that your CD-ROM drive needs the Adaptec driver, but the tape drive needs the BusLogic driver. When loading a module isn't enough: The 'post-install' entry Sometimes, just loading the module is not enough to get things working. For instance, if you have your soundcard compiled as a module, it is often convenient to set a certain volume level. Only problem is, the setting vanishes the next time the module is loaded. Here is a neat trick from Ben Galliart (bgallia@luc.edu): The final solution required installing the setmix-0.1 package ( ftp://sunsite.unc.edu/pub/Linux/apps/sound/mixers/setmix-0.1.tar.gz ) And then adding the following lines to my /etc/conf.modules : post-install sound /usr/local/bin/setmix -f /etc/volume.conf What this does is that after the sound module is loaded, kerneld runs the command indicated by the 'post-install sound' entry. So the sound module gets configured with the command '/usr/local/bin/setmix -f /etc/volume.conf'. This may be useful for other modules as well, e.g. the lp module can be configured with the tunelp program by adding post-install lp tunelp For kerneld to recognize these options, you will need a version of kerneld that is 1.3.69f or later. NOTE: An earlier version of this mini-HOWTO mentioned a "pre-remove" option, that might be used to run a command just before kerneld removed a module. However, this has never worked and its use is therefore discouraged - most likely, this option will disappear in a future kerneld release. The whole issue of module "settings" is undergoing some change at the moment, and may look different on your system by the time you read this. ---------------------------------------------------------------------------- Spying on kerneld If you have tried everything, and just cannot figure out what the kernel is asking kerneld to do, there is a way of seeing the requests that kerneld receives, and hence to figure out what should go into /etc/conf.modules: The kdstat utility. This nifty little program comes with the modules-package, but it is not compiled or installed by default. To build it: cd /usr/src/modules-2.0.0/kerneld make kdstat Then, to make kerneld display information about what it is doing, run kdstat debug and kerneld will start spewing messages on the console about what it is doing. If you then try and run the command that you want to use, you will see the kerneld requests; these can be put into /etc/conf.modules and aliased to the module needed to get the job done. To turn off the debugging, run '/sbin/kdstat nodebug' . ---------------------------------------------------------------------------- Dial-on-demand networking NOTE: The dial-on-demand feature in kerneld was discussed a lot on the linux-kernel mailing list in May and June. It seems that there may be some race conditions in the code, and some of the networking gurus recommend that you do not use kerneld for this purpose. The diald package can be used instead, and also offers more flexibility regarding when to activate the connection. kerneld also gets a request when the kernel needs to send data to a network connection for which there is no known route. This is typically the case when your network access is through a SLIP- or PPP-connection that is only active part of the time. The request that kerneld gets are of the form "request-route a.b.c.d", where a.b.c.d is the IP address that the kernel has data for. kerneld will handle this request by running a shell script, /sbin/request-route, with the IP address as parameter. The most likely IP address requested the first time is that of your nameserver (see /etc/resolv.conf) so that will be the address passed to the request-route script. Unless you have more than one possible network connection (dial-up or ethernet), you can safely ignore the IP address; all of your network access has to go the same way, so there is no need to differentiate between requests for one IP address or another. To implement on-demand dialing, you just need to change the /sbin/request-route script so that it sets up your SLIP or PPP connection. For SLIP, this typically involves running 'dip' or some other program to call the SLIP server and setup the connection; for PPP, you will probably run chat+pppd. The script does not need to worry about loading the ppp- or slip-modules; this will happen automatically through kerneld. Calling up your ISP and setting up the SLIP/PPP connection can take a while, and may not always be succesful. The request-route script therefore has a built-in timer - by default set for 60 seconds - which is how long it will keep the kernel waiting for the kerneld request to complete. But often the network setup does not take 60 seconds, so for the quickest possible response you should arrange for the request-route timer to be killed as soon as the network setup is complete. SLIP users can do this with recent version of dip, by including the command shell kill `cat /tmp/request-route` just before the "mode SLIP" command in your DIP script. PPP users should have kill `cat /tmp/request-route` in their /etc/ppp/ip-up script. If your network takes longer than 60 seconds to setup, then you will need to change the duration of the timer in the /sbin/request-route script. In that case, you will probably also need to change the kerneld delay for autocleaning unused modules, by adding a "delay=xxx" option to the line in /etc/rc.d/rc.S that starts up kerneld. The 'xxx' value is the delay before modules are removed, in seconds (default is 60). This is especially necessary if you used ppp: The ppp modules are loaded as soon as pppd starts, but if you use a command like "/usr/sbin/pppd connect `chat -f /etc/chat.script` ..." then pppd is idle while the chat-script runs, and the ppp-modules may have been unloaded by the time the chat-script completes! kerneld does not yet monitor the network activity to shutdown the network connection; however, PPP users can take advantage of the 'idle-disconnect' option for pppd introduced in ppp-2.2.0. If you pass the option 'idle-disconnect 600' to pppd, then the PPP connection will be terminated after 600 seconds (10 minutes) of inactivity. SLIP users will have to shutdown the connection manually. ---------------------------------------------------------------------------- Special kerneld uses I knew you would ask about how to setup the screensaver module ... The 'kerneld/GOODIES' directory in modules-package has a couple of kernel patches for screensaver- and consolebeep-support in kerneld; these are not yet part of the official kernel. So you will need to install the kernel-patches and rebuild the kernel. To install a patch, you use the "patch" command: cd /usr/src/linux patch -s -p1