crl_
" accept command line options of the form
-C "coral_command"
, followed by
the names of one or more 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
CoralReef applications operate on "sources" of network traffic.
Simple sources 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.
CoralReef also recognizes "compound" sources, which consist of the
concatenation of the data in multiple simple sources. On the command line of
a crl_* application, a compound source is specified by surrounding a list of
simple sources with "[" and "]". (There must be space between the
brackets and the names in the list.)
The files must be listed in time order.
All simple sources that make up a compound source must be the same type
and should not have prefixes.
If a prefix is required, it should be placed before the "[", with no space.
The following example has one source consisting of three dag files:
crl_flow -Ci=60 dag:[ trace1 trace2 trace3 ]
The types are:
if:interface
" (The "if:" prefix is always required.)
first=0..65535,user
ifconfig(8)
. On Linux,
the pseudo-interface named "any
" listens to all interfaces.
CoralReef uses libpcap to read "if:
" sources.
crl:/dev/dagN
" (prefix may be omitted)
dag
" driver on Linux or FreeBSD
nif=1..4,first=48..720,last
nif=1..4,first=15..1536,varlen
nif=1..4,first=15..1536,varlen
phy
and proto
iomode options.
cat /proc/dag
" will report the device is "Busy");
the card must be re-initialized before another
process can read from it.
crl:/dev/fatmN
" (prefix may be omitted)
fatm
" driver on FreeBSD
first=0..48,last,echo
(libcoral allows first=96..144
and user
, but the firmware fails)
crl:/dev/pointN
" (prefix may be omitted)
point
" driver on FreeBSD
first=0..144,idle,ctrl,last,user,all
(echo
is always enabled)
-
" 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.
crl:filename
" (prefix may be omitted)
crl:filename
" (prefix may be omitted)
dag:filename
" (prefix may be omitted if
filename has ".dag" suffix)
dagsnap
tracefile (legacy or ERF) with 64 bit timestamps.
All combinations of varlen, novarlen, and slen are supported
(varlen records were not supported before CoralReef 3.7).
ERF files (DAG version >= 3.5) contain physical and datalink
information, so it is not necessary to specify them on the command line.
However, Legacy (DAG version < 3.5) files contain no record of
what options were used, so you must specify the physical and datalink
layer protocols with the phy
and proto
iomode options.
The bw
option may be specified, but is not required.
E.g., a file created with "dagsnap -p12 -n2 foo.dag
"
on a DAG 3.2 card should be specified with the coral option
"-C'src dag:foo.dag
bw=OC12c,phy=ATM,96'
".
To avoid needing to specify options every time for legacy DAG files,
you could run
crl_to_dag
with the options once to convert the
DAG legacy file to a DAG ERF file, and use the ERF file from
then on; or, put the options in a config file and use a command option
like "-Cf=foo.cfg
".
pcap:filename
" (prefix may be omitted
if filename is a regular file)
tsh:filename
" (prefix may be omitted if
filename has ".tsh" suffix)
-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
version
config=filename
f=filename
comment=string
iomode=[option...]
m=[option...]
!
",
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:
nif=N
[first=]N
last
user
first
).
ctrl
idle
all
user,ctrl,idle
".
varlen
fw=name
{bandwidth|bw}=rate
phy[sical]=type
proto
" command.
proto=[subif=]protocol
allow=subif[=protocol]
deny=subif[=protocol]
proto
",
"allow
", and
"deny
"
commands for details.
echo
rx
tx
vlan
xilinx=name
strongarm=name
scramble
source=sourcename[,option...]
src=sourcename[,option...]
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
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 DAG POS interfaces, the default link layer protocol is CHDLC. For all other interface types, the default link layer protocol is UNKNOWN.
deny=0:16
proto=27:*=IPv4
allow=42:*
deny=*:*
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
filter
" commands and/or by the application),
they will be joined with "and
".
See the documentation for tcpdump
for the syntax of expression.
If pcap can not parse the layer 2 headers (e.g., MPLS),
the filter may not work as expected;
see ipfilter for a solution.
Note: due to the design of libpcap and BPF, 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.
If your filter does not need to analyze layer 2 headers, you can
use ipfilter instead to avoid needing to
specify "vlan
".
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.
Note that discarded packets still count towards duration and interval.
prefilter=expression
ipfilter=expression
ip[0] & 0xf0 == 0x40
" instead of "ip
"
to match only IPv4 packets, and
"ip[0] & 0xf0 == 0x60
" instead of "ip6
"
to match only IPv6 packets.
anon[ymize]=option[,option...]
ip
ipv4
ipv6
keep
zero
cryptopan
bits
is less than the full address
length, the trailing bits will be zeroed.
For IPv6, a reasonable choice might be
"cryptopan,bits=64
": this will preserve prefix
relationships in the network part of the address, but
obliterate the host part.
src
dst
bits=N
bits=-N
keepmcast
cryptopan
, there is no guarantee that
other anonymized addresses will not collide with multicast
addresses.)
embed
cryptopan
, there is no guarantee that
other anonymized addresses will not collide with these special
addresses.)
keyfile=filename
ip
, ipv4
,
or ipv6
is irrelevant):
notrunc
anon=cryptopan,ipv4,src,keyfile=./ip4.key,ipv6,keyfile=./ip6.key
".
Another example:
zero the low 80 bits of normal IPv6 addresses
and the low 11 bits of IPv4 addresses,
including those embedded within IPv6 addresses,
but leave IPv6 multicast addresses alone:
"anon=zero,ipv4,bits=-11,ipv6,bits=-80,embed,keepmcast
".
Note that prior to version 3.8.5, when anonymization was enabled,
libcoral would discard packets that did not have a recognizable layer
3 header and packets whose outermost layer 3 header was not
anonymizable. Now, those packets are not discarded, but are truncated
at the beginning of the unanonymizable part (unless "notrunc" is
specified).
If you wish to discard non-IP packets, use
"filter='not ip'
" or similar option.
anon[ymize][=filename]
anon=ipv4,cryptopan[,keyfile=filename],ipv6,zero
"
(for backward compatibility).
p[ackets]=N
-Cskippackets
).
0 indicates no limit. Default is 0.
{skippackets|sp}=N
c[ells]=N
b[locks]=N
d[uration]=time
-Cd=3600
" and
"-Cd=1:00
"
both set duration to 1 hour.
Default is 0.
mintime=time
maxtime=time
i[nterval]=time
alignint[=1]
ai[=1]
-Ci=00:05:00
-Cai
",
the first interval ends at 13:30:00
(and since it began at 13:27:52, the length of the first interval
is only 0:02:08, not 0:05:00).
Subsequent intervals will thus start on rounded boundaries:
13:30:00, 13:35:00, and so on.
Interval rounding makes the most sense when the interval length
is evenly divisible into 1 hour.
Note that this option does not cause the
duration to be rounded.
alignint=0
ai=0
dropinterval=time
di=time
v[erbosity]=level
norm[alize][=1]
norm[alize]=0
gz[ip][=level]
sort
ignore_time_err
e[rrfile]=filename
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:
.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.
-\?
or '-?'
).
Rotated files can be read by coral applications using the
compound source feature,
by enclosing the list of generated files in "[" and "]".
If the name of the rotating file is chosen so that shell globbing
sorts the names in temporal order, you can later use a convenient file glob
to generate the compound source list on the command line.
For example, if you took two sets of simultaneous traces,
one with the rotating name "in-%Y%m%d-%H%M%S.dag
"
and the other with "out-%Y%m%d-%H%M%S.dag
",
they could later be read by another application like this:
crl_app ... [ in-20040921-*.dag ] [ out-20040921-*.dag ]
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, the "use" column
contains "Y" if coral can parse the protocol and/or
"P" if the protocol makes sense to use in a configuration
protocol rule.
layer1 | prefix | name | description | use | 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.) | Y | 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 | Y | |
2 | DLT
| ATM_RFC1483 2
| Multiprotocol Encapsulation over AAL5 (aka "aal5snap" on Cisco routers). Recognized protocols include IPv4, IPv6, ARP, PPP, and Bridged IEEE 802.3. | YP | 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.) | YP | af-lane-0084.000 |
2 | DLT
| ILMI
| Integrated Local Management Interface, over AAL5. | YP | af-ilmi-0065.000 |
2 | DLT
| ETHER
| DIX Ethernet (also accepts IEEE 802.3), including IEEE 802.1Q VLAN | YP | |
2 | DLT
| IEEE802
| IEEE 802.3 (also accepts DIX Ethernet), including IEEE 802.1Q VLAN | YP | IEEE 802.3, 802.2; RFC 1042 |
2 | DLT
| IEEE8021D
| IEEE 802.1D bridge spanning tree | IEEE 802.1D | |
2 | DLT
| CHDLC
| Cisco HDLC, over POS | YP | RFC 1547 (4.3.1) |
2 | DLT
| MPoFR
| Multiprotocol over Frame Relay (also, Frame over SONET) | YP | RFC 1490, 2427 |
2 | DLT
| UoPOS
| Unknown protocol over PoS - libcoral will attempt to parse this as CHDLC, PPPoHDLC, or MPoFR | YP | |
2 | DLT
| PPP
| Point-to-Point Protocol | YP | RFC 1661, 2364 |
2 | DLT
| PPPoHDLC
| PPP over HDLC | Y | RFC 1662, 2615 |
2 | DLT
| PPPoED
| PPP over Ethernet, discovery stage | Y | RFC 2516 |
2 | DLT
| PPPoES
| PPP over Ethernet, session stage | Y | RFC 2516 |
2 | DLT
| BRIDGED_LAN
| Bridged IEEE 802.3/Ethernet (over PPP) | Y | RFC 1638 (4.2) |
2 | DLT
| GIGX
| DEC Gigaswitch encapsulation (?), over AAL5 (no validation, assumed to contain ATM_RFC1483) | YP | |
2 | DLT
| MPLS
| Multi-Protocol Label Switching (may contain IPv4, IPv6, or ETHER) | Y | RFC 3032 |
2 | DLT
| NULL
| BSD "null" | YP | |
2 | DLT
| LOOP
| OpenBSD "loopback" | YP | |
2 | DLT
| LINUX_SLL
| Linux "cooked" encapsulation | YP | |
3 | NETPROTO
| IPv4 or IP
| Internet Protocol, version 4 | YP | RFC 791, 3168 |
3 | NETPROTO
| IPv6
| Internet Protocol, version 6 | YP | RFC 2460, 3168 |
3 | NETPROTO
| RAW_IP
| Internet Protocol (version determined from packet header) | YP | |
3 | NETPROTO
| ARP
| Internet Address Resolution Protocol (Ethernet and ATM) | YP | RFC 826, 1293, 1577, 2225 |
3 | NETPROTO
| REVARP
| Reverse ARP | P | |
3 | NETPROTO
| SLARP
| Cisco SLARP (in CHDLC) | ||
3 | NETPROTO
| CLNP_ESIS
| CLNP/ES-IS (in CHDLC) | ||
3 | NETPROTO
| IPX
| IPX | YP | |
3 | NETPROTO
| IPX_E
| IPX (ECONFIG E option) | YP | |
3 | NETPROTO
| APPLETALK
| AppleTalk | YP | |
3 | NETPROTO
| AARP
| AppleTalk Address Resolution Protocol | YP | |
3 | PROTO
| LCP
| PPP Link Control Protocol | RFC 1661 | |
4 | IPPROTO
| TCP
| Transport Control Protocol, over IP | Y | RFC 793, 1323, 2018, 3168 |
4 | IPPROTO
| UDP
| User Datagram Protocol, over IP | Y | RFC 768 |
4 | IPPROTO
| ICMP
| Internet Control Message Protocol, over IPv4 | Y | RFC 792, 1192, 4884, 4950 |
4 | IPPROTO
| ICMP6
| Internet Control Message Protocol, over IPv6 | Y | RFC 2463 |
4 | IPPROTO
| HOPOPTS 3
| IPv6 Hop-by-Hop Options | Y | RFC 2460 |
4 | IPPROTO
| ROUTING 3
| IPv6 Routing Header | Y | RFC 2460 |
4 | IPPROTO
| FRAGMENT 3
| IPv6 Fragment Header | Y | RFC 2460 |
4 | IPPROTO
| ESP 3
| IPv4/IPv6 Encap Security Payload | Y | RFC 2406 |
4 | IPPROTO
| AH 3
| IPv4/IPv6 Authentication Header | Y | RFC 2402 |
4 | IPPROTO
| DSTOPTS 3
| IPv6 Destination Options | Y | RFC 2460 |
4 | IPPROTO
| EGP
| Exterior Gateway Protocol | RFC 888 | |
4 | IPPROTO
| MTP
| Multicast Transport Protocol | ||
4 | IPPROTO
| ENCAP
| Encapsulation Header | RFC 1241 | |
4 | IPPROTO
| PIM
| Protocol Independent Multicast | ||
4 | IPPROTO
| SCTP
| Stream Control Transmission Protocol | ||
4 | IPPROTO
| GRE
| Generic Routing Encapsulation, version 0 | Y | RFC 2784 |
5 | PROTO
| SNMP
| Simple Network Management Protocol | Y | RFC 1157; af-ilmi-0065.000 |
5 | PROTO
| DNS
| Domain Name Service | Y | RFC 1035, 1876, 2136, 2671 |
proto
configuration command.
We expect to support more protocols in the future, depending on demand.