MAGNET Software Distribution

This is the official distribution site for MAGNET. Once you have the source for a version of the Linux kernel, come here to download the appropriate MAGNET patchfile to include MAGNET into your kernel. Then, follow the MAGNET Installation Instructions to get MAGNET running in your environment.

Patches

We recommend you use the latest version. (This may require hand application of the latest patch on previous kernels.)

These are maintained for historical interest only. Please use the latest version which contains all known bug fixes.

MAGNET Installation Instructions

The following instructions assume familiarity in building a kernel from source.

(For more information on how to build a kernel, see http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html. Also some distributions have their own way to build a kernel, e.g., Debian. It is best to use your distribution's way if there is one.)

MAGNET-ize the Linux kernel
1. Get an official kernel release (e.g., 2.4.19) from http://www.kernel.org/, your favorite Linux kernel repository or from your distribution's repository. Install it, usually in /usr/src. Change to the kernel directory.
2. Download the MAGNET patch for your kernel version, e.g., patch-2.4.19-magnet.
  (If a patch for your kernel version is not yet available, select the closest patch. You may need to do some manual work to get the patch installed.)
3. Patch the kernel "patch -p1 < patch-2.4.19-magnet".
Configure the kernel
1. Configure the kernel with the necessary options for your hardware.
2. Make sure to check "YES" when to "Prompt for development and/or incomplete code/drivers" under "Code maturity level options".
3. Select "MAGNET kernel instrumentation" under the "Kernel hacking" option to enable various choices about configuring MAGNET. Configure MAGNET appropriately.
Make, install and activate the MAGNET-ized kernel
Build the user-space tools: mkmagnet, magnet-read, magnet-parse and magnet-dump
1. Make the tools: "cd magnet; make -f Makefile.tools"
2. Install the tools in /usr/sbin: "make -f Makefile.tools install"
Check for a MAGNET-ized kernel

Reboot.
The existence of /proc/magnet indicates that MAGNET is installed properly. Cat /proc/magnet to see details about the installation.

Create MAGNET device file (typically /dev/magnet) by checking /proc/magnet and using the the major/minor numbers found there to create /dev/magnet with mknod.
Test MAGNET

Create an empty trace file: "mkmagnet -b "
Collect events: "magnet-read "
Parse events: "magnet-parse > "

Optionally enable unattended data collection

NOTE: magnet.cron has not been extensively tested since v1.0.0.

Modify the configuration lines of the scripts (magnet.cron and magnet.copy) to reflect your environment.

Create cron job for magnet.cron: "crontab -e"

  # Set up MAGNET to run every day at 12:34 AM
  34 0 * * * /usr/sbin/magnet.cron

  cd /etc/rc3.d
  ln -s /bin/magnet.cron S89magnet

Example

In this section, we give an example of how we build a MAGNET-ized kernel.

Note: We highly recommend the Debian distribution (www.debian.org) as it makes package management almost painless. Since that is the distribution we use, the example below shows the steps necessary to build and install a MAGNET-ized kernel under Debian.

MAGNET-ize the Linux kernel

Get kernel source from kernel.org

  > wget ftp://ftp.kernel.org/pub/linux/kernel/v2.4/linux-2.4.19.tar.bz2
  > tar jxpf linux-2.4.18.tar.bz2
  > mv linux-2.4.19 magnet-2.4.18

or download from the Debian distribution:

  > apt-get install kernel-source-2.4.19
  > cd /usr/src
  > tar jxpf kernel-source-2.4.19.tar.bz2
  > mv kernel-source-2.4.19 magnet-2.4.18

Get MAGNET patch off our web site and place in /usr/src/magnet-2.4.19

Patch the kernel

  > cd magnet-2.4.19
  > patch -p1 < patch-2.4.19-magnet

Configure the kernel
1. Configure for your hardware. (Here we see one of the benefits of using Debian. A copy of the configuration files for installed kernels are kept in /boot. Copy one of them as your initial configuration.)
```
  > cp /boot/config-2.4.19 .config
  > make 
        
```
  Change any options as appropriate but make sure that "Prompt for development and/or incomplete code/drivers" under "Code maturity level options" has been enabled in order to display MAGNET options.
2. Select "MAGNET kernel instrumentation" under the "Kernel hacking" option to enable various choices about configuring MAGNET. Also select which subsystems you wish to instrument, as shown.
```
  [*] MAGNET kernel instrumentation
    (256)   Buffer size (default 256 pages)
    [*]   Extended instrumentation
    [ ]   Debugging code
    [ ]   Benchmarking code
    [*]   Network instrumentation
    [*]Socket layer
    [ ]       Extended socket instrumentation
    [*]     TCP layer
    [ ]       Extended TCP instrumentation
    [*]     UDP layer
    [ ]       Extended UDP instrumentation
    [*]     IP layer
    [ ]       Extended IP instrumentation
    [ ]     Generic network device
    [*]     Ethernet devices
    [ ]       Extended Ethernet instrumentation
    [ ]   Task scheduling instrumentation
        
```
3. Make, install and activate the MAGNET-ized kernel.
  Here is where Debian really shines!
```
  > make-kpkg --rootcmd fakeroot clean
  > make-kpkg --rootcmd fakeroot --revision 1.0 \
              --append_to_version '-magnet' kernel_image
  > sudo dpkg -i /usr/src/kernel-image-2.4.19-magnet_1.0_i386.deb
        
```
  The latter command may prompt you to create a boot floppy or to install a boot block to activate the new kernel, as shown below. Answer as appropriate. (Typically the defaults are fine so just hit the carriage return twice.)
```
  Would you like to create a boot floppy now? [No] 
  You already have a LILO configuration in /etc/lilo.conf
  Install a boot block using the existing /etc/lilo.conf? [Yes] 
        
```
  There... building and installing a kernel is not too painful is it!
  
  Note: you may also want to specify modules_image if you have any kernel modules not included in the kernel source that need to be built. The details of doing this are beyond the scope of this document, but the synopsis is that all modules with source code in /usr/src/modules will have package built by "make-kpkg modules_image" and deposited in /usr/src. Install them with dpkg.

Build and install user-space tools

  > cd /usr/src/magnet-2.4.19/magnet
  > make -f Makefile.tools
  > make -f Makefile.tools install

Check the MAGNET-ized kernel

Reboot

Check for /proc/magnet

  > cat /proc/magnet

  ---------------------------------------------------------------
  MAGNET: Monitoring Apparatus for General kerNel Event Tracing
  ---------------------------------------------------------------
  Version: 2.0.0
  Device Name: /dev/magnet
  Device Number: 10, 63
  Buffer Size: 1024 KB (256 pages)
  Record size: 20 bytes
  Extended Info: off
  Socket: on
  TCP: on
  UDP: on
  IP: on
  Task: off
  ---------------------------------------------------------------
  RADIANT (http://www.lanl.gov/radiant)
  ---------------------------------------------------------------

Create MAGNET device file (typically /dev/magnet)
1. Use magnet.cron to create /dev/magnet
```
  > magnet.cron
        
```
2. Alternatively, create by hand
```
  > mknod /dev/magnet c  
        
```
  where the major and minor numbers are obtained from /proc/magnet as above.

Test MAGNET

Create an empty trace file

 > cd /tmp
 > mkmagnet mytrace.mag

Collect events
```
 > magnet-read mytrace.mag
        
```

Parse events into human readable form

 > magnet-parse mytrace.mag > mytrace.txt

Optionally enable unattended data collection (see above)

NOTICE: Information from this server resides on a computer system funded by the U.S. Department of Energy. Anyone using this system consents to monitoring of this use by system or security personnel. For complete conditions of use see Disclaimer/Privacy.