Idiots guide to setting up CoMo with nprobe-style SK98 drivers
--------------------------------------------------------------

NOTE: At one point, this worked with both 2.4 and 2.6 series kernels.
The 2.4 support has rotted, and this guide only describes how to
install the 2.6 variant.

Setting up the drivers
----------------------
1) First, get the modified sk98 from the University of Cambridge
Computer Lab web site:

wget http://www.cl.cam.ac.uk/Research/SRG/netos/nprobe/downloads/sk98lin.tar.bz2
tar -xvjf sk98lin.tar.bz2

2) Next, build the drivers.  To do this, you'll need to have the
relevant kernel headers installed in the usual place under
/lib/modules; most distributions do this for you if you use a
pre-built kernel, and it's done automatically make modules_install if
you build your own, so this isn't usually a problem.  To build
the driver, change directory to the sk98lin directory and run make:

cd sk98lin
make -f Makefile.26

That should complete without errors.  On some kernel versions, there
may be a few warnings; these can be safely ignored.

3) You now need to load the sk98 driver.  Selecting the right module
arguments is not entirely trivial, and depends on the local
configuration.  If the configuration is such that you could sensibly
use an ordinary network interface and tcpdump, then you probably won't
need any arguments at all; this happens if you're using a monitoring
port on a switch.  If you're in some circumstance where transmitting
any data at all would be impossible or just generally a bad idea
(e.g. a passive tap on fibre), you need to disable autonegotiation by
specifying ``AutoNeg_A=Off DupCap_A=Off AutoNeg_B=Off DupCap_B=Off
Role_A=Slave Role_B=Slave''.

Depending on the model of card, you might also need to specify
RlmtMode=DualNet, for either passive or active taps.  This will
definitely be required if you have a dual port card with
autonegotiation turned off; otherwise, it's unlikely to do much harm,
but probably won't be required.

This is by far the most fiddly bit of setting the card up, and you may
need several attempts to get it to work nicely.  The most common
symptom of an error here is that the driver loads and finds the card,
but you never see any packets.

4) Create the device special file.  This may have already been done
for you, depending on the distribution; anything which runs either
devfs or a full udev should automate this.  The device special
should be /dev/sk98; check that it exists with ls -l /dev/sk98.
If it doesn't, you need to create it by hand.  First, find
the minor number from /proc/misc.  This file should look something
like this:

144 nvram
184 microcode
 63 device-mapper
175 agpgart
 64 sk98
228 hpet
135 rtc

You want the number to the left of sk98; in this case, 64.  Create the
device special with

mknod /dev/sk98 c 10 <minor>

e.g.

mknod /dev/sk98 c 10 64

5) Check the device file is correct.  Very strange things can happen
if this is wrong.  Go ls -l /dev/sk98.  You should see a line like:

crw-------  1 root system 10, 64 Jul  6 15:09 /dev/sk98

The important parts are the initial c, which must be there (a leading
b is particularly bad news) and the bit that says ``10, 64''.  The
first number here is the device major, which must be 10, and the
second is the device minor, which you can get out of /proc/misc.  If
the special is wrong, delete it and go back to step 4.

6) Configure the interfaces.  They need to be up and promisc.  For example,
if you wanted to monitor eth2 and eth3, you'd go

ifconfig eth2 up promisc
ifconfig eth3 up promisc

Unlike pcap-based systems, you don't need to give the interfaces IP
addresses.

Simple testing of the device
----------------------------

The sk98 driver tarball includes a simple dumper application which
takes packets from the card and writes them out in libpcap format.
This is useful for testing that the device actually works before
trying CoMo.

Building is fairly straightforward: just run make from the uspace
directory of the sk98 tarball.  This should generate a binary
called dumper, which can be run as ./dumper <dumpfile> e.g.

./dumper /tmp/some_file

This will spend a few minutes calibrating the timers, and then start
dumping packets to the file.

Note that timer calibration depends on the card receiving a reasonable
number of packets (at least a few dozen a second).


Building and running CoMo
-------------------------

1) Get CoMo from the sourceforge site.  If you want to use the 0.4
series, you'll also need to get and apply a patch from the Computer
Lab web site:
http://www.cl.cam.ac.uk/Research/SRG/netos/nprobe/downloads/como.newsk98.diff.
Fetch and extract the como-0.4 tarball, and then go patch -p1 <
como.newsk98.diff from the como-0.4 directory.

The unstable version of CoMo, available from the CVS repository,
doesn't need any patching.


2) Enable the sk98 sniffer in config_vars.local.  This should say something
like:

#HAVE_FTLIB_AND_ZLIB=1
#USE_SK98=1
#USE_DAG=1
#HAVE_FLEX_AND_BISON=1
#USE_STARGATE=1
#USE_PRISM2=1

If it doesn't exist, copy it from config_vars.default.  You need to
uncomment the USE_SK98 line (and whatever else is appropriate for your
local site).

3) Build CoMo.  como directory, and run make.

4) Write a como.conf file.  The easiest way of doing this is to copy
example.conf from the base directory of the tarball and then edit it a
little.  In addition to the configuration which would be required by
a CoMo built to use libpcap, you need to enable the sk98 sniffer.
The line you need to add says

sniffer "sk98" "/dev/sk98"

Place this near the start of the file; anywhere before the first
module directive should work.

5) Run CoMo.  Just go ./como from the base directory.  It's likely
that you won't see anything for a few minutes while timer calibration
is going through; be patient.

As before, timer calibration depends on the card receiving a
reasonable number of packets per second (a few dozen is usually
sufficient).