stream_cat is the core utility to extract data off the system. By default it outputs a standard nanosecond PCAP to stdout. This can be piped in multiple ways per the unix philosophy
$ sudo stream_cat --help
stream_cat -vf (stream name)
-v : verbose print of status
--follow : follow mode
--follow-start : follow mode but start at the begining of the file
--check-fcs : check for FCS errors
--force-hdd : force reading from HDD
--info : dump info on the current capture
--cpu <cpuid> : pin to a specific CPU
--io-priority <level> : sets IO priority (default 20)
-n N : follow mode start N packets from the end
--bpf "bpf expression" : add a BPF filter expression
--chunked : output chunks of packets
--decap : de-encapsulate packets
--pktslice <bytes> : slice packets before sending down the pipe
--time-start <HH:MM:SS> : time start in local timezone hour:min:sec
--time-stop <HH:MM:SS> : time stop in local timezone hour:min:sec
--epoch-start <epoch time> : time start in epoch nano seconds
--epoch-stop <epoch time> : time stop in epoch nano seconds
--no-pcap-header : remove pcap header from output stream
Example: 'sudo stream_cat -f -n 1000000 | tcpdump -r - -nn '
Example: 'sudo stream_cat --bpf "host 192.168.1.1" | tcpdump -r - -nn '
$
Reference
CLI argument reference
--cpu <cpu number>
Pins stream_cat to a specific CPU number.
--ring <ring path> <bpf filter> <cpu number>
Writes PCAP to the specified LXC <ring path> when the <bpf filter> matches.
Multiple rings can be specified
NOTE: if no BPF is used <bpf filter> needs to be ""
Above example uses stream_cat with an epoch and BPF filter to isolate the packet histogram deltas between packets. This is particularly useful for checking QoS SLAs
--delta-histo-bin <nanos>
Used with capinfos2 it specifes the width of each timebin (e.g. the histogram resolution). By default it uses 1nsec. Example usage below, this uses a 1e6 (1 millisecond) time bin with a 10msec offset.
As the number of timebins is limited, it may be nessecarry to offset the histogram to where the data is. The example below offsets it by 10msec with a time bin of 1msec.
Filters the specified capture using and end time specified argument epoch time value.
Value of 0 means filter is disabled
NOTE: typically --epoch-start and --epoch-stop are used together
Example: filter up to epoch time 1497015594000000000. This example uses capinfos2 to verify the last packet (Time Last) meets the specified filter value.
The following section shows how to use stream_cat on the command line in various different ways.
Where test_capture is used, replace with a stream capture name from your fmadio system.
Where sample_file.pcap is used, replace with your own pcap filename.
Whole file
To create a whole pcap of an entire fmadio system capture use the following:
stream_cat -v test_capture > sample_file.pcap
Time Selection
To choose a selection of time for a pcap on the fmadio system the following can be used. The following example selects a time period using epoch nano seconds. 1000 nanoseconds of capture time will be extracted - assuming the stream was captured during this epoch period.
Stream_cat can be executed with packet filtering commands. These are similar to the filter methods used by wireshark filtering. Example filters are also available in the fmadio user guide.
The examples here show some simple filter examples.
Stream_cat with a IP and UDP filter:
stream_cat -v --bpf "ip and udp" test_capture > sample_file.pcap
Stream_cat with a UDP port 80 filter:
stream_cat -v --bpf "udp port 80" test_capture > sample_file.pcap
Stream_cat with a complex filter - select port 80 packets with tcp range selectors :
Stream_cat is very useful for piping output to other programs to process the data. Examples are shown in the stream_cat --help. The example here shows stream_cat used with gzip to compress the output pcap into a smaller sized file.
