CoralReef Application Documentation

CoralReef programs starting with 'crl_' operate on coral sources as input, and take options in the form of -C 'coral_command'. For more information, see the CoralReef command usage document.

Utilities

crl_trace

Captures raw ATM cell traces from any CoralReef device or POS traces from a DAG device and dump them to a file in CoralReef format. The output filename can be set by the "-o outfile" command line option; the default name is '%s.crl'. '%s' will be replaced with the number of seconds since 1970-01-01 00:00:00 UTC. We recommend using a ".crl" suffix for these files. If outfile ends in ".gz", and CoralReef was compiled with libz, the output file will be gzipped. With one or more trace file as input, crl_trace can also be used to join multiple traces into one, and convert old trace formats to the (current) CoralReef format. Unlike most CoralReef applications, crl_trace does not try to correct for the FATM timestamp bug, but records raw data; other applications that read the trace later can correct for the bug.

If protocol rules configuration commands are given, they will be recorded in the file and used by other applications that read the file. However, "deny" commands do not actually prevent recording of the specified subinterface.

If no -Ccomment option is given, crl_trace writes the hostname and command line into the comment field of the tracefile.

To take traces of non-ATM sources, and output them to a pcap file, see crl_to_pcap.

crl_info

Prints information about the selected file to stderr. Reports the type of the hardware, the iomode it was in, the interface it is on, the hardware revision, bandwidth of the link, etc. In addition to standard CoralReef options, it accepts:
-v
print CoralReef package and file format versions
-d
print cell counts if applicable, else packet counts
-p
print packet counts
-s
short form: print counts only
-b
print per-block counts (if applicable)
-c
operate on cells instead of blocks (if applicable)
-r
use raw (uncorrected) time

Sample output.

crl_print

Prints ATM cells in hex and ascii. ATM headers are expanded to a more readable form, unless the "-r" (raw) option is specified.

Sample (sanitized) output.

crl_print_pkt

Prints information about full (reassembled) link or sub-network layer packets: interface, time, protocol-specific information, length, and data in hex and ascii. In addition to standard CoralReef options, it accepts:
-l layer
Print information about protocols up to layer (default 2).
-m layer
Skip information about layers below layer (default 1).
-P
Do not print partial packets.
-p
Print partial packets
-s
Print in short format, one line per packet.
-c
Print and verify IP checksum
The source code crl_print_pkt.c is a good example of using the packet API.

Sample (sanitized) output.

crl_time

Outputs to stdout one line per cell in trace. Each line after the header contains the following fields:
if
interface number
cell
cell number
high
high order bits of card timestamp (in hex)
low
low order bits of card timestamp (in hex)
seconds
timestamp, converted to seconds
difference
difference (in seconds) between this cell and the previous cell on the same interface
comment
description of any unusual conditions detected
  • high stamp inc (1) (when the high word of the timestamp increments)
  • XXX wrap error (on Fore cards, when hardware and firmware clocks have wrapping errors.)
  • XXX warning: large diff
  • XXX error: diff too small
  • XXX error: diff zero
  • XXX major error: negative diff
Useful for debugging hardware clock problems, allowing one to look at inter-arrival times and other statistics. In addition to standard CoralReef options, it accepts:
-i interface
Read data only from interface
-p
use packet timestamps (default is to use ATM cell timestamps if all sources are ATM, packet timestamps otherwise)
-r
Raw timestamps: don't try to correct card clock resets or Fore ATM clock wraps
-s
Sorts cells by time, interleaving interfaces.

Sample output.

crl_cut

Copies a section of an ATM cell trace file to another file. Useful for isolating a portion of a tracefile for later analysis, without requiring the storage of the entire original trace. In addition to standard CoralReef options, it accepts:
-ooutfile
Specifies the file to write the output to.
-iinterface
Read data only from interface
-nnum
Skip cells before the numth (default: 0)
-Nnum
Stop reading after the numth cell
-ttime
Read only cells with timestamp >= time (in seconds)
-Ttime
Read only cells with timestamp <= time (in seconds)

To cut a trace file by packet count (and output to a pcap file), see crl_to_pcap.

crl_guess

Usage: crl_guess [-d] filename

If filename is in any trace file format that CoralReef can read, crl_guess will attempt to identify the file format (including capture length), the subinterfaces contained within the file, and, if the interface was ATM, the link layer encapsulation protocol used on each subinterface. crl_guess ignores any protocol options recorded in the file, and attempts to guess the protocols by directly analyzing the packet headers. If the file contains records from multiple interfaces, crl_guess assumes they are all the same type of interface with the same set of subinterfaces and encapsulations.

