When the FMADIO device captures packets, they are stored in a stream within a highly specialized file system. These packet streams are not in the standard PCAP file format, and they cannot be “opened” or “piped” like a conventional Linux file; to provide similar functionality to coreutils cat, use the stream_cat utility.
The simplest possible usage of this tool is shown below; stream_dump is used to determine the name of the desired stream, and that name is given to stream_cat to redirect it to a Linux file.
fmadio@fmadio20v3-508:/mnt/store0/develop$ sudo stream_dump
Streams:
...omitted for this documentation
[0067] capture0_20250123_0000 351GB Chunk(Cnt: 1437988 Start:27777204 End:29215191 Comp:1.20) Inv:-nan Cap:-nan CacheI:-nan Cache:-nan Disk:-nan Drop:-nan Pkt:0
...omitted for this documentation
Capture Size : 4912 GB (0.4395%)
Physical Size : 11178 GB
Maximum Size : 48009 GB
Compress Ratio : 1.1301 %
Cache Cnt : 2 x 512 GB ( 1024 GB)
Store Cnt : 3 x 4001 GB ( 12002 GB)
ECC Cnt : 1 x 4001 GB
Next Cache : 1636104 : 3907090
Next Store : 9531818 : 11446335
Next Chunk : 45965562 : 183141360
Validate Enable: 0
Validate Offset: 0
Validate Size : 0 (0.00GB)
fmadio@fmadio20v3-508:/mnt/store0/develop$ sudo stream_cat capture0_20250123_0000 > /tmp/my_packets.pcapTip: FMADIO systems have special Bash auto-completion routines for stream_cat. If you write sudo stream_cat and then press the spacebar and then the tab key, a list of available streams will be given that you can choose from by filling in more characters from the remainder of the name of the desired stream and then pressing tab again.
For a “cookbook” of even more possible uses for stream_cat, run stream_cat --examples in your shell.
Parameters
If you need a quick refresher on each of these, you can always use stream_cat --help in your shell.
--bpf "<bpf filter>"
Apply a Berkeley Packet Filter (BPF) to prevent certain packets from being emitted.
--bpf-decap
If a BPF filter was set, run it after de-encapsulating outgoing packets rather than before.
--decap
Emit de-encapsulated packets instead of emitting them as-is. Kinds of encapsulation that can be handled include:
Arista 7130
Arista 7280
Cisco 3550
Ixia
Virtual Network Tag (VNTag)
VLAN (IEEE 802.1ad)
VLAN QinQ (EtherType 0×8100)
Note that while many different encapsulation “stacks” are covered, de-encapsulation may still not function as expected on extremely deeply-layered or exotic packets. In some cases you can combine stream_cat --decap with pcap_decap to handle e.g. VLAN tags underneath Generic Routing Encapsulation. If, even after trying pcap_decap, you nonetheless feel that your use case is not adequately serviced, please contact support@fmad.io.
--epoch-start <nanoseconds>
stream_cat will skip emitting packets with a timestamp before the given number of nanoseconds after the Unix epoch.
--epoch-stop <nanoseconds>
stream_cat will skip emitting packets with a timestamp after the given number of nanoseconds after the Unix epoch.
--follow (or -f)
Enables “follow mode”. This changes stream_cat’s behavior to read packets from the stream being built from an on-going capture, rather than from a stream stored from a past capture.
--follow-start
Does the same thing as --follow, but starts from the beginning of the current capture file instead of the end.
--follow-pre <number of packets>
Set follow mode to start a certain number of packets before the end of the stream currently being captured.
--footer-arista7130
Every packet emitted to normal PCAP (the default output format) gets an Arista 7130 footer appended.
--frame "<frame filter>"
Prevent certain packets being emitted with a frame filter. For more information about what this parameter expects for an argument, see the frame filter reference guide.
--gre <session ID>
stream_cat will skip emitting packets which do not match the given Generic routing encapsulation (GRE) session ID.
--info
This changes stream_cat’s behavior so that, instead of writing PCAP from a stored (or the current) stream, it instead prints information about the current on-going capture and then immediately exits. Example output:
fmadio@fmadio200v4-000:~$ sudo stream_cat --info
CaptureActive: 1
CaptureName: scheduler
CaptureIndex: 1066
CapturePackets: 100400962
CaptureBytes: 68003412009
CaptureDrop: 0--json
This changes stream_cat’s behavior so that, instead of writing PCAP from a stored (or the current) stream, it instead prints information about the current on-going capture and then immediately exits. Example output:
fmadio@fmadio200v4-812:/mnt/store0/develop$ sudo stream_cat --info --json | jq
JSON format output
{
"CaptureActive": 1,
"CaptureName": "deleteme",
"CaptureIndex": 1066,
"CapturePackets": 100400962,
"CaptureBytes": 68003412009,
"CaptureDrop": 0
}-n <integer>
Emit a maximum of <integer> packets before stopping.
--no-pcap-header
Do not emit a PCAP file header when starting output.
--only-fcs-error
Only output packets with bad frame check sequences.
--pktslice <bytes>
Slice packets before emitting them. This is useful if you, for example, only need their headers and not their payloads.
--ring <path>
Send packets to an FMADIO ring buffer instead of standard output. Note that this argument can be used multiple times to send to many rings at once.
--ring-filter-frame <path> "<frame filter>"
If using --ring, apply a frame filter to that specific ring.
--ring-filter-bpf <path> "<bpf filter>"
If using --ring, apply a Berkeley Packet Filter to that specific ring.
--time-start <HH:MM:SS>
This is like --epoch-start except the time can be given in 24-hour format relative to the local timezone.
--time-stop <HH:MM:SS>
This is like --epoch-stop except the time can be given in 24-hour format relative to the local timezone.
--tsmode-* <port>
Includes:
--tsmode-arista7280-mac48
--tsmode-arista7280-eth64
--tsmode-arista7150-insert
--tsmode-arista7150-overwrite
--tsmode-arista7130
--tsmode-cisco3550
--tsmode-cisco-erspan3
--tsmode-nic
Each changes the kind of encapsulation that stream_cat will attempt to strip from every packet.
Parameters Internal
The following parameters are reserved for internal use. Use with caution.
--chunked--cpu--decap-dump--disable-cycle-calibration--force-drop--index--io-priority--nop-truncate--print-period--prefetch-depth--realtime--ring-cpu--ring-eof--ring-reset--ring-timeout--ring-timeout-exit--shmring--shmring-no-flow-control--shmring-no-hb--sockfd--stride-offset--timeout-interval--timeout-packetcount--timeout-send--uid
Examples
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.pcapTime 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 -v --epoch-start 1622000000000000000 --epoch-stop 1622000000000001000 test_capture > sample_file.pcapPacket Filters
tream_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.pcapStream_cat with a UDP port 80 filter:
stream_cat -v --bpf "udp port 80" test_capture > sample_file.pcapStream_cat with a complex filter - select port 80 packets with tcp range selectors :
stream_cat -v --bpf "port 80 and tcp[((tcp[12:1] & 0xf0) >> 2):4]" test_capture > sample_file.pcapPipeing
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.
stream_cat -v -bpf "udp port 80" test_capture | gzip --fast > sample_file.pcap.gzLXC Ring
streamcat can write directly to an lxc ring buffer located in /opt/fmadio/queue/lxc_ring0
It can also write to multiple lxcring buffers from a single stream_cat instance by issuing the --ring command line multiple times.
LXC Ring - One Ring - No Filter
This example writes all captured data to a single LXC Ring with no BPF filter applied
$ sudo stream_cat --ring /opt/fmadio/queue/lxc_ring0 "" my_capture_20220325_000NOTE: the "" arguments are required. This indicates a NULL BPF filter
LXC Ring - One Ring - BPF Filter
The following example writes to a single LXC Ring with a simple "tcp" BPF filter
$ sudo stream_cat --ring /opt/fmadio/queue/lxc_ring0 "tcp" my_capture_20220325_000LXC Ring - 4 Ring - BPF Filter
Example below shows a single stream_cat instance writing to 4 separate LXC Ring rings each with a different BPF Filter
$ sudo stream_cat --ring /opt/fmadio/queue/lxc_ring0 "net 192.168.0.0/24"
--ring /opt/fmadio/queue/lxc_ring1 "net 192.168.1.0/24"
--ring /opt/fmadio/queue/lxc_ring2 "net 192.168.2.0/24"
--ring /opt/fmadio/queue/lxc_ring3 "net 192.168.3.0/24"
my_capture_20220325_000NOTE: above should be a single line