Network Stack Driver Module Files

Network Stack Driver Module README File
Date: Tue Jan 21 23:57:51 PST 2003
=======================================
Contents
  - Introduction
  - Directory Structure
  - Caveats
  - Installation
    + Step 1: Apply Kernel Patch
    + Step 2: Build Kernel
    + Step 3: Install and Boot on New Kernel
    + Step 4: Build net_mod.o
    + Step 5: Install net_mod.o
  - Known Problems
  - Bug Reports

Introduction
============
The Network Stack Driver Module, also referred to as net_mod (or
on SourceForge as netmod) is a set of patches and a kernel module
that provides a socket protocol handler API for the Linux kernel.
The code can be used for any implementation that wishes to either
filter or intercept socket calls for handling purposes under Linux,
and is structured as a general-purpose API for use by anyone.

The latest net_mod image can always be retrieved from:

    http://www.sourceforge.net/projects/netmod/

Directory Structure
===================
The net_mod source code is maintained as a .tar.gz, which is a
compressed tarball image.  The image can be extracted with the
command:

    tar xzf <filename>

Where <filename> is the name of the net_mod image.  For example,
running the command:

    tar -xzf net_mod-1.1.0.tgz

will extract the net_mod image into a directory named net_mod-1.1.0.
Within this directory will be this file (README), and two directories
labelled "patches" and "src".  The "patches" directory contains a set
of kernel patches to apply for various Linux kernels.  A patch may
or may not exist for your kernel.

The other subdirectory is "src", which contains the Linux kernel module
source code.


Caveats
=======
The net_mod driver code is currently only available for Linux 2.4
kernels.  It has not been tested or tried with Linux 2.5 kernels, nor
will it work (at this time) on Linux 2.2 kernels.


Installation
============
As of version 1.1.0, the net_mod installation steps have changed to
allow the kernel module portion of the code to be built independently
from the Linux kernel source tree.

There are a few steps to installing net_mod into your kernel:

    - Apply the appropriate kernel patch for your Linux kernel,
      and build a new kernel to run on.  Boot on this new kernel.

    - Build the net_mod.o Linux kernel module on the running
      kernel.

    - Install the net_mod.o kernel module into your appropriate
      modules directory.

Please follow the steps below to build and install the net_mod.o
kernel module.


Step 1: Apply Kernel Patch
--------------------------
The first step involves determining which kernel patch applies
to your kernel.  In the "patches" directory there are a series
of directories which contain kernel patches for different
kernel versions.

If you see a subdirectory which matches your kernel version,
you may apply the patch to your kernel source tree with the
"patch" command.  For example, if you are using kernel version
2.4.19, and you wish to apply the patch "linux-2.4.19-atk.patch"
to your kernel source tree, run the command:

    patch -p1 -l < <dir>/linux-2.4.19-atk.patch

This assumes that you are in the root of your Linux kernel source
tree (for example, /usr/src/linux), and that a copy of the
linux-2.4.19-atk.patch is located in <dir>.

A clean patch operation will not report any errors for each file
patched.  Each line reported should state:

    patching file <filename>

If the patch applies cleanly without warnings or errors, proceed
to Step 2.

If there are warnings or errors, please verify that the modified
files have the correct changes applied them.  This will require
some knowledge of how the patch command works, as well as files
generated on error.  Review any .rej and .orig files created by
the patch command and apply any corrections (if needed) by hand.

There may or may not be a patch that matches your kernel exactly;
in those cases, you will need to generate a custom patch to match
your kernel tree.  For assistance, contact the SourceForge project
administrators.


Step 2: Build Kernel
--------------------
Configuring and building a Linux kernel is an involved process.
While some Linux distributions have simplified the procedures,
it requires some understanding of how to set up a kernel
configuration file, build dependencies, and install both the
kernel and modules.

This README file is not intended as an instruction manual on how
to build and install a new kernel; however, in general, you must
perform the following operations:

    - Build a new kernel configuration file.  This can either be
      done by:

          + copying an existing kernel configuration file from
            your configs directory into your .config file, and
            then running "make oldconfig";

          + creating a new configuration file from either
            running "make config", "make menuconfig", or
            "make xconfig".  Be sure to specify all of the
            options required for your kernel, either as
            built-in, or as modules.

    - Create the module dependencies with the command "make dep".

    - Build the kernel with the command "make bzImage", or build
      and install the kernel with the command "make install".

    - Build all of your kernel modules with the command "make modules",
      and install the modules with the command "make modules_install".

Once all of these steps have been completed, assuming no errors,
you will have a working kernel and any modules you specified for
build installed.
      
If you had any problems during the build and installation phase,
please read through the Linux README file for your kernel, or
consult any number of Linux technical resources on how to build
and install a Linux kernel.  There is information on the Linux
kernel web site:

    http://www.kernel.org/


Step 3: Install and Boot on New Kernel
--------------------------------------
Installation of the kernel on some distributions such as Red Hat
is handled during the "make install" and "make modules_install"
procedures.  For those cases, the boot files for installation are
updated to boot the new kernel.

However, not every installation has this functionality, so it is
important to verify that the installation of the kernel was successful
and that the information is in your LILO or GRUB configuration.

The LILO configuration file is /etc/lilo.conf, and the GRUB
configuration file is /etc/grub.conf (which is typically a link
to /boot/grub/grub.conf).  Please read the manual pages for
"lilo" and "grub" for file format information and to ensure
you have set up your boot configuration files properly.

As a safety precaution, it is important to keep at least one
older kernel as a boot option so that if there is a problem
with booting your new kernel, you can recover the boot
configuration on an earlier kernel.

If you have an initrd image that coincides with your kernel,
be sure your boot configuration also specifies an initrd
image.  If one was not created automatically when you installed
the kernel and modules, run "mkinitrd" to generate a new one.
Please review the "mkinitrd" manual page for information on
how to create an initrd image for a new kernel.

Once the boot configuration file is correct, if you are using LILO, 
run "lilo" to load the new boot configuration information.  If
you are using GRUB, no additional steps are required.  Once you
are sure everything is correct, reboot your system and boot up
on the new kernel.

Step 4: Build net_mod.o
-----------------------
Building net_mod.o against the running kernel is straightforward.
The Makefile in the "src" directory will build using the source
tree for the running kernel, assuming the build links are set correctly.
If they header files found by the Makefile do not match the running
kernel, the resuling net_mod.o kernel module may not build or install
properly.

The Makefile will first attempt to use the header files located in
the /lib/modules/`uname -r`/build/include directory. The `uname -r`
command determines the version of the running kernel, which should
match against the currently booted system. If this directory
does not exist, the Makefile will try to use the header files in
/usr/src/linux/include. If that directory does not exist, then the
build or installation may not complete correctly.

If you are using a Red Hat or other standard distribution, be sure
the kernel-source RPM is installed for your kernel.  This will ensure
the kernel sources are available for your system.

To build the net_mod.o kernel module, type in the command:

    make

This will build all of the source code files needed for the kernel
module and create net_mod.o.  If there are errors in the build
process, verify that the problem is not a general Linux 2.4 issue
with the net_mod driver source code.


Step 5: Install net_mod.o
-------------------------

If everything built properly and the running kernel is a match for
the net_mod.o kernel module, then run the command:

    make install

This will install the net_mod.o kernel module into the
/lib/modules/`uname -r` directory.  After the net_mod.o driver
is installed, the command "depmod -a" is run to update module
dependencies based on the running kernel and the modules for
that kernel.

If this command runs without error, then the build was successful
and the driver can be loaded with the "modprobe" command.

If errors are reported, then the newly built module either had symbols
that do not match the running kernel, or the net_mod patch was not
applied to the kernel that is currently running.  If a module dependency
error is reported from the "depmod -a" operation, then it is possible
the header files used to build net_mod against do not match the running
kernel.   Verify the kernel header files are correct, and be sure the
running kernel has the appropriate net_mod kernel patch installed
properly.


Known Problems
==============
There are no known problems at this time.  New problems or support
requests can be sent to the Support section at:

    http://www.sourceforge.net/projects/netmod/

There is a Support section where new support requests can be filed.

Bug Reports
===========
Any and all bug reports should be filed at:

    http://www.sourceforge.net/projects/netmod/

There is a Bugs section where new bugs can be filed.  The SourceForge
maintainers will address problems as they are reported.