Basic CoralReef command usage

CoralReef applications whose names begin with "crl_" accept command line options of the form -C "coral_command", followed by one or more filenames of CoralReef sources. Note that if the option contains spaces, it must be quoted from the shell. For example,
crl_trace -Cd=600 -C "comment site_name" /dev/point0

Sources

CoralReef applications operate on "sources", which include several types of live network interfaces/devices, and several types of tracefiles containing data recorded from one or more network interfaces/devices. The name of a source may be prefixed to indicate what type of source it is. If the name has no prefix, CoralReef will attempt to determine the type by the filename suffix (the suffixes ".enc" and ".gz" are skipped); if there is no suffix, CoralReef will attempt to determine the type by the file's device type or magic number. The types are:

Live sources

For all source types, bandwidth and physical options are useful only to tell CoralReef what to expect from the source, if CoralReef can not determine it from the source itself. The bandwidth and physical options never change the configuration of the source.

Trace file sources

For all file sources, the special filename "-" indicates that a tracefile should be read from stdin. If libcoral was compiled with libz, trace files in most formats may be gzipped, even on stdin. As of version 3.5, trace files are not limited to regular files; they may also be devices (e.g., /dev/fd/*) or FIFOs.

Configuration Commands

These commands can be used on the command line as the argument to a -C option, or in a configuration file. Valid commands are listed below, but not all commands are meaningful in all applications. For commands that take arguments, the arguments may follow '=' or whitespace.
# comment
Ignored.

version
Print the CoralReef package version and the current file format version.

config=filename
f=filename
Read CoralReef commands from filename. This is normally used on the command line, but can be used in a config file to chain config files.

comment=string
Defines a string that will be written into the file header by the coral_write functions.

iomode=[option...]
m=[option...]
Defines the default iomode options for subsequent coral sources. On a live source, an iomode option specifies how much data to capture per packet, or other configuration. On a file source that does not contain the options used to record it (i.e., anything other than pcap and CAIDA .crl formats), an iomode option can be used to tell CoralReef what to expect in the file. Multiple options may be separated by commas or whitespace. If a boolean option is preceded by "!", it will be disabled. Some applications ignore this command and use a fixed iomode. In those that don't, the default is usually "rx,first=48" (i.e., capture only the first cell of each AAL5 PDU). Note that not all sources support all options; see the section on sources above. Options:
[first=]N
capture the first N bytes of layer 2 PDU (packet or frame). On ATM devices, N is rounded up to a multiple of 48 bytes (1 cell).
last
capture last cell of each ATM AAL5 PDU (packet).
user
capture all bytes of each packet (overrides first).
ctrl
capture OAM/RM ATM cells.
idle
capture idle ATM cells.
all
equivalent to "user,ctrl,idle".
fw=name
use file name as firmware image for FATM or POINT cards. The default is selected automatically based on the source type and iomode, and should usually not be changed. You should use this option only if you know what you're doing, and use the correct source type and iomode.
{bandwidth|bw}=rate
set a device to use bandwidth rate, if it is configurable;
phy[sical]=type
set a device to use physical layer type type, if it is configurable. If this is not specified, CoralReef may infer it from the data link layer protocol defined by a "proto" command.
proto=[subif=]protocol
allow=subif[=protocol]
deny=subif[=protocol]
Set the data link layer protocol of the device. See the "proto", "allow", and "deny" commands for details.
echo
enable echoing of received data (aka passthrough or loopback) on devices which support it.
rx
allow receiving (this usually should not be changed on command line).
tx
allow transmitting (this usually should not be changed on command line).
vlan
source contains IEEE 802.1Q VLAN. If you want to use a pcap filter, this option is necessary to work around a bug in libpcap (as of version 0.7.0-281, at least).
xilinx=name
strongarm=name
scramble
As of CoralReef version 3.5, these options are no longer supported, since DAG cards are expected to be pre-configured.

source=sourcename[,option...]
src=sourcename[,option...]
Defines a coral source sourcename, as described under Sources. There may be multiple "source" commands; each one defines a new CoralReef source with its own options. The options may be any of the options accepted by the "iomode" command above, and will override any options specified in earlier "iomode" commands. Options specified in a "source" command affect only the source defined in the same "source" command.

proto=protocol
Tells libcoral to interpret traffic as data link protocol protocol.
proto=subif=protocol
allow=subif[=protocol]
deny=subif[=protocol]
proto and allow tell libcoral to accept traffic from subinterface subif, and optionally to interpret it as data link protocol protocol.

deny tells libcoral to discard traffic from subinterface subif. Protocol is accepted but ignored, to make it convenient to change a config file line from proto to deny and back without deleting protocol.

The proto, allow, and deny commands are collectively called "protocol rules". They are not valid in applications that read blocks (as opposed to cells or packets; i.e., crl_trace). When subif is an ATM vpi:vci, these commands specify RFC 1483/2684 VC Based Multiplexing. Subif should not be used with other types of interfaces (to filter by IEEE 802.1Q VLAN, use a '-Cfilter vlan vlan_id' command.)

On interfaces that have subinterfaces (i.e., ATM), packets are tested against the subinterface rules in the order the rules are defined, and the first matching rule is used. Packets that do not match any rule or match a rule without a specified protocol are assumed to have the interface's protocol.

Protocol is usually a layer 2 encapsulation. If null encapsulation (sometimes called "aal5mux" on ATM subinterfaces) is used, protocol may be a layer 3 protocol. Valid protocol names are listed below (although not all of them make sense in a protocol rule; some are used only for displaying information).

For ATM interfaces, a subinterface is specified as "vpi:vci". A field of subif will be interpreted as hex if it begins with "0x", otherwise octal if it begins with "0", otherwise decimal. A field of "*" will match all possible values.

For pcap interfaces, the link layer protocol is determined from the interface. For ATM interfaces, if no protocol rules are specified, the default link layer protocol for virtual channels 0:0 through 0:15 is UNKNOWN, for 0:16 is ILMI, and for all other virtual channels is ATM_RFC1483. For all other interface types, the default link layer protocol is UNKNOWN.

Example rules for an ATM network with signaling on VPVC 0:16, null-encapsulated ("aal5mux") IPv4 on VP 27, and RFC1483 LLC/SNAP on VP 42, and uninteresting traffic on all other VCs:
deny=0:16
proto=27:*=IPv4
allow=42:*
deny=*:*
A final "proto=ATM_RFC1483" rule could have been given, but is not necessary, since ATM_RFC1483 is the default data link protocol for ATM devices. The "allow=42:*" rule could also have been written "proto=42:*=ATM_RFC1483"

filter=expression
In CoralReef applications that read packets, only packets that match the tcpdump/pcap expression will be read. If multiple filter expressions are specified (by multiple "filter" commands and/or by the application), they will be joined with "and". See the documentation for tcpdump for the syntax of expression. Note: due to a bug in libpcap, when reading a VLAN interface, you must specify the "vlan" iomode option or begin your expression with "vlan and", or operations on layer 3 and above will not work. This bug is present in libpcap versions 0.6.2 (the first to support VLAN at all) through 0.7.0 (the latest available at the time of this writing). If you have a later version of libpcap and you are not sure the bug is fixed, know that it is always safe to specify the "vlan" option to CoralReef if the source contains VLAN traffic. Also note, due to a bug in libpcap 0.6.2, it is not possible to apply a filter to VLAN and non-VLAN sources simultaneously with libpcap 0.6.2 (this was fixed in 0.7.0). You can also use "crl_to_pcap -r" to strip the link layer encapsulation from a VLAN source to make it a non-VLAN source.

p[ackets]=N
In applications that read packets, stop reading after N packets. 0 indicates no limit. Default is 0.

c[ells]=N
In applications that read cells, stop reading after N cells. 0 indicates no limit. Default is 0.

b[locks]=N
In applications that read blocks or cells, stop reading after N blocks. 0 indicates no limit. Default is 0.

d[uration]=seconds
In some CoralReef applications, this determines how many seconds to run; 0 usually indicates unlimited runtime. Default is 0.

i[nterval]=seconds
In some CoralReef applications, this determines how many seconds between some periodic operation; 0.0 usually indicates that no periodic operation should be done. The value can be specified with up to 6 decimal places. Default is 0.0.

v[erbosity]=level
Sets the verbosity level of libcoral and possibly the whole program. Level 0 is error messages only; level 1 includes warnings; level 2 and higher include additional information. Default is 1.

norm[alize]={0|1}
If set to 1 (the default), all timestamps will be normalized to the unix epoch (if possible). If set to 0, timestamps may be relative to the unix epoch or to the time the interface was started. Applications that read packets, sort by time, or use interval or duration may ignore this option and force normalization when reading from multiple interfaces that were not started at the same time.

gz[ip][=level]
Enables gzip compression of files written by coral_write() (e.g., the -o option of crl_trace). The level parameter can be 0 (no compression), or between 1 (fastest) and 9 (best compression). The default compression level is 1 to make it practical for use on live sources. (In versions of CoralReef before 3.5, the default level was 6).

e[rrfile]=filename
Output of libcoral and possibly the whole program will be written to filename. Default is stderr.
The "source", "iomode", and "filter" commands are cumulative; for any other repeated commands, only the last one given is effective. So, for example, if file "coral.cfg" contains "verbosity=2", and the command line options are "-Cverbosity=0 -Cconfig=coral.cfg", then the verbosity level will be 2; but if the command line options are reversed, the verbosity will be 0.

Some other common options available on some applications are:

-ofilename
Output to file filename. If filename ends in ".gz", or the -Cgzip option was specified, the file will be gzipped. The recommended suffix for (uncompressed) CoralReef files is ".crl". The special filename "-" indicates standard output.
-P
When reading packets, do not read partial packets
-p
When reading packets, do read partial packets (enabled by default)
-?
Display a summary of the options available in this application. (Note: in some shells, you may need to type -\? or '-?').

Protocols

When specifying a protocol on the command line or configuration file, only the name is needed (e.g., PPP). In the C API, identifiers are formed by concatenating "CORAL_", prefix, "_", and name (e.g., CORAL_DLT_PPP). In the perl API, identifiers are formed by concatenating the prefix, "_", and name, in the Coral:: namespace (e.g., $Coral::DLT_PPP). In the table below, an "ok" in the "pr" column indicates the protocol makes sense to use in a configuration protocol rule.

layer1 prefix name description pr standards
PROTO UNKNOWN unknown
1 PHY ATM Asynchronous Transfer Mode (The default link layer protocol for virtual channels 0:0 through 0:15 is UNKNOWN, for 0:16 is ILMI, and for all other virtual channels is ATM_RFC1483.) af-bici-0013.003
1 PHY POS Packet Over SONET (proto must also be specified; there is no default)
2 DLT ATM_AAL5 ATM Adaptation Layer type 5
2 DLT ATM_RFC14832 LLC encapsulation of Routed protocols (IPv4, IPv6, ARP, PPP) over AAL5 (aka "aal5snap" on Cisco routers). (LLC encapsulation of Bridged protocols is not yet implemented.) ok RFC 1483, 2684
2 DLT LANE_IEEE8023 LAN Emulation for IEEE 802.3/Ethernet, over AAL5. (LAN Emulation for IEEE 802.5 is not yet implemented.) ok af-lane-0084.000
2 DLT ILMI Integrated Local Management Interface, over AAL5. ok af-ilmi-0065.000
2 DLT ETHER DIX Ethernet (also accepts IEEE 802.3), including IEEE 802.1Q VLAN ok
2 DLT IEEE802 IEEE 802.3 (also accepts DIX Ethernet), including IEEE 802.1Q VLAN ok IEEE 802.3
2 DLT IEEE8021D IEEE 802.1D bridge spanning tree IEEE 802.1D
2 DLT CHDLC Cisco HDLC, over POS ok
2 DLT PPP Point-to-Point Protocol ok RFC 1661
2 DLT PPPoHDLC PPP over HDLC RFC 1662, 2615
2 DLT PPPoED PPP over Ethernet, discovery stage RFC 2516
2 DLT PPPoES PPP over Ethernet, session stage RFC 2516
2 DLT BRIDGED_LAN Bridged IEEE 802.3/Ethernet (over PPP) RFC 1638
2 DLT GIGX DEC Gigaswitch encapsulation (?), over AAL5 (no validation, assumed to contain ATM_RFC1483) ok
3 NETPROTO IPv4 or IP Internet Protocol, version 4 ok RFC 791
3 NETPROTO IPv6 Internet Protocol, version 6 ok RFC 2460
3 NETPROTO ARP Internet Address Resolution Protocol (Ethernet and ATM) ok RFC 826, 1293, 1577, 2225
3 NETPROTO IPX IPX ok
3 NETPROTO IPX_E IPX (ECONFIG E option) ok
3 NETPROTO APPLETALK AppleTalk ok
3 NETPROTO AARP AppleTalk Address Resolution Protocol ok
4 IPPROTO TCP Transport Control Protocol, over IP RFC 793
4 IPPROTO UDP User Datagram Protocol, over IP RFC 768
4 IPPROTO ICMP Internet Control Message Protocol, over IPv4 RFC 792
4 IPPROTO ICMP6 Internet Control Message Protocol, over IPv6 RFC 2463
4 IPPROTO HOPOPTS3 IPv6 Hop-by-Hop Options RFC 2460
4 IPPROTO ROUTING3 IPv6 Routing Header RFC 2460
4 IPPROTO FRAGMENT3 IPv6 Fragment Header RFC 2460
4 IPPROTO ESP3 IPv4/IPv6 Encap Security Payload RFC 2406
4 IPPROTO AH3 IPv4/IPv6 Authentication Header RFC 2402
4 IPPROTO DSTOPTS3 IPv6 Destination Options RFC 2460
5 PROTO SNMP Simple Network Management Protocol RFC 1157

1The division into OSI layers is crude, since many are actually sublayers (especially within layer 2).
2To specify RFC 1483 VC Based Multiplexing, use the proto configuration command.
3These are part of IP, but it is convenient to treat them as being encapsulated in IP or each other.

We expect to support more protocols in the future, depending on demand.