---
title: "stream_cat"
slug: "fmadio-utils-stream-cat"
updated: 2026-10-17T10:56:11Z
published: 2026-10-17T10:56:11Z
canonical: "docs.fmad.io/fmadio-utils-stream-cat"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fmad.io/llms.txt
> Use this file to discover all available pages before exploring further.

# stream_cat

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.

```plaintext
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.pcap
```

Tip: 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](https://www.ibm.com/docs/en/qsip/7.4?topic=queries-berkeley-packet-filters) (BPF) to prevent certain packets from being emitted.

### `--bpf-decap`

If a [BPF filter](/v1/docs/fmadio-utils-stream-cat#bpf-filter-expression) was set, run it after [de-encapsulating](/v1/docs/fmadio-utils-stream-cat#decap) 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
- [CAPWAP](https://en.wikipedia.org/wiki/Control_and_Provisioning_of_Wireless_Access_Points_protocol)
- Cisco 3550
- Ixia
- [MPLS](https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching)
- Virtual Network Tag (VNTag)
- [VLAN](https://en.wikipedia.org/wiki/VLAN) (IEEE 802.1ad)
- VLAN QinQ (EtherType 0×8100)
- [VXLAN](https://en.wikipedia.org/wiki/Virtual_Extensible_LAN)

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](/v1/docs/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](https://en.wikipedia.org/wiki/Unix_time).

### `--epoch-stop <nanoseconds>`

stream_cat will skip emitting packets with a timestamp after the given number of nanoseconds after the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time).

### `--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](/v1/docs/fmadio-utils-stream-cat#follow-or-f) 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](/v1/docs/frame-filters).

### `--gre <session ID>`

stream_cat will skip emitting packets which do not match the given [Generic routing encapsulation](https://en.wikipedia.org/wiki/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:

```plaintext
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:

```plaintext
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.

### `--cpu <cpu number>`

Pins the CPU of the main stream_cat thread, this is the thread that fetches data from the disk

### `--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](/v1/docs/frame-filters) to that specific ring.

### `--ring-filter-bpf <path> "<bpf filter>"`

If using `--ring`, apply a [Berkeley Packet Filter](https://www.ibm.com/docs/en/qsip/7.4?topic=queries-berkeley-packet-filters) to that specific ring.

### `--ring-cpu <path> <cpu number>`

Pins the stream_cat egress thread to the LXC Ring buffer to the specified CPU number.

NOTE: In LXC Ring mode stream_cat uses 1 thread per ring, in addition to the main data fetch thread.

### `--time-start <HH:MM:SS>`

This is like [--epoch-start](/v1/docs/fmadio-utils-stream-cat#epochstart-nanoseconds) 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](/v1/docs/fmadio-utils-stream-cat#epochstop-nanoseconds) 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:

```plaintext
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.

```plaintext
stream_cat -v --epoch-start 1622000000000000000 --epoch-stop 1622000000000001000 test_capture > sample_file.pcap
```

### Packet 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:

```plaintext
stream_cat -v --bpf "ip and udp" test_capture > sample_file.pcap
```

#### Stream_cat with a UDP port 80 filter:

```plaintext
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 :

```plaintext
stream_cat -v --bpf "port 80 and tcp[((tcp[12:1] & 0xf0) >> 2):4]" test_capture > sample_file.pcap
```

### Pipeing

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.

```plaintext
stream_cat -v -bpf "udp port 80" test_capture | gzip --fast > sample_file.pcap.gz
```

---

## LXC 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

```plaintext
$ sudo stream_cat --ring /opt/fmadio/queue/lxc_ring0 ""  my_capture_20220325_000
```

NOTE: 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

```plaintext
$ sudo stream_cat --ring /opt/fmadio/queue/lxc_ring0 "tcp"  my_capture_20220325_000
```

### LXC 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

```plaintext
$ 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_000
```

NOTE: above should be a single line