Getting Started Using CoralReef

Getting Started with CoralReef Software

This document only describes using the CoralReef software package. It assumes your hardware is already set up according to the vendor's instructions and the "Hardware" section of the FAQ, the drivers are installed if you are using special capture cards, your monitoring interfaces are connected to the network you plan to monitor, and that the CoralReef software is installed according to the INSTALL file in the top directory of the software distribution.

Testing your installation

Most of the examples below use a DAG 4.x card, /dev/dag0. For Point cards, use /dev/point0; for FATM cards, use /dev/fatm0; for native system interfaces like eth0, use a name like if:eth0.

If you are using CoralReef with an ATM card (Point or FORE ATM), a good first test that everything is set up correctly is crl_rate_layer2. Try a command like:

    crl_rate_layer2 -Cd=60 /dev/fatm0
This will print a summary of the number of ATM cells and data rate seen on each VC in a 60 second period. If these values look reasonable, you know your hardware and drivers are set up correctly. If you have a POINT card and see a large number of unexpected VC's in addition to the expected VC's, especially at high total traffic rates, you may be experiencing a known bug in which the POINT card shifts ATM cells by a multiple of 4 bytes.

For any type of interface, try crl_rate next. For example,

    crl_rate -Cd=60 /dev/dag0
This will print a summary of IP packets, IP bytes, and non-IP datagrams seen on the interface in a 60 second period, broken down by subinterfaces if applicable (e.g., ATM VPVC). If you're using an ATM interface, this assumes that each VC contains traffic encapsulated with LLC/SNAP according to RFC 1483. If this is not true, you'll see a lot of non-IP packets reported in the example above. If you want to ignore certain VCs (such as those dedicated to signalling), you can exclude them with the deny option. If some or all of your VCs contain an encapsulation other than RFC 1483, you can specify that with the proto option. (See the Command Usage document.) For example, if you have null-encapsulated IP traffic on VP:VC 42:6, ATM_RFC1483 traffic on VP:VC 27:3, and there's signalling traffic on VP:VC 0:16 that you don't care about, you might have a Cisco router with the configuration
    atm pvc 1 42 6 aal5mux ip
    atm pvc 2 27 3 aal5snap
and you would use a CoralReef command like this:
    crl_rate -C'deny 0:16' -C'proto 42:6 IP' -Cd=60 /dev/fatm0
This will print the same summary as the previous example, except that VP:VC 0:16 will be ignored, VP:VC 42:6 will be interpreted as containing null-encapsulated IP, and every other VP:VC will be interpreted as containing ATM_RFC1483. You may want to put these proto and deny commands in a configuration file, which you can use with any crl_* application with the -Cf=file option.

For more information on applications, see the Applications document.

Writing your own software with CoralReef

Links to the documentation for C and perl APIs can be found in the main documentation index. If you are writing in C or C++, we suggest starting your project with a copy of $prefix/Coral/lib/example ($prefix is typically /usr/local). That directory contains an example C program that uses libcoral, and Makefile that knows how to find libcoral headers and libraries to build the program.

Related Objects

See https://catalog.caida.org/software/coralreef/ to explore related objects to this document in the CAIDA Resource Catalog.