The results of crl_guess are printed in a form suitable for use in a CoralReef configuration file, including a "source" command with prefix and iomode options, and, if the interface was ATM, a "proto" or "deny" command for each subinterface. Note that on ATM interfaces, virtual channels 0:0 through 0:15 are used for signalling, and crl_guess will always report them as UNKNOWN if they are present.

crl_guess can take up to a minute or more if some subinterfaces are truly unidentifiable, but is usually much faster when all subinterfaces are parsable or the file is total garbage.

Unlike most "crl_*" programs, crl_guess does not take -C options, and never requires a filename prefix or iomode to identify the file format; crl_guess is in fact useful for figuring out this information if you have forgotten it. Options:

-d
Print debug information.

Sample output.

Converters

crl_to_pcap (formerly crl_filter)

Acts like a CoralReef equivalent of tcpdump. Given any Coral source (not necessarily crl format), this application applies a BPF filter expression to all packets, and writes the matching packets to the output file in pcap format. With no filter, it allows all packets through; this is useful as a Coral-to-pcap converter. In addition to standard CoralReef options, it accepts:
-o outfile
Dump matching packets to outfile in pcap binary format, suitable for being read as a "pcap:" coral source or by "tcpdump -r". We recommend using a ".pcap" suffix for such files. (default: stdout)
-inum
Read only from interface num (default: read all interfaces of all sources)
-f expression
BPF filtering expression, same as for tcpdump (this does the same thing as the -C'filter=...' configuration option).
-r
Strip the link layer protocol and write only raw IP packets. This can be used to combine sources with different link layers into a single pcap file, or just to discard unneeded information. Packets that do not contain IP are discarded in their entirety.
-nnum
Skip packets before the numth (default: 0)
-Nnum
Stop reading after the numth packet
-ttime
Read only packets with timestamp >= time (in seconds)
-Ttime
Read only packets with timestamp <= time (in seconds)

crl_tofr+

This application reads one or more sources (in any format readable by CoralReef) and writes the packets to stdout in 'fr+' format. For more information on the fr+ format, see: http://moat.nlanr.net/Coral-tools/. However, the information there on Coral file format is VERY out of date and should be ignored.

crl_tofr

This application reads one or more sources (in any format readable by CoralReef) and writes the packets to stdout in 'fr' format. For more information on the fr+ format, see: http://moat.nlanr.net/Coral-tools/. However, the information there on Coral file format is VERY out of date and should be ignored.

crl_totsh

This application reads one or more sources (in any format readable by CoralReef) and writes the packets to stdout in 'tsh' format. For more information on the tsh format, see the tsh section of the command usage document.

crl_encode

Encodes the IP addresses stored in a coral trace as to protect the privacy of those logged as well as removing any cell payload that might have been captured. Like crl_trace, it does not correct timestamp errors, but leaves timestamps untouched. In addition to standard CoralReef options, it accepts:
-o outfile
Specifies the file to write the output to.

Dynamic reports

crl_rate (formerly crl_vpvc)

Collect IP-level stats, collecting the IP lengths, IP-packet counts, non-IP packet counts and IPv6 packet counts per interface/subinterface. Outputs summaries every interval seconds. interval defaults to 60 seconds. Useful for checking if a link is being utilized to its maximum allocated bandwidth. In addition to standard CoralReef options, it accepts:
-s
Outputs information in 'short mode', with only a single line for each interval.
-D[SITsit]
controls display options as follows:
S
displays subinterface-level information.
I
displays interface-level totals.
T
displays totals for all interfaces.
s, i, and t are the same as S, I, and T, respectively, except that redundant information is suppressed (e.g., if there's only one interface, only that total will be displayed).
The default is equivalent to -Dsit.

Sample output.

crl_rate_layer2 (formerly crl_vpvc_layer2)

Collect ATM-level stats, collecting the cell counts and bandwidth per VPI/VCI pair. Requires iomode = user. Outputs summaries every interval seconds. interval defaults to 60 seconds. Useful for making sure a monitor has been installed correctly. The output can be compared with SNMP and the expected bandwidth for the specified VPI/VCI pair. (And that you're even connected to the ones you thought you were!)

Sample output.

Static reports

crl_bycountry

Usage: crl_bycountry [-Ccoral_command]... source routing_table

Outputs the amount of traffic flowing to and from networks, and between networks, ASes, and countries. As opposed to crl_netnet, uses routing table information to determine the networks. Useful for finding inter-country or inter-AS traffic patterns. It requires the uncensored data files to generate sensible results. Source is any CoralReef source. Routing_table the name of a file contaning a parsed routing table (the output of parse_bgp_dump). Calls crl_ipmatrix internally, and uses the NetGeoClient library and server.

Sample output.

crl_hist

Outputs a report on packet and byte counts by IP length and protocol, port summary matrices for TCP and UDP, fragment counts by protocol, packet length histograms for the entire trace and for a list of applications, and the top 10 source and destination port numbers seen for TCP and UDP traffic. Useful for general reports on length, port, and protocol usage.

Sample output. (Note: port 0 means all ports.)

crl_hist_helper

Used as a subprocess of crl_hist. The interface between crl_hist and its helper is a private matter, and is subject to change without notice.

crl_tos

For each interface, displays the TOS of IP packets seen, and the percentage of packets that fall under each value. Useful for determining what TOS values are being used on a network, especially since the diffserv group has proposed using 'unused' bits from TOS.

Sample output.

crl_llcsnap

Prints out the all of the LLC/SNAP values in the trace, separated out by interface and VPI/VCI pairs. The number of occurrences is shown first. Note: Assumes that the input is ATM with ATM_RFC1483 (LLC/SNAP) encapsulation, and that exactly one cell per packet was captured (i.e., iomode=first=48). Useful for determining when a link, known to be carrying LLC/SNAP encapsulated traffic, has corruption, either in the card or elsewhere on the network.

Sample output.

Special-purpose applications

crl_portmap

Captures all packets from all hosts that connect to any other host's portmap port (111). It begins by capturing SYN packets sent to the portmap port on any host. Each time it sees such a packet, it also starts capturing all packets sent to or from the host that sent the portmap SYN packet. The idea behind this is that opening a connection to a portmap port could be the first step of an attack, so any host that does so should be carefully monitored.

In addition to standard CoralReef options, it accepts:

-o outfile
Dump to file outfile (without this option, there is no output. Use '-o -' to print to stdout)
-P
Do not allow partial packets

crl_dnsstat (members only)

The crl_dnsstat application watches for DNS queries on UDP port 53 and counts numbers of messages and numbers of queries, aggregated by any of source IP, destination IP, opcode, query type, query class. The subjects of queries are never recorded. The example output below shows the finest aggregation (most detail) it is capable of recording; command line options can be used to reduce the detail. The "notes" column displays any unusual statistics: the number of messages that contained multiple queries or zero queries, and the number of messages for which the number of queries was impossible to determine.

In addition to standard CoralReef options, it accepts:

-plen
aggregate hosts by CIDR prefix length (default: 32)
-a
resolve IP addresses to hostnames (requires -p32)
-n
print DNS code numbers, not symbols
-S
ignore IP source address
-D
ignore IP destination address
-Q
don't count by query opcode/class/type
-h
print in more human-friendly format
-r
do not count messages with RD set
-s
print information on hash table usage
-u
print contents of unusual messages to stderr

Sample output, with source IP addresses changed for privacy.

Traffic flow applications

crl_flow

Creates summaries of traffic flow for post-processing by t2_report and other scripts. With further refinements, will replace several other summary scripts. After each interval (defined with the -Ci=n option), crl_flow outputs tables of flows which expired during the interval and tables of flows which are still active, aggregated by source and destination IP addresses, protocol, and source and destination ports. The tables are broken down by subinterface (e.g., ATM VPI/VCI). In addition to standard CoralReef options, crl_flow accepts:
-p length
Specify prefix masklength; can be between 8 and 32. Default to 32.
-A
Print active flows in addition to expired flows every interval (otherwise, still-active flows will be printed at end of run)
-a
Display the cname of the addresses. (Must use masklength of 32 to make sense.)
-s
Print hashtable statistics (for development).
-b or -B
Dumps tables in binary format, suitable for efficient input to any t2_* application
-h
Dumps tables in a format that's easier for humans to read.
-o outfile
Specifies the output file to write to (default to stdout). outfile is the name of the output file. '%s' within the filename will be replaced with the number of seconds since 1970-01-01 00:00:00 Z. '-' means standard output.
-O outfile
Like -o, except that a new file is written every interval. If outfile contains '%s', then there will be a file for every interval, otherwise the file will be constantly over-written with the latest interval.
-I
Expire all flows at the end of each interval (like crl_traffic2 in earlier versions of CoralReef).
-Talgorithm
Use algorithm to expire flows:
fN
expire flows after a fixed period of N seconds of inactivity (like NetFlow).
mM,I
expire flows after an inactive period of M times the largest inter-packet gap, with the gap initially set to I seconds (like NeTraMet).
N
no expiry (default)

By default, flows never expire; you must give at least one of the -I or -T options to make flows expire. The -I and -T options may be used together if you're feeling adventurous.

If interrupted, crl_flow will stop reading, and will report the last partial interval (prior to version 3.4, crl_traffic2 would lose the last interval data).

Sample output.

crl_traffic2

Equivalent to crl_flow -I.

t2_report

Generates HTML summary reports from the output of crl_traffic2. Described in its own document.

t2_ASmatrix

Takes a parsed routing table (from parse_bgp_dump) and crl_traffic2 output, and outputs similar output to crl_traffic2, but with source/destination IP pairs, ports and protocols replaced by source/destination AS pairs. crl_traffic2 output is read from standard input. Note: be sure to use '-p 32' on crl_traffic2 to get accurate IP->AS mapping. t2_ASmatrix accepts the following options:
-S[bpf]
Controls sorting options as follows:
b
sorts by bytes.
p
sorts by packets.
f
sorts by flows.
-ntopn
limits the number of entries displayed to topn. (defaults to showing all entries)

Example call: crl_traffic2 -Ci=10 -p 32 /dev/point0 | t2_ASmatrix

Sample output.

t2_top

Takes crl_traffic2 output, and sorts entries by keys, bytes, packets, or flows. Data is read from standard input.
Options:
-D[m]
Controls display options as follows:
m
shows meta-information about the input tables.
-S[bpf]
Controls sorting options as follows:
b
sorts by bytes.
p
sorts by packets.
f
sorts by flows.
(with no sorting option, entries will be sorted by keys)
-n topn
Limits the number of displayed entries to topn. (defaults to showing all)
-h
Formats the output in a more human-readable form, attempting to line up the field columns.

Sample output.

t2_convert

Takes crl_traffic2 output, and outputs similar output to crl_traffic2, but with aggregation of the source/destination IP pairs, ports and protocols. Data is read from standard input.
Options:
-t
Outputs timestamp information for each entry.
-F
Flattens the flows count to 1 for each entry in the converted table.

Example call: crl_traffic2 -Ci=10 /dev/point0 | t2_convert Proto_Ports_Table

The set of table types which can be aggregated are listed in the documentation for the Tables objects as the various make_XYZ commands. These include: IP_Matrix, src_IP_Table, dst_IP_Table, Proto_Ports_Table, Port_Matrix, src_Port_Table, dst_Port_Table.

t2_rate

Similar to crl_rate, outputs information about every interface/subinterface, with the addition of a tuple (unique connection) rate, and works on crl_traffic2 output instead of on CoralReef devices or tracefiles.
Options:
-s
Outputs information in 'short mode', with only a single line for each interval.
-D[SITsit]
controls display options as follows:
S
displays subinterface-level information.
I
displays interface-level totals.
T
displays totals for all interfaces.
s, i, and t are the same as S, I, and T, respectively, except that redundant information is suppressed (e.g., if there's only one interface, only that total will be displayed).
The default is equivalent to -Dsit.

Sample output (normal mode).

Sample output (short mode).

Routing table parser

parse_bgp_dump

Reads in a Cisco bgp dump file (such as those available at http://moat.nlanr.net/AS/), and converts into a simpler format that maps network prefixes and masklens to source ASes. The output is used by ASFinder in apps such as crl_bycountry.

Sample output.

Traffic validation

crl_idle_verify

Despite the name, checks to make sure incoming ATM cells are valid IP (not idle) cells. Displays some stats on ones that aren't. The assumption is that since much ATM traffic is IP, if a large percentage of these cells are failing IP checks, they must be corrupt. Useful for low-level debugging of ATM networks, in conjuction with crl_fail.

Sample output (stdout).
Sample output (stderr).

crl_fail

Makes a trace of those cells which fail IP validity checks. It does not, however, do checksum calculations. Useful for general network debugging and culling out interesting (e.g., possibly bad cells) parts of a trace, to save space. For example, if crl_idle_verify shows an abnormally high amount of non-IP cells on an ATM link known to be carrying IP traffic (and culling out non-IP VPI/VCI pairs), one could run crl_fail to output a small trace of bad cells, and run crl_llcsnap on that trace. The default value of the output file is '%s.crl'. '%s' will be replaced with the number of seconds since 1970-01-01 00:00:00 Z. The filename can be overridden by the '-o outfile' commandline option. If outfile ends in ".gz", and CoralReef was compiled with libz, the output file will be gzipped.

crl_nonip

Soon-to-be-defunct program.
Displays LLC/SNAP information about any non-IP packets in a coral trace. Note: Assumes that encapsulation is LLC/SNAP, outputs the appropriate 8 bytes in LLC/SNAP format. Thus it only works on links with DLT_ATM_RFC1483 encapsulation.

Sample output.

Other

spoolcat

Usage: spoolcat glob

Continuously scans for files matching glob, copies them to stdout, and deletes them. Glob is a standard file globbing pattern, and must be quoted from the shell. Useful for spooling .t2 files into t2_report.

playback

Generates a cell, repeatedly, on a device. Currently only works with the Fore ATM devices. Takes the board number and optionally the vpi and vci for the connection. The cell to be generated is hard-coded. This application is not built by default.

crl_hostmatrix

Soon-to-be-defunct.
Takes the output from crl_ipmatrix and displays the source hostname, destination hostname, packets, ratio of packets to total packets, bytes, and ratio of bytes to total bytes. All arguments are passed directly onto crl_ipmatrix. Useful for general debugging of traffic flow and scanning which hosts are sending a large amount of traffic. Each line has the following tab-delimited format: 
src_hostname dst_hostname packet_count packet_percent byte_count byte_percent

Sample (sanitized) output.

crl_flowscnt

Groups packets into bins in order to measure flows. In addition to a final report, it will report partial results every 100000 packets. Basis of a framework for comparing different definitions of flows and analyzing which definition gives more useful data.

Sample output.

crl_sample

Sample Perl application for the CRL module. Prints statistics about a trace. Currently prints the number of IP packets, IP bytes, TCP packets, TCP bytes, TCP acks, TCP pushes, number of packets per protocol, and the number of bytes per protocol.

Sample output.

Obsolete

crl_netnet

Soon-to-be-defunct program.
Outputs a matrix showing the amount of traffic flowing between different networks, separated by VPI/VCI pairs. Note: does not use routing table information, only prefix masklength. This is especially handy for analyzing traffic on a particular network, like a university, and studying (from within it) the traffic between different sections. Options:
-p length
Specify prefix masklength; can be between 8 and 32. Default to 16.
-a
Display the cname of the addresses. (Must use '-p 32' to make sense.)
-s
Show statistics; will dump the hashtable's statistics before quitting.

Sample output.

crl_ipmatrix

Soon-to-be-defunct. Use only if you wish to pipe the output into crl_hostmatrix; otherwise, use "crl_flow <options> | t2_convert IP_Matrix".

Keeps track of the total number of packets and bytes that have been seen between each source IP and destination IP. Can be instructed to dump the information periodically if the dumpRate variable is set. Otherwise, the first two lines of output are the total number of packets and bytes, respectively. Useful for general debugging of traffic flow and scanning which IP addresses are sending a large amount of traffic.

crl_portsummary

Soon-to-be-defunct program.
Gives a summary of the ports packets are going to and from across a coral device. Lists the interface, protocol, source and destination port of the packet as well as the length. Periodically dumps information. Useful mainly as input to crl_hist. Each line has the following tab-delimited format: 
interface protocol ports_ok src_port dst_port packet_len packet_count

Sample output.

crl_ipaddr

Obsolete. Use "crl_print_pkt -s" instead.

Prints out the timestamp, IP source, destination, and protocol for every packet. Useful for looking at the interarrival times in a low-level analysis of packets between specific IP addresses.

Sample output.

crl_timestamps

Obsolete. See crl_time.

crl_toascii

Obsolete. Use crl_print or crl_print_pkt.

t2_aggregate

This program is deprecated. Use t2_convert and t2_top instead.

t2_top10

This program is deprecated. Use "t2_convert src_IP_Table | t2_top [-S[b|p|f]] -n 10" instead.

t2_tuple

This program is deprecated. Use "t2_rate -Ds".