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
.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:
if:interface
" (The "if:" prefix is always required.)
first=0..65535,user
ifconfig(8)
. CoralReef
uses libpcap to read "if:
" sources.
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)
crl:/dev/dagN
" (prefix may be omitted)
dag
" driver on Linux
first=48..720,user
first=48
(proto
must also be specified)
cat /proc/dag
" will report the device is "Busy");
the card must be re-initialized before another
CoralReef process can read from it.
A sample inititalization script suitable for both use as an
inittab script and for manual re-initialization can be found
here.
(In versions of CoralReef prior to 3.5, the user had to specify
the physical mode and bandwidth, and CoralReef would configure
the card to match. In 3.5 and later, these parameters are not required,
but if they are given, CoralReef verifies that they match the card's
configuration.)
-
" 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
"
dagsnap
tracefile with 64 bit timestamps.
Since a dagsnap
file contains no record of what options
were used, 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
"
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, you could run
crl_trace
with the options once to convert the
dagsnap
file to a coral file, and use the coral 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
"
-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:
[first=]N
last
user
first
).
ctrl
idle
all
user,ctrl,idle
".
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 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.
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
c[ells]=N
b[locks]=N
d[uration]=seconds
i[nterval]=seconds
v[erbosity]=level
norm[alize]={0|1}
gz[ip][=level]
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 '-?'
).
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_RFC1483 2
| 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
| HOPOPTS 3
| IPv6 Hop-by-Hop Options | RFC 2460 | |
4 | IPPROTO
| ROUTING 3
| IPv6 Routing Header | RFC 2460 | |
4 | IPPROTO
| FRAGMENT 3
| IPv6 Fragment Header | RFC 2460 | |
4 | IPPROTO
| ESP 3
| IPv4/IPv6 Encap Security Payload | RFC 2406 | |
4 | IPPROTO
| AH 3
| IPv4/IPv6 Authentication Header | RFC 2402 | |
4 | IPPROTO
| DSTOPTS 3
| IPv6 Destination Options | RFC 2460 | |
5 | PROTO
| SNMP
| Simple Network Management Protocol | RFC 1157 |
proto
configuration command.
We expect to support more protocols in the future, depending on demand.