# read_pcap

Parses PCAP byte streams into packet events.

```tql
read_pcap [emit_file_headers=bool]
```

## Description

The `read_pcap` operator converts raw bytes representing a [PCAP](https://datatracker.ietf.org/doc/id/draft-gharris-opsawg-pcap-00.html) file into events.

PCAPNG

The current implementation does *not* support [PCAPNG](https://www.ietf.org/archive/id/draft-tuexen-opsawg-pcapng-05.html).

### `emit_file_headers = bool (optional)`

Emit a `pcap.file_header` event that represents the PCAP file header. If present, the parser injects this additional event before the subsequent stream of packets.

Emitting this extra event makes it possible to seed [`write_pcap`](https://preview.docs.tenzir.com/375/375/reference/operators/write_pcap.md) with a file header from the input. This allows you to preserve timestamp formatting (microseconds vs. nanoseconds) and byte order in packet headers.

When the parser processes a concatenated stream of PCAP files, `emit_file_headers=true` also re-emits every intermediate file header as a separate event.

Use this option when you want to reproduce the original trace layout.

## Schemas

The operator emits events with the following schemas.

### `pcap.file_header`

Contains the global header for one PCAP trace.

| Field           | Type     | Description                                 |
| :-------------- | :------- | :------------------------------------------ |
| `magic_number`  | `uint64` | The PCAP magic number.                      |
| `major_version` | `uint64` | The major PCAP format version.              |
| `minor_version` | `uint64` | The minor PCAP format version.              |
| `reserved1`     | `uint64` | Reserved header field.                      |
| `reserved2`     | `uint64` | Reserved header field.                      |
| `snaplen`       | `uint64` | The maximum captured packet size.           |
| `linktype`      | `uint64` | The link-layer type for subsequent packets. |

### `pcap.packet`

Contains one captured packet from the trace.

| Field                    | Type     | Description                            |
| :----------------------- | :------- | :------------------------------------- |
| `timestamp`              | `time`   | The time when the packet was captured. |
| `linktype`               | `uint64` | The link-layer type of the packet.     |
| `original_packet_length` | `uint64` | The length of the original packet.     |
| `captured_packet_length` | `uint64` | The length of the captured packet.     |
| `data`                   | `blob`   | The captured packet payload.           |

## Examples

### Read packets from a PCAP file

```tql
from_file "/tmp/trace.pcap" {
  read_pcap
}
```

### Capture packets from `en1` and preserve file headers

```tql
from_nic "en1" {
  read_pcap emit_file_headers=true
}
```

## See Also

* [`from_nic`](https://preview.docs.tenzir.com/375/375/reference/operators/from_nic.md)
* [`write_pcap`](https://preview.docs.tenzir.com/375/375/reference/operators/write_pcap.md)
* [`decapsulate`](https://preview.docs.tenzir.com/375/375/reference/functions/decapsulate.md)