Building a Web100 Kernel ========================= This document covers general instructions and advice on how to: - apply the web100 patches to a linux kernel - build the kernel, and - install the newly built kernel on the system IMPORTANT: Currently Web100 patches have only been tested for specific kernels from kernel.org. The detailed version specific release information appears in README.web100. Be sure that you have a good repeatable procedure for building, installing and testing kernels (see below) before applying the web100 patch. If you are moving to a new base kernel, it is especially important that you verify that your new kernel is fully functional before you apply the web100 patch. We typically have far less difficulty installing web100 than getting new base kernels properly configured to support all devices and features. BEFORE YOU PROCEED ------------------ Before you proceed, it may be a good idea to take the following steps so that you can backtrack if you run into problems: - Make a copy of the current kernel - Make a copy of the .config file (usually in /usr/src/linux) - Tar up the files in the /lib/modules directory corresponding to the current working kernel APPLYING WEB100 PATCH --------------------- You will need to become root before applying the patches: % su (Enter root password) # cd /usr/src/linux --------------------------------------------------------------------- Note: SAVE A COPY OF THE PATCH FILE It is a good idea to save a copy of the patch file you will be using for web100, so that you can backout of the patch (to get a clean kernel tree) if necessary. This will also be needed before applying the next version of web100 patch file because the patches are distributed as full patches as opposed to incremental patches. IMPORTANT: The patches are intended to be applied on a clean kernel from kernel.org. If you are already running a patched kernel, please be sure to either unpatch the kernel first, or get a fresh kernel. To unpatch (when required): patch -Rp3 < [path-to-web100-dir]/web100-[version-name].patch --------------------------------------------------------------------- # patch -p3 < [path-to-web100-dir]/web100-[version-name].patch The patch command should complete successfully without any errors. There is, however, one file for which the patch may fail, and that is the patch to the Makefile in the top level. This situation is explained in the "EXTRAVERSION" section below. If all the patches are successful, you may want to skim thorough the following section to understand the implication of modifying the EXTRAVERSION string. EXTRAVERSION ------------ The top level kernel Makefile defines "EXTRAVERSION" (typically on line 4). EXTRAVERSION determines the suffix of the kernel version name. It is used for a number of things, including determining the directory name used by loadable kernel modules. The Makefile patch will fail on all 3rd party kernels, because all 3rd party vendors alter EXTRAVERSION. - If EXTRAVERSION is not updated by web100 (ie. patch fails) and you ignore this error, your web100 kernel will attempt to use the same loadable modules as the original kernel. This is generally expeditious, but sometimes leads to unexpected operational dependences. (e.g. A configuration change to one kernel may make other kernels incompatible with their modules.) However, please keep in mind that some third party software packages check the kernel version string and abort if they do not recognize it. People who are installing picky third party software may need to avoid updating the EXTRAVERSION string. CAUTION: If at all possible, we recommend that you avoid this approach. - If EXTRAVERSION is not updated by web100 (ie. patch fails), then you should edit the Makefile by hand and append "-web100" to the EXTRAVERSION string (no spaces between the exisiting string the added string). Please note that web100 will function with or without updated EXTRAVERSION string. However your choice for the EXTRAVERSION string may greatly affect other operational issues, such as module compatibility. You may want to edit the makefile by hand to reflect your own operational preference. CONFIGURING THE KERNEL ---------------------- We have found it to be safer to force a full rebuild: # cd /usr/src/linux # cp .config config.save # make mrproper # cp config.save .config # make menuconfig To enable web100 features select the following options: Code maturity level options ---> [*] Prompt for development and/or incomplete code/drivers Processor type and features ---> [*] Symmetric multi-processing support (Select for SMPs only) Networking options ---> [*] Web100 networking enhancements (NEW) [*] Web100: TCP statistics (NEW) [*] Web100: Net100 extensions (NEW) [*] Web100: netlink event notification service (NEW) (7) Web100: default winscale initial value (NEW) Note: The last option is set to 7 automatically. Change it if appropriate for your system. Save menuconfig options Finally, do a "make dep" to set up the dependencies correctly. # make dep COMPILING and INSTALLING THE KERNEL ----------------------------------- The next steps are platform dependent: For installing on Intel Linux, follow steps for "INTEL". For installing on Alpha Linux, follow steps for "ALPHA". --------------- INTEL --------------- *** Save old kernel *** If you prefer creating a boot floppy for booting the system with the new kernel, please go to "Booting system using boot floppy" section. If you're using LILO or GRUB, and would prefer saving the new kernel to disk, the following section explains the steps: (cd /usr/src/linux) # make bzImage # cp arch/i386/boot/bzImage /boot/vmlinuz-2.4.19-web100 Build and install modules for this kernel (this step may be skipped if the EXTRAVERSION string was not modified; see notes above). # make modules # make modules_install Laptop users should note that it can be time consuming if you have to build a full set of pcmcia drivers. LILO Users ----------- Edit /etc/lilo.conf and add the appropriate lines. Example (if /dev/hda2 is where /boot resides): image = /boot/vmlinuz-2.4.19-web100 label=linux-web100 root=/dev/hda2 Run "/sbin/lilo -v" Reboot the system. Select "linux-web100" to boot the web100 kernel. Go to the "Confirming Web100 Kernel" section. GRUB Users ----------- Edit /boot/grub and add the following lines to 'menu.lst'. Example (if booting from /dev/hda5): title linux-web100 kernel (hd0, 4)/boot/vmlinuz-2.4.19-web100 root=/dev/hda5 Reboot system with new kernel. Go to the "Confirming Web100 Kernel" section. Booting system using boot floppy --------------------------------- To create a boot disk with the new kernel, and booting the system without editing lilo.conf: cd /usr/src/linux Insert a floppy into the A: drive make bzdisk This will copy the new compressed kernel onto the floppy disk. Boot the system from floppy. Go to the "Confirming Web100 Kernel" section. --------------- ALPHA --------------- *** Save old kernel *** # make boot # cp arch/alpha/boot/vmlinux.gz /boot/vmlinuz-2.4.19-web100 Build and install modules for this kernel (this step may be skipped if the EXTRAVERSION string was not modified; see notes above). # make modules # make modules_install Laptop users should note that it can be time consuming if you have to build a full set of pcmcia drivers. Reboot the system using the new kernel. Go to the "Confirming Web100 Kernel" section. CONFIRMING WEB100 KERNEL ------------------------ The message "Web100 [VERSION] build [version-name]: Initialization successful" should appear in the /var/log/dmesg file. The date in [version-name] should match the "date" part from the file name in the patch file. In addition, check the first line of the file "/proc/web100/header". This line should match the [version-name] in the /var/log/dmesg file. If system fails to boot, see the "Troubleshooting" section. TROUBLESHOOTING --------------- If the system doesn't boot correctly using the web100 kernel, boot it up with the older kernel that was running on the system. Check the options in the "make menuconfig" step to make sure the kernel options were selected correctly, recompile the kernel and reboot with the web100 kernel. If you're unable to get the web100 kernel up, please send a problem report to support@web100.org OR submit a trouble ticket at internal.web100.org. If you use pcmcia drivers or other loadable kernel modules, you may find that you need to rebuild them after applying the web100 patch. You should also save copies of your non-web100 modules in case you need to go back. (See EXTRAVERSION above) SUBMITTING A PROBLEM REPORT --------------------------- If you're unable to get the web100 kernel up, please send a problem report to support@web100.org. Please try to include as much of the information as possible to assist us in troubleshooting the problems you are experiencing. Depending on the problem you are experiencing, it may not be possible to provide all that is requested below, but please try to provide as much of it as possible. - Output of the following commands: uname -a head -1 /proc/web100/header - List of third party packages installed - The name of the web100 patch file - List of patch failures and the ".rej" file(s) - Description of the problem; Please include specific details of the hardware and software configuration if you suspect that that may be the source of the problem